Coding Planner: a spec-driven workflow for Claude Code

Coding Planner is the set of Claude Code skills (packaged instructions, with any scripts, that an agent loads only when a task needs them), commands, rules and scripts that AR Labs uses to direct coding agents, AI agents that write code. It is the tooling for our coding pipeline, the route every code change takes: spec, test-first build, second-model review, a person's merge. Its starting idea is to plan before writing code, and match the depth of planning to the size of the task. It began as a routing skill that sorted tasks into three tiers of planning, and an early version of that is public on GitHub. The internal version has since grown into most of the harness our coding agents run in (the harness is everything around the model that shapes what an agent does: agent program, instructions, skills, hooks, tools and checks), and it carries work from a rough idea to reviewed code on a branch. This page is the project overview. The method itself is described step by step in the coding pipeline, and the routing skill at its entrance on the Coding Planner skill page.

The public release: three tiers of planning

The version on GitHub is a context-engineering framework for Claude Code, Anthropic's command-line coding agent. Context engineering means choosing what goes into a model's context window at each step, so that it works from the right facts. The framework assesses each coding task with a decision matrix (how many files it touches, whether a clear pattern already exists in the codebase, and whether it changes the architecture) and routes it to one of three planning depths.

• Tier 1, simple. A light scan for the existing pattern, and a short scratchpad of steps.
• Tier 2, medium. Discovery and comparison of two or three patterns, with notes on how the change integrates.
• Tier 3, complex. Deep research with parallel sub-agents across the codebase and external documentation, producing a full PRP. A PRP (product requirement prompt) is a plan agents build from, in a format adapted from Rasmus Widing's: a requirements document's goal and justification plus the context, approach and validation steps the agent needs.

Every tier ends at the same place: the plan is shown to a person, and nothing is implemented until they approve it. The release installs with one script.

The current version: from a router to enforcement in code

Daily use of the three-tier router exposed its limit. The ordering of the work lived in prompt text, and a prompt is a request: an agent weighs it against everything else in its context. Nothing recorded which stage a piece of work had reached, so an agent had to infer it from how the documents looked, and that inference can be wrong. A detailed task sitting under a design brief looks as though planning has already happened when it has not. A skill runs inside the agent's loop, so it cannot refuse to let the agent move on.

The redesign moved enforcement out of instructions and into code. The internal version now has these parts:

• A durable record of progress. Each piece of work is an issue, called a bead, in Beads, Steve Yegge's open-source issue tracker for coding agents. The step a piece of work has reached is recorded on its issue, so it is read as a fact, never guessed from how files look.
• A manifest. One data file declares the steps for each kind of work and what each step requires. Changing the process means editing data, not logic.
• A transition script. Every move from one step to the next goes through one script, which refuses a move the evidence does not support.
• Floors and gates. A floor is a machine check, such as "the reviewed commit is on the target branch". A gate is a point work cannot pass until a condition is met: an approval, a check, or answers collected. A floor never passes on anyone's say-so; if it cannot prove something, it refuses or escalates.
• A stateless driver. A script that reads the whole tree of work, does one thing per piece and exits. It can be hosted in an interactive session, where a person answers questions at gates, or run unattended.
• Commands for each step. Writing a spec, implementing test-first, independent review by a different model, and delivery. The PRP command from the public release survives inside this structure.

flowchart LR
  P["Person"] --> SK["Router skill"]
  SK --> CMD["Step commands"]
  CMD --> TS["Transition script"]
  TS --> MF["Manifest of steps"]
  TS --> BD["Beads issue tracker"]
  DR["Driver"] --> BD
  DR --> CMD
  TS --> FL["Floors: git, GitHub, files"]

The three tiers have since been retired. Work now enters in one of two shapes: a lone task, tracked as a single issue, or a campaign, work planned in one PRP and split into a tree of issues. Both walk the same route of spec, implementation, review and delivery.

Each step on that route has to prove its result before work moves on. The spec opens with a block the scripts read: the issue it belongs to, the commit it was written against and the files it expects to touch, which the driver uses to keep two pieces of work out of each other's files. The code is written in a git worktree of its own, on a branch cut from the target, never in the checkout people look at. Review runs in a different command-line tool under a different model family, and its verdict counts only for the exact commit it read; a failed review gets at most one fix round, then waits for a person. Delivery is proved, not declared: the reviewed commit, or the merge of a pull request containing it, must be on the target branch before the issue closes. A campaign then checks that every scenario its plan promised has a test carrying that scenario's name, and that the whole suite passes on the assembled work. How much of this runs without a person is set per campaign by an autonomy level; no level ever skips a machine check.

What exists today

The current version runs our own software development, including our voice agents, websites and Coding Planner itself, and it is developed continuously. Its full documentation, a plain-English system reference and a set of guides, is published on this site (see below). Some parts are not built: there is no approval surface yet that can tell a person from an agent, no built checkpoint for merging a finished campaign branch to main, and no automated check that the enforcement hooks (scripts run automatically around an agent's action that can block it) are actually registered, as opposed to present on disk.

The public GitHub repository holds the earlier three-tier release. The current version is not packaged for outside use. It depends on several groups of files that must travel together (the skill, the commands, the rules they cite and the scripts they call), and a copy missing any one of them would let through work the pipeline is designed to block.

Documentation

The full documentation describes the system as we run it today, not the earlier public release.

• The skill: how a request is routed as a lone task or a campaign, and what each command produces.
• The harness: recorded state, checks, approvals, the driver and its hosts, with an overview map.
• Status and next steps: what is built and what remains.
• The system reference: the authoritative description in seven parts, from the concepts to what is not built and every configuration setting.
• The pipeline map: every step and every file, region by region.
• The entry boundary: how a clarification interview hands work to a fresh planning session.
• The agent reference: one screen of routes, floors, verbs and metadata for an agent operating the pipeline.
• The two incidents: the planning failures that started the rebuild, as a blameless record.

Decisions

• Guards fail open, gates fail closed. A guard that blocks a dangerous command must never lock up a session because of its own fault. A gate that decides whether work may advance must never advance when in doubt.
• Refuse is not escalate. "Not done yet" and "I cannot answer this" are reported differently, because one means fix the work and the other means fix the harness.
• A process failure is a harness defect. If a property of the harness would have made a failure impossible, the failure is treated as a defect in the harness, whichever agent made the mistake.
• Keep the slash commands. The redesign wired a deterministic core underneath the existing commands rather than rewriting them.

The approach draws openly on others' work: Matt Pocock's published workflow for AI coding (vertical slices, the grilling interview, review in a fresh context) and Steve Yegge's Beads.