@sienklogic/plan-build-run 2.21.0 → 2.21.2

package/plugins/pbr/skills/shared/context-budget.md

@@ -12,10 +12,48 @@ Every skill that spawns agents or reads significant content must follow these ru
 
 1. **Never** read agent definition files (`agents/*.md`) — `subagent_type` auto-loads them
 2. **Never** inline large files into Task() prompts — tell agents to read files from disk instead
-3. **Minimize** reading subagent output into main context — read only frontmatter, not full content
+3. **Read depth scales with context window** — check `context_window_tokens` in `.planning/config.json`:
+   - At < 500000 tokens (default 200k): read only frontmatter, status fields, or summaries. Never read full SUMMARY.md, VERIFICATION.md, or RESEARCH.md bodies.
+   - At >= 500000 tokens (1M model): MAY read full subagent output bodies when the content is needed for inline presentation or decision-making. Still avoid unnecessary reads.
 4. **Delegate** heavy work to subagents — the orchestrator routes, it doesn't execute
 5. **Before spawning agents**: If you've 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.
 
+## Read Depth by Context Window
+
+| Context Window | Subagent Output Reading | SUMMARY.md | VERIFICATION.md | PLAN.md (other phases) |
+|---------------|------------------------|------------|-----------------|------------------------|
+| < 500k (200k model) | Frontmatter only | Frontmatter only | Frontmatter only | Current phase only |
+| >= 500k (1M model) | Full body permitted | Full body permitted | Full body permitted | Current phase only |
+
+**How to check:** Read `.planning/config.json` and inspect `context_window_tokens`. If the field is absent, treat as 200k (conservative default).
+
+**Applies to:** build, plan, review skills — any skill that reads back subagent artifacts.
+
+## Context Degradation Awareness
+
+Quality degrades gradually before panic thresholds fire. Watch for these early warning signs:
+
+- **Silent partial completion** — agent claims task is done but implementation is incomplete. Self-check catches file existence but not semantic completeness. Always verify agent output meets the plan's must_haves, not just that files exist.
+- **Increasing vagueness** — agent starts using phrases like "appropriate handling" or "standard patterns" instead of specific code. This indicates context pressure even before budget warnings fire.
+- **Skipped steps** — agent omits protocol steps it would normally follow. If an agent's success criteria has 8 items but it only reports 5, suspect context pressure.
+
+When delegating to agents, the orchestrator cannot verify semantic correctness of agent output — only structural completeness. This is a fundamental limitation. Mitigate with must_haves.truths and spot-check verification.
+
+## State Consolidation Impact
+
+State consolidation (Phase 5) reduces core planning files from 5 to 3:
+- CONTEXT.md is now merged into PROJECT.md ## Context section
+- HISTORY.md is now merged into STATE.md ## History section
+- This reduces per-phase context loading overhead — fewer files to read, same information
+
+**File size estimates (post-consolidation):**
+- PROJECT.md: ~2-4 KB (includes Context section)
+- STATE.md: ~3-6 KB (includes History section)
+- ROADMAP.md: ~3-8 KB (depending on phase count)
+- config.json: ~1-2 KB
+
+**Note:** PROJECT.md is larger now with the merged Context section. Factor this into context budget when loading project state.
+
 ## Customization
 
 Skills should add skill-specific rules below the reference line. Common skill-specific additions:
