Initial commit

skills/implement-feature/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: implement-feature
+description: This skill should be used when implementing non-trivial software features that require planning, review, testing, and documentation. It orchestrates a team of specialized development agents (Groucho, Chico, Zeppo, Harpo) through a rigorous 7-phase workflow to ensure features are properly architected, implemented, reviewed, verified, and documented. Use this skill for multi-file features, new functionality, or any work where quality and thoroughness matter. Do not use for trivial single-line fixes or quick experimental prototypes.
+---
+
+# 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

skills/implement-feature/assets/IMPLEMENTATION.md

@@ -0,0 +1,32 @@
+# Implementation Summary: [Feature Name]
+
+## Completed Steps
+
+**Step 1:** [Description]
+- Files modified: [list]
+- Key changes: [summary]
+
+**Step 2:** [Description]
+- Files modified: [list]
+- Key changes: [summary]
+
+## Files Changed
+
+### New Files
+- `path/to/new/file.ext` - [Purpose and key contents]
+
+### Modified Files
+- `path/to/modified/file.ext` - [What was changed and why]
+
+## Code Comments Added
+
+- [ ] Code comments added (if requested)
+- [ ] No comments needed
+
+## Deviations from Plan
+
+[Any changes made during implementation that differed from the original plan, and why]
+
+## Ready for Review
+
+Implementation complete. All planned steps executed according to PLAN.md.

skills/implement-feature/assets/PLAN.md

@@ -0,0 +1,40 @@
+# Implementation Plan: [Feature Name]
+
+## Approach
+
+[High-level description of how this will be implemented, including architectural decisions]
+
+## Files to Create/Modify
+
+**NEW:**
+- `path/to/new/file.ext` - [Purpose]
+
+**MODIFY:**
+- `path/to/existing/file.ext` - [What changes will be made]
+
+## Key Architectural Decisions
+
+**[Decision Name]**
+- [Rationale for this decision]
+- [Alternatives considered]
+
+## Implementation Steps
+
+**Step 1:** [Brief description]
+- [Details of what this step involves]
+
+**Step 2:** [Brief description]
+- [Details of what this step involves]
+
+**Step 3:** [Brief description]
+- [Details of what this step involves]
+
+## Dependencies
+
+- [External libraries or tools needed]
+- [Existing codebase patterns to follow]
+
+## Risks & Mitigations
+
+- **Risk**: [Potential issue]
+  - **Mitigation**: [How to address it]

skills/implement-feature/assets/REFLECTION.md

@@ -0,0 +1,51 @@
+# Session Reflection: [Feature Name]
+
+**Date**: [YYYY-MM-DD HH:MM Timezone]
+**Session**: `YYYYMMDD-HHMM-slug`
+
+## Task Summary
+
+[Brief description of what was accomplished in this session]
+
+## User Corrections
+
+### Correction 1: [What user corrected]
+- **Context**: [What you did wrong]
+- **User feedback**: [What user said]
+- **Gap type**: [coverage|effectiveness|clarity|error]
+- **Gap analysis**: [What instruction was missing or ineffective]
+
+### Correction 2: [What user corrected]
+- **Context**: [What you did wrong]
+- **User feedback**: [What user said]
+- **Gap type**: [coverage|effectiveness|clarity|error]
+- **Gap analysis**: [What instruction was missing or ineffective]
+
+## Project Preferences Revealed
+
+- [Preference 1]: [Description]
+- [Preference 2]: [Description]
+
+## Gates Triggered
+
+- [ ] Groucho consultation (Phase 2)
+- [ ] User plan confirmation (Phase 2)
+- [ ] Step-by-step confirmations (Phase 3)
+- [ ] Chico review permission (Phase 4)
+- [ ] Zeppo testing strategy (Phase 5)
+- [ ] Harpo documentation (Phase 6)
+- [ ] Reflection recording (Phase 7)
+
+## Workflow Observations
+
+**What worked well:**
+- [Observation 1]
+- [Observation 2]
+
+**What needs improvement:**
+- [Issue 1 and potential solution]
+- [Issue 2 and potential solution]
+
+## Notes
+
+[Any additional observations or context for future reference]

skills/implement-feature/assets/REQUIREMENTS.md

@@ -0,0 +1,32 @@
+# Requirements: [Feature Name]
+
+## Summary
+
+[1-2 sentence description of what needs to be built]
+
+## Detailed Requirements
+
+1. [Specific functionality needed]
+2. [Another requirement]
+3. [Edge cases to handle]
+
+## Constraints
+
+- [Technical constraints]
+- [Performance requirements]
+- [Compatibility requirements]
+
+## User Preferences
+
+- [Preferred approach or technology]
+- [Code style or patterns to follow]
+
+## Success Criteria
+
+- [ ] [Measurable outcome 1]
+- [ ] [Measurable outcome 2]
+- [ ] [Measurable outcome 3]
+
+## Documentation Links
+
+[Links to API docs, references, or related documentation fetched during requirements gathering]

skills/implement-feature/assets/TESTING.md

@@ -0,0 +1,51 @@
+# Testing Plan: [Feature Name]
+
+## Test Strategy
+
+[Overview of testing approach from Zeppo]
+
+## Automated Tests
+
+### Test 1: [Test Name]
+- **Purpose**: [What this test validates]
+- **Method**: [How to run it]
+- **Expected Result**: [What should happen]
+
+### Test 2: [Test Name]
+- **Purpose**: [What this test validates]
+- **Method**: [How to run it]
+- **Expected Result**: [What should happen]
+
+## Manual Verification Steps
+
+1. [Step-by-step manual test]
+   - Expected: [outcome]
+
+2. [Another manual test]
+   - Expected: [outcome]
+
+## Edge Cases to Test
+
+- [Edge case 1]: [Expected behavior]
+- [Edge case 2]: [Expected behavior]
+
+## Performance Considerations
+
+[Any performance testing needed]
+
+## Test Results
+
+### Automated Tests
+- [ ] All automated tests pass
+
+### Manual Verification
+- [ ] Manual test 1 completed
+- [ ] Manual test 2 completed
+
+### Edge Cases
+- [ ] Edge case 1 verified
+- [ ] Edge case 2 verified
+
+## Issues Found
+
+[Any issues discovered during testing and how they were addressed]

skills/implement-feature/references/phase-1-gather-requirements.md

@@ -0,0 +1,58 @@
+# Phase 1: GATHER REQUIREMENTS
+
+## Objective
+
+Understand what the user needs before jumping to solutions.
+
+## Why This Exists
+
+Without clear requirements, you can't build the right thing. This prevents building the wrong feature, missing requirements, and having no success criteria.
+
+## Protocol
+
+1. **Ask clarifying questions** (2-4 at a time)
+   - What is the user trying to achieve?
+   - What specific functionality is needed?
+   - Are there constraints or preferences?
+   - What does success look like?
+
+2. **Confirm understanding**
+   - Summarize what you've understood
+   - Ask: "Is there anything else?" and "Are there edge cases?"
+
+3. **Create session directory**
+   ```bash
+   scripts/init_session.sh <feature-slug>
+   ```
+   Use lowercase-with-hyphens (e.g., `user-authentication`)
+
+4. **Read template and create REQUIREMENTS.md**
+   - Read `assets/REQUIREMENTS.md` as a guide
+   - Write complete requirements to `docs/sessions/YYYYMMDD-HHMM-<slug>/REQUIREMENTS.md`
+   - Include: Summary, detailed requirements, constraints, user preferences, success criteria, documentation links (if fetched)
+
+5. **Store documentation links**
+   If you fetch API docs or references, include them in REQUIREMENTS.md. These MUST be passed to Groucho in Phase 2.
+
+6. **Complete Phase 1 todos**
+   - Mark "Create session directory and REQUIREMENTS.md" as completed
+   - Mark "Phase 1: Gather requirements" as completed
+   - Mark "Get user approval to consult Groucho" as in_progress
+   - Ask user for approval to proceed to Phase 2
+
+## Critical Anti-Patterns
+
+**❌ Assuming requirements are obvious**
+
+Don't assume the approach. User says "add authentication" - ask about method, features, constraints first.
+
+**❌ Incomplete requirements**
+
+"Add CSV export" is too vague. Include specific functionality, constraints, success criteria, edge cases.
+
+## Key Takeaways
+
+- Focus on needs, not solutions
+- Ask questions incrementally
+- Document everything
+- Store documentation links for Groucho

