Initial commit

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