claude-cook 1.10.1

package/get-shit-done/templates/context.md

@@ -0,0 +1,283 @@
+# Phase Context Template
+
+Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures implementation decisions for a phase.
+
+**Purpose:** Document decisions that downstream agents need. Researcher uses this to know WHAT to investigate. Planner uses this to know WHAT choices are locked vs flexible.
+
+**Key principle:** Categories are NOT predefined. They emerge from what was actually discussed for THIS phase. A CLI phase has CLI-relevant sections, a UI phase has UI-relevant sections.
+
+**Downstream consumers:**
+- `gsd-phase-researcher` — Reads decisions to focus research (e.g., "card layout" → research card component patterns)
+- `gsd-planner` — Reads decisions to create specific tasks (e.g., "infinite scroll" → task includes virtualization)
+
+---
+
+## File Template
+
+```markdown
+# Phase [X]: [Name] - Context
+
+**Gathered:** [date]
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+[Clear statement of what this phase delivers — the scope anchor. This comes from ROADMAP.md and is fixed. Discussion clarifies implementation within this boundary.]
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### [Area 1 that was discussed]
+- [Specific decision made]
+- [Another decision if applicable]
+
+### [Area 2 that was discussed]
+- [Specific decision made]
+
+### [Area 3 that was discussed]
+- [Specific decision made]
+
+### Claude's Discretion
+[Areas where user explicitly said "you decide" — Claude has flexibility here during planning/implementation]
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+[Any particular references, examples, or "I want it like X" moments from discussion. Product references, specific behaviors, interaction patterns.]
+
+[If none: "No specific requirements — open to standard approaches"]
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+[Ideas that came up during discussion but belong in other phases. Captured here so they're not lost, but explicitly out of scope for this phase.]
+
+[If none: "None — discussion stayed within phase scope"]
+
+</deferred>
+
+---
+
+*Phase: XX-name*
+*Context gathered: [date]*
+```
+
+<good_examples>
+
+**Example 1: Visual feature (Post Feed)**
+
+```markdown
+# Phase 3: Post Feed - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Display posts from followed users in a scrollable feed. Users can view posts and see engagement counts. Creating posts and interactions are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Layout style
+- Card-based layout, not timeline or list
+- Each card shows: author avatar, name, timestamp, full post content, reaction counts
+- Cards have subtle shadows, rounded corners — modern feel
+
+### Loading behavior
+- Infinite scroll, not pagination
+- Pull-to-refresh on mobile
+- New posts indicator at top ("3 new posts") rather than auto-inserting
+
+### Empty state
+- Friendly illustration + "Follow people to see posts here"
+- Suggest 3-5 accounts to follow based on interests
+
+### Claude's Discretion
+- Loading skeleton design
+- Exact spacing and typography
+- Error state handling
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I like how Twitter shows the new posts indicator without disrupting your scroll position"
+- Cards should feel like Linear's issue cards — clean, not cluttered
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Commenting on posts — Phase 5
+- Bookmarking posts — add to backlog
+
+</deferred>
+
+---
+
+*Phase: 03-post-feed*
+*Context gathered: 2025-01-20*
+```
+
+**Example 2: CLI tool (Database backup)**
+
+```markdown
+# Phase 2: Backup Command - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+CLI command to backup database to local file or S3. Supports full and incremental backups. Restore command is a separate phase.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Output format
+- JSON for programmatic use, table format for humans
+- Default to table, --json flag for JSON
+- Verbose mode (-v) shows progress, silent by default
+
+### Flag design
+- Short flags for common options: -o (output), -v (verbose), -f (force)
+- Long flags for clarity: --incremental, --compress, --encrypt
+- Required: database connection string (positional or --db)
+
+### Error recovery
+- Retry 3 times on network failure, then fail with clear message
+- --no-retry flag to fail fast
+- Partial backups are deleted on failure (no corrupt files)
+
+### Claude's Discretion
+- Exact progress bar implementation
+- Compression algorithm choice
+- Temp file handling
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I want it to feel like pg_dump — familiar to database people"
+- Should work in CI pipelines (exit codes, no interactive prompts)
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Scheduled backups — separate phase
+- Backup rotation/retention — add to backlog
+
+</deferred>
+
+---
+
+*Phase: 02-backup-command*
+*Context gathered: 2025-01-20*
+```
+
+**Example 3: Organization task (Photo library)**
+
+```markdown
+# Phase 1: Photo Organization - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Organize existing photo library into structured folders. Handle duplicates and apply consistent naming. Tagging and search are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Grouping criteria
+- Primary grouping by year, then by month
+- Events detected by time clustering (photos within 2 hours = same event)
+- Event folders named by date + location if available
+
+### Duplicate handling
+- Keep highest resolution version
+- Move duplicates to _duplicates folder (don't delete)
+- Log all duplicate decisions for review
+
+### Naming convention
+- Format: YYYY-MM-DD_HH-MM-SS_originalname.ext
+- Preserve original filename as suffix for searchability
+- Handle name collisions with incrementing suffix
+
+### Claude's Discretion
+- Exact clustering algorithm
+- How to handle photos with no EXIF data
+- Folder emoji usage
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I want to be able to find photos by roughly when they were taken"
+- Don't delete anything — worst case, move to a review folder
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Face detection grouping — future phase
+- Cloud sync — out of scope for now
+
+</deferred>
+
+---
+
+*Phase: 01-photo-organization*
+*Context gathered: 2025-01-20*
+```
+
+</good_examples>
+
+<guidelines>
+**This template captures DECISIONS for downstream agents.**
+
+The output should answer: "What does the researcher need to investigate? What choices are locked for the planner?"
+
+**Good content (concrete decisions):**
+- "Card-based layout, not timeline"
+- "Retry 3 times on network failure, then fail"
+- "Group by year, then by month"
+- "JSON for programmatic use, table for humans"
+
+**Bad content (too vague):**
+- "Should feel modern and clean"
+- "Good user experience"
+- "Fast and responsive"
+- "Easy to use"
+
+**After creation:**
+- File lives in phase directory: `.planning/phases/XX-name/{phase}-CONTEXT.md`
+- `gsd-phase-researcher` uses decisions to focus investigation
+- `gsd-planner` uses decisions + research to create executable tasks
+- Downstream agents should NOT need to ask the user again about captured decisions
+</guidelines>

