Pipeline and Stages

Pipeline and Stages

harness-kit carries one feature through six gated stages:

prd → prp → plan → dev → test → pr

v5 (live): a new intake stage runs before prd. It harvests context from the repo and the context library so the pipeline runs without stopping to ask for inputs, and every stage now follows the orchestrator-plus-leaf-subagents pattern: inputs via resolve-mark-proceed, evals dispatched to a fresh evaluator. The six gated stages below are unchanged; intake sits in front of them and the gating machinery stays the same.

The first two belong to the product-manager agent, the last four to the staff-software-engineer agent. Each stage is a small harness: a guide tells the agent how to write, references give it context, a sensor enforces structure, an eval scores quality, and an approval marker gates the next stage.

Anatomy of every stage

GUIDE     how to write it          pipeline.md · coding-style.md · templates/
REF       context to pull in       AGENTS.md · prp/<feature>.md · conventions/{area}.md
SENSOR    must-pass structure      deterministic, blocks approval
EVAL      scored rubric            LLM-judge, threshold 8.0, retry x3

The flow inside a stage:

1. The agent reads the guides and references and writes the artifact to .claude/runtime/outputs/{pm,sse}/{stage}/{feature_id}.md.
2. On save, deterministic sensors fire. Failure blocks and returns feedback; the agent fixes only the failed parts.
3. The eval scores the artifact 0-10. Below 8.0 retries (up to 3), regenerating only the low-scoring dimensions.
4. On pass, the agent appends an approval marker <!-- approved: {date} score={n} -->.
5. Token spend for the phase is recorded and an inline <!-- tokens: ... --> comment is appended.

The approval marker is the gate: the next stage checks for it before starting.

The stages

Stage	Agent	Artifact	Gates (sensors · evals)
prd	product-manager	Product Requirements Document	prd-structure, prd-acceptance-criteria · prd-quality, prd-readiness
prp	product-manager	Product Requirements Prompt (eng handoff)	prp-structure, prp-context-quality, prp-links, link-validator · prp-quality, prp-context-readiness
plan	staff-software-engineer	technical plan	plan-structure · plan-quality
dev	staff-software-engineer	code + commits	code-conventions, test-coverage, dev-structure · dev-quality
test	staff-software-engineer	test run report	test-structure · test-quality
pr	staff-software-engineer	pull request	pr-structure · pr-quality · arms pr-monitor

System design (the system-architect agent) is an optional front stage before prp/plan: a strong System Design Doc feeds a sharper PRP and a grounded plan. It is not part of the default six-stage pipeline.

Approval markers and token accounting

• Approval marker: <!-- approved: YYYY-MM-DD score=N --> (the PRP also carries ready-for-handoff: true). Its presence is what lets the next stage begin.
• Tokens: hooks bracket each phase with start/end markers, then token-phase.py sums usage from the Claude transcript and writes .claude/runtime/outputs/{pm,sse}/tokens/{feature_id}.json. All stages of one feature append to the same file by reusing the feature_id, so you get the whole lifecycle's cost in one place. Token accounting never blocks a stage; if the transcript is unreadable it logs and exits clean.

Status bar

A live indicator tracks the active feature across all stages:

idle · /product-manager:run · /sse:run · /pipeline:continue
billing-fix [prd+prp+plan+dev+test+pr] · prp approved · plan drafting · next /sse:plan · sensor: plan-structure
billing-fix · complete (prd/prp/plan/dev/test/pr)

State persists at .claude/.pipeline-state.json. Close the session and reopen, /pipeline:continue resumes at the next pending stage. When the PR merges, the monitor clears state automatically.

Single-stage and detour commands

Every stage is also its own command, so you can run just the part you need:

/product-manager:prd | :prp
/sse:plan | :dev | :test | :pr
/sse:run --local        plan → dev → test, no PR
/pipeline:continue      resume next pending stage
/pipeline:reset         abandon the active run

Same sensors, same evals, same artifacts, you lose the one-command convenience, not the gating.

The SDD variant (spec-driven loop)

/sse:sdd replaces the single-shot dev → test with a goal loop:

prd → prp → plan → [dev ↔ test ↔ spec-satisfied eval]  →  [user gate]  →  pr
                         ↑ loop, cap 3 iterations          stops local

• A pre-flight sensor prp-has-acceptance-criteria blocks if the PRP is not testable.
• The loop predicate is built from the PRP's Success criteria (verifiable) + Validation gates.
• Each iteration's spec-satisfied eval runs in a fresh session (no worker context) and returns PASS/FAIL, not a score. FAIL re-enters with a next_iter_focus hint.
• The PR is never auto-opened; you review the transcript at .claude/runtime/outputs/sse/sdd/{feature_id}.md and run /sse:pr when ready.

See also

• Golden Path: running all six stages with one command
• Sensors and Evals: the gates in detail
• Agents: who owns which stage