claude-cook 1.10.1 → 1.10.2

package/commands/gsd/pm-cycle.md

@@ -0,0 +1,284 @@
+---
+name: gsd:pm-cycle
+description: Full-brain autonomous PM cycle — reads state, decides, acts, exits
+argument-hint: "[phase]"
+agent: gsd-pm
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - mcp__vibe_kanban__*
+  - mcp__context7__*
+---
+
+<execution_context>
+@~/.claude/get-shit-done/references/ui-brand.md
+@~/.claude/get-shit-done/references/vibe-kanban.md
+@~/.claude/get-shit-done/workflows/pm-cycle.md
+@~/.claude/get-shit-done/workflows/pm-check.md
+@~/.claude/get-shit-done/workflows/pm-sync.md
+@~/.claude/get-shit-done/workflows/pm-dispatch.md
+@~/.claude/get-shit-done/workflows/pm-replan.md
+</execution_context>
+
+<objective>
+**The autonomous PM brain.** Each invocation is a stateless decision engine — reads all persistent state, decides the single most important action to take, executes it, updates state, and exits.
+
+Called by `pm-loop.sh` on every cycle. Each call gets a fresh 200k context. State persists via `.planning/` files.
+
+**This is the Ralph-style loop brain.** One command runs the entire PM lifecycle: plan → sync → dispatch → monitor → replan → advance phase → complete milestone.
+</objective>
+
+<context>
+Phase hint: $ARGUMENTS (optional — auto-detected from STATE.md if not provided)
+</context>
+
+<process>
+
+## 1. Load All State
+
+Read these files (all reads in parallel):
+
+```
+.planning/config.json       → PM config (project_id, repos, executor, toggles)
+.planning/STATE.md          → Current position (phase, status, decisions)
+.planning/ROADMAP.md        → Phase structure, goals, milestone scope
+.planning/PM-LOG.md         → Recent activity (tail last 20 lines)
+```
+
+If `$ARGUMENTS` provides a phase number, use it. Otherwise, detect from STATE.md.
+
+Identify:
+- `current_phase`: phase number being worked on
+- `phase_dir`: `.planning/phases/{phase-dir}/`
+- `pm_config`: the `pm` section from config.json
+
+If no `.planning/` directory or no `config.json` with `pm` section:
+```
+No PM configuration found. Run /gsd:pm-start to initialize.
+```
+Exit with code 0.
+
+## 2. Assess Phase State
+
+Check the current phase directory:
+
+```bash
+# Count plans, tickets, summaries
+ls -1 .planning/phases/{phase_dir}/*-PLAN.md 2>/dev/null | wc -l
+ls -1 .planning/phases/{phase_dir}/TICKET-MAP.md 2>/dev/null | wc -l
+```
+
+Read TICKET-MAP.md if it exists. Parse ticket statuses.
+
+Classify the phase into exactly ONE state:
+
+| State | Condition |
+|-------|-----------|
+| `NEEDS_PLANNING` | No PLAN.md files in phase directory |
+| `NEEDS_SYNC` | PLAN.md files exist but no TICKET-MAP.md |
+| `NEEDS_DISPATCH` | TICKET-MAP.md exists with `todo` tickets in a ready wave |
+| `MONITORING` | Tickets are `inprogress` — workers running |
+| `PHASE_COMPLETE` | All tickets in TICKET-MAP.md are `done` |
+| `MILESTONE_COMPLETE` | Current phase is the last phase AND it's complete |
+
+State: "Phase {X} state: {STATE}"
+
+## 3. Execute Single Action
+
+Based on the classified state, execute ONE action per cycle. Each action updates state and exits — the shell loop handles continuation.
+
+---
+
+### Action: NEEDS_PLANNING
+
+Spawn gsd-planner agent to create plans for this phase.
+
+```
+Spawning planner for Phase {X}: {name}...
+```
+
+Use Task tool to spawn gsd-planner:
+- Provide phase goal from ROADMAP.md
+- Provide PROJECT.md context
+- Wait for plans to be written
+
+Then spawn gsd-plan-checker to verify plan quality.
+
+Update STATE.md: set phase status to "planned".
+
+Log to PM-LOG.md:
+```markdown
+## [{TIMESTAMP}] PLANNED
+
+- Phase {X}: {plan_count} plans created
+- Plans: {list plan names}
+```
+
+**Exit code 0** — next cycle will sync.
+
+---
+
+### Action: NEEDS_SYNC
+
+Run pm-sync workflow:
+1. Read all PLAN.md files in phase directory
+2. For each plan, call `mcp__vibe_kanban__create_task` with:
+   - Title: "Phase {X} Plan {Y}: {objective}"
+   - Description: Full PLAN.md content (this IS the worker's prompt)
+3. Write TICKET-MAP.md with all mappings
+
+Update STATE.md: set phase status to "synced".
+
+Log to PM-LOG.md:
+```markdown
+## [{TIMESTAMP}] SYNCED
+
+- Phase {X}: {ticket_count} tickets created
+- Project: {project_id}
+```
+
+**Exit code 0** — next cycle will dispatch.
+
+---
+
+### Action: NEEDS_DISPATCH
+
+Run pm-dispatch workflow:
+1. Identify the next ready wave (all prior waves complete)
+2. For each `todo` ticket in this wave:
+   - Call `mcp__vibe_kanban__start_workspace_session` with:
+     - task_id, executor, repos (from config)
+   - Update TICKET-MAP.md: status → inprogress, dispatched timestamp
+3. Log dispatch to PM-LOG.md
+
+Update STATE.md: set phase status to "dispatched, wave {N}".
+
+Log to PM-LOG.md:
+```markdown
+## [{TIMESTAMP}] DISPATCHED
+
+- Wave {N}: {count} workers launched
+- Executor: {executor}
+- Tickets: {list ticket IDs}
+```
+
+**Exit code 0** — next cycle will monitor.
+
+---
+
+### Action: MONITORING
+
+Run pm-check workflow:
+1. Poll VK: `mcp__vibe_kanban__list_tasks(project_id)`
+2. Diff against TICKET-MAP.md
+3. Classify events and react:
+
+**For each completed ticket:**
+- Update TICKET-MAP.md: status → done, completed timestamp
+- Log completion
+
+**For each failed/cancelled ticket:**
+- If `auto_replan_on_failure` is true in config:
+  - Run pm-replan workflow (TARGETED scope)
+  - Create fix ticket, dispatch it
+- Else: log failure, continue monitoring
+
+**If wave complete (all tickets in current wave done):**
+- If `auto_dispatch_next_wave` is true AND more waves exist:
+  - Run pm-dispatch for next wave
+- Else: log wave completion
+
+**If all tickets done:**
+- This is actually PHASE_COMPLETE — will be caught next cycle
+
+**If no changes detected:**
+- Brief log only: "No changes. {N} tickets inprogress."
+
+Update STATE.md + TICKET-MAP.md + PM-LOG.md.
+
+**Exit code 0** — next cycle continues monitoring or advances.
+
+---
+
+### Action: PHASE_COMPLETE
+
+1. Read ROADMAP.md
+2. Identify next phase number
+3. If next phase exists:
+   - Update STATE.md: advance to next phase, status "pending"
+   - Log phase completion
+
+```markdown
+## [{TIMESTAMP}] PHASE_COMPLETE
+
+- Phase {X}: all {N} tickets done
+- Duration: {start} → {end}
+- Advancing to Phase {X+1}: {name}
+```
+
+**Exit code 0** — next cycle will plan the new phase.
+
+4. If no next phase → this is MILESTONE_COMPLETE.
+
+---
+
+### Action: MILESTONE_COMPLETE
+
+1. Log milestone completion:
+
+```markdown
+## [{TIMESTAMP}] MILESTONE_COMPLETE
+
+- All {N} phases complete
+- Total tickets: {count}
+- Duration: {start} → {end}
+```
+
+2. Create stop signal:
+```bash
+touch .planning/.pm-stop
+```
+
+3. Update STATE.md: milestone status "complete"
+
+4. Present:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PM ► MILESTONE COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+All phases complete. PM loop will stop on next cycle.
+
+Run /gsd:complete-milestone to archive and plan next.
+```
+
+**Exit with code 42** — signals shell loop to stop.
+
+---
+
+## 4. Cycle Summary
+
+After executing the action, output a brief cycle summary:
+
+```
+[{TIMESTAMP}] Cycle complete — State: {STATE} → Action: {ACTION}
+```
+
+This is the only user-visible output per cycle (pm-loop.sh captures it).
+
+</process>
+
+<constraints>
+- **One action per cycle.** Never do two lifecycle steps in one invocation. Let the loop handle progression.
+- **Never write code.** You are a PM. You plan, delegate, monitor, replan. Workers write code.
+- **Trust the files.** All truth is in .planning/ files. Don't assume or remember across cycles.
+- **Exit codes matter.** 0 = continue, 42 = milestone done (stop loop), 1 = error.
+- **Log everything.** Every action gets a PM-LOG.md entry with timestamp.
+- **Respect wave discipline.** Never dispatch wave N+1 until all wave N tickets are done.
+- **Replan, don't panic.** Failed tickets get auto-replanned, not abandoned.
+</constraints>

package/commands/gsd/pm-start.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:pm-start
-description: Plan a phase, sync to Vibe Kanban tickets, dispatch workers, optionally start autonomous monitor loop
-argument-hint: "<phase> [--autonomous] [--manual] [--executor=CLAUDE_CODE] [--skip-plan]"
+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]"
 agent: gsd-pm
 allowed-tools:
   - Read
@@ -24,21 +24,23 @@ allowed-tools:
 </execution_context>
 
 <objective>
-Initialize PM mode for a phase: create plans (unless --skip-plan), sync to Vibe Kanban tickets, dispatch wave 1 workers, and optionally launch the autonomous monitoring loop.
+Start the fully autonomous PM agent. Validates environment, sets up VK connection, and launches `pm-loop.sh` — the Ralph-style infinite loop that handles the ENTIRE lifecycle:
 
-**This is the main PM entry point.** It transitions GSD from local execution to external delegation.
+**plan → sync tickets → dispatch workers → monitor → replan on failure → advance phases → complete milestone**
 
-**Orchestrator role:** Validate environment, run planning pipeline if needed, sync plans to VK tickets, dispatch workers, optionally start pm-loop.sh.
+After this command, the PM runs unattended. Each loop cycle is a fresh Claude invocation via `/gsd:pm-cycle` — no context rot.
+
+Use `--manual` to skip the loop and manage phases manually with `/gsd:pm-cycle`.
 </objective>
 
 <context>
-Phase number: $ARGUMENTS (required — which phase to manage)
+Phase number: $ARGUMENTS (required — starting phase)
 
 **Flags:**
-- `--autonomous` — After dispatch, launch pm-loop.sh for continuous monitoring
-- `--manual` — After dispatch, show status and available commands (default)
+- `--manual` — Don't launch the loop, manage manually with `/gsd:pm-cycle`
 - `--executor=X` — Override default executor (CLAUDE_CODE, CURSOR_AGENT, CODEX, etc.)
-- `--skip-plan` — Skip planning, assume plans already exist (use with /gsd:plan-phase)
+- `--skip-plan` — Skip initial planning, assume plans already exist
+- `--max-iterations=N` — Safety cap on loop cycles (default: 0 = unlimited)
 </context>
 
 <process>
@@ -168,15 +170,14 @@ Present:
 | ...    | ...  | ...      | launched |
 ```
 
-## 7. Start Monitor (mode-dependent)
+## 7. Launch PM Loop (default: autonomous)
 
-### Autonomous Mode (--autonomous)
+### Autonomous Mode (default)
 
-Initialize PM-LOG.md with INIT entry.
-Launch pm-loop.sh:
+Launch pm-loop.sh — the Ralph-style infinite loop that calls `/gsd:pm-cycle` each iteration. The brain handles everything from here: monitoring, wave advancement, replanning, phase progression.
 
 ```bash
-nohup ~/.claude/scripts/pm-loop.sh --phase={X} --interval={poll_interval} > /dev/null 2>&1 &
+nohup ~/.claude/scripts/pm-loop.sh --phase={X} --interval={poll_interval} --max-iterations={max_iterations} > .planning/pm-loop.log 2>&1 &
 echo $! > .planning/.pm-loop-pid
 ```
 
@@ -187,26 +188,32 @@ Present:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 PM loop running (PID: {pid})
+Brain: /gsd:pm-cycle (full lifecycle per iteration)
 Polling every {interval}s
 Log: .planning/PM-LOG.md
 
+The PM will autonomously:
+  plan → sync → dispatch → monitor → replan → advance phases
+
 Stop with: /gsd:pm-stop  or  touch .planning/.pm-stop
+Status: /gsd:pm-status
 ```
 
-### Manual Mode (default)
+### Manual Mode (--manual)
+
+Don't launch the loop. User runs `/gsd:pm-cycle` manually for each step.
 
 Present:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PM ► MANUAL MODE — WORKERS RUNNING
+ PM ► MANUAL MODE
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Workers dispatched. Use these commands to manage:
+Workers dispatched. Run these commands to manage:
 
-/gsd:pm-check    — Poll ticket status and react
+/gsd:pm-cycle    — Run one full-brain cycle (decides + acts)
 /gsd:pm-status   — View dashboard
-/gsd:pm-replan   — Modify plans if issues found
-/gsd:pm-stop     — Stop PM monitoring
+/gsd:pm-replan   — Modify plans with feedback
 ```
 
 ## 8. Update STATE.md

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

@@ -0,0 +1,144 @@
+# PM Cycle Workflow — Full-Brain Autonomous Decision Engine
+
+## Overview
+
+This workflow powers `/gsd:pm-cycle` — the autonomous PM brain. Each invocation reads all state, classifies the situation, executes one action, updates state, and exits. The shell loop (`pm-loop.sh`) handles repetition.
+
+## State Classification
+
+Read phase directory and TICKET-MAP.md to classify into exactly one state:
+
+```
+NEEDS_PLANNING    → No PLAN.md files
+NEEDS_SYNC        → Plans exist, no TICKET-MAP.md
+NEEDS_DISPATCH    → TICKET-MAP has todo tickets in ready wave
+MONITORING        → Tickets inprogress
+PHASE_COMPLETE    → All tickets done, more phases in roadmap
+MILESTONE_COMPLETE → All tickets done, last phase in roadmap
+```
+
+## State Machine
+
+```
+NEEDS_PLANNING ──spawn planner──→ NEEDS_SYNC
+NEEDS_SYNC ──create tickets──→ NEEDS_DISPATCH
+NEEDS_DISPATCH ──launch workers──→ MONITORING
+MONITORING ──poll + react──→ MONITORING (loop)
+                          ──→ NEEDS_DISPATCH (wave complete, next wave ready)
+                          ──→ PHASE_COMPLETE (all done)
+                          ──→ MONITORING + replan (ticket failed)
+PHASE_COMPLETE ──advance phase──→ NEEDS_PLANNING (next phase)
+                              ──→ MILESTONE_COMPLETE (last phase)
+MILESTONE_COMPLETE ──stop signal──→ EXIT
+```
+
+## Action Details
+
+### NEEDS_PLANNING
+
+**Goal:** Create PLAN.md files for the current phase.
+
+1. Read ROADMAP.md for phase goal and scope
+2. Read PROJECT.md for project context
+3. Spawn gsd-planner agent via Task tool:
+   - Provide: phase number, goal, project context, any prior learnings from PM-LOG
+   - Agent writes PLAN.md files to phase directory
+4. Spawn gsd-plan-checker agent via Task tool:
+   - Verify plans against phase goal
+   - Max 3 planner↔checker iterations
+5. Update STATE.md: phase status → "planned"
+6. Log to PM-LOG.md
+
+### NEEDS_SYNC
+
+**Goal:** Create Vibe Kanban tickets for each plan.
+
+Follow `pm-sync.md` workflow:
+1. Read all PLAN.md files in phase directory
+2. For each plan:
+   - Extract objective, wave number from frontmatter
+   - Create VK ticket: `mcp__vibe_kanban__create_task(project_id, title, description)`
+   - Description = full PLAN.md content (worker's complete prompt)
+3. Write TICKET-MAP.md with mapping table
+4. Update STATE.md: phase status → "synced"
+5. Log to PM-LOG.md
+
+### NEEDS_DISPATCH
+
+**Goal:** Launch worker agents for the next ready wave.
+
+Follow `pm-dispatch.md` workflow:
+1. Parse TICKET-MAP.md for wave structure
+2. Identify next undispatched wave where all prior waves are done
+3. For each `todo` ticket in target wave:
+   - Call `mcp__vibe_kanban__start_workspace_session`:
+     - task_id: from TICKET-MAP
+     - executor: from config (default: CLAUDE_CODE)
+     - repos: from config (repo_id + base_branch)
+   - Update TICKET-MAP: status → inprogress, dispatched timestamp
+4. Update STATE.md: phase status → "dispatched, wave {N}"
+5. Log to PM-LOG.md
+
+### MONITORING
+
+**Goal:** Poll ticket status, react to changes.
+
+Follow `pm-check.md` workflow:
+1. Call `mcp__vibe_kanban__list_tasks(project_id)`
+2. Diff current status against TICKET-MAP.md last-known status
+3. For each change:
+
+| Event | Reaction |
+|-------|----------|
+| Ticket: todo → inprogress | Update TICKET-MAP (worker started) |
+| Ticket: inprogress → done | Update TICKET-MAP, check wave completion |
+| Ticket: inprogress → inreview | Update TICKET-MAP (awaiting review) |
+| Ticket: any → cancelled | If auto_replan: run pm-replan (TARGETED). Else: log warning |
+| Wave complete | If auto_dispatch_next_wave: dispatch next wave. Else: log |
+| All tickets done | Mark as PHASE_COMPLETE (caught next cycle) |
+| No changes | Log: "No changes. {N} inprogress, {M} todo." |
+
+4. Update TICKET-MAP.md + STATE.md + PM-LOG.md
+
+**Stuck detection:** If a ticket has been `inprogress` for longer than 30 minutes (configurable), log a warning. After 60 minutes, consider re-dispatching with a different executor.
+
+### PHASE_COMPLETE
+
+**Goal:** Advance to next phase in roadmap.
+
+1. Read ROADMAP.md
+2. Find next phase after current
+3. If next phase exists:
+   - Update STATE.md: current_phase → next phase, status → "pending"
+   - Log: "Phase {X} complete. Advancing to Phase {X+1}: {name}"
+4. If no next phase:
+   - This is MILESTONE_COMPLETE
+
+### MILESTONE_COMPLETE
+
+**Goal:** Signal completion, stop loop.
+
+1. Log: "Milestone complete. All {N} phases done."
+2. Write `.planning/.pm-stop` file (signals pm-loop.sh to exit)
+3. Update STATE.md: milestone_status → "complete"
+4. Exit with code 42
+
+## PM-LOG Entry Format
+
+Every action writes a timestamped entry:
+
+```markdown
+## [{YYYY-MM-DD HH:MM:SS}] {ACTION}
+
+- {detail 1}
+- {detail 2}
+- State: {previous} → {new}
+```
+
+## Error Handling
+
+- VK API errors: Log error, exit with code 1 (shell loop retries next cycle)
+- Planner spawn failure: Log error, exit with code 1
+- Dispatch failure (single ticket): Skip that ticket, continue with others, log
+- All dispatches fail: Log error, exit with code 1
+- State file missing: Log error, suggest `/gsd:pm-start`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-cook",
-  "version": "1.10.1",
+  "version": "1.10.2",
   "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"

package/scripts/pm-loop.sh

@@ -1,12 +1,16 @@
 #!/bin/bash
-# pm-loop.sh — Autonomous PM monitor loop
+# pm-loop.sh — Fully autonomous PM loop (Ralph-style)
 #
-# Runs an infinite loop that invokes claude CLI with /gsd:pm-check on each cycle.
+# Runs an infinite loop. Each iteration invokes claude CLI with /gsd:pm-cycle —
+# the full-brain PM that reads state, decides what to do, acts, and exits.
 # Each invocation is a fresh 200k context — no context rot.
-# State persists via .planning/ files (TICKET-MAP.md, STATE.md, PM-LOG.md).
+# State persists via .planning/ files.
+#
+# The PM brain handles the ENTIRE lifecycle autonomously:
+#   plan → sync tickets → dispatch workers → monitor → replan → advance phases → complete milestone
 #
 # Usage:
-#   ./scripts/pm-loop.sh [--phase=N] [--interval=60]
+#   ./scripts/pm-loop.sh [--phase=N] [--interval=60] [--max-iterations=50]
 #   PM_PHASE=1 PM_POLL_INTERVAL=30 ./scripts/pm-loop.sh
 #
 # Stop:
@@ -14,7 +18,7 @@
 #   OR run /gsd:pm-stop
 #
 # Background:
-#   nohup ./scripts/pm-loop.sh --phase=1 > /dev/null 2>&1 &
+#   nohup ./scripts/pm-loop.sh --phase=1 > .planning/pm-loop.log 2>&1 &
 
 set -euo pipefail
 
@@ -22,6 +26,7 @@ set -euo pipefail
 
 PHASE="${PM_PHASE:-}"
 INTERVAL="${PM_POLL_INTERVAL:-60}"
+MAX_ITERS="${PM_MAX_ITERATIONS:-0}"  # 0 = unlimited
 
 for arg in "$@"; do
   case $arg in
@@ -31,14 +36,27 @@ for arg in "$@"; do
     --interval=*)
       INTERVAL="${arg#*=}"
       ;;
+    --max-iterations=*)
+      MAX_ITERS="${arg#*=}"
+      ;;
     --help|-h)
