/tdd-cycle

description: "Execute a comprehensive TDD workflow with strict red-green-refactor discipline"
argument-hint: "<feature or module to implement> [--incremental|--suite] [--coverage 80]"

TDD Cycle Orchestrator

CRITICAL BEHAVIORAL RULES

You MUST follow these rules exactly. Violating any of them is a failure.

1. **Execute steps in order.** Do NOT skip ahead, reorder, or merge steps. 2. **Write output files.** Each step MUST produce its output file in `.tdd-cycle/` before the next step begins. Read from prior step files — do NOT rely on context window memory. 3. **Stop at checkpoints.** When you reach a `PHASE CHECKPOINT`, you MUST stop and wait for explicit user approval before continuing. Use the AskUserQuestion tool with clear options. 4. **Halt on failure.** If any step fails (agent error, test failure, missing dependency), STOP immediately. Present the error and ask the user how to proceed. Do NOT silently continue. 5. **Use only local agents.** All `subagent_type` references use agents bundled with this plugin or `general-purpose`. No cross-plugin dependencies. 6. **Never enter plan mode autonomously.** Do NOT use EnterPlanMode. This command IS the plan — execute it.

Pre-flight Checks

Before starting, perform these checks:

1. Check for existing session

Check if `.tdd-cycle/state.json` exists:

• If it exists and `status` is `"in_progress"`: Read it, display the current step, and ask the user:

  Found an in-progress TDD cycle session:
  Feature: [name from state]
  Current step: [step from state]

  1. Resume from where we left off
  2. Start fresh (archives existing session)

• If it exists and `status` is `"complete"`: Ask whether to archive and start fresh.

2. Initialize state

Create `.tdd-cycle/` directory and `state.json`:

{
  "feature": "$ARGUMENTS",
  "status": "in_progress",
  "mode": "suite",
  "coverage_target": 80,
  "current_step": 1,
  "current_phase": 1,
  "completed_steps": [],
  "files_created": [],
  "started_at": "ISO_TIMESTAMP",
  "last_updated": "ISO_TIMESTAMP"
}

Parse `$ARGUMENTS` for `--incremental`, `--suite`, and `--coverage` flags. Use defaults if not specified (mode: suite, coverage: 80).

3. Parse feature description

Extract the feature description from `$ARGUMENTS` (everything before the flags). This is referenced as `$FEATURE` in prompts below.

---

Configuration

Coverage Thresholds

• Minimum line coverage: parsed from `--coverage` flag (default 80%)
• Minimum branch coverage: 75%
• Critical path coverage: 100%

Refactoring Triggers

• Cyclomatic complexity > 10
• Method length > 20 lines
• Class length > 200 lines
• Duplicate code blocks > 3 lines

---

Phase 1: Test Specification and Design (Steps 1-2)

Step 1: Requirements Analysis

Use the Task tool to analyze requirements:

Task:
  subagent_type: "general-purpose"
  description: "Analyze requirements for TDD: $FEATURE"
  prompt: |
    You are a software architect specializing in test-driven development.

    Analyze requirements for: $FEATURE

    ## Deliverables
    1. Define acceptance criteria with clear pass/fail conditions
    2. Identify edge cases (null/empty, boundary values, error states, concurrent access)
    3. Create a comprehensive test scenario matrix mapping requirements to test cases
    4. Categorize tests: unit, integration, contract, property-based
    5. Identify external dependencies that will need mocking

    Write your complete analysis as a single markdown document.

Save the agent's output to `.tdd-cycle/01-requirements.md`.

Update `state.json`: set `current_step` to 2, add `"01-requirements.md"` to `files_created`, add step 1 to `completed_steps`.

Step 2: Test Architecture Design

Read `.tdd-cycle/01-requirements.md` to load requirements context.

Use the Task tool to design test architecture:

Task:
  subagent_type: "general-purpose"
  description: "Design test architecture for $FEATURE"
  prompt: |
    You are a test automation expert specializing in test architecture and TDD workflows.

    Design test architecture for: $FEATURE

    ## Requirements
    [Insert full contents of .tdd-cycle/01-requirements.md]

    ## Deliverables
    1. Test structure and organization (directory layout, naming conventions)
    2. Fixture design (shared setup, teardown, test data factories)
    3. Mock/stub strategy (what to mock, what to use real implementations for)
    4. Test data strategy (generators, factories, edge case data sets)
    5. Test execution order and parallelization plan
    6. Framework-specific configuration (matching project's existing test framework)

    Ensure architecture supports isolated, fast, reliable tests.
    Write your complete design as a single markdown document.

Save the agent's output to `.tdd-cycle/02-test-architecture.md`.

Update `state.json`: set `current_step` to "checkpoint-1", add step 2 to `completed_steps`.

---

PHASE CHECKPOINT 1 — User Approval Required

You MUST stop here and present the test specification and architecture for review.

Display a summary of the requirements analysis from `.tdd-cycle/01-requirements.md` and test architecture from `.tdd-cycle/02-test-architecture.md` (key test scenarios, architecture decisions, mock strategy) and ask:

Test specification and architecture complete. Please review:
- .tdd-cycle/01-requirements.md
- .tdd-cycle/02-test-architecture.md

1. Approve — proceed to RED phase (write failing tests)
2. Request changes — tell me what to adjust
3. Pause — save progress and stop here

Do NOT proceed to Phase 2 until the user selects option 1. If they select option 2, revise and re-checkpoint. If option 3, update `state.json` status and stop.

---

Phase 2: RED — Write Failing Tests (Steps 3-4)

Step 3: Write Unit Tests (Failing)

Read `.tdd-cycle/01-requirements.md` and `.tdd-cycle/02-test-architecture.md`.

Use the Task tool:

Task:
  subagent_type: "general-purpose"
  description: