/todo-worktree

Todo Implementation Program

Structured workflow to transform vague todos into implemented features using git worktrees and VS Code handoff. Supports task isolation, resumption, and clean commit history.

Workflow

**CRITICAL**

• You MUST follow workflow phases in order: INIT → SELECT → REFINE → 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 commiter
• You MUST consult with the user in case of unexpected errors
• You MUST not forget to commits files you added/deleted/modified in the IMPLEMENT phase

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 "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 below

         # 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]

         ## 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. Create git worktree with branch: `git worktree add -b [task-title-slug] todos/worktrees/$(date +%Y-%m-%d-%H-%M-%S)-[task-title-slug]/ HEAD` 6. Change CWD to worktree: `cd todos/worktrees/[timestamp]-[task-title-slug]/` 7. Initialize `task.md` from template in worktree root:

   # [Task Title]
   **Status:** Refining
   **Agent PID:** [Bash(echo $PPID)]

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

   ## Description
   [what we're building]
   
   *Read [analysis.md](./analysis.md) in full for detailed codebase research and context*

   ## Implementation Plan
   [how we are building it]
   - [ ] Code change with location(s) if applicable (src/file.ts:45-93)
   - [ ] Automated test: ...
   - [ ] User test: ...

   ## Notes
   [Implementation notes]

8. 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

2. Append analysis by agents verbatim to `analysis.md` 3. Draft description → STOP → "Use this description? (y/n)" 4. Draft implementation plan → STOP → "Use this implementation plan? (y/n)" 5. Update `task.md` with fully refined content and set `**Status**: InProgress` 6. Commit refined plan: `git add -A && git commit -m "[task-title]: Refined 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 implementation"

IMPLEMENT

1. Execute the implementation plan checkbox by checkbox:

• **During this process, if you discover unforeseen work is needed, you MUST:**
• Pause and propose a new checkbox for the plan
• STOP → "Add this new checkbox to the plan? (y/n)"
• Add new checkbox to `task.md` before proceeding
• For the current checkbox:
• Make code changes
• Summarize changes
• STOP → "Approve these changes? (y/n)"
• Mark checkbox complete in `task.md`
• Commit progress, including added/modified/deleted files: `git ad