@sienklogic/plan-build-run 2.53.0 → 2.54.0

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

@@ -57,6 +57,7 @@ Parse the phase number and optional flags:
 | `3 --gaps` | Create gap-closure plans for phase 3 (from VERIFICATION.md) |
 | `3 --teams` | Plan phase 3 using specialist agent teams |
 | (no number) | Use current phase from STATE.md |
+| `3 --preview` | Preview what planning would produce for phase 3 without spawning agents |
 
 ### Subcommands
 
@@ -125,6 +126,35 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut (`state lo
 5. If no phase number given, read current phase from `.planning/STATE.md`
 6. **CONTEXT.md existence check**: If the phase is non-trivial (has 2+ requirements or success criteria), check whether a CONTEXT.md exists at EITHER `.planning/CONTEXT.md` (project-level) OR `.planning/phases/{NN}-{slug}/CONTEXT.md` (phase-level). If NEITHER exists, warn: "Phase {N} has no CONTEXT.md. Consider running `/pbr:discuss {N}` first to capture your preferences. Continue anyway?" If user says no, stop. If yes, continue. If at least one exists, proceed without warning.
 
+#### --preview mode
+
+If `--preview` is present in `$ARGUMENTS`:
+
+1. Detect the `--preview` flag and extract the phase number.
+2. Render the following dry-run banner:
+
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  DRY RUN — /pbr:plan {N} --preview                           ║
+   ║  No researchers or planners will be spawned                  ║
+   ╚══════════════════════════════════════════════════════════════╝
+   ```
+
+3. Show the 5 steps that would occur:
+
+   1. Parse ROADMAP.md for phase {N} goal, dependencies, and requirements
+   2. Spawn researcher agents to investigate codebase and gather context
+   3. Spawn planner agent to write PLAN files based on research
+   4. Run plan-checker to validate structure and completeness
+   5. Present plans for your approval before building
+
+4. Show estimated agent spawns: ~2-4 agents (1-2 researchers + 1 planner + 1 plan-checker)
+5. Show output location: `.planning/phases/{NN}-{slug}/PLAN-NN.md`
+
+6. **STOP** — do not proceed to Step 2.
+
+---
+
 **If phase already has plans:**
 - Use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
   question: "Phase {N} already has plans. Re-plan from scratch?"
@@ -253,21 +283,25 @@ Output format: Return both sections as markdown. End with ## BRIEFING COMPLETE."
 ```
 
 After the Task() completes:
-- If `## Seeds` section contains matches: present them to the user via AskUserQuestion (pattern: yes-no-pick from `skills/shared/gate-prompts.md`):
-  question: "Include these {N} seeds in planning?"
-  header: "Seeds?"
-  options:
-    - label: "Yes, all"     description: "Include all {N} matching seeds"
-    - label: "Let me pick"  description: "Choose which seeds to include"
-    - label: "No"           description: "Proceed without seeds"
-- If "Yes, all": include seed content in planner context
-- If "Let me pick": present individual seeds for selection
-- If "No": proceed without seeds
-
-- If `## Deferred Ideas` section has items: present via AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
-  question: "Include these deferred ideas in planning context?"
-- If "Yes": append to planner context under `Deferred ideas to consider:`
-- If "No": proceed without changes
+- If `## Seeds` section contains matches:
+  - If `gates.confirm_seeds` is `true` in config: present them to the user via AskUserQuestion (pattern: yes-no-pick from `skills/shared/gate-prompts.md`):
+      question: "Include these {N} seeds in planning?"
+      header: "Seeds?"
+      options:
+        - label: "Yes, all"     description: "Include all {N} matching seeds"
+        - label: "Let me pick"  description: "Choose which seeds to include"
+        - label: "No"           description: "Proceed without seeds"
+    - If "Yes, all": include seed content in planner context
+    - If "Let me pick": present individual seeds for selection
+    - If "No": proceed without seeds
+  - If `gates.confirm_seeds` is `false` (default): automatically include all matching seeds in planner context without prompting. Log: "Including {N} seeds automatically (gates.confirm_seeds=false)."
+
+- If `## Deferred Ideas` section has items:
+  - If `gates.confirm_deferred` is `true` in config: present via AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
+      question: "Include these deferred ideas in planning context?"
+    - If "Yes": append to planner context under `Deferred ideas to consider:`
+    - If "No": proceed without changes
+  - If `gates.confirm_deferred` is `false` (default): automatically append deferred ideas to planner context without prompting. Log: "Including deferred ideas automatically (gates.confirm_deferred=false)."
 
 - If both sections are empty: proceed silently to Step 5 (no AskUserQuestion needed)
 
@@ -556,10 +590,26 @@ Read `skills/plan/templates/gap-closure-prompt.md.tmpl` and use it as the prompt
 ## Error Handling
 
 ### Phase not found
-If the specified phase doesn't exist in ROADMAP.md, display a branded error box — see `skills/shared/error-reporting.md`, pattern: Phase not found.
+If the specified phase doesn't exist in ROADMAP.md, use conversational recovery:
+
+1. Run: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js suggest-alternatives phase-not-found {slug}`
+2. Parse the JSON response to get `available` phases and `suggestions` (closest matches).
+3. Display: "Phase '{slug}' not found. Did you mean one of these?"
+   - List `suggestions` (if any) as numbered options.
+   - Offer "Show all phases" to list `available`.
+4. Use AskUserQuestion (pattern: yes-no-pick from `skills/shared/gate-prompts.md`) to let the user pick a phase or abort.
+   - If user picks a valid phase slug: re-run with that slug.
+   - If user chooses to abort: stop cleanly with a friendly message.
 
 ### Missing prerequisites
-If REQUIREMENTS.md or ROADMAP.md don't exist, display a branded error box — see `skills/shared/error-reporting.md`, pattern: Missing prerequisites.
+If REQUIREMENTS.md or ROADMAP.md don't exist, use conversational recovery:
+
+1. Run: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js suggest-alternatives missing-prereq {phase}`
+2. Parse the JSON response to get `existing_summaries`, `missing_summaries`, and `suggested_action`.
+3. Display what is already complete and what is missing.
+4. Use AskUserQuestion to offer: "Run /pbr:build {prerequisite-phase} first, or continue anyway?"
+   - If user chooses to continue: proceed with planning (note missing prereqs in plan frontmatter).
+   - If user chooses to build first: stop and display the suggested build command.
 
 ### Research agent fails
 If the researcher Task() fails, display:

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

@@ -77,7 +77,18 @@ Execute these steps in order.
 5. If no phase number given, read current phase from `.planning/STATE.md`
 6. If `.planning/.auto-verify` signal file exists, read it and note the auto-verification was already queued. Delete the signal file after reading (one-shot, same pattern as auto-continue.js).
 
-**Validation errors — use branded error boxes:**
+**Validation errors:**
+
+If phase directory not found, use conversational recovery:
+
+1. Run: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js suggest-alternatives phase-not-found {slug}`
+2. Parse the JSON response to get `available` phases and `suggestions` (closest matches).
+3. Display: "Phase '{slug}' not found. Did you mean one of these?"
+   - List `suggestions` (if any) as numbered options.
+   - Offer "Show all phases" to list `available`.
+4. Use AskUserQuestion (pattern: yes-no-pick from `skills/shared/gate-prompts.md`) to let the user pick a phase or abort.
+   - If user picks a valid phase slug: re-run with that slug.
+   - If user chooses to abort: stop cleanly with a friendly message.
 
 If no SUMMARY.md files:
 ```

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

@@ -1,10 +1,10 @@
 ---
 name: setup
-description: "Onboarding wizard. Initialize project, select models, verify setup."
+description: "Reconfigure an existing Plan-Build-Run project (models, features, CLAUDE.md)."
 allowed-tools: Read, Write, Bash, Glob, AskUserQuestion
 ---
 
-**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.**
+**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 tokens. Begin executing Step 1 immediately.**
 
 ## Step 0 — Immediate Output
 
@@ -12,198 +12,54 @@ allowed-tools: Read, Write, Bash, Glob, AskUserQuestion
 
 ```
 ╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► SETUP                                      ║
+║  PLAN-BUILD-RUN ► RECONFIGURE                                ║
 ╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
 
-# /pbr:setup — Plan-Build-Run Setup Wizard
+# /pbr:setup — Plan-Build-Run Reconfigure
 
-You are running the **setup** skill. This is an interactive onboarding wizard that guides users through Plan-Build-Run project setup. Use AskUserQuestion at each step for clear choices.
+You are running the **setup** skill in **reconfigure mode**. This wizard lets existing Plan-Build-Run projects change model profiles, workflow features, and CLAUDE.md integration. It does NOT re-initialize or overwrite project state.
 
 ---
 
-## Step 1: Detect Project State — Idempotency Guard
+## Step 1: Detect Project State
 
-Check if `.planning/` directory exists in the current working directory.
+Check if `.planning/config.json` exists.
 
-**If `.planning/` exists**:
-- Check for existing core files: `STATE.md`, `ROADMAP.md`, `config.json`
-- If ANY of these exist, present a checkpoint:
-
-  Use AskUserQuestion:
-    question: "Existing project detected with {list of found files}. How should we proceed?"
-    header: "Setup"
-    options:
-      - label: "Resume"       description: "Keep existing .planning/ and review configuration (recommended)"
-      - label: "Reset"        description: "Archive current .planning/ to .planning.bak/ and start fresh"
-      - label: "Abort"        description: "Cancel setup — keep everything as-is"
-
-  - If "Resume": Tell the user: "Keeping existing project. Reviewing configuration." Skip to Step 3 (model selection)
-  - If "Reset": Run `mv .planning .planning.bak` (creating a backup), then proceed with fresh setup below
-  - If "Abort": Display "Setup cancelled. Run `/pbr:status` to see current project state." and stop
-
-- If `.planning/` exists but has NONE of the core files (empty or only has subdirs):
-  - Tell the user: "Found empty .planning/ directory. Proceeding with initialization."
-  - Continue to fresh setup below
-
-**If `.planning/` does NOT exist**:
-- Ask the user:
-
-```
-AskUserQuestion:
-  question: "No Plan-Build-Run project found. Would you like to initialize one?"
-  header: "Initialize"
-  options:
-    - label: "Yes, initialize here"
-      description: "Creates .planning/ directory with default config, STATE.md, and ROADMAP.md"
-    - label: "No, just exploring"
-      description: "Exit the wizard — you can run /pbr:begin later for full project setup"
-```
-
-If "No", display: "Run `/pbr:begin` when you're ready to start a project. It includes deep requirements gathering and roadmap creation." Then stop.
-
-If "Yes", create the minimal `.planning/` structure:
-
-**CRITICAL: Create .planning/ directory structure NOW. Do NOT skip this step.**
-
-```bash
-mkdir -p .planning/phases .planning/todos/pending .planning/todos/done .planning/logs .planning/research
-```
-
-**CRITICAL: Write .planning/config.json NOW. Do NOT skip this step.**
-
-Before writing config.json, check for user-level defaults:
-
-```bash
-node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" config load-defaults
-```
-
-If user defaults exist (the output has keys like `mode`, `features`, etc.), inform the user: "Found your saved preferences from ~/.claude/pbr-defaults.json. These will be merged into your project config (project-specific settings take precedence)." Then deep-merge user defaults into the config below before writing.
-
-Create `.planning/config.json` with defaults (merged with user defaults if they exist):
-```json
-{
-  "version": 2,
-  "context_strategy": "aggressive",
-  "mode": "interactive",
-  "depth": "standard",
-  "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": "sonnet"
-  },
-  "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
-  }
-}
-```
-
-**CRITICAL: Write .planning/STATE.md NOW. Do NOT skip this step.**
-
-Create `.planning/STATE.md`:
-```markdown
----
-version: 2
-current_phase: 0
-total_phases: 0
-status: "initialized"
-progress_percent: 0
-last_activity: "{today's date}"
-last_command: "/pbr:setup"
-blockers: []
----
-# Project State
-
-## Current Position
-Phase: 0 of 0
-Status: initialized
-
-Plan-Build-Run project initialized via /pbr:setup. Run /pbr:begin to start requirements gathering and roadmap creation.
+**If `.planning/config.json` does NOT exist:**
+Display:
 ```
+No Plan-Build-Run project found in this directory.
 
----
-
-## Step 2: Project Type (new projects only)
+/pbr:setup is for reconfiguring existing projects.
+To start a new project, run: /pbr:begin
 
+/pbr:begin includes everything /pbr:setup used to do, plus deep requirements gathering and roadmap creation.
 ```
