@sienklogic/plan-build-run 2.18.1 → 2.19.1

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,80 @@
+---
+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 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