CODING PLANNER

Documentation · AR Labs

Reference

The pipeline map

Every step and every file in the coding planner pipeline, one region at a time.

The map

The pipeline has six regions, the same six as the overview on the harness page. Select a region on the map, or a section in the list under it, to go to that region's detailed diagram. In each detailed diagram, a dotted box stands for a neighbouring region and links to its section.

An overview map of the coding planner pipeline in six regions, with no per-step detail. On the left, the entry skills (grill-me and the coding-planner router) choose between two doors: a campaign enters through the campaign door, the init verb, and a lone task enters through the task door, the init-task verb. The campaign door leads to the container route, which plans and splits the work (design, PRP, child beads) and later integrates it once every child has closed. Each child, and every lone task, walks the leaf route: build the leaf (spec, code, review), pass the Gate B floor that checks the review verdicts, deliver to the target branch (never to main), and pass the Gate C floor that checks the work landed on the target; a closed leaf returns control to the container's integrate step. Below the routes, the scripts region: the runner hosts each pass of the driver, the driver dispatches the executor, and the executor runs each step in its own worktree. The driver claims work and records exits through the transition script, the steps call the transition script's verbs too, and the transition script is the only writer of pipeline state into Beads, the state store. To the left of the scripts, the guard hooks check every tool call the dispatched step session makes. Along the foot, the artifacts the steps write and the floors read: DESIGN.md and the PRP, the spec, the review artifact, and the task branch with its pull request. A legend keys three arrow styles (control flow, dispatch, writes) and the circle used for a floor, an evidence check that refuses or escalates.
Fig R.0 The map: each region links to its section below.
  1. 01 Entry: the skills and the two doors
  2. 02 The container route
  3. 03 The leaf route
  4. 04 The scripts
  5. 05 The guard hooks
  6. 06 The artifacts

01 Entry: the skills and the two doors

Work enters the pipeline through one of two doors, and the entry skills decide which. grill-me interviews the person and writes a brief, and the coding-planner router decides whether the work is a lone task or a campaign. The diagram shows the three skills with their files, the campaign door and the task door with the transition-script verbs that open them, and where each door leads: a campaign enters the container route at create-prp, and a lone task enters the leaf route at generate-spec.

Region 1 of the coding planner pipeline map: the entry skills and the two doors. Inside the .claude/skills/ directory, three skills are stacked. grill-me (.claude/skills/grill-me/SKILL.md) interviews the person and writes a brief; its handoff ends in continue, park or abandon. It hands off to coding-planner, the router (.claude/skills/coding-planner/SKILL.md), which decides whether the work is a lone task or a campaign; both shapes carry a bead. The router offers doc-review (.claude/skills/doc-review/SKILL.md), an optional, advisory audit of DESIGN.md, the PRP or a spec. From the router a junction splits two ways. A campaign goes to the campaign door, pipeline-transition.sh init plus set-mode --from-staged, which a fresh session runs; grill-me also writes the brief that this door reads. A lone task goes to the task door, pipeline-transition.sh init-task, with an adopt stamp for work that predates the doors. The campaign door enters the container route at create-prp, its entry stage, and the task door enters the leaf route at generate-spec. Both routes are drawn as dotted boxes that link to their own sections.
Fig R.1 Entry: three skills, two doors, and where each door leads.

Back to the map

02 The container route

A container is a bead that is split into child beads instead of being built directly: the campaign at the root of a tree, or any bead whose spec turns out to be compound. The diagram follows its route from top to bottom: design, the PRP, the fan-out into children, the delegate step that waits for every child to close, and integrate. Between two steps, a diamond is a human gate and a circle is a floor, labelled with the check it runs and the transition verb that crosses it.

Region 2 of the coding planner pipeline map: the container route, read top to bottom. generate-design (.claude/commands/coding-planner/generate-design.md) writes DESIGN.md, ADRs and C4 diagrams and also runs as refine-design; its human gate is not enforced and records no verb. create-prp (.claude/commands/coding-planner/create-prp.md) is the entry stage and writes the PRP with Gherkin criteria; a human gate and the file_exists floor are crossed with propose then complete. A loop from create-prp back to generate-design is refine-design, a post-PRP revisit of the same file crossed with propose then complete, which only the deep setting relaxes. to-issues lives in .claude/skills/to-issues/SKILL.md and fans the work out into child beads plus an ISSUE-BREAKDOWN doc; a human gate and the fanout_birth_facts floor are crossed with birth-facts, propose and complete. Each child bead walks its own route: arrows go to the leaf route, and a compound child repeats the container route; a compound spec comes back to to-issues with complete --next to-issues, and a task-door bead needs --ruling or --authority to do that. The delegate step has no command file: its children_terminal floor completes when every child is closed, and closed leaves report back to it. integrate (.claude/commands/coding-planner/integrate.md) is terminal: a fresh sub-agent reconciles the work, and its human gate and the integrated_acceptance and file_exists floors are crossed with propose then integrate, its own verb. The campaign door and the leaf route are drawn as dotted boxes that link to their sections.
Fig R.2 The container route: five steps, the gates and floors between them, and the arrows to and from the leaf route.

