claude-cook 1.10.5 → 1.10.6

package/agents/cook-planner.md

@@ -61,6 +61,14 @@ Claude degrades when it perceives context pressure and enters "completion mode."
 
 **Aggressive atomicity:** More plans, smaller scope, consistent quality. Each plan: 2-3 tasks max.
 
+
+## PRD Slicing Rule
+
+Every PLAN.md must represent **one PRD slice** (one user-facing capability).
+- If a phase requirement includes multiple capabilities or flows, split into multiple PLAN.md files.
+- Aim for 1-2 acceptance criteria per plan; avoid bundled mega-plans.
+- The resulting plan should fit in a single, focused ticket.
+
 ## Ship Fast
 
 No enterprise process. No approval gates.

package/agents/cook-pm.md

@@ -81,6 +81,13 @@ When a worker fails:
 4. Dispatch a fresh worker on the fix
 5. Log everything to PM-LOG.md
 
+
+## Ticket Granularity (PRD-aligned)
+
+- Each ticket must map to a single PRD slice (one user-facing capability).
+- If a PLAN.md appears to bundle multiple capabilities, spawn the planner in revision mode to split it before syncing.
+- If acceptance criteria exceed 4-5 bullets, it is too large — split.
+
 ## Wave Discipline
 
 Plans have wave assignments. Respect them:
@@ -88,6 +95,13 @@ Plans have wave assignments. Respect them:
 - Wave 2 only after ALL wave 1 tickets are `done`
 - This prevents dependency conflicts between parallel workers
 
+## Autonomous Loop = Minimal User Interruptions
+
+When running under `/cook:pm-start` and `pm-loop.sh`, you MUST avoid asking the user questions.
+- Do **not** use AskUserQuestion in the autonomous loop.
+- If a choice is required, pick a safe default and **log the choice** in PM-LOG.md.
+- Only ask the user if a **critical, irreversible** decision cannot be made safely.
+
 </philosophy>
 
 <never_do>
@@ -190,7 +204,7 @@ For each ticket in TICKET-MAP.md:
 **On WAVE_COMPLETE:**
 1. Read config for `auto_dispatch_next_wave`
 2. If true: dispatch all wave N+1 tickets (see dispatch flow)
-3. If false: log and suggest `/pm:dispatch` to user
+3. If false: log and wait (no user prompt in autonomous mode)
 4. Update STATE.md wave summary
 
 **On FAILED:**
@@ -200,18 +214,18 @@ For each ticket in TICKET-MAP.md:
    - Spawn cook-planner in revision mode with failure context
    - Create fix plan → create fix ticket → dispatch
    - Increment replan_count in TICKET-MAP
-4. If false OR max reached: log failure, present to user
+4. If false OR max reached: log failure and wait (no user prompt in autonomous mode)
 
 **On STUCK:**
 1. Log a warning entry
 2. If autonomous mode: attempt re-dispatch with same executor
-3. If still stuck after 2 re-dispatches: escalate to user
+3. If still stuck after 2 re-dispatches: log escalation and wait
 
 **On PHASE_COMPLETE:**
 1. Update STATE.md: phase complete
 2. Update TICKET-MAP.md: phase_status = complete
 3. Log phase completion summary
-4. Present to user: "Phase X complete. Run /cook:pm-start {X+1} for next phase."
+4. No user prompt in autonomous mode (pm-cycle will advance phases automatically)
 
 **On NO_CHANGE:**
 1. Brief log entry: "No changes detected"

package/commands/cook/pm-start.md

@@ -1,7 +1,7 @@
 ---
 name: cook:pm-start
 description: Start fully autonomous PM — plans, syncs, dispatches, monitors, and advances phases automatically
-argument-hint: "<phase> [--manual] [--executor=CLAUDE_CODE] [--skip-plan] [--max-iterations=0] [--max-replans=3] [--calls=0]"
+argument-hint: "<phase> [--manual] [--background] [--executor=CLAUDE_CODE] [--skip-plan] [--max-iterations=0] [--max-replans=3] [--calls=0]"
 agent: cook-pm
 allowed-tools:
   - Read
@@ -38,7 +38,7 @@ Phase number: $ARGUMENTS (required — starting phase)
 
 **Flags:**
 - `--manual` — Don't launch the loop, manage manually with `/cook:pm-cycle`
-- `--background` — Run loop detached (default: foreground with live output)
+- `--background` — Run loop detached (default: background when autonomous)
 - `--executor=X` — Override default executor (CLAUDE_CODE, CURSOR_AGENT, CODEX, etc.)
 - `--skip-plan` — Skip initial planning, assume plans already exist
 - `--max-iterations=N` — Safety cap on loop cycles (default: 0 = unlimited)
