@sienklogic/plan-build-run 2.21.0 → 2.21.2

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

@@ -1,7 +1,8 @@
 ---
 name: status
 description: "Show current project status and suggest what to do next."
-allowed-tools: Read, Glob, Grep, AskUserQuestion
+allowed-tools: Read, Glob, Grep, Bash, AskUserQuestion
+argument-hint: "[--json]"
 ---
 
 **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.**
@@ -18,12 +19,17 @@ allowed-tools: Read, Glob, Grep, AskUserQuestion
 
 Then proceed to Step 1.
 
-# /pbr:status — Project Status Dashboard
+# /pbr:progress — Project Status Dashboard
 
 You are running the **status** skill. Your job is to read the project state and present a clear, actionable status dashboard. You suggest the most logical next action based on where the project is.
 
 This skill runs **inline** and is **read-only** — it never modifies any files.
 
+## References
+
+- `references/questioning.md` — Questioning philosophy (for routing intelligence)
+- `references/ui-brand.md` — Status symbols, banners, progress display format
+
 ---
 
 ## Core Principle
@@ -36,125 +42,122 @@ This skill runs **inline** and is **read-only** — it never modifies any files.
 
 ### Step 1: Read Project State
 
-**Tooling shortcut**: Instead of parsing multiple files manually, you can run:
-```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load
-```
-and
-```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state check-progress
-```
-These return structured JSON with config, state, roadmap, and filesystem-verified progress. Falls back gracefully if the script is missing — parse files manually in that case.
+**CRITICAL — STOP. You MUST run these CLI commands FIRST. Do NOT skip them. Do NOT read files manually instead.**
 
