claude-cook 1.10.8 → 1.11.0

package/commands/cook/debug.md

@@ -1,169 +0,0 @@
----
-name: cook:debug
-description: Systematic debugging with persistent state across context resets
-argument-hint: [issue description]
-allowed-tools:
-  - Read
-  - Bash
-  - Task
-  - AskUserQuestion
----
-
-<objective>
-Debug issues using scientific method with subagent isolation.
-
-**Orchestrator role:** Gather symptoms, spawn cook-debugger agent, handle checkpoints, spawn continuations.
-
-**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
-</objective>
-
-<context>
-User's issue: $ARGUMENTS
-
-Check for active sessions:
-```bash
-ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
-```
-</context>
-
-<process>
-
-## 0. Resolve Model Profile
-
-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 |
-|-------|---------|----------|--------|
-| cook-debugger | opus | sonnet | sonnet |
-
-Store resolved model for use in Task calls below.
-
-## 1. Check Active Sessions
-
-If active sessions exist AND no $ARGUMENTS:
-- List sessions with status, hypothesis, next action
-- User picks number to resume OR describes new issue
-
-If $ARGUMENTS provided OR user describes new issue:
-- Continue to symptom gathering
-
-## 2. Gather Symptoms (if new issue)
-
-Use AskUserQuestion for each:
-
-1. **Expected behavior** - What should happen?
-2. **Actual behavior** - What happens instead?
-3. **Error messages** - Any errors? (paste or describe)
-4. **Timeline** - When did this start? Ever worked?
-5. **Reproduction** - How do you trigger it?
-
-After all gathered, confirm ready to investigate.
-
-## 3. Spawn cook-debugger Agent
-
-Fill prompt and spawn:
-
-```markdown
-<objective>
-Investigate issue: {slug}
-
-**Summary:** {trigger}
-</objective>
-
-<symptoms>
-expected: {expected}
-actual: {actual}
-errors: {errors}
-reproduction: {reproduction}
-timeline: {timeline}
-</symptoms>
-
-<mode>
-symptoms_prefilled: true
-goal: find_and_fix
-</mode>
-
-<debug_file>
-Create: .planning/debug/{slug}.md
-</debug_file>
-```
-
-```
-Task(
-  prompt=filled_prompt,
-  subagent_type="cook-debugger",
-  model="{debugger_model}",
-  description="Debug {slug}"
-)
-```
-
-## 4. Handle Agent Return
-
-**If `## ROOT CAUSE FOUND`:**
-- Display root cause and evidence summary
-- Offer options:
-  - "Fix now" - spawn fix subagent
-  - "Plan fix" - suggest /cook:plan-phase --gaps
-  - "Manual fix" - done
-
-**If `## CHECKPOINT REACHED`:**
-- Present checkpoint details to user
-- Get user response
-- Spawn continuation agent (see step 5)
-
-**If `## INVESTIGATION INCONCLUSIVE`:**
-- Show what was checked and eliminated
-- Offer options:
-  - "Continue investigating" - spawn new agent with additional context
-  - "Manual investigation" - done
-  - "Add more context" - gather more symptoms, spawn again
-
-## 5. Spawn Continuation Agent (After Checkpoint)
-
-When user responds to checkpoint, spawn fresh agent:
-
-```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: find_and_fix
-</mode>
-```
-
-```
-Task(
-  prompt=continuation_prompt,
-  subagent_type="cook-debugger",
-  model="{debugger_model}",
-  description="Continue debug {slug}"
-)
-```
-
-</process>
-
-<success_criteria>
-- [ ] Active sessions checked
-- [ ] Symptoms gathered (if new)
-- [ ] cook-debugger spawned with context
-- [ ] Checkpoints handled correctly
-- [ ] Root cause confirmed before fixing
-</success_criteria>

package/commands/cook/discuss-phase.md

