tdd-cycle

What this skill does

# TDD Cycle Skill

Run a full RED-GREEN-REFACTOR Test-Driven Development workflow for a feature. This skill drives the entire TDD lifecycle: understand the feature, write failing tests, confirm they fail (RED), implement minimal code to make them pass (GREEN), then refactor while keeping tests green (REFACTOR).

**CRITICAL: Complete ALL 7 phases.** The workflow is not complete until Phase 7: Report is finished. After completing each phase, immediately proceed to the next phase without waiting for user prompts.

## Core Principles

1. **Tests before implementation** -- Write tests first. The tests define what the code should do. Implementation follows from tests, not the other way around.
2. **Minimal implementation** -- Write only the code needed to make failing tests pass. No extra features, no premature optimization, no speculative abstractions.
3. **Regression protection** -- Existing tests must continue passing at every phase. Zero tolerance for regressions.
4. **Phase gate enforcement** -- Each phase must complete and verify before the next begins. RED verification is mandatory. GREEN verification is mandatory.
5. **Behavior over implementation** -- Tests verify what code does (inputs, outputs, side effects), not how it does it internally.
6. **Autonomous after plan confirmation** -- The user confirms the plan once in Phase 3. After that, the entire RED-GREEN-REFACTOR cycle runs without interruption.

## AskUserQuestion is MANDATORY

**IMPORTANT**: You MUST use the `AskUserQuestion` tool for ALL questions to the user. Never ask questions through regular text output.

- Plan confirmation -> AskUserQuestion
- Framework selection -> AskUserQuestion
- Clarifying questions -> AskUserQuestion
- Error recovery options -> AskUserQuestion

Text output should only be used for presenting information, summaries, and progress updates.

**NEVER do this** (asking via text output):
```
Should I proceed with this plan?
1. Yes
2. No, modify it
```

**ALWAYS do this** (using AskUserQuestion tool):
```yaml
AskUserQuestion:
  questions:
    - header: "TDD Plan Confirmation"
      question: "Review the TDD plan above. Ready to proceed?"
      options:
        - label: "Proceed"
          description: "Run the full RED-GREEN-REFACTOR cycle autonomously"
        - label: "Modify plan"
          description: "Adjust tests, scope, or approach before starting"
        - label: "Cancel"
          description: "Cancel the TDD workflow"
      multiSelect: false
```

---

## Phase 1: Parse Input

**Goal:** Determine the input type and resolve context.

Analyze `$ARGUMENTS` to determine the operating mode.

### Input Type Detection

**Feature Description** -- triggered when input is:
- Free-text describing a feature (e.g., "add user login with email and password")
- A file path to source code that needs TDD treatment (e.g., `src/auth/login.py`)

**Task ID** -- triggered when input is:
- A numeric ID, possibly prefixed with `#` or `task-` (e.g., `5`, `#5`, `task-5`)

**Spec Section** -- triggered when input is:
- A spec file path with optional section reference (e.g., `specs/SPEC-feature.md Section 5.1`)

### Context Resolution

**Feature Description:**
1. Record the feature description for use in Phase 3 (Plan)
2. Use Glob/Grep to find existing related code if a file path is provided
3. Determine the target module and directory

**Task ID:**
1. Use `TaskGet` to retrieve the full task details
2. Extract acceptance criteria (Functional, Edge Cases, Error Handling)
3. Check `metadata.spec_path` for the source spec
4. Record the task's description, requirements, and blocked-by/blocks relationships

**Spec Section:**
1. Read the spec file
2. Locate the referenced section
3. Extract acceptance criteria, user stories, and edge cases from the section

### Error Cases

**No input provided:**
```yaml
AskUserQuestion:
  questions:
    - header: "TDD Input"
      question: "What would you like to run TDD for?"
      options:
        - label: "Feature description"
          description: "Describe the feature to build test-first"
        - label: "Task ID"
          description: "Run TDD for a Claude Code Task"
        - label: "Spec section"
          description: "Run TDD from a spec's acceptance criteria"
        - label: "Retrofit existing code"
          description: "Add tests to existing untested code"
      multiSelect: false
```

