/atdd-team

name: atdd-team
description: >-
  Use to orchestrate a team-based ATDD workflow — six phases (spec writing,
  spec review, pipeline generation, implementation, refine, verify & harden)
  each handled by a fresh agent so no role erodes across a long-running
  feature. Triggers — "build a feature with a team", "use ATDD with agents",
  "create an ATDD team", "orchestrate agents for ATDD", "coordinate agents
  for feature development", "add ATDD roles to my team", "add spec-writer
  and reviewer to the team".

Team-Based ATDD Workflow

Orchestrate an agent team that follows the Acceptance Test Driven Development workflow. The team lead coordinates specialist agents through six phases. Each phase is run by a **fresh agent invocation** — no agent persists across phases.

Why fresh per phase

A long-lived agent's context compacts as a feature runs for hours. Compaction silently erodes role identity and discipline: agents lose their role, invent constraints that do not exist, and skip expensive-but-required steps. A fresh per-phase agent reloads its instructions clean — the same insight as the engineer plugin's per-skill model. The "team" exists for **parallelism** across features, not for keeping agents alive within one feature.

Team Detection

Before spawning phase agents, check for existing teams:

1. Read `~/.claude/teams/` to list active teams. 2. If a team exists, present the user with a choice:

• **Extend** — run the ATDD phases for this feature alongside the existing team.
• **Replace** — shut down the existing team and run ATDD fresh.
• **New team** — run the ATDD pipeline as a separate team.

If no team exists, proceed directly.

Roles

Each phase is run by a fresh agent invocation scoped to that phase, then ended.

| Role | Maps to | Owns phase | |------|---------|-----------| | `spec-writer` | discuss, discover-acs, atdd spec step | 1 Spec Writing | | `reviewer` | spec-guardian agent | 2 Spec Review | | `implementer` | atdd impl, pipeline-builder | 3 Pipeline Gen, 4 Implementation | | `refiner` | the engineer plugin's `refine` skill | 5 Refine | | `architect` | consistency-check, crap-analyzer, atdd-mutate | 6 Verify & Harden |

The **team lead** (the orchestrating agent or user) owns the workflow, approves all work, enforces discipline, and verifies the `agent_id` independence binding. The team lead never delegates approval — specs are the team lead's contract.

Coordination rules

• **Durable handoffs, not chat.** Each phase ends by writing a handoff summary

to `features/NNN-slug/handoffs/` (the engineer plugin's handoff contract, with the `exit_criteria` block). The next phase's fresh agent reads the prior handoff for context — coordination survives a context compaction.

• **Phase gate = checkpoint exit criteria.** A phase is done only when its

handoff asserts every exit criterion met (Foundation Design Section 8). Before starting a phase, verify the prior checkpoint is complete — run the engineer plugin's `scripts/dae_handoff.py <feature-dir> --through <prior-cp>`.

• **`agent_id` independence (Principle 7).** Each phase handoff records its

`agent_id`. The `architect`'s `agent_id` MUST differ from both the `implementer`'s and the `refiner`'s — the verifier verifies neither its own code nor its own refinement. The team lead checks this.

• **Role boundary.** The `implementer` takes the code to green only — it does

NOT do deep refactoring; that is the `refiner`'s phase. Every phase handoff states explicitly what was NOT done and what is left for the next role.

• **Per-phase anchor.** Each phase agent's spawn prompt embeds a `reorient`-style

anchor: role, autonomy level, the prior handoff, the phase's exit criteria, and the non-negotiables. See `references/prompts.md`.

Workflow Phases

Execute phases strictly in order. Each phase spawns a fresh agent, ends with a durable handoff, and is gated on the prior checkpoint's exit criteria.

Before Phase 1, create one TodoWrite todo per phase of this workflow (Phases 1–6), all at once — the full list up front, as a roadmap. Flip each todo to `in_progress` / `completed` as you go. See `${CLAUDE_PLUGIN_ROOT}/references/progress-indicator.md`.

Phase 1 — Spec Writing

**Assign to:** a fresh `spec-writer` agent.

Instruct it to: 1. Read the existing codebase to understand domain language 2. Write the feature's `spec.md` in standard Gherkin 3. Use ONLY external observables — no implementation language 4. Follow the standard Gherkin format from the atdd skill 5. End with a handoff summary

**Gate:** Team lead reviews and approves the specs (Checkpoint 3 exit criteria). Do not proceed until approved.

For the detailed prompt template, see `references/prompts.md` — Phase 1.

Phase 2 — Spec Review

**Assign to:** a fresh `reviewer` agent.

Run the spec-guardian agent to audit `spec.md` for implementation leakage: class/function names, database tables, API endpoints, framework terms, internal state. Also verify one behavior per scenario and clarity for non-developers.

**Gate:** The reviewer's handoff reports findings. The team lead decides whether the spec needs revision. If revisions are needed, return to Phase 1.

For the detailed prompt template, see `references/prompts.md` — Phase 2.

Phase 3 — Pipeline Generation

**Assign to:** a fresh `implementer` agent (or the team lead).

Generate the project-specific test pipeline — the `pipeline-builder` agent produces the generator + step handlers + runner; `dae_gherkin.py` is the portable, shipped parser. Run the acceptance tests — they **must fail** (red). If they pass, either the behavior exists or the generator is wrong.

**Gate:** Acceptance tests fail as expected. Pipeline is functional.

For the detailed prompt template, see `references/prompts.md` — Phase 3.

Phase 4 — Implementation

**Assign to:** a fresh `implementer` agent.

Instruct it to: 1. Run acceptance tests — confirm they fail 2. Pick the simplest failing acc