@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/pbr/skills/begin/SKILL.md

@@ -6,9 +6,11 @@ allowed-tools: Read, Write, Bash, Glob, Grep, WebFetch, WebSearch, Task, AskUser
 
 **STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**
 
-# /pbr:begin — Project Initialization
+# /pbr:new-project — Project Initialization
 
-You are the orchestrator for `/pbr:begin`. This skill initializes a new Plan-Build-Run project through deep questioning, optional research, requirements scoping, and roadmap generation. Your job is to stay lean — delegate heavy work to Task() subagents and keep the user's main context window clean.
+**References:** `@references/questioning.md`, `@references/ui-brand.md`
+
+You are the orchestrator for `/pbr:new-project`. This skill initializes a new Plan-Build-Run project through deep questioning, optional research, requirements scoping, and roadmap generation. Your job is to stay lean — delegate heavy work to Task() subagents and keep the user's main context window clean.
 
 ## Context Budget
 
@@ -23,13 +25,29 @@ Additionally for this skill:
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► STARTING PROJECT
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► STARTING PROJECT                           ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
 
+## Multi-Session Sync
+
+Before any phase-modifying operations, this skill acquires a claim on the project:
+
+```
+acquireClaim(planningDir, sessionId)
+```
+
+Where `planningDir` is the `.planning/` directory and `sessionId` is the current session identifier. If the claim fails (another session owns it), display: "Another session owns this project. Use `/pbr:progress` to see active claims."
+
+On completion or error, release the claim:
+
+```
+releaseClaim(planningDir, sessionId)
+```
+
 ## Prerequisites
 
 - Working directory should be the project root
@@ -60,11 +78,11 @@ Check if the current directory has existing code:
 
 **If existing code found:**
 Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
-  question: "This looks like an existing codebase. Run /pbr:scan to analyze what's here first?"
+  question: "This looks like an existing codebase. Run /pbr:map-codebase to analyze what's here first?"
   options:
-    - label: "Yes, scan"   description: "Run /pbr:scan first to analyze existing code"
-    - label: "No, begin"   description: "Proceed with /pbr:begin on top of existing code"
-- If user selects "Yes, scan": suggest `/pbr:scan` and stop
+    - label: "Yes, scan"   description: "Run /pbr:map-codebase first to analyze existing code"
+    - label: "No, begin"   description: "Proceed with /pbr:new-project on top of existing code"
+- If user selects "Yes, scan": suggest `/pbr:map-codebase` and stop
 - If user selects "No, begin": proceed to Step 2
 
 **If `.planning/` already exists:**
@@ -75,7 +93,7 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
     - label: "No"   description: "Cancel — keep existing planning"
 - If user selects "No": **STOP IMMEDIATELY. Do not ask again. Do not proceed to Step 2. End the skill with this message:**
   ```
-  Keeping existing .planning/ directory. Use `/pbr:status` to see current project state, or `/pbr:plan` to continue planning.
+  Keeping existing .planning/ directory. Use `/pbr:progress` to see current project state, or `/pbr:plan-phase` to continue planning.
   ```
   **Do NOT re-prompt the same question or any other question. The skill is finished.**
 - If user selects "Yes": proceed (existing directory will be overwritten during state initialization)
@@ -119,10 +137,142 @@ Have a natural conversation to understand the user's vision. Do NOT present a fo
 
 ---
 