package/get-shit-done/templates/continue-here.md

@@ -0,0 +1,78 @@
+# Continue-Here Template
+
+Copy and fill this structure for `.planning/phases/XX-name/.continue-here.md`:
+
+```yaml
+---
+phase: XX-name
+task: 3
+total_tasks: 7
+status: in_progress
+last_updated: 2025-01-15T14:30:00Z
+---
+```
+
+```markdown
+<current_state>
+[Where exactly are we? What's the immediate context?]
+</current_state>
+
+<completed_work>
+[What got done this session - be specific]
+
+- Task 1: [name] - Done
+- Task 2: [name] - Done
+- Task 3: [name] - In progress, [what's done on it]
+</completed_work>
+
+<remaining_work>
+[What's left in this phase]
+
+- Task 3: [name] - [what's left to do]
+- Task 4: [name] - Not started
+- Task 5: [name] - Not started
+</remaining_work>
+
+<decisions_made>
+[Key decisions and why - so next session doesn't re-debate]
+
+- Decided to use [X] because [reason]
+- Chose [approach] over [alternative] because [reason]
+</decisions_made>
+
+<blockers>
+[Anything stuck or waiting on external factors]
+
+- [Blocker 1]: [status/workaround]
+</blockers>
+
+<context>
+[Mental state, "vibe", anything that helps resume smoothly]
+
+[What were you thinking about? What was the plan?
+This is the "pick up exactly where you left off" context.]
+</context>
+
+<next_action>
+[The very first thing to do when resuming]
+
+Start with: [specific action]
+</next_action>
+```
+
+<yaml_fields>
+Required YAML frontmatter:
+
+- `phase`: Directory name (e.g., `02-authentication`)
+- `task`: Current task number
+- `total_tasks`: How many tasks in phase
+- `status`: `in_progress`, `blocked`, `almost_done`
+- `last_updated`: ISO timestamp
+</yaml_fields>
+
+<guidelines>
+- Be specific enough that a fresh Claude instance understands immediately
+- Include WHY decisions were made, not just what
+- The `<next_action>` should be actionable without reading anything else
+- This file gets DELETED after resume - it's not permanent storage
+</guidelines>

package/get-shit-done/templates/debug-subagent-prompt.md

