claude-cook 1.10.1 → 1.10.3

package/agents/gsd-pm.md

@@ -28,19 +28,45 @@ Plan → Sync Tickets → Dispatch Workers → Monitor → React → Replan if n
 
 <philosophy>
 
+## PM = Project Authority
+
+You are the Product Manager — the single source of truth for the project. You hold:
+- **Full project context**: PROJECT.md (vision, requirements), ROADMAP.md (phases, goals), STATE.md (living memory)
+- **Progress tracking**: TICKET-MAP.md (ticket statuses, wave progress, timelines), PM-LOG.md (decision history)
+- **Relationship map**: which tickets depend on which, what each phase delivers, how it all connects
+
+Workers know nothing about the project. They receive an atomic ticket and a codebase. **You** provide the context that makes their work meaningful.
+
 ## PM, Not Developer
 
-You are the product manager. You think in terms of:
+You think in terms of:
 - Goals, not implementations
-- Tickets, not code
+- Deliverables, not code
 - Delegation, not execution
-- Monitoring, not building
+- Progress tracking, not building
+
+Your value: making sure the RIGHT things get built in the RIGHT order, detecting failures early, adapting the plan, and maintaining the big picture that no individual worker can see.
+
+## Agile Tickets, Not Code Dumps
 
-Your value: making sure the RIGHT things get built in the RIGHT order, detecting failures early, and adapting the plan.
+Tickets are **atomic, isolated task assignments** — like a good Agile user story:
+- Describe **what** to deliver and **why** it matters
+- Define **acceptance criteria** as observable behaviors
+- List **dependencies** on other tickets
+- Never include file paths, function names, code snippets, or architecture decisions
 
-## Plans Are Worker Prompts
+**Why:** Workers are coding agents with full codebase access. They figure out implementation by reading the code. Tickets that prescribe code become stale, create merge conflicts, and prevent agents from making better decisions based on actual codebase state.
 
-When you sync a PLAN.md to a Vibe Kanban ticket, the ticket description IS the worker's prompt. The external coding agent receives the full plan content and executes it. Make plans clear, self-contained, and unambiguous.
+The PM's job is to decompose the project into the smallest meaningful units of work and assign them clearly. The worker's job is to figure out how to implement each unit.
+
+## Progress Tracking Is Your Core Job
+
+After every action, update your tracking artifacts:
+- **TICKET-MAP.md** — the live dashboard of all tickets, their statuses, and wave progress
+- **PM-LOG.md** — timestamped decision log (what happened, what you decided, why)
+- **STATE.md** — project-level position (current phase, overall progress)
+
+These files are your memory across context resets. Without them, you lose all state.
 
 ## Tickets Are Source of Truth
 
@@ -51,7 +77,7 @@ TICKET-MAP.md + Vibe Kanban status is the authoritative state. Not your memory,
 When a worker fails:
 1. Don't retry blindly — diagnose first
 2. Spawn gsd-planner in revision mode for targeted fix
-3. Cancel the failed ticket, create a fix ticket
+3. Cancel the failed ticket, create a fix ticket (Agile format)
 4. Dispatch a fresh worker on the fix
 5. Log everything to PM-LOG.md
 
@@ -262,10 +288,10 @@ Triggered by: ticket failure, human feedback, or /pm:replan command.
 2. Wait for plans
 3. Spawn gsd-plan-checker to verify new plans
 4. If checker rejects: retry planner (max 3 iterations)
-5. Sync changes to Vibe Kanban:
+5. Sync changes to Vibe Kanban (all tickets in Agile format — no code specifics):
    - Cancel obsolete tickets: `update_task(task_id, status="cancelled")`
-   - Create new tickets: `create_task(project_id, title, description)`
-   - Update changed tickets: `update_task(task_id, description=new_content)`
+   - Create new Agile tickets: `create_task(project_id, title, agile_description)`
+   - Update changed tickets: `update_task(task_id, description=new_agile_ticket)`
 6. Update TICKET-MAP.md with new mapping
 7. Record replan in TICKET-MAP Replan History section
 8. Log to PM-LOG.md
@@ -277,29 +303,39 @@ Triggered by: ticket failure, human feedback, or /pm:replan command.
 
 ## Plan-to-Ticket Sync
 