+### Step 2.5: Fast-Path Offer (inline)
+
+Before asking any workflow preference questions, offer the user a quick-start option:
+
+Use AskUserQuestion:
+  question: "How do you want to configure this project?"
+  header: "Setup mode"
+  options:
+    - label: "Quick start"
+      description: "Use all defaults — model balanced, depth standard, interactive mode, parallel on. Writes config in seconds."
+    - label: "Custom setup"
+      description: "Walk through model selection, features, and preferences step by step."
+
+**If user selects "Quick start":**
+- Tell the user: "Tip: Agents set to `inherit` use your Claude Code session model. For cost savings, run on Sonnet -- orchestration and inherit agents work well at that tier. See `references/model-profiles.md` for details."
+- Write `.planning/config.json` immediately using the default config below (no further questions):
+  ```json
+  {
+    "version": 2,
+    "context_strategy": "aggressive",
+    "mode": "interactive",
+    "depth": "standard",
+    "context_window_tokens": 200000,
+    "features": {
+      "structured_planning": true,
+      "goal_verification": true,
+      "integration_verification": true,
+      "context_isolation": true,
+      "atomic_commits": true,
+      "session_persistence": true,
+      "research_phase": true,
+      "plan_checking": true,
+      "tdd_mode": false,
+      "status_line": true,
+      "auto_continue": false,
+      "auto_advance": false,
+      "team_discussions": false,
+      "inline_verify": false
+    },
+    "models": {
+      "researcher": "sonnet",
+      "planner": "inherit",
+      "executor": "inherit",
+      "verifier": "sonnet",
+      "integration_checker": "sonnet",
+      "debugger": "inherit",
+      "mapper": "sonnet",
+      "synthesizer": "haiku"
+    },
+    "parallelization": {
+      "enabled": true,
+      "plan_level": true,
+      "task_level": false,
+      "max_concurrent_agents": 3,
+      "min_plans_for_parallel": 2,
+      "use_teams": false
+    },
+    "planning": {
+      "commit_docs": true,
+      "max_tasks_per_plan": 3,
+      "search_gitignored": false
+    },
+    "git": {
+      "branching": "none",
+      "commit_format": "{type}({phase}-{plan}): {description}",
+      "phase_branch_template": "plan-build-run/phase-{phase}-{slug}",
+      "milestone_branch_template": "plan-build-run/{milestone}-{slug}",
+      "mode": "enabled"
+    },
+    "gates": {
+      "confirm_project": true,
+      "confirm_roadmap": true,
+      "confirm_plan": true,
+      "confirm_execute": false,
+      "confirm_transition": true,
+      "issues_review": true
+    },
+    "safety": {
+      "always_confirm_destructive": true,
+      "always_confirm_external_services": true
+    }
+  }
+  ```
+- Write `.planning/.active-skill` with text "begin"
+- Write CLAUDE.md integration block (see Step 3d-claude below) using the project name gathered in Step 2
+- Skip to Step 4 (Research Decision)
+- Tell the user: "Quick start selected. Using all defaults — you can adjust later with `/pbr:settings`."
+
+**If user selects "Custom setup":** proceed to Step 3 normally.
+
+---
+
 ### Step 3: Workflow Preferences (inline)
 
 After understanding the project, configure the Plan-Build-Run workflow. Use AskUserQuestion for each preference below. Present them sequentially with conversational bridging (e.g., "Great. Next...") to keep the flow natural.
 
+**3-model. Model Profile:**
+Note: These profiles control agent models. The orchestrator uses your Claude Code session model. For cost optimization, consider running on Sonnet -- agents with `inherit` will follow. See `references/model-profiles.md`.
+
+Use AskUserQuestion:
+  question: "Which model profile should agents use?"
+  header: "Models"
+  options:
+    - label: "Balanced (Recommended)"
+      description: "Sonnet for most agents, Haiku for synthesizer. Good quality/cost tradeoff."
+    - label: "Quality"
+      description: "Opus for executor and planner, Sonnet for others. Best results, highest cost."
+    - label: "Budget"
+      description: "Haiku for most agents. Fastest and cheapest, but lower quality."
+
+Apply the selected profile to the models block in config.json:
+- **Balanced**: executor=sonnet, researcher=sonnet, planner=sonnet, verifier=sonnet, synthesizer=haiku, context_window_tokens=200000, agent_checkpoint_pct=50
+- **Quality**: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet, context_window_tokens=1000000, agent_checkpoint_pct=65
+- **Budget**: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku, context_window_tokens=200000, agent_checkpoint_pct=50
+
+**3-features. Workflow Features:**
+Use AskUserQuestion:
+  question: "Any extra workflow features?"
+  header: "Features"
+  multiSelect: true
+  options:
+    - label: "Auto-continue"
+      description: "Automatically chain commands (build → review → next phase) without prompting"
+    - label: "TDD mode"
+      description: "Write tests before implementation in executor agents"
+    - label: "Strict gates"
+      description: "Require verification AND review to pass before advancing phases"
+    - label: "Git branching"
+      description: "Create a branch per phase for cleaner PR history"
+
+Apply selections:
+- **Auto-continue**: Set `features.auto_continue: true`
+- **TDD mode**: Set `features.tdd_mode: true`
+- **Strict gates**: Set `gates.verification: true`, `gates.review: true`, `gates.plan_approval: true`
+- **Git branching**: Set `git.branching: "phase"`
+
 **3a. Mode:**
 Use the **toggle-confirm** pattern from `skills/shared/gate-prompts.md`:
   question: "How do you want to work?"
