Pipeline and Stages

Pipeline and Stages

harness-kit carries one feature through six gated stages:

prd → prp → plan → dev → test → pr

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