-AskUserQuestion:
-  question: "What kind of project is this?"
-  header: "Project type"
-  options:
-    - label: "Greenfield"
-      description: "Starting from scratch — full planning cycle recommended"
-    - label: "Existing codebase"
-      description: "Adding Plan-Build-Run to an existing project — run /pbr:scan first"
-    - label: "Prototype/experiment"
-      description: "Quick iteration — lighter workflow with fewer gates"
-```
-
-Based on selection:
-- **Greenfield**: Keep defaults (full gates, structured planning)
-- **Existing codebase**: Suggest running `/pbr:scan` after setup to map the codebase
-- **Prototype**: Set `depth: "quick"`, disable `gates.verification`, disable `gates.review`, set `features.research_phase: false`
+Stop. Do not proceed further.
 
-Update config.json with any changes.
+**If `.planning/config.json` exists:**
+- Read `.planning/config.json`
+- Display the current settings summary:
+  ```
+  Current configuration:
+  - Model profile: {derived from models block — balanced/quality/budget or custom}
+  - Depth: {depth}
+  - Mode: {mode}
+  - Auto-continue: {features.auto_continue}
+  - TDD mode: {features.tdd_mode}
+  - Git branching: {git.branching}
+  ```
+- Proceed to Step 2.
 
 ---
 
-## Step 3: Model Selection
+## Step 2: Model Selection
 
-```
-AskUserQuestion:
-  question: "Which model profile should Plan-Build-Run use for agents?"
+Use AskUserQuestion:
+  question: "Which model profile should agents use?"
   header: "Models"
   options:
     - label: "Balanced (Recommended)"