skills/implement-feature/references/phase-2-plan.md

@@ -0,0 +1,69 @@
+# Phase 2: PLAN
+
+## Objective
+
+Create implementation plan aligned with existing codebase patterns.
+
+## Why This Exists
+
+Groucho prevents: reinventing solutions, inconsistent code structure, architectural decisions in isolation, missing existing patterns.
+
+## Protocol
+
+1. **Get user approval to consult Groucho**
+   - Mark "Get user approval to consult Groucho" as in_progress
+   - Ask: "May I consult Groucho? I'll provide requirements, docs, constraints, and preferences."
+   - Wait for user confirmation
+   - Mark as completed only after user confirms
+
+2. **Consult Groucho with ALL context**
+   - Complete requirements
+   - **Documentation links from Phase 1** - If you fetched ANY docs, you MUST pass them to Groucho
+   - Technical constraints
+   - User preferences
+
+3. **Present complete plan to user**
+   - High-level approach
+   - Files to create/modify
+   - Key architectural decisions
+   - Dependencies
+   - Implementation steps
+
+4. **Validate phase boundaries - THINK HARD**
+   - Does the plan include testing steps? → Move to Phase 5
+   - Does the plan include documentation? → Move to Phase 6
+   - IMPLEMENT = code only (not testing, not docs)
+   - VERIFY = testing only
+   - DOCUMENT = docs only
+
+   Correct any violations before presenting to user.
+
+5. **Read template and create PLAN.md**
+   - Read `assets/PLAN.md` as a guide
+   - Write complete plan to `docs/sessions/YYYYMMDD-HHMM-<slug>/PLAN.md`
+
+6. **Get user approval to proceed to Phase 3**
+   - Mark "Get user approval to proceed to Phase 3" as in_progress
+   - Ask: "Please confirm this plan before I proceed to implementation."
+   - Wait for user confirmation
+   - Do NOT proceed until user explicitly confirms
+   - Mark as completed only after user confirms
+   - Mark "Phase 2: Plan implementation" as completed
+   - Expand Phase 3 with implementation step todos
+
+## Critical Anti-Patterns
+
+**❌ "Empty directory means no patterns"**
+
+Groucho checks the ENTIRE codebase, not just one directory. Project-wide patterns (testing, error handling, logging) still apply.
+
+**❌ "I fetched docs but didn't pass to Groucho"**
+
+If you fetched ANY documentation in Phase 1, you MUST pass those links to Groucho. He determines relevance, not you.
+
+## Key Takeaways
+
+- Always consult Groucho (even for "simple" tasks)
+- Provide complete context (requirements, docs, constraints, preferences)
+- Validate phase boundaries (IMPLEMENT = code only)
+- Wait for user confirmation before proceeding

skills/implement-feature/references/phase-3-implement.md