Back to the map

03 The leaf route

A leaf is a bead where code is written. The diagram follows its route from spec to implementation, review and delivery, with its two floors: Gate B, which reads the review artifact, and Gate C, which checks that the work landed on the target branch. Beside the route are the files that hang off it: the Codex spec author, the one-round remediation and the review artifact. Below it are the other command files in the same directory: the cockpit, the contract every dispatched agent reads first, and three retired commands.

Region 3 of the coding planner pipeline map: the leaf route, read top to bottom, with the files that hang off it. A lone task enters from the task door and each child bead enters from the container route. generate-spec (.claude/commands/coding-planner/generate-spec.md) writes build/specs/<bead>.md and classifies the bead as leaf or compound; a human gate and the file_exists and spec_frontmatter floors are crossed with propose then complete, and a compound bead goes back to to-issues with --next to-issues. When the spec author is Codex, generate-spec dispatches generate-spec-codex (generate-spec-codex.md, the spec-author verb), which runs spec/vox-spec.sh and records the proposal. implement (implement.md) does TDD on the task/<bead> branch, keeps the walkthrough, and pushes a pull request; its human gate has no floor, a declared gap, and is crossed with propose then complete. review (review.md) is Gate B: an independent Codex review on four axes, at most two rounds. It runs review/vox-review.sh <root> --base --bead, which writes the review artifact <project>/build/reviews/<bead>-<ts>.md with four verdicts and the sha in YAML frontmatter. When a fix is owed, review dispatches remediate (remediate.md, the fix_command, one round), which fixes CRITICAL findings, commits and stops; round 2 follows, then a person. The Gate B floor review_verdicts, with no human gate, reads the latest build/reviews/<bead>-*.md and needs reviewed_sha equal to HEAD before complete. deliver (deliver.md) is Gate C: it lands on origin/<target> and never merges to main; the landed_on_target floor, verb deliver, closes the leaf, and the closed leaf reports back to the container route's delegate step. Also in this directory: drive.md, the cockpit, which hosts one pass of pipeline-driver.sh pass --root <bead>, renders, asks the human and re-invokes; afk-contract.md, which every dispatched agent reads first; and three retired command files, detail-planner.md, quick-context.md and spec-zoom.md, kept for reference. The task door, the container route and the scripts are drawn as dotted boxes that link to their sections.
Fig R.3 The leaf route: four steps with Gate B and Gate C, the files that hang off them, and the rest of the command directory.

Back to the map

04 The scripts

The scripts are the harness that runs the routes without a person driving each step. The diagram shows how a pass starts (the headless runner or the cockpit hosts the driver), how the driver dispatches one step through the executor into a headless session in a per-bead worktree, and how every change to pipeline state goes through the transition script into Beads. The Codex harnesses for review and spec drafting, and the test suite, sit at the bottom.

Region 4 of the coding planner pipeline map: the scripts in .claude/scripts/ and what they start. pipeline-run.sh is the headless host: it loops while work is ready, with a pass cap of 16, and hosts pipeline-driver.sh. The drive cockpit also hosts a pass, with pipeline-driver.sh pass --root <bead>. pipeline-driver.sh runs read, decide (a pure function), act, and a typed exit. It acts through pipeline-transition.sh with claim, complete, record-exit and record-run, and reads step, kind and autonomy through it. pipeline-transition.sh is the single writer of pipeline.* state, with the verbs and the floors; the command files call its verbs propose, complete, integrate, deliver, set-step and birth-facts. It writes to and reads from Beads, the single state store (bd, pipeline.*), holding stage, artifact, lease, exit, reviewed, delivered and driver_last; it has one writer, pipeline-transition.sh, and the bd guard denies direct writes. The driver dispatches pipeline-executor.sh across the dispatch seam with <bead> <step> <cmd> <resume>. The executor handles one bead, one step and one attempt, with a surface fingerprint. It resolves the bead to its primary checkout with project-resolver.ts (from ~/.vox/config.json), runs git worktree add to make a per-bead worktree at <project_roots.worktrees>/<project-id>/<bead-id> on task/<bead> from origin/<target>, reused by every step, and spawns a headless Claude session (claude -p, VOX_AFK=1, --setting-sources user, --settings .claude/settings.json, --add-dir $VOX_ROOT) whose working directory is that worktree. The session returns a result file, exit=n, to the executor; it reads afk-contract.md first, then Read(<command file>), and executes it for the bead; and the PreToolUse guard hooks bite on its tool calls. The Codex harnesses: review.md runs review/vox-review.sh <root> --base --bead, the Codex reviewer, which writes the review artifact and a VOX_REVIEW_RESULT line; review/vox-review-blocked.sh turns a result other than ok into a BLOCK note and an exit=n result file; generate-spec-codex runs spec/vox-spec.sh, where Codex drafts the spec and prints a VOX_SPEC_RESULT line; and tests/run.sh is the suite run before Gate B, with --record <bead>. The cockpit, the command files, the guard hooks, the review command, the review artifact and generate-spec-codex are drawn as dotted boxes that link to their sections.
Fig R.4 The scripts: the driver and its hosts, the executor and what it starts, the single writer and Beads, and the Codex harnesses.

