claude-cook 1.10.8 → 1.11.0

package/commands/cook/pm-start.md

@@ -1,7 +1,7 @@
 ---
 name: cook:pm-start
-description: Start fully autonomous PM — plans, syncs, dispatches, monitors, and advances phases automatically
-argument-hint: "<phase> [--manual] [--background] [--executor=CLAUDE_CODE] [--skip-plan] [--max-iterations=0] [--max-replans=3] [--calls=0]"
+description: Start fully autonomous PM — runs the entire lifecycle from init to milestone completion
+argument-hint: "[phase] [--init] [--prd=<file>] [--manual] [--background] [--executor=CLAUDE_CODE] [--skip-plan] [--max-iterations=0] [--max-replans=3] [--calls=0]"
 agent: cook-pm
 allowed-tools:
   - Read
@@ -18,29 +18,34 @@ allowed-tools:
 <execution_context>
 @~/.claude/cook/references/ui-brand.md
 @~/.claude/cook/references/vibe-kanban.md
+@~/.claude/cook/workflows/pm-cycle.md
 @~/.claude/cook/workflows/pm-sync.md
 @~/.claude/cook/workflows/pm-dispatch.md
 @~/.claude/agents/cook-pm.md
 </execution_context>
 
 <objective>
-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:
+Start the fully autonomous PM agent. Auto-detects the current project state and picks up from the right point in the lifecycle:
 
-**plan → sync tickets → dispatch workers → monitor → replan on failure → advance phases → complete milestone**
+```
+NEEDS_INIT → NEEDS_RESEARCH → NEEDS_ROADMAP → NEEDS_PLANNING → NEEDS_SYNC → NEEDS_DISPATCH → MONITORING → NEEDS_REVIEW → PHASE_COMPLETE → ... → MILESTONE_COMPLETE
+```
 
-After this command, the PM runs unattended. Each loop cycle is a fresh Claude invocation via `/cook:pm-cycle` — no context rot.
+The PM runs the **entire lifecycle** unattended — from project init through research, planning, ticket creation, worker dispatch, code review (via VK review agent), phase advancement, and milestone completion.
 
-Use `--manual` to skip the loop and manage phases manually with `/cook:pm-cycle`.
+Each loop cycle is a fresh Claude invocation via `/cook:pm-cycle` — no context rot.
 </objective>
 
 <context>
-Phase number: $ARGUMENTS (required — starting phase)
+Phase number: $ARGUMENTS (optional — auto-detected if omitted)
 
 **Flags:**
+- `--init` — Start from scratch, create .planning/ and PROJECT.md
+- `--prd=<file>` — Provide a PRD file for project initialization
 - `--manual` — Don't launch the loop, manage manually with `/cook:pm-cycle`
 - `--background` — Run loop detached (default: background when autonomous)
 - `--executor=X` — Override default executor (CLAUDE_CODE, CURSOR_AGENT, CODEX, etc.)
-- `--skip-plan` — Skip initial planning, assume plans already exist
+- `--skip-plan` — Skip planning, assume plans already exist
 - `--max-iterations=N` — Safety cap on loop cycles (default: 0 = unlimited)
 - `--max-replans=N` — Auto replan attempts on repeated errors (default: 3)
 - `--calls=N` — Max Claude calls per hour (default: 0 = unlimited)
@@ -49,23 +54,54 @@ Phase number: $ARGUMENTS (required — starting phase)
 
 <process>
 
-## 1. Validate Environment
+## 1. Auto-Detect State
+
+Classify the current project state to determine where to start:
 
 ```bash
-test -d .planning && echo "exists" || echo "missing"
+# Check each condition in order
+test -d .planning && echo "planning_exists" || echo "no_planning"
+test -f .planning/PROJECT.md && echo "project_exists" || echo "no_project"
+test -f .planning/research/SUMMARY.md && echo "research_done" || echo "no_research"
+test -f .planning/ROADMAP.md && echo "roadmap_exists" || echo "no_roadmap"
+```
+
+**State detection logic:**
+
+| Condition | Detected State | Action |
+|-----------|---------------|--------|
+| No `.planning/` or no `PROJECT.md` | NEEDS_INIT | Scaffold project |
+| No `.planning/research/SUMMARY.md` | NEEDS_RESEARCH | Run research agents |
+| No `ROADMAP.md` | NEEDS_ROADMAP | Create roadmap |
+| Phase has no PLAN.md files | NEEDS_PLANNING | Create plans |
+| Plans exist, no TICKET-MAP | NEEDS_SYNC | Create tickets |
+| TICKET-MAP has todo tickets | NEEDS_DISPATCH | Launch workers |
+| Tickets inprogress/inreview | MONITORING | Poll and react |
+| All tickets done | PHASE_COMPLETE | Advance phase |
+
+**Override:** If `--init` flag is set, always start from NEEDS_INIT regardless of current state.
+
+Present detected state:
 ```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PM ► STATE DETECTED: {state}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-If no `.planning/`: Error — run `/cook:new-project` first.
+Starting from: {state description}
+Phase: {N or "new project"}
+```
 