-### Creating Tickets from Plans
+### Creating Agile Tickets from Plans
 
 For each PLAN.md in the phase directory:
 
 1. Read plan content
-2. Extract from frontmatter: wave, depends_on
-3. Build ticket title: `"Phase {X} Plan {Y}: {first_line_of_objective}"`
-4. Build ticket description: Full PLAN.md content (the worker's prompt)
-5. Call `mcp__vibe_kanban__create_task(project_id, title, description)`
-6. Record in TICKET-MAP.md: plan, ticket_id, status=todo, wave, etc.
+2. Extract from frontmatter: wave, depends_on, must_haves
+3. Extract from `<objective>`: what this delivers and why
+4. Build ticket title: `"Phase {X} Plan {Y}: {objective_summary}"`
+5. Build ticket description as **Agile ticket** (see format in pm-sync.md):
+   - Task: one-paragraph summary of what to deliver (no code specifics)
+   - Why: value and what it unblocks
+   - Acceptance Criteria: observable behaviors from must_haves.truths
+   - Dependencies: ticket IDs from depends_on
+   - Scope: wave, phase, plan reference
+6. Call `mcp__vibe_kanban__create_task(project_id, title, description)`
+7. Record in TICKET-MAP.md: plan, ticket_id, status=todo, wave, etc.
+
+**Never put file paths, function names, code snippets, or implementation details in ticket descriptions.**
 
 ### Updating Tickets from Modified Plans
 
 For each modified PLAN.md:
+
 1. Find corresponding ticket_id in TICKET-MAP.md
-2. If ticket status is `todo` (not yet dispatched): update description
+2. If ticket status is `todo` (not yet dispatched): rebuild Agile ticket from updated plan, update description
 3. If ticket status is `inprogress`: log warning — worker is already running
-4. Call `update_task(task_id, description=new_plan_content)`
+4. Call `update_task(task_id, description=new_agile_ticket)`
 5. Update TICKET-MAP.md
 
 ### Cancelling Tickets for Removed Plans
 
 For each plan that no longer exists:
+
 1. Find corresponding ticket_id in TICKET-MAP.md
 2. Call `update_task(task_id, status="cancelled")`
 3. Mark as cancelled in TICKET-MAP.md

package/commands/gsd/help.md

@@ -424,16 +424,17 @@ Example config:
 ### Product Manager Mode
 
 **`/gsd:pm-start <phase>`**
-Plan a phase, sync to Vibe Kanban tickets, dispatch external coding agents.
+Start fully autonomous PM — plans, syncs, dispatches, monitors, and advances phases.
 
-- Plans phase (reuses gsd-planner + checker pipeline)
-- Syncs plans to Vibe Kanban as tickets (one ticket per PLAN.md)
-- Dispatches wave 1 workers via `start_workspace_session`
-- `--autonomous`: launches `pm-loop.sh` for continuous monitoring
-- `--manual`: shows status and available commands (default)
+- Runs **foreground by default** — live progress, desktop notifications, progress bars
+- Plans phase, syncs to Agile tickets (atomic, code-agnostic), dispatches workers
+- Autonomously monitors, replans on failure, advances phases, completes milestone
+- `--background`: detach to run silently (logs to pm-loop.log, still sends desktop notifications)
+- `--manual`: don't launch loop, manage with `/gsd:pm-cycle` manually
 - `--executor=X`: override default executor (CLAUDE_CODE, CURSOR_AGENT, etc.)
+- `--no-notify`: disable desktop notifications
 
-Usage: `/gsd:pm-start 1 --autonomous`
+Usage: `/gsd:pm-start 1`
 
 **`/gsd:pm-check [phase]`**
 Single monitoring cycle — poll tickets, detect changes, react.
@@ -520,11 +521,11 @@ Usage: `/gsd:pm-stop`
 
 ```
 /gsd:new-project                          # Initialize project
-/gsd:pm-start 1 --autonomous             # Plan + sync + dispatch + auto-monitor
-# pm-loop.sh runs in background, polling every 60s
-/gsd:pm-status                            # Check dashboard anytime
-/gsd:pm-replan 1 "use Redis instead"      # Change plans mid-flight
-/gsd:pm-stop                              # Stop autonomous loop
+/gsd:pm-start 1                           # Starts PM — live progress in terminal
+# PM runs foreground: you see every cycle, progress bars, notifications
+# It plans → syncs tickets → dispatches → monitors → replans → advances phases
+# Stop with Ctrl+C or /gsd:pm-stop from another terminal
+/gsd:pm-replan 1 "use Redis instead"      # Change plans mid-flight (from another terminal)
 ```
 
 **Debugging an issue:**

package/commands/gsd/pm-cycle.md

@@ -0,0 +1,296 @@
+---
+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 — create **Agile-style tickets** (NOT code dumps):
+1. Read all PLAN.md files in phase directory
+2. For each plan, extract objective, acceptance criteria (must_haves), wave, dependencies
+3. Build an Agile ticket for each plan (Task, Why, Acceptance Criteria, Dependencies, Scope)
+4. Call `mcp__vibe_kanban__create_task` with:
+   - Title: "Phase {X} Plan {Y}: {objective}"
+   - Description: Structured Agile ticket — atomic, isolated, no file paths or code specifics
+5. 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 **rich cycle report** — the user sees this live in their terminal (pm-loop.sh runs foreground by default). Be informative, not terse.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PM ► {ACTION} — Phase {X}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{What happened this cycle — 2-3 sentences describing the action taken,
+any decisions made, and what changed.}
+
+Tickets: {done}/{total} done | {inprogress} running | {todo} queued
+Wave: {current_wave}/{total_waves}
+Next: {What the PM will do on the next cycle}
+```
+
+**This is live user-facing output.** The PM loop runs in the foreground — the user is watching. Report progress actively: what you did, what's happening, what's next. Don't be silent.
+
+</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.
+- **Report actively.** The user sees your output live. Tell them what's happening — don't be a silent background process.
+</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,25 @@ 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`
+- `--background` — Run loop detached (default: foreground with live output)
 - `--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)
+- `--no-notify` — Disable desktop notifications
 </context>
 
 <process>
@@ -121,15 +125,17 @@ If no plans exist OR user wants to re-plan:
 
 **Key difference from /gsd:plan-phase:** After planning, continue to sync+dispatch instead of stopping.
 
-## 5. Sync Plans to Vibe Kanban Tickets
+## 5. Sync Plans to Agile Tickets
 
-Follow the pm-sync workflow:
+Follow the pm-sync workflow — create **Agile-style tickets**, not code dumps:
 
 1. Read all PLAN.md files in the phase directory
-2. For each plan:
+2. For each plan, build an Agile ticket:
+   - Extract: objective, acceptance criteria (must_haves), wave, dependencies
    - Build title: `"Phase {X} Plan {Y}: {objective}"`
-   - Build description: full PLAN.md content
-   - `create_task(project_id, title, description)`
+   - Build description: structured Agile ticket (Task, Why, Acceptance Criteria, Dependencies, Scope)
+   - **No file paths, function names, or code snippets** — tickets describe WHAT to deliver
+   - `create_task(project_id, title, agile_description)`
 3. Write TICKET-MAP.md with all mappings
 
 Present:
@@ -168,45 +174,65 @@ Present:
 | ...    | ...  | ...      | launched |
 ```
 
-## 7. Start Monitor (mode-dependent)
+## 7. Launch PM Loop (default: foreground, live output)
 
-### Autonomous Mode (--autonomous)
+### Autonomous Mode (default) — FOREGROUND
 
-Initialize PM-LOG.md with INIT entry.
-Launch pm-loop.sh:
+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.
 
 ```bash
-nohup ~/.claude/scripts/pm-loop.sh --phase={X} --interval={poll_interval} > /dev/null 2>&1 &
-echo $! > .planning/.pm-loop-pid
+~/.claude/scripts/pm-loop.sh --phase={X} --interval={poll_interval} --max-iterations={max_iterations}
 ```
 
+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
+
+Stop with: `Ctrl+C` | `touch .planning/.pm-stop` | `/gsd: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.
+
+### Background Mode (--background)
+
+If the user explicitly passes `--background`, launch detached:
+
+```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:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PM ► AUTONOMOUS MODE ACTIVE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PM ► BACKGROUND MODE
 
 PM loop running (PID: {pid})
-Polling every {interval}s
-Log: .planning/PM-LOG.md
-
-Stop with: /gsd:pm-stop  or  touch .planning/.pm-stop
+Log: tail -f .planning/pm-loop.log
+Stop: /gsd:pm-stop  or  touch .planning/.pm-stop
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-### 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,145 @@
+# 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 Agile-style Vibe Kanban tickets for each plan.
+
+Follow `pm-sync.md` workflow:
+1. Read all PLAN.md files in phase directory
+2. For each plan, build an **Agile ticket** (atomic, isolated, code-agnostic):
+   - Extract objective, acceptance criteria (must_haves), wave, dependencies
+   - Create VK ticket: `mcp__vibe_kanban__create_task(project_id, title, description)`
+   - Description = structured Agile ticket (Task, Why, Acceptance Criteria, Dependencies, Scope)
+   - **Do NOT dump PLAN.md content** — tickets describe WHAT to deliver, not HOW to code it
+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/get-shit-done/workflows/pm-replan.md

@@ -87,7 +87,8 @@ Action: Cancel all undone tickets, re-plan from phase goal.
 
 6. Sync to Vibe Kanban:
    - `update_task(failed_ticket_id, status="cancelled")`
-   - `create_task(project_id, fix_title, fix_plan_content)` → new ticket
+   - Build Agile ticket from fix plan (Task, Why, Acceptance Criteria, Dependencies, Scope — no code specifics)
+   - `create_task(project_id, fix_title, agile_ticket_description)` → new ticket
    - Record in TICKET-MAP.md
 
 7. Dispatch fix ticket if autonomous mode

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

@@ -58,20 +58,63 @@ Build three lists:
 
 ## 3. Create Tickets for New Plans
 
+**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.
+
 For each new plan:
 
-1. Read the full PLAN.md content
+1. Read the PLAN.md content
 2. Extract from frontmatter: `wave`, `depends_on`, `phase`, `plan`
-3. Extract objective from the `<objective>` section (first line)
-4. Build ticket:
-   - **title:** `"Phase {phase} Plan {plan}: {objective_first_line}"`
-   - **description:** Full PLAN.md content as-is (this is the worker's prompt)
-5. Call `mcp__vibe_kanban__create_task(project_id, title, description)`
-6. Record in TICKET-MAP.md:
+3. Extract from `<objective>` section: what this plan accomplishes and why
+4. Extract from `must_haves` frontmatter: truths (observable behaviors), artifacts (deliverables)
+5. Build an **Agile ticket** (NOT a code dump):
+
+   - **title:** `"Phase {phase} Plan {plan}: {objective_summary}"`
+   - **description:** Structured Agile ticket (see format below)
+
+6. Call `mcp__vibe_kanban__create_task(project_id, title, description)`
+7. Record in TICKET-MAP.md:
    ```
    | {plan} | {task_summary} | {ticket_uuid} | todo | — | {wave} | — | — | new |
    ```
 
+### Agile Ticket Format
+
+```markdown
+## Task
+
+{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.}
+
+## Why
+
+{Why this task matters for the project. What value it adds. What it unblocks.}
+
+## Acceptance Criteria
+
+- [ ] {Observable behavior 1 — from must_haves.truths}
+- [ ] {Observable behavior 2}
+- [ ] {Deliverable exists — from must_haves.artifacts, described generically}
+
+## Dependencies
+
+- {List ticket IDs this depends on, from depends_on field, or "None"}
+
+## Scope
+
+- Wave: {N}
+- Phase: {phase_name}
+- Plan ref: {plan_id} (see .planning/ for implementation details)
+```
+
+**What NOT to include in tickets:**
+- File paths or directory structures
+- Function/class/method names
+- Code snippets or pseudocode
+- Specific library API calls
+- Internal architecture decisions
+
+**Why:** Workers are coding agents with full codebase access. They figure out implementation from context. Tickets that prescribe code become stale, create merge conflicts, and prevent the agent from making better decisions based on actual codebase state.
+
 </step>
 
 <step name="sync_modified">
@@ -82,11 +125,13 @@ For each modified plan:
 
 1. Find ticket_id from TICKET-MAP.md
 2. Check current ticket status:
-   - If `todo`: safe to update → `update_task(task_id, description=new_content)`
+   - If `todo`: safe to update → rebuild Agile ticket from updated PLAN.md, then `update_task(task_id, description=new_agile_ticket)`
    - If `inprogress`: **WARNING** — worker is running. Log warning, do NOT update.
    - If `done`/`cancelled`: skip (no point updating)
 3. Update TICKET-MAP.md with notes
 
+**Important:** Always regenerate the Agile ticket format from the updated PLAN.md. Never dump raw PLAN.md content into the ticket description.
+
 </step>
 
 <step name="sync_removed">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-cook",
-  "version": "1.10.1",
+  "version": "1.10.3",
   "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,20 +1,25 @@
 #!/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
+#
+# RUNS IN FOREGROUND by default — you see live progress.
+# Use --background to detach (output goes to .planning/pm-loop.log).
 #
 # 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:
 #   touch .planning/.pm-stop
 #   OR run /gsd:pm-stop
-#
-# Background:
-#   nohup ./scripts/pm-loop.sh --phase=1 > /dev/null 2>&1 &
+#   OR Ctrl+C (foreground mode)
 
 set -euo pipefail
 
@@ -22,6 +27,9 @@ set -euo pipefail
 
 PHASE="${PM_PHASE:-}"
 INTERVAL="${PM_POLL_INTERVAL:-60}"
+MAX_ITERS="${PM_MAX_ITERATIONS:-0}"  # 0 = unlimited
+BACKGROUND=false
+NOTIFY=true
 
 for arg in "$@"; do
   case $arg in
@@ -31,14 +39,37 @@ for arg in "$@"; do
     --interval=*)
       INTERVAL="${arg#*=}"
       ;;
+    --max-iterations=*)
+      MAX_ITERS="${arg#*=}"
+      ;;
+    --background)
+      BACKGROUND=true
+      ;;
+    --no-notify)
+      NOTIFY=false
+      ;;
     --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 "Runs in FOREGROUND by default — you see live progress."
