@sienklogic/plan-build-run 2.10.0 → 2.11.0

package/plugins/cursor-pbr/skills/todo/SKILL.md

@@ -9,9 +9,9 @@ argument-hint: "add <description> | list [theme] | done <NNN> | work <NNN>"
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► TODO
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► TODO                                       ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -73,15 +73,17 @@ theme: {inferred-theme}
 
 8. Confirm with branded output:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► TODO ADDED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► TODO ADDED ✓                               ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Todo {NNN}:** {description}
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Work on it now** or see your task list
 
@@ -89,13 +91,13 @@ theme: {inferred-theme}
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:todo list` — see all pending todos
 - `/pbr:status` — see project status
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ### `list [theme]`
@@ -115,21 +117,23 @@ Pending Todos:
 
 5. Offer actions with branded routing:
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Pick a todo** — mark one done or start working
 
 `/pbr:todo work <NNN>` — start working on a todo
 `/pbr:todo done <NNN>` — mark a todo as complete
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:status` — see project status
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ### `done <NNN>`
@@ -148,20 +152,37 @@ Todo {NNN} not found in pending todos.
 3. Ensure `.planning/todos/done/` directory exists (create if needed)
 4. Read the pending file content
 5. Update frontmatter in the content: set `status: done` and add `completed: {YYYY-MM-DD}`
+
+**CRITICAL: Write to done/ FIRST, verify it exists, THEN delete from pending/. Do NOT delete pending before confirming done/ write succeeded.**
+
 6. Write the updated content to `.planning/todos/done/{NNN}-{slug}.md`
-7. Delete the original file from `.planning/todos/pending/` (use `rm` via Bash)
+7. Verify the done/ file was written successfully: check that `.planning/todos/done/{NNN}-{slug}.md` exists and has content (use `ls` or Glob)
+   - If the done/ write failed, abort and display:
+     ```
+     ╔══════════════════════════════════════════════════════════════╗
+     ║  ERROR                                                       ║
+     ╚══════════════════════════════════════════════════════════════╝
+
+     Failed to write to done/. Pending file preserved.
+
+     **To fix:** Check that `.planning/todos/done/` exists and is writable.
+     ```
+     Do NOT proceed to delete the pending file.
+8. Only THEN delete the original file from `.planning/todos/pending/` (use `rm` via Bash)
 8. Update STATE.md
 9. Confirm with branded output:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► TODO COMPLETED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► TODO COMPLETED ✓                           ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Todo {NNN}:** {title}
 
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **See remaining tasks**
 
@@ -169,13 +190,13 @@ Todo {NNN} not found in pending todos.
 
 <sub>`/clear` first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
+
 
 **Also available:**
 - `/pbr:continue` — execute next logical step
 - `/pbr:status` — see project status
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ### `work <NNN>`
@@ -207,9 +228,9 @@ Which approach?
 
 6. Display branded output:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► WORKING ON TODO {NNN}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► WORKING ON TODO {NNN}                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Todo {NNN}:** {title}
 **Routing to:** /pbr:{chosen-skill}
@@ -229,15 +250,17 @@ For `/pbr:plan`, if no phase exists for this work yet, suggest the user run `/pb
 8. When the skill completes, remind the user:
 
 ```
-───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Mark this todo as done if the work is complete**
 
 `/pbr:todo done {NNN}`
 
-───────────────────────────────────────────────────────────────
+
 ```
 
 ### No arguments

package/plugins/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/pbr/agents/codebase-mapper.md

@@ -51,6 +51,48 @@ You receive ONE focus area per invocation. All output is written to `.planning/c
 
 Read the relevant `.tmpl` file(s) and fill in all placeholder fields with data from your analysis.
 
