Orchestration and Subagents

Status: live (v5). The orchestrator-and-leaf topology is in place across every stage: intake is a read-only subagent, each stage's eval is dispatched to a fresh evaluator that did not author the artifact, and inputs follow resolve-mark-proceed. The canonical shape lives at .claude/shared/pipeline-pattern.md. Model tiering to Haiku for the cheapest checks is still (planned).

harness-kit's original pipeline is carried by two monolithic agents: product-manager runs prd then prp inline, and staff-software-engineer runs plan → dev → test → pr inline. Inside each agent, the sensors and evals run in the same context as the author. This page explains why v5 breaks that into an orchestrator plus small, single-purpose subagents, and, just as importantly, where it deliberately does not.

Why subagents

A subagent is a fresh, isolated context invoked through the Task tool. Splitting work into subagents pays off in exactly three situations, and v5 uses each of them:

Context isolation. A stage that reads hundreds of files (intake, dev) should not carry that bulk into the stages after it. Each subagent boots clean and returns only a distilled result.
Parallelism. Genuinely independent work runs concurrently: a panel of reviewers, or dev fanning out over independent modules.
Adversarial separation. The agent that writes an artifact must not be the agent that grades it. A fresh critic with no stake in the text gives an honest score.

The third is the strongest reason. Today the same agent writes a PRD and then evaluates it, which is grade-your-own-homework: the score is inflated because the grader is attached to the work. A separate evaluator, booted fresh and handed only the artifact, has nothing to defend.

This is not a new idea in harness-kit. The SDD loop already runs its spec-satisfied eval in a fresh session with no worker context (see Pipeline and Stages). v5 generalizes that one instance into the rule for every gate.

The over-decomposition trap

Every subagent hop has a cost: a fresh context boot, re-reading files it does not inherit (subagents share no memory), added latency, and added tokens. So the goal is not one subagent per step. Split only when a hop buys one of the three payoffs above. Otherwise, keep the work inline or, better, in a deterministic script.

The dividing line is judgment versus determinism:

A check that is a structural rule, "does the PRD contain the required sections?", is a sensor script. It does not need a model, and a model would only make it slower and less reliable.
A check that requires reading and weighing, "is this hypothesis actually testable?", is an eval subagent.

harness-kit already keeps its deterministic sensors as scripts. v5 preserves that. Decomposition adds subagents for judgment and isolation, not for work that code already does better.

Three concerns, separated

The core move is to stop tangling three different responsibilities inside one agent:

Concern	Who owns it in v5	Rule
Coordination — sequencing, state, markers, retries, gates	one orchestrator (the main session)	Never writes an artifact. Only dispatches and commits state.
Generation — write the PRD, PRP, plan, code	author subagents	Stateless. Explicit inputs, structured output.
Verification — sensor + eval	verifier subagents, separate from the author	The grader never wrote the thing it grades.

The monolithic agents mixed all three. Separating them is what makes the gates trustworthy and the contexts clean.

The topology

/pipeline:run "<one-line idea>"
  │  orchestrator = main session: owns .pipeline-state.json, markers, gates
  │
  ├─ intake        subagent   harvest repo + context-library → intake.md
  │      ↓ orchestrator reads unknowns[], decides the PRD gate
  ├─ prd-author    subagent   write PRD
  ├─ prd-sensor    script     structural pass/fail (no model)
  ├─ prd-eval      subagent   adversarial score, fresh context
  │      ↓ score ≥ 8.0 → orchestrator writes approval marker → next stage
  ├─ prp-author / prp-eval
  ├─ planner
  ├─ dev × N       subagents  fan out only over independent modules
  ├─ tester
  ├─ reviewer × 3  subagents  parallel, distinct lenses (correctness · security · repro)
  └─ pr-author

The orchestrator is a coordinator, not a worker. It spawns each leaf, reads the leaf's structured return, and commits the resulting state transition. Leaves never talk to each other; all information flows through the orchestrator and the artifacts on disk.

The adversarial split

The rule that makes gates honest:

The subagent that authors an artifact is never the subagent that evaluates it.

The evaluator is booted with no memory of how the artifact was written. It receives only the artifact and the rubric, and it is prompted to find what is wrong, not to defend what is there. For high-stakes gates a panel replaces a single judge: three evaluators with distinct lenses run in parallel and a majority decides. Diversity of lens catches failure modes that a single reviewer, or three identical reviewers, would miss.

Model tiering

Separating concerns lets each subagent run on the right-sized model:

Work	Model	Why
Deterministic sensors	(none — script)	Structural rules do not need inference.
Mechanical / cheap judgment	Haiku (planned)	Fast, cheap, good enough for narrow checks.
Authoring and adversarial eval	Opus	The parts that need real reasoning.

A monolithic agent has to run everything at one tier. Decomposition lets the cheap work be cheap and reserves the strong model for authoring and judgment.

Claude Code constraints shape the design

Subagents in Claude Code are stateless leaves: they cannot mutate shared state, they inherit no memory from the caller, and nesting is limited (a subagent cannot freely spawn its own subagents). This is not a limitation to fight; it dictates a clean design:

The orchestrator owns all state. .claude/.pipeline-state.json and the marker files are written by the orchestrator, through the existing pipeline.py and marker.sh, never by a leaf.
Leaves return, they do not commit. A subagent fills an artifact and reports a structured result. The orchestrator reads that result and performs the state transition.
The existing hook, marker, and token machinery is untouched. Subagents slot in underneath it: a leaf writes the artifact, the orchestrator flips state, and the same post-write hooks fire as before.

Nothing that works today is thrown away. Subagents enter as leaves under the coordination layer that already exists.

Contracts

Reliable orchestration needs explicit contracts. Each subagent is given:

Explicit inputs — file paths, not "the context". prd-author is handed the path to intake.md and the guide paths, not a vague instruction to "use what you know".
Structured output — a defined shape the orchestrator can parse and branch on. For example, intake returns { squad, problem, repos[], customers[], unknowns[] }, and the orchestrator reads unknowns[] to decide whether the PRD gate needs the human.

Without contracts, orchestration degrades into guesswork about what a leaf produced. With them, the control flow is deterministic even though the leaves are inferential.

How it rolled out: a vertical slice first

v5 did not rebuild both monoliths at once. That would be a large, hard-to-debug change. The rollout proved a single vertical slice — the prd stage — through the new pattern end to end first:

intake (subagent) → prd-author → prd-sensor (script) → prd-eval (subagent, fresh context)

Once that slice worked against a real repository, it became the template, captured as .claude/shared/pipeline-pattern.md. Every other stage (prp, plan, dev, test, pr, and the system-design stages) was then a replication of that validated pattern rather than a simultaneous experiment: each reads its inputs via resolve-mark-proceed and dispatches its eval to a fresh evaluator. New stages follow the same file.