@sienklogic/plan-build-run 2.1.0 → 2.1.1

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

@@ -1,7 +1,7 @@
 ---
 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
 ---
 
 **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.**
@@ -11,19 +11,24 @@ allowed-tools: Read, Glob, Grep, AskUserQuestion
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PROJECT STATUS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PROJECT STATUS                             ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 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
@@ -57,7 +62,7 @@ Read the following files (skip any that don't exist):
 
      No Plan-Build-Run project found.
 
-     **To fix:** Run `/pbr:begin` to start a new project, or `/pbr:scan` to analyze an existing codebase.
+     **To fix:** Run `/pbr:new-project` to start a new project, or `/pbr:map-codebase` to analyze an existing codebase.
      ```
    - Stop here if no project found.
 
@@ -73,6 +78,59 @@ Read the following files (skip any that don't exist):
 5. **`.planning/REQUIREMENTS.md`** — Requirements (if exists)
    - Extract: requirement completion status if tracked
 
+### Step 1b: Read Local LLM Stats (advisory — skip on any error)
+
+After loading config.json, check `local_llm.enabled`. If `true`:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js llm status
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js llm metrics
+```
+
+Parse both JSON responses. Capture:
+
+- `status.model` — model name
+- `metrics.total_calls` — lifetime total calls
+- `metrics.tokens_saved` — lifetime frontier tokens saved
+- `metrics.cost_saved_usd` — lifetime cost estimate
+- `metrics.avg_latency_ms` — lifetime average latency
+
+Also run session-scoped metrics if `.planning/.session-start` exists:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js llm metrics --session <content-of-.session-start>
+```
+
+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.
+
+6. **`.planning/STATE.md` ## History section** (if exists)
+   - Note: milestone completions, phase completion records (consolidated from legacy HISTORY.md)
+   - **Backwards compat:** If STATE.md has no ## History section but `.planning/HISTORY.md` exists, read from the legacy file
+
+7. **`.planning/PROJECT.md` ## Context section** (if exists)
+   - Note: locked decisions, user constraints, deferred ideas (consolidated from legacy CONTEXT.md)
+   - **Backwards compat:** If PROJECT.md has no ## Context section but `.planning/CONTEXT.md` exists, read from the legacy file
+
+### Step 1d: Check Project Documents
+
+Check existence of the core project-level documents and record their status for Step 4 display:
+- `.planning/PROJECT.md` — exists or not (includes ## Context section for locked decisions)
+- `.planning/REQUIREMENTS.md` — exists or not
+
 ### Step 2: Scan Phase Directories
 
 For each phase listed in ROADMAP.md:
@@ -114,7 +172,7 @@ Warning: STATE.md is {N} lines (limit: 150). Run any build/review command to aut
 - 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.`
 
-If any discrepancy found, add: `Run /pbr:resume to auto-reconcile STATE.md.`
+If any discrepancy found, add: `Run /pbr:resume-work to auto-reconcile STATE.md.`
 
 ### Step 3: Check for Special Conditions
 
@@ -136,7 +194,7 @@ If any discrepancy found, add: `Run /pbr:resume to auto-reconcile STATE.md.`
 - **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}`."
+     - Flag: "WARN: Phase {N} plans may be stale — dependency phase {M} was re-built since planning. Consider re-planning with `/pbr:plan-phase {N}`."
 
 #### Active Debug Sessions
 - Check `.planning/debug/` for files with `status: active`
@@ -146,10 +204,22 @@ 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.md` for active note entries
-- Count active notes (lines matching `^- \[` that don't contain `[promoted]`)
-- Also check `~/.claude/notes.md` for global notes
+- Check `.planning/notes/` directory for note files (individual `.md` files)
+- Count active notes (files where frontmatter does NOT contain `promoted: true`)
+- Also check `~/.claude/notes/` for global notes
 
 #### Quick Tasks
 - Check `.planning/quick/` for recent quick tasks
@@ -171,6 +241,25 @@ 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 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,24 +269,34 @@ 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.
+
+{If local_llm.enabled AND total_calls > 0:}
+Local LLM: enabled ({model}, avg {avg_ms}ms)
+This session: {session_calls} calls, ~{session_tokens} frontier tokens saved
+Lifetime: {total_calls} calls, ~{tokens_saved} tokens saved (~{cost_str} at $3/M)
+
+{If local_llm.enabled AND total_calls == 0:}
+Local LLM: enabled ({model}) — no calls yet this session
 ```
 
+The Local LLM block is **advisory only** — it never affects the routing decision or Next Up suggestion.
+
 ### Progress Bar
 
 Generate a 20-character progress bar:
@@ -215,15 +314,16 @@ 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
 
@@ -233,52 +333,66 @@ Based on the project state, suggest the single most logical next action:
 
 ```
 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 → "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 → "All phases complete! Your next steps:\n       -> /pbr:milestone audit — verify cross-phase integration (recommended)\n       -> /pbr:milestone complete — archive this milestone and create a git tag\n       -> /pbr:milestone new — start planning the next set of features"
+         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`"
+
+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
 ```
 
 **If only one reasonable next action exists**, present it with branded routing:
 
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{brief explanation}**
 
 `{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`):
@@ -306,8 +420,8 @@ Build options dynamically from the decision tree results. Always include "Someth
 
 ### 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
@@ -317,9 +431,12 @@ Build options dynamically from the decision tree results. Always include "Someth
 
 ### All phases complete
 - Celebrate briefly: "All phases complete!"
-- 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
+- Check for existing audit report: look for `*-MILESTONE-AUDIT.md` in `.planning/`
+  - **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
@@ -347,9 +464,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 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
 

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