@@ -176,53 +176,35 @@ Present:
 | ...    | ...  | ...      | launched |
 ```
 
-## 7. Launch PM Loop (default: foreground, live output)
+## 7. Launch PM Loop (default: background in autonomous mode)
 
-### Autonomous Mode (default) — FOREGROUND
+### Autonomous Mode (default) — BACKGROUND
 
-Launch pm-loop.sh in the **foreground** — the user sees live progress, cycle-by-cycle output, progress bars, and desktop notifications for key events. The PM actively reports what it's doing. The loop will automatically trigger `/cook:pm-replan` after repeated failures, up to the configured max.
+Launch pm-loop.sh in the **background** by default in autonomous mode. This avoids blocking the command while keeping the loop running. The loop will automatically trigger `/cook:pm-replan` after repeated failures, up to the configured max.
 
 ```bash
-~/.claude/scripts/pm-loop.sh --phase={X} --interval={poll_interval} --max-iterations={max_iterations}
+~/.claude/scripts/pm-loop.sh --phase={X} --interval={poll_interval} --max-iterations={max_iterations} --background
 ```
 
-The loop runs in the current terminal. The user sees:
-- Cycle headers with timestamps
-- Full pm-cycle output (banners, ticket tables, decisions)
-- Progress bars between cycles (done/running/todo counts)
-- Countdown to next cycle
-- Desktop notifications for: milestone complete, errors, phase advances
+Output goes to `.planning/pm-loop.log`. Desktop notifications still work in background mode (macOS/Linux).
 
-Stop with: `Ctrl+C` | `touch .planning/.pm-stop` | `/cook:pm-stop`
+Stop with: `touch .planning/.pm-stop` | `/cook:pm-stop`
 
-**Note:** This is a blocking call — it takes over the terminal. The PM actively reports to the user rather than hiding in a log file.
+If the user explicitly asks for foreground mode, run without `--background`.
 
-### Background Mode (--background)
+### Foreground Mode (explicit)
 
-If the user explicitly passes `--background`, launch detached:
+If the user explicitly asks for foreground/live output, launch without `--background`:
 
 ```bash
-~/.claude/scripts/pm-loop.sh --phase={X} --interval={poll_interval} --max-iterations={max_iterations} --background
-```
-
-This re-execs with nohup and exits immediately. Output goes to `.planning/pm-loop.log`.
-
-Desktop notifications still work in background mode (macOS/Linux).
-
-Present:
+~/.claude/scripts/pm-loop.sh --phase={X} --interval={poll_interval} --max-iterations={max_iterations}
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PM ► BACKGROUND MODE
 
-PM loop running (PID: {pid})
-Log: tail -f .planning/pm-loop.log
-Stop: /cook:pm-stop  or  touch .planning/.pm-stop
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
+This blocks the terminal and streams live output.
 
-### Manual Mode (--manual)
+### Manual Mode (--manual only)
 
-Don't launch the loop. User runs `/cook:pm-cycle` manually for each step.
+Only use manual mode if the user explicitly passes `--manual`. Otherwise always launch the loop.
 
 Present:
 ```

package/cook/workflows/pm-sync.md

@@ -60,6 +60,8 @@ Build three lists:
 
 **Ticket philosophy:** Tickets are Agile-style task assignments — atomic, isolated, and code-agnostic. They describe **what** to deliver and **why**, not **how** to implement it. The worker agent reads the codebase to figure out implementation. This makes tickets robust to codebase changes and readable by any stakeholder.
 
+**PRD-driven slicing:** Each ticket must map to a single PRD slice (one user-facing capability). If a plan spans multiple capabilities or flows, split it into multiple smaller plans before ticketing. Use REQUIREMENTS.md / PROJECT.md (or PRD.md if present) to identify the slice.
+
 For each new plan:
 
 1. Read the PLAN.md content
@@ -85,20 +87,32 @@ For each new plan:
 {One-paragraph summary of what to deliver. Written as a user story or task statement.
 Focus on the deliverable, not implementation details. No file paths, no function names, no code snippets.}
 
+## PRD Slice
+
+- **Feature/Capability:** {single PRD slice name}
+- **User Flow:** {entry point → key steps → outcome}
+- **In Scope:** {1-3 concrete deliverables}
+- **Out of Scope:** {explicit non-goals to prevent bloat}
+
 ## Why
 
 {Why this task matters for the project. What value it adds. What it unblocks.}
 
-## Acceptance Criteria
+## Acceptance Criteria (DoD)
 
 - [ ] {Observable behavior 1 — from must_haves.truths}
 - [ ] {Observable behavior 2}
 - [ ] {Deliverable exists — from must_haves.artifacts, described generically}
+- [ ] {No major regressions in related flows}
 
 ## Dependencies
 
 - {List ticket IDs this depends on, from depends_on field, or "None"}
 
+## QA Notes
+
+- {How to verify quickly (manual steps or simple checks)}
+
 ## Scope
 
 - Wave: {N}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-cook",
-  "version": "1.10.5",
+  "version": "1.10.6",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode and Gemini by TÂCHES.",
   "bin": {
     "claude-cook": "bin/install.js"