@@ -0,0 +1,82 @@
+# Phase 3: IMPLEMENT
+
+## Objective
+
+Execute plan step-by-step with reviewable increments.
+
+## Why This Exists
+
+Step-by-step prevents: context overload, no course correction opportunity, overwhelming changes, "while I'm here" scope creep.
+
+## Step Boundaries
+
+- One step = one logical unit (function, model, endpoint, file section, config change)
+- Maximum 50 lines per step
+- No "while I'm here" additions
+- Break down plan before starting
+
+## Step Execution Protocol with TodoWrite
+
+**MANDATORY for every step:**
+
+1. **Create step todos** from the plan
+   - Add todos for each implementation step
+   - Use descriptive names (no step numbers)
+   - Keep max 50 lines per step
+2. **Mark current step in_progress**
+3. **Perform ONLY that step's work** (no extras, no unrelated fixes)
+4. **Mark step completed**
+5. **User can confirm or request changes** before next step
+
+Never write entire files in one response unless explicitly instructed.
+
+## Granularity Examples
+
+**❌ BAD - Too coarse:**
+```
+Step 1: Implement the authentication system
+```
+
+**✅ GOOD - Right granularity:**
+```
+Step 1: Create User model with email/password fields (~25 lines)
+Step 2: Add password hashing function using bcrypt (~30 lines)
+Step 3: Add password comparison function (~20 lines)
+Step 4: Create login endpoint that validates credentials (~35 lines)
+Step 5: Add JWT token generation function (~40 lines)
+```
+
+## After All Steps Complete
+
+1. **Read template and create IMPLEMENTATION.md**
+   - Read `assets/IMPLEMENTATION.md` as a guide
+   - Write implementation summary to `docs/sessions/YYYYMMDD-HHMM-<slug>/IMPLEMENTATION.md`
+   - Include: Completed steps, files changed, code comments status, deviations from plan
+
+2. **Offer to add code comments** (if appropriate)
+
+3. **Do NOT run tests (Phase 5) or update docs (Phase 6)**
+
+4. **Complete Phase 3**
+   - Mark "Phase 3: Implement" as completed
+   - Mark "Get user approval to consult Chico" as in_progress
+   - Ask: "May I consult Chico to review this implementation?"
+   - Wait for user confirmation
+
+## Critical Anti-Patterns
+
+**❌ "Batching multiple steps"**
+
+One step at a time. ONLY batch if user explicitly instructs: "Do all remaining steps without asking."
+
+**❌ "While I'm here" additions**
+
+Stay focused on current step. If you notice something else, propose it as a separate step.
+
+## Key Takeaways
+
+- One step = one logical unit (max 50 lines)
+- Always mark in_progress, perform, mark completed, wait for confirmation
+- No "while I'm here" additions
+- Break down plan before starting
+- Phase boundaries: code only, no testing or docs

skills/implement-feature/references/phase-4-review.md

@@ -0,0 +1,71 @@
+# Phase 4: REVIEW
+
+## Objective
+
+Verify implementation meets requirements and identify issues before testing.
+
+## Why This Exists
+
+Chico prevents: shipping bugs, missing requirements, code quality issues, testing broken code.
+
+## Protocol
+
+1. **Get user approval to consult Chico**
+   - Mark "Get user approval to consult Chico" as in_progress
+   - Ask: "May I consult Chico to review the implementation?"
+   - Wait for user confirmation
+   - Mark as completed only after user confirms
+
+2. **Consult Chico**
+   - Provide all code from Phase 3
+   - Reference to REQUIREMENTS.md
+   - Any specific concerns
+
+3. **Receive Chico's feedback**
+   - Requirements verification
+   - Bug identification
+   - Code quality improvements
+   - Edge cases
+   - **Chico adds todos for issues found** with [Chico] prefix
+
+   Trust his fresh perspective.
+
+4. **Fix issues one at a time** (do NOT batch)
+   ```
+   Issue 1: [description]
+   [Fix Issue 1]
+   "Issue 1 fixed. Proceed to Issue 2?"
+   [WAIT]
+   ```
+
+5. **If fixes were made: Ask about re-review**
+   ```
+   "Should I have Chico review the fixes?"
+   ```
+   Often warranted for multiple significant fixes or critical logic changes.
+
+6. **Do not claim completion until approved**
+
+7. **Complete Phase 4**
+   - Mark "Phase 4: Review with Chico" as completed
+   - Mark "Get user approval to consult Zeppo" as in_progress
+   - Ask: "May I consult Zeppo for testing strategy?"
+   - Wait for user confirmation
+
+## Critical Anti-Patterns
+
+**❌ "Skipping Chico because I'm confident"**
+
+Review is MANDATORY, not optional. Fresh eyes catch issues you miss. Chico verifies against requirements, not just bugs.
+
+**❌ "Testing before review"**
+
+Always REVIEW (Phase 4) before VERIFY (Phase 5). Don't waste time testing code that needs fixes.
+
+## Key Takeaways
+
+- Chico review is mandatory
+- Review before testing (always Phase 4 before Phase 5)
+- Fix issues one at a time with confirmation
+- Trust Chico's feedback
+- Re-review when needed