Back to the map

05 The guard hooks

The guard hooks are checks that run before every tool call a dispatched session makes, so a step cannot quietly change what enforces it. The diagram shows the three hooks with the tool calls each one watches, and settings.json, which registers them and from which the session loads them.

Region 5 of the coding planner pipeline map: the guard hooks and their registration. In .claude/hooks/ there are three PreToolUse hooks. guard-enforcement-surface.ts watches Edit, Write, MultiEdit, NotebookEdit and Bash calls for edits to the enforcement surface. bd-pipeline-guard.ts watches Bash calls to bd and to the transition script; it is the bd guard that denies direct writes to pipeline state. guard-worktree-edits.ts watches Edit, Write and MultiEdit calls that would touch the primary checkout. The three join into one arrow: the PreToolUse hooks bite on every tool call of the dispatched session, which is drawn as a dotted box linking to the scripts section. Below, in .claude/, settings.json registers each hook and its matcher, and the session loads the hooks from it.
Fig R.5 The guard hooks: three PreToolUse checks on the dispatched session, registered in settings.json.

Back to the map

06 The artifacts

The artifacts are the files and records the steps leave behind, and they are what the floors check. The diagram has one row per artifact: the step that writes it on the left, the artifact and its path in the middle, and the gate or floor that checks it on the right.

Region 6 of the coding planner pipeline map: the artifacts, one row each, with the step that writes it on the left and the check on the right. generate-design writes the design record, DESIGN.md with ADRs and C4 diagrams; its human gate is not enforced and records no verb. create-prp writes the PRP with Gherkin criteria, a *-prp.md file; the file_exists floor checks it, crossed with propose then complete. to-issues writes the child beads and an ISSUE-BREAKDOWN doc; the fanout_birth_facts floor checks them, with birth-facts, propose and complete. generate-spec writes build/specs/<bead>.md, which classifies the bead as leaf or compound; the file_exists and spec_frontmatter floors check it. implement writes the task/<bead> branch, the walkthrough and a pull request; there is no floor, a declared gap, and the human gate is crossed with propose then complete. review/vox-review.sh writes the review artifact <project>/build/reviews/<bead>-<ts>.md with four verdicts and the sha in YAML frontmatter; the Gate B floor review_verdicts reads the latest one and needs reviewed_sha equal to HEAD. deliver lands the work on origin/<target>, never on main; the Gate C floor landed_on_target, verb deliver, checks the landing and closes the leaf. Each writer is a dotted box that links to its section.
Fig R.6 The artifacts: what each step writes, and the gate or floor that checks it.

Back to the map

The whole map in one image, zoomable

The original single chart, with every region at once. It loads fitted to the width of the page; zoom in on the part you want, or open it on its own.

A flow chart of the whole coding planner pipeline in six labelled regions. Top: the entry skills grill-me, coding-planner (the router) and doc-review feed two doors on the left, the campaign door (pipeline-transition.sh init) and the task door (init-task). Middle, the command files in .claude/commands/coding-planner: the container route runs generate-design, create-prp, to-issues, a delegate floor (children_terminal) and integrate; the leaf route runs generate-spec, implement, review with its Gate B floor review_verdicts, and deliver with its Gate C floor landed_on_target. Between steps, diamonds mark human gates and circles mark deterministic floors, each labelled with the transition verb that crosses it: propose, complete, integrate or deliver. Below the routes hang generate-spec-codex.md, drive.md (the cockpit), remediate.md (the one fix round), the review artifact in build/reviews, afk-contract.md, and three greyed retired commands. Bottom left, the scripts in .claude/scripts: pipeline-run.sh hosts pipeline-driver.sh, the driver dispatches through pipeline-executor.sh, the executor resolves the bead with project-resolver.ts, cuts a per-bead git worktree and starts a headless Claude session there, and every pipeline state write goes through pipeline-transition.sh into Beads, the single state store drawn as a database. Bottom right, the three guard hooks in .claude/hooks and .claude/settings.json, which bite on the dispatched session as PreToolUse hooks. A legend keys the four arrow styles: control flow, dispatch, reads and writes. A small annotation describes the executor's per-bead worktree placement.