-      echo "Usage: pm-loop.sh [--phase=N] [--interval=60]"
+      echo "Usage: pm-loop.sh [--phase=N] [--interval=60] [--max-iterations=0]"
+      echo ""
+      echo "Fully autonomous PM loop. Each cycle invokes /gsd:pm-cycle which"
+      echo "reads state and decides what to do: plan, sync, dispatch, monitor,"
+      echo "replan, advance phases, or complete milestone."
+      echo ""
+      echo "Options:"
+      echo "  --phase=N           Starting phase number (auto-detected if omitted)"
+      echo "  --interval=N        Seconds between cycles (default: 60)"
+      echo "  --max-iterations=N  Safety cap on cycles (default: 0 = unlimited)"
       echo ""
       echo "Environment variables:"
-      echo "  PM_PHASE           Phase number to monitor"
-      echo "  PM_POLL_INTERVAL   Seconds between poll cycles (default: 60)"
+      echo "  PM_PHASE             Phase number"
+      echo "  PM_POLL_INTERVAL     Seconds between cycles (default: 60)"
+      echo "  PM_MAX_ITERATIONS    Max cycles (default: 0 = unlimited)"
       echo ""
-      echo "Stop: touch .planning/.pm-stop"
+      echo "Stop: touch .planning/.pm-stop  OR  /gsd:pm-stop"
       exit 0
       ;;
     *)