skills/implement-feature/references/phase-5-verify.md

@@ -0,0 +1,68 @@
+# Phase 5: VERIFY
+
+## Objective
+
+Ensure implementation works correctly through testing.
+
+## Why This Exists
+
+Zeppo prevents: shipping untested code, missing edge cases, undiscovered bugs, no verification strategy.
+
+## Protocol
+
+1. **Get user approval to consult Zeppo**
+   - Mark "Get user approval to consult Zeppo" as in_progress
+   - Ask: "May I consult Zeppo to create a testing strategy?"
+   - Wait for user confirmation
+   - Mark as completed only after user confirms
+
+2. **Consult Zeppo**
+   - Provide complete implementation from Phase 3
+   - Reference to REQUIREMENTS.md
+   - Any specific concerns about functionality
+
+3. **Receive Zeppo's testing strategy**
+   - Automated tests to write/run
+   - Manual verification steps
+   - Edge cases to test
+   - Performance considerations
+   - **Zeppo adds todos for test tasks** with [Zeppo] prefix
+
+4. **Read template and create TESTING.md**
+   - Read `assets/TESTING.md` as a guide
+   - Write verification plan to `docs/sessions/YYYYMMDD-HHMM-<slug>/TESTING.md`
+   - Include: Test strategy, automated tests, manual verification steps, edge cases, test results
+
+5. **Execute tests**
+   - Run automated tests
+   - Perform manual verification
+   - Check edge cases
+   - Validate against requirements
+
+6. **Do not close task until tests pass**
+   - All tests must pass
+   - Address issues discovered
+   - Ask if user wants to update TESTING.md with results
+
+7. **Complete Phase 5**
+   - Mark "Phase 5: Verify with Zeppo" as completed
+   - Mark "Get user approval to consult Harpo" as in_progress
+   - Ask: "May I consult Harpo for documentation?"
+   - Wait for user confirmation
+
+## Critical Anti-Patterns
+
+**❌ "Skipping Zeppo because tests seem obvious"**
+
+Even "obvious" testing benefits from systematic approach. Zeppo identifies edge cases you miss.
+
+**❌ "Proceeding with failing tests"**
+
+All tests must pass before moving to documentation. Don't leave broken functionality.
+
+## Key Takeaways
+
+- Zeppo creates comprehensive test strategy
+- Write test plan to TESTING.md
+- Execute all tests (automated and manual)
+- Don't proceed until all tests pass

skills/implement-feature/references/phase-6-document.md

@@ -0,0 +1,60 @@
+# Phase 6: DOCUMENT
+
+## Objective
+
+Update documentation to reflect the new feature.
+
+## Why This Exists
+
+Harpo prevents: undocumented features, stale docs, users unable to use new functionality, lost knowledge.
+
+## Protocol
+
+1. **Get user approval to consult Harpo**
+   - Mark "Get user approval to consult Harpo" as in_progress
+   - Ask: "May I consult Harpo to update documentation?"
+   - Wait for user confirmation
+   - Mark as completed only after user confirms
+
+2. **Consult Harpo**
+   - Provide complete implementation details
+   - Describe what was built
+   - Identify target audience (end users, developers, etc.)
+   - Specify documentation standards to follow
+
+3. **Harpo updates relevant documentation**
+   - README files with new features
+   - API documentation for new endpoints
+   - User guides for new functionality
+   - Code comments and docstrings
+   - CHANGELOG entries
+   - Architecture Decision Records (if needed)
+   - **Harpo adds todos for documentation tasks** with [Harpo] prefix
+
+4. **Ensure docs reflect changes accurately**
+   - Verify documentation matches implementation
+   - Check examples are correct
+   - Ensure completeness
+
+5. **Complete Phase 6**
+   - Mark "Phase 6: Document with Harpo" as completed
+   - Mark "Get user approval to proceed to Phase 7" as in_progress
+   - Ask: "May I proceed to Phase 7: Reflection?"
+   - Wait for user confirmation
+
+## Critical Anti-Patterns
+
+**❌ "Documenting while coding"**
+
+Documentation belongs to Phase 6, not Phase 3. Implementation may change during review/testing.
+
+**❌ "Skipping documentation because feature is self-explanatory"**
+
+No feature is self-explanatory. Users need docs. Future you needs docs.
+
+## Key Takeaways
+
+- Harpo handles all documentation
+- Update README, API docs, user guides as needed
+- Documentation must match implementation
+- Don't skip this phase

