TDD

Test-Driven Development — Multi-Agent Orchestration

Enforce disciplined RED-GREEN-REFACTOR cycles using separate subagents for test writing and implementation. The core innovation: the Test Writer never sees implementation code, and the Implementer never sees the specification. This prevents the LLM from leaking implementation intent into test design.

When to Use

• User requests TDD, test-first, or red-green-refactor workflow
• User says /tdd with a feature description or bug report
• User wants to add a feature with test coverage enforced from the start
• User wants to fix a bug by first writing a reproducing test

Invocation Modes

In --auto mode, skip all [HUMAN CHECKPOINT] steps. Print status lines instead:

[auto] RED  slice 1/4: "validates email format" — test failing as expected
[auto] GREEN slice 1/4: passing (attempt 1)
[auto] REFACTOR slice 1/4: 1 suggestion applied, 0 skipped

Stop and ask the user ONLY when:

• Implementation fails after 5 attempts
• Regressions cannot be auto-fixed after 3 attempts
• A script error makes it impossible to continue (missing binary, permission denied, etc.)

In --dry-run mode, validate the entire orchestration pipeline without executing any subagents or writing any code:

1. Phase 0 runs fully: detect framework, verify baseline, extract API, discover docs, create state file
2. Phase 1 runs fully: decompose into slices (still requires user approval)
3. For each slice: render all three agent prompts (Test Writer, Implementer, Refactorer) with actual variables. Print rendered prompts to the user with character counts.
4. No Task() calls are made. No test files are written. No implementation code is generated.
5. Validate: check that all template variables resolve (no {UNRESOLVED} placeholders), all scripts execute without error, and the state file is well-formed.
6. Report summary:

DRY RUN COMPLETE: {feature name}

Phase 0:
  Framework: {framework}
  Language: {language}
  Baseline: {pass|greenfield}
  API surface: {line count} lines
  Doc context: {line count} lines (or "none")

Phase 1:
  Slices: {N} ({layer breakdown})

Prompts rendered: {N * 3} (all variables resolved)
  Test Writer:   {char count} chars
  Implementer:   {char count} chars
  Refactorer:    {char count} chars

State file: .tdd-state.json written
No code was modified.

This mode is useful for:

• Validating that scripts work in the project's environment
• Reviewing prompt content before committing to a full TDD run
• Testing skill changes without side effects

Architecture Overview

ORCHESTRATOR (you, reading this file)
├─ Phase 0: Setup — detect framework, extract API, create state file
├─ Phase 1: Decompose into vertical slices → user approves
│
├─ FOR EACH SLICE:
│   ├─ Phase 2 (RED):    Task(Test Writer)  ← spec + API only
│   ├─ Phase 3 (GREEN):  Task(Implementer)  ← failing test + error only
│   └─ Phase 4 (REFACTOR): Task(Refactorer) ← all code + green results
│
└─ Summary

Context Boundaries (the key constraint)

Workflow

Phase 0: Setup (once per session)

Step 1: Detect framework and test runner.

Check for: package.json (jest/vitest), pyproject.toml/pytest.ini (pytest),
go.mod (go test), Cargo.toml (cargo test), Gemfile (rspec), composer.json (phpunit)

If ambiguous, ask: "What command runs your tests? (e.g., npm test, pytest)"

Step 2: Detect language from source files (for agent prompts):

TypeScript (.ts/.tsx), JavaScript (.js/.jsx), Python (.py), Go (.go), Rust (.rs), Ruby (.rb), PHP (.php)

Step 3: Verify green baseline.

bash ~/.claude/skills/tdd/scripts/run_tests.sh {FRAMEWORK} "{TEST_COMMAND}"

Parse the JSON output.

• If status is "pass": proceed.
• If status is "fail": stop — "Existing tests are failing. TDD starts from a green baseline."
• If status is "error" AND total is 0: greenfield project — no tests exist yet. This is fine. Proceed.

Step 4: Extract the public API surface.

bash ~/.claude/skills/tdd/scripts/extract_api.sh {SOURCE_DIR}

Save the output — this is what the Test Writer will see. If empty (greenfield), that's expected.

Step 5: Discover project documentation.

bash ~/.claude/skills/tdd/scripts/discover_docs.sh {PROJECT_ROOT} --lang {LANGUAGE}

This searches for:

• Documentation files: README, ARCHITECTURE.md, docs/ folder, DESIGN.md, SPEC files, ADRs
• API specifications: OpenAPI/Swagger, GraphQL schemas, .proto files
• Source docstrings: JSDoc, Python docstrings, Go doc comments, Rust /// comments

Save the output as {DOC_CONTEXT}. This feeds into:

• Phase 1 — so slice decomposition is informed by documented behavior and API contracts
• Phase 2 — so the Test Writer writes tests aligned with documented intent, not just code signatures

