feat(05-tdd): TDD integration with detection, annotation, and execution flow
- Add references/tdd.md with detection heuristics, red-green-refactor cycle - Add tdd_annotation section to plan-format.md with task structure - Expand plan-phase.md with TDD detection and annotation guidance - Add tdd_execution section to execute-phase.md with commit patterns - TDD-aware task routing in execute step 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
@@ -243,6 +243,43 @@ Use for: Technology selection, architecture decisions, design choices, feature p
|
||||
See `./checkpoints.md` for comprehensive checkpoint guidance.
|
||||
</task_types>
|
||||
|
||||
<tdd_annotation>
|
||||
Tasks can include `tdd="true"` attribute when TDD improves quality:
|
||||
|
||||
**Structure:**
|
||||
```xml
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task N: [Name]</name>
|
||||
<files>[paths]</files>
|
||||
<test-first>[What test to write first - the failing assertion]</test-first>
|
||||
<action>[Implementation to make test pass]</action>
|
||||
<verify>[Tests pass, behavior works]</verify>
|
||||
<done>[Criteria]</done>
|
||||
</task>
|
||||
```
|
||||
|
||||
**When to add tdd="true":**
|
||||
- Business logic with defined inputs/outputs
|
||||
- API endpoints with request/response contracts
|
||||
- Data transformations and parsing
|
||||
- Validation rules
|
||||
- Algorithms with testable behavior
|
||||
|
||||
**When NOT to add tdd="true":**
|
||||
- UI layout and styling
|
||||
- Configuration changes
|
||||
- Glue code connecting existing components
|
||||
- One-off scripts
|
||||
|
||||
**Execution flow (when tdd="true"):**
|
||||
1. Claude writes failing test from `<test-first>`
|
||||
2. Claude implements from `<action>` until test passes
|
||||
3. Claude refactors if needed (tests still pass)
|
||||
4. Claude commits atomic change
|
||||
|
||||
See `./tdd.md` for comprehensive TDD guidance.
|
||||
</tdd_annotation>
|
||||
|
||||
<context_references>
|
||||
Use @file references to load context for the prompt:
|
||||
|
||||
@@ -347,6 +384,26 @@ Claude: "How? What type? What library? Where?"
|
||||
Claude can implement this immediately.
|
||||
</just_right>
|
||||
|
||||
<tdd_example>
|
||||
TDD task example:
|
||||
|
||||
```xml
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: Create email validation utility</name>
|
||||
<files>src/lib/validation.ts, src/lib/validation.test.ts</files>
|
||||
<test-first>
|
||||
Test: isValidEmail returns true for valid emails, false for invalid
|
||||
Cases: "user@example.com" → true, "invalid" → false, "" → false, "user@" → false
|
||||
</test-first>
|
||||
<action>Implement isValidEmail using regex pattern. Handle edge cases: empty string, missing @, missing domain.</action>
|
||||
<verify>npm test -- validation.test.ts passes all cases</verify>
|
||||
<done>Email validation works for all edge cases, tests document behavior</done>
|
||||
</task>
|
||||
```
|
||||
|
||||
Claude executes this with RED → GREEN → REFACTOR cycle, producing atomic commits.
|
||||
</tdd_example>
|
||||
|
||||
<too_detailed>
|
||||
Writing the actual code in the plan. Trust Claude to implement from clear instructions.
|
||||
</too_detailed>
|
||||
|
||||
168
get-shit-done/references/tdd.md
Normal file
168
get-shit-done/references/tdd.md
Normal file
@@ -0,0 +1,168 @@
|
||||
<overview>
|
||||
TDD is about design quality, not coverage metrics. The red-green-refactor cycle forces you to think about behavior before implementation, producing cleaner interfaces and more testable code.
|
||||
|
||||
**Principle:** If you can describe the behavior as `expect(fn(input)).toBe(output)` before writing `fn`, TDD improves the result.
|
||||
</overview>
|
||||
|
||||
<detection>
|
||||
## When TDD Improves Quality
|
||||
|
||||
**TDD candidates (add `tdd="true"`, include `<test-first>`):**
|
||||
- Business logic with defined inputs/outputs
|
||||
- API endpoints with request/response contracts
|
||||
- Data transformations, parsing, formatting
|
||||
- Validation rules and constraints
|
||||
- Algorithms with testable behavior
|
||||
- State machines and workflows
|
||||
- Utility functions with clear specifications
|
||||
|
||||
**Skip TDD (standard `type="auto"`):**
|
||||
- UI layout, styling, visual components
|
||||
- Configuration changes
|
||||
- Glue code connecting existing components
|
||||
- One-off scripts and migrations
|
||||
- Simple CRUD with no business logic
|
||||
- Exploratory prototyping
|
||||
|
||||
**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
|
||||
→ Yes: TDD will help
|
||||
→ No: Implement first, add tests after if needed
|
||||
</detection>
|
||||
|
||||
<execution_flow>
|
||||
## Red-Green-Refactor Cycle
|
||||
|
||||
**RED - Write failing test:**
|
||||
1. Create test file following project conventions
|
||||
2. Write test describing expected behavior (from `<test-first>` element)
|
||||
3. Run test - it MUST fail
|
||||
4. If test passes: feature exists or test is wrong. Investigate.
|
||||
5. Commit: `test: add failing test for [feature]`
|
||||
|
||||
**GREEN - Implement to pass:**
|
||||
1. Write minimal code to make test pass
|
||||
2. No cleverness, no optimization - just make it work
|
||||
3. Run test - it MUST pass
|
||||
4. Commit: `feat: implement [feature]`
|
||||
|
||||
**REFACTOR (if needed):**
|
||||
1. Clean up implementation if obvious improvements exist
|
||||
2. Run tests - MUST still pass
|
||||
3. Only commit if changes made: `refactor: clean up [feature]`
|
||||
|
||||
**Atomic commits:** Each TDD task produces 2-3 commits following this pattern.
|
||||
</execution_flow>
|
||||
|
||||
<test_quality>
|
||||
## Good Tests vs Bad Tests
|
||||
|
||||
**Test behavior, not implementation:**
|
||||
- Good: "returns formatted date string"
|
||||
- Bad: "calls formatDate helper with correct params"
|
||||
- Tests should survive refactors
|
||||
|
||||
**One concept per test:**
|
||||
- Good: Separate tests for valid input, empty input, malformed input
|
||||
- Bad: Single test checking all edge cases with multiple assertions
|
||||
|
||||
**Descriptive names:**
|
||||
- Good: "should reject empty email", "returns null for invalid ID"
|
||||
- Bad: "test1", "handles error", "works correctly"
|
||||
|
||||
**No implementation details:**
|
||||
- Good: Test public API, observable behavior
|
||||
- Bad: Mock internals, test private methods, assert on internal state
|
||||
</test_quality>
|
||||
|
||||
<framework_setup>
|
||||
## Test Framework Setup (If None Exists)
|
||||
|
||||
When a TDD task exists but no test framework is configured:
|
||||
|
||||
**1. Detect project type:**
|
||||
```bash
|
||||
# JavaScript/TypeScript
|
||||
if [ -f package.json ]; then echo "node"; fi
|
||||
|
||||
# Python
|
||||
if [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo "python"; fi
|
||||
|
||||
# Go
|
||||
if [ -f go.mod ]; then echo "go"; fi
|
||||
|
||||
# Rust
|
||||
if [ -f Cargo.toml ]; then echo "rust"; fi
|
||||
```
|
||||
|
||||
**2. Install minimal framework:**
|
||||
| Project | Framework | Install |
|
||||
|---------|-----------|---------|
|
||||
| Node.js | Jest | `npm install -D jest @types/jest ts-jest` |
|
||||
| Node.js (Vite) | Vitest | `npm install -D vitest` |
|
||||
| Python | pytest | `pip install pytest` |
|
||||
| Go | testing | Built-in |
|
||||
| Rust | cargo test | Built-in |
|
||||
|
||||
**3. Create config if needed:**
|
||||
- Jest: `jest.config.js` with ts-jest preset
|
||||
- Vitest: `vitest.config.ts` with test globals
|
||||
- pytest: `pytest.ini` or `pyproject.toml` section
|
||||
|
||||
**4. Verify setup:**
|
||||
```bash
|
||||
# Run empty test suite - should pass with 0 tests
|
||||
npm test # Node
|
||||
pytest # Python
|
||||
go test ./... # Go
|
||||
cargo test # Rust
|
||||
```
|
||||
|
||||
**5. Create first test file:**
|
||||
Follow project conventions for test location:
|
||||
- `*.test.ts` / `*.spec.ts` next to source
|
||||
- `__tests__/` directory
|
||||
- `tests/` directory at root
|
||||
</framework_setup>
|
||||
|
||||
<error_handling>
|
||||
## Error Handling
|
||||
|
||||
**Test doesn't fail in RED phase:**
|
||||
- Feature may already exist - investigate
|
||||
- Test may be wrong (not testing what you think)
|
||||
- Fix before proceeding
|
||||
|
||||
**Test doesn't pass in GREEN phase:**
|
||||
- Debug implementation
|
||||
- Don't skip to next task
|
||||
- Keep iterating until green
|
||||
|
||||
**Tests fail in REFACTOR phase:**
|
||||
- Undo refactor
|
||||
- Commit was premature
|
||||
- Refactor in smaller steps
|
||||
|
||||
**Unrelated tests break:**
|
||||
- Stop and investigate
|
||||
- May indicate coupling issue
|
||||
- Fix before proceeding
|
||||
</error_handling>
|
||||
|
||||
<commit_pattern>
|
||||
## Commit Pattern for TDD Tasks
|
||||
|
||||
Each TDD task produces atomic commits:
|
||||
|
||||
```
|
||||
test: add failing test for email validation
|
||||
|
||||
feat: implement email validation
|
||||
|
||||
refactor: extract regex to constant (optional)
|
||||
```
|
||||
|
||||
This pattern:
|
||||
- Creates clean git history
|
||||
- Each commit is independently revertable
|
||||
- Shows TDD discipline in commit log
|
||||
</commit_pattern>
|
||||
@@ -439,6 +439,10 @@ Execute each task in the prompt. **Deviations are normal** - handle them automat
|
||||
|
||||
**If `type="auto"`:**
|
||||
|
||||
**Before executing:** Check if task has `tdd="true"` attribute:
|
||||
- If yes: Follow TDD execution flow (see `<tdd_execution>`) - RED → GREEN → REFACTOR cycle with multiple atomic commits
|
||||
- If no: Standard implementation with single commit
|
||||
|
||||
- Work toward task completion
|
||||
- **If CLI/API returns authentication error:** Handle as authentication gate (see below)
|
||||
- **When you discover additional work not in plan:** Apply deviation rules (see below) automatically
|
||||
@@ -810,6 +814,54 @@ Logged to .planning/ISSUES.md for future consideration:
|
||||
|
||||
</deviation_documentation>
|
||||
|
||||
<tdd_execution>
|
||||
## TDD Task Execution
|
||||
|
||||
When executing a task with `tdd="true"` attribute:
|
||||
|
||||
**1. Check test infrastructure:**
|
||||
If no test framework configured:
|
||||
- Detect project type from package.json/requirements.txt/etc.
|
||||
- Install minimal test framework (Jest, pytest, Go testing, etc.)
|
||||
- Create test config file
|
||||
- Verify: run empty test suite
|
||||
|
||||
**2. RED - Write failing test:**
|
||||
- Read `<test-first>` element for test specification
|
||||
- Create test file if doesn't exist (follow project conventions)
|
||||
- Write test(s) that describe expected behavior
|
||||
- Run tests - MUST fail (if passes, test is wrong or feature exists)
|
||||
- Commit: "test: add failing test for [feature]"
|
||||
|
||||
**3. GREEN - Implement to pass:**
|
||||
- Read `<action>` element for implementation guidance
|
||||
- Write minimal code to make test pass
|
||||
- Run tests - MUST pass
|
||||
- Commit: "feat: implement [feature]"
|
||||
|
||||
**4. REFACTOR (if needed):**
|
||||
- Clean up code if obvious improvements
|
||||
- Run tests - MUST still pass
|
||||
- Commit only if changes made: "refactor: clean up [feature]"
|
||||
|
||||
**Commit pattern for TDD tasks:**
|
||||
Each TDD task produces 2-3 atomic commits:
|
||||
1. `test: add failing test for X`
|
||||
2. `feat: implement X`
|
||||
3. `refactor: clean up X` (optional)
|
||||
|
||||
**Error handling:**
|
||||
- If test doesn't fail in RED phase: Test is wrong or feature already exists. Investigate before proceeding.
|
||||
- If test doesn't pass in GREEN phase: Debug implementation, don't skip to next task.
|
||||
- If tests fail in REFACTOR phase: Undo refactor, commit was premature.
|
||||
|
||||
**Verification:**
|
||||
After TDD task completion, ensure:
|
||||
- All tests pass
|
||||
- Test coverage for the new behavior exists
|
||||
- No unrelated tests broken
|
||||
</tdd_execution>
|
||||
|
||||
<step name="checkpoint_protocol">
|
||||
When encountering `type="checkpoint:*"`:
|
||||
|
||||
|
||||
@@ -19,8 +19,9 @@ Decimal phases enable urgent work insertion without renumbering:
|
||||
2. ~/.claude/get-shit-done/references/plan-format.md
|
||||
3. ~/.claude/get-shit-done/references/scope-estimation.md
|
||||
4. ~/.claude/get-shit-done/references/checkpoints.md
|
||||
5. .planning/ROADMAP.md
|
||||
6. .planning/PROJECT.md
|
||||
5. ~/.claude/get-shit-done/references/tdd.md
|
||||
6. .planning/ROADMAP.md
|
||||
7. .planning/PROJECT.md
|
||||
|
||||
**Load domain expertise from ROADMAP:**
|
||||
- Parse ROADMAP.md's `## Domain Expertise` section for paths
|
||||
@@ -187,7 +188,33 @@ Decompose phase into tasks. Each task needs:
|
||||
- **Verify**: How to prove it worked
|
||||
- **Done**: Acceptance criteria
|
||||
|
||||
**TDD fit:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`? Yes (business logic, APIs, validation) → test-first. No (UI layout, config, glue code) → standard implementation.
|
||||
**TDD detection:** For each task, evaluate TDD fit:
|
||||
|
||||
TDD candidates (add `tdd="true"` to task, include `<test-first>` element):
|
||||
- Business logic with defined inputs/outputs
|
||||
- API endpoints with request/response contracts
|
||||
- Data transformations, parsing, formatting
|
||||
- Validation rules and constraints
|
||||
- Algorithms with testable behavior
|
||||
- State machines and workflows
|
||||
|
||||
Skip TDD (standard `type="auto"` task):
|
||||
- UI layout, styling, visual components
|
||||
- Configuration changes
|
||||
- Glue code connecting existing components
|
||||
- One-off scripts and migrations
|
||||
- Simple CRUD with no business logic
|
||||
|
||||
**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
|
||||
→ Yes: Add `tdd="true"`, include `<test-first>` describing the failing test
|
||||
→ No: Standard task, no TDD annotation
|
||||
|
||||
**Test framework:** If project has no test setup and TDD tasks exist, add a setup task first:
|
||||
- Detect project type (package.json → Jest, requirements.txt → pytest, etc.)
|
||||
- Add minimal test configuration
|
||||
- Create example test file to verify setup
|
||||
|
||||
See `~/.claude/get-shit-done/references/tdd.md` for complete TDD guidance.
|
||||
|
||||
**Checkpoints:** Visual/functional verification → checkpoint:human-verify. Implementation choices → checkpoint:decision. Manual action (email, 2FA) → checkpoint:human-action (rare).
|
||||
|
||||
@@ -292,6 +319,21 @@ Phase plan created: .planning/phases/XX-name/{phase}-01-PLAN.md
|
||||
- "Set up authentication" / "Make it secure" / "Handle edge cases"
|
||||
|
||||
If you can't specify Files + Action + Verify + Done, the task is too vague.
|
||||
|
||||
**Good TDD task:**
|
||||
```xml
|
||||
<task type="auto" tdd="true">
|
||||
<name>Create price calculator with discount rules</name>
|
||||
<files>src/lib/pricing.ts, src/lib/pricing.test.ts</files>
|
||||
<test-first>
|
||||
Test: calculatePrice applies discounts correctly
|
||||
Cases: base 100 + 10% off → 90, base 100 + 20% off + $5 coupon → 75
|
||||
</test-first>
|
||||
<action>Implement calculatePrice(base, discountPercent, couponAmount). Apply percentage first, then flat amount.</action>
|
||||
<verify>npm test -- pricing.test.ts passes</verify>
|
||||
<done>Price calculation handles all discount combinations correctly</done>
|
||||
</task>
|
||||
```
|
||||
</task_quality>
|
||||
|
||||
<anti_patterns>
|
||||
|
||||
Reference in New Issue
Block a user