Claude Code Claude.MD - Based on https://github.com/badlogic/claude-commands/

gistfile1.txt

# TDD Todo Implementation Program
Structured Test-Driven Development (TDD) workflow to transform vague todos into implemented features using git worktrees and VS Code handoff. Supports test-first development, task isolation, resumption, and clean commit history.

## Workflow

**CRITICAL**
- You MUST follow workflow phases in order: INIT → SELECT → REFINE → TEST-FIRST → IMPLEMENT → COMMIT
- You MUST get user confirmation or input at each STOP
- You MUST iterate on refinement STOPs until user confirms
- You MUST NOT mention yourself in commit messages or add yourself as a committer
- You MUST consult with the user in case of unexpected errors
- You MUST commit all files you added/deleted/modified in the IMPLEMENT phase
- You MUST NOT create duplicate or versioned files - use git for version control
- You MUST delete files that are no longer needed and commit the deletions

## Context Management
- You MUST read `task.md` and `todos/project-description.md` in full before any action
- You MUST verify understanding by stating what the task accomplishes
- You MUST verify the task scope matches the original todo - if it seems like multiple features, STOP and ask
- You MUST show full error output, never summarize failures
- You MUST ask for clarification if codebase patterns are unclear

## State Transitions
Each phase completes when:
- **INIT**: Project description exists, no orphaned tasks, or task resumed
- **SELECT**: Todo selected, worktree created, task.md initialized
- **REFINE**: User approves test-driven plan
- **TEST-FIRST**: All planned tests written and failing
- **IMPLEMENT**: All tests pass, validation succeeds, user acceptance met
- **COMMIT**: PR created, task moved to done

## Definition of Done
A task is complete when:
- All planned tests pass
- Project validation (lint/test/build) succeeds
- User acceptance criteria verified
- No obsolete files remain
- Project description updated if structure changed
- Clean git history with descriptive commits

### INIT
1. Check for task resume: If `task.md` exists in current directory:
     - Read `task.md` and `todos/project-description.md` in full in parallel
     - Update `**Agent PID:** [Bash(echo $PPID)]` in task.md
     - If Status is "Refining": Continue to REFINE
     - If Status is "WritingTests": Continue to TEST-FIRST
     - If Status is "InProgress": Continue to IMPLEMENT
     - If Status is "AwaitingCommit": Continue to COMMIT
     - If Status is "Done": Task is complete, do nothing

2. Add `/todos/worktrees/` to .gitignore: `rg -q "/todos/worktrees/" .gitignore || echo -e "\n/todos/worktrees/" >> .gitignore`

3. Read `todos/project-description.md` in full
   - If missing:
      - STOP → "Please provide the editor command to open folders (e.g. 'code', 'cursor')"
      - Use parallel Task agents to analyze codebase:
         - Identify purpose, features
         - Identify languages, frameworks, tools (build, dependency management, test, etc.)
         - Identify components and architecture
         - Extract commands from build scripts (package.json, CMakeLists.txt, etc.)
         - Map structure, key files, and entry points
         - Identify test setup and how to create new tests
      - Present proposed project description using template:
         ```markdown
         # Project: [Name]
         [Concise description]

         ## Features
         [List of key features and purpose]

         ## Tech Stack
         [Languages, frameworks, build tools, etc.]

         ## Structure
         [Key directories, entry points, important files]

         ## Architecture
         [How components interact, main modules]

         ## Commands
         - Build: [command]
         - Test: [command]
         - Lint: [command]
         - Dev/Run: [command if applicable]

         ## Testing
         [How to create and run tests]
         [Preferred testing framework]
         [Test organization strategy]

         ## Editor
         - Open folder: [command]
         ```
      - STOP → "Any corrections needed? (y/n)"
      - Write confirmed content to `todos/project-description.md`

