Skip to content

Agent Pipelines

Jump to bottom
Pierry Borges edited this page Jul 15, 2026 · 1 revision

Agent Pipelines

One sequence diagram per agent, showing what actually happens between the command you type and the artifact you get back: which sensors run, which eval scores the result, and where the gate sits.

Pipeline and Stages describes the stages themselves. Sensors and Evals describe the two kinds of feedback. This page is the wiring.

What every stage shares

The same loop runs at every stage of every agent, so read it once and the three diagrams below get much shorter:

  1. The agent generates the artifact under .claude/runtime/outputs/.
  2. Sensors check it deterministically. Pass or fail, no score, no judgment.
  3. An eval scores it. The evaluator is a fresh sub-agent (Task tool, general-purpose) that gets only the artifact path and the rubric path. The author never grades its own work.
  4. Below the threshold, the agent regenerates only the failed or low-scoring sections and tries again. Maximum three attempts, then it returns a blocker instead of proceeding.
  5. On success it appends an approval marker: <!-- approved: {YYYY-MM-DD} score={weighted-total} -->. That marker is the gate the next stage checks.

The threshold is weighted total >= 8.0 for every scored eval: prd-quality, prp-quality, plan-quality, dev-quality, test-quality, pr-quality, design-quality, and design-review-depth.

Human gates belong to the orchestrator, not to the agents. /pipeline:run stops at exactly two: approve the direction after the PRD, and approve the PR before it opens. Individual stages never add gates of their own.

product-manager

prd → prp. Entry point /product-manager:run. Inputs come from the intake artifact rather than from you, so the agent does not stop to ask.

sequenceDiagram
    actor You
    participant PM as product-manager
    participant S as sensors
    participant E as eval (fresh judge)

    You->>PM: /product-manager:run
    PM->>PM: read intake artifact for {feature_id}
    PM->>S: PRD → prd-structure, prd-acceptance-criteria
    S-->>PM: pass or fail, retry up to 3
    PM->>E: prd-quality, then prd-readiness (advisory)
    E-->>PM: weighted total, needs >= 8.0
    PM->>PM: append approval marker to the PRD
    Note over PM: pre-prp-check.sh refuses to start<br/>the PRP without an approved PRD
    PM->>S: PRP → prp-structure, prp-context-quality, prp-links
    S-->>PM: pass or fail, retry up to 3
    PM->>E: prp-quality, then prp-context-readiness
    E-->>PM: score plus one-shot likelihood
    PM-->>You: PRP marked ready-for-handoff
Loading

Artifacts land at .claude/runtime/outputs/pm/prd/{feature_id}.md and .claude/runtime/outputs/pm/prp/{feature_id}.md.

Two details the diagram compresses. prd-readiness is advisory and has no numeric threshold, so it reports without blocking. prp-context-readiness is the real handoff gate: it passes only when every structural sensor passed, shippable is yes or partial, there are at most two blocking questions, and one_shot_likelihood >= 0.7.

staff-software-engineer

plan → dev → test → pr. Entry point /sse:run. It reads the latest approved PRP and auto-detects the area skill (backend, web, mobile, devops) from the repo's files, layering the designer skill on top when the work is clearly a new UI.

sequenceDiagram
    actor You
    participant SSE as staff-software-engineer
    participant S as sensors
    participant E as eval (fresh judge)
    participant GH as GitHub

    You->>SSE: /sse:run
    SSE->>SSE: read approved PRP, detect area skill
    SSE->>S: plan → plan-structure
    S-->>SSE: pass
    SSE->>E: plan-quality
    E-->>SSE: score >= 8.0, plan approved
    SSE->>S: dev → code-conventions, test-coverage after each step
    S-->>SSE: fail means fix and retry, hard stop after 3
    SSE->>E: dev-quality on the dev summary
    E-->>SSE: score >= 8.0, dev approved
    SSE->>SSE: detect and run the repo's test command
    SSE->>E: test-quality, approved only when exit code is 0
    E-->>SSE: score >= 8.0, test approved
    Note over You,SSE: /pipeline:run stops here for the PR gate<br/>/sse:run --local stops for good
    SSE->>GH: gh pr create --draft
    GH-->>SSE: PR url
    SSE->>E: pr-quality
    E-->>SSE: score >= 8.0, PR approved
    SSE->>GH: /sse:pr-monitor polls for the merge
    GH-->>You: merged, pipeline state cleared
Loading

Artifacts land under .claude/runtime/outputs/sse/{plan,dev,test,pr}/{feature_id}.md.

The dev stage is the only one that gates twice: code-conventions and test-coverage run against the code after each implementation step, and dev-structure plus dev-quality then run against the written summary. Failing tests are never retried automatically; the agent returns a blocker and lets you decide.

The SDD variant

/sse:sdd replaces the linear dev and test stages with a goal loop. It plans once, then iterates until the PRP's own spec is satisfied. It is local-only and never opens a PR.

sequenceDiagram
    participant SSE as staff-software-engineer
    participant Sup as supervisor eval (fresh session)

    SSE->>SSE: prp-has-acceptance-criteria, fail blocks the run
    SSE->>SSE: /sse:plan once, wait for the approval marker
    loop up to 3 iterations
        SSE->>SSE: /sse:dev, later passes get --focus from the last verdict
        SSE->>SSE: /sse:test
        SSE->>Sup: PRP, dev summary, test report, git diff main...HEAD
        Sup-->>SSE: PASS breaks the loop, FAIL returns next_iter_focus
    end
    SSE->>SSE: write the transcript, approved on PASS, blocked at the cap
Loading

The predicate is built from the PRP itself: every bullet under Success criteria (verifiable) must be met by both code and a test, and every command in the Validation gates block must exit 0. The supervisor runs in a fresh session so the worker's context cannot leak into its own grading. Hitting the three-iteration cap is real signal that the spec and the code disagree.

system-architect

design → review. Entry point /system-design:run. This agent is an optional front stage before the PRP, not part of the golden path. It picks a topic skill the same way the staff engineer picks an area skill: url-shortener, rate-limiter, or search-engine when the problem matches one, and the generic design skill otherwise.

sequenceDiagram
    actor You
    participant SA as system-architect
    participant S as sensors (self-applied)
    participant E as eval (fresh judge)

    You->>SA: /system-design:run
    SA->>SA: route to a topic skill, or fall back to generic design
    SA->>S: design → design-structure, design-rigor
    S-->>SA: a missing section, number, or mermaid diagram blocks
    SA->>E: design-quality
    E-->>SA: score >= 8.0, design approved
    SA->>SA: adversarial review, the 10 staff questions
    SA->>S: review → design-structure, review variant
    S-->>SA: 10 questions answered, verdict present
    SA->>E: design-review-depth
    E-->>SA: score >= 8.0
    SA-->>You: verdict ship, revise, or block
Loading

Artifacts land at .claude/runtime/outputs/architect/design/{feature_id}.md and .claude/runtime/outputs/architect/review/{feature_id}.md.

This agent is deliberately hook-free: its sensors are self-applied markdown rules rather than scripts run by settings.json hooks, which keeps it portable to any tool that reads AGENTS.md. The review defaults to skeptical and interrogates rather than summarizes. A block verdict is terminal, the design is not marked ready and the run surfaces the blockers instead.

Related

harness-kit

The harness

v5: autonomy

System design

Back to repo →

Clone this wiki locally