@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/pbr/skills/shared/context-loader-task.md

@@ -28,22 +28,28 @@ Task({
     - .planning/STATE.md
     - .planning/ROADMAP.md
     - .planning/REQUIREMENTS.md
+    - .planning/PROJECT.md (if exists — project vision and scope)
     - .planning/CONTEXT.md
     - Any .planning/phases/*/CONTEXT.md files
     - .planning/research/SUMMARY.md (if exists)
-    - .planning/NOTES.md (if exists)
+    - .planning/notes/*.md (if notes directory exists — read frontmatter for date/promoted status)
     - .planning/HISTORY.md (if exists — scan for decisions relevant to current work only, do NOT summarize all history)
 
   Return ONLY the briefing text. No preamble, no suggestions."
 })
 ```
 
+### CLI Alternative
+
+Alternatively, the skill can call `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load` for structured JSON state instead of spawning a briefing Task. Use the CLI approach when only state data is needed; use the Task approach when project context (decisions, notes, history) is also needed.
+
 ### Key Rules
 
 1. **Only runs if `.planning/` directory exists.** Skills invoked on fresh projects with no planning directory skip this entirely.
 2. **Budget: ~500 tokens.** The briefing must be concise. The subagent reads full files in its own context; the orchestrator receives only the summary.
 3. **No suggestions.** The briefing reports state, it does not recommend actions. The skill logic decides what to do.
 4. **Read-only.** The briefing task must not write any files.
+5. **No subagent_type needed.** This is the ONE exception to the "always use `pbr:*` agents" rule. Bare `Task()` without `subagent_type` is intentional here — these are lightweight read-only briefings that don't need agent-specific prompts. Do NOT generalize this pattern to other Task() calls — all research, execution, and analysis Task() calls MUST use `subagent_type: "pbr:{agent}"`.
 
 ### Using the Briefing
 
@@ -64,6 +70,7 @@ Task({
     - .planning/STATE.md
     - .planning/ROADMAP.md
     - .planning/REQUIREMENTS.md
+    - .planning/PROJECT.md (if exists — project vision and scope)
     - .planning/CONTEXT.md
     - Any .planning/phases/*/CONTEXT.md files
     - .planning/HISTORY.md (if exists — scan for decisions relevant to '{topic}' only, do NOT summarize all history)
@@ -77,7 +84,7 @@ Task({
 
 ## Variation: Scan Reconnaissance
 
-For `/pbr:scan`, the pattern adapts to codebase analysis rather than project state:
+For `/pbr:map-codebase`, the pattern adapts to codebase analysis rather than project state:
 
 1. The orchestrator performs a quick inline scan (detect project type, scale, key directories)
 2. Writes the results to `.planning/codebase/RECON.md`

package/plugins/pbr/skills/shared/digest-select.md

@@ -64,11 +64,11 @@ These fields give downstream skills enough context to build on prior work withou
 
 ## Skill-Specific Notes
 
-### /pbr:plan
+### /pbr:plan-phase
 - Direct dependencies: frontmatter + "Key Decisions" section (planner reads full bodies from disk)
 - Used in Step 2: Load Context
 
-### /pbr:build
+### /pbr:execute-phase
 - Direct dependencies (completed earlier waves): frontmatter only for prior work table
 - Used in Step 6a: Spawn Executors (prior_work section of executor prompt)
 

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,79 +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
-
-For errors that don't halt the workflow — skill can suggest a fix or retry:
+## Error Box Format
 
 ```
-⚠ Warning: {short description}
-
-{1-2 line explanation of what went wrong}
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
 
-To fix: {actionable instruction}
-```
+{one-line description of what went wrong}
 
-Example:
+**To fix:** {specific action the user should take}
 ```
-⚠ Warning: STATE.md is 180 lines (limit: 150)
 
-The state file has grown beyond the recommended size, which increases context usage on load.
+## Warning Format (non-blocking)
 
-To fix: Run /pbr:health to compact the Accumulated Context section.
 ```
-
-## Fatal Error
-
-For errors that stop execution — skill cannot continue:
-
+⚠ {one-line warning}
+  {optional detail or suggestion}
 ```
-✗ Error: {short description}
+Continue execution after showing a warning.
 
-{1-2 line explanation}
+## Common Error Patterns
 
-What to try:
-  1. {first suggestion}
-  2. {second suggestion}
-  3. {fallback — often /pbr:health or manual fix}
-```
+### Phase not found
+Message: "Phase {N} not found in ROADMAP.md."
+Fix: "Run `/pbr:progress` to see available phases."
 
-Example:
-```
-✗ Error: PLAN.md not found for phase 03
+### Missing prerequisites (no REQUIREMENTS.md or ROADMAP.md)
+Message: "Project not initialized. Missing REQUIREMENTS.md or ROADMAP.md."
+Fix: "Run `/pbr:new-project` first."
 
-No plan files exist in .planning/phases/03-auth/. The executor cannot run without a plan.
+### No plans found for phase
+Message: "Phase {N} has no plans."
+Fix: "Run `/pbr:plan-phase {N}` first."
 
-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
-```
+### 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}`."
 
-## Validation Error
+### Planner agent failure
+Message: "Planner agent failed for Phase {N}."
+Fix: "Try again with `/pbr:plan-phase {N} --skip-research`. Check `.planning/CONTEXT.md` for conflicting constraints."
 
-For format or schema validation failures (config, plan format, commit message):
+### 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).
 
-```
-✗ Validation failed: {what was validated}
+### 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.
 
-Issues:
-  - {specific issue 1}
-  - {specific issue 2}
-
-Expected format: {brief format description or example}
-```
-
-## Hook Block Message
-
-For PreToolUse hooks that reject a tool call:
-
-```
-Blocked: {short reason}
-
-{explanation}
-
-{how to fix or alternative approach}
-```
+## Usage
 
-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.
+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/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
 
@@ -40,6 +40,6 @@ Given phase number N:
 
 ## Error Messages
 
-- 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."
+- No argument and no current phase: "Which phase? Specify a number or run /pbr:progress to see where you are."
+- Phase not found: "Phase {N} not found in .planning/phases/. Run /pbr:progress to see available phases."
+- Wrong state: "Phase {N} hasn't been planned yet. Run /pbr:plan-phase {N} first."

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.js` 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,8 +107,8 @@ 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 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
 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.
@@ -127,35 +146,8 @@ Historical decisions live in HISTORY.md and per-phase SUMMARY.md files.
 
 ---
 
-## Common Update Scenarios
+## Anti-Pattern
 
-### 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
-```
-
-### 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,22 +12,48 @@ 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.
+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-work` 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"`.
 
 ## Behavioral Rules (apply to every skill)
 
-10. **Do not** re-litigate decisions that are already locked in CONTEXT.md -- respect locked decisions unconditionally.
-11. **Do not** create artifacts the user did not approve -- always confirm before writing new planning documents.
-12. **Do not** modify files outside the skill's stated scope -- check the "Files Created/Modified" table in each skill.
-13. **Do not** suggest multiple next actions without clear priority -- one primary suggestion, alternatives listed secondary.
-14. **Do not** use `git add .` or `git add -A` -- stage specific files only.
-15. **Do not** include sensitive information (API keys, passwords, tokens) in planning documents or commits.
+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.