@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plugins/pbr/skills/shared/domain-probes.md

@@ -1,6 +1,6 @@
 # Domain-Aware Probing Patterns
 
-Shared reference for `/pbr:explore`, `/pbr:begin`, and `/pbr:discuss`.
+Shared reference for `/pbr:explore`, `/pbr:new-project`, and `/pbr:discuss-phase`.
 
 When the user mentions a technology area, use these probes to ask insightful follow-up questions. Don't run through them as a checklist — pick the 2-3 most relevant based on context. The goal is to surface hidden assumptions and trade-offs the user may not have considered yet.
 

package/plugins/pbr/skills/shared/error-reporting.md

@@ -1,81 +1,59 @@
-# Error Reporting Fragment
+# Error Reporting — Standard Format
 
-Standard error display formats for all skills. Reference `references/ui-formatting.md` for the full brand guide.
+Use the branded error box for all blocking errors. Present the box, explain what happened, and give a specific fix action.
 
-## Recoverable Error
+## Error Box Format
 
-For errors that don't halt the workflow — skill can suggest a fix or retry:
-
-```
-⚠ Warning: {short description}
-
-{1-2 line explanation of what went wrong}
-
-To fix: {actionable instruction}
-```
-
-Example:
 ```
-⚠ Warning: STATE.md is 180 lines (limit: 150)
-
-The state file has grown beyond the recommended size, which increases context usage on load.
-
-To fix: Run /pbr:health to compact the Accumulated Context section.
-```
-
-## Fatal Error
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
 
-For errors that stop execution — skill cannot continue:
+{one-line description of what went wrong}
 
+**To fix:** {specific action the user should take}
 ```
-✗ Error: {short description}
 
-{1-2 line explanation}
+## Warning Format (non-blocking)
 
-What to try:
-  1. {first suggestion}
-  2. {second suggestion}
-  3. {fallback — often /pbr:health or manual fix}
 ```
-
-Example:
+⚠ {one-line warning}
+  {optional detail or suggestion}
 ```
-✗ Error: PLAN.md not found for phase 03
-
-No plan files exist in .planning/phases/03-auth/. The executor cannot run without a plan.
-
-What to try:
-  1. Run /pbr:plan 3 to create a plan first
-  2. Check if the phase directory exists: ls .planning/phases/03-*
-  3. Run /pbr:health to check planning directory integrity
-```
-
-## Validation Error
+Continue execution after showing a warning.
 
-For format or schema validation failures (config, plan format, commit message):
+## Common Error Patterns
 
-```
-✗ Validation failed: {what was validated}
+### Phase not found
+Message: "Phase {N} not found in ROADMAP.md."
+Fix: "Run `/pbr:status` to see available phases."
 
-Issues:
-  - {specific issue 1}
-  - {specific issue 2}
+### Missing prerequisites (no REQUIREMENTS.md or ROADMAP.md)
+Message: "Project not initialized. Missing REQUIREMENTS.md or ROADMAP.md."
+Fix: "Run `/pbr:new-project` first."
 
-Expected format: {brief format description or example}
-```
+### No plans found for phase
+Message: "Phase {N} has no plans."
+Fix: "Run `/pbr:plan-phase {N}` first."
 
-## Hook Block Message
+### Dependency phase not complete
+Message: "Phase {N} depends on Phase {M}, which is not complete."
+Fix: "Build Phase {M} first with `/pbr:execute-phase {M}`."
 
-For PreToolUse hooks that reject a tool call:
+### Planner agent failure
+Message: "Planner agent failed for Phase {N}."
+Fix: "Try again with `/pbr:plan-phase {N} --skip-research`. Check `.planning/PROJECT.md` for conflicting constraints."
 
-```
-Blocked: {short reason}
+### Checker loops (3+ iterations without pass)
+Message: "Plan checker failed to pass after 3 revision iterations for Phase {N}."
+Fix: "Review the remaining issues below and decide whether to proceed or revise manually. Run `/pbr:plan-phase {N}` to restart planning from scratch."
+After displaying: present remaining issues and ask user to decide (proceed or intervene).
 
-{explanation}
-
-{how to fix or alternative approach}
-```
+### Research agent failure
+Display as WARNING (non-blocking): "Research agent failed. Planning without phase-specific research. This may result in less accurate plans."
+Continue to the planning step.
 
