Implement Feature

Core Principles

1. Ambiguity means proceed strictly

When uncertain whether an approval todo applies, that uncertainty is the reason to apply it. The process exists precisely for situations where you're tempted to skip it.

2. Phase boundaries are strict

• IMPLEMENT = write code only
• VERIFY = test code only
• DOCUMENT = update docs only

3. Step-by-step prevents overwhelm

One logical unit per step (max 50 lines). Wait for confirmation between steps.

Development Team

• Groucho - Architectural advisor (Phase 2). Ensures new code aligns with existing patterns.
• Chico - Code reviewer (Phase 4). Verifies implementation meets requirements.
• Zeppo - Debugger and tester (Phase 5). Creates testing strategies.
• Harpo - Documentation specialist (Phase 6). Updates documentation.

TodoWrite Management

Use TodoWrite to track all workflow progress:

1. Initialize phase todos at skill start

   • Create todo for each of the 7 phases
   • Add approval todos between phases
   • Write initial state to TODO.md

2. Expand phases just-in-time

   • When entering a phase, add its specific subtasks
   • Use natural list ordering (no step numbers)
   • Insert new todos at appropriate position as work progresses

3. Exactly ONE todo in_progress at a time

   • Mark current task as in_progress
   • Complete it before starting next
   • This prevents skipping steps

4. Approval todos enforce gates

   • "Get user approval to proceed to Phase X"
   • "Get user approval to consult [Agent]"
   • Mark in_progress when asking
   • Complete only after user confirms

5. Persist state to TODO.md

   • Update TODO.md after completing each phase
   • Update TODO.md when agents add todos
   • Enables session resumption with exact state

6. Agent coordination via shared todo list

   All agents work on ONE shared todo list for complete visibility:

   • Agents create todos for their domain with [AgentName] prefix

     • Chico creates: "[Chico] Review error handling"
     • Zeppo creates: "[Zeppo] Run integration tests"
     • Harpo creates: "[Harpo] Update API documentation"

   • Agents mark their own todos in_progress/completed

     • When Chico adds review todos, Chico marks them completed
     • Main agent sees Chico's findings in shared list

   • Main agent creates and completes implementation todos

     • No prefix or [Main] for implementation work
     • Main agent fixes issues identified by other agents

   • Exactly ONE in_progress applies globally

     • Prevents main agent and subagents from conflicting work
     • Todo list shows who is working on what in real-time

Session Structure

docs/sessions/YYYYMMDD-HHMM-<slug>/
├── TODO.md           (Persistent todo state, updated throughout)
├── REQUIREMENTS.md   (Phase 1)
├── PLAN.md          (Phase 2)
├── IMPLEMENTATION.md (Phase 3)
├── TESTING.md       (Phase 5)
└── REFLECTION.md    (Phase 7)

Initialize: scripts/init_session.sh <feature-slug>

TODO.md persistence:

• Write current todo list state to TODO.md after each phase completes
• Enables session resumption with exact workflow state
• Format: Simple markdown checklist matching TodoWrite state
• Main agent and all subagents update same shared TODO.md

The 7 Phases

Phase 1: GATHER REQUIREMENTS

Understand what the user needs.

• Ask clarifying questions
• Confirm understanding
• Create session directory
• Write requirements to REQUIREMENTS.md
• Store documentation links for Groucho

Load references/phase-1-gather-requirements.md for details.

Phase 2: PLAN

Create implementation plan aligned with existing patterns.

• Get user approval to consult Groucho
• Provide: requirements, docs from Phase 1, constraints, preferences
• Present complete plan
• Write to PLAN.md
• Get user approval to proceed to Phase 3

Load references/phase-2-plan.md for details.

Phase 3: IMPLEMENT

Execute plan step-by-step.

• Create todo for each implementation step
• One step = one logical unit (max 50 lines)
• Complete each todo before starting next
• User can confirm or request changes between steps

Load references/phase-3-implement.md for details.

Phase 4: REVIEW

Verify implementation meets requirements.

• Get user approval to consult Chico
• Have Chico review all Phase 3 code
• Chico adds todos for issues found
• Fix issues one at a time
• Ask if Chico should re-review
• Don't claim completion until approved

Load references/phase-4-review.md for details.

Phase 5: VERIFY

Ensure implementation works correctly.

• Get user approval to consult Zeppo
• Get testing strategy from Zeppo
• Zeppo adds todos for test tasks
• Write verification plan to TESTING.md
• Execute tests
• Don't close until tests pass

Load references/phase-5-verify.md for details.

Phase 6: DOCUMENT

Update documentation.

• Get user approval to consult Harpo
• Have Harpo update relevant docs
• Harpo adds todos for documentation tasks
• Ensure docs reflect changes

Load references/phase-6-document.md for details.

Phase 7: REFLECT

Record learnings.

• Get user approval to proceed to Phase 7
• Create REFLECTION.md
• Document: task summary, user corrections, preferences, todos completed
• Ask about cleaning up session files

Load references/phase-7-reflect.md for details.

TodoWrite State Recovery

If todo state becomes out of sync:

1. Review current progress honestly
2. Update TodoWrite to reflect actual state
3. Continue from correct position
4. TodoWrite state is the source of truth

Resources

scripts/

• init_session.sh - Create session directory

references/

• phase-1-gather-requirements.md
• phase-2-plan.md
• phase-3-implement.md
• phase-4-review.md
• phase-5-verify.md
• phase-6-document.md
• phase-7-reflect.md
• session-resumption.md

assets/

• Templates for session phase files

Load phase references only when entering that phase.

Starting a Task

If user provides session slug to resume:

1. Read docs/sessions/<session-slug>/TODO.md to reconstruct workflow state
2. Load TodoWrite with state from TODO.md
3. Identify first incomplete todo
4. Mark that todo as in_progress
5. Continue from that point in workflow

If user requests new feature implementation:

1. Do not attempt to solve problems yet
2. Acknowledge you'll use the 7-phase workflow
3. List all 7 phases
4. Initialize TodoWrite with phase structure:
   • Create todo for each of the 7 phases
   • Add approval todos between phases
   • Mark "Phase 1: Gather requirements" as in_progress
   • Write initial state to TODO.md
5. Begin Phase 1