If empty (no docs found), that's fine — proceed without doc context.

Step 6: Create the state file .tdd-state.json in the project root:

{
  "feature": "user's feature description",
  "framework": "jest|vitest|pytest|go|cargo|rspec|phpunit",
  "language": "typescript|javascript|python|go|rust|ruby|php",
  "test_command": "the full test command",
  "source_dir": "src/",
  "doc_context": "output from discover_docs.sh (or empty string)",
  "auto_mode": false,
  "dry_run": false,
  "slices": [],
  "current_slice": 0,
  "phase": "setup",
  "layer_map": {},
  "files_modified": [],
  "test_files_created": []
}

Each slice in the slices array includes a layer field: "domain", "domain-service", "application", or "infrastructure". See Phase 1 for how layers are assigned.

The layer_map maps directory prefixes to layers. Built during Phase 1 from project structure:

{
  "layer_map": {
    "src/domain/": "domain",
    "src/services/": "domain-service",
    "src/application/": "application",
    "src/infrastructure/": "infrastructure",
    "src/adapters/": "infrastructure",
    "src/controllers/": "infrastructure"
  }
}

If the project has no clear directory-layer mapping (flat structure), set layer_map to {} and skip path-based validation.

Step 5a (auto-detect layer_map): If layer_map is empty, scan the source directory for common DDD/layered architecture directory names and auto-populate:

Common directory → layer mappings (check if directories exist):
  */domain/       → "domain"
  */models/       → "domain"          (ORM models often serve as domain entities)
  */entities/     → "domain"
  */value_objects/ → "domain"
  */services/     → "application"     (unless clearly infrastructure)
  */application/  → "application"
  */use_cases/    → "application"
  */core/         → "application"
  */infrastructure/ → "infrastructure"
  */adapters/     → "infrastructure"
  */controllers/  → "infrastructure"
  */api/          → "infrastructure"
  */bot/          → "infrastructure"  (Telegram/Discord bot handlers)
  */handlers/     → "infrastructure"
  */repositories/ → "infrastructure"  (concrete repo implementations)

Only add entries for directories that actually exist in the source tree. If fewer than 2 directories match, leave layer_map empty (flat project). Present the auto-detected map to the user for confirmation:

Auto-detected layer map from directory structure:
  src/models/     → domain
  src/services/   → application
  src/core/       → application
  src/bot/        → infrastructure
  src/api/        → infrastructure

Does this mapping look correct? (adjust if needed)

Update state: "phase": "setup". Write state file immediately.

Phase 1: Specification Decomposition

Take the user's feature request and decompose into ordered vertical slices. Each slice is one testable behavior.

Use doc context: When decomposing, cross-reference {DOC_CONTEXT} from Phase 0 Step 5. Documentation often describes intended behaviors, edge cases, and API contracts that should inform slice boundaries. If docs mention specific error cases, validation rules, or behavioral requirements, consider them as slice candidates.

Inside-Out Slice Ordering

After identifying all slices, sort them inside-out by architectural layer. This ensures each slice can build on real (not mocked) implementations from previous slices:

1. Domain model slices first — pure logic, no dependencies, no mocks needed
2. Domain service slices — cross-aggregate operations using real domain objects
3. Application service / use case slices — orchestration using in-memory fakes for ports
4. Infrastructure adapter slices last — repos, external APIs, framework adapters

Assign each slice a layer tag: domain, domain-service, application, or infrastructure. Use the heuristics from references/layer_guide.md to classify.

Why inside-out? Domain slices produce real objects that later slices use directly. This minimizes mocking and catches integration issues early. It also ensures business rules are implemented and tested before any infrastructure decisions are made.

For simple projects where all code lives in one layer, all slices get layer: "application" and the ordering doesn't change — the guidance degrades gracefully.

Edge Cases in Slice Ordering

Infrastructure-only features (e.g., "add email provider retry logic", "switch from Postgres to MySQL"):

• If a feature has NO domain or application behavior changes, all slices may be infrastructure. This is valid — skip the inner layers entirely.
• Present as: "This is a pure infrastructure change. All slices are infrastructure-layer."