+      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 "  --background        Detach and run in background (logs to pm-loop.log)"
+      echo "  --no-notify         Disable desktop notifications"
       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  OR  Ctrl+C"
       exit 0
       ;;
     *)
@@ -63,17 +94,117 @@ if ! command -v claude &> /dev/null; then
   exit 1
 fi
 
+# ─── Background mode: re-exec detached ───────────────────────────
+
+if [ "$BACKGROUND" = true ]; then
+  # Strip --background from args, re-exec with nohup
+  ARGS=()
+  for arg in "$@"; do
+    [ "$arg" != "--background" ] && ARGS+=("$arg")
+  done
+  nohup "$0" "${ARGS[@]}" > .planning/pm-loop.log 2>&1 &
+  BG_PID=$!
+  echo "$BG_PID" > .planning/.pm-loop-pid
+  echo "PM loop launched in background (PID: $BG_PID)"
+  echo "Log: tail -f .planning/pm-loop.log"
+  echo "Stop: touch .planning/.pm-stop"
+  exit 0
+fi
+
+# ─── Desktop notification helper ─────────────────────────────────
+
+notify() {
+  local title="$1"
+  local message="$2"
+  local urgency="${3:-normal}"  # normal, critical
+
+  if [ "$NOTIFY" = false ]; then
+    return
+  fi
+
+  # macOS
+  if command -v osascript &> /dev/null; then
+    osascript -e "display notification \"$message\" with title \"$title\"" 2>/dev/null || true
+    # Sound for critical events
+    if [ "$urgency" = "critical" ]; then
+      afplay /System/Library/Sounds/Glass.aiff 2>/dev/null &
+    fi
+    return
+  fi
+
+  # Linux
+  if command -v notify-send &> /dev/null; then
+    local urgency_flag="normal"
+    [ "$urgency" = "critical" ] && urgency_flag="critical"
+    notify-send -u "$urgency_flag" "$title" "$message" 2>/dev/null || true
+    return
+  fi
+}
+
+# ─── Progress summary helper ─────────────────────────────────────
+
+print_progress() {
+  # Read TICKET-MAP.md for quick progress snapshot
+  local ticket_map=""
+  ticket_map=$(find .planning/phases/ -name "TICKET-MAP.md" -print -quit 2>/dev/null || true)
+
+  if [ -n "$ticket_map" ] && [ -f "$ticket_map" ]; then
+    local done_count=$(grep -c "| done " "$ticket_map" 2>/dev/null || echo "0")
+    local inprogress_count=$(grep -c "| inprogress " "$ticket_map" 2>/dev/null || echo "0")
+    local todo_count=$(grep -c "| todo " "$ticket_map" 2>/dev/null || echo "0")
+    local total=$((done_count + inprogress_count + todo_count))
+
+    if [ "$total" -gt 0 ]; then
+      # Build progress bar
+      local pct=0
+      if [ "$total" -gt 0 ]; then
+        pct=$((done_count * 100 / total))
+      fi
+      local bar_len=20
+      local filled=$((pct * bar_len / 100))
+      local empty=$((bar_len - filled))
+      local bar=""
+      for ((i=0; i<filled; i++)); do bar+="█"; done
+      for ((i=0; i<empty; i++)); do bar+="░"; done
+
+      echo "  ┌─────────────────────────────────────────┐"
+      echo "  │  Progress: [$bar] ${pct}%"
+      echo "  │  Done: $done_count  Running: $inprogress_count  Todo: $todo_count  Total: $total"
+      echo "  └─────────────────────────────────────────┘"
+    fi
+  fi
+}
+
+# ─── Graceful Ctrl+C handling ────────────────────────────────────
+
+cleanup() {
+  TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+  echo ""
+  echo "[$TIMESTAMP] PM loop interrupted (Ctrl+C). Cleaning up..."
+  echo "" >> "$LOG_FILE"
+  echo "## [$TIMESTAMP] INTERRUPTED" >> "$LOG_FILE"
+  echo "" >> "$LOG_FILE"
+  echo "- PM loop interrupted by user" >> "$LOG_FILE"
+  echo "- Completed $CYCLE cycles" >> "$LOG_FILE"
+  rm -f "$PID_FILE"
+  notify "GSD PM" "PM loop stopped by user after $CYCLE cycles"
+  exit 0
+}
+trap cleanup SIGINT SIGTERM
+
 # ─── Configuration ────────────────────────────────────────────────
 
 STOP_FILE=".planning/.pm-stop"
 PID_FILE=".planning/.pm-loop-pid"
 LOG_FILE=".planning/PM-LOG.md"
 CYCLE=0