-Read config:
+## 2. Setup Config
+
+Read or create config:
 ```bash
 cat .planning/config.json 2>/dev/null
 ```
 
-Check for pm section. If missing, initialize it:
+If missing or no pm section, initialize:
 ```json
 "pm": {
-  "mode": "manual",
+  "mode": "autonomous",
   "poll_interval_seconds": 60,
   "project_id": null,
   "repos": [],
@@ -77,21 +113,9 @@ Check for pm section. If missing, initialize it:
 ```
 
 Apply flag overrides:
-- `--autonomous` → set `pm.mode` to `"autonomous"`
 - `--manual` → set `pm.mode` to `"manual"`
 - `--executor=X` → set `pm.default_executor`
 
-Write updated config.json.
-
-## 2. Parse Phase Number
-
-Extract phase number from $ARGUMENTS. Validate it exists in ROADMAP.md.
-
-Find or create phase directory:
-```bash
-ls .planning/phases/ | grep "^{phase_num}"
-```
-
 ## 3. Setup Vibe Kanban Connection
 
 If `pm.project_id` is null:
@@ -101,110 +125,39 @@ If `pm.project_id` is null:
 3. Call `mcp__vibe_kanban__list_repos(project_id)` — get repo details
 4. Save project_id and repos to config.json
 
-Present:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PM ► CONNECTED TO VIBE KANBAN
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Project: {name} ({project_id})
-Repos: {repo_list}
-Executor: {default_executor}
-```
-
-## 4. Plan Phase (unless --skip-plan)
-
-If plans already exist for this phase AND --skip-plan not specified:
-- Ask user: "Plans already exist. Re-plan or use existing?"
-
-If no plans exist OR user wants to re-plan:
-- Follow the same planning pipeline as `/cook:plan-phase`:
-  1. Resolve model profile
-  2. Optionally run phase researcher
-  3. Spawn cook-planner via Task tool
-  4. Spawn cook-plan-checker to verify
-  5. Iterate planner ↔ checker until plans pass (max 3)
-
-**Key difference from /cook:plan-phase:** After planning, continue to sync+dispatch instead of stopping.
+## 4. Execute First Cycle Inline
 
-## 5. Sync Plans to Agile Tickets
+Run one cycle of the pm-cycle state machine inline (based on detected state from step 1). This ensures the first action happens immediately without waiting for the loop.
 
-Follow the pm-sync workflow — create **Agile-style tickets**, not code dumps:
+Follow the action for the detected state as defined in `pm-cycle.md`:
+- NEEDS_INIT → scaffold project
+- NEEDS_RESEARCH → spawn research agents
+- NEEDS_ROADMAP → spawn roadmapper
+- NEEDS_PLANNING → spawn planner + checker
+- NEEDS_SYNC → create tickets
+- NEEDS_DISPATCH → dispatch workers
+- MONITORING → poll and react
 
-1. Read all PLAN.md files in the phase directory
-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: 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:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PM ► TICKETS SYNCED
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-{N} plans → {N} tickets created
-
-| Wave | Plan | Ticket | Title |
-| ---- | ---- | ------ | ----- |
-| ...  | ...  | ...    | ...   |
-```
-
-## 6. Dispatch Wave 1
-
-Follow the pm-dispatch workflow:
-
-1. Collect all wave 1 tickets from TICKET-MAP
-2. For each:
-   - `start_workspace_session(task_id, executor, repos)`
-   - Update TICKET-MAP: status=inprogress, dispatched=now
-3. Log dispatches to PM-LOG.md
-
-Present:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PM ► WAVE 1 DISPATCHED
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-{N} workers launched:
-
-| Ticket | Plan | Executor | Status |
-| ------ | ---- | -------- | ------ |
-| ...    | ...  | ...      | launched |
-```
-
-## 7. Launch PM Loop (default: background in autonomous mode)
+## 5. Launch PM Loop
 
 ### Autonomous Mode (default) — BACKGROUND
 
-Launch pm-loop.sh in the **background** by default in autonomous mode. This avoids blocking the command while keeping the loop running. The loop will automatically trigger `/cook:pm-replan` after repeated failures, up to the configured max.
+Build the pm-loop.sh command with all detected parameters:
 
 ```bash