@@ -166,15 +316,40 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
 - `yes` (default) — commit planning docs
 - `no` — add .planning/ to .gitignore
 
+**3d-claude. CLAUDE.md Integration:**
+
+Check if a `CLAUDE.md` file exists in the project root.
+
+**If it exists**: Read it. If it does NOT already contain a "Plan-Build-Run" section, append the block below.
+**If it does NOT exist**: Create `CLAUDE.md` with the block below.
+
+Append/create:
+
+```markdown
+## Plan-Build-Run
+
+This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run) for structured development.
+
+- Project state: `.planning/STATE.md` (source of truth for current phase and progress)
+- Configuration: `.planning/config.json`
+- Run `/pbr:progress` to see current project state and suggested next action.
+
+**After compaction or context recovery**: Read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
+```
+
 **After gathering preferences:**
 
-1. Read the config template from `skills/begin/templates/config.json.tmpl`
-2. Apply the user's choices to the template
+**CRITICAL (no hook): You MUST create the .planning/ directory and write config.json NOW. Do not proceed without this.**
+
+1. Read the config template from `${CLAUDE_SKILL_DIR}/templates/config.json.tmpl`
+2. Apply the user's choices to the template (including 3d-claude CLAUDE.md integration)
 3. Create `.planning/` directory
 4. Write `.planning/config.json` with the user's preferences
 
 **IMPORTANT**: This step MUST happen BEFORE research (Step 5) because depth controls how many researchers to spawn.
 
+**CRITICAL (hook-enforced): Write .active-skill NOW.** Write the text "begin" to `.planning/.active-skill` using the Write tool. Verify the file exists before proceeding.
+
 ---
 
 ### Step 4: Research Decision (inline)
@@ -195,13 +370,23 @@ Based on the depth setting from Step 3, determine the research approach:
 - Tell user: "Skipping research phase (depth: quick). Moving straight to requirements."
 
 **If depth is `standard` or `comprehensive`:**
-Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
-  question: "I'd like to research the technology landscape before planning. This helps create better plans. Proceed with research?"
-  options:
-    - label: "Yes"  description: "Run research agents (recommended for standard/comprehensive)"
-    - label: "No"   description: "Skip research, move straight to requirements"
-- If user selects "No": skip to Step 7
-- If user selects "Yes": proceed to Step 5
+
+**Auto-mode bypass:** If the `--auto` flag is active or `config.mode === 'autonomous'`:
+- Default to `standard` depth (2 researchers: STACK, FEATURES) unless depth was explicitly set to `comprehensive`
+- Set `gates.confirm_research` to `false` (skip the depth selection gate)
+- Display: "PBR > Auto-mode: advancing to research (standard depth)..."
+- Proceed directly to Step 5
+
+**Interactive mode (default):**
+- If `gates.confirm_research` is `true` in config:
+  Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
+    question: "I'd like to research the technology landscape before planning. This helps create better plans. Proceed with research?"
+    options:
+      - label: "Yes"  description: "Run research agents (recommended for standard/comprehensive)"
+      - label: "No"   description: "Skip research, move straight to requirements"
+  - If user selects "No": skip to Step 7
+  - If user selects "Yes": proceed to Step 5
+- If `gates.confirm_research` is `false` (default): proceed directly to Step 5 (research runs automatically)
 
 ---
 
@@ -209,13 +394,33 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
 
 Spawn parallel Task() subagents for research. Each researcher writes to `.planning/research/`.
 
-**Create `.planning/research/` directory first.**
+**CRITICAL (no hook): Create .planning/research/ directory NOW before spawning researchers. Do NOT skip this step.**
+
+**Learnings injection (opt-in):** Before spawning researchers, check if global learnings exist:
+
+```bash
+node {resolved_plugin_root}/scripts/pbr-tools.js learnings query --tags "stack,tech" 2>/dev/null
+```
+
+If the command succeeds AND returns a non-empty JSON array:
+
+- Write the results to a temp file:
+
+  ```bash
+  node {resolved_plugin_root}/scripts/pbr-tools.js learnings query --tags "stack,tech" > /tmp/pbr-learnings-$$.md
+  ```
+
+- Note the temp file path as `{learnings_temp_path}`
+- Add this file to the researcher's `files_to_read` block (see below)
+
+If no learnings exist or the command fails: skip injection silently.
 
 **For each research topic, spawn a Task():**
 
 ```
 Task({
   subagent_type: "pbr:researcher",
+  // After researcher: check for ## RESEARCH COMPLETE or ## RESEARCH BLOCKED
   prompt: <see researcher prompt template below>
 })
 ```