@@ -0,0 +1,91 @@
+# Debug Subagent Prompt Template
+
+Template for spawning gsd-debugger agent. The agent contains all debugging expertise - this template provides problem context only.
+
+---
+
+## Template
+
+```markdown
+<objective>
+Investigate issue: {issue_id}
+
+**Summary:** {issue_summary}
+</objective>
+
+<symptoms>
+expected: {expected}
+actual: {actual}
+errors: {errors}
+reproduction: {reproduction}
+timeline: {timeline}
+</symptoms>
+
+<mode>
+symptoms_prefilled: {true_or_false}
+goal: {find_root_cause_only | find_and_fix}
+</mode>
+
+<debug_file>
+Create: .planning/debug/{slug}.md
+</debug_file>
+```
+
+---
+
+## Placeholders
+
+| Placeholder | Source | Example |
+|-------------|--------|---------|
+| `{issue_id}` | Orchestrator-assigned | `auth-screen-dark` |
+| `{issue_summary}` | User description | `Auth screen is too dark` |
+| `{expected}` | From symptoms | `See logo clearly` |
+| `{actual}` | From symptoms | `Screen is dark` |
+| `{errors}` | From symptoms | `None in console` |
+| `{reproduction}` | From symptoms | `Open /auth page` |
+| `{timeline}` | From symptoms | `After recent deploy` |
+| `{goal}` | Orchestrator sets | `find_and_fix` |
+| `{slug}` | Generated | `auth-screen-dark` |
+
+---
+
+## Usage
+
+**From /gsd:debug:**
+```python
+Task(
+  prompt=filled_template,
+  subagent_type="gsd-debugger",
+  description="Debug {slug}"
+)
+```
+
+**From diagnose-issues (UAT):**
+```python
+Task(prompt=template, subagent_type="gsd-debugger", description="Debug UAT-001")
+```
+
+---
+
+## Continuation
+
+For checkpoints, spawn fresh agent with:
+
+```markdown
+<objective>
+Continue debugging {slug}. Evidence is in the debug file.
+</objective>
+
+<prior_state>
+Debug file: @.planning/debug/{slug}.md
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+
+<mode>
+goal: {goal}
+</mode>
+```

package/get-shit-done/templates/discovery.md