-This format is used by validate-commit.js and check-dangerous-commands.js. The `decision: "block"` and `reason` fields in the JSON output follow this pattern.
+## Usage
 
-Block reasons should always include a "To fix:" line with actionable guidance so the user or agent knows how to resolve the block.
+In skill files, replace repeated error box content with:
+"Display a branded error box — use the format from `skills/shared/error-reporting.md`, pattern: {pattern name}."

package/plugins/pbr/skills/shared/gate-prompts.md

@@ -5,6 +5,8 @@
 
 These patterns provide consistent, structured prompts for user decision points. Skills reference these patterns by name to ensure all gate checks use the same format.
 
+**For checkpoint box format details, see `@references/ui-brand.md`** — checkpoint boxes use double-line border drawing with 62-character inner width. All gate types (approval, decision, information) should use the standardized checkpoint box format from ui-brand.md when presenting user-facing decision points.
+
 ## Rules
 
 - `header` must be max 12 characters
@@ -107,7 +109,7 @@ Use AskUserQuestion:
   header: "Escalate"
   options:
     - label: "Accept gaps"  description: "Mark as complete-with-gaps and move on"
-    - label: "Re-plan"      description: "Go back to /pbr:plan with gap context"
+    - label: "Re-plan"      description: "Go back to /pbr:plan-phase with gap context"
     - label: "Debug"        description: "Spawn /pbr:debug to investigate root causes"
     - label: "Retry"        description: "Try one more verification cycle"
   multiSelect: false
@@ -257,7 +259,7 @@ Use AskUserQuestion:
   header: "Scope"
   options:
     - label: "Quick task"  description: "Execute as lightweight task"
-    - label: "Full plan"   description: "Switch to /pbr:plan for proper planning"
+    - label: "Full plan"   description: "Switch to /pbr:plan-phase for proper planning"
     - label: "Revise"      description: "Let me rewrite the task description"
   multiSelect: false
 ```

package/plugins/pbr/skills/shared/memory-capture.md

@@ -0,0 +1,48 @@
+## Memory Capture (Post-Agent)
+
+After any agent that supports memory suggestions completes, check the agent's Task() output for `<memory_suggestion>` blocks.
+
+**Supported agents:** executor, planner, researcher, debugger.
+
+### Parsing Protocol
+
+1. Scan the agent's returned output text for `<memory_suggestion type="...">` blocks
+2. For each block found, extract:
+   - `type` attribute: one of `user`, `feedback`, `project`, `reference`
+   - `description:` line (first line of content) -- a one-line summary
+   - Remaining content after the description line -- the memory body
+3. If **0 suggestions** found: skip silently, proceed with normal flow
+4. If **1-2 suggestions** found: save each immediately (see Saving below)
+5. If **3+ suggestions** found: display them to the user and ask via AskUserQuestion which to save (the agent may be over-suggesting)
+
+### Saving
+
+For each suggestion to save:
+
+1. Generate a slug from the description (first 4 words, lowercase, hyphenated)
+2. Determine the target directory:
+   - `project` or `reference` type -> `.planning/memory/{slug}.md` (project-scoped, survives with .planning/)
+   - `user` or `feedback` type -> use the Write tool to save to the auto-memory directory
+3. Write the file with standard frontmatter:
+
+       ---
+       name: {slug}
+       description: "{description from the suggestion}"
+       type: {type from the suggestion}
+       ---
+
+       {memory content body}
+
+4. Update MEMORY.md index if saving to auto-memory directory
+
+### When to Skip
+
+- If the agent failed (PLAN FAILED, DEBUG FAILED, etc.) -- do not process suggestions from failed runs
+- If the suggestion content is clearly ephemeral (mentions "this task", "current file", etc.) -- skip it
+- If a memory with very similar content already exists -- skip to avoid duplicates
+
+### Anti-Patterns
+
+- DO NOT save every suggestion blindly -- quality over quantity
+- DO NOT save task-specific details as memory -- only reusable knowledge
+- DO NOT block the workflow waiting for memory saves -- this is a post-completion step

package/plugins/pbr/skills/shared/phase-argument-parsing.md

@@ -24,9 +24,9 @@ Input       → Normalized  → Directory Name
 1. Phase number must be numeric (integer or decimal with one decimal place)
 2. Phase must exist in ROADMAP.md (or be a valid target for insert/add)
 3. Phase must be in the expected state for the operation:
-   - `/pbr:plan N` — phase must not already have plans (unless re-planning)
-   - `/pbr:build N` — phase must have plans
-   - `/pbr:review N` — phase must have been built (SUMMARY.md files exist)
+   - `/pbr:plan-phase N` — phase must not already have plans (unless re-planning)
+   - `/pbr:execute-phase N` — phase must have plans
+   - `/pbr:verify-work N` — phase must have been built (SUMMARY.md files exist)
 
 ## Finding Phase Directory
 
@@ -42,4 +42,4 @@ Given phase number N:
 
 - No argument and no current phase: "Which phase? Specify a number or run /pbr:status to see where you are."
 - Phase not found: "Phase {N} not found in .planning/phases/. Run /pbr:status to see available phases."
-- Wrong state: "Phase {N} hasn't been planned yet. Run /pbr:plan {N} first."
+- Wrong state: "Phase {N} hasn't been planned yet. Run /pbr:plan-phase {N} first."

package/plugins/pbr/skills/shared/revision-loop.md

@@ -16,6 +16,7 @@ This pattern applies whenever:
 ### Flow
 
 ```