-Read the following files (skip any that don't exist):
+First, run the init command to capture routing, drift, and metadata:
 
-1. **`.planning/config.json`** — Project settings
-   - If this doesn't exist, display:
-     ```
-     ╔══════════════════════════════════════════════════════════════╗
-     ║  ERROR                                                       ║
-     ╚══════════════════════════════════════════════════════════════╝
-
-     No Plan-Build-Run project found.
-
-     **To fix:** Run `/pbr:begin` to start a new project, or `/pbr:scan` to analyze an existing codebase.
-     ```
-   - Stop here if no project found.
-
-2. **`.planning/STATE.md`** — Current position, progress, blockers
-   - Extract: current phase, current plan, overall progress, blockers, session info
+```bash
+node plugins/pbr/scripts/pbr-tools.js init status
+```
 
-3. **`.planning/ROADMAP.md`** — Phase overview
-   - Extract: all phases with names, descriptions, status indicators
+Store the JSON result as `blob`. This provides:
+- `blob.routing` — suggestNext output with `blob.routing.command` and `blob.routing.reason` for Step 5 smart routing
+- `blob.drift` — STATE.md discrepancy warnings (`blob.drift.drift_detected`, `blob.drift.stale_fields`)
+- `blob.counts.pending_todos`, `blob.counts.notes`, `blob.counts.active_debug` — directory scan counts
+- `blob.has_paused_work` — whether .continue-here file exists
+- `blob.progress` — progress bar data (percentage, completed_plans, total_plans)
+- `blob.state` — STATE.md frontmatter fields
+- `blob.config.mode`, `blob.config.features`, `blob.config.workflow` — config checks
 
-4. **`.planning/PROJECT.md`** — Project metadata (if exists)
-   - Extract: project name, milestone info
+If `blob.error` is set, display the error banner and stop (no project found).
 
-5. **`.planning/REQUIREMENTS.md`** — Requirements (if exists)
-   - Extract: requirement completion status if tracked
+Then run the status render CLI for the full formatted dashboard:
 
-### Step 2: Scan Phase Directories
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js status render
+```
 
-For each phase listed in ROADMAP.md:
+This returns a **complete, deterministic JSON object** with ALL project status: milestones, phases, progress bar, routing recommendations, todos, notes, quick tasks, paused work, documents, and warnings. Parse the JSON and proceed directly to Step 4 (Display) using the structured data. The init blob supplements this with routing and metadata that `status render` does not provide.
 
-1. Check if the phase directory exists in `.planning/phases/`
-2. If exists, scan for:
-   - `CONTEXT.md` — discussion happened
-   - `*-PLAN.md` or `PLAN.md` files — plans exist
-   - `*-SUMMARY.md` or `SUMMARY.md` files — plans were executed
-   - `VERIFICATION.md` — phase was reviewed
-   - `.continue-here.md` — paused work
+**If the CLI command fails** (non-zero exit or invalid JSON), display:
 
-3. Calculate phase status:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
 
-| Condition | Status |
-|-----------|--------|
-| No directory | Not started |
-| Directory exists, no plans | Discussed only |
-| Plans exist, no summaries | Planned (ready to build) |
-| Some summaries, not all | Building (in progress) |
-| All summaries exist | Built (ready to review) |
-| VERIFICATION.md exists, status=passed | Verified (complete) |
-| VERIFICATION.md exists, status=gaps_found | Needs fixes |
+Failed to render status dashboard. Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js status render` manually to diagnose.
+```
 
-4. Calculate progress percentage:
-   - Count total plans across all phases
-   - Count plans with SUMMARY.md (status=completed)
-   - Progress = completed / total * 100
+Stop execution — do NOT attempt manual file reads as fallback.
 
-### Step 2b: Check STATE.md Size and Consistency
+### Step 1b: Read Context Budget (advisory — skip on any error)
 
-Count lines in `.planning/STATE.md`. If over 150 lines, add a warning to the dashboard:
-```
-Warning: STATE.md is {N} lines (limit: 150). Run any build/review command to auto-compact it.
+Run:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js context-triage
 ```
 
-**Discrepancy check:** Compare STATE.md phase/plan/status claims against the filesystem:
-- Does the phase directory exist? If not: `Warning: STATE.md references Phase {N} but no directory exists.`
-- Does the plan count match? If not: `Warning: STATE.md says {X} plans but filesystem has {Y}.`
-- Does the status match? If STATE.md says "verified" but no `VERIFICATION.md` exists: `Warning: STATE.md says "verified" but no VERIFICATION.md found.`
+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.
 
-If any discrepancy found, add: `Run /pbr:resume to auto-reconcile STATE.md.`
+**Steps 2-2b:** The `status render` CLI output includes phase statuses, plan counts, progress percentage, and STATE.md discrepancy warnings. Parse the JSON directly — do NOT re-scan the filesystem.
 
 ### Step 3: Check for Special Conditions
 
+Use blob fields from the init call where available to avoid redundant filesystem scans:
+
 #### Paused Work
-- Search for `.continue-here.md` files in `.planning/phases/`
-- If found: note the phase and brief description of where work stopped
+- Check `blob.has_paused_work` — if true, note that paused work exists
+- If more detail is needed, search for `.continue-here.md` files in `.planning/phases/`
 
 #### Verification Gaps
 - Search for `VERIFICATION.md` files with `gaps_found` status
 - If found: note which phases have gaps
 
-#### Cross-Phase Re-Planning Check
-- For each planned phase, check if its dependency phases have been built yet
-- Logic:
-  1. Read ROADMAP.md to find phase dependencies (phases that come before)
-  2. If Phase N has plans but Phase N-1 doesn't have summaries (wasn't built yet):
-     - This means Phase N was planned without knowledge of what Phase N-1 actually produced
-     - Flag for re-planning
-- **Dependency fingerprint check**: For each planned phase with `dependency_fingerprints` in plan frontmatter:
-  1. Compare the fingerprints against current dependency SUMMARY.md files
-  2. If any fingerprint is stale (dependency was re-built after the plan was created):
-     - Flag: "WARN: Phase {N} plans may be stale — dependency phase {M} was re-built since planning. Consider re-planning with `/pbr:plan {N}`."
-
 #### Active Debug Sessions
-- Check `.planning/debug/` for files with `status: active`
-- Note any active debug sessions
+- Use `blob.counts.active_debug` for the count of active debug sessions
+- If count > 0: note active debug sessions
 
 #### Pending Todos
-- Check `.planning/todos/pending/` for pending todo files
-- Count and summarize if any exist
+- Use `blob.counts.pending_todos` for the count of pending todo files
+- If count > 0: summarize
+
+#### 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`)
+- Use `blob.counts.notes` for the total count of note files in `.planning/notes/`
+- For promoted status filtering, read individual note frontmatter only if needed
 - Also check `~/.claude/notes/` for global notes
 
 #### Quick Tasks
 - Check `.planning/quick/` for recent quick tasks
 - Note any failed or partial quick tasks
 
