Orchestration and Subagents

The pipeline runs as one orchestrator plus small subagents. intake is a read-only subagent, each stage's eval goes to a judge that did not write the artifact, and inputs follow resolve, mark, proceed. The canonical shape is .claude/shared/pipeline-pattern.md. Model tiering to Haiku is planned; today every agent runs on Opus.

Why subagents

A subagent is a fresh, isolated context started through the Task tool. A split pays off in three cases. Context isolation keeps a stage that reads hundreds of files, like intake, from carrying that bulk forward. Parallelism runs independent work at once. Adversarial separation keeps the author from grading its own work.

The third matters most. An author grading its own PRD inflates the score. A fresh evaluator that receives only the artifact and the rubric has nothing to defend. The SDD loop's spec-satisfied eval already ran in a fresh session; v5 made that the rule for every gate.

The over-decomposition trap

Every hop costs a context boot, re-reading files (subagents share no memory), latency, and tokens. Split only when a hop buys one of the three payoffs. A structural rule ("does the PRD have the required sections") is a sensor script with no model. A judgment ("is this hypothesis testable") is an eval.

Three concerns

Concern	Owner	Rule
Coordination: sequencing, state, markers, retries, gates	the orchestrator (main session)	Never writes an artifact
Generation: PRD, PRP, plan, code	the stage author	Explicit inputs, structured output
Verification: sensors and eval	sensor runner and a separate judge	The grader never wrote what it grades

The topology

flowchart TD
    O[orchestrator: owns .pipeline-state.json, markers, gates] --> I[intake subagent: writes intake.md]
    I --> O
    O --> A[stage author: prd, prp, plan, dev, test, pr]
    A --> S[sensor runner: pass or fail, no model]
    S --> E[judge: local Claude or jev, fresh context]
    E --> V[eval-score.py verifies the total]
    V -->|>= 8.0| O
    V -->|below| A

Leaves never talk to each other. Information flows through the orchestrator and the artifacts on disk.

The judge

The evaluator starts with no memory of how the artifact was written and gets only the artifact and the rubric. The project picks it with /hk:eval jev | local, stored in .claude/hk-config.json. local is a fresh Claude evaluator. jev is Jev by TypeSafe AI, a different model family, which reduces self-preference bias without removing it; it escalates to Claude when unsure on a deciding check. spec-satisfied and the readiness gates always use Claude. See Evals.

The pattern allows a panel of three evaluators with distinct lenses for the highest-stakes gates. No stage command uses one today, and dev runs as a single author with no module fan-out.

Claude Code constraints

Subagents are stateless leaves: they cannot mutate shared state, inherit no memory, and cannot freely spawn their own subagents. So the orchestrator owns all state and writes .claude/.pipeline-state.json and markers through pipeline.py and marker.sh. A leaf fills an artifact and returns a result; the orchestrator performs the state transition. The hook, marker, and token machinery stays as it was.

Contracts

Each subagent gets file paths as inputs and returns a shape the orchestrator can parse. intake returns squad, problem, repos, customers, and unknowns, and the orchestrator reads unknowns to decide what the PRD gate shows you. With contracts, control flow is deterministic while the leaves are inferential.

Rollout

v5 proved one vertical slice first: intake, prd author, prd sensor script, prd eval in a fresh context. Once it worked against a real repo it became pipeline-pattern.md, and prp, plan, dev, test, pr, and the system-design stages copied it. New stages follow the same file.