@@ -0,0 +1,151 @@
+---
+name: statusline
+description: "Install or configure the PBR status line in Claude Code."
+allowed-tools: Read, Write, Bash, AskUserQuestion
+argument-hint: "[install | uninstall | preview]"
+---
+
+**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 ~3,000 tokens. Begin executing Step 0 immediately.**
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► STATUS LINE                                ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+# /pbr:statusline — Status Line Setup
+
+The PBR status line displays live project state (phase, plan, status, git branch, context usage) in the Claude Code terminal status bar.
+
+---
+
+## Subcommand Parsing
+
+Parse `$ARGUMENTS`:
+
+| Argument | Action |
+|----------|--------|
+| `install` or empty | Install/enable the status line |
+| `uninstall` or `remove` | Remove the status line configuration |
+| `preview` | Show what the status line looks like without installing |
+
+---
+
+## Subcommand: install (default)
+
+### Step 1: Locate the status-line script
+
+**CRITICAL: You must resolve the correct absolute path to `status-line.js`. Do NOT hardcode paths.**
+
+1. The script lives at `${CLAUDE_PLUGIN_ROOT}/scripts/status-line.js`
+2. Resolve `${CLAUDE_PLUGIN_ROOT}` to its absolute path using `pwd` or by checking the plugin root
+3. If running from a local plugin dir (`claude --plugin-dir .`), the path is the local repo's `plugins/pbr/scripts/status-line.js`
+4. If running from the installed plugin cache (`~/.claude/plugins/cache/`), use that path
+5. **Verify the script exists** with `ls` before proceeding. If it doesn't exist, show an error and stop.
+
+Store the resolved absolute path as `SCRIPT_PATH`.
+
+### Step 2: Read current settings
+
+Read `~/.claude/settings.json` (or `$HOME/.claude/settings.json`).
+
+- If the file doesn't exist: start with an empty object `{}`
+- If it exists: parse the JSON content
+- Check if `statusLine` key already exists:
+  - If yes and points to the same script: inform user "PBR status line is already installed." and stop (unless they want to reconfigure)
+  - If yes but points to a different command: warn user and ask if they want to replace it
+
+### Step 3: Configure settings.json
+
+Use AskUserQuestion:
+  question: "Install the PBR status line? This adds a `statusLine` entry to ~/.claude/settings.json."
+  header: "Install?"
+  options:
+    - label: "Install"  description: "Enable the PBR status line in Claude Code"
+    - label: "Preview first"  description: "Show a preview before installing"
+    - label: "Cancel"  description: "Don't install"
+  multiSelect: false
+
+If "Preview first": run the preview subcommand (show sample output), then ask again.
+If "Cancel": stop.
+If "Install":
+
+**CRITICAL: Use Read tool to read the file, then Write to update it. Do NOT use sed or other text manipulation on JSON files.**
+
+**CRITICAL: Back up settings.json NOW.** Write the original content to `~/.claude/settings.json.bak` before making any changes.
+
+1. Read `~/.claude/settings.json`
+2. Write the original content to `~/.claude/settings.json.bak`
+3. Parse the JSON
+4. Set `statusLine` to:
+   ```json
+   {
+     "type": "command",
+     "command": "node \"SCRIPT_PATH\""
+   }
+   ```
+   Where `SCRIPT_PATH` is the resolved absolute path from Step 1. Use forward slashes even on Windows.
+5. Write the updated JSON back (preserve all other settings, use 2-space indentation)
+
+### Step 4: Verify and confirm
+
+Display:
+```
+✓ PBR status line installed
+
+  Script: {SCRIPT_PATH}
+  Config: ~/.claude/settings.json
+
+The status line will appear on your next Claude Code session.
+Restart Claude Code or run `/clear` to activate it now.
+
+Customize per-project via .planning/config.json:
+  "status_line": {
+    "sections": ["phase", "plan", "status", "git", "context"],
+    "brand_text": "PBR"
+  }
+```
+
+---
+
+## Subcommand: uninstall
+
+1. Read `~/.claude/settings.json`
+2. If no `statusLine` key: inform user "No status line configured." and stop
+3. **CRITICAL: Back up settings.json NOW.** Write the original content to `~/.claude/settings.json.bak` before making any changes.
+4. Remove the `statusLine` key from the JSON
+5. Write the updated file
+5. Display: `✓ PBR status line removed. Restart Claude Code to take effect.`
+
+---
+
+## Subcommand: preview
+
+1. Locate and run the status-line script: `node {SCRIPT_PATH}`
+   - Pass sample stdin JSON: `{"context_window": {"used_percentage": 35}, "model": {"display_name": "Claude Opus 4.6"}, "cost": {"total_cost_usd": 0.42}}`
+2. Display the raw output to the user
+3. Also show a description of each section:
+   - **Phase**: Current phase number and name from STATE.md
+   - **Plan**: Plan progress (N of M)
+   - **Status**: Phase status keyword (planning, building, built, etc.)
+   - **Git**: Current branch + dirty indicator
+   - **Context**: Unicode bar showing context window usage (green/yellow/red)
+
+---
+
+## Edge Cases
+
+### No .planning/ directory
+The status line works even without `.planning/` — it will show only git and context sections. Installation doesn't require a PBR project.
+
+### Plugin installed from npm vs local
+The script path differs between `~/.claude/plugins/cache/plan-build-run/pbr/{version}/scripts/status-line.js` and a local `plugins/pbr/scripts/status-line.js`. The install command must resolve the actual path at install time.
+
+### Existing non-PBR status line
+If `statusLine` already exists with a different command, warn the user and confirm before replacing.