+ERROR_STREAK=0
+MAX_ERROR_STREAK=5
 
 # 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 +219,7 @@ Started: $TIMESTAMP
 Mode: autonomous
 Poll interval: ${INTERVAL}s
 Phase: ${PHASE:-auto}
+Max iterations: ${MAX_ITERS:-unlimited}
 
 ---
 
@@ -100,56 +232,176 @@ 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 ────────────────────────────────────────────────────
+# ─── Startup banner ──────────────────────────────────────────────
 
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo " PM Loop — Phase: ${PHASE:-auto} | Interval: ${INTERVAL}s"
-echo " PID: $$ | Stop: touch $STOP_FILE"
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo " PM ► AUTONOMOUS MODE ACTIVE"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "  Phase: ${PHASE:-auto-detect}"
+echo "  Interval: ${INTERVAL}s"
+echo "  PID: $$"
+if [ "$MAX_ITERS" -gt 0 ] 2>/dev/null; then
+  echo "  Max iterations: $MAX_ITERS"
+fi
+echo ""
+echo "  Stop: Ctrl+C  |  touch .planning/.pm-stop  |  /gsd:pm-stop"
+echo ""
+echo "  The PM will autonomously:"
+echo "    plan → sync → dispatch → monitor → replan → advance phases"
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+notify "GSD PM" "Autonomous PM started for Phase ${PHASE:-auto}" "normal"
+
+# ─── Main loop ────────────────────────────────────────────────────
 
 while true; do
   # ── Check stop signal ──
   if [ -f "$STOP_FILE" ]; then
     TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
