Spec-Driven Test-Driven Development

Workflow Router

Does a codebase already exist?
  |
  NO --> GREENFIELD (new project from scratch)
  |       Phases: Clarify -> Specify -> Test Plan -> TDD -> Verify
  |
  YES --> What type of change?
           |
           +-> Bug report / error / regression
           |     --> BUGFIX workflow
           |     Phases: Explore -> Bugfix Spec -> TDD -> Verify
           |
           +-> Add new capability not in codebase
           |     --> Does test infrastructure exist?
           |          |
           |          YES --> ENHANCEMENT workflow
           |          |     Phases: Explore -> Clarify -> Specify (delta) -> Test Plan -> TDD -> Verify
           |          |
           |          NO  --> ENHANCEMENT (NO TESTS) workflow
           |                Phases: Explore -> Clarify -> Specify (delta) -> Bootstrap Tests -> Test Plan -> TDD -> Verify
           |
           +-> Change behavior without adding capability
           |     --> Does test infrastructure exist?
           |          |
           |          YES --> REFACTOR workflow
           |          |     Phases: Explore -> Clarify -> Specify (delta) -> Test Plan -> TDD -> Verify
           |          |
           |          NO  --> REFACTOR (NO TESTS) workflow
           |                Phases: Explore -> Clarify -> Specify (delta) -> Bootstrap Tests -> Test Plan -> TDD -> Verify
           |
           +-> Simple, well-understood change (one-sentence diff)
                 --> DIRECT (skip this skill)

• Test files (

  *test*

  ,

  *spec*

  ,

  __tests__/

  )
• Test runner config (jest.config., vitest.config., pytest.ini, conftest.py, .mocharc.*)
• Test script in manifest (

  "test"

  script in package.json, test target in Makefile)
• CI config that runs tests

Phase 0: Explore Existing Codebase (Brownfield Only)

What to discover

1. Project structure: Directory layout, where source and tests live
2. Tech stack: Framework, language, versions, build system, package manager
3. Architectural patterns: MVC, layered, event-driven, microservices, etc.
4. Naming conventions: File naming, function naming, variable casing
5. Existing patterns: Find the closest analog to the requested change — how is similar functionality already implemented?
6. Data models: Key entities, relationships, schemas
7. Test infrastructure: Test framework, test runner command, fixture patterns, approximate coverage, where test files live
8. Existing spec artifacts: Check for prior requirements.md, design.md, tasks.md, CLAUDE.md, or similar documentation
9. Affected area: Which files and modules will this change touch?

How to explore

• Read the project's CLAUDE.md or README first (if they exist)
• Use glob/grep to find relevant source files and test files
• Read 2-3 existing files in the affected area to absorb patterns
• If prior spec files exist, read them to understand accumulated requirements

Test infrastructure assessment

"test"

Output: Codebase Context Summary

Stack: [framework, language, test runner]
Patterns: [architecture, naming, file organization]
Affected area: [files/modules this change touches]
Existing tests: [relevant test files, approximate count, runner command]
  OR: No test infrastructure found
Test state: [tests exist | partial infra | no tests]
Prior specs: [any existing requirements.md/design.md or none]
Closest analog: [existing feature most similar to requested change]

Phase 1: Clarify Requirements

Greenfield

Brownfield (tests exist)

• What should the NEW behavior be? (the codebase shows current behavior)
• Where does new behavior differ from existing patterns?
• What existing behavior must NOT change?
• Are there constraints the existing architecture imposes?

Brownfield (no tests)

• Test framework preference: Does the user have a preferred test framework? If not, recommend one based on the stack (see Bootstrap Tests phase).
• Test scope: Should tests cover ONLY the new/changed code, or also establish baseline coverage for existing code in the affected area?
• Test location: Co-located with source (

  src/foo.test.ts

  ) or separate directory (

  tests/

  )? Infer from project conventions if possible.

• Multiple valid interpretations producing different implementations
• Missing I/O specifications, pre/post conditions, or data formats
• Unspecified error handling, edge cases, or boundary conditions
• Unclear performance, security, or environmental constraints
• Change touches shared/critical code paths

• Request is well-constrained with one obvious implementation
• Ambiguity is purely cosmetic (naming, formatting)
• Clarification loop has reached 3 rounds (proceed with stated assumptions)

