status

name	status
description	Show current project status and suggest what to do next.
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.

Step 0 — Immediate Output

Before ANY tool calls, display this banner:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► PROJECT STATUS                             ║
╚══════════════════════════════════════════════════════════════╝

Then proceed to Step 1.

/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

Show the user where they are and what to do next. The status display should be a quick glance, not a wall of text. Surface problems and route to the right action.

---

Flow

Step 1: Read Project State

CRITICAL — STOP. You MUST run these CLI commands FIRST. Do NOT skip them. Do NOT read files manually instead.

First, run the init command to capture routing, drift, and metadata:

node plugins/pbr/scripts/pbr-tools.js init status

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

If blob.error is set, display the error banner and stop (no project found).

Then run the status render CLI for the full formatted dashboard:

pbr-tools status render

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.

If the CLI command fails (non-zero exit or invalid JSON), display:

╔══════════════════════════════════════════════════════════════╗
║  ERROR                                                       ║
╚══════════════════════════════════════════════════════════════╝

Failed to render status dashboard. Run `pbr-tools status render` manually to diagnose.

Stop execution — do NOT attempt manual file reads as fallback.

Step 1b: Read Context Budget (advisory — skip on any error)

Run:

pbr-tools 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.

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

• 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

Active Debug Sessions

• Use blob.counts.active_debug for the count of active debug sessions
• If count > 0: note active debug sessions

Pending Todos

• 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

• 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:

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:

Project: {name from PROJECT.md or config.json}
Phase: {current} of {total} -- {current phase name}
Progress: [{progress bar}] {percentage}%

Phase Status:
| Phase | Status | Plans | Progress |
|-------|--------|-------|----------|
| 1. {name} | {status indicator} {status text} | {completed}/{total} | {percentage}% |
| 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}
- {blocker 2}

{If no blockers:}
Blockers: None

{If paused work:}
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-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-phase {N}`.

{If active debug sessions:}
Debug: {count} active session(s). Run `/pbr:debug` to continue.

{If pending todos:}
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

Generate a 20-character progress bar:

[████████████████████] 100%    (all filled)
[████████████████░░░░] 80%     (16 filled, 4 empty)
[████████░░░░░░░░░░░░] 40%     (8 filled, 12 empty)
[░░░░░░░░░░░░░░░░░░░░] 0%      (all empty)

Use Unicode block characters:

• Filled: █ (full block, U+2588)
• Empty: ░ (light shade, U+2591)

Status Indicators

Use the standardized symbol set from references/ui-brand.md:

Status	Indicator
Complete/Verified	✓
In Progress	◆
Not started	○
Needs fixes / Warning	⚠
Failed / Blocked	✗
Auto-approved	⚡

Step 5: Smart Routing

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 (fallback):

1. Is there paused work (.continue-here.md)?
   YES → "Resume your work: `/pbr:resume-work`"

2. Is there a verification with 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:execute-phase {N}`"

4. Is the current phase built but not reviewed?
   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-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-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. 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:

╔══════════════════════════════════════════════════════════════╗
║  ▶ NEXT UP                                                   ║
╚══════════════════════════════════════════════════════════════╝

**{brief explanation}**

`{suggested command}`

{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): 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?" header: "Next Step" options: - label: "{primary action}" description: "{brief explanation}" - label: "{alternative 1}" description: "{brief explanation}" - label: "{alternative 2}" description: "{brief explanation}" - label: "Something else" description: "Enter a different command" multiSelect: false

Build options dynamically from the decision tree results. Always include "Something else" as the last option. Generate 1-3 real options based on the state analysis.

After user selects an option:

• If they selected a real action: display "Run: /pbr:{action} {args}" so they can execute it
• If they selected "Something else": ask what they'd like to do (freeform text)
• This skill remains read-only — display the command, do not execute it

---

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: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
• Always verify by scanning phase directories
• If STATE.md disagrees with the file system, note the discrepancy: "Note: STATE.md says Phase 2 is in progress, but all plans have summaries. Status may need updating."

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: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
• Show them as "Not started" with no plan counts

Multiple milestones

• If PROJECT.md shows multiple milestones, display the current one
• Show completed milestones as collapsed summary

Large project (many phases)

• If more than 8 phases, consider grouping:
  • Completed phases: collapsed summary
  • Current phase: full detail
  • Upcoming phases: brief list

---

Performance

This skill should be fast. It's a status check, not an analysis.

DO:

• Read files quickly (frontmatter only where possible)
• Use Glob to find files efficiently
• Cache nothing (always read fresh state)

DO NOT:

• Read full SUMMARY.md contents (frontmatter is enough)
• Read plan file contents (just check existence)
• Run Bash commands except for Step 1b (pbr-tools context-triage, always run but skip on error)
• Modify any files
• Spawn any Task agents

---

Anti-Patterns

1. DO NOT modify any files — this is read-only
2. DO NOT run Bash commands — use Read and Glob only
3. DO NOT show overwhelming detail — keep it scannable
4. DO NOT hide problems — surface blockers, gaps, and warnings prominently
5. DO NOT suggest multiple actions without prioritizing — the primary suggestion should be clear
6. DO NOT re-read full file contents when frontmatter is sufficient
7. DO NOT show completed phases in full detail unless specifically relevant
8. DO NOT execute the suggested action — present it for the user to run manually. Use /pbr:continue for auto-execution.