-    echo "[$TIMESTAMP] Stop signal received. Exiting."
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo " PM ► STOPPED"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+    echo "  [$TIMESTAMP] Stop signal received after $CYCLE cycles."
+    echo ""
     echo "" >> "$LOG_FILE"
     echo "## [$TIMESTAMP] STOP" >> "$LOG_FILE"
     echo "" >> "$LOG_FILE"
     echo "- PM loop stopped by stop file" >> "$LOG_FILE"
     echo "- Completed $CYCLE cycles" >> "$LOG_FILE"
     rm -f "$STOP_FILE" "$PID_FILE"
+    notify "GSD PM" "PM loop stopped after $CYCLE cycles"
     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 ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo " PM ► MAX ITERATIONS REACHED"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+    echo "  Completed $((CYCLE - 1)) cycles. Safety cap: $MAX_ITERS."
+    echo ""
+    echo "" >> "$LOG_FILE"
+    echo "## [$TIMESTAMP] MAX_ITERATIONS" >> "$LOG_FILE"
+    echo "" >> "$LOG_FILE"
+    echo "- Reached max iterations: $MAX_ITERS" >> "$LOG_FILE"
+    rm -f "$PID_FILE"
+    notify "GSD PM" "PM loop reached max iterations ($MAX_ITERS)" "normal"
+    exit 0
+  fi
+
+  # ── Cycle header ──
   TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
