claude-cook 1.10.1

package/get-shit-done/references/vibe-kanban.md

@@ -0,0 +1,142 @@
+# Vibe Kanban MCP Reference
+
+Reference for PM agent interactions with the Vibe Kanban task management system.
+
+## Tool Catalog
+
+### Reading State
+
+**`mcp__vibe_kanban__list_projects`**
+Returns all available projects. Use to discover `project_id` on first run.
+
+**`mcp__vibe_kanban__list_tasks(project_id, [status])`**
+List all tickets in a project. Optional status filter: `todo`, `inprogress`, `inreview`, `done`, `cancelled`.
+
+**`mcp__vibe_kanban__get_task(task_id)`**
+Get full ticket details including description and status. Use to read worker output/notes.
+
+**`mcp__vibe_kanban__list_repos(project_id)`**
+List all repositories for a project. Returns `repo_id` needed for dispatch.
+
+**`mcp__vibe_kanban__get_repo(repo_id)`**
+Get repo details including scripts (setup, cleanup, dev server).
+
+### Writing State
+
+**`mcp__vibe_kanban__create_task(project_id, title, [description])`**
+Create a new ticket. The description should contain the full PLAN.md content as the worker's prompt.
+
+**`mcp__vibe_kanban__update_task(task_id, [title], [description], [status])`**
+Update ticket fields. Use for:
+- Marking tickets `done` after verification
+- Marking tickets `cancelled` during replan
+- Updating description when plans change
+
+**`mcp__vibe_kanban__delete_task(task_id)`**
+Permanently delete a ticket. Prefer `update_task(status: cancelled)` for audit trail.
+
+### Dispatching Workers
+
+**`mcp__vibe_kanban__start_workspace_session(task_id, executor, repos, [variant])`**
+Launch an external coding agent to work on a ticket.
+
+Parameters:
+- `task_id`: The ticket UUID to assign
+- `executor`: Agent type — one of:
+  - `CLAUDE_CODE` — Claude Code CLI
+  - `AMP` — Amp agent
+  - `GEMINI` — Gemini CLI
+  - `CODEX` — OpenAI Codex
+  - `OPENCODE` — OpenCode
+  - `CURSOR_AGENT` — Cursor agent
+  - `QWEN_CODE` — Qwen Code
+  - `COPILOT` — GitHub Copilot
+  - `DROID` — Droid agent
+- `repos`: Array of `{repo_id, base_branch}` objects
+- `variant`: Optional executor variant
+
+### Repository Scripts
+
+**`mcp__vibe_kanban__update_setup_script(repo_id, script)`**
+Set the script that runs when a workspace initializes (e.g., `npm install`).
+
+**`mcp__vibe_kanban__update_cleanup_script(repo_id, script)`**
+Set the script that runs when a workspace tears down.
+
+**`mcp__vibe_kanban__update_dev_server_script(repo_id, script)`**
+Set the dev server script (e.g., `npm run dev`).
+
+## Ticket Status Lifecycle
+
+```
+todo ──→ inprogress ──→ inreview ──→ done
+  │          │              │
+  │          └──→ cancelled ←──┘
+  └──→ cancelled
+```
+
+- `todo`: Created, not yet dispatched
+- `inprogress`: Worker session launched
+- `inreview`: Worker completed, awaiting PM review
+- `done`: PM confirmed completion
+- `cancelled`: Abandoned (replanned or removed)
+
+## PM Usage Patterns
+
+### Initial Setup (first /pm:start)
+
+```
+1. list_projects() → find project_id
+2. list_repos(project_id) → find repo_id + base_branch
+3. Save to .planning/config.json pm section
+```
+
+### Plan-to-Ticket Sync
+
+```
+For each PLAN.md:
+  title = "Phase {X} Plan {Y}: {objective_summary}"
+  description = full PLAN.md content
+  create_task(project_id, title, description)
+  → record ticket_id in TICKET-MAP.md
+```
+
+### Dispatch Workers
+
+```
+For each ticket in current wave with status=todo:
+  start_workspace_session(
+    task_id=ticket_id,
+    executor=config.pm.default_executor,
+    repos=[{repo_id, base_branch}]
+  )
+  update_task(ticket_id, status="inprogress")
+```
+
+### Monitor Cycle
+
+```
+tickets = list_tasks(project_id)
+For each ticket:
+  current = ticket.status
+  previous = TICKET-MAP[ticket_id].status
+  if current != previous:
+    handle_transition(previous, current, ticket)
+    update TICKET-MAP
+```
+
+### Replan Sync
+
+```
+# Cancel old tickets
+For each obsolete ticket:
+  update_task(ticket_id, status="cancelled")
+
+# Create new tickets
+For each new plan:
+  create_task(project_id, title, description)
+
+# Update modified tickets
+For each changed plan:
+  update_task(ticket_id, description=new_plan_content)
+```

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

