# Four Agent Pipeline

> Orchestrates a four-agent coding pipeline (Specifier -> Coder -> Refactorer -> Architect) with steel-cage quality gates and automatic failure routing. Use when the user wants spec-driven development, says "run the four-agent pipeline", "compile this requirement into acceptance criteria", "multi-agent TDD", or wants AI agents to check each other's work instead of human code review.

- Skill: `whaojie797-design/four-agent-pipeline` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add whaojie797-design/four-agent-pipeline`
- Raw SKILL.md: https://api.skillmd.com/api/skills/whaojie797-design/four-agent-pipeline/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: whaojie797-design (https://skillmd.com/u/whaojie797-design)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/whaojie797-design/four-agent-pipeline

---


# Four-Agent Pipeline

One idea, four agents, zero line-by-line human review. The human does exactly two
things: write the requirement in a machine-verifiable form (via the Specifier),
and trust a welded-shut set of automated quality gates. Everything in between is
agents keeping each other honest.

Core philosophy: **don't review the process — gate the outcome.**

## When to Use This Skill

- Building a non-trivial feature where "vibe-coded" output is not acceptable
- Setting up spec-driven development with Gherkin acceptance criteria
- Running a multi-agent workflow (Claude Code subagents, CrewAI, or four
  separate sessions with the same model) with clear role separation
- Replacing or augmenting human code review with measurable quality gates

## The Pipeline

```
vague requirement (natural language)
        |
        v
[1] SPECIFIER   compiles requirement -> Gherkin acceptance criteria + DoD
        |       (the ONLY output a human reviews; spec is frozen after sign-off)
        v
[2] CODER       minimal implementation -> all acceptance + unit tests green
        |
        v
[3] REFACTORER  structure only, never behavior -> complexity/dup/mutation targets met
        |
        v
[4] ARCHITECT   veto power -> per-gate PASS/FAIL with measured values
        |
        v
auto-merge — human reviews the acceptance-criteria diff, never the code diff
```

Failures never stall on a human. Every FAIL is routed back to the responsible
upstream agent with the measured value vs. threshold. See
`references/failure-routing.md`.

## How to Run

1. **Scaffold** (optional): `python scripts/init_pipeline.py <project-dir> --feature <name>`
   creates `spec.md`, `acceptance/<name>.feature`, and the report templates.
2. **Phase 1 — Specify**: give the requirement to the Specifier
   (full prompt: `references/specifier.md`). A human reviews and signs off the
   spec. After sign-off the spec is frozen — downstream agents may file a Spec
   Objection Report but never edit the spec themselves.
3. **Phase 2 — Code**: hand the frozen spec to the Coder
   (`references/coder.md`). Gate to exit: acceptance + unit tests 100% green.
4. **Phase 3 — Refactor**: hand the green code to the Refactorer
   (`references/refactorer.md`). Gates to exit: every metric in
   `references/steel-cage.md` meets its threshold, mutation score included.
5. **Phase 4 — Gate review**: hand everything to the Architect
   (`references/architect.md`). PASS -> merge. FAIL -> route back per
   `references/failure-routing.md` and repeat from that agent.

## Hard Rules (all four agents must obey)

- The spec is a contract. Frozen after human sign-off.
- No vague words in acceptance criteria — every criterion is a decidable boolean.
- Coder never weakens tests to make them pass; Refactorer never changes behavior.
- Every gate is binary. "Close enough" is a FAIL.
- The Architect adjudicates on reproducible measurements only, never taste.

## Bundled Resources

- `references/specifier.md` — full system prompt for Agent 1 (requirements -> Gherkin)
- `references/coder.md` — full system prompt for Agent 2 (green tests, minimal impl)
- `references/refactorer.md` — full system prompt for Agent 3 (structure + mutation testing)
- `references/architect.md` — full system prompt for Agent 4 (veto gatekeeper)
- `references/steel-cage.md` — the quality-gate checklist: thresholds + tools per ecosystem
- `references/failure-routing.md` — who-fails-goes-back-to-whom table
- `assets/templates/` — spec, feature, test-report, quality-report, gate-report, routing templates
- `scripts/init_pipeline.py` — scaffolds the pipeline directory layout (Python stdlib only)