-  echo "[$TIMESTAMP] Cycle #$CYCLE — polling..."
+  echo "┌─────────────────────────────────────────────────────"
+  echo "│ Cycle #$CYCLE — $TIMESTAMP"
+  echo "└─────────────────────────────────────────────────────"
+  echo ""
 
-  # 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
+  # Output streams directly to terminal (foreground mode)
+  CYCLE_START=$(date +%s)
+  claude -p --dangerously-skip-permissions "$PROMPT" 2>&1
+  EXIT_CODE=$?
+  CYCLE_END=$(date +%s)
+  CYCLE_DURATION=$((CYCLE_END - CYCLE_START))
+
+  echo ""
+
+  # ── Handle exit codes ──
+  case $EXIT_CODE in
+    0)
+      # Normal — more work to do
+      ERROR_STREAK=0
+      print_progress
+      echo ""
+      echo "  Cycle #$CYCLE completed in ${CYCLE_DURATION}s. Next in ${INTERVAL}s..."
+      echo ""
+      ;;
+    42)
+      # Milestone complete — all done!
+      TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+      echo ""
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      echo " PM ► MILESTONE COMPLETE"
+      echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+      echo ""
+      echo "  All phases complete after $CYCLE cycles."
+      echo "  Run /gsd:complete-milestone to archive."
+      echo ""
+      print_progress
+      echo ""
       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"