-~/.claude/scripts/pm-loop.sh --phase={X} --interval={poll_interval} --max-iterations={max_iterations} --background
+~/.claude/scripts/pm-loop.sh \
+  --phase={X} \
+  --interval={poll_interval} \
+  --max-iterations={max_iterations} \
+  --background \
+  ${prd_flag}
 ```
 
-Output goes to `.planning/pm-loop.log`. Desktop notifications still work in background mode (macOS/Linux).
+Where `${prd_flag}` is `--prd=<file>` if provided.
 
 Stop with: `touch .planning/.pm-stop` | `/cook:pm-stop`
 
-If the user explicitly asks for foreground mode, run without `--background`.
-
-### Foreground Mode (explicit)
-
-If the user explicitly asks for foreground/live output, launch without `--background`:
-
-```bash
-~/.claude/scripts/pm-loop.sh --phase={X} --interval={poll_interval} --max-iterations={max_iterations}
-```
-
-This blocks the terminal and streams live output.
-
-### Manual Mode (--manual only)
-
-Only use manual mode if the user explicitly passes `--manual`. Otherwise always launch the loop.
+### Manual Mode (--manual)
 
 Present:
 ```
@@ -212,17 +165,17 @@ Present:
  PM ► MANUAL MODE
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Workers dispatched. Run these commands to manage:
+Run these commands to manage:
 
 /cook:pm-cycle    — Run one full-brain cycle (decides + acts)
 /cook:pm-status   — View dashboard
 /cook:pm-replan   — Modify plans with feedback
 ```
 
-## 8. Update STATE.md
+## 6. Update STATE.md
 
 Update STATE.md with PM status:
-- Current position: Phase X, PM mode active
+- Current position: Phase X (or "initializing"), PM mode active
 - Vibe Kanban Status section: project, tickets, last polled
 
 </process>

package/cook/workflows/pm-check.md

@@ -133,14 +133,15 @@ Run /cook:pm-start {X+1} to begin next phase.
 ### WORKER_COMPLETED (inprogress → inreview)
 1. Call `get_task(task_id)` to read worker output/notes
 2. Update TICKET-MAP.md: status=inreview, review_started=timestamp
-3. Trigger automated code review:
-   - Spawn `feature-dev:code-reviewer` agent via Task tool
-   - Provide: ticket title, acceptance criteria from ticket description, recent commits (use `git log --oneline -10` to find relevant commits)
-   - The reviewer examines the diff and returns a verdict: **PASS** or **FAIL** with issues
-4. Based on review result:
-   - **PASS:** Update ticket status to `done` via `mcp__vibe_kanban__update_task(task_id, status="done")`. Update TICKET-MAP.md: status=done, completed=timestamp, review=passed. Check if this completes the wave.
-   - **FAIL:** Update ticket status back to `inprogress` via `mcp__vibe_kanban__update_task(task_id, status="inprogress")`. Update TICKET-MAP.md: status=inprogress, review=failed. Append review feedback as a task note via `mcp__vibe_kanban__update_task(task_id, description=original_description + "\n\n## Review Feedback\n\n" + reviewer_issues)`. Re-dispatch the ticket so the worker can address review feedback.
-5. Log review result to PM-LOG.md
+3. Delegate review to Vibe Kanban's review agent:
+   - Call `mcp__vibe_kanban__start_workspace_session(task_id, executor="REVIEW_AGENT", repos=[...])`
+   - This launches VK's review agent on the worker's changes
+   - Update TICKET-MAP: review_dispatched=timestamp
+4. Transition back to MONITORING — PM polls `list_tasks()` to detect review outcomes:
+   - VK review agent marks ticket → `done` (review passed)
+   - VK review agent marks ticket → `inprogress` with feedback (review failed, needs fixes)
+   - PM reacts to these transitions in subsequent poll cycles
+5. Log review dispatch to PM-LOG.md
 
 ### WORKER_AUTO_COMPLETED (inprogress → done, bypass review)
 1. Call `get_task(task_id)` to read worker output/notes

package/cook/workflows/pm-cycle.md

@@ -4,16 +4,21 @@
 
 This workflow powers `/cook: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.
 