Missing port interface (domain-service needs a port that doesn't exist yet):

• The first slice that needs the port should create the interface as part of its implementation. The Implementer is allowed to create files in inner layers (domain/domain-service can define their own ports).
• Example: a domain-service slice for RegistrationService creates domain/ports/UserRepository interface as part of GREEN.

Cross-cutting slices (a slice touches multiple layers):

• Tag with the INNERMOST layer it touches. The Implementer may create files in that layer and any inner layers.
• Example: a use case that also introduces a new domain event is tagged application but creates a file in domain/events/.

Present to the user:

I've broken this into N vertical slices (ordered inside-out):

Domain:
1. [behavior] — [what the test verifies]

Domain Services:
2. [behavior] — [what the test verifies]

Application:
3. [behavior] — [what the test verifies]

Infrastructure:
4. [behavior] — [what the test verifies]

Each slice follows RED -> GREEN -> REFACTOR before moving to the next.
Does this decomposition look right?

If all slices fall in one layer, skip the layer headings and present as a flat list.

Wait for user approval (even in --auto mode — slice decomposition always needs sign-off).

Update state: Write slices array (each with layer field), set "phase": "decomposed".

Dry-Run Phase Override (Phase 2–4)

In --dry-run mode, replace Phases 2–4 entirely with the following for each slice:

1. Refresh API surface (extract_api.sh)
2. Render the Test Writer prompt with all variables filled in. Print it under a ### Test Writer Prompt (slice N) heading.
3. Render the Implementer prompt using placeholder test code: "(dry-run: test code would be generated by Test Writer)" for {FAILING_TEST_CODE} and "(dry-run: no test output)" for {TEST_FAILURE_OUTPUT}.
4. Render the Refactorer prompt using placeholder values: "(dry-run: no green output)" for {GREEN_TEST_OUTPUT}, "(dry-run: code from Test Writer)" for {ALL_TEST_CODE}, "(dry-run: code from Implementer)" for {ALL_IMPLEMENTATION_CODE}.
5. For each rendered prompt, verify no {UNRESOLVED_VARIABLE} patterns remain (regex: \{[A-Z][A-Z_]+\}). Report any unresolved variables as errors.
6. Print character counts for each prompt.
7. Move to next slice (no Task() calls, no file writes, no test runs).

After all slices are processed, print the dry-run summary and exit. Do NOT clean up the state file — it's useful for subsequent --resume.

Phase 2: RED — Write One Failing Test

Step 1: Refresh the API surface (it changes as slices are implemented):

bash ~/.claude/skills/tdd/scripts/extract_api.sh {SOURCE_DIR}

Step 2: Read the prompt template from references/agent_prompts.md -> "Test Writer Agent" section. Construct the prompt by filling in:

• {SLICE_SPEC}: The current slice's behavior description
• {LANGUAGE}: Detected language from Phase 0
• {FRAMEWORK}: Detected framework name
• {API_SURFACE}: Output from extract_api.sh
• {DOC_CONTEXT}: Output from discover_docs.sh (Phase 0 Step 5). Include only sections relevant to the current slice — filter by keyword match if the full output is large.
• {TEST_FILE_PATH}: Where the test should go (follow project conventions)
• {EXISTING_TEST_CONTENT}: Current content of the test file (if it exists), or "No test file exists yet."
• {FRAMEWORK_SKELETON}: The relevant skeleton from references/framework_configs.md
• {LAYER}: The slice's layer tag from Phase 1
• {LAYER_TEST_CONSTRAINTS}: Layer-specific test constraints (see agent_prompts.md -> Layer-Specific Constraint Lookup)

Step 3: Launch the Test Writer agent:

Task(subagent_type="general-purpose", prompt=<constructed prompt>)

Step 4: Parse the JSON response using the parse_agent_json logic from agent_prompts.md:

1. Strip markdown fences if present
2. Try direct JSON parse
3. If that fails, find first { and last }, try that substring
4. If still invalid: retry the Task call once with appended "Return ONLY a JSON object."
5. If still failing: extract test code manually from the raw response

Step 5: Write the test code to the test file. If the file exists, append the test function (and merge imports). If new, create with the agent's imports_needed + test_code.

Step 5a (post-write test smell scan): Scan the test code for common smells before running:

Step 5b (post-write layer lint): Scan the test code for layer-violating patterns:

If forbidden patterns found:

1. Remove the offending mock/pattern from the test
2. Re-launch Test Writer with appended: "Do NOT use mocking libraries. This is a {LAYER} layer test. Use real domain objects."
3. If second attempt still uses forbidden patterns, ask user

Step 6: Run the test to confirm it FAILS (expect an assertion failure, not a setup error):

bash ~/.claude/skills/tdd/scripts/run_tests.sh {FRAMEWORK} "{TEST_COMMAND_FOR_SPECIFIC_TEST}"

Step 7: Evaluate the result with semantic validation:

Step 8 (interactive mode only — skip in --auto): Present to the user:

RED: Test written and failing as expected.

Test: {test_name}
File: {test_file_path}
Failure: {failure message from JSON}

This test verifies: {test_description from agent response}

Proceed to GREEN phase? (or adjust the test?)

Wait for user approval before proceeding to GREEN.

Update state: "phase": "red", add test file to test_files_created. Write state immediately.