4. Check for orphaned tasks: `mkdir -p todos/worktrees todos/done && orphaned_count=0 && for d in todos/worktrees/*/task.md; do [ -f "$d" ] || continue; pid=$(grep "^**Agent PID:" "$d" | cut -d' ' -f3); [ -n "$pid" ] && ps -p "$pid" >/dev/null 2>&1 && continue; orphaned_count=$((orphaned_count + 1)); task_name=$(basename $(dirname "$d")); task_title=$(head -1 "$d" | sed 's/^# //'); echo "$orphaned_count. $task_name: $task_title"; done`
   - Present numbered list of orphaned tasks
   - STOP → "Resume orphaned task? (number or title/ignore)"
      - If resume:
         - Open editor at worktree: `[editor-command] /absolute/path/to/todos/worktrees/[task-name]/`
         - STOP → "Editor opened at worktree. Run `claude "/todo"` in worktree"
      - else go to SELECT

### SELECT
1. Read `todos/todos.md` in full
2. Present numbered list of todos with one line summaries
3. STOP → "Which todo would you like to work on? (enter number)"
4. Remove selected todo from `todos/todos.md` and commit: `git commit -am "Remove todo: [task-title]"`
5. Fetch and pull latest changes from remote:
   ```bash
   git fetch origin
   git pull origin $(git branch --show-current)
   ```
6. Create git worktree with branch: 
   ```bash
   git worktree add -b [task-title-slug] todos/worktrees/$(date +%Y-%m-%d-%H-%M-%S)-[task-title-slug]/ HEAD
   ```
7. Change CWD to worktree: `cd todos/worktrees/[timestamp]-[task-title-slug]/`
8. Pull latest changes in the new worktree:
   ```bash
   git pull origin $(git branch --show-current)
   ```
9. Initialize `task.md` from template in worktree root:
   ```markdown
   # [Task Title]
   **Workflow**: Follow TDD process in project root claude.md
   **Status:** Refining
   **Agent PID:** [Bash(echo $PPID)]

   ## Original Todo
   [raw todo text from todos/todos.md]

   ## Description
   [what we're building]

   ## Test-Driven Development Plan
   ### Test Cases
   - [ ] Test 1: [Specific test case description]
     - Input: 
     - Expected Output: 
     - Rationale: 

   ### Implementation Plan
   [how we are building it]
   - [ ] Code changes with location(s) if applicable (src/file.ts:45-93)
   - [ ] Refactor/cleanup steps
   - [ ] Performance considerations

   ## Notes
   [Implementation notes]
   - TDD Approach: 
     1. Write failing test
     2. Write minimal code to pass test
     3. Refactor
   ```
10. Commit and push initial task setup: `git add . && git commit -m "[task-title]: Initialization" && git push -u origin [task-title-slug]`

### REFINE
1. Research codebase with parallel Task agents:
   - Where in codebase changes are needed for this todo
   - What existing patterns/structures to follow
   - Which files need modification
   - What related features/code already exist
   - Analyze current test coverage and testing approach
2. Append analysis by agents verbatim to `analysis.md`
3. Draft description → STOP → "Use this description? (y/n)"
4. **Scope verification**: If the refined task involves multiple distinct features or significant architectural changes:
   - STOP → "This seems like multiple todos. Should we split this? (y/n)"
   - If yes, break into separate todos and return to SELECT
5. Draft test cases and implementation plan → STOP → "Use this test-driven plan? (y/n)"
   - Ensure test cases cover:
     - Happy path
     - Edge cases
     - Error handling
     - Performance considerations
   - **Note**: Approval of this plan includes approval of all test cases and implementation steps
5. Update `task.md` with fully refined content and set `**Status**: WritingTests`
6. Commit refined plan: `git add -A && git commit -m "[task-title]: Refined TDD plan"`
7. Open editor at worktree: `[editor-command] /absolute/path/to/todos/worktrees/[timestamp]-[task-title-slug]/`
8. STOP → "Editor opened at worktree. Run `claude "/todo"` in worktree to start test-first development"