+The PM runs the **entire project lifecycle** end-to-end: from project initialization through research, roadmapping, planning, ticket creation, worker dispatch, monitoring, code review, phase advancement, and milestone completion — all without stopping.
+
 ## State Classification
 
-Read phase directory and TICKET-MAP.md to classify into exactly one state:
+Read `.planning/` directory and state files to classify into exactly one state:
 
 ```
-NEEDS_PLANNING    → No PLAN.md files
+NEEDS_INIT        → No .planning/ directory or no PROJECT.md
+NEEDS_RESEARCH    → PROJECT.md exists but no .planning/research/SUMMARY.md
+NEEDS_ROADMAP     → Research done but no ROADMAP.md
+NEEDS_PLANNING    → Phase has 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
-NEEDS_REVIEW      → Tickets inreview (awaiting code review)
+NEEDS_REVIEW      → Tickets inreview (awaiting VK review agent)
 PHASE_COMPLETE    → All tickets done, more phases in roadmap
 MILESTONE_COMPLETE → All tickets done, last phase in roadmap
 ```
@@ -21,6 +26,9 @@ MILESTONE_COMPLETE → All tickets done, last phase in roadmap
 ## State Machine
 
 ```
+NEEDS_INIT ──scaffold project──→ NEEDS_RESEARCH
+NEEDS_RESEARCH ──spawn researchers──→ NEEDS_ROADMAP
+NEEDS_ROADMAP ──spawn roadmapper──→ NEEDS_PLANNING
 NEEDS_PLANNING ──spawn planner──→ NEEDS_SYNC
 NEEDS_SYNC ──create tickets──→ NEEDS_DISPATCH
 NEEDS_DISPATCH ──launch workers──→ MONITORING
@@ -29,8 +37,8 @@ MONITORING ──poll + react──→ MONITORING (loop)
                           ──→ NEEDS_DISPATCH (wave complete, next wave ready)
                           ──→ PHASE_COMPLETE (all done)
                           ──→ MONITORING + replan (ticket failed)
-NEEDS_REVIEW ──code review──→ MONITORING (review passed → done, check wave)
-                            ──→ MONITORING (review failed → re-dispatch)
+NEEDS_REVIEW ──VK review agent──→ MONITORING (review passed → done, check wave)
+                                ──→ MONITORING (review failed → re-dispatch)
 PHASE_COMPLETE ──advance phase──→ NEEDS_PLANNING (next phase)
                               ──→ MILESTONE_COMPLETE (last phase)
 MILESTONE_COMPLETE ──stop signal──→ EXIT
@@ -38,6 +46,62 @@ MILESTONE_COMPLETE ──stop signal──→ EXIT
 
 ## Action Details
 
+### NEEDS_INIT
+
+**Goal:** Scaffold the project structure so the PM can operate.
+
+1. Check if `.planning/` directory exists. If not, create it.
+2. Check for PRD or project description:
+   - If `--prd <file>` was passed via pm-loop.sh: read that file as the project description
+   - If a `PRD.md` or `prd.md` exists in the repo root: use it
+   - Otherwise: read any README.md or project files to infer scope
+3. Create `PROJECT.md` from template (follow @~/.claude/cook/templates/project.md):
+   - Fill in: project name, description, goals, tech stack (from existing code or PRD)
+4. Create `config.json` from template (follow @~/.claude/cook/templates/config.json):
+   - Set `pm.project_id` to null (will be discovered during NEEDS_SYNC)
+   - Set defaults for model profile, executor, intervals
+5. Create initial `STATE.md` from template (follow @~/.claude/cook/templates/state.md)
+6. Log to PM-LOG.md:
+   ```markdown
+   ## [{timestamp}] INIT
+
+   - Project scaffolded from {source: PRD/README/description}
+   - Created: PROJECT.md, config.json, STATE.md
+   - Next: Research phase
+   ```
+
+### NEEDS_RESEARCH
+
+**Goal:** Gather domain knowledge and technical context before roadmapping.
+
+1. Read PROJECT.md for project scope and goals
+2. Spawn 4 research agents in parallel via Task tool (run_in_background=true):
+   - **cook-project-researcher** (focus: "architecture") — evaluate architecture patterns
+   - **cook-project-researcher** (focus: "stack") — evaluate tech stack choices
+   - **cook-project-researcher** (focus: "features") — break down feature requirements
+   - **cook-project-researcher** (focus: "pitfalls") — identify risks and common pitfalls
+3. Each researcher writes to `.planning/research/`:
+   - `ARCHITECTURE.md`, `STACK.md`, `FEATURES.md`, `PITFALLS.md`
+4. After all 4 complete, spawn **cook-research-synthesizer**:
+   - Reads all 4 research files
+   - Writes `.planning/research/SUMMARY.md`
+5. Update STATE.md: status → "researched"
+6. Log to PM-LOG.md
+
+### NEEDS_ROADMAP
+
+**Goal:** Create a phased roadmap from research findings.
+
+1. Read `.planning/research/SUMMARY.md` for synthesized findings
+2. Read PROJECT.md for goals and constraints
+3. Spawn **cook-roadmapper** agent via Task tool:
+   - Provide: project context, research summary, milestone goals
+   - Agent writes `ROADMAP.md` to `.planning/`
+   - Roadmap contains: phases with goals, scope, dependencies, success criteria
+4. Create phase directories: `.planning/phases/phase-{N}-{slug}/`
+5. Update STATE.md: current_phase → phase 1, status → "roadmapped"
+6. Log to PM-LOG.md
+
 ### NEEDS_PLANNING
 
 **Goal:** Create PLAN.md files for the current phase.
@@ -109,27 +173,28 @@ Follow `pm-check.md` workflow:
 
 ### NEEDS_REVIEW
 
-**Goal:** Run automated code review on tickets that workers have completed.
+**Goal:** Delegate code review to Vibe Kanban's review agent.
+
+The PM does **not** run its own code reviewer. Instead, it delegates review to the Vibe Kanban platform's review capabilities:
 
 1. Find all tickets with status `inreview` in TICKET-MAP.md
 2. For each `inreview` ticket:
    a. Read ticket details via `mcp__vibe_kanban__get_task(task_id)`
-   b. Spawn `feature-dev:code-reviewer` agent via Task tool:
-      - Provide: ticket title, acceptance criteria, recent git commits
-      - Reviewer examines the diff for bugs, security issues, and code quality
-   c. Based on review verdict:
-      - **PASS:** Update ticket → `done` via `mcp__vibe_kanban__update_task(task_id, status="done")`. Update TICKET-MAP: status=done, review=passed.
-      - **FAIL:** Update ticket → `inprogress` via `mcp__vibe_kanban__update_task(task_id, status="inprogress")`. Append review feedback to ticket description. Re-dispatch worker to address feedback.
-3. After all reviews processed:
-   - Check wave completion (all done → dispatch next wave or PHASE_COMPLETE)
-4. Log review results to PM-LOG.md:
+   b. Dispatch review via Vibe Kanban:
+      - Call `mcp__vibe_kanban__start_workspace_session(task_id, executor="REVIEW_AGENT", repos=[...])`
+      - This launches VK's review agent on the worker's changes
+   c. Update TICKET-MAP: review_dispatched=timestamp
+3. After dispatching reviews, transition back to MONITORING:
+   - PM polls `list_tasks()` to detect review outcomes
+   - When VK review agent completes: ticket → `done` (passed) or → `inprogress` (failed with feedback)
+   - PM reacts to these transitions in the normal MONITORING flow
+4. Log review dispatch to PM-LOG.md:
    ```markdown
