Team-Based ATDD Workflow

Orchestrate an agent team that follows the Acceptance Test Driven Development workflow. The team lead coordinates specialist agents through five phases: spec writing, spec review, pipeline generation, implementation, and post-implementation review.

Team Detection

Before creating a team, check for existing teams:

1. •Read ~/.claude/teams/ to list active teams
2. •If a team exists, present the user with a choice:
   • •Extend — Add ATDD roles (spec-writer, implementer, reviewer) to the existing team. Skip roles that already exist by name.
   • •Replace — Shut down the existing team and create a fresh ATDD team.
   • •New team — Create a separate ATDD team alongside the existing one.

If no team exists, proceed directly to team creation.

Roles

Create three teammates with these roles:

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

Workflow Phases

Execute phases strictly in order. Each phase has a gate that must pass before proceeding to the next phase.

Phase 1 — Spec Writing

Assign to: spec-writer

Send the feature description and instruct the spec-writer to:

1. •Read the existing codebase to understand domain language
2. •Write Given/When/Then specs in specs/[feature-name].txt
3. •Use ONLY external observables — no implementation language
4. •Follow the GWT format from the atdd skill (semicolon comments, periods at end of statements)
5. •Send specs back for review before proceeding

Gate: Team lead reviews and approves specs. Do not proceed until approved.

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

Phase 2 — Spec Review

Assign to: reviewer

Instruct the reviewer to audit specs for implementation leakage:

• •Class names, function names, method names
• •Database tables, columns, queries
• •API endpoints, HTTP methods, status codes
• •Framework terms (controller, service, repository)
• •Internal state or data structures

Also verify: one behavior per spec, clarity for non-developers, language portability.

Gate: Reviewer sends findings. Team lead decides whether specs need revision. If revisions needed, return to Phase 1.

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

Phase 3 — Pipeline Generation

Assign to: Team lead (self) or implementer

Generate or update the 3-stage test pipeline:

1. •Parser — reads specs/*.txt, outputs IR
2. •Generator — reads IR, produces runnable tests
3. •Runner — run-acceptance-tests.sh

Run acceptance tests after generation. 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: implementer

Instruct the implementer to:

1. •Run acceptance tests — confirm they fail
2. •Pick the simplest failing acceptance test
3. •Write a unit test, then minimal code to pass it
4. •Refactor, repeat until that acceptance test passes
5. •Move to next failing acceptance test
6. •Continue until ALL acceptance + unit tests pass

Rules for the implementer:

• •Never modify spec files — they are the contract
• •Never modify generated test files — only regenerate
• •If a spec seems wrong, stop and ask the team lead
• •Report results of both test streams when done

Gate: Both test streams green. Implementer reports results.

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

Phase 5 — Post-Implementation Review

Assign to: reviewer

Two reviews:

1. •Spec review — Run /atdd:spec-check. Check if implementation details leaked into specs during development.
2. •Code review — Check test quality, code structure, missing edge cases.

Gate: Reviews clean or issues addressed. Team lead approves.

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

After Completion

When all phases pass:

1. •Run both test streams one final time to confirm green
2. •Ask the user whether to commit (do not auto-commit)
3. •Ask whether to iterate with the next feature (return to Phase 1) or shut down the team

Tips for Team Leads

• •Never delegate spec approval. Specs are the team lead's contract.
• •Run spec-check twice — before and after implementation.
• •Test portability. Verify specs would work for a different implementation language.
• •Scope tightly. One feature per cycle. Do not spec the whole system.
• •Verify both streams personally before accepting the implementer's work.
• •Keep the team informed. When revising specs after review, notify the implementer so they don't work against stale specs.

Additional Resources

Reference Files

For detailed prompt templates for each phase:

• •references/prompts.md — Copy-paste prompt templates for every phase, including the team creation prompt and all agent instructions