• Ask up to 3 focused questions per round
• Each question should target a decision that changes the implementation
• State the default assumption alongside each question
• After each round, summarize resolved items and remaining unknowns

Phase 2: Write Specification

EARS notation (all workflows)

Requirement ID namespacing (brownfield)

• REQ-E-nnn

  for enhancement requirements

• REQ-R-nnn

  for refactor requirements

• REQ-BUG-nnn

  for bugfix requirements

Unchanged Behavior section (critical for brownfield)

- INV-001: WHEN [condition] THE SYSTEM SHALL CONTINUE TO [existing behavior]

Greenfield: requirements.md + design.md

Enhancement: requirements.md + design-delta.md

• Modified components (what exists → what changes)
• New components (what's added)
• Integration points (how new connects to existing)
• Files to modify vs. files to create

## Test Infrastructure (New)
- **Framework:** [chosen framework and rationale]
- **Runner command:** [command to run tests]
- **Config file:** [path to test config]
- **Test location:** [co-located | separate directory]
- **Naming convention:** [pattern, e.g., *.test.ts, test_*.py]

Bugfix: bugfix.md

1. Current Behavior (defect): WHEN [x] THEN the system [incorrect behavior]
2. Expected Behavior (correct): WHEN [x] THEN the system SHALL [correct behavior]
3. Unchanged Behavior (regression): WHEN [y] THE SYSTEM SHALL CONTINUE TO [existing behavior]

Phase 3: Bootstrap Test Infrastructure (No-Tests Workflows Only)

Step 1: Select test framework

Step 2: Install and configure

1. Add the framework as a dev dependency:

   npm install --save-dev vitest          # Node/TS
   pip install pytest                     # Python
   # Go and Rust have built-in testing

2. Create test config (if the framework needs one):

   • vitest.config.ts

     ,

     jest.config.ts

     ,

     pytest.ini

     , etc.
   • Match the project's existing config patterns (TypeScript for TS projects, YAML if project uses YAML configs, etc.)
3. Add test runner script to the project manifest:
   json

   // package.json
   { "scripts": { "test": "vitest run" } }

   toml

   # pyproject.toml
   [tool.pytest.ini_options]
   testpaths = ["tests"]

4. Create test directory (if using separate directory convention):

   mkdir tests/          # or __tests__/ or test/

5. Verify the framework works by writing a trivial smoke test:
   typescript

   // tests/smoke.test.ts
   import { describe, it, expect } from 'vitest'
   
   describe('test infrastructure', () => {
     it('works', () => {
       expect(1 + 1).toBe(2)
     })
   })

   Run it. If it passes, infrastructure is ready. Delete or keep the smoke test as appropriate.

Step 3: Establish test conventions

src/module/foo.ts

src/module/foo.test.ts

tests/module/foo.test.ts

it('createsUserWithEmail')

test_creates_user_with_email

Step 4: Write characterization tests (critical)

What to characterize

1. Public functions/methods you'll call or modify: test their current inputs → outputs
2. API endpoints you'll change: test their current request → response
3. Critical code paths through the module: test the happy path and major error paths
4. Integration points between the module and its callers: test that callers get what they expect

How many characterization tests

• Enhancement: Characterize the specific functions/endpoints you'll modify or call. Not the entire codebase — just the affected surface.
• Refactor: More extensive. Characterize ALL externally observable behavior of the code being refactored. This is your safety net.
• Bugfix: Characterize the behavior around the bug. The reproduction test IS a characterization test (it documents the current broken behavior).

Characterization test naming

test_CHAR_[function]_[scenario]_[current_behavior]

def test_CHAR_create_user_with_valid_data_returns_user_object():
def test_CHAR_create_user_with_duplicate_email_raises_conflict():
def test_CHAR_get_user_nonexistent_returns_none():

Run characterization tests

Deliverable: Test infrastructure ready

• Framework installed and configured
• Runner command works
• Test conventions documented
• Characterization tests pass against unchanged code
• You can now proceed to Phase 4 (Test Plan) with confidence

Phase 4: Derive Test Plan

tasks.md

Brownfield: Discover existing tests first

1. Find existing test files in the affected area (glob for

   *test*

   ,

   *spec*

   )
2. Read relevant existing tests to understand patterns (framework, assertions, fixtures, naming conventions)
3. Check for existing coverage of the behaviors you're about to change
4. Match existing patterns in all new tests (same framework, same style, same file location conventions)

Brownfield (no tests): Use characterization tests as baseline

1. Your characterization tests ARE the existing tests. They serve the same role as pre-existing tests in the standard brownfield workflow.
2. Match the conventions you established in Phase 3 for all new tests.
3. Do not add more characterization tests at this point — Phase 3 covered the affected area. Focus on test derivation from the spec.
4. Map invariants to characterization tests: Each INV-* should correspond to at least one characterization test that already passes.

Test derivation rules

1. Each EARS requirement → at least one acceptance test (Given/When/Then)
2. Each data model/interface → unit tests for validation, transformation, edge cases
3. Each integration point → integration test using real services where possible
4. Each invariant → regression test confirming unchanged behavior
   • If tests already exist: existing tests cover this
   • If no tests existed: characterization tests from Phase 3 cover this
5. Identify properties (invariants for all inputs) → property-based tests

Traceability

| Req ID    | Test Case IDs     | Status      |
|-----------|-------------------|-------------|
| REQ-E-001 | TC-E-001, TC-E-002| Not Started |
| INV-001   | TC-REG-001        | Not Started |

• Every NEW requirement must have >= 1 test
• Every INVARIANT must have >= 1 regression test
• Existing tests from prior iterations are NOT orphans — only flag tests from the current iteration that don't map to a requirement
• The traceability matrix covers only the current iteration's scope

• Characterization tests (CHAR-) map to INV- invariants
• Include them in the matrix with their CHAR prefix:

| Req ID    | Test Case IDs        | Status      |
|-----------|----------------------|-------------|
| REQ-E-001 | TC-E-001, TC-E-002   | Not Started |
| INV-001   | CHAR-create-user-001 | Passing (baseline) |
| INV-002   | CHAR-get-user-001    | Passing (baseline) |

tasks.md

• Maps to one or more requirements
• Has clear acceptance criteria
• Follows dependency order
• Includes "Write tests" as the FIRST subtask (TDD)
• Brownfield: Specifies which files are MODIFIED vs. CREATED

## Task 0: Bootstrap test infrastructure
- Status: [ ] Not Started
- Requirements: (infrastructure — no REQ mapping)
- Subtasks:
  1. Install [framework], create config
  2. Add test runner script
  3. Write characterization tests for affected area
  4. Verify all characterization tests pass
- Acceptance: `[test command]` runs and all characterization tests pass

Phase 5: TDD Implementation Loop

For each task:

1. RED    - Write failing test(s) for the task's requirements
2. RUN    - Execute test, confirm it FAILS (if it passes, test is wrong)
3. GREEN  - Write MINIMAL code to make the test pass
4. RUN    - Execute ALL tests (new + existing), confirm ALL pass
5. REFACTOR - Clean up, ensure no test breakage
6. COMMIT - Mark task complete in tasks.md

Running tests (brownfield, tests exist)

• Inner loop: Run only the new/affected tests during Red-Green iterations (for speed)
• Task boundary: Run the FULL test suite after completing each task (for regression safety)
• Final verification: Run full suite + linters + type checks at the end

Running tests (brownfield, no tests — after bootstrap)

• Inner loop: Run new tests + characterization tests during Red-Green iterations. The characterization tests are your regression guardrail.
• Task boundary: Run ALL tests (characterization + new) after each task.
• Final verification: Run all tests + linters + type checks at the end.

Rules

• Never write implementation before its test.
• Never alter the spec to satisfy a test. Spec-derived tests are authoritative.
• Minimal code only. Add nothing beyond what makes the current test pass.
• All tests green before moving to next task.
• Use real dependencies where feasible. Mocks only for external services outside your control.
• Decompose classes by method dependency. Generate in dependency order, test each method individually.
• Bounded repair. 3 fix attempts max, then reassess or ask user.

Brownfield-specific rules (all brownfield workflows)

• Match existing patterns. New code must follow the conventions discovered in Phase 0 (naming, file structure, import style, error handling).
• Refactor only what you wrote. Do NOT refactor existing code unless the task explicitly requires it. Existing code is assumed correct until proven otherwise.
• Read before calling. Before calling existing functions, read their actual signatures. Do not assume existing interfaces — verify them.
• If an existing test breaks, your new code caused a regression. Fix your new code first (existing passing tests are authoritative). Only modify an existing test if the spec explicitly changes that behavior.
• If a characterization test breaks (no-tests workflow), the same rule applies: your new code caused a regression. Fix your new code. The characterization test documents real behavior that something depends on.

Hallucination prevention

1. Verify external APIs/libraries exist and check current interfaces
2. Chain-of-thought: reason step-by-step before coding
3. Run static analysis after generation
4. Use execution traceback (not just re-reading) to fix failures
5. Brownfield: Read existing code before calling it; verify signatures

Phase 6: Verification

Checklist

• Spec compliance: Every new requirement has at least one passing test
• All tests pass: Full test suite green (new AND existing)
• Traceability complete: Updated matrix with final status
• No untested new requirements: Every REQ-* from this iteration is covered
• Unchanged behaviors verified: All INV-* regression tests pass
• Static analysis clean: No linter errors, type errors, security warnings
• Pattern compliance (brownfield): New code follows existing conventions

Additional no-tests verification

• Test infrastructure works:

  [test command]

  runs cleanly from project root
• Characterization tests still pass: All CHAR-* tests green, confirming no behavioral regressions in the affected area
• Test conventions documented: Future developers can find and follow the test patterns (in design-delta.md or equivalent)
• Runner script exists: Test command is in manifest (package.json scripts, Makefile, etc.) — not just a manual invocation

Deliverables

1. requirements.md

   — Full specification

2. design.md

   — Full technical design

3. tasks.md

   — Task list with traceability matrix
4. Test suite — All passing
5. Implementation code

1. requirements.md

   — New/changed requirements only (or appended to existing)

2. design-delta.md

   — What changed in the design

3. tasks.md

   — Task list with traceability matrix for this iteration
4. New/modified tests
5. Implementation changes
6. Change summary: Files modified, files created, behaviors added/changed

1. requirements.md

   — New/changed requirements only (or appended to existing)

2. design-delta.md

   — What changed in the design, INCLUDING test infrastructure decisions (framework, conventions, directory structure)

3. tasks.md

   — Task list with traceability matrix (includes CHAR-* mappings)
4. Test infrastructure: config, runner script, directory structure
5. Characterization tests for affected area
6. New tests derived from spec
7. Implementation changes
8. Change summary: Files modified, files created, behaviors added/changed, test infrastructure established

1. bugfix.md

   — Bug analysis with Current/Expected/Unchanged
2. Tests: reproduction, fix validation, regression
3. Fix implementation
4. Change summary

Failure Recovery

Test fails
  |
  +-> Is it a NEW test that fails?
  |     +-> Code bug: fix implementation
  |     +-> Test wrong: does it match spec?
  |          +-> Yes: fix code (spec is authoritative)
  |          +-> No: fix test (or revisit spec with user)
  |
  +-> Is it an EXISTING test that fails? (standard brownfield)
  |     +-> Your new code caused a regression
  |     +-> Fix your new code (existing tests are authoritative)
  |     +-> Do NOT modify the existing test unless the spec
  |         explicitly changes that behavior
  |     +-> If the existing test seems wrong, confirm with user
  |         before changing it
  |
  +-> Is it a CHARACTERIZATION test that fails? (no-tests brownfield)
  |     +-> Your new code caused a behavioral regression
  |     +-> Fix your new code (characterization tests document real behavior)
  |     +-> Do NOT modify the characterization test unless the spec
  |         explicitly changes that behavior (listed in Modified Behavior
  |         with Was/Now)
  |     +-> If the characterization test documents behavior the spec
  |         INTENDS to change, update the test to match the new spec
  |
  +-> Test infrastructure won't set up? (no-tests bootstrap)
        +-> Check framework compatibility with project's Node/Python/etc. version
        +-> Check for conflicting config (e.g., module type mismatches)
        +-> Try the next framework in the recommendation table
        +-> If stuck after 2 frameworks, ask user for guidance

Reference Files

• Spec templates: See references/spec-template.md for all templates: Feature, Enhancement, Refactor, Bugfix, and Codebase Context
• Test plan guide: See references/test-plan.md for test derivation, existing test discovery, characterization tests, traceability, and Given/When/Then
• Edge case catalog: See references/edge-cases.md for edge case categories to check during specification