@@ -0,0 +1,146 @@
+# Discovery Template
+
+Template for `.planning/phases/XX-name/DISCOVERY.md` - shallow research for library/option decisions.
+
+**Purpose:** Answer "which library/option should we use" questions during mandatory discovery in plan-phase.
+
+For deep ecosystem research ("how do experts build this"), use `/gsd:research-phase` which produces RESEARCH.md.
+
+---
+
+## File Template
+
+```markdown
+---
+phase: XX-name
+type: discovery
+topic: [discovery-topic]
+---
+
+<session_initialization>
+Before beginning discovery, verify today's date:
+!`date +%Y-%m-%d`
+
+Use this date when searching for "current" or "latest" information.
+Example: If today is 2025-11-22, search for "2025" not "2024".
+</session_initialization>
+
+<discovery_objective>
+Discover [topic] to inform [phase name] implementation.
+
+Purpose: [What decision/implementation this enables]
+Scope: [Boundaries]
+Output: DISCOVERY.md with recommendation
+</discovery_objective>
+
+<discovery_scope>
+<include>
+- [Question to answer]
+- [Area to investigate]
+- [Specific comparison if needed]
+</include>
+
+<exclude>
+- [Out of scope for this discovery]
+- [Defer to implementation phase]
+</exclude>
+</discovery_scope>
+
+<discovery_protocol>
+
+**Source Priority:**
+1. **Context7 MCP** - For library/framework documentation (current, authoritative)
+2. **Official Docs** - For platform-specific or non-indexed libraries
+3. **WebSearch** - For comparisons, trends, community patterns (verify all findings)
+
+**Quality Checklist:**
+Before completing discovery, verify:
+- [ ] All claims have authoritative sources (Context7 or official docs)
+- [ ] Negative claims ("X is not possible") verified with official documentation
+- [ ] API syntax/configuration from Context7 or official docs (never WebSearch alone)
+- [ ] WebSearch findings cross-checked with authoritative sources
+- [ ] Recent updates/changelogs checked for breaking changes
+- [ ] Alternative approaches considered (not just first solution found)
+
+**Confidence Levels:**
+- HIGH: Context7 or official docs confirm
+- MEDIUM: WebSearch + Context7/official docs confirm
+- LOW: WebSearch only or training knowledge only (mark for validation)
+
+</discovery_protocol>
+
+
+<output_structure>
+Create `.planning/phases/XX-name/DISCOVERY.md`:
+
+```markdown
+# [Topic] Discovery
+
+## Summary
+[2-3 paragraph executive summary - what was researched, what was found, what's recommended]
+
+## Primary Recommendation
+[What to do and why - be specific and actionable]
+
+## Alternatives Considered
+[What else was evaluated and why not chosen]
+
+## Key Findings
+
+### [Category 1]
+- [Finding with source URL and relevance to our case]
+
+### [Category 2]
+- [Finding with source URL and relevance]
+
+## Code Examples
+[Relevant implementation patterns, if applicable]
+
+## Metadata
+
+<metadata>
+<confidence level="high|medium|low">
+[Why this confidence level - based on source quality and verification]
+</confidence>
+
+<sources>
+- [Primary authoritative sources used]
+</sources>
+
+<open_questions>
+[What couldn't be determined or needs validation during implementation]
+</open_questions>
+
+<validation_checkpoints>
+[If confidence is LOW or MEDIUM, list specific things to verify during implementation]
+</validation_checkpoints>
+</metadata>
+```
+</output_structure>
+
+<success_criteria>
+- All scope questions answered with authoritative sources
+- Quality checklist items completed
+- Clear primary recommendation
+- Low-confidence findings marked with validation checkpoints
+- Ready to inform PLAN.md creation
+</success_criteria>
+
+<guidelines>
+**When to use discovery:**
+- Technology choice unclear (library A vs B)
+- Best practices needed for unfamiliar integration
+- API/library investigation required
+- Single decision pending
+
+**When NOT to use:**
+- Established patterns (CRUD, auth with known library)
+- Implementation details (defer to execution)
+- Questions answerable from existing project context
+
+**When to use RESEARCH.md instead:**
+- Niche/complex domains (3D, games, audio, shaders)
+- Need ecosystem knowledge, not just library choice
+- "How do experts build this" questions
+- Use `/gsd:research-phase` for these
+</guidelines>

package/get-shit-done/templates/milestone-archive.md

@@ -0,0 +1,123 @@
+# Milestone Archive Template
+
+This template is used by the complete-milestone workflow to create archive files in `.planning/milestones/`.
+
+---
+
+## File Template
+
+# Milestone v{{VERSION}}: {{MILESTONE_NAME}}
+
+**Status:** ✅ SHIPPED {{DATE}}
+**Phases:** {{PHASE_START}}-{{PHASE_END}}
+**Total Plans:** {{TOTAL_PLANS}}
+
+## Overview
+
+{{MILESTONE_DESCRIPTION}}
+
+## Phases
+
+{{PHASES_SECTION}}
+
+[For each phase in this milestone, include:]
+
+### Phase {{PHASE_NUM}}: {{PHASE_NAME}}
+
+**Goal**: {{PHASE_GOAL}}
+**Depends on**: {{DEPENDS_ON}}
+**Plans**: {{PLAN_COUNT}} plans
+
+Plans:
+
+- [x] {{PHASE}}-01: {{PLAN_DESCRIPTION}}
+- [x] {{PHASE}}-02: {{PLAN_DESCRIPTION}}
+      [... all plans ...]
+
+**Details:**
+{{PHASE_DETAILS_FROM_ROADMAP}}
+
+**For decimal phases, include (INSERTED) marker:**
+
+### Phase 2.1: Critical Security Patch (INSERTED)
+
+**Goal**: Fix authentication bypass vulnerability
+**Depends on**: Phase 2
+**Plans**: 1 plan
+
+Plans:
+
+- [x] 02.1-01: Patch auth vulnerability
+
+**Details:**
+{{PHASE_DETAILS_FROM_ROADMAP}}
+
+---
+
+## Milestone Summary
+
+**Decimal Phases:**
+
+- Phase 2.1: Critical Security Patch (inserted after Phase 2 for urgent fix)
+- Phase 5.1: Performance Hotfix (inserted after Phase 5 for production issue)
+
+**Key Decisions:**
+{{DECISIONS_FROM_PROJECT_STATE}}
+[Example:]
+
+- Decision: Use ROADMAP.md split (Rationale: Constant context cost)
+- Decision: Decimal phase numbering (Rationale: Clear insertion semantics)
+
+**Issues Resolved:**
+{{ISSUES_RESOLVED_DURING_MILESTONE}}
+[Example:]
+
+- Fixed context overflow at 100+ phases
+- Resolved phase insertion confusion
+
+**Issues Deferred:**
+{{ISSUES_DEFERRED_TO_LATER}}
+[Example:]
+
+- PROJECT-STATE.md tiering (deferred until decisions > 300)
+
+**Technical Debt Incurred:**
+{{SHORTCUTS_NEEDING_FUTURE_WORK}}
+[Example:]
+
+- Some workflows still have hardcoded paths (fix in Phase 5)
+
+---
+
+_For current project status, see .planning/ROADMAP.md_
+
+---
+
+## Usage Guidelines
+
+<guidelines>
+**When to create milestone archives:**
+- After completing all phases in a milestone (v1.0, v1.1, v2.0, etc.)
+- Triggered by complete-milestone workflow
+- Before planning next milestone work
+
+**How to fill template:**
+
+- Replace {{PLACEHOLDERS}} with actual values
+- Extract phase details from ROADMAP.md
+- Document decimal phases with (INSERTED) marker
+- Include key decisions from PROJECT-STATE.md or SUMMARY files
+- List issues resolved vs deferred
+- Capture technical debt for future reference
+
+**Archive location:**
+
+- Save to `.planning/milestones/v{VERSION}-{NAME}.md`
+- Example: `.planning/milestones/v1.0-mvp.md`
+
+**After archiving:**
+
+- Update ROADMAP.md to collapse completed milestone in `<details>` tag
+- Update PROJECT.md to brownfield format with Current State section
+- Continue phase numbering in next milestone (never restart at 01)
+  </guidelines>