@@ -1,86 +0,0 @@
----
-name: cook:discuss-phase
-description: Gather phase context through adaptive questioning before planning
-argument-hint: "<phase>"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-
-<objective>
-Extract implementation decisions that downstream agents need — researcher and planner will use CONTEXT.md to know what to investigate and what choices are locked.
-
-**How it works:**
-1. Analyze the phase to identify gray areas (UI, UX, behavior, etc.)
-2. Present gray areas — user selects which to discuss
-3. Deep-dive each selected area until satisfied
-4. Create CONTEXT.md with decisions that guide research and planning
-
-**Output:** `{phase}-CONTEXT.md` — decisions clear enough that downstream agents can act without asking the user again
-</objective>
-
-<execution_context>
-@~/.claude/cook/workflows/discuss-phase.md
-@~/.claude/cook/templates/context.md
-</execution_context>
-
-<context>
-Phase number: $ARGUMENTS (required)
-
-**Load project state:**
-@.planning/STATE.md
-
-**Load roadmap:**
-@.planning/ROADMAP.md
-</context>
-
-<process>
-1. Validate phase number (error if missing or not in roadmap)
-2. Check if CONTEXT.md exists (offer update/view/skip if yes)
-3. **Analyze phase** — Identify domain and generate phase-specific gray areas
-4. **Present gray areas** — Multi-select: which to discuss? (NO skip option)
-5. **Deep-dive each area** — 4 questions per area, then offer more/next
-6. **Write CONTEXT.md** — Sections match areas discussed
-7. Offer next steps (research or plan)
-
-**CRITICAL: Scope guardrail**
-- Phase boundary from ROADMAP.md is FIXED
-- Discussion clarifies HOW to implement, not WHETHER to add more
-- If user suggests new capabilities: "That's its own phase. I'll note it for later."
-- Capture deferred ideas — don't lose them, don't act on them
-
-**Domain-aware gray areas:**
-Gray areas depend on what's being built. Analyze the phase goal:
-- Something users SEE → layout, density, interactions, states
-- Something users CALL → responses, errors, auth, versioning
-- Something users RUN → output format, flags, modes, error handling
-- Something users READ → structure, tone, depth, flow
-- Something being ORGANIZED → criteria, grouping, naming, exceptions
-
-Generate 3-4 **phase-specific** gray areas, not generic categories.
-
-**Probing depth:**
-- Ask 4 questions per area before checking
-- "More questions about [area], or move to next?"
-- If more → ask 4 more, check again
-- After all areas → "Ready to create context?"
-
-**Do NOT ask about (Claude handles these):**
-- Technical implementation
-- Architecture choices
-- Performance concerns
-- Scope expansion
-</process>
-
-<success_criteria>
-- Gray areas identified through intelligent analysis
-- User chose which areas to discuss
-- Each selected area explored until satisfied
-- Scope creep redirected to deferred ideas
-- CONTEXT.md captures decisions, not vague vision
-- User knows next steps
-</success_criteria>

package/commands/cook/execute-phase.md

