@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/pbr/skills/shared/state-update.md

@@ -1,24 +1,38 @@
 # STATE.md Update Pattern
 
-Standard pattern for updating `.planning/STATE.md`. Include this fragment in skills that modify project state.
+Standard pattern for updating `.planning/STATE.md`. CLI commands handle both YAML frontmatter and markdown body atomically. Skills and agents call `pbr-tools.js` commands instead of writing STATE.md directly.
+
+> Referenced by: build, plan, review, milestone, pause, resume, continue, begin, import, quick skills
 
 ---
 
-**CRITICAL: STATE.md has TWO representations — YAML frontmatter AND markdown body. You MUST update BOTH when changing state. The status line reads frontmatter; humans and hooks read the body. If you only update frontmatter, the body goes stale and the status line shows wrong data. Do NOT skip body updates under any circumstances.**
+## CLI Command Reference
+
+All commands use: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js <command>`
+
+| Action | CLI Command | What It Updates |
+|--------|------------|-----------------|
+| Update single field | `state update <field> <value>` | Frontmatter field + body line |
+| Update multiple fields | `state patch '{"field":"value",...}'` | Multiple frontmatter fields + body lines atomically |
+| Advance plan counter | `state advance-plan` | `plans_complete` + `progress_percent` in frontmatter and body |
+| Recalculate progress | `state update-progress` | `progress_percent` from disk (counts plans vs summaries) |
+| Complete a phase | `phase complete <N>` | STATE.md (advance phase, reset plans) + ROADMAP.md (checkbox, table) |
+| Record activity | `state record-activity "<desc>"` | `last_activity` with today's date + description |
+| Load full state | `state load` | Returns JSON -- does not write |
 
 ---
 
-## When to Update STATE.md
+## When to Use Each Command
 
-| Event | What to Update |
-|-------|---------------|
-| Phase status changes (planned, building, verified) | Frontmatter fields AND Current Position section |
-| Plan completes or fails | Frontmatter fields AND Plan counter, status, last activity |
-| Phase advances to next phase | Frontmatter fields AND Phase line, Status, Last activity, Progress bar |
-| New decision made | Accumulated Context > Decisions |
-| Blocker discovered or resolved | Accumulated Context > Blockers/Concerns |
-| Session starts or ends | Session Continuity section |
-| Milestone boundary | Milestone section |
+| Event | CLI Command |
+|-------|------------|
+| Plan completes | `state advance-plan` then `state update-progress` |
+| Phase status changes | `state update status <value>` |
+| Phase fully built and verified | `phase complete <N>` |
+| After any state mutation | `state record-activity "<what happened>"` |
+| Session starts (read only) | `state load` |
+| New decision made | Edit STATE.md "Accumulated Context > Decisions" section directly (CLI does not manage this section) |
+| Blocker discovered | Edit STATE.md "Accumulated Context > Blockers" section directly |
 
 ---
 
@@ -36,9 +50,6 @@ See: .planning/PROJECT.md (updated {date})
 Update `Current focus` when phase changes.
 
 ### 2. Current Position (lines 9-14)
-
-**CRITICAL: This section MUST match the frontmatter fields above it. When you update `current_phase` or `status` in frontmatter, you MUST also update the corresponding lines below. A hook will auto-fix drift, but do not rely on it.**
-
 ```
 ## Current Position
 Phase: {N} of {total} ({Phase name})
@@ -53,7 +64,7 @@ Progress: [{progress_bar}] {percent}%
 Phase 3 of 10 = 20% → [████░░░░░░░░░░░░░░░░] 20%
 Phase 7 of 10 = 70% → [██████████████░░░░░░] 70%
 ```
-Calculation: `filled = Math.round((completed_phases / total_phases) * 20)`
+Calculation: `filled = Math.round((completed_phases / phase_count) * 20)` where `phase_count` is derived from ROADMAP.md (available via `stateLoad` as `phase_count`)
 
 ### 3. Accumulated Context (lines 16-25)
 ```
