claude-cook 1.10.2 → 1.10.4

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

@@ -125,12 +125,14 @@ Log to PM-LOG.md:
 
 ### Action: NEEDS_SYNC
 
-Run pm-sync workflow:
+Run pm-sync workflow — create **Agile-style tickets** (NOT code dumps):
 1. Read all PLAN.md files in phase directory
-2. For each plan, call `mcp__vibe_kanban__create_task` with:
+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: Full PLAN.md content (this IS the worker's prompt)
-3. Write TICKET-MAP.md with all mappings
+   - 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".
 
@@ -263,13 +265,22 @@ Run /gsd:complete-milestone to archive and plan next.
 
 ## 4. Cycle Summary
 
-After executing the action, output a brief 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.
 
 ```
-[{TIMESTAMP}] Cycle complete — State: {STATE} → Action: {ACTION}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ 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 the only user-visible output per cycle (pm-loop.sh captures it).
+**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>
 
@@ -281,4 +292,5 @@ This is the only user-visible output per cycle (pm-loop.sh captures it).
 - **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

@@ -38,9 +38,11 @@ Phase number: $ARGUMENTS (required — starting phase)
 
 **Flags:**
 - `--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 initial planning, assume plans already exist
 - `--max-iterations=N` — Safety cap on loop cycles (default: 0 = unlimited)
+- `--no-notify` — Disable desktop notifications
 </context>
 
 <process>
@@ -123,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:
@@ -170,33 +174,48 @@ Present:
 | ...    | ...  | ...      | launched |
 ```
 
-## 7. Launch PM Loop (default: autonomous)
+## 7. Launch PM Loop (default: foreground, live output)
 
-### Autonomous Mode (default)
+### Autonomous Mode (default) — FOREGROUND
 
-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.
+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} --max-iterations={max_iterations} > .planning/pm-loop.log 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})
-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
+Log: tail -f .planning/pm-loop.log
+Stop: /gsd:pm-stop  or  touch .planning/.pm-stop
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
 ### Manual Mode (--manual)

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

@@ -51,14 +51,15 @@ MILESTONE_COMPLETE ──stop signal──→ EXIT
 
 ### NEEDS_SYNC
 
-**Goal:** Create Vibe Kanban tickets for each plan.
+**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:
-   - Extract objective, wave number from frontmatter
+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 = full PLAN.md content (worker's complete prompt)
+   - 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

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.2",
+  "version": "1.10.4",
   "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

@@ -9,6 +9,9 @@
 # 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] [--max-iterations=50]
 #   PM_PHASE=1 PM_POLL_INTERVAL=30 ./scripts/pm-loop.sh
@@ -16,9 +19,7 @@
 # Stop:
 #   touch .planning/.pm-stop
 #   OR run /gsd:pm-stop
-#
-# Background:
-#   nohup ./scripts/pm-loop.sh --phase=1 > .planning/pm-loop.log 2>&1 &
+#   OR Ctrl+C (foreground mode)
 
 set -euo pipefail
 
@@ -27,6 +28,8 @@ 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
@@ -39,6 +42,12 @@ for arg in "$@"; do
     --max-iterations=*)
       MAX_ITERS="${arg#*=}"
       ;;
+    --background)
+      BACKGROUND=true
+      ;;
+    --no-notify)
+      NOTIFY=false
+      ;;
     --help|-h)
       echo "Usage: pm-loop.sh [--phase=N] [--interval=60] [--max-iterations=0]"
       echo ""
@@ -46,17 +55,21 @@ for arg in "$@"; do
       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"
       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  OR  /gsd:pm-stop"
+      echo "Stop: touch .planning/.pm-stop  OR  /gsd:pm-stop  OR  Ctrl+C"
       exit 0
       ;;
     *)
@@ -81,12 +94,112 @@ 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"
@@ -121,28 +234,50 @@ 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 " 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"
+  echo "  Max iterations: $MAX_ITERS"
 fi
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 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
 
@@ -150,62 +285,125 @@ while true; do
   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 ""
+    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
 
-  # ── Run one brain cycle ──
+  # ── Cycle header ──
   TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
-  echo "[$TIMESTAMP] Cycle #$CYCLE — brain thinking..."
+  echo "┌─────────────────────────────────────────────────────"
+  echo "│ Cycle #$CYCLE — $TIMESTAMP"
+  echo "└─────────────────────────────────────────────────────"
+  echo ""
 
   # Build the prompt
-  if [ -n "$PHASE" ]; then
+  # Only pass phase hint on cycle 1 — after that, pm-cycle auto-detects
+  # from STATE.md so it can advance through phases autonomously.
+  if [ "$CYCLE" -eq 1 ] && [ -n "$PHASE" ]; then
     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, continue loop
+      # 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
+      # Milestone complete — all done!
       TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
       echo ""
-      echo "[$TIMESTAMP] Milestone complete! PM loop exiting."
+      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] LOOP_EXIT" >> "$LOG_FILE"
       echo "" >> "$LOG_FILE"
       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 "[$TIMESTAMP] WARNING: claude exited with code $EXIT_CODE (cycle #$CYCLE)"
+      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 code $EXIT_CODE on cycle #$CYCLE" >> "$LOG_FILE"
+      echo "- Error streak: $ERROR_STREAK/$MAX_ERROR_STREAK" >> "$LOG_FILE"
+
+      # 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
 
-  echo ""
-
-  # ── Sleep until next cycle ──
-  TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
-  echo "[$TIMESTAMP] Next cycle 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