@@ -73,7 +91,7 @@ CYCLE=0
 # Clean any stale stop signal
 rm -f "$STOP_FILE"
 
-# Record PID for /pm:stop
+# Record PID for /gsd:pm-stop
 echo $$ > "$PID_FILE"
 
 # ─── Init log ─────────────────────────────────────────────────────
@@ -88,6 +106,7 @@ Started: $TIMESTAMP
 Mode: autonomous
 Poll interval: ${INTERVAL}s
 Phase: ${PHASE:-auto}
+Max iterations: ${MAX_ITERS:-unlimited}
 
 ---
 
@@ -100,12 +119,16 @@ echo "" >> "$LOG_FILE"
 echo "- PM loop started (PID: $$)" >> "$LOG_FILE"
 echo "- Phase: ${PHASE:-auto-detect}" >> "$LOG_FILE"
 echo "- Interval: ${INTERVAL}s" >> "$LOG_FILE"
+echo "- Max iterations: ${MAX_ITERS:-unlimited}" >> "$LOG_FILE"
 
 # ─── Main loop ────────────────────────────────────────────────────
 
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo " PM Loop — Phase: ${PHASE:-auto} | Interval: ${INTERVAL}s"
 echo " PID: $$ | Stop: touch $STOP_FILE"
+if [ "$MAX_ITERS" -gt 0 ] 2>/dev/null; then
+  echo " Max iterations: $MAX_ITERS"
+fi
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo ""
 