@@ -89,81 +100,55 @@ Resume file: {path or "None"}
 
 ## Size Limit Enforcement
 
-**Hard limit: 150 lines.** After every STATE.md write, check the line count. If over 150 lines, compact:
+**Hard limit: 100 lines.** After every STATE.md write, check the line count. If over 100 lines, compact:
 
 1. **Collapse completed phase entries** to one-liners:
    ```
    Phase 1: verified 2026-02-08
    Phase 2: verified 2026-02-09
    ```
-2. **Remove decisions already captured in CONTEXT.md** — avoid duplication between STATE.md and phase CONTEXT.md files
-3. **Remove old session entries** — keep only the current session's continuity data
+2. **Remove decisions already captured in phase CONTEXT.md files** -- avoid duplication between STATE.md and phase-level CONTEXT.md
+3. **Remove old session entries** -- keep only the current session's continuity data
 4. **Keep these always:** current phase detail, active blockers, core value statement, milestone info
 
-If still over 150 lines after compaction, the Accumulated Context section has grown too large. Move non-critical decisions to the phase's CONTEXT.md file.
+If still over 100 lines after compaction, the Accumulated Context section has grown too large. Move non-critical decisions to the phase's CONTEXT.md file.
 
 ---
 
-## HISTORY.md Archival
+## History Archival
 
-When a milestone completes or a phase is verified, archive historical context to `.planning/HISTORY.md` to keep STATE.md lean:
+When a milestone completes or a phase is verified, archive historical context to the STATE.md ## History section to keep the Accumulated Context section lean:
 
 ### What to Archive
 
-| Trigger | What moves to HISTORY.md |
-|---------|-------------------------|
+| Trigger | What moves to STATE.md ## History |
+|---------|----------------------------------|
 | Phase verified | One-liner summary: "Phase {N} ({name}): verified {date}" |
 | Milestone complete | Full milestone record: name, phases covered, key decisions |
-| Accumulated Context > 20 lines | Decisions from completed phases (keep only current-phase decisions in STATE.md) |
+| Accumulated Context > 20 lines | Decisions from completed phases (keep only current-phase decisions in Accumulated Context) |
 
 ### How to Archive
 
-Use `pbr-tools.js history append`:
+Use `pbr-tools.js` to append to STATE.md ## History:
+
 ```
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append phase "Phase 3 (Auth)" "Verified 2026-02-10. Key decisions: JWT + httpOnly cookies, Discord OAuth."
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append milestone "v1.0 User Auth" "Phases 1-4. All verified. Core auth flow complete."
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state record-activity "Phase 3 (Auth): verified 2026-02-10. Key decisions: JWT + httpOnly cookies, Discord OAuth."
 ```
 
 ### After Archiving
 
-Remove the archived content from STATE.md. The Accumulated Context section should contain ONLY:
+Remove the archived content from the Accumulated Context section. It should contain ONLY:
+
 - Decisions relevant to the **current** phase
 - Active (unresolved) blockers
 - Pending todos for the current milestone
 
-Historical decisions live in HISTORY.md and per-phase SUMMARY.md files.
+Historical decisions live in STATE.md ## History and per-phase SUMMARY.md files.
 
 ---
 
-## Common Update Scenarios
-
-### After build completes
-```
-Plan: {N} of {total} in current phase
-Status: Building → Reviewing (if all plans done) or Building (if more plans remain)
-Last activity: {date} -- Built plan {plan_id}
-```
-
-### After review/verification passes
-```
-Status: Verified
-Last activity: {date} -- Phase {N} verified
-Progress: [{updated bar}] {new percent}%
-```
-Also update **Current focus** to point to the next phase.
-
-### After pause
-```
-## Session Continuity
-Last session: {timestamp}
-Stopped at: {what was in progress}
-Resume file: .planning/.pause-state.json
-```
+## Anti-Pattern
 