@@ -212,19 +68,20 @@ AskUserQuestion:
       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."
-```
+    - label: "Keep current"
+      description: "Leave model settings unchanged."
 
-Apply the selected profile to `config.json`:
+Apply the selected profile to the models block in config.json:
 - **Balanced**: executor=sonnet, researcher=sonnet, planner=sonnet, verifier=sonnet, synthesizer=haiku
 - **Quality**: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet
 - **Budget**: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku
+- **Keep current**: no change to models block
 
 ---
 
-## Step 4: Workflow Preferences
+## Step 3: Workflow Features
 
-```
-AskUserQuestion:
+Use AskUserQuestion:
   question: "Which workflow features do you want enabled?"
   header: "Features"
   multiSelect: true
@@ -237,9 +94,8 @@ AskUserQuestion:
       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:
+Apply selections (others unchanged):
 - **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`
@@ -247,15 +103,23 @@ Apply selections:
 
 ---
 
-## Step 4b: CLAUDE.md Integration
+## Step 4: 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.
+**If it exists**: Read it. If it does NOT already contain a "Plan-Build-Run" section, offer to append the integration block.
+**If it does NOT exist**: Offer to create `CLAUDE.md` with the integration block.
 
-Append/create this content:
+Use AskUserQuestion:
+  question: "Update CLAUDE.md with Plan-Build-Run integration notes?"
+  header: "CLAUDE.md"
+  options:
+    - label: "Yes"
+      description: "Add or update the Plan-Build-Run section in CLAUDE.md"
+    - label: "No"
+      description: "Skip — leave CLAUDE.md as-is"
 
+If "Yes", append/create:
 ```markdown
 ## Plan-Build-Run
 