@@ -228,7 +433,19 @@ Task({
 
 For each researcher, construct the prompt by reading the template and filling in placeholders:
 
-Read `skills/begin/templates/researcher-prompt.md.tmpl` for the prompt structure.
+Read `${CLAUDE_SKILL_DIR}/templates/researcher-prompt.md.tmpl` for the prompt structure.
+
+**Prepend this block to the researcher prompt before sending:**
+
+```
+<files_to_read>
+CRITICAL (no hook): Read these files BEFORE any other action:
+1. .planning/REQUIREMENTS.md — scoped requirements (if exists)
+{if learnings_temp_path exists}2. {learnings_temp_path} — cross-project learnings (tech stack patterns from past PBR projects){/if}
+</files_to_read>
+```
+
+If `{learnings_temp_path}` was produced in the learnings injection step above, replace `{if...}{/if}` with the actual line. If no learnings were found, omit line 2 entirely.
 
 **Placeholders to fill:**
 - `{project name from questioning}` — project name gathered in Step 2
@@ -265,10 +482,23 @@ Read `skills/begin/templates/researcher-prompt.md.tmpl` for the prompt structure
 - What performance issues are typical?
 - What security concerns exist?
 
+**Domain-specific template injection:**
+
+Each researcher must be told which domain-specific template to follow. When constructing the researcher prompt, inject the correct template path for the assigned topic:
+
+| Topic | Template Path |
+|-------|--------------|
+| STACK | `${CLAUDE_PLUGIN_ROOT}/templates/research-outputs/STACK.md.tmpl` |
+| FEATURES | `${CLAUDE_PLUGIN_ROOT}/templates/research-outputs/FEATURES.md.tmpl` |
+| ARCHITECTURE | `${CLAUDE_PLUGIN_ROOT}/templates/research-outputs/ARCHITECTURE.md.tmpl` |
+| PITFALLS | `${CLAUDE_PLUGIN_ROOT}/templates/research-outputs/PITFALLS.md.tmpl` |
+
+Include the resolved absolute path in the researcher prompt (resolve `${CLAUDE_PLUGIN_ROOT}` before sending).
+
 **Parallelization:**
 - Spawn ALL researchers in parallel (multiple Task() calls in one response)
 - Use `run_in_background: true` for each researcher
-- Before spawning, display to the user: `◐ Spawning {N} researchers in parallel...`
+- Before spawning, display to the user: `◆ Spawning {N} researchers in parallel...`
 - While waiting, display progress to the user:
   - After spawning: list of topics being researched
   - Periodically (every ~30s): check `TaskOutput` with `block: false` for each agent and report status
@@ -276,11 +506,53 @@ Read `skills/begin/templates/researcher-prompt.md.tmpl` for the prompt structure
   - When all complete: "All {N} researchers finished. Proceeding to synthesis."
 - Wait for all to complete before proceeding
 
+#### Partial Failure Detection
+
+After all researchers complete (or timeout), check which research files were actually produced:
+
+1. List files in `.planning/research/` (excluding SUMMARY.md)
+2. Map against expected files for the current depth level:
+   - **standard**: expect STACK.md, FEATURES.md (2 files)
+   - **comprehensive**: expect STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md (4 files)
+3. Count successes and failures
+4. For files that exist, also check for `## RESEARCH BLOCKED` marker -- count these as "completed with issues" (still pass to synthesizer, which handles them)
+
+**If all expected files present:** proceed to Step 6.
+
+**If some files missing (partial failure):**
+
+Display: "Research partially complete: {N} of {M} researchers succeeded."
+List the missing dimensions.
+
+**Auto-mode:** Display "Continuing with gaps (auto-mode). Gaps will be noted in synthesis." and proceed to Step 6.
+
+**Interactive mode:** Use AskUserQuestion with 3 options:
+
+```
+question: "Research partially complete. {N} of {M} researchers succeeded. How would you like to proceed?"
+header: "Partial Research"
+options:
+  - label: "Continue with gaps"
+    description: "Proceed to synthesis -- gaps will be noted in SUMMARY.md"
+  - label: "Retry failed"
+    description: "Re-spawn only the failed researchers, then re-check"
+  - label: "Abort research"
+    description: "Skip research entirely and move to requirements"
+```
+
+- If "Continue with gaps": proceed to Step 6
+- If "Retry failed": re-spawn only the failed researchers (same Task() pattern), then re-run partial failure detection
+- If "Abort research": skip to Step 7 (Requirements Scoping)
+
 ---
 
 ### Step 6: Synthesis (delegated to subagent)
 
-After all researchers complete, display to the user: `◐ Spawning synthesizer...`
+**Auto-mode bypass:** If the `--auto` flag is active or `config.mode === 'autonomous'`, skip the "Research complete. Review findings?" gate and proceed directly to synthesizer spawning.
+
+**Interactive mode:** If a review gate is configured (e.g., `gates.confirm_research_review`), present the research findings and ask the user to review before synthesis. Preserve the existing review gate behavior.
+
+After all researchers complete (and review gate passed or bypassed), display to the user: `◆ Spawning synthesizer...`
 
 Spawn a synthesis agent:
 
@@ -297,12 +569,42 @@ Task({
 
 #### Synthesis Prompt Template
 
-Read `skills/begin/templates/synthesis-prompt.md.tmpl` for the prompt structure.
+Read `${CLAUDE_SKILL_DIR}/templates/synthesis-prompt.md.tmpl` for the prompt structure.
+
+**Prepend this block to the synthesizer prompt before sending:**
+```
+<files_to_read>
+CRITICAL (no hook): Read these files BEFORE any other action:
+1. .planning/research/*.md — all research output files from Step 5
+</files_to_read>
+```
+
+**Dynamic file discovery:** Do NOT pass a hardcoded list of research files. Instead, instruct the synthesizer to "Read ALL .md files in the `.planning/research/` directory (excluding SUMMARY.md). These are your research inputs." The synthesizer discovers available files at runtime, which handles partial failure gracefully.
+
+**Commit instruction:** Instruct the synthesizer to commit all research files together after producing SUMMARY.md: "After writing SUMMARY.md, commit ALL files in `.planning/research/` together with message: `docs(research): complete research synthesis`"
 
 **Placeholders to fill:**
-- `{List all .planning/research/*.md files that were created}` — list the research files produced in Step 5
+- `{List all .planning/research/*.md files that were created}` — list the research files produced in Step 5 (for reference, but synthesizer uses dynamic discovery)
+
+**After the synthesizer completes**, check for completion markers in the Task() output:
 
-**After the synthesizer completes**, display:
+- If `## SYNTHESIS COMPLETE` is present: proceed normally
+- If `## SYNTHESIS BLOCKED` is present: warn the user and offer to proceed without synthesis:
+  ```
+  ⚠ Synthesizer reported BLOCKED: {reason from output}
+  Research files are still available individually in .planning/research/.
+  ```
+  Use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
+    question: "Synthesis was blocked. Continue without synthesis?"
+    header: "Blocked"
+    options:
+      - label: "Yes"  description: "Proceed to requirements — use individual research files"
+      - label: "No"   description: "Stop and investigate"
+  - If "Yes": proceed to Step 7 without SUMMARY.md
+  - If "No": stop and suggest reviewing .planning/research/ files
+- If neither marker is found: warn the user that the synthesizer may not have completed successfully, but proceed if SUMMARY.md exists on disk
+
+If synthesis succeeded, display:
 ```
 ✓ Research synthesis complete — see .planning/research/SUMMARY.md
 ```
@@ -311,6 +613,8 @@ Read `skills/begin/templates/synthesis-prompt.md.tmpl` for the prompt structure.
 
 ### Step 7: Requirements Scoping (inline)
 
+**Auto-mode chaining:** If `config.mode === 'autonomous'`, display "PBR > Auto-mode: advancing to requirements scoping..." and proceed through this step without interactive gates. Auto-derive requirements from research findings and questioning context. Classify all identified features as v1 (committed) unless they clearly belong in a later phase.
+
 Present research findings (if any) and interactively scope requirements with the user.
 
 **7a. Present findings:**
@@ -331,11 +635,10 @@ For each category, present the features and ask the user to classify each:
 - **Out of scope** — Will NOT be built
 
 **7d. Assign REQ-IDs:**
-For each committed requirement, assign an ID in the format `{CATEGORY}-{NN}`:
-- `AUTH-01`: User can log in with Discord OAuth
-- `AUTH-02`: Protected routes redirect to login
-- `UI-01`: Dashboard shows player statistics
-- `UI-02`: Mobile-responsive layout
+For each committed requirement, assign an ID using the REQ-F/REQ-NF schema:
+- Functional requirements: `REQ-F-xxx` numbered sequentially within each category (REQ-F-001, REQ-F-002, ...)
+- Non-functional requirements: `REQ-NF-xxx` numbered sequentially across all NFR categories (REQ-NF-001, REQ-NF-002, ...)
+- Examples: `REQ-F-001: User can log in with Discord OAuth`, `REQ-NF-001: Page loads in <2s on 4G`
 
 Each requirement must be:
 - **User-centric** — describes a capability from the user's perspective
@@ -343,7 +646,10 @@ Each requirement must be:
 - **Specific** — not vague ("fast" is bad, "page loads in <2s" is good)
 
 **7e. Write REQUIREMENTS.md:**
-Read the template from `skills/begin/templates/REQUIREMENTS.md.tmpl` and write `.planning/REQUIREMENTS.md` with:
+
+**CRITICAL (no hook): Write REQUIREMENTS.md NOW. The roadmap planner depends on this file.**
+
+Read the template from `${CLAUDE_SKILL_DIR}/templates/REQUIREMENTS.md.tmpl` and write `.planning/REQUIREMENTS.md` with:
 - All v1 requirements grouped by category
 - All v2 requirements with deferral reasons
 - Out-of-scope items with rationale
@@ -353,13 +659,14 @@ Read the template from `skills/begin/templates/REQUIREMENTS.md.tmpl` and write `
 
 ### Step 8: Roadmap Generation (delegated to subagent)
 
-Display to the user: `◐ Spawning planner (roadmap)...`
+Display to the user: `◆ Spawning planner (roadmap)...`
 
 Spawn the planner in roadmap mode:
 
 ```
 Task({
   subagent_type: "pbr:planner",
+  // After planner: check for ## PLANNING COMPLETE or ## PLANNING FAILED
   prompt: <roadmap prompt>
 })
 ```
@@ -370,7 +677,16 @@ Task({
 
 #### Roadmap Prompt Template
 
-Read `skills/begin/templates/roadmap-prompt.md.tmpl` for the prompt structure.
+Read `${CLAUDE_SKILL_DIR}/templates/roadmap-prompt.md.tmpl` for the prompt structure.
+
+**Prepend this block to the roadmap planner prompt before sending:**
+```
+<files_to_read>
+CRITICAL (no hook): Read these files BEFORE any other action:
+1. .planning/REQUIREMENTS.md — scoped requirements for phase planning
+2. .planning/research/SUMMARY.md — research synthesis (if exists)
+</files_to_read>
+```
 
 **Placeholders to fill:**
 - `{project name}` — project name from Step 2
@@ -378,13 +694,16 @@ Read `skills/begin/templates/roadmap-prompt.md.tmpl` for the prompt structure.
 - `{quick|standard|comprehensive}` — depth setting from Step 3
 
 **After the planner completes:**
+- **Spot-check:** Verify `.planning/ROADMAP.md` exists on disk using Glob before attempting to read it. If missing, the planner may have failed silently — warn: `⚠ ROADMAP.md not found after planner completed. Re-spawning planner...` and retry once.
 - Read `.planning/ROADMAP.md`
-- Count the phases and milestones from the roadmap content
+- Count the phases from the roadmap content
+- Verify the roadmap contains a `## Milestone:` section wrapping the phases (the planner should generate this). If not, the initial set of phases constitutes the first milestone — add the section header yourself.
 - Display:
   ```
-  ✓ Roadmap created — {N} phases across {M} milestones
+  ✓ Roadmap created — {N} phases in milestone "{name}"
   ```
-- If `gates.confirm_roadmap` is true in config, use the **approve-revise-abort** pattern from `skills/shared/gate-prompts.md`:
+- **Auto-mode bypass:** If `config.mode === 'autonomous'`, display "PBR > Auto-mode: advancing to state initialization..." and skip the roadmap approval gate. Proceed directly to Step 9.
+- If `gates.confirm_roadmap` is true in config (interactive mode), use the **approve-revise-abort** pattern from `skills/shared/gate-prompts.md`:
   question: "Approve this roadmap?"
   options:
     - label: "Approve"          description: "Proceed with this roadmap"
@@ -400,8 +719,12 @@ Read `skills/begin/templates/roadmap-prompt.md.tmpl` for the prompt structure.
 
 Write the project state files from templates:
 
+**CRITICAL (no hook): You MUST write all 5 state initialization files (Steps 9a-9e). Do NOT skip any.**
+
+**CRITICAL (no hook): Write PROJECT.md NOW. Do NOT skip this step.**
+
 **9a. Write PROJECT.md:**
-1. Read `skills/begin/templates/PROJECT.md.tmpl`
+1. Read `${CLAUDE_SKILL_DIR}/templates/PROJECT.md.tmpl`
 2. Fill in:
    - `{project_name}` — from questioning
    - `{2-3 sentences}` — project description from questioning
@@ -412,8 +735,10 @@ Write the project state files from templates:
 3. Write to `.planning/PROJECT.md`
 4. Ensure the `## Milestones` section is filled in with the project name and phase count from the roadmap
 
+**CRITICAL (no hook): Write STATE.md NOW. Do NOT skip this step.**
+
 **9b. Write STATE.md:**
-1. Read `skills/begin/templates/STATE.md.tmpl`
+1. Read `${CLAUDE_SKILL_DIR}/templates/STATE.md.tmpl`
 2. Fill in:
    - `{date}` — today's date
    - `{total}` — total phase count from roadmap
@@ -424,43 +749,42 @@ Write the project state files from templates:
 4. Fill in the `## Milestone` section with the project name and total phase count
 5. **STATE.md size limit**: Follow size limit enforcement rules in `skills/shared/state-update.md` (150 lines max).
 
-**9c. Write CONTEXT.md:**
-Create `.planning/CONTEXT.md` from information gathered during questioning:
-
-```markdown
-# Project Context
-
-## Locked Decisions
-{Technology choices, architecture decisions, and constraints that are NON-NEGOTIABLE}
-
-| Decision | Rationale | Locked By |
-|----------|-----------|-----------|
-| {e.g., "Use TypeScript"} | {User preference, team skill} | User |
+**CRITICAL (no hook): Write context to PROJECT.md NOW. Do NOT skip this step.**
 
-## User Constraints
-{Budget, timeline, skill level, hosting, team size}
+**9c. Write context to PROJECT.md ## Context section:**
+1. Read `${CLAUDE_SKILL_DIR}/templates/project-CONTEXT.md.tmpl`
+2. Fill in from the questioning conversation:
+   - Locked Decisions: all technology choices and architecture decisions from Step 2
+   - User Constraints: budget, timeline, skill level, hosting, team
+   - Deferred Ideas: out-of-scope items identified in Step 7c scoping
+   - Claude's Discretion: any areas where user said "you decide"
+3. Append to `.planning/PROJECT.md` under a `## Context` section with subsections:
+   - `### Locked Decisions`
+   - `### User Constraints`
+   - `### Deferred Ideas`
+4. Do NOT write a separate CONTEXT.md file. All context lives in PROJECT.md now.
+5. **Backwards compat migration:** If `.planning/CONTEXT.md` exists (from a prior project version), read its content and merge into PROJECT.md ## Context section. Log: "PBR > Migrated CONTEXT.md into PROJECT.md"
 
-## Deferred Ideas
-{Features explicitly moved to v2 or out-of-scope}
+**CRITICAL (no hook): Write history to STATE.md NOW. Do NOT skip this step.**
 
-| Idea | Reason Deferred |
-|------|----------------|
-| {feature} | {reason} |
-```
-
-**9d. Write HISTORY.md:**
-Create `.planning/HISTORY.md` with an initial entry:
+**9d. Write initial history to STATE.md ## History section:**
+Append to `.planning/STATE.md` a `## History` section with the initial entry:
 
 ```markdown
-# Project History
+## History
 
-## {date} — Project Created
+### {date} -- Project Created
 
 - Initialized Plan-Build-Run project
 - Depth: {depth}, Mode: {mode}
 - Roadmap: {N} phases planned
 ```
 
+Do NOT write a separate HISTORY.md file. All history lives in STATE.md now.
+**Backwards compat:** If `.planning/HISTORY.md` exists, the history.js library reads from it as a fallback. On next historyAppend call, entries go to STATE.md ## History.
+
+**CRITICAL (no hook): Create phase directories NOW. Do NOT skip this step.**
+
 **9e. Create phase directories:**
 For each phase in the roadmap, create the directory structure:
 ```
@@ -492,62 +816,34 @@ If `gates.confirm_project` is true in config:
   - Phases: {count} phases in roadmap
   - Requirements: {count} v1 requirements
   - Config: depth={depth}, mode={mode}
-- Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
-  question: "Everything look good? Commit the planning docs?"
-  options:
-    - label: "Yes"  description: "Stage and commit .planning/ files"
-    - label: "No"   description: "Let me review and adjust first"
-- If user selects "Yes" and `planning.commit_docs` is true:
-  - Stage `.planning/` files (excluding research/ if gitignored)
-  - Commit: `chore: initialize plan-build-run project planning`
-- If user selects "No": let user review and adjust
+- If `gates.confirm_commit_docs` is `true` OR this is a **brownfield** project (existing code detected in Step 1):
+  Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
+    question: "Everything look good? Commit the planning docs?"
+    options:
+      - label: "Yes"  description: "Stage and commit .planning/ files"
+      - label: "No"   description: "Let me review and adjust first"
+  - If user selects "Yes" and `planning.commit_docs` is true:
+    - Stage `.planning/` files (excluding research/ if gitignored)
+    - Commit: `chore: initialize plan-build-run project planning`
+  - If user selects "No": let user review and adjust
+- If `gates.confirm_commit_docs` is `false` AND greenfield: skip the question and commit automatically if `planning.commit_docs` is true
 
 ---
 
-## Completion
-
-After all steps complete, present the final summary:
+## Cleanup
 
-Use the branded stage banner from `references/ui-formatting.md`:
+Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.
 
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PROJECT INITIALIZED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**{name}**
-
-{core value one-liner}
-
-Roadmap: {N} phases
-  1. {Phase 1 name}
-  2. {Phase 2 name}
-  ...
-
-Requirements: {N} committed, {M} deferred, {K} out-of-scope
-```
-
-Then use the "Next Up" routing block:
-```
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Phase 1: {Name}** — {one-line goal}
-
-`/pbr:discuss 1`
-
-<sub>`/clear` first → fresh context window</sub>
+## Completion
 
-───────────────────────────────────────────────────────────────
+After all steps complete, present the final summary using the stage banner format from Read `references/ui-brand.md`:
 
-**Also available:**
-- `/pbr:explore` — open-ended exploration before planning
-- `/pbr:plan 1` — jump straight to planning Phase 1
-- `/pbr:config` — adjust workflow settings
+Display the `PROJECT INITIALIZED ✓` banner with project name, core value, phase list, and requirement counts. Then display the "Next Up" block (see § "Next Up Block" in ui-brand.md) pointing to `/pbr:discuss-phase 1` with alternatives: `/pbr:explore`, `/pbr:plan-phase 1`, `/pbr:new-milestone`, `/pbr:settings`. Include `<sub>/clear first → fresh context window</sub>` inside the Next Up routing block.
 
-───────────────────────────────────────────────────────────────
-```
+**Auto-mode chaining to first phase discussion:** If `config.mode === 'autonomous'`, after displaying the completion banner, automatically chain to the first phase discussion:
+- Display: "PBR > Auto-mode: advancing to phase 1 discussion..."
+- Write `.planning/.auto-next` with `/pbr:discuss-phase 1` to trigger auto-continue hook
+- If any stage in the auto-mode chain fails, stop the chain and report: "PBR > Auto-mode chain stopped: {stage} failed. Resume manually with `/pbr:{next_command}`."
 
 ---
 
@@ -557,7 +853,7 @@ Then use the "Next Up" routing block:
 If a researcher Task() fails or times out:
 - Note which topic wasn't researched
 - Continue with available research
-- Display: `⚠ Research on {topic} failed. Proceeding without it. You can re-research during /pbr:plan.`
+- Display: `⚠ Research on {topic} failed. Proceeding without it. You can re-research during /pbr:plan-phase.`
 
 ### User wants to restart
 If user says they want to start over mid-flow:
@@ -578,7 +874,7 @@ Cannot create .planning/ directory.
 
 ---
 
-## Files Created by /pbr:begin
+## Files Created by /pbr:new-project
 
 | File | Purpose | When |
 |------|---------|------|
@@ -587,8 +883,6 @@ Cannot create .planning/ directory.
 | `.planning/research/SUMMARY.md` | Research synthesis | Step 6 (if research enabled) |
 | `.planning/REQUIREMENTS.md` | Scoped requirements | Step 7 |
 | `.planning/ROADMAP.md` | Phase roadmap | Step 8 |
-| `.planning/PROJECT.md` | Project overview | Step 9 |
-| `.planning/STATE.md` | Current state tracker | Step 9 |
-| `.planning/CONTEXT.md` | Decisions and constraints | Step 9 |
-| `.planning/HISTORY.md` | Project history log | Step 9 |
+| `.planning/PROJECT.md` | Project overview + context (locked decisions, constraints, deferred ideas) | Step 9 |
+| `.planning/STATE.md` | Current state tracker + history log | Step 9 |
 | `.planning/phases/NN-*/` | Phase directories | Step 9 |