@@ -1,339 +0,0 @@
----
-name: cook:execute-phase
-description: Execute all plans in a phase with wave-based parallelization
-argument-hint: "<phase-number> [--gaps-only]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Glob
-  - Grep
-  - Bash
-  - Task
-  - TodoWrite
-  - AskUserQuestion
----
-
-<objective>
-Execute all plans in a phase using wave-based parallel execution.
-
-Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan.
-
-Context budget: ~15% orchestrator, 100% fresh per subagent.
-</objective>
-
-<execution_context>
-@~/.claude/cook/references/ui-brand.md
-@~/.claude/cook/workflows/execute-phase.md
-</execution_context>
-
-<context>
-Phase: $ARGUMENTS
-
-**Flags:**
-- `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans.
-
-@.planning/ROADMAP.md
-@.planning/STATE.md
-</context>
-
-<process>
-0. **Resolve Model Profile**
-
-   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 |
-   |-------|---------|----------|--------|
-   | cook-executor | opus | sonnet | sonnet |
-   | cook-verifier | sonnet | sonnet | haiku |
-
-   Store resolved models for use in Task calls below.
-
-1. **Validate phase exists**
-   - Find phase directory matching argument
-   - Count PLAN.md files
-   - Error if no plans found
-
-2. **Discover plans**
-   - List all *-PLAN.md files in phase directory
-   - Check which have *-SUMMARY.md (already complete)
-   - If `--gaps-only`: filter to only plans with `gap_closure: true`
-   - Build list of incomplete plans
-
-3. **Group by wave**
-   - Read `wave` from each plan's frontmatter
-   - Group plans by wave number
-   - Report wave structure to user
-
-4. **Execute waves**
-   For each wave in order:
-   - Spawn `cook-executor` for each plan in wave (parallel Task calls)
-   - Wait for completion (Task blocks)
-   - Verify SUMMARYs created
-   - Proceed to next wave
-
-5. **Aggregate results**
-   - Collect summaries from all plans
-   - Report phase completion status
-
-6. **Commit any orchestrator corrections**
-   Check for uncommitted changes before verification:
-   ```bash
-   git status --porcelain
-   ```
-
-   **If changes exist:** Orchestrator made corrections between executor completions. Commit them:
-   ```bash
-   git add -u && git commit -m "fix({phase}): orchestrator corrections"
-   ```
-
-   **If clean:** Continue to verification.
-
-7. **Verify phase goal**
-   Check config: `WORKFLOW_VERIFIER=$(cat .planning/config.json 2>/dev/null | grep -o '"verifier"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")`
-
-   **If `workflow.verifier` is `false`:** Skip to step 8 (treat as passed).
-
-   **Otherwise:**
-   - Spawn `cook-verifier` subagent with phase directory and goal
-   - Verifier checks must_haves against actual codebase (not SUMMARY claims)
-   - Creates VERIFICATION.md with detailed report
-   - Route by status:
-     - `passed` → continue to step 8
-     - `human_needed` → present items, get approval or feedback
-     - `gaps_found` → present gaps, offer `/cook:plan-phase {X} --gaps`
-
-8. **Update roadmap and state**
-   - Update ROADMAP.md, STATE.md
-
-9. **Update requirements**
-   Mark phase requirements as Complete:
-   - Read ROADMAP.md, find this phase's `Requirements:` line (e.g., "AUTH-01, AUTH-02")
-   - Read REQUIREMENTS.md traceability table
-   - For each REQ-ID in this phase: change Status from "Pending" to "Complete"
-   - Write updated REQUIREMENTS.md
-   - Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line
-
-10. **Commit phase completion**
-    Check `COMMIT_PLANNING_DOCS` from config.json (default: true).
-    If false: Skip git operations for .planning/ files.
-    If true: Bundle all phase metadata updates in one commit:
-    - Stage: `git add .planning/ROADMAP.md .planning/STATE.md`
-    - Stage REQUIREMENTS.md if updated: `git add .planning/REQUIREMENTS.md`
-    - Commit: `docs({phase}): complete {phase-name} phase`
-
-11. **Offer next steps**
-    - Route to next action (see `<offer_next>`)
-</process>
-
-<offer_next>
-Output this markdown directly (not as a code block). Route based on status:
-
-| Status | Route |
-|--------|-------|
-| `gaps_found` | Route C (gap closure) |
-| `human_needed` | Present checklist, then re-route based on approval |
-| `passed` + more phases | Route A (next phase) |
-| `passed` + last phase | Route B (milestone complete) |
-
----
-
-**Route A: Phase verified, more phases remain**
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- COOK ► PHASE {Z} COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Phase {Z}: {Name}**
-
-{Y} plans executed
-Goal verified ✓
-
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
-
-/cook:discuss-phase {Z+1} — gather context and clarify approach
-
-<sub>/clear first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
-
-**Also available:**
-- /cook:plan-phase {Z+1} — skip discussion, plan directly
-- /cook:verify-work {Z} — manual acceptance testing before continuing
-
-───────────────────────────────────────────────────────────────
-
----
-
-**Route B: Phase verified, milestone complete**
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- COOK ► MILESTONE COMPLETE 🎉
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**v1.0**
-
-{N} phases completed
-All phase goals verified ✓
-
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Audit milestone** — verify requirements, cross-phase integration, E2E flows
-
-/cook:audit-milestone
-
-<sub>/clear first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
-
-**Also available:**
-- /cook:verify-work — manual acceptance testing
-- /cook:complete-milestone — skip audit, archive directly
-
-───────────────────────────────────────────────────────────────
-
----
-
-**Route C: Gaps found — need additional planning**
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- COOK ► PHASE {Z} GAPS FOUND ⚠
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Phase {Z}: {Name}**
-
-Score: {N}/{M} must-haves verified
-Report: .planning/phases/{phase_dir}/{phase}-VERIFICATION.md
-
-### What's Missing
-
-{Extract gap summaries from VERIFICATION.md}
-
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Plan gap closure** — create additional plans to complete the phase
-
-/cook:plan-phase {Z} --gaps
-
-<sub>/clear first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
-
-**Also available:**
-- cat .planning/phases/{phase_dir}/{phase}-VERIFICATION.md — see full report
-- /cook:verify-work {Z} — manual testing before planning
-
-───────────────────────────────────────────────────────────────
-
----
-
-After user runs /cook:plan-phase {Z} --gaps:
-1. Planner reads VERIFICATION.md gaps
-2. Creates plans 04, 05, etc. to close gaps
-3. User runs /cook:execute-phase {Z} again
-4. Execute-phase runs incomplete plans (04, 05...)
-5. Verifier runs again → loop until passed
-</offer_next>
-
-<wave_execution>
-**Parallel spawning:**
-
-Before spawning, read file contents. The `@` syntax does not work across Task() boundaries.
-
-```bash
-# Read each plan and STATE.md
-PLAN_01_CONTENT=$(cat "{plan_01_path}")
-PLAN_02_CONTENT=$(cat "{plan_02_path}")
-PLAN_03_CONTENT=$(cat "{plan_03_path}")
-STATE_CONTENT=$(cat .planning/STATE.md)
-```
-
-Spawn all plans in a wave with a single message containing multiple Task calls, with inlined content:
-
-```
-Task(prompt="Execute plan at {plan_01_path}\n\nPlan:\n{plan_01_content}\n\nProject state:\n{state_content}", subagent_type="cook-executor", model="{executor_model}")
-Task(prompt="Execute plan at {plan_02_path}\n\nPlan:\n{plan_02_content}\n\nProject state:\n{state_content}", subagent_type="cook-executor", model="{executor_model}")
-Task(prompt="Execute plan at {plan_03_path}\n\nPlan:\n{plan_03_content}\n\nProject state:\n{state_content}", subagent_type="cook-executor", model="{executor_model}")
-```
-
-All three run in parallel. Task tool blocks until all complete.
-
-**No polling.** No background agents. No TaskOutput loops.
-</wave_execution>
-
-<checkpoint_handling>
-Plans with `autonomous: false` have checkpoints. The execute-phase.md workflow handles the full checkpoint flow:
-- Subagent pauses at checkpoint, returns structured state
-- Orchestrator presents to user, collects response
-- Spawns fresh continuation agent (not resume)
-
-See `@~/.claude/cook/workflows/execute-phase.md` step `checkpoint_handling` for complete details.
-</checkpoint_handling>
-
-<deviation_rules>
-During execution, handle discoveries automatically:
-
-1. **Auto-fix bugs** - Fix immediately, document in Summary
-2. **Auto-add critical** - Security/correctness gaps, add and document
-3. **Auto-fix blockers** - Can't proceed without fix, do it and document
-4. **Ask about architectural** - Major structural changes, stop and ask user
-
-Only rule 4 requires user intervention.
-</deviation_rules>
-
-<commit_rules>
-**Per-Task Commits:**
-
-After each task completes:
-1. Stage only files modified by that task
-2. Commit with format: `{type}({phase}-{plan}): {task-name}`
-3. Types: feat, fix, test, refactor, perf, chore
-4. Record commit hash for SUMMARY.md
-
-**Plan Metadata Commit:**
-
-After all tasks in a plan complete:
-1. Stage plan artifacts only: PLAN.md, SUMMARY.md
-2. Commit with format: `docs({phase}-{plan}): complete [plan-name] plan`
-3. NO code files (already committed per-task)
-
-**Phase Completion Commit:**
-
-After all plans in phase complete (step 7):
-1. Stage: ROADMAP.md, STATE.md, REQUIREMENTS.md (if updated), VERIFICATION.md
-2. Commit with format: `docs({phase}): complete {phase-name} phase`
-3. Bundles all phase-level state updates in one commit
-
-**NEVER use:**
-- `git add .`
-- `git add -A`
-- `git add src/` or any broad directory
-
-**Always stage files individually.**
-</commit_rules>
-
-<success_criteria>
-- [ ] All incomplete plans in phase executed
-- [ ] Each plan has SUMMARY.md
-- [ ] Phase goal verified (must_haves checked against codebase)
-- [ ] VERIFICATION.md created in phase directory
-- [ ] STATE.md reflects phase completion
-- [ ] ROADMAP.md updated
-- [ ] REQUIREMENTS.md updated (phase requirements marked Complete)
-- [ ] User informed of next steps
-</success_criteria>

package/commands/cook/list-phase-assumptions.md

@@ -1,50 +0,0 @@
----
-name: cook:list-phase-assumptions
-description: Surface Claude's assumptions about a phase approach before planning
-argument-hint: "[phase]"
-allowed-tools:
-  - Read
-  - Bash
-  - Grep
-  - Glob
----
-
-<objective>
-Analyze a phase and present Claude's assumptions about technical approach, implementation order, scope boundaries, risk areas, and dependencies.
-
-Purpose: Help users see what Claude thinks BEFORE planning begins - enabling course correction early when assumptions are wrong.
-Output: Conversational output only (no file creation) - ends with "What do you think?" prompt
-</objective>
-
-<execution_context>
-@~/.claude/cook/workflows/list-phase-assumptions.md
-</execution_context>
-
-<context>
-Phase number: $ARGUMENTS (required)
-
-**Load project state first:**
-@.planning/STATE.md
-
-**Load roadmap:**
-@.planning/ROADMAP.md
-</context>
-
-<process>
-1. Validate phase number argument (error if missing or invalid)
-2. Check if phase exists in roadmap
-3. Follow list-phase-assumptions.md workflow:
-   - Analyze roadmap description
-   - Surface assumptions about: technical approach, implementation order, scope, risks, dependencies
-   - Present assumptions clearly
-   - Prompt "What do you think?"
-4. Gather feedback and offer next steps
-</process>
-
-<success_criteria>
-
-- Phase validated against roadmap
-- Assumptions surfaced across five areas
-- User prompted for feedback
-- User knows next steps (discuss context, plan phase, or correct assumptions)
-  </success_criteria>