# pipeline stages

_Status: direction — as of 2026-07-16_
_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), [overview](../OVERVIEW.md)_

## Purpose

Defines the v1 tracer-bullet pipeline shape for `/implement <ticket>`: the ordered stages,
which actor (code/engineer/agent) owns each, and the two 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 `/implement <ticket>`. 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 to the
   human rather than looping forever.
6. **Reviewer agent** — 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.
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).

Two 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.

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.

## Open questions

- Skill/agent naming for each stage (test-writer, programmer, reviewer) — must follow the
  cc-os naming convention before anything ships.
- Whether a cheap tests-vs-spec review should run *before* the programmer stage in later
  versions, to catch misaligned tests before paying for implementation.
- Whether Pocock's `implement` skill is adopted as a thin router over these stages, or
  redesigned from scratch.

## 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)
- `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)