@@ -270,49 +134,37 @@ This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run)
 
 ---
 
-## Step 5: Verification
+## Step 5: Write Updated Config
 
-**CRITICAL: Run validation checks NOW to confirm setup succeeded. Do NOT skip this step.**
+**CRITICAL: Write `.planning/config.json` NOW with all changes from Steps 2-3. Do NOT skip this step.**
 
-Run a quick health check:
+Write the updated config.json to disk with all applied changes.
 
-1. Verify `.planning/config.json` is valid JSON
-2. Verify `.planning/STATE.md` exists and is parseable
-3. Verify hook scripts are accessible: `node ${CLAUDE_PLUGIN_ROOT}/scripts/progress-tracker.js` from the project directory
-4. Check that `npm test` works (if package.json exists)
+---
 
-Display results:
+## Step 6: Verification
 
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► SETUP COMPLETE ✓                           ║
-╚══════════════════════════════════════════════════════════════╝
-
-Project: {cwd basename}
-Model profile: {balanced/quality/budget}
-Depth: {quick/standard/comprehensive}
-Features: {list of enabled non-default features}
+Run a quick check:
+1. Verify `.planning/config.json` is valid JSON (read it back)
+2. Display updated settings summary
 
+Display:
+```
 ╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
+║  PLAN-BUILD-RUN ► RECONFIGURE COMPLETE ✓                     ║
 ╚══════════════════════════════════════════════════════════════╝
 
-**Start your project** — define requirements and create a roadmap
-
-`/pbr:begin`
-
-<sub>`/clear` first → fresh context window</sub>
+Updated:
+- Model profile: {new profile}
+- Features changed: {list or "none"}
+- CLAUDE.md: {updated/skipped}
 
-**Also available:**
-- `/pbr:scan` — analyze existing codebase (if adding to existing project)
-- `/pbr:config` — fine-tune individual settings
-- `/pbr:help` — command reference
+Run /pbr:status to see current project state.
 ```
 
 ---
 
 ## Error Handling
 