@@ -0,0 +1,159 @@
+# Debug Template
+
+Template for `.planning/debug/[slug].md` — active debug session tracking.
+
+---
+
+## File Template
+
+```markdown
+---
+status: gathering | investigating | fixing | verifying | resolved
+trigger: "[verbatim user input]"
+created: [ISO timestamp]
+updated: [ISO timestamp]
+---
+
+## Current Focus
+<!-- OVERWRITE on each update - always reflects NOW -->
+
+hypothesis: [current theory being tested]
+test: [how testing it]
+expecting: [what result means if true/false]
+next_action: [immediate next step]
+
+## Symptoms
+<!-- Written during gathering, then immutable -->
+
+expected: [what should happen]
+actual: [what actually happens]
+errors: [error messages if any]
+reproduction: [how to trigger]
+started: [when it broke / always broken]
+
+## Eliminated
+<!-- APPEND only - prevents re-investigating after /clear -->
+
+- hypothesis: [theory that was wrong]
+  evidence: [what disproved it]
+  timestamp: [when eliminated]
+
+## Evidence
+<!-- APPEND only - facts discovered during investigation -->
+
+- timestamp: [when found]
+  checked: [what was examined]
+  found: [what was observed]
+  implication: [what this means]
+
+## Resolution
+<!-- OVERWRITE as understanding evolves -->
+
+root_cause: [empty until found]
+fix: [empty until applied]
+verification: [empty until verified]
+files_changed: []
+```
+
+---
+
+<section_rules>
+
+**Frontmatter (status, trigger, timestamps):**
+- `status`: OVERWRITE - reflects current phase
+- `trigger`: IMMUTABLE - verbatim user input, never changes
+- `created`: IMMUTABLE - set once
+- `updated`: OVERWRITE - update on every change
+
+**Current Focus:**
+- OVERWRITE entirely on each update
+- Always reflects what Claude is doing RIGHT NOW
+- If Claude reads this after /clear, it knows exactly where to resume
+- Fields: hypothesis, test, expecting, next_action
+
+**Symptoms:**
+- Written during initial gathering phase
+- IMMUTABLE after gathering complete
+- Reference point for what we're trying to fix
+- Fields: expected, actual, errors, reproduction, started
+
+**Eliminated:**
+- APPEND only - never remove entries
+- Prevents re-investigating dead ends after context reset
+- Each entry: hypothesis, evidence that disproved it, timestamp
+- Critical for efficiency across /clear boundaries
+
+**Evidence:**
+- APPEND only - never remove entries
+- Facts discovered during investigation
+- Each entry: timestamp, what checked, what found, implication
+- Builds the case for root cause
+
+**Resolution:**
+- OVERWRITE as understanding evolves
+- May update multiple times as fixes are tried
+- Final state shows confirmed root cause and verified fix
+- Fields: root_cause, fix, verification, files_changed
+
+</section_rules>
+
+<lifecycle>
+
+**Creation:** Immediately when /gsd:debug is called
+- Create file with trigger from user input
+- Set status to "gathering"
+- Current Focus: next_action = "gather symptoms"
+- Symptoms: empty, to be filled
+
+**During symptom gathering:**
+- Update Symptoms section as user answers questions
+- Update Current Focus with each question
+- When complete: status → "investigating"
+
+**During investigation:**
+- OVERWRITE Current Focus with each hypothesis
+- APPEND to Evidence with each finding
+- APPEND to Eliminated when hypothesis disproved
+- Update timestamp in frontmatter
+
+**During fixing:**
+- status → "fixing"
+- Update Resolution.root_cause when confirmed
+- Update Resolution.fix when applied
+- Update Resolution.files_changed
+
+**During verification:**
+- status → "verifying"
+- Update Resolution.verification with results
+- If verification fails: status → "investigating", try again
+
+**On resolution:**
+- status → "resolved"
+- Move file to .planning/debug/resolved/
+
+</lifecycle>
+
+<resume_behavior>
+
+When Claude reads this file after /clear:
+
+1. Parse frontmatter → know status
+2. Read Current Focus → know exactly what was happening
+3. Read Eliminated → know what NOT to retry
+4. Read Evidence → know what's been learned
+5. Continue from next_action
+
+The file IS the debugging brain. Claude should be able to resume perfectly from any interruption point.
+
+</resume_behavior>
+
+<size_constraint>
+
+Keep debug files focused:
+- Evidence entries: 1-2 lines each, just the facts
+- Eliminated: brief - hypothesis + why it failed
+- No narrative prose - structured data only
+
+If evidence grows very large (10+ entries), consider whether you're going in circles. Check Eliminated to ensure you're not re-treading.
+
+</size_constraint>

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

