# pipeline stages

_Status: settled — grilled 2026-07-18_
_Connects to: [deterministic-gates](deterministic-gates.md), [agent-design-principles](agent-design-principles.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [worktree-parallelism](worktree-parallelism.md), [pipeline-observability](pipeline-observability.md), [standards-and-conventions](standards-and-conventions.md), [debugger](debugger.md), [overview](../OVERVIEW.md)_

## Purpose

Defines the v1 tracer-bullet pipeline shape for `/os-sdlc:implement <ticket>`: the ordered
stages, which actor (code/engineer/agent) owns each, and the three decisions that keep the
pipeline at one-agent-one-job grain. Load this before designing any pipeline stage, skill, or
agent definition for os-sdlc.

## Design

Manually triggered by `/os-sdlc:implement <ticket>` — an orchestrator skill consuming exactly
one ticket as argument. The orchestrator prompt is written from scratch: none of Matt
Pocock's `implement` wording survives, since his prompt assumes a single agent running its
own tests, which contradicts [deterministic-gates](deterministic-gates.md) (hooks, not
agents, run tests). Pocock's `implement` stays in Sources as lineage only. Like every prompt
in this pipeline, the orchestrator prompt follows the minimal-prompt discipline
(ADR-0044): start from the fewest sentences stating the job, inputs, and return format, and
add wording only in response to an observed failure.

Stages, in order:

1. **Ticket intake** (code) — reads the issue via the `os-backlog` tracker key
   (`.cc-os/config`); no new ticketing system, per ADR-0037's composability constraint.
2. **Test-writer agent** — writes failing tests from the ticket, nothing else.
3. **Red-assert gate** (deterministic hook) — runs the suite; it MUST fail. A pass here means
   vacuous tests or the feature already exists — either way the pipeline halts rather than
   proceeding on a false signal.
4. **Programmer agent** — makes the tests pass. One agent, not a seam-creator/implementor
   split.
5. **Green-assert gate** (deterministic hook) — suite + lint must pass. Failures are
   auto-fed back into the same programmer's next turn; a max-iterations cap escalates rather
   than looping forever. In v1 escalation goes to the human; once the happy path is trusted,
   the stuck path routes to the [debugger](debugger.md) first — a separate agent from the
   reviewer below.
6. **Reviewer agent** — a *named agent* (not a skill), so its tool surface is minimal and
   its context never leaks into the orchestrator's (see
   [agent-design-principles](agent-design-principles.md)). Named `reviewer`, alongside
   `test-writer` and `programmer` — cc-os's first named agents. Agent names are kebab-case
   role-nouns naming the actor (who does the job), distinct from the verb-first rule that
   governs skill names (see
   `plugins/cc-architect/references/conventions/cc-os-naming.md`). It reads only a hook-assembled
   context packet — test status from the green-assert gate (passing, unless max-iterations
   escalated), a mechanically generated diff, and the spec/ticket — gathered into one
   document by a code-actor hook before the agent is invoked; the reviewer runs nothing
   itself. Two ordered checks: first tests align with the spec/ticket, then code aligns
   with both tests and spec. Order matters — misaligned tests invalidate a "code passes
   tests" result. **Scope is the judgment residue only** — code *standards/conventions* are
   already proven mechanically by the gates ([standards-and-conventions](standards-and-conventions.md)),
   so the reviewer never re-checks them; it checks spec fidelity, test relevance, and that
   the code solves the assigned problem rather than merely gaming the tests. Because mechanical
   quality is a settled precondition, this is normally a **single-shot opus** call over that
   packet. ADR-0037's `/os-sdlc:review` (spec-fidelity + judgment-residue smells) is
   satisfied by this same agent; if standalone review of an
   arbitrary diff is wanted outside a pipeline run, a thin skill wrapper dispatches the
   agent with a hand-assembled packet — one reviewer, two entry points.
7. **Cleanup & report** (agent/code mix) — trims scratch artifacts, produces a summary for the
   human. What gets written, where, and for how long is defined in
   [pipeline-observability](pipeline-observability.md).
8. **Human merge gate** — v1 has no automated merge; see
   [worktree-parallelism](worktree-parallelism.md).

Three decisions fix the grain of this pipeline:

- **One programmer agent, not seam-creator/implementor.** The seam is not a judgment
  boundary — splitting it adds a handoff and context loss for no trust gain. This is exactly
  the over-granularity DeltaRefinery suffered from. Revisit only if audits show programmers
  entangling design decisions to cheat tests (i.e., gaming the green-assert gate instead of
  solving the ticket).
- **Refactor is not a standing stage.** The reviewer's critique triggers a correction loop —
  re-invoking the programmer with findings — using the same feedback mechanism as a failing
  gate, rather than a dedicated pipeline stage.
- **No pre-programmer tests-vs-spec review stage.** The reviewer's first ordered check (stage
  6, above) already covers tests-vs-spec alignment; adding a second, earlier review of the
  same question buys nothing but a cheaper failure mode — the only cost of catching a
  misaligned test late is one wasted programmer run. Revisit only if audits show a pattern of
  wasted programmer runs traced to misaligned tests. Related: mechanically lintable TEST
  standards (linting tests like code, per
  [standards-and-conventions](standards-and-conventions.md)) further shrink what's left for
  the reviewer to catch by judgment at all.

Grain: one ticket, one vertical slice. TDD is internal to the stage (test-writer then
programmer within one ticket's run), never orchestrated per-example from outside — that
per-example granularity was a DeltaRefinery downside being deliberately dropped.

## Resolved 2026-07-18

Agent naming, orchestrator-prompt provenance, and the pre-programmer-review question (all
open as of 2026-07-16) are settled above. No open questions remain in this doc; the tracer
walk (rung zero of build sequencing, see [overview](../OVERVIEW.md)) is performed by hand,
once, in a real git worktree with `.cc-os/config` manually copied in to work around
[worktree-parallelism](worktree-parallelism.md)'s Forgejo issue #73 — the native fix for #73
is a hard dependency of wiring this pipeline into skills/hooks/agents.

## Sources

- ADR-0037 (`docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md`)
- ADR-0042 (2026-07-16, Planka retirement / git-issues-only os-backlog)
- ADR-0044 (2026-07-18, minimal-prompt discipline)
- `plugins/cc-architect/references/conventions/cc-os-naming.md` (agent naming, added
  2026-07-18)
- `plugins/os-sdlc/OVERVIEW.md`
- SecondBrain vault: `agentic-sdlc-ai-developer-workflow-taxonomy.md`,
  `matt-pocock-skills-v1-1-changes.md`
- `~/dev/delta-refinery` (prior art, principles kept/dropped as noted above)
- 2026-07-16 design session (this doc's origin); grilled 2026-07-18