-### After milestone completion
-```
-## Milestone
-Current: {project_name} {next_version}
-Phases: {new_start}-{new_end}
-Status: In progress
-```
+> **DO NOT** use Write or Edit to modify STATE.md frontmatter or the Current Position body section.
+> Always use CLI commands. They ensure frontmatter and body stay in sync.
+> **Exception:** Accumulated Context sections (Decisions, Blockers, Todos) are edited directly since they are freeform text.

package/plugins/pbr/skills/shared/universal-anti-patterns.md

@@ -12,26 +12,49 @@ These rules prevent context rot -- quality degradation as the context window fil
 
 1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them. Reading agent definitions into the orchestrator wastes main context for content that is automatically injected into subagent sessions.
 2. **Never** inline large files into Task() prompts -- tell agents to read files from disk instead. Agents have their own 200k token context windows.
-3. **Minimize** reading subagent output into main context -- read only frontmatter, status fields, or summaries. Never read full SUMMARY.md, VERIFICATION.md, or RESEARCH.md bodies into the orchestrator unless specifically needed for inline presentation.
+3. **Read depth scales with context window** — check `context_window_tokens` in `.planning/config.json`. At < 500000: read only frontmatter, status fields, or summaries from subagent output. At >= 500000 (1M model): full body reads are permitted when content is needed for inline decisions. See `skills/shared/context-budget.md` § "Read Depth by Context Window" for the complete table.
 4. **Delegate** heavy work to Task() subagents -- the orchestrator routes, it does not build, analyze, research, investigate, or verify.
 5. **Proactive pause warning**: If you have already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider running `/pbr:pause` to checkpoint progress." Suggest pause proactively rather than waiting for compaction.
 
 ## File Reading Rules (apply to every skill)
 
-6. **Never** read full SUMMARY.md bodies from prior phases -- read frontmatter only (unless the skill specifically requires body content for presentation).
+6. **SUMMARY.md read depth scales with context window** — at context_window_tokens < 500000: read frontmatter only from prior phase SUMMARYs. At >= 500000: full body reads are permitted for direct-dependency phases. Transitive dependencies (2+ phases back) remain frontmatter-only regardless of context window.
 7. **Never** read full PLAN.md files from other phases -- only current phase plans.
 8. **Never** read `.planning/logs/` files -- only the health skill reads these.
-9. **Do not** re-read full file contents when frontmatter is sufficient -- frontmatter contains status, key_files, commits, and provides fields.
+9. **Do not** re-read full file contents when frontmatter is sufficient -- frontmatter contains status, key_files, commits, and provides fields. Exception: at context_window_tokens >= 500000, re-reading a full body is acceptable when the orchestrator needs semantic content, not just structural metadata.
 
 ## Task/Subagent Rules (apply to every skill)
 
 10. **Never** invoke `Skill()` inside a `Task()` subagent -- the Skill tool is not available in subagent contexts. Subagents spawned by `Task()` cannot resolve `/pbr:*` skill prefixes, so `Skill({ skill: "pbr:plan" })` will silently fail. Instead, chain skills at the orchestrator level (return control to the orchestrator, then call `Skill()` from there). For subagent work, use `subagent_type: "pbr:{agent}"` which auto-loads agent definitions.
