claude-cook 1.10.1

package/get-shit-done/workflows/list-phase-assumptions.md

@@ -0,0 +1,178 @@
+<purpose>
+Surface Claude's assumptions about a phase before planning, enabling users to correct misconceptions early.
+
+Key difference from discuss-phase: This is ANALYSIS of what Claude thinks, not INTAKE of what user knows. No file output - purely conversational to prompt discussion.
+</purpose>
+
+<process>
+
+<step name="validate_phase" priority="first">
+Phase number: $ARGUMENTS (required)
+
+**If argument missing:**
+
+```
+Error: Phase number required.
+
+Usage: /gsd:list-phase-assumptions [phase-number]
+Example: /gsd:list-phase-assumptions 3
+```
+
+Exit workflow.
+
+**If argument provided:**
+Validate phase exists in roadmap:
+
+```bash
+cat .planning/ROADMAP.md | grep -i "Phase ${PHASE}"
+```
+
+**If phase not found:**
+
+```
+Error: Phase ${PHASE} not found in roadmap.
+
+Available phases:
+[list phases from roadmap]
+```
+
+Exit workflow.
+
+**If phase found:**
+Parse phase details from roadmap:
+
+- Phase number
+- Phase name
+- Phase description/goal
+- Any scope details mentioned
+
+Continue to analyze_phase.
+</step>
+
+<step name="analyze_phase">
+Based on roadmap description and project context, identify assumptions across five areas:
+
+**1. Technical Approach:**
+What libraries, frameworks, patterns, or tools would Claude use?
+- "I'd use X library because..."
+- "I'd follow Y pattern because..."
+- "I'd structure this as Z because..."
+
+**2. Implementation Order:**
+What would Claude build first, second, third?
+- "I'd start with X because it's foundational"
+- "Then Y because it depends on X"
+- "Finally Z because..."
+
+**3. Scope Boundaries:**
+What's included vs excluded in Claude's interpretation?
+- "This phase includes: A, B, C"
+- "This phase does NOT include: D, E, F"
+- "Boundary ambiguities: G could go either way"
+
+**4. Risk Areas:**
+Where does Claude expect complexity or challenges?
+- "The tricky part is X because..."
+- "Potential issues: Y, Z"
+- "I'd watch out for..."
+
+**5. Dependencies:**
+What does Claude assume exists or needs to be in place?
+- "This assumes X from previous phases"
+- "External dependencies: Y, Z"
+- "This will be consumed by..."
+
+Be honest about uncertainty. Mark assumptions with confidence levels:
+- "Fairly confident: ..." (clear from roadmap)
+- "Assuming: ..." (reasonable inference)
+- "Unclear: ..." (could go multiple ways)
+</step>
+
+<step name="present_assumptions">
+Present assumptions in a clear, scannable format:
+
+```
+## My Assumptions for Phase ${PHASE}: ${PHASE_NAME}
+
+### Technical Approach
+[List assumptions about how to implement]
+
+### Implementation Order
+[List assumptions about sequencing]
+
+### Scope Boundaries
+**In scope:** [what's included]
+**Out of scope:** [what's excluded]
+**Ambiguous:** [what could go either way]
+
+### Risk Areas
+[List anticipated challenges]
+
+### Dependencies
+**From prior phases:** [what's needed]
+**External:** [third-party needs]
+**Feeds into:** [what future phases need from this]
+
+---
+
+**What do you think?**
+
+Are these assumptions accurate? Let me know:
+- What I got right
+- What I got wrong
+- What I'm missing
+```
+
+Wait for user response.
+</step>
+
+<step name="gather_feedback">
+**If user provides corrections:**
+
+Acknowledge the corrections:
+
+```
+Key corrections:
+- [correction 1]
+- [correction 2]
+
+This changes my understanding significantly. [Summarize new understanding]
+```
+
+**If user confirms assumptions:**
+
+```
+Assumptions validated.
+```
+
+Continue to offer_next.
+</step>
+
+<step name="offer_next">
+Present next steps:
+
+```
+What's next?
+1. Discuss context (/gsd:discuss-phase ${PHASE}) - Let me ask you questions to build comprehensive context
+2. Plan this phase (/gsd:plan-phase ${PHASE}) - Create detailed execution plans
+3. Re-examine assumptions - I'll analyze again with your corrections
+4. Done for now
+```
+
+Wait for user selection.
+
+If "Discuss context": Note that CONTEXT.md will incorporate any corrections discussed here
+If "Plan this phase": Proceed knowing assumptions are understood
+If "Re-examine": Return to analyze_phase with updated understanding
+</step>
+
+</process>
+
+<success_criteria>
+- Phase number validated against roadmap
+- Assumptions surfaced across five areas: technical approach, implementation order, scope, risks, dependencies
+- Confidence levels marked where appropriate
+- "What do you think?" prompt presented
+- User feedback acknowledged
+- Clear next steps offered
+</success_criteria>