@@ -38,3 +76,30 @@ Additionally for this skill:
 - {Skill-specific rule 1}
 - {Skill-specific rule 2}
 ```
+
+## Agent Elapsed Time Estimates
+
+When displaying agent spawn lines (e.g., "Spawning researcher..."), append a parenthetical estimate:
+
+| Agent Type | Display Text | Estimate |
+|------------|-------------|----------|
+| researcher | Spawning researcher... | (est. 1-3 min) |
+| planner | Spawning planner... | (est. 2-5 min) |
+| executor | Spawning executor... | (est. 3-8 min) |
+| verifier | Spawning verifier... | (est. 1-2 min) |
+| codebase-mapper | Spawning codebase-mapper... | (est. 1-2 min) |
+| plan-checker | Spawning plan-checker... | (est. 1-2 min) |
+| integration-checker | Spawning integration-checker... | (est. 2-4 min) |
+| debugger | Spawning debugger... | (est. 2-5 min) |
+| general | Spawning agent... | (est. 1-4 min) |
+| audit | Spawning audit... | (est. 2-4 min) |
+
+**Usage**: In any skill that spawns Task() agents, prefix spawn displays with the agent name and append the estimate from this table. Example:
+
+```
+Spawning researcher... (est. 1-3 min)
+Spawning planner... (est. 2-5 min)
+[Wave 1: 3 plans in parallel] Spawning executors... (est. 3-8 min each)
+```
+
+Skills that spawn agents: build, plan, review, debug, scan, milestone, quick.

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

@@ -28,22 +28,28 @@ Task({
     - .planning/STATE.md
     - .planning/ROADMAP.md
     - .planning/REQUIREMENTS.md
-    - .planning/CONTEXT.md
-    - Any .planning/phases/*/CONTEXT.md files
+    - .planning/PROJECT.md (if exists — project vision, scope, and context)
+    - Any .planning/phases/*/CONTEXT.md files (phase-level locked decisions)
     - .planning/research/SUMMARY.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)
+    - .planning/KNOWLEDGE.md (if exists -- project knowledge: rules, patterns, lessons)
+    - .planning/STATE.md ## History section (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,9 +70,10 @@ Task({
     - .planning/STATE.md
     - .planning/ROADMAP.md
     - .planning/REQUIREMENTS.md
-    - .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)
+    - .planning/PROJECT.md (if exists — project vision, scope, and context)
+    - Any .planning/phases/*/CONTEXT.md files (phase-level locked decisions)
+    - .planning/KNOWLEDGE.md (if exists -- project knowledge: rules, patterns, lessons)
+    - .planning/STATE.md ## History section (scan for decisions relevant to '{topic}' only, do NOT summarize all history)
 
   Focus on: decisions, requirements, and phase goals related to '{topic}'.
   Return ONLY the briefing text. No preamble, no suggestions."
@@ -77,10 +84,10 @@ 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`
-3. Passes RECON.md content to the spawned analysis agents as baseline context
+1. The orchestrator runs `init map-codebase` to get config, model, and existing map metadata
+2. Spawns 4 parallel codebase-mapper agents — each explores the codebase independently
+3. Agents write documents directly to `.planning/codebase/` (no context transfer back)
 
-This is the same principle (build context before main work) but the source is the codebase rather than planning files.
+This is the same principle (delegate heavy work to agents) but the agents self-discover rather than receiving pre-built context.

package/plugins/pbr/skills/shared/criterion-writing.md

@@ -0,0 +1,58 @@
+## Criterion Writing Guidance
+
+> Loaded by: planner agent, plan-checker agent
+
+Must-have criteria steer executor behavior. Wording that is vague or subjective produces vague implementations. Every criterion should be verifiable by a shell command returning 0/non-0.
+
+### Vague-to-Concrete Examples
+
+**Bad:** "User authentication should work properly"
+**Good:** "POST /api/auth/login returns 200 with {token} on valid credentials and 401 on invalid"
+
+**Bad:** "Error handling should be robust"
+**Good:** "Every async function in src/api/ has a try-catch that logs to structured logger and returns appropriate HTTP status"
+
+**Bad:** "The UI should be responsive"
+**Good:** "All pages pass Lighthouse accessibility audit at mobile viewport (375px)"
+
+**Bad:** "Code should be well-structured"
+**Good:** "No file exceeds 300 lines; no function exceeds 40 lines; all exports have JSDoc"
+
+**Bad:** "The system should be performant"
+**Good:** "API endpoints respond in <200ms at p95 under 100 concurrent requests"
+
+**Bad:** "Security should be handled properly"
+**Good:** "All user input sanitized via DOMPurify before render; no raw SQL queries outside query builder"
+
+### Vague Pattern Reference
+
+| Pattern | Problem | Fix |
+|---------|---------|-----|
+| "should be good/nice/clean/proper" | Subjective quality | Add observable threshold |
+| "properly handles/manages/processes" | Undefined "properly" | Specify behavior for each case |
+| "clean code" | Aesthetic judgment | Measurable constraint (line count, lint rules) |
+| "well-tested/structured/organized" | No coverage target | Numeric threshold or structural rule |
+| "responsive" (no px) | No viewport threshold | Specify exact breakpoints |
+| "performant" (no number) | No baseline | Add latency/throughput target |
+| "robust" (no mechanism) | No resilience spec | Name retry/fallback/timeout strategy |
+| "secure" (no mechanism) | Too broad | Name specific sanitization/auth mechanism |
+
+### Self-Check Before Committing Criteria
+
+For each must-have truth, ask:
+
+1. Can I write a `grep`, `test`, or `curl` command that returns 0 when this is true?
+2. Would two different executors produce observably similar results from this wording?
+3. Does this describe a user-observable outcome, not an implementation aesthetic?
+
+If any answer is "no", rewrite the criterion with a specific threshold or observable.
+
+### Why This Matters
+
+Vague criteria create a feedback loop:
+- Planner writes "should work properly"
+- Executor interprets loosely, implements minimal path
+- Verifier cannot objectively evaluate "properly"
+- Review flags gaps, triggering rework
+
+Concrete criteria break this loop by giving executor and verifier the same objective target.

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