# Adopt planning, parallel sessions and headless workflows

Read the [complete reference](https://hamedtaheri.com/playbook/v0.2.0/reference/workflows.md) before using these patterns. The scripts described there belong to the author's implementation and are not shipped in this kit; the person can request a copy from the author (see [start.md](https://hamedtaheri.com/playbook/v0.2.0/agent/start.md)). Do not invent an installed command or silently launch a paid run.

## Assess and prepare

1. Inspect actual project instructions, accepted goal, current source, permissions, available tools and provider login. Confirm whether this is planning, setup or execution.
2. Use design/planning skills where available to resolve the specification before implementation. Produce a spec with behavior, exact interfaces, non-goals, invariants and acceptance; then an [implementation plan](https://hamedtaheri.com/playbook/v0.2.0/templates/implementation-plan.md) with files, dependencies, verification and review points.
3. Select coherent deliverables. Isolate checkouts and test resources. Order shared-schema and interface changes; do not equate several tiny commits with several shipped features.

## Choose execution

- Interactive lanes: suitable for discovery and changing constraints. Assign one task and owner per session, explicit worktree, revision and stop rules. Send [focused messages](https://hamedtaheri.com/playbook/v0.2.0/templates/session-message.md) only when authorized, then retain accepted state in tasks/decisions/handoffs.
- Scripted lanes: suitable for ready bounded tasks. Inspect installed runner source, CLI version, configuration and the command's actual side effects. Produce a dry-run plan first. Encode approved constraints in the worker card/brief before reducing context discovery.

## Run and review

Verify the spec's current-content gate, environment and ownership. Use a versioned claim if the backend offers one (Personize supports `expectedVersion`); the reference queue's write/wait/re-read, and the plan runner's opt-in claim with read-back, do not prove exclusivity across coordinators, so run one coordinator at a time with them. Budget preparation, worker, coordinator, internal/external reviews and repairs. Cap checks between stages and timeouts are not live spending guarantees.

Record provider, harness, auth mode, model, attempt, revision, token counters and pricing source/date. Keep actual charges, API-equivalent valuation and subscription quota separate. Codex can resume at the product level, but this ephemeral runner adapter does not implement recovery resume.

Validate acceptance with real commands and relevant environments. Review the exact head revision. Do not interpret `MERGE`, `ready_for_gate` or a clean external review as release authority. Escalate missing specs, environments, unknown spend and unresolved decisions. Use bounded fixes; repeated findings in the same area may need a new design.

## Drive a queue without doing the work

When a session drives the runner, it runs commands and reads short output; workers, reviewers and drafters are separate headless processes with caps. The driver does not patch the runner during a run: it writes a note and ends. It never routes around a refusal, never merges a PR directly (landing goes through the authorized landing script only) and never files board tasks; a proposed split stays a proposal for the person. One dollar cap covers preparation, workers, reviews, fix rounds and the coordinator; check the remainder before each wave.

## Park work that needs the person

Work that needs a human action other than a PR review moves to a waiting state and records three things: the kind of need (decision, approval, verify, wait or proposal), a self-contained ask (the exact question, or the exact command with preflight, verification and rollback) and what resumes once it is answered. Runners claim only backlog work, so parked tasks are never picked up again by a worker; a human session works through them. Prod-touching briefs must declare their human gate, or explicitly declare none; without it the pipeline stops before the worker. Agents never turn their own suggestions into tasks.

## Audits and UI checks

Run a security audit as a capped job: pinned, read-only review skills in headless sessions, nothing installed in the product repository, a dry run that shows the job list and worst-case cost before the person approves a ceiling, a triage table, and a code check of each confirmed row before it becomes a task. Rows that need cloud or configuration access become verification tasks for a person. Do not publish findings.

Test the UI in a real browser against a test account. Credentials stay outside every repository and are never printed. Touch only items the session created. Fix a bug in the change under test with a failing test first; report other bugs; turn feature ideas into proposals.

## Close or hand off

Retain revision, acceptance, failed and passed checks, reports, cost completeness, owner, human question and exact resume step. Report a failed board write as NOT saved. Keep raw transcripts, keys and private identifiers out of public contributions. Offer only an explicitly requested, redacted learning report through the contribution process.