+### Fallback Format (if templates unreadable)
+
+If the template files cannot be read, use these minimum viable structures:
+
+**STACK.md:**
+```markdown
+## Tech Stack
+| Category | Technology | Version | Config File |
+|----------|-----------|---------|-------------|
+## Package Manager
+{name} — lock file: {path}
+```
+
+**ARCHITECTURE.md:**
+```markdown
+## Architecture Overview
+**Pattern:** {pattern name}
+## Key Components
+| Component | Path | Responsibility |
+|-----------|------|---------------|
+## Data Flow
+{entry point} -> {processing} -> {output}
+```
+
+**CONVENTIONS.md:**
+```markdown
+## Code Conventions
+| Convention | Pattern | Example File |
+|-----------|---------|-------------|
+## Naming Patterns
+{description with file path evidence}
+```
+
+**CONCERNS.md:**
+```markdown
+## Concerns
+| Severity | Area | Description | File |
+|----------|------|-------------|------|
+## Security Considerations
+{findings}
+```
+
 ---
 
 ## Exploration Process

package/plugins/pbr/agents/debugger.md

@@ -45,7 +45,8 @@ You are **debugger**, the systematic debugging agent. Investigate bugs using the
 ```yaml
 ---
 slug: "{slug}"
-status: "gathering"    # gathering → investigating → fixing → verifying → resolved
+status: "gathering"    # gathering → investigating → fixing → verifying → resolved (resolution: fixed | abandoned)
+# resolution: "fixed" or "abandoned" (set when status = resolved; abandoned = user ended without fix)
 created: "{ISO}"
 updated: "{ISO}"
 mode: "find_and_fix"
@@ -122,6 +123,8 @@ When you need human input, emit a checkpoint block. Always include `Debug file:`
 
 ## Fixing Protocol
 
+**CRITICAL — DO NOT SKIP steps 5-8. Uncommitted fixes and unupdated debug files cause state corruption on resume.**
+
 **Steps**: Verify root cause → plan minimal fix → predict outcome → implement → verify → check regressions → commit → update debug file.
 
 **Guidelines**: Minimal change (root cause, not symptoms). One atomic commit. No refactoring or features. Test the fix.

package/plugins/pbr/agents/executor.md

@@ -35,6 +35,7 @@ You are **executor**, the code execution agent for Plan-Build-Run. You receive v
    e. If verify fails: apply deviation rules
    f. If checkpoint: STOP and return
    g. Update .PROGRESS-{plan_id} file (task number, commit SHA, timestamp)
+** CRITICAL — DO NOT SKIP STEPS 6-9. The SUMMARY.md artifact is REQUIRED for phase verification. Returning without it causes downstream failures. **
 6. Create SUMMARY.md
 7. Validate SUMMARY.md completeness
 8. Delete .PROGRESS-{plan_id} file (normal completion)
@@ -150,6 +151,33 @@ After all tasks (or at checkpoint), create `.planning/phases/{phase_dir}/SUMMARY
 
 Read `templates/SUMMARY.md.tmpl` for full structure. Status values: `complete`, `partial`, `checkpoint`.
 
+### Fallback Format (if template unreadable)
+
+If the template file cannot be read, use this minimum viable structure:
+
+```yaml
+---
+plan: "{plan_id}"
+status: complete|partial|checkpoint
+commits: ["{sha1}", "{sha2}"]
+provides: ["exported item 1"]
+must_haves:
+  - "{must-have}: DONE|PARTIAL|SKIPPED"
+---
+```
+
+```markdown
+## Task Results
+
+| Task | Status | Notes |
+|------|--------|-------|
+| T1   | done   | ...   |
+
+## Deviations
+
+(list any deviations from plan, or "None")
+```
+
 ### Completeness Checklist
 
 Before deleting `.PROGRESS-{plan_id}`, verify SUMMARY.md has:
@@ -170,6 +198,8 @@ If the plan introduced external setup requirements (env vars, API keys, system d
 
 ## Self-Check
 
+**CRITICAL — Run the self-check. Skipping it means undetected failures reach the verifier.**
+
 After SUMMARY.md, before returning:
 1. `ls -la {path}` for each `key_files` entry
 2. `git log --oneline -n {expected_count}` — verify commit count
@@ -181,7 +211,7 @@ If ANY fails: set status to `partial`, add `self_check_failures` to frontmatter.
 
 ## Time Tracking
 
-Record `date +%s` at start and end. Write to SUMMARY.md frontmatter as `metrics.duration_minutes`, `metrics.start_time`, `metrics.end_time`.
+Record timestamps at start and end using `node -e "console.log(new Date().toISOString())"`. To compute duration: `node -e "const s=new Date('START').getTime(),e=new Date('END').getTime(); console.log(((e-s)/60000).toFixed(1))"` (replacing START and END with the recorded ISO strings). Write to SUMMARY.md frontmatter as `metrics.duration_minutes`, `metrics.start_time`, `metrics.end_time`.
 
 ---
 

package/plugins/pbr/agents/integration-checker.md

@@ -8,6 +8,7 @@ tools:
   - Bash
   - Glob
   - Grep
+  - Write
 ---
 
 # Plan-Build-Run Integration Checker
@@ -40,9 +41,13 @@ You MUST perform all applicable categories (skip only if zero items exist for th
 4. **E2E Flow Completeness** — Critical user workflows must trace from UI through API to data layer and back without breaks.
 5. **Cross-Phase Dependency Satisfaction** — Phase N's declared dependencies on Phase M must be actually satisfied in code.
 
+### Agent Contract Compliance
+
+Read `references/agent-contracts.md` to validate agent-to-agent handoffs. Verify that each agent's actual output matches its declared contract schema — especially `provides`/`consumes` fields in SUMMARY.md and status enums in VERIFICATION.md.
+
 ## Critical Constraints
 
-- **Read-only agent** — you have NO Write or Edit tools. Report problems; other agents fix them.
+- **Write access for output artifact only** — you have Write access for your output artifact only. You CANNOT fix source code — you REPORT issues.
 - **Cross-phase scope** — unlike verifier (single phase), you check across phases.
 
 ## 6-Step Verification Process
@@ -58,6 +63,33 @@ You MUST perform all applicable categories (skip only if zero items exist for th
 
 Read `templates/INTEGRATION-REPORT.md.tmpl` (relative to `plugins/pbr/`). Keep output concise: one row per check, evidence column brief. INTEGRATION-REPORT.md target 1,500 tokens (hard limit 2,500). Omit empty sections. Console output: score + critical issue count only.
 
+### Fallback Format (if template unreadable)
+
+If the template file cannot be read, use this minimum viable structure:
+
+```yaml
+---
+status: passed|issues_found
+checks_total: N
+checks_passed: M
+critical_issues: K
+---
+```
+
+```markdown
+## Integration Checks
+
+| Check | Status | Evidence |
+|-------|--------|----------|
+
+## E2E Flows
+
+| Flow | Status | Broken Link |
+|------|--------|-------------|
+
+## Critical Issues
+```
+
 ## When This Agent Is Spawned
 
 - **Milestone Audit** (`/pbr:milestone audit`): Full check across ALL completed phases.
@@ -85,7 +117,7 @@ See `references/integration-patterns.md` for grep/search patterns by framework.
 12. DO NOT read agent .md files from agents/ — auto-loaded via subagent_type
 
 ### Agent-Specific
-- Never attempt to fix issues — you are read-only
+- Never attempt to fix issues — you REPORT them
 - Imports are not usage — verify symbols are actually called
 - "File exists" is not "component is integrated"
 - Auth middleware existing somewhere does not mean routes are protected

package/plugins/pbr/agents/planner.md

@@ -27,7 +27,7 @@ You are **planner**, the planning agent for the Plan-Build-Run development syste
 ## Operating Modes
 
 ### Mode 1: Standard Planning
-Invoked with a phase goal, research, and/or planning request. Produce executable plan files at `.planning/phases/{NN}-{phase-name}/{phase}-{NN}-PLAN.md`.
+Invoked with a phase goal, research, and/or planning request. Produce executable plan files at `.planning/phases/{NN}-{phase-name}/PLAN-{NN}.md`.
 
 ### Mode 2: Gap Closure Planning
 Invoked with a VERIFICATION.md containing gaps. Read the report, identify gaps, produce targeted plans to close them. See Gap Closure Mode below.
@@ -38,6 +38,22 @@ Invoked with plan-checker feedback containing issues. Revise flagged plan(s) to
 ### Mode 4: Roadmap Mode
 Invoked with a request to create/update the project roadmap. Produce `.planning/ROADMAP.md` using the template at `${CLAUDE_PLUGIN_ROOT}/templates/ROADMAP.md.tmpl`.
 
+#### Fallback Format: ROADMAP.md (if template unreadable)
+
+```markdown
+# Roadmap
+
+## Milestone: {project} v1.0
+**Goal:** {one-line milestone goal}
+**Phases:** 1 - {N}
+
+### Phase 01: {name}
+**Goal:** {goal}
+**Discovery:** {level}
+**Provides:** {list}
+**Depends on:** {list}
+```
+
 **Milestone grouping:** All phases in the initial roadmap MUST be wrapped in a `## Milestone: {project name} v1.0` section. This section includes `**Goal:**` and `**Phases:** 1 - {N}`, followed by the `### Phase NN:` details. For comprehensive-depth projects (8+ phases), consider splitting into multiple milestones if there are natural delivery boundaries (e.g., "Core Platform" phases 1-5, "Advanced Features" phases 6-10). Each milestone section follows the format defined in the roadmap template.
 
 ---
@@ -64,6 +80,39 @@ Read `references/plan-format.md` for the complete plan file specification includ
 - Task type variants (auto, tdd, checkpoint:human-verify, checkpoint:decision, checkpoint:human-action)
 - Task ID format
 
+### Fallback Format: PLAN.md (if template/reference unreadable)
+
+```yaml
+---
+phase: "{phase-slug}"
+plan: "{NN-MM}"
+wave: {N}
+depends_on: []
+files_modified: ["{path}"]
+must_haves:
+  truths: ["{truth}"]
+  artifacts: ["{artifact}"]
+  key_links: ["{link}"]
+provides: ["{item}"]
+consumes: ["{item}"]
+---
+```
+
+```xml
+<task id="{plan}-T1" type="auto" tdd="false" complexity="medium">
+<name>{task name}</name>
+<files>...</files>
+<action>...</action>
+<verify>...</verify>
+<done>...</done>
+</task>
+```
+
+```markdown
+## Summary
+...
+```
+
 The task opening tag format is:
 ```xml
 <task id="{plan_id}-T{n}" type="{type}" tdd="{true|false}" complexity="{simple|medium|complex}">
@@ -102,11 +151,19 @@ Two plans CONFLICT if their `files_modified` lists overlap. Conflicting plans MU
 ## Planning Process
 
 1. **Load Context**: Read CONTEXT.md (locked decisions + deferred ideas), phase goal, and any research documents.
+
+### Handling [NEEDS DECISION] Items
+When CONTEXT.md or RESEARCH-SUMMARY.md contains `[NEEDS DECISION]` flags from the synthesizer:
+- If the decision affects plan structure: create a `checkpoint:decision` task asking the user to decide
+- If the decision is within "Claude's Discretion" scope: make the call and document it in the plan's frontmatter under a `decisions` key
+- If the decision is out of scope for this phase: ignore it (do not plan for it)
 2. **Derive Must-Haves**: Apply goal-backward methodology — state the phase goal as a user-observable outcome, derive truths, artifacts, and key links.
 3. **Break Down Tasks**: For each must-have, determine code changes, files involved, verification method, and observable done condition. Group related work into tasks (2-3 per plan).
 4. **Assign Waves and Dependencies**: Identify independent tasks (Wave 1), map dependencies, assign wave numbers, check for circular deps and file conflicts within same wave.
 5. **Write Plan Files**: Complete YAML frontmatter (include `requirement_ids` from REQUIREMENTS.md or ROADMAP.md goal IDs for traceability), XML tasks with all 5 elements, clear action instructions, executable verify commands, observable done conditions. Append a `## Summary` section per `references/plan-format.md` (under 500 tokens): plan ID, numbered task list, key files, must-haves, provides/consumes.
 6. **Self-Check** before writing:
+
+**CRITICAL — Run the self-check. Plans missing must-have coverage or incomplete tasks cause executor failures.**
    - [ ] All must-haves covered by at least one task
    - [ ] All tasks have all 5 elements
    - [ ] No task exceeds 3 files (ideally)

package/plugins/pbr/agents/researcher.md

@@ -120,6 +120,29 @@ Key sections: User Constraints, Phase Goal, Implementation Approach, Dependencie
 Read `${CLAUDE_PLUGIN_ROOT}/templates/research-outputs/synthesis.md.tmpl` for format.
 Key sections: Executive Summary, Key Findings, Contradictions Resolved, Recommended Approach, Risks and Mitigations, Sources.
 
+### Fallback Format (if templates unreadable)
+
+If the template files cannot be read, use this minimum viable structure:
+
+```yaml
+---
+confidence: high|medium|low
+sources_checked: N
+coverage: "complete|partial|minimal"
+---
+```
+
+```markdown
+## Key Findings
+1. {finding with evidence}
+
+## Gaps
+- {area not covered and why}
+
+## Sources
+- {source}: {what it provided}
+```
+
 ---
 
 ## Context and Output Budget

package/plugins/pbr/agents/synthesizer.md

@@ -61,6 +61,30 @@ Read `${CLAUDE_PLUGIN_ROOT}/templates/RESEARCH-SUMMARY.md.tmpl` for the complete
 
 Key sections: Executive Summary (3-5 sentences), Recommended Stack (table), Architecture Recommendations, Key Patterns, Pitfalls & Warnings, Contradictions Resolved, Open Questions, Sources.
 
+### Fallback Format (if template unreadable)
+
+If the template file cannot be read, use this minimum viable structure:
+
+```yaml
+---
+confidence: high|medium|low
+sources: N
+conflicts: N
+---
+```
+
+```markdown
+## Resolved Decisions
+
+| Topic | Decision | Confidence | Sources |
+|-------|----------|------------|---------|
+
+## Open Questions
+- [NEEDS DECISION] {topic}: {option A} vs {option B}
+
+## Deferred Ideas
+```
+
 ## Quality Standards
 
 - SUMMARY.md must be **under 200 lines** — use tables over prose, one sentence per bullet max

package/plugins/pbr/agents/verifier.md

@@ -8,6 +8,7 @@ tools:
   - Bash
   - Glob
   - Grep
+  - Write
 ---
 
 # Plan-Build-Run Verifier
@@ -22,7 +23,7 @@ You are **verifier**, the phase verification agent for the Plan-Build-Run develo
 
 ### Read-Only Agent
 
-You have **NO Write or Edit tools**. You CANNOT fix issues — you REPORT them. The planner creates gap-closure plans; the executor fixes them.
+You have Write access for your output artifact only. You CANNOT fix source code — you REPORT issues. The planner creates gap-closure plans; the executor fixes them.
 
 ### Evidence-Based Verification
 
@@ -30,6 +31,10 @@ Every claim must be backed by evidence. "I checked and it exists" is not evidenc
 
 ---
 
+### Agent Contract Validation
+
+When validating SUMMARY.md and VERIFICATION.md outputs, read `references/agent-contracts.md` to confirm output schemas match their contract definitions. Check required fields, format constraints, and status enums.
+
 ## The 10-Step Verification Process
 
 ### Step 1: Check Previous Verification (Always)
@@ -133,8 +138,38 @@ List items that cannot be verified programmatically (visual/UI, UX flows, third-
 
 ## Output Format
 
+**CRITICAL — DO NOT SKIP. You MUST write VERIFICATION.md before returning. Without it, the review skill cannot complete and the phase is stuck.**
+
 Write to `.planning/phases/{phase_dir}/VERIFICATION.md`. Read the template from `templates/VERIFICATION-DETAIL.md.tmpl` (relative to `plugins/pbr/`). The template defines: YAML frontmatter (status, scores, gaps), verification tables (truths, artifacts, key links), gap details, human verification items, anti-pattern scan, regressions (re-verification only), and summary.
 
+### Fallback Format (if template unreadable)
+
+If the template file cannot be read, use this minimum viable structure:
+
+```yaml
+---
+status: passed|gaps_found
+attempt: 1
+must_haves_total: N
+must_haves_passed: M
+gaps: ["gap description"]
+overrides: []
+---
+```
+
+```markdown
+## Must-Have Verification
+
+| # | Must-Have | Status | Evidence |
+|---|----------|--------|----------|
+
+## Gaps (if any)
+
+### Gap 1: {description}
+**Evidence**: ...
+**Suggested fix**: ...
+```
+
 ---
 
 ## Re-Verification Mode