### TEST-FIRST
1. For each test case in the approved plan:
   - Write a failing test
     - Ensure test is minimal and specific
     - Captures intended behavior
   - Commit the failing test:
     `git add -A && git commit -m "Test: [Test case description] (Red)"`
2. After all tests are written:
   - Run test suite
   - Confirm all new tests are failing
3. Set `**Status**: InProgress` in `task.md`

### IMPLEMENT
1. Execute the implementation plan test by test:
   - **During this process, if you discover unforeseen work is needed, you MUST:**
      - Pause and propose a new test case or implementation step
      - STOP → "Add this new test/implementation step to the plan? (y/n)"
      - Add new test case or implementation step to `task.md` before proceeding
   - For each test in the approved plan:
      - Write minimal code to make the test pass
      - Run tests to confirm
      - **Delete any files that are no longer needed** (obsolete code, temporary files, etc.)
      - Commit with "Green" status: 
        `git add -A && git commit -m "Implement: [Test case description] (Green)"`
      - Refactor if needed (as outlined in approved plan)
        - Run tests after each refactoring
        - **Delete any files made obsolete by refactoring**
        - Commit refactoring: 
          `git add -A && git commit -m "Refactor: [Brief description] (Green)"`
2. After all tests pass, run project validation (lint/test/build).
    - If validation fails:
      - Report full error(s)
      - Propose one or more new test cases or implementation steps to fix the issue
      - STOP → "Add these test cases/steps to the plan? (y/n)"
      - Add new test case(s) or implementation step(s) to `task.md`
      - Go to step 1 of `IMPLEMENT`.
3. Present final user acceptance test steps → STOP → "Do all tests and user acceptance criteria pass? (y/n)"
4. Check if project description needs updating:
   - If implementation changed structure, features, or commands:
      - Present proposed updates to `todos/project-description.md`
      - STOP → "Update project description as shown? (y/n)"
      - If yes, update `todos/project-description.md`
5. Set `**Status**: AwaitingCommit` in `task.md`
6. Commit final implementation: `git add -A && git commit -m "Complete TDD implementation"`

### COMMIT
1. Present summary of what was done
   - Highlight TDD process: 
     - Tests written
     - Minimal implementation
     - Refactoring steps
2. STOP → "Ready to create PR? (y/n)"
3. Set `**Status**: Done` in `task.md`
4. Move task and analysis to done with git tracking:
   - `git mv task.md todos/done/[timestamp]-[task-title-slug].md`
   - `git mv analysis.md todos/done/[timestamp]-[task-title-slug]-analysis.md`
5. Commit all changes: `git add -A && git commit -m "Complete TDD implementation"`
6. Push branch to remote and create pull request using GitHub CLI
7. Add continuous workflow todos to `todos/todos.md`:
   ```bash
   echo "- Refresh claude context and continue development workflow" >> todos/todos.md
   echo "- Add another todo to maintain continuous development cycle" >> todos/todos.md
   ```
8. STOP → "PR created. Delete the worktree? (y/n)"
   - If yes: `git -C "$(git rev-parse --show-toplevel)" worktree remove todos/worktrees/[timestamp]-[task-title-slug]`
   - Note: If Claude was spawned in the worktree, the working directory will become invalid after removal
9. STOP → "Ready to continue with next todo? Run `claude '/todo'` to restart workflow"

**Key TDD Principles
- **Red-Green-Refactor**: Write failing test → Make it pass → Improve code quality
- **Minimal Implementation**: Write only enough code to make tests pass
- **Test Coverage**: Cover happy path, edge cases, and error handling
- **Incremental Development**: One test case at a time
- **Clean Commits**: Each phase has clear commit messages with TDD status
- **No Duplication**: Use git for version control, not file versioning
- **Clean Codebase**: Delete obsolete files - don't leave unused code around