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:

```bash
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:

```bash
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:
```bash
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:

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

```
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.