+#### Verification Debt Scan
+Scan ALL completed phases (not just current) for outstanding verification items:
+
+```bash
+for dir in .planning/phases/*/; do
+  VFILE=$(ls "$dir"VERIFICATION*.md 2>/dev/null | head -1)
+  if [ -n "$VFILE" ]; then
+    STATUS=$(grep -m1 "^status:" "$VFILE" | awk '{print $2}')
+    if [ "$STATUS" = "gaps_found" ] || [ "$STATUS" = "human_needed" ] || [ "$STATUS" = "partial" ]; then
+      echo "DEBT: $(basename "$dir") — $STATUS"
+    fi
+  fi
+done
+```
+
+If ANY phase has outstanding verification (gaps_found, human_needed, partial):
+- Display a `Verification Debt` section in the status dashboard
+- List each phase with outstanding items and their status
+- This is non-blocking — informational only, but surfaces items that might be forgotten
+
 ### Step 4: Display Status Dashboard
 
 Present the status in this format:
@@ -171,6 +174,34 @@ Phase Status:
 | 2. {name} | {status indicator} {status text} | {completed}/{total} | {percentage}% |
 | ...
 
+**Project documents:**
+| File | Status |
+|------|--------|
+| PROJECT.md | {exists / not found -- run /pbr:new-project} (includes ## Context section) |
+| REQUIREMENTS.md | {exists / not found -- run /pbr:new-project} |
+
+{If STATE.md frontmatter contains a `velocity` field (JSON object), display velocity metrics in a single compact line:}
+Velocity:  {velocity.plans_executed} plans | avg {velocity.avg_duration_minutes} min/plan | trend: {velocity.trend}
+Total:     {total_plans} plans across all phases
+{If no `velocity` field exists in STATE.md frontmatter, skip this block entirely — do not show "No metrics".}
+
+{If STATE.md frontmatter contains `session_last`, display session continuity:}
+Last session: {session_last}{if session_stopped_at:} — stopped at: {session_stopped_at}{/if}
+{If no `session_last` field exists, skip this block entirely.}
+
+{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}
@@ -180,22 +211,23 @@ Blockers:
 Blockers: None
 
 {If paused work:}
-Paused: Phase {N} has a checkpoint at plan {M}. Run `/pbr:resume` to continue.
+Paused: Phase {N} has a checkpoint at plan {M}. Run `/pbr:resume-work` to continue.
 
 {If verification gaps:}
-Gaps: Phase {N} verification found {count} gaps. Run `/pbr:plan {N} --gaps` to address.
+Gaps: Phase {N} verification found {count} gaps. Run `/pbr:plan-phase {N} --gaps` to address.
 
 {If cross-phase re-planning needed:}
-Warning: Phase {N} was planned before Phase {M} was built. Consider re-planning with `/pbr:plan {N}`.
+Warning: Phase {N} was planned before Phase {M} was built. Consider re-planning with `/pbr:plan-phase {N}`.
 
 {If active debug sessions:}
 Debug: {count} active session(s). Run `/pbr:debug` to continue.
 
 {If pending todos:}
-Todos: {count} pending. Run `/pbr:todo list` to see them.
+Todos: {count} pending. Run `/pbr:check-todos` to see them.
 
 {If notes exist:}
 Notes: {count} quick capture(s). `/pbr:note list` to review.
+
 ```
 
 ### Progress Bar
@@ -215,54 +247,80 @@ Use Unicode block characters:
 
 ### Status Indicators
 
-Use indicators from `references/ui-formatting.md`:
+Use the standardized symbol set from `references/ui-brand.md`:
 
 | Status | Indicator |
 |--------|-----------|
-| Complete/Verified | checkmark |
-| In Progress | half-filled circle |
-| Not started | empty circle |
-| Needs fixes | warning triangle |
-| Blocked | blocked symbol |
+| Complete/Verified | `✓` |
+| In Progress | `◆` |
+| Not started | `○` |
+| Needs fixes / Warning | `⚠` |
+| Failed / Blocked | `✗` |
+| Auto-approved | `⚡` |
 
 ### Step 5: Smart Routing
 
-Based on the project state, suggest the single most logical next action:
+Use `blob.routing.command` and `blob.routing.reason` from the init blob to determine the primary next action. The routing field contains the suggestNext output which implements the full decision tree below. Fall back to the manual decision tree only if `blob.routing` is unavailable.
 
-**Decision tree:**
+**Decision tree (fallback):**
 
 ```
 1. Is there paused work (.continue-here.md)?
-   YES → "Resume your work: `/pbr:resume`"
+   YES → "Resume your work: `/pbr:resume-work`"
 
 2. Is there a verification with gaps?
-   YES → "Fix verification gaps: `/pbr:plan {N} --gaps`"
+   YES → "Fix verification gaps: `/pbr:plan-phase {N} --gaps`"
 
 3. Is the current phase planned but not built?
-   YES → "Build the current phase: `/pbr:build {N}`"
+   YES → "Build the current phase: `/pbr:execute-phase {N}`"
 
 4. Is the current phase built but not reviewed?
-   YES → "Review what was built: `/pbr:review {N}`"
+   YES → Read `workflow.validate_phase` from config.json (default: `true`).
+     IF true  → "Validate coverage gaps: `/pbr:validate-phase {N}`"
+     IF false → "Review what was built: `/pbr:verify-work {N}`"
 
 5. Is the current phase verified (complete)?
    YES → Is there a next phase?
      YES → Was next phase already planned?
        YES → Does it need re-planning? (dependency phase changed)
-         YES → "Re-plan with updated context: `/pbr:plan {N+1}`"
-         NO → "Build the next phase: `/pbr:build {N+1}`"
-       NO → "Plan the next phase: `/pbr:plan {N+1}`"
-     NO → Check for existing `*-MILESTONE-AUDIT.md` in `.planning/`:\n       IF audit passed → "All phases complete and audited! `/pbr:milestone complete` to archive and tag."\n       IF audit has gaps → "Audit found gaps. `/pbr:milestone gaps` to address them."\n       IF no audit → "All phases complete! `/pbr:milestone audit` to verify cross-phase integration (recommended), then `/pbr:milestone complete`."
+         YES → "Re-plan with updated context: `/pbr:plan-phase {N+1}`"
+         NO → "Build the next phase: `/pbr:execute-phase {N+1}`"
+       NO → "Plan the next phase: `/pbr:plan-phase {N+1}`"
+     NO → Check for existing `*-MILESTONE-AUDIT.md` in `.planning/`:\n       IF audit passed → "All phases complete and audited! `/pbr:complete-milestone` to archive and tag."\n       IF audit has gaps → "Audit found gaps. `/pbr:plan-milestone-gaps` to address them."\n       IF no audit → "All phases complete! `/pbr:audit-milestone` to verify cross-phase integration (recommended), then `/pbr:complete-milestone`."
 
 6. Is the current phase not started?
    YES → Has it been discussed?
-     YES → "Plan this phase: `/pbr:plan {N}`"
-     NO → "Start with a discussion: `/pbr:discuss {N}` or jump to `/pbr:plan {N}`"
+     YES → "Plan this phase: `/pbr:plan-phase {N}`"
+     NO → "Start with a discussion: `/pbr:discuss-phase {N}` or jump to `/pbr:plan-phase {N}`"
 
 7. Active debug sessions?
    YES → "Continue debugging: `/pbr:debug`"
 
-8. Nothing active?
-   → "Start your project: `/pbr:begin`"
+8. Pending notes to review?
+   YES → "Review notes: `/pbr:note list`"
+
+9. Nothing active?
+   → "Start your project: `/pbr:new-project`"
+
+Autonomous mode suggestion (conditional):
+After the primary next-action is determined, check the number of pending phases:
+- Count all phases in ROADMAP.md whose status is `not_started`, `discussed`, `ready_to_plan`, or `planned`
+- If count >= 2 AND `config.mode` is NOT `autonomous`:
+  Display this advisory block below the primary next-action suggestion:
+
+  ─────────────────────────────────────────────
+  Multiple phases ready: {count} phases pending.
+  Run all phases hands-free with `/pbr:autonomous`
+  ─────────────────────────────────────────────
+
+- If count < 2 OR config.mode is already `autonomous`: skip — do not display.
+
+Other skills available for routing:
+- `/pbr:explore` — open-ended idea exploration
+- `/pbr:note` — zero-friction idea capture
+- `/pbr:debug` — systematic debugging
+- `/pbr:import` — import external plans
+- `/pbr:autonomous` — run multiple phases hands-free (when multiple phases are pending)
 ```
 
 **If only one reasonable next action exists**, present it with branded routing:
@@ -278,12 +336,17 @@ 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}
 
 
 ```
 
-**If multiple reasonable next actions exist** (2-3 alternatives), use the **action-routing** pattern (see `skills/shared/gate-prompts.md`):
+**If multiple reasonable next actions exist** (2-3 alternatives):
+**CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
+Use the **action-routing** pattern (see `skills/shared/gate-prompts.md`):
 
 Use AskUserQuestion:
   question: "What would you like to do next?"
@@ -304,12 +367,14 @@ Build options dynamically from the decision tree results. Always include "Someth
 
 ---
 
+Reference: `skills/shared/error-reporting.md` for branded error output patterns.
+
 ## Edge Cases
 
 ### No `.planning/` directory at all
 - Display: "No Plan-Build-Run project found."
-- Suggest: `/pbr:begin` to start a new project
-- Also mention: `/pbr:scan` if there's an existing codebase to analyze first
+- Suggest: `/pbr:new-project` to start a new project
+- Also mention: `/pbr:map-codebase` if there's an existing codebase to analyze first
 
 ### STATE.md exists but is outdated
 - STATE.md may not reflect the actual file system state
@@ -320,11 +385,11 @@ Build options dynamically from the decision tree results. Always include "Someth
 ### All phases complete
 - Celebrate briefly: "All phases complete!"
 - Check for existing audit report: look for `*-MILESTONE-AUDIT.md` in `.planning/`
-  - **If audit exists and passed:** Suggest `/pbr:milestone complete` to archive (audit already done)
-  - **If audit exists with gaps:** Suggest `/pbr:milestone gaps` to address issues
-  - **If no audit exists:** Suggest `/pbr:milestone audit` to verify cross-phase integration (recommended first)
-- Then: `/pbr:milestone complete` to archive the milestone and tag it
-- Or: `/pbr:milestone new` to start the next set of features
+  - **If audit exists and passed:** Suggest `/pbr:complete-milestone` to archive (audit already done)
+  - **If audit exists with gaps:** Suggest `/pbr:plan-milestone-gaps` to address issues
+  - **If no audit exists:** Suggest `/pbr:audit-milestone` to verify cross-phase integration (recommended first)
+- Then: `/pbr:complete-milestone` to archive the milestone and tag it
+- Or: `/pbr:new-milestone` to start the next set of features
 
 ### ROADMAP.md has phases but no phase directories
 - This is normal for future phases
@@ -352,9 +417,10 @@ This skill should be fast. It's a status check, not an analysis.
 - Cache nothing (always read fresh state)
 
 **DO NOT:**
+
 - Read full SUMMARY.md contents (frontmatter is enough)
 - Read plan file contents (just check existence)
-- Run any Bash commands
+- Run Bash commands except for Step 1b (`pbr-tools context-triage`, always run but skip on error)
 - Modify any files
 - Spawn any Task agents