@@ -0,0 +1,247 @@
+# UAT Template
+
+Template for `.planning/phases/XX-name/{phase}-UAT.md` — persistent UAT session tracking.
+
+---
+
+## File Template
+
+```markdown
+---
+status: testing | complete | diagnosed
+phase: XX-name
+source: [list of SUMMARY.md files tested]
+started: [ISO timestamp]
+updated: [ISO timestamp]
+---
+
+## Current Test
+<!-- OVERWRITE each test - shows where we are -->
+
+number: [N]
+name: [test name]
+expected: |
+  [what user should observe]
+awaiting: user response
+
+## Tests
+
+### 1. [Test Name]
+expected: [observable behavior - what user should see]
+result: [pending]
+
+### 2. [Test Name]
+expected: [observable behavior]
+result: pass
+
+### 3. [Test Name]
+expected: [observable behavior]
+result: issue
+reported: "[verbatim user response]"
+severity: major
+
+### 4. [Test Name]
+expected: [observable behavior]
+result: skipped
+reason: [why skipped]
+
+...
+
+## Summary
+
+total: [N]
+passed: [N]
+issues: [N]
+pending: [N]
+skipped: [N]
+
+## Gaps
+
+<!-- YAML format for plan-phase --gaps consumption -->
+- truth: "[expected behavior from test]"
+  status: failed
+  reason: "User reported: [verbatim response]"
+  severity: blocker | major | minor | cosmetic
+  test: [N]
+  root_cause: ""     # Filled by diagnosis
+  artifacts: []      # Filled by diagnosis
+  missing: []        # Filled by diagnosis
+  debug_session: ""  # Filled by diagnosis
+```
+
+---
+
+<section_rules>
+
+**Frontmatter:**
+- `status`: OVERWRITE - "testing" or "complete"
+- `phase`: IMMUTABLE - set on creation
+- `source`: IMMUTABLE - SUMMARY files being tested
+- `started`: IMMUTABLE - set on creation
+- `updated`: OVERWRITE - update on every change
+
+**Current Test:**
+- OVERWRITE entirely on each test transition
+- Shows which test is active and what's awaited
+- On completion: "[testing complete]"
+
+**Tests:**
+- Each test: OVERWRITE result field when user responds
+- `result` values: [pending], pass, issue, skipped
+- If issue: add `reported` (verbatim) and `severity` (inferred)
+- If skipped: add `reason` if provided
+
+**Summary:**
+- OVERWRITE counts after each response
+- Tracks: total, passed, issues, pending, skipped
+
+**Gaps:**
+- APPEND only when issue found (YAML format)
+- After diagnosis: fill `root_cause`, `artifacts`, `missing`, `debug_session`
+- This section feeds directly into /gsd:plan-phase --gaps
+
+</section_rules>
+
+<diagnosis_lifecycle>
+
+**After testing complete (status: complete), if gaps exist:**
+
+1. User runs diagnosis (from verify-work offer or manually)
+2. diagnose-issues workflow spawns parallel debug agents
+3. Each agent investigates one gap, returns root cause
+4. UAT.md Gaps section updated with diagnosis:
+   - Each gap gets `root_cause`, `artifacts`, `missing`, `debug_session` filled
+5. status → "diagnosed"
+6. Ready for /gsd:plan-phase --gaps with root causes
+
+**After diagnosis:**
+```yaml
+## Gaps
+
+- truth: "Comment appears immediately after submission"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect missing dependency"
+  missing:
+    - "Add commentCount to useEffect dependency array"
+  debug_session: ".planning/debug/comment-not-refreshing.md"
+```
+
+</diagnosis_lifecycle>
+
+<lifecycle>
+
+**Creation:** When /gsd:verify-work starts new session
+- Extract tests from SUMMARY.md files
+- Set status to "testing"
+- Current Test points to test 1
+- All tests have result: [pending]
+
+**During testing:**
+- Present test from Current Test section
+- User responds with pass confirmation or issue description
+- Update test result (pass/issue/skipped)
+- Update Summary counts
+- If issue: append to Gaps section (YAML format), infer severity
+- Move Current Test to next pending test
+
+**On completion:**
+- status → "complete"
+- Current Test → "[testing complete]"
+- Commit file
+- Present summary with next steps
+
+**Resume after /clear:**
+1. Read frontmatter → know phase and status
+2. Read Current Test → know where we are
+3. Find first [pending] result → continue from there
+4. Summary shows progress so far
+
+</lifecycle>
+
+<severity_guide>
+
+Severity is INFERRED from user's natural language, never asked.
+
+| User describes | Infer |
+|----------------|-------|
+| Crash, error, exception, fails completely, unusable | blocker |
+| Doesn't work, nothing happens, wrong behavior, missing | major |
+| Works but..., slow, weird, minor, small issue | minor |
+| Color, font, spacing, alignment, visual, looks off | cosmetic |
+
+Default: **major** (safe default, user can clarify if wrong)
+
+</severity_guide>
+
+<good_example>
+```markdown
+---
+status: diagnosed
+phase: 04-comments
+source: 04-01-SUMMARY.md, 04-02-SUMMARY.md
+started: 2025-01-15T10:30:00Z
+updated: 2025-01-15T10:45:00Z
+---
+
+## Current Test
+
+[testing complete]
+
+## Tests
+
+### 1. View Comments on Post
+expected: Comments section expands, shows count and comment list
+result: pass
+
+### 2. Create Top-Level Comment
+expected: Submit comment via rich text editor, appears in list with author info
+result: issue
+reported: "works but doesn't show until I refresh the page"
+severity: major
+
+### 3. Reply to a Comment
+expected: Click Reply, inline composer appears, submit shows nested reply
+result: pass
+
+### 4. Visual Nesting
+expected: 3+ level thread shows indentation, left borders, caps at reasonable depth
+result: pass
+
+### 5. Delete Own Comment
+expected: Click delete on own comment, removed or shows [deleted] if has replies
+result: pass
+
+### 6. Comment Count
+expected: Post shows accurate count, increments when adding comment
+result: pass
+
+## Summary
+
+total: 6
+passed: 5
+issues: 1
+pending: 0
+skipped: 0
+
+## Gaps
+
+- truth: "Comment appears immediately after submission in list"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect missing dependency"
+  missing:
+    - "Add commentCount to useEffect dependency array"
+  debug_session: ".planning/debug/comment-not-refreshing.md"
+```
+</good_example>