package/get-shit-done/workflows/map-codebase.md

@@ -0,0 +1,322 @@
+<purpose>
+Orchestrate parallel codebase mapper agents to analyze codebase and produce structured documents in .planning/codebase/
+
+Each agent has fresh context, explores a specific focus area, and **writes documents directly**. The orchestrator only receives confirmation + line counts, then writes a summary.
+
+Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
+</purpose>
+
+<philosophy>
+**Why dedicated mapper agents:**
+- Fresh context per domain (no token contamination)
+- Agents write documents directly (no context transfer back to orchestrator)
+- Orchestrator only summarizes what was created (minimal context usage)
+- Faster execution (agents run simultaneously)
+
+**Document quality over length:**
+Include enough detail to be useful as reference. Prioritize practical examples (especially code patterns) over arbitrary brevity.
+
+**Always include file paths:**
+Documents are reference material for Claude when planning/executing. Always include actual file paths formatted with backticks: `src/services/user.ts`.
+</philosophy>
+
+<process>
+
+<step name="resolve_model_profile" priority="first">
+Read model profile for agent spawning:
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default to "balanced" if not set.
+
+**Model lookup table:**
+
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| gsd-codebase-mapper | sonnet | haiku | haiku |
+
+Store resolved model for use in Task calls below.
+</step>
+
+<step name="check_existing">
+Check if .planning/codebase/ already exists:
+
+```bash
+ls -la .planning/codebase/ 2>/dev/null
+```
+
+**If exists:**
+
+```
+.planning/codebase/ already exists with these documents:
+[List files found]
+
+What's next?
+1. Refresh - Delete existing and remap codebase
+2. Update - Keep existing, only update specific documents
+3. Skip - Use existing codebase map as-is
+```
+
+Wait for user response.
+
+If "Refresh": Delete .planning/codebase/, continue to create_structure
+If "Update": Ask which documents to update, continue to spawn_agents (filtered)
+If "Skip": Exit workflow
+
+**If doesn't exist:**
+Continue to create_structure.
+</step>
+
+<step name="create_structure">
+Create .planning/codebase/ directory:
+
+```bash
+mkdir -p .planning/codebase
+```
+
+**Expected output files:**
+- STACK.md (from tech mapper)
+- INTEGRATIONS.md (from tech mapper)
+- ARCHITECTURE.md (from arch mapper)
+- STRUCTURE.md (from arch mapper)
+- CONVENTIONS.md (from quality mapper)
+- TESTING.md (from quality mapper)
+- CONCERNS.md (from concerns mapper)
+
+Continue to spawn_agents.
+</step>
+
+<step name="spawn_agents">
+Spawn 4 parallel gsd-codebase-mapper agents.
+
+Use Task tool with `subagent_type="gsd-codebase-mapper"`, `model="{mapper_model}"`, and `run_in_background=true` for parallel execution.
+
+**CRITICAL:** Use the dedicated `gsd-codebase-mapper` agent, NOT `Explore`. The mapper agent writes documents directly.
+
+**Agent 1: Tech Focus**
+
+Task tool parameters:
+```
+subagent_type: "gsd-codebase-mapper"
+model: "{mapper_model}"
+run_in_background: true
+description: "Map codebase tech stack"
+```
+
+Prompt:
+```
+Focus: tech
+
+Analyze this codebase for technology stack and external integrations.
+
+Write these documents to .planning/codebase/:
+- STACK.md - Languages, runtime, frameworks, dependencies, configuration
+- INTEGRATIONS.md - External APIs, databases, auth providers, webhooks
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only.
+```
+
+**Agent 2: Architecture Focus**
+
+Task tool parameters:
+```
+subagent_type: "gsd-codebase-mapper"
+model: "{mapper_model}"
+run_in_background: true
+description: "Map codebase architecture"
+```
+
+Prompt:
+```
+Focus: arch
+
+Analyze this codebase architecture and directory structure.
+
+Write these documents to .planning/codebase/:
+- ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points
+- STRUCTURE.md - Directory layout, key locations, naming conventions
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only.
+```
+
+**Agent 3: Quality Focus**
+
+Task tool parameters:
+```
+subagent_type: "gsd-codebase-mapper"
+model: "{mapper_model}"
+run_in_background: true
+description: "Map codebase conventions"
+```
+
+Prompt:
+```
+Focus: quality
+
+Analyze this codebase for coding conventions and testing patterns.
+
+Write these documents to .planning/codebase/:
+- CONVENTIONS.md - Code style, naming, patterns, error handling
+- TESTING.md - Framework, structure, mocking, coverage
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only.
+```
+
+**Agent 4: Concerns Focus**
+
+Task tool parameters:
+```
+subagent_type: "gsd-codebase-mapper"
+model: "{mapper_model}"
+run_in_background: true
+description: "Map codebase concerns"
+```
+
+Prompt:
+```
+Focus: concerns
+
+Analyze this codebase for technical debt, known issues, and areas of concern.
+
+Write this document to .planning/codebase/:
+- CONCERNS.md - Tech debt, bugs, security, performance, fragile areas
+
+Explore thoroughly. Write document directly using template. Return confirmation only.
+```
+
+Continue to collect_confirmations.
+</step>
+
+<step name="collect_confirmations">
+Wait for all 4 agents to complete.
+
+Read each agent's output file to collect confirmations.
+
+**Expected confirmation format from each agent:**
+```
+## Mapping Complete
+
+**Focus:** {focus}
+**Documents written:**
+- `.planning/codebase/{DOC1}.md` ({N} lines)
+- `.planning/codebase/{DOC2}.md` ({N} lines)
+
+Ready for orchestrator summary.
+```
+
+**What you receive:** Just file paths and line counts. NOT document contents.
+
+If any agent failed, note the failure and continue with successful documents.
+
+Continue to verify_output.
+</step>
+
+<step name="verify_output">
+Verify all documents created successfully:
+
+```bash
+ls -la .planning/codebase/
+wc -l .planning/codebase/*.md
+```
+
+**Verification checklist:**
+- All 7 documents exist
+- No empty documents (each should have >20 lines)
+
+If any documents missing or empty, note which agents may have failed.
+
+Continue to commit_codebase_map.
+</step>
+
+<step name="commit_codebase_map">
+Commit the codebase map:
+
+**Check planning config:**
+
+```bash
+COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
+```
+
+**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
+
+**If `COMMIT_PLANNING_DOCS=true` (default):**
+
+```bash
+git add .planning/codebase/*.md
+git commit -m "$(cat <<'EOF'
+docs: map existing codebase
+
+- STACK.md - Technologies and dependencies
+- ARCHITECTURE.md - System design and patterns
+- STRUCTURE.md - Directory layout
+- CONVENTIONS.md - Code style and patterns
+- TESTING.md - Test structure
+- INTEGRATIONS.md - External services
+- CONCERNS.md - Technical debt and issues
+EOF
+)"
+```
+
+Continue to offer_next.
+</step>
+
+<step name="offer_next">
+Present completion summary and next steps.
+
+**Get line counts:**
+```bash
+wc -l .planning/codebase/*.md
+```
+
+**Output format:**
+
+```
+Codebase mapping complete.
+
+Created .planning/codebase/:
+- STACK.md ([N] lines) - Technologies and dependencies
+- ARCHITECTURE.md ([N] lines) - System design and patterns
+- STRUCTURE.md ([N] lines) - Directory layout and organization
+- CONVENTIONS.md ([N] lines) - Code style and patterns
+- TESTING.md ([N] lines) - Test structure and practices
+- INTEGRATIONS.md ([N] lines) - External services and APIs
+- CONCERNS.md ([N] lines) - Technical debt and issues
+
+
+---
+
+## ▶ Next Up
+
+**Initialize project** — use codebase context for planning
+
+`/gsd:new-project`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Re-run mapping: `/gsd:map-codebase`
+- Review specific file: `cat .planning/codebase/STACK.md`
+- Edit any document before proceeding
+
+---
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- .planning/codebase/ directory created
+- 4 parallel gsd-codebase-mapper agents spawned with run_in_background=true
+- Agents write documents directly (orchestrator doesn't receive document contents)
+- Read agent output files to collect confirmations
+- All 7 codebase documents exist
+- Clear completion summary with line counts
+- User offered clear next steps in GSD style
+</success_criteria>

package/get-shit-done/workflows/pm-check.md

@@ -0,0 +1,210 @@
+# PM Check Workflow — Single Poll+React Cycle
+
+<purpose>
+Execute one stateless monitoring cycle: poll Vibe Kanban tickets, diff against TICKET-MAP.md, react to state changes, log decisions, update persistent state.
+
+This workflow is the atomic unit of the PM loop. Called by:
+- `pm-loop.sh` (autonomous mode — once per interval)
+- `/gsd:pm-check` (manual mode — user-triggered)
+
+Each invocation is a fresh Claude context. All state comes from files.
+</purpose>
+
+<process>
+
+<step name="load_state" priority="first">
+
+## 1. Load Persistent State
+
+Read the following files to reconstruct PM context:
+
+```bash
+cat .planning/config.json           # pm section
+cat .planning/STATE.md              # current position
+```
+
+From config.json, extract:
+- `pm.project_id` — VK project UUID
+- `pm.repos` — repo configs for dispatch
+- `pm.default_executor` — which agent to use
+- `pm.auto_replan_on_failure` — whether to auto-fix
+- `pm.auto_dispatch_next_wave` — whether to auto-advance
+- `pm.max_replan_attempts` — replan limit
+
+Find the active phase:
+```bash
+# Get current phase from STATE.md
+grep "Phase:" .planning/STATE.md | head -1
+```
+
+Read the active TICKET-MAP:
+```bash
+cat .planning/phases/{phase_dir}/TICKET-MAP.md
+```
+
+**If no TICKET-MAP exists:** This phase has no tickets yet. Exit with message suggesting `/gsd:pm-start`.
+
+**If phase_status is `complete`:** Exit with message that phase is done.
+
+</step>
+
+<step name="poll_vk">
+
+## 2. Poll Vibe Kanban
+
+Call `mcp__vibe_kanban__list_tasks(project_id)` to get all tickets.
+
+For each ticket returned, build a map:
+```
+current_state = {
+  ticket_id: { status, title, description_snippet }
+}
+```
+
+</step>
+
+<step name="diff">
+
+## 3. Diff Against TICKET-MAP
+
+For each ticket tracked in TICKET-MAP.md:
+
+```
+previous_status = TICKET-MAP[ticket_id].status
+current_status  = current_state[ticket_id].status
+
+if previous_status != current_status:
+  events.push({
+    ticket_id, title,
+    from: previous_status,
+    to: current_status
+  })
+```
+
+Classify each event:
+
+| Transition | Event Type |
+| ---------- | ---------- |
+| todo → inprogress | WORKER_STARTED |
+| inprogress → inreview | WORKER_COMPLETED |
+| inprogress → done | WORKER_AUTO_COMPLETED |
+| any → cancelled | TICKET_CANCELLED |
+| (no change, inprogress for too long) | POTENTIALLY_STUCK |
+
+Aggregate events:
+
+| Condition | Aggregate Event |
+| --------- | --------------- |
+| All wave N tickets are `done` | WAVE_COMPLETE |
+| All tickets across all waves are `done` | PHASE_COMPLETE |
+| No changes detected | NO_CHANGE |
+
+</step>
+
+<step name="react">
+
+## 4. React to Events
+
+Process events in priority order:
+
+### PHASE_COMPLETE (highest priority)
+1. Update TICKET-MAP.md: `phase_status: complete`
+2. Update STATE.md: mark phase complete, advance current position
+3. Log phase completion summary to PM-LOG.md
+4. Present to user:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PM ► PHASE COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Phase {X}: {name} — all tickets done.
+
+Run /gsd:pm-start {X+1} to begin next phase.
+```
+
+### WAVE_COMPLETE
+1. Identify next wave tickets in TICKET-MAP
+2. Check `pm.auto_dispatch_next_wave` in config
+3. If true: dispatch all next-wave tickets (call dispatch flow from gsd-pm agent)
+4. If false: log and present suggestion to user
+5. Update STATE.md wave summary
+
+### WORKER_COMPLETED / WORKER_AUTO_COMPLETED
+1. Call `get_task(task_id)` to read worker output/notes
+2. Update TICKET-MAP.md: status=done, completed=timestamp
+3. Check if this completes the wave
+
+### TICKET_CANCELLED (potential failure)
+1. Call `get_task(task_id)` to read cancellation reason
+2. Check `pm.auto_replan_on_failure` in config
+3. Read current replan_count from TICKET-MAP Replan History
+4. If auto_replan AND replan_count < max_replan_attempts:
+   - Spawn gsd-planner via Task tool in gap-closure mode
+   - Pass: failed ticket details, phase goal, existing plans
+   - After planner returns: sync new plan to VK ticket
+   - Dispatch fix ticket
+   - Increment replan_count
+5. If not auto or max reached: log and present failure to user with options
+
+### POTENTIALLY_STUCK
+1. Log warning
+2. If autonomous: consider re-dispatching
+3. Present to user if manual mode
+
+### NO_CHANGE
+1. Brief log entry only
+
+</step>
+
+<step name="log">
+
+## 5. Log to PM-LOG.md
+
+Append a timestamped entry:
+
+```markdown
+## [YYYY-MM-DD HH:MM:SS] POLL
+
+- Checked {N} tickets for phase {X}
+- Events: {list of transitions, or "No changes"}
+- Actions: {list of actions taken, or "None"}
+- Next: {what to expect}
+```
+
+For significant events (dispatch, replan, phase complete), use the specific event type instead of POLL:
+
+```markdown
+## [YYYY-MM-DD HH:MM:SS] DISPATCH
+
+- Dispatched wave {N}: {ticket list}
+- Executor: {name}
+
+## [YYYY-MM-DD HH:MM:SS] REPLAN
+
+- Failed ticket: {title} ({ticket_id})
+- Reason: {error details}
+- Fix plan created: {plan_name}
+- Fix ticket: {new_ticket_id}
+```
+
+</step>
+
+<step name="update_state">
+
+## 6. Update Persistent State
+
+### TICKET-MAP.md
+- Update status column for all changed tickets
+- Update last_polled timestamp
+- Add replan entries if applicable
+
+### STATE.md — Vibe Kanban Status section
+- Update ticket summary table
+- Update last_polled
+- Update PM loop status
+- Update next action description
+- Update Recent Ticket Events (keep last 5)
+
+</step>
+
+</process>