Tdd Cycle

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):

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:

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 

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 

---

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:

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:

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"
          description: "A different framework (tests may need manual adjustment)"
      multiSelect: false

Step 4: Load Test Pattern References

Read framework-specific patterns and templates:

Read: ${CLAUDE_PLUGIN_ROOT}/skills/generate-tests/references/test-patterns.md
Read: ${CLAUDE_PLUGIN_ROOT}/skills/generate-tests/references/framework-templates.md

Step 5: Explore Codebase

1. Use Glob to find files related to the feature scope
2. Use Grep to locate relevant symbols, functions, and patterns
3. Read existing test files to understand test conventions (naming, structure, fixtures, assertion style)
4. Identify where new test files and implementation files should be placed
5. Read 2-3 representative existing test files if available to match project test style

Step 6: Snapshot Existing Test State

Run the existing test suite and record the baseline:

• Total tests, pass count, fail count
• List any pre-existing failures (these are not your responsibility to fix)
• This baseline is used in Phases 4 (RED) and 5 (GREEN) to separate new results from existing state

Python (pytest):

pytest --tb=short -q 2>&1 || true

TypeScript (Jest/Vitest):

npx jest --no-coverage 2>&1 || true
npx vitest run --reporter=verbose 2>&1 || true

Record the baseline: {total} tests, {passed} passed, {failed} failed

---

Phase 3: Plan

Goal: Present the TDD plan to the user and get a single confirmation before running autonomously.

Build the TDD Plan

Based on the parsed input and codebase exploration, construct a plan covering:

1. Feature scope: What behavior will be implemented
2. Tests to write: List of test cases with descriptive names, organized by category:

• Functional tests (core behavior)
• Edge case tests (boundary conditions)
• Error handling tests (failure scenarios)

1. Test file location: Where test files will be created
2. Implementation approach: What source files will be created or modified
3. Coverage target: Expected coverage percentage
4. Strictness level: RED phase enforcement level (from settings)

Present Plan

Present the plan as a formatted summary:

## TDD Plan: {feature name}

**Framework**: {pytest | Jest | Vitest}
**Strictness**: {strict | normal | relaxed}
**Coverage Target**: {percentage}%

### Tests to Write

**Functional:**
- test_{behavior_1}: {description}
- test_{behavior_2}: {description}

**Edge Cases:**
- test_{edge_case_1}: {description}

**Error Handling:**
- test_{error_1}: {description}

### Test Files
- {test_file_path_1}

### Implementation Files
- {source_file_path_1} (create / modify)

### Approach
{Brief description of the implementation strategy}

Confirm Plan

Use AskUserQuestion to get confirmation:

AskUserQuestion:
  questions:
    - header: "TDD Plan Confirmation"
      question: "Review the TDD plan above. Ready to proceed with the RED-GREEN-REFACTOR cycle?"
      options:
        - label: "Proceed"
          description: "Run the full TDD cycle autonomously — no further interruptions"
        - label: "Modify plan"
          description: "Adjust the test plan before starting"
        - label: "Cancel"
          description: "Cancel this TDD workflow"
      multiSelect: false

If "Modify plan": Ask what changes are needed via AskUserQuestion, update the plan, and present again for confirmation.

If "Cancel": Stop the workflow and inform the user.

If "Proceed": Continue to Phase 4. From this point forward, the workflow runs autonomously without user interaction.

---

Phase 4: RED Phase

Goal: Write failing tests from requirements, then run the test suite to confirm all new tests fail.

CRITICAL: After plan confirmation, this phase and all subsequent phases run autonomously. Do NOT prompt the user for input.

Load TDD Workflow Reference

Read the TDD workflow reference for phase definitions and verification rules:

Read: ${CLAUDE_PLUGIN_ROOT}/skills/tdd-cycle/references/tdd-workflow.md

Step 1: Write Failing Tests

Write the test files planned in Phase 3:

1. Convert requirements to test cases: Each acceptance criterion becomes one or more test assertions
2. Follow project test conventions: Match existing test file naming, directory structure, assertion style, and fixture patterns
3. Write behavior-driven tests: Test what the code should do, not how it does it. Focus on inputs, outputs, and observable side effects
4. Use the AAA pattern: Arrange (setup), Act (execute), Assert (verify)
5. Include edge case tests: Boundary conditions, null/empty inputs, error scenarios
6. Use descriptive test names:

• pytest: test___
• Jest/Vitest: describe("", () => { it("should when ", ...) })

IMPORTANT: Do NOT write any implementation code during this step. Only write test files.

Step 2: Run Tests -- Confirm RED

Run the full test suite:

Python:

pytest --tb=short -q 2>&1

TypeScript:

npx jest --no-coverage 2>&1
npx vitest run --reporter=verbose 2>&1

Step 3: Verify RED State

Compare results against the Phase 2 baseline to isolate new test results.

Expected outcome: ALL new tests fail with appropriate errors (ImportError, ModuleNotFoundError, AttributeError, AssertionError, etc.)

Apply strictness level:

| Strictness | If new tests pass | Action | |------------|-------------------|--------| | strict | ANY new test passes | Abort workflow. Report which tests passed and likely cause | | normal | Some new tests pass | Log warning. Investigate: is implementation already present? Are tests too weak? Continue after investigation | | relaxed | Any outcome | Log results and continue regardless |

Edge Case: Tests Pass Immediately

If some or all new tests pass before implementation:

1. Check if implementation already exists: Search for existing code that satisfies the tests
2. If implementation exists: Log a warning to the user. If ALL tests pass, skip to Phase 6 (REFACTOR). If partial, proceed to Phase 5 (GREEN) for remaining tests
3. If tests are too weak: Strengthen the tests to properly verify new behavior, then re-run RED
4. Log the finding for the Phase 7 report

---

Phase 5: GREEN Phase

Goal: Implement the minimal code necessary to make all failing tests pass.

Step 1: Implement Minimally

Write only the code needed to make the current failing tests pass:

1. Follow existing patterns: Match the codebase's coding style, error handling approach, and module organization
2. Work incrementally: Address one test (or small group of related tests) at a time when possible
3. No test modifications: Do NOT change the tests written in Phase 4. If a test is genuinely wrong, document the issue explicitly
4. Handle errors at boundaries: Add error handling that the tests verify, but do not add speculative error handling
5. Follow project conventions: Read CLAUDE.md rules, match naming, match file organization

Implementation Order

Follow dependency-aware order:

1. Data layer (models, schemas, types)
2. Service layer (business logic, utilities)
3. API/Interface layer (endpoints, handlers, UI components)
4. Configuration (env vars, config files)

Step 2: Run Tests -- Confirm GREEN

Run the full test suite:

pytest --tb=short -q 2>&1          # Python
npx jest --no-coverage 2>&1        # Jest
npx vitest run --reporter=verbose 2>&1  # Vitest

Step 3: Verify GREEN State

Expected outcome: ALL tests pass (new tests + existing baseline tests).

• ALL new tests MUST pass: Every test from Phase 4 should now pass
• NO regressions: Compare against the Phase 2 baseline. No previously-passing test should now fail

If Tests Fail

1. Identify the failing test and the root cause
2. Fix the IMPLEMENTATION (not the tests) to make it pass
3. Re-run the full suite
4. Repeat until all tests pass (up to 5 iterations)
5. If after 5 iterations tests still fail, report FAIL

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sequenzia
• Source: sequenzia/agent-alchemy
• License: MIT
• Homepage: https://sequenzia.github.io/agent-alchemy

Install and usage instructions live in the source repository linked above.