+11. **NEVER** use non-PBR agent types (`general-purpose`, `Explore`, `Plan`, `Bash`, `feature-dev`, etc.) -- ALWAYS use `subagent_type: "pbr:{agent}"` (e.g., `pbr:researcher`, `pbr:executor`, `pbr:general`). PBR agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this. A PreToolUse hook **blocks** non-PBR agent spawns by default. Exceptions: (a) bare `Task()` with no `subagent_type` for lightweight read-only briefings (see context-loader-task pattern), (b) if the user says "use native agents", add `[native]` to the Task description to bypass the block for that call.
+
+## Questioning Anti-Patterns (apply to every skill)
+
+Reference: `references/questioning.md` for the full anti-pattern list.
+
+20. **Do not** walk through checklists -- checklist walking (asking items one by one from a list) is the #1 anti-pattern. Instead, use progressive depth: start broad, dig where interesting.
+21. **Do not** use corporate speak -- avoid jargon like "stakeholder alignment", "synergize", "deliverables". Use plain language: "who needs to approve?", "work together", "what you'll ship".
+22. **Do not** apply premature constraints -- don't narrow the solution space before understanding the problem. Ask about the problem first, then constrain.
+
+## State Consolidation Anti-Patterns (apply to every skill)
+
+23. **Do not** write to `.planning/CONTEXT.md` -- context is now merged into PROJECT.md ## Context section. Write to PROJECT.md instead.
+24. **Do not** write to `.planning/HISTORY.md` -- history is now merged into STATE.md ## History section. Use `historyAppend()` which targets STATE.md.
+25. **Do not** check for `mode === 'auto'` -- the correct value is `mode === 'autonomous'`. The schema defines `"autonomous"`, not `"auto"`.
+26. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update <field> <value>` or `roadmap update-status <phase> <status>` for mutations. Direct Write tool usage bypasses `lockedFileUpdate()` and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template (e.g., during `/pbr:begin`) is allowed.
 
 ## Behavioral Rules (apply to every skill)
 
-11. **Do not** re-litigate decisions that are already locked in CONTEXT.md -- respect locked decisions unconditionally.
+11. **Do not** re-litigate decisions that are already locked in CONTEXT.md (or PROJECT.md ## Context section) -- respect locked decisions unconditionally.
 12. **Do not** create artifacts the user did not approve -- always confirm before writing new planning documents.
 13. **Do not** modify files outside the skill's stated scope -- check the "Files Created/Modified" table in each skill.
 14. **Do not** suggest multiple next actions without clear priority -- one primary suggestion, alternatives listed secondary.
 15. **Do not** use `git add .` or `git add -A` -- stage specific files only.
+15b. **Do not** write STATE.md frontmatter or Current Position body section directly using Write/Edit -- use `pbr-tools.js` CLI commands (`state update`, `state patch`, `state advance-plan`, `phase complete`) which keep frontmatter and body in sync atomically. Exception: Accumulated Context sections (Decisions, Blockers, Todos) may be edited directly.
 16. **Do not** include sensitive information (API keys, passwords, tokens) in planning documents or commits.
+
+## Error Recovery Rules (apply to every skill)
+
+17. **Git lock detection**: Before any git operation, if it fails with "Unable to create lock file", check for stale `.git/index.lock` and advise the user to remove it (do not remove automatically — another process may hold it legitimately).
+18. **Config fallback awareness**: `configLoad()` returns `null` silently on invalid JSON. If your skill depends on config values, check for null and warn the user: "config.json is invalid or missing — running with defaults. Run `/pbr:health` to diagnose."
+19. **Partial state recovery**: If STATE.md references a phase directory that doesn't exist, do not proceed silently. Warn the user and suggest `/pbr:health` to diagnose the mismatch.

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

@@ -0,0 +1,155 @@
+---
+name: ship
+description: "Create a rich PR from planning artifacts (SUMMARY one-liners, requirement coverage, verification status)."
+allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
+argument-hint: "[--base <branch>] [--draft]"
+---
+
+**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Begin executing Step 1 immediately.**
+
+# /pbr:ship -- Create PR from Planning Artifacts
+
+**References:** `@references/ui-brand.md`
+
+You are the orchestrator for `/pbr:ship`. This skill generates a rich pull request from PBR planning artifacts -- SUMMARY one-liners, verification status, and requirement coverage. It uses `gh pr create` to open the PR.
+
+## Step 0 -- Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
++--------------------------------------------------------------+
+|  PLAN-BUILD-RUN > SHIP                                       |
++--------------------------------------------------------------+
+```
+
+Then proceed to Step 1.
+
+## Step 1: Parse Arguments and Validate
+
+1. Parse `$ARGUMENTS` for optional flags:
+   - `--base <branch>` -- target branch for the PR (default: repo default branch)
+   - `--draft` -- create as draft PR
+2. Verify `gh` CLI is available: `gh --version`
+3. Verify git working tree is clean. If uncommitted changes exist, warn:
+   ```
+   WARNING: You have uncommitted changes. Commit or stash before shipping.
+   ```
+   **CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding:
+   Use AskUserQuestion (pattern: yes-no):
+     question: "Continue with uncommitted changes?"
+   If "No": stop.
+4. Verify current branch is NOT the default branch:
+   ```bash
+   git rev-parse --abbrev-ref HEAD
+   ```
+   If on main/master, warn and stop: "You are on the default branch. Create a feature branch first."
+
+## Step 2: Gather Planning Artifacts
+
+1. Read `.planning/STATE.md` to get current phase info (phase number, slug, status)
+2. Find the current phase directory: `.planning/phases/{NN}-{slug}/`
+3. Read all `SUMMARY-*.md` files in the phase directory:
+   - Extract `status` from frontmatter
+   - Extract one-liner descriptions from the body (first non-heading, non-empty line after `## Task Results`)
+   - Collect `commits` arrays from frontmatter
+4. Read `VERIFICATION.md` in the phase directory (if exists):
+   - Extract `score` and `status` from frontmatter
+   - Extract pass/fail counts
+5. Read `.planning/ROADMAP.md`:
+   - Extract requirements mapped to the current phase
+   - Extract phase goal
+6. Compute git stats:
+   ```bash
+   git diff --stat $(git merge-base HEAD main)..HEAD
+   git log --oneline $(git merge-base HEAD main)..HEAD | wc -l
+   ```
+
+## Step 3: Generate PR Body
+
+Build the PR body with these sections:
+
+```markdown
+## Summary
+
+{Phase goal from ROADMAP.md}
+
+{For each SUMMARY file: "- **Plan {NN}**: {one-liner status}" }
+
+## Requirements
+
+| REQ-ID | Description | Status |
+|--------|-------------|--------|
+{For each requirement mapped to this phase}
+
+## Verification
+
+- **Score**: {score from VERIFICATION.md or "Not verified"}
+- **Status**: {status}
+- **Must-haves**: {pass_count}/{total_count} passing
+
+## Changes
+
+- **Commits**: {commit_count}
+- **Files changed**: {file_count}
+- **Insertions**: +{insertions}
+- **Deletions**: -{deletions}
+
+---
+Generated with [Plan-Build-Run](https://github.com/pibster/plan-build-run)
+```
+
+## Step 4: Create PR
+
+1. Generate a PR title from the phase: `feat({phase-slug}): {phase goal summary}`
+   - Keep under 70 characters
+   - Use appropriate commit type (feat, fix, refactor) based on phase goal keywords
+2. Run `gh pr create`:
+   ```bash
+   gh pr create --title "{title}" --body "$(cat <<'PREOF'
+   {generated body}
+   PREOF
+   )"
+   ```
+   - Add `--base {branch}` if `--base` flag was provided
+   - Add `--draft` if `--draft` flag was provided
+3. Capture and display the PR URL
+
+## Step 5: Display Result
+
+```
+PR created: {url}
+
+  Title:    {title}
+  Base:     {base branch}
+  Status:   {draft or ready}
+  Commits:  {count}
+  Files:    {count}
+```
+
+## Step 6: Next Steps
+
+After displaying the PR result, always present a NEXT UP routing block:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**PR created** — continue to the next phase or track progress
+
+`/pbr:continue`
+
+**Also available:**
+- `/pbr:status` — see overall project status
+- `/pbr:milestone` — if this was the last phase, complete the milestone
+
+<sub>`/clear` first → fresh context window</sub>
+```
+
+## Error Handling
+
+- `gh` not installed: "Install GitHub CLI: https://cli.github.com/"
+- Not a git repo: stop with error
+- No planning artifacts found: "No SUMMARY files found. Run /pbr:build first."
+- PR creation fails: show the `gh` error output and suggest fixes

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

@@ -0,0 +1,110 @@
+---
+name: stats
+description: "Display project statistics — phases, plans, requirements, git metrics, and timeline."
+allowed-tools: Read, Bash, Glob, Grep
+argument-hint: "[--json]"
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it.**
+
+# /pbr:stats — Project Statistics
+
+Display comprehensive project metrics: phase/plan completion, requirement coverage, git activity, and timeline. Runs inline — no subagent needed.
+
+## Step 0 — Banner
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► STATS                                      ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+## Step 1 — Gather Data
+
+```bash
+# Phase counts
+PHASE_DIRS=$(ls -d .planning/phases/*/ 2>/dev/null | wc -l)
+PLANS=$(ls .planning/phases/*/PLAN-*.md 2>/dev/null | wc -l)
+SUMMARIES=$(ls .planning/phases/*/SUMMARY-*.md 2>/dev/null | wc -l)
+VERIFICATIONS=$(ls .planning/phases/*/VERIFICATION*.md 2>/dev/null | wc -l)
+
+# Quick task counts
+QUICK_TOTAL=$(ls -d .planning/quick/*/ 2>/dev/null | wc -l)
+
+# Git metrics
+TOTAL_COMMITS=$(git rev-list --count HEAD 2>/dev/null || echo 0)
+RECENT_COMMITS=$(git log --oneline --since="7 days ago" 2>/dev/null | wc -l)
+FILES_CHANGED=$(git diff --stat HEAD~10 2>/dev/null | tail -1)
+
+# Todo counts
+PENDING_TODOS=$(ls .planning/todos/pending/*.md 2>/dev/null | wc -l)
+DONE_TODOS=$(ls .planning/todos/done/*.md 2>/dev/null | wc -l)
+
+# Milestone info from STATE.md
+MILESTONE=$(grep "^Active:" .planning/STATE.md 2>/dev/null | head -1)
+```
+
+Also read ROADMAP.md for milestone history count and REQUIREMENTS.md for coverage.
+
+## Step 1b — Cost & Duration Data
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js benchmarks summary --json
+```
+
+Parse the JSON result. If `totals.count > 0`, include a "Cost & Duration" section in the output showing:
+- Total agent spawns and cumulative duration
+- Top 3 phases by total duration
+- Top 3 agent types by spawn count
+
+If no data or `totals.count === 0`, skip this section silently.
+
+Also run:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js benchmarks agents --json
+```
+
+Use the agents result for the "Top 3 agent types" breakdown.
+
+Display format (append after Timeline section):
+
+```
+Cost & Duration:
+  Total Spawns: {count} agents, {duration}
+  Top Phases:   {phase1} ({duration1}), {phase2} ({duration2}), {phase3} ({duration3})
+  Top Agents:   {type1} ({count1}x), {type2} ({count2}x), {type3} ({count3}x)
+```
+
+## Step 2 — Display
+
+```
+Project Statistics
+══════════════════════════════════════════
+
+Milestone:  {active milestone name}
+Phases:     {completed}/{total} ({percent}%)
+Plans:      {total plans} written, {summaries} completed
+Verified:   {verifications}/{completed phases}
+
+Quick Tasks: {total} ({percent}% success rate)
+Todos:       {pending} pending, {done} completed
+
+Git Activity (7 days):
+  Commits:  {recent_commits}
+  Total:    {total_commits} all-time
+  Changed:  {files_changed}
+
+Timeline:
+  Started:  {first commit date}
+  Latest:   {last commit date}
+  Duration: {days} days
+```
+
+If `--json` flag: output raw JSON instead of formatted text.
+
+## Anti-Patterns
+
+1. DO NOT spawn subagents — stats is inline only
+2. DO NOT modify any files — read-only
+3. DO NOT count files that don't exist — use proper error handling