Pipeline and Stages

harness-kit carries one feature through six gated stages:

prd → prp → plan → dev → test → pr

The product-manager agent owns the first two and the staff-software-engineer agent owns the last four. An intake stage runs in front: it harvests the repo and the context library so no stage stops to ask, and each stage then runs as an orchestrator with leaf subagents. /pipeline:run drives intake through pr with two human gates, after the PRD and before the PR.

Anatomy of a stage

Each stage is a small harness: guides such as pipeline.md and templates/ say how to write, references such as prp/<feature>.md and conventions/{area}.md give context, a sensor blocks on bad structure, and an eval scores quality.

The agent writes the artifact to .claude/runtime/outputs/{pm,sse}/{stage}/{feature_id}.md. On save the sensors fire, and a failure returns feedback so the agent fixes only the failed parts. Then the judge answers the rubric's atomic yes/no checks, and eval-score.py recomputes the weighted 0 to 10 total from the rubric weights.

The judge is a fresh Claude evaluator (local, the default) or Jev by TypeSafe AI (jev), set per project with /hk:eval. Below 8.0 the stage retries up to 3 times, regenerating only the failed checks. On pass the agent appends <!-- approved: {date} score={n} -->, and the next stage checks for that marker before it starts.

The stages

prp-links runs link-validator.py. The readiness evals and spec-satisfied always use Claude, whichever judge you pick. System design, owned by the system-architect agent, is an optional front stage before prp or plan and sits outside these six.

Approval markers and tokens

The marker is <!-- approved: YYYY-MM-DD score=N -->, and the PRP also carries ready-for-handoff: true. Its presence lets the next stage begin.

Hooks bracket each phase, and token-phase.py sums usage from the Claude transcript into .claude/runtime/outputs/{pm,sse}/tokens/{feature_id}.json, one file per agent for the whole lifecycle because every stage reuses the feature_id. Token accounting never blocks a stage; on an unreadable transcript it logs and exits clean.

Pipeline status

hk status prints the active feature. The same line can drive the Claude Code status line, but only if you install with HK_STATUSLINE=1; by default the harness leaves your own status line alone, since a project setting would override it.

idle · /product-manager:run · /sse:run · /pipeline:continue
billing-fix · prp approved · plan drafting · next /sse:plan
billing-fix · complete

State lives in .claude/.pipeline-state.json. Reopen a session and /pipeline:continue resumes at the next pending stage. When the PR merges, the monitor clears the state.

Context tools

Stages that read the target repo run .claude/scripts/context-tools.sh once and use what is installed. semble finds code by intent and returns file and line, repowise explains modules and scores the risk of touching them and lists the tests that cover a change, context7 fetches current library docs, and joern or graphify answer who calls what. With none of them the stage falls back to grep. context-strategy.md maps each question to a tool.

Single-stage commands

Every stage is also its own command with the same sensors and evals. The list of detours is on Golden Path.

The SDD loop

/sse:sdd replaces the single pass of dev and test with a goal loop:

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

The pre-flight sensor prp-has-acceptance-criteria blocks a PRP that is not testable. The loop predicate comes from the PRP's Success criteria (verifiable) and Validation gates. Each iteration's spec-satisfied eval runs in a fresh Claude session and returns PASS or FAIL; a FAIL re-enters with a next_iter_focus hint.

The PR never opens on its own. You read the transcript at .claude/runtime/outputs/sse/sdd/{feature_id}.md and run /sse:pr when ready.

See also Golden Path, Sensors, Evals, Agents.

This page mirrors Pipeline and Stages in the wiki. Edit it there.