Then prompt for the specific value based on the selection.

**Invalid task ID:**
```
ERROR: Task #{id} not found.

Available tasks:
{List first 5 pending/in-progress tasks from TaskList}

Usage: /tdd-cycle <feature-description|task-id|spec-section>
```

**Invalid spec path:**
```
ERROR: Spec file not found: {path}

Did you mean one of these?
{List matching files from Glob search for similar names}

Usage: /tdd-cycle <spec-path>
```

---

## Phase 2: Understand

**Goal:** Load project conventions, detect the test framework, and explore the relevant codebase.

### Step 1: Load Project Conventions

Read project-level conventions:
```
Read: CLAUDE.md
Read: .claude/agent-alchemy.local.md (if it exists)
```

Load cross-plugin skills for language and project awareness:
```
Read: ${CLAUDE_PLUGIN_ROOT}/../core-tools/skills/language-patterns/SKILL.md
Read: ${CLAUDE_PLUGIN_ROOT}/../core-tools/skills/project-conventions/SKILL.md
```

Apply their guidance when writing tests and implementation code.

### Step 2: Load TDD Configuration

Read TDD settings from `.claude/agent-alchemy.local.md` if it exists:

```yaml
tdd:
  framework: auto                    # auto | pytest | jest | vitest
  coverage-threshold: 80             # Minimum coverage percentage (0-100)
  strictness: normal                 # strict | normal | relaxed
  test-review-threshold: 70          # Minimum test quality score (0-100)
  test-review-on-generate: false     # Run test-reviewer after generate-tests
```

Record the TDD strictness level (default: `normal` if not configured).
Record the framework override (default: `auto` -- use detection chain).
Record the coverage threshold (default: `80` -- clamp to 0-100 if out of range).

**Error handling:**
- If the settings file does not exist, use defaults for all settings.
- If the YAML frontmatter is malformed, use defaults and log a warning.
- If `tdd.framework` is set to an unrecognized value, fall back to auto-detection.

### Step 3: Detect Test Framework

Follow the framework detection chain to identify the project's test framework.

**Priority 1 -- Config Files (High Confidence):**

*Python:*
- `pyproject.toml` with `[tool.pytest.ini_options]` or `[tool.pytest]` -> pytest
- `setup.cfg` with `[tool:pytest]` -> pytest
- `pytest.ini` exists -> pytest
- `conftest.py` at project root or in `tests/` -> pytest

*TypeScript/JavaScript:*
- `vitest.config.*` exists -> Vitest (takes priority)
- `jest.config.*` exists -> Jest
- `package.json` with `vitest` in dependencies/devDependencies -> Vitest
- `package.json` with `jest` in dependencies/devDependencies -> Jest
- `package.json` with `"jest": {}` config section -> Jest

**Priority 2 -- Existing Test Files (Medium Confidence):**
- `test_*.py` or `*_test.py` -> pytest
- `*.test.ts` / `*.spec.ts` with `vitest` imports -> Vitest
- `*.test.ts` / `*.spec.ts` with `jest` imports or no explicit imports -> Jest

**Priority 3 -- Settings Fallback (Low Confidence):**
- Check `.claude/agent-alchemy.local.md` for `tdd.framework`

**Priority 4 -- User Prompt Fallback:**

If all detection methods fail:
```yaml
AskUserQuestion:
  questions:
    - header: "Test Framework"
      question: "No test framework was detected in this project. Which framework should be used?"
      options:
        - label: "pytest"
          description: "Python testing framework (recommended for Python projects)"
        - label: "Jest"
          description: "JavaScript/TypeScript testing framework"
        - label: "Vitest"
          description: "Vite-native testing framework (modern alternative to Jest)"
        - label: "Other"
          des