@@ -123,33 +146,66 @@ while true; do
     exit 0
   fi
 
-  # ── Run one check cycle ──
+  # ── Max iterations guard ──
   CYCLE=$((CYCLE + 1))
+  if [ "$MAX_ITERS" -gt 0 ] 2>/dev/null && [ "$CYCLE" -gt "$MAX_ITERS" ]; then
+    TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+    echo "[$TIMESTAMP] Max iterations ($MAX_ITERS) reached. Stopping."
+    echo "" >> "$LOG_FILE"
+    echo "## [$TIMESTAMP] MAX_ITERATIONS" >> "$LOG_FILE"
+    echo "" >> "$LOG_FILE"
+    echo "- Reached max iterations: $MAX_ITERS" >> "$LOG_FILE"
+    rm -f "$PID_FILE"
+    exit 0
+  fi
+
+  # ── Run one brain cycle ──
   TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
-  echo "[$TIMESTAMP] Cycle #$CYCLE — polling..."
+  echo "[$TIMESTAMP] Cycle #$CYCLE — brain thinking..."
 
-  # Fresh Claude invocation each cycle = no context rot
+  # Build the prompt
   if [ -n "$PHASE" ]; then
-    claude --print --dangerously-skip-permissions --command "/gsd:pm-check $PHASE" 2>&1 || {
-      echo "[$TIMESTAMP] WARNING: claude exited with error (cycle #$CYCLE)"
+    PROMPT="/gsd:pm-cycle $PHASE"
+  else
+    PROMPT="/gsd:pm-cycle"
+  fi
+
+  # Fresh Claude invocation — full brain, fresh 200k context
+  claude -p --dangerously-skip-permissions "$PROMPT" 2>&1
+  EXIT_CODE=$?
+
+  # ── Handle exit codes ──
+  case $EXIT_CODE in
+    0)
+      # Normal — more work to do, continue loop
+      ;;
+    42)
+      # Milestone complete — all done
+      TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+      echo ""
+      echo "[$TIMESTAMP] Milestone complete! PM loop exiting."
       echo "" >> "$LOG_FILE"