+      notify "GSD PM" "Milestone complete! All phases done after $CYCLE cycles." "critical"
+      exit 0
+      ;;
+    *)
+      # Error — log and continue (don't crash the loop)
+      ERROR_STREAK=$((ERROR_STREAK + 1))
+      TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+      echo "  ⚠ Cycle #$CYCLE failed (exit code $EXIT_CODE, streak: $ERROR_STREAK/$MAX_ERROR_STREAK)"
       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"
+      echo "- Error streak: $ERROR_STREAK/$MAX_ERROR_STREAK" >> "$LOG_FILE"
 
-  echo ""
+      # Notify on errors
+      notify "GSD PM" "Cycle #$CYCLE failed (code $EXIT_CODE)" "critical"
+
+      # Stop if too many consecutive errors
+      if [ "$ERROR_STREAK" -ge "$MAX_ERROR_STREAK" ]; then
+        echo ""
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo " PM ► ERROR — TOO MANY FAILURES"
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo ""
+        echo "  $ERROR_STREAK consecutive errors. Stopping to prevent waste."
+        echo "  Check .planning/PM-LOG.md for details."
+        echo "  Fix the issue, then restart with /gsd:pm-start"
+        echo ""
+        echo "" >> "$LOG_FILE"
+        echo "## [$TIMESTAMP] ERROR_STREAK_HALT" >> "$LOG_FILE"
+        echo "" >> "$LOG_FILE"
+        echo "- Halted after $ERROR_STREAK consecutive errors" >> "$LOG_FILE"
+        rm -f "$PID_FILE"
+        notify "GSD PM" "PM halted: $ERROR_STREAK consecutive errors" "critical"
+        exit 1
+      fi
+      ;;
+  esac
 
-  # ── Sleep until next cycle ──
-  echo "[$TIMESTAMP] Next check in ${INTERVAL}s..."
-  sleep "$INTERVAL"
+  # ── Countdown to next cycle ──
+  for ((remaining=INTERVAL; remaining>0; remaining--)); do
+    # Check stop signal during sleep too
+    if [ -f "$STOP_FILE" ]; then
+      break
+    fi
+    # Show countdown every 15 seconds
+    if [ $((remaining % 15)) -eq 0 ] && [ "$remaining" -ne "$INTERVAL" ]; then
+      echo "  ... next cycle in ${remaining}s"
+    fi
+    sleep 1
+  done
 done