-   ## [{timestamp}] CODE_REVIEW
+   ## [{timestamp}] REVIEW_DISPATCH
 
-   - Reviewed {N} tickets
-   - Passed: {list}
-   - Failed: {list with issue summaries}
-   - Actions: {re-dispatched / wave advanced / etc.}
+   - Dispatched VK review for {N} tickets
+   - Tickets: {list}
+   - Next: Monitoring for review outcomes
    ```
 
 ### PHASE_COMPLETE
@@ -169,6 +234,7 @@ Every action writes a timestamped entry:
 
 - VK API errors: Log error, exit with code 1 (shell loop retries next cycle)
 - Planner spawn failure: Log error, exit with code 1
+- Research agent failure: Log error, retry next cycle (partial research is ok)
 - 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 `/cook:pm-start`
+- State file missing: Auto-detect correct state from filesystem and recover

package/package.json

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

@@ -7,13 +7,14 @@
 # State persists via .planning/ files.
 #
 # The PM brain handles the ENTIRE lifecycle autonomously:
-#   plan → sync tickets → dispatch workers → monitor → replan → advance phases → complete milestone
+#   init → research → roadmap → plan → sync tickets → dispatch workers → monitor → review → 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]
+#   ./scripts/pm-loop.sh --init --prd=PRD.md    # Start from scratch with PRD
 #   PM_PHASE=1 PM_POLL_INTERVAL=30 ./scripts/pm-loop.sh
 #
 # Stop:
@@ -32,9 +33,18 @@ MAX_CALLS_PER_HOUR="${PM_MAX_CALLS_PER_HOUR:-0}"  # 0 = unlimited
 MAX_REPLAN_ATTEMPTS="${PM_MAX_REPLAN_ATTEMPTS:-3}"
 BACKGROUND=false
 NOTIFY=true
+INIT_MODE=false
+PRD_FILE=""
 
 for arg in "$@"; do
   case $arg in
+    --init)
+      INIT_MODE=true
+      ;;
+    --prd=*)
+      PRD_FILE="${arg#*=}"
+      INIT_MODE=true
+      ;;
     --phase=*)
       PHASE="${arg#*=}"
       ;;
@@ -68,15 +78,16 @@ for arg in "$@"; do
       exit 0
       ;;
     --help|-h)
-      echo "Usage: pm-loop.sh [--phase=N] [--interval=60] [--max-iterations=0] [--calls=0]"
+      echo "Usage: pm-loop.sh [--phase=N] [--init] [--prd=FILE] [--interval=60] [--max-iterations=0]"
       echo ""
-      echo "Fully autonomous PM loop. Each cycle invokes /cook:pm-cycle which"
-      echo "reads state and decides what to do: plan, sync, dispatch, monitor,"
-      echo "replan, advance phases, or complete milestone."
+      echo "Fully autonomous PM loop. Runs the ENTIRE project lifecycle:"
+      echo "init → research → roadmap → plan → sync → dispatch → monitor → review → advance"
       echo ""
       echo "Runs in FOREGROUND by default — you see live progress."
       echo ""
       echo "Options:"
+      echo "  --init              Start from scratch (create .planning/)"
+      echo "  --prd=FILE          Provide PRD file for project init (implies --init)"
       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)"
@@ -106,12 +117,18 @@ done
 
 # ─── Validate ─────────────────────────────────────────────────────
 
-if [ ! -d ".planning" ]; then
+if [ ! -d ".planning" ] && [ "$INIT_MODE" = false ]; then
   echo "ERROR: No .planning/ directory found."
-  echo "Run /cook:new-project first, then /cook:pm-start"
+  echo "Run with --init to start from scratch, or /cook:new-project first"
   exit 1
 fi
 
+# Create .planning/ if --init and it doesn't exist
+if [ "$INIT_MODE" = true ] && [ ! -d ".planning" ]; then
+  mkdir -p .planning
+  echo "Created .planning/ directory"
+fi
+
 if ! command -v claude &> /dev/null; then
   echo "ERROR: claude CLI not found in PATH."
   echo "Install: https://docs.anthropic.com/en/docs/claude-code"
@@ -470,10 +487,13 @@ while true; do
   echo ""
 
   # Build the prompt
-  # Only pass phase hint on cycle 1 — after that, pm-cycle auto-detects
+  # Cycle 1: pass phase hint and PRD if provided. After that, pm-cycle auto-detects
   # from STATE.md so it can advance through phases autonomously.
-  if [ "$CYCLE" -eq 1 ] && [ -n "$PHASE" ]; then
-    PROMPT="/cook:pm-cycle $PHASE"
+  if [ "$CYCLE" -eq 1 ]; then
+    PROMPT="/cook:pm-cycle"
+    [ -n "$PHASE" ] && PROMPT="$PROMPT $PHASE"
+    [ "$INIT_MODE" = true ] && PROMPT="$PROMPT --init"
+    [ -n "$PRD_FILE" ] && PROMPT="$PROMPT --prd=$PRD_FILE"
   else
     PROMPT="/cook:pm-cycle"
   fi