+prev_issue_count = Infinity
 iteration = 0
 
 LOOP:
@@ -27,18 +28,33 @@ LOOP:
      a. iteration += 1
      b. If iteration > 3:
         → Escalate to user (see "After 3 Iterations" below)
-     c. Re-spawn the producing agent with checker feedback appended
-     d. After revision completes, go to LOOP
+     c. Parse issue count from checker output
+     d. If issue_count >= prev_issue_count:
+        → Escalate to user: "Revision loop stalled (issue count not decreasing)"
+     e. prev_issue_count = issue_count
+     f. Re-spawn the producing agent with checker feedback appended
+     g. After revision completes, go to LOOP
 ```
 
+### Issue Count Tracking
+
+Track the number of BLOCKER + WARNING issues returned by the checker on each iteration. If the count does not decrease between consecutive iterations, the producing agent is stuck and further iterations will not help. Break early and escalate to the user.
+
+Display iteration progress before each revision spawn:
+`◆ Revision iteration {N}/3 — {blocker_count} blockers, {warning_count} warnings`
+
 ### Re-spawn Prompt Structure
 
-When re-spawning the producing agent for revision, append the checker feedback:
+When re-spawning the producing agent for revision, pass the checker's YAML-formatted issues. The checker's output contains a `## Issues` heading followed by a YAML block. Parse this block and pass it verbatim to the revision agent.
 
 ```
-<checker_feedback>
-{Inline the checker's issue report}
-</checker_feedback>
+<checker_issues>
+The issues below are in YAML format. Each has: dimension, severity, finding,
+affected_field, suggested_fix. Address ALL BLOCKER issues. Address WARNING
+issues where feasible.
+
+{YAML issues block from checker output — passed verbatim}
+</checker_issues>
 
 <revision_instructions>
 Address ALL BLOCKER and WARNING issues identified above.
@@ -46,6 +62,8 @@ Address ALL BLOCKER and WARNING issues identified above.
 - For each WARNING: address or explain why it's acceptable
 - Do NOT introduce new issues while fixing existing ones
 - Preserve all content not flagged by the checker
+This is revision iteration {N} of max 3. Previous iteration had {prev_count}
+issues. You must reduce the count or the loop will terminate.
 </revision_instructions>
 ```
 

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

@@ -1,19 +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.cjs` commands instead of writing STATE.md directly.
+
+> Referenced by: build, plan, review, milestone, pause, resume, continue, begin, import, quick skills
+
+---
+
+## 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) | Current Position section |
-| Plan completes or fails | Plan counter, status, last activity |
-| 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 |
 
 ---
 
@@ -45,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)
 ```
@@ -88,74 +107,48 @@ Resume file: {path or "None"}
    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.
 
 ---
 
-## 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.cjs` 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}
-```
+## Anti-Pattern
 
-### 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
-```
-
-### 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.cjs` 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,154 @@
+---
+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.
+   ```
+   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