-- If `.planning/` creation fails (permissions): Tell user to create it manually and retry
+- If config.json parse fails: Display the raw content and ask user to fix it manually, then retry
 - If config.json write fails: Display the JSON content and ask user to save it manually
-- If health check fails: Display specific failure and suggest `/pbr:health` for diagnostics

package/plugins/pbr/skills/shared/context-budget.md

@@ -48,3 +48,30 @@ Additionally for this skill:
 - {Skill-specific rule 1}
 - {Skill-specific rule 2}
 ```
+
+## Agent Elapsed Time Estimates
+
+When displaying agent spawn lines (e.g., "Spawning researcher..."), append a parenthetical estimate:
+
+| Agent Type | Display Text | Estimate |
+|------------|-------------|----------|
+| researcher | Spawning researcher... | (est. 1-3 min) |
+| planner | Spawning planner... | (est. 2-5 min) |
+| executor | Spawning executor... | (est. 3-8 min) |
+| verifier | Spawning verifier... | (est. 1-2 min) |
+| codebase-mapper | Spawning codebase-mapper... | (est. 1-2 min) |
+| plan-checker | Spawning plan-checker... | (est. 1-2 min) |
+| integration-checker | Spawning integration-checker... | (est. 2-4 min) |
+| debugger | Spawning debugger... | (est. 2-5 min) |
+| general | Spawning agent... | (est. 1-4 min) |
+| audit | Spawning audit... | (est. 2-4 min) |
+
+**Usage**: In any skill that spawns Task() agents, prefix spawn displays with the agent name and append the estimate from this table. Example:
+
+```
+Spawning researcher... (est. 1-3 min)
+Spawning planner... (est. 2-5 min)
+[Wave 1: 3 plans in parallel] Spawning executors... (est. 3-8 min each)
+```
+
+Skills that spawn agents: build, plan, review, debug, scan, milestone, quick.

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

@@ -98,6 +98,20 @@ node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js llm metrics --session <content-o
 
 If `local_llm.enabled` is `false` or commands fail, skip this step silently.
 
+### Step 1c: Read Context Budget (advisory — skip on any error)
+
+Run:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js context-triage
+```
+
+Parse the JSON response. Capture:
+- `tier` — one of PEAK / GOOD / DEGRADING / POOR / CRITICAL
+- `percentage` — numeric 0-100 (or null if unavailable)
+- `recommendation` — PROCEED / CHECKPOINT / COMPACT
+
+Store these for use in Step 4 display and Step 5 routing.
+
 ### Step 2: Scan Phase Directories
 
 For each phase listed in ROADMAP.md:
@@ -171,6 +185,18 @@ If any discrepancy found, add: `Run /pbr:resume to auto-reconcile STATE.md.`
 - Check `.planning/todos/pending/` for pending todo files
 - Count and summarize if any exist
 
+#### Critical Path
+Identify the single next-blocking item — the one phase or plan whose completion unblocks the most downstream work.
+
+Logic:
+1. From ROADMAP.md dependency graph, find all phases that are NOT yet verified.
+2. For each unverified phase, count how many other unverified phases list it in `depends_on` (direct + transitive).
+3. The phase with the highest downstream dependent count is the critical-path phase.
+4. If all unverified phases are independent (no dependencies between them), the critical path is the current phase from STATE.md.
+5. Within the critical-path phase, the critical-path plan is the lowest-numbered plan without a SUMMARY.md.
+
+Store: `criticalPhase` (number + name), `criticalPlan` (plan ID or null if phase not yet planned), `criticalCount` (number of downstream phases blocked).
+
 #### Quick Notes
 - Check `.planning/notes/` directory for note files (individual `.md` files)
 - Count active notes (files where frontmatter does NOT contain `promoted: true`)
@@ -196,6 +222,19 @@ Phase Status:
 | 2. {name} | {status indicator} {status text} | {completed}/{total} | {percentage}% |
 | ...
 
+{If context tier is DEGRADING, POOR, or CRITICAL:}
+⚠ Context: {percentage}% used ({tier}) — {recommendation_text}
+  Run `/compact` to reclaim context before spawning more agents.
+
+Where `{recommendation_text}` maps:
+- DEGRADING → "quality may degrade on complex agents"
+- POOR → "context window is filling up"
+- CRITICAL → "STOP — compact before continuing"
+
+{If criticalPhase is identified AND criticalCount >= 1 AND there are 2+ unverified phases with dependencies:}
+Critical Path: Phase {N} — {phase name}{, Plan {criticalPlan} is next} [BLOCKING {criticalCount} downstream phase(s)]
+{Else: omit — not meaningful when only one phase remains or no inter-phase dependencies exist}
+
 {If blockers exist:}
 Blockers:
 - {blocker 1}
@@ -313,7 +352,10 @@ Based on the project state, suggest the single most logical next action:
 
 `{suggested command}`
 
-<sub>`/clear` first → fresh context window</sub>
+{If context percentage > 40% OR tier is DEGRADING/POOR/CRITICAL:}
+<sub>`/clear` first → fresh context window ({percentage}% used)</sub>
+{Else: omit the /clear hint entirely}
+{If `percentage` is null (no context data): omit the hint}
 
 
 ```
@@ -390,7 +432,7 @@ This skill should be fast. It's a status check, not an analysis.
 
 - Read full SUMMARY.md contents (frontmatter is enough)
 - Read plan file contents (just check existence)
-- Run Bash commands except for Step 1b (2-3 `pbr-tools` calls only when `local_llm.enabled: true`, skipped entirely otherwise)
+- Run Bash commands except for Step 1b (`pbr-tools llm` calls only when `local_llm.enabled: true`) and Step 1c (`pbr-tools context-triage`, always run but skip on error)
 - Modify any files
 - Spawn any Task agents