-      echo "## [$TIMESTAMP] ERROR" >> "$LOG_FILE"
+      echo "## [$TIMESTAMP] LOOP_EXIT" >> "$LOG_FILE"
       echo "" >> "$LOG_FILE"
-      echo "- Claude exited with error on cycle #$CYCLE" >> "$LOG_FILE"
-    }
-  else
-    claude --print --dangerously-skip-permissions --command "/gsd:pm-check" 2>&1 || {
-      echo "[$TIMESTAMP] WARNING: claude exited with error (cycle #$CYCLE)"
+      echo "- Milestone complete after $CYCLE cycles" >> "$LOG_FILE"
+      rm -f "$PID_FILE"
+      exit 0
+      ;;
+    *)
+      # Error — log and continue (don't crash the loop)
+      TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+      echo "[$TIMESTAMP] WARNING: claude exited with code $EXIT_CODE (cycle #$CYCLE)"
       echo "" >> "$LOG_FILE"
       echo "## [$TIMESTAMP] ERROR" >> "$LOG_FILE"
       echo "" >> "$LOG_FILE"
-      echo "- Claude exited with error on cycle #$CYCLE" >> "$LOG_FILE"
-    }
-  fi
+      echo "- Claude exited with code $EXIT_CODE on cycle #$CYCLE" >> "$LOG_FILE"
+      ;;
+  esac
 
   echo ""
 
   # ── Sleep until next cycle ──
-  echo "[$TIMESTAMP] Next check in ${INTERVAL}s..."
+  TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+  echo "[$TIMESTAMP] Next cycle in ${INTERVAL}s..."
   sleep "$INTERVAL"
 done