skills/implement-feature/references/phase-7-reflect.md

@@ -0,0 +1,56 @@
+# Phase 7: REFLECT
+
+## Objective
+
+Record learnings for continuous improvement.
+
+## Why This Exists
+
+Session reflections identify instruction gaps, reveal project preferences, and enable workflow improvement over time.
+
+## Protocol
+
+1. **Get user approval to proceed to Phase 7**
+   - Mark "Get user approval to proceed to Phase 7" as in_progress
+   - Ask: "Would you like me to record learnings from this session?"
+   - Wait for user confirmation
+   - Mark as completed only after user confirms
+
+2. **If approved, read template and create REFLECTION.md**
+   - Read `assets/REFLECTION.md` as a guide
+   - Write to `docs/sessions/YYYYMMDD-HHMM-<slug>/REFLECTION.md`
+   - Use user's current timezone for timestamp
+
+3. **Required sections**
+   - **Task Summary**: Brief description of what was accomplished
+   - **User Corrections**: Each time user corrected you, explain reasoning and identify gap
+   - **Project Preferences Revealed**: Patterns or preferences discovered
+   - **Todos Completed**: Which todos were completed during this session
+   - **Workflow Observations**: What worked well or needs improvement
+
+4. **Gap types for User Corrections**
+   - **coverage**: No instruction existed for this situation
+   - **effectiveness**: Instruction exists but failed to prevent issue
+   - **clarity**: Instruction was misunderstood or ambiguous
+   - **error**: No gap, you simply made an error
+
+5. **Complete Phase 7**
+   - Mark "Phase 7: Reflect on implementation" as completed
+   - Session complete
+
+## Critical Anti-Patterns
+
+**❌ "Skipping reflection because everything went smoothly"**
+
+Even smooth sessions reveal preferences and patterns worth documenting.
+
+**❌ "Not recording user corrections"**
+
+User corrections are the most valuable data for improving instructions.
+
+## Key Takeaways
+
+- Always suggest recording learnings
+- Document user corrections with gap analysis
+- Capture project preferences
+- Ask about file cleanup

skills/implement-feature/references/session-resumption.md

@@ -0,0 +1,131 @@
+# Session Resumption
+
+## Objective
+
+Resume interrupted sessions by detecting completed phases and loading context.
+
+## Why This Exists
+
+Users may need to pause and resume feature work. File existence indicates phase completion, enabling precise resumption point detection.
+
+## Resumption Detection Protocol
+
+### 1. Detect resumption request
+
+User provides session slug without "implement" verb:
+- ✓ "Continue session-resumption"
+- ✓ "Resume auth-flow"
+- ✗ "Implement user-login" (fresh start)
+
+### 2. Locate matching sessions
+
+```bash
+find docs/sessions -type d -name "*-<slug>" | sort -r
+```
+
+Multiple matches → Ask user which to use (show timestamps).
+
+### 3. Map file existence to completed phases
+
+Check session directory for phase files:
+
+| File exists | Phase completed | Resume at |
+|-------------|-----------------|-----------|
+| None | Nothing | Phase 1 (fresh start) |
+| REQUIREMENTS.md | Phase 1 | Phase 2 (PLAN) |
+| PLAN.md | Phase 2 | Phase 3 (IMPLEMENT) |
+| IMPLEMENTATION.md | Phase 3 | Infer: Phase 4 or 5 |
+| TESTING.md | Phase 5 | Infer: Phase 6 or 7 |
+| REFLECTION.md | Phase 7 | Session complete |
+
+**Progressive disclosure**: Files created when entering each phase, not at initialization.
+
+**Phase 4 and 6 inference**: These phases (REVIEW, DOCUMENT) don't create files. When ambiguous:
+- If IMPLEMENTATION.md exists but TESTING.md doesn't → Ask user: "Resume at Phase 4 (REVIEW) or Phase 5 (VERIFY)?"
+- If TESTING.md exists but REFLECTION.md doesn't → Ask user: "Resume at Phase 6 (DOCUMENT) or Phase 7 (REFLECT)?"
+
+### 4. Load context from existing files
+
+Read ALL existing phase files in session directory:
+- REQUIREMENTS.md → requirements, constraints, success criteria
+- PLAN.md → implementation approach, files to modify, architectural decisions
+- IMPLEMENTATION.md → what was implemented, how it works
+- TESTING.md → test strategy, verification results
+- REFLECTION.md → learnings, corrections
+
+### 5. Present resumption summary to user
+
+**Example 1: Clear resumption point**
+```
+"Found session: docs/sessions/20251020-2342-session-resumption
+
+Completed phases:
+✓ Phase 1: GATHER REQUIREMENTS
+✓ Phase 2: PLAN
+
+Context loaded:
+- Requirements: Session resumption with progressive disclosure
+- Plan: File-based phase detection using existence markers
+
+Next: Phase 3 (IMPLEMENT)
+
+Proceed with Phase 3?"
+```
+
+**Example 2: Ambiguous resumption point (requires user clarification)**
+```
+"Found session: docs/sessions/20251020-2342-add-metrics
+
+Completed phases:
+✓ Phase 1: GATHER REQUIREMENTS
+✓ Phase 2: PLAN
+✓ Phase 3: IMPLEMENT
+
+Context loaded:
+- Requirements: Add usage metrics tracking and export
+- Plan: Create metrics collection system with CSV/JSON export
+- Implementation: Metrics service and export handlers created
+
+IMPLEMENTATION.md exists but TESTING.md does not.
+
+Resume at Phase 4 (REVIEW) or Phase 5 (VERIFY)?"
+```
+
+### 6. Resume at next phase
+
+Load appropriate phase reference and continue workflow.
+
+## Multiple Session Handling
+
+When multiple sessions match slug:
+
+```
+"Multiple sessions found for 'session-resumption':
+
+1. docs/sessions/20251020-2342-session-resumption (Oct 20, 11:42pm)
+   - Last phase: IMPLEMENT
+
+2. docs/sessions/20251019-1056-session-resumption (Oct 19, 10:56am)
+   - Last phase: PLAN
+
+Which session should I resume?"
+```
+
+Wait for user selection.
+
+## Critical Anti-Patterns
+
+**❌ "Resuming without reading context"**
+
+Always read ALL existing phase files. Context is critical for continuity.
+
+**❌ "Assuming IMPLEMENTATION.md means implementation is done"**
+
+IMPLEMENTATION.md created at end of Phase 3 (before REVIEW). Phase 3 complete, but Phase 4 still needed.
+
+## Key Takeaways
+
+- File existence = phase completion marker
+- Progressive disclosure prevents false positives
+- Always load complete context before resuming
+- Multiple matches require user selection

skills/implement-feature/scripts/init_session.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# Initialize a new feature implementation session directory
+# Usage: ./init_session.sh <feature-slug>
+
+set -e
+
+if [ -z "$1" ]; then
+    echo "Error: Feature slug required"
+    echo "Usage: $0 <feature-slug>"
+    exit 1
+fi
+
+SLUG="$1"
+TIMESTAMP=$(date +"%Y%m%d")
+SESSION_DIR="docs/sessions/${TIMESTAMP}-${SLUG}"
+
+# Create session directory
+mkdir -p "$SESSION_DIR"
+
+echo "✅ Session initialized: $SESSION_DIR"