@sienklogic/plan-build-run 2.9.1 → 2.11.0

package/plugins/cursor-pbr/references/pbr-tools-cli.md

@@ -0,0 +1,285 @@
+# pbr-tools.js CLI Reference
+
+Command-line interface for structured JSON operations on `.planning/` state.
+Skills and agents call this via Bash to avoid token-expensive text parsing.
+
+```
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js <command> [args]
+```
+
+All commands output JSON to stdout. Errors output JSON with an `error` field to stderr (exit code 1).
+
+---
+
+## State Commands
+
+### `state load`
+
+Returns full project state as a single JSON object.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load
+```
+
+**Output:**
+```json
+{
+  "exists": true,
+  "config": { ... },        // config.json contents
+  "state": {                 // STATE.md frontmatter + parsed body
+    "version": 2,
+    "current_phase": "1",
+    "status": "building",
+    "progress_percent": 45,
+    "last_activity": "2025-01-15",
+    "last_command": "/pbr:build",
+    "blockers": []
+  },
+  "roadmap": {               // Parsed ROADMAP.md
+    "phases": [{ "number": "01", "name": "...", "status": "planned", ... }]
+  },
+  "phase_count": 3,
+  "current_phase": "1",
+  "progress": { "phases": [...], "total_plans": 5, "completed_plans": 2, "percentage": 40 }
+}
+```
+
+### `state check-progress`
+
+Recalculates progress from filesystem (plan files, summaries, verification).
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state check-progress
+```
+
+**Output:**
+```json
+{
+  "phases": [
+    { "directory": "01-setup", "plans": 2, "summaries": 2, "completed": 2, "has_verification": true, "status": "verified" }
+  ],
+  "total_plans": 5,
+  "completed_plans": 3,
+  "percentage": 60
+}
+```
+
+### `state update <field> <value>`
+
+Atomically updates a single field in STATE.md. Uses file locking.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update current_phase 2
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update status building
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update last_activity now   # auto-timestamps
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update plans_complete 3
+```
+
+**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`
+
+**Output:** `{ "success": true, "field": "status", "value": "building" }`
+
+---
+
+## Config Commands
+
+### `config validate`
+
+Validates `config.json` against the JSON schema. Detects both schema violations and semantic conflicts.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config validate
+```
+
+**Output:**
+```json
+{
+  "valid": true,
+  "errors": [],
+  "warnings": ["features.auto_continue=true with mode=interactive: auto_continue only fires in autonomous mode"]
+}
+```
+
+### `config resolve-depth [dir]`
+
+Resolves the effective depth profile by merging base profile with user overrides.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth /path/to/.planning
+```
+
+**Output:** Full depth profile object with all resolved values (research rounds, plan detail level, verification depth, etc.)
+
+---
+
+## Plan & Phase Commands
+
+### `plan-index <phase>`
+
+Returns plan inventory for a phase, grouped by wave.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js plan-index 1
+```
+
+**Output:**
+```json
+{
+  "phase": "01-setup",
+  "total_plans": 3,
+  "plans": [
+    {
+      "file": "PLAN-01.md",
+      "plan_id": "01",
+      "wave": 1,
+      "type": "feature",
+      "autonomous": true,
+      "depends_on": [],
+      "gap_closure": false,
+      "has_summary": true,
+      "must_haves_count": 4
+    }
+  ],
+  "waves": { "wave_1": ["01", "02"], "wave_2": ["03"] }
+}
+```
+
+### `phase-info <phase>`
+
+Comprehensive single-phase status combining roadmap, filesystem, and plan data.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js phase-info 1
+```
+
+**Output:**
+```json
+{
+  "phase": "01-setup",
+  "name": "setup",
+  "goal": "Initialize project infrastructure",
+  "roadmap_status": "building",
+  "filesystem_status": "partial",
+  "plans": [...],
+  "plan_count": 3,
+  "summaries": [{ "file": "SUMMARY-01.md", "plan": "01", "status": "complete" }],
+  "completed": 1,
+  "verification": null,
+  "has_context": false
+}
+```
+
+### `must-haves <phase>`
+
+Collects all must-haves from phase plans — truths, artifacts, and key links.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js must-haves 1
+```
+
+**Output:**
+```json
+{
+  "phase": "01-setup",
+  "plans": {
+    "01": { "truths": ["..."], "artifacts": ["..."], "key_links": ["..."] }
+  },
+  "all": { "truths": [...], "artifacts": [...], "key_links": [...] },
+  "total": 12
+}
+```
+
+---
+
+## Frontmatter Command
+
+### `frontmatter <filepath>`
+
+Parses a markdown file's YAML frontmatter and returns as JSON.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js frontmatter .planning/phases/01-setup/PLAN-01.md
+```
+
+**Output:** The frontmatter fields as a JSON object. Returns `{ "error": "File not found: ..." }` if the file doesn't exist.
+
+---
+
+## Roadmap Commands
+
+### `roadmap update-status <phase> <status>`
+
+Updates the Status column for a phase in ROADMAP.md's Phase Overview table. Uses file locking. Warns on invalid status transitions but does not block them.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js roadmap update-status 1 building
+```
+
+**Valid statuses:** `pending`, `planned`, `building`, `built`, `partial`, `needs_fixes`, `verified`, `skipped`
+
+**Output:** `{ "success": true, "old_status": "planned", "new_status": "building" }`
+
+### `roadmap update-plans <phase> <complete> <total>`
+
+Updates the Plans column (e.g., "2/5") for a phase in ROADMAP.md.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js roadmap update-plans 1 2 5
+```
+
+**Output:** `{ "success": true, "old_plans": "1/5", "new_plans": "2/5" }`
+
+---
+
+## History Commands
+
+### `history append <type> <title> [body]`
+
+Appends a record to HISTORY.md. Creates the file if it doesn't exist.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append milestone "v1.0 Release" "Initial release with core features"
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append phase "01-setup Complete" "3 plans executed, all verified"
+```
+
+**Types:** `milestone`, `phase`
+
+**Output:** `{ "success": true }`
+
+### `history load`
+
+Loads all HISTORY.md records as structured JSON.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history load
+```
+
+**Output:**
+```json
+{
+  "records": [
+    { "type": "milestone", "title": "v1.0 Release", "date": "2025-01-15", "body": "..." }
+  ],
+  "line_count": 42
+}
+```
+
+Returns `null` if HISTORY.md doesn't exist.
+
+---
+
+## Event Command
+
+### `event <category> <event> [JSON-details]`
+
+Logs a structured event to `.planning/logs/events.jsonl`.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event build plan-complete '{"plan":"01","phase":"01-setup"}'
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event error hook-failure '{"script":"validate-task.js"}'
+```
+
+**Output:** `{ "logged": true, "category": "build", "event": "plan-complete" }`
+
+If the JSON-details argument is not valid JSON, it's stored as `{ "raw": "<the string>" }`.

package/plugins/cursor-pbr/references/ui-formatting.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/ui-formatting.md -->
 # Plan-Build-Run UI Brand & Formatting Reference
 
 Consistent output formatting for all Plan-Build-Run skills. Every skill that produces user-facing output should follow these patterns.
@@ -8,9 +7,9 @@ Consistent output formatting for all Plan-Build-Run skills. Every skill that pro
 Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► {STAGE NAME}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► {STAGE NAME}                              ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 **Stage names (uppercase):**
@@ -22,7 +21,7 @@ Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
 - `EXECUTING WAVE {N}`
 - `VERIFYING`
 - `PHASE {N} COMPLETE ✓`
-- `MILESTONE COMPLETE 🎉`
+- `MILESTONE COMPLETE`
 - `SCANNING CODEBASE`
 - `DEBUGGING`
 
@@ -34,9 +33,9 @@ Use for major workflow transitions. Always use `PLAN-BUILD-RUN` prefix.
 
 Format:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► {SKILL NAME}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► {SKILL NAME}                              ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 **Skill names (uppercase):**
@@ -156,7 +155,7 @@ For research agents:
 
 ## Checkpoint Boxes
 
-User action required. Use double-line box drawing, 62-character width.
+User action required. Use double-line box drawing, 62-character inner width.
 
 ```
 ╔══════════════════════════════════════════════════════════════╗
@@ -165,9 +164,7 @@ User action required. Use double-line box drawing, 62-character width.
 
 {Content}
 
-──────────────────────────────────────────────────────────────
 → {ACTION PROMPT}
-──────────────────────────────────────────────────────────────
 ```
 
 **Types:**
@@ -261,25 +258,21 @@ Use plain conversational prompts for these cases instead.
 Always present at end of major completions (phase complete, milestone complete, project init).
 
 ```
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{Identifier}: {Name}** — {one-line description}
 
 `{copy-paste command}`
 
 <sub>`/clear` first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
+```
 
 **Also available:**
 - `/pbr:alternative-1` — description
 - `/pbr:alternative-2` — description
 
-───────────────────────────────────────────────────────────────
-```
-
 **Shorter routing (for minor completions):**
 ```
 What's next?
@@ -334,18 +327,18 @@ Use tables for structured data:
 ### Phase Complete
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} COMPLETE ✓                      ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {Name}**
 
 {X} plans executed
 Goal verified ✓
 
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N+1}: {Name}** — {Goal from ROADMAP.md}
 
@@ -353,30 +346,26 @@ Goal verified ✓
 
 <sub>/clear first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
 - /pbr:plan {N+1} — skip discussion, plan directly
 - /pbr:review {N} — manual acceptance testing before continuing
-
-───────────────────────────────────────────────────────────────
 ```
 
 ### Milestone Complete
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► MILESTONE COMPLETE 🎉
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► MILESTONE COMPLETE                         ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{version}**
 
 {N} phases completed
 All phase goals verified ✓
 
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Audit milestone** — verify requirements, cross-phase integration, E2E flows
 
@@ -384,21 +373,17 @@ All phase goals verified ✓
 
 <sub>/clear first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
 - /pbr:review — manual acceptance testing
-- /pbr:milestone complete — skip audit, archive directly
-
-───────────────────────────────────────────────────────────────
+- /pbr:milestone complete — archive milestone after audit passes
 ```
 
 ### Gaps Found
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PHASE {N} GAPS FOUND ⚠                    ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Phase {N}: {Name}**
 
@@ -409,9 +394,9 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
 
 {Extract gap summaries from VERIFICATION.md}
 
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
 
 **Plan gap closure** — create additional plans to complete the phase
 
@@ -419,13 +404,9 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
 
 <sub>/clear first → fresh context window</sub>
 
-───────────────────────────────────────────────────────────────
-
 **Also available:**
 - cat .planning/phases/{phase_dir}/VERIFICATION.md — see full report
 - /pbr:review {N} — manual testing before planning
-
-───────────────────────────────────────────────────────────────
 ```
 
 ---
@@ -435,9 +416,9 @@ Report: .planning/phases/{phase_dir}/VERIFICATION.md
 Use for session lifecycle transitions (pause/resume):
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► SESSION RESTORED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SESSION RESTORED ✓                         ║
+╚══════════════════════════════════════════════════════════════╝
 
 Position: Phase {N} — {phase name}, Plan {M}
 Paused: {ISO datetime}
@@ -453,10 +434,11 @@ Other session banners: `SESSION SAVED ✓` (pause), `RESUMING SESSION` (resume s
 ## Anti-Patterns
 
 Do NOT:
-- Use varying box/banner widths
-- Mix banner styles (`===`, `---`, `***`) with `━━━` banners
+- Use varying box/banner widths — always 62-character inner width
+- Use `━━━` heavy bars or `───` thin dividers for banners/sections — use `╔═╗║╚═╝` boxes
+- Mix banner styles (`===`, `---`, `***`) with double-line boxes
 - Skip `PLAN-BUILD-RUN ►` prefix in stage banners
-- Use random emoji (only `🎉` for milestone complete, `✓` for phase complete)
+- Use random emoji (only for milestone complete, `✓` for phase complete)
 - Skip the "Next Up" block after major completions
 - Reference non-Plan-Build-Run commands (always use `/pbr:*` commands)
 - Use non-Plan-Build-Run branding in banners

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

@@ -20,9 +20,9 @@ Additionally for this skill:
 **Before ANY tool calls**, display this banner:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► STARTING PROJECT
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► STARTING PROJECT                           ║
+╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
@@ -165,6 +165,8 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
 
 **After gathering preferences:**
 
+**CRITICAL: You MUST create the .planning/ directory and write config.json NOW. Do not proceed without this.**
+
 1. Read the config template from `skills/begin/templates/config.json.tmpl`
 2. Apply the user's choices to the template
 3. Create `.planning/` directory
@@ -172,6 +174,8 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
 
 **IMPORTANT**: This step MUST happen BEFORE research (Step 5) because depth controls how many researchers to spawn.
 
+**CRITICAL: Write .active-skill NOW.** Write the text "begin" to `.planning/.active-skill` using the Write tool. Verify the file exists before proceeding.
+
 ---
 
 ### Step 4: Research Decision (inline)
@@ -206,7 +210,7 @@ Use the **yes-no** pattern from `skills/shared/gate-prompts.md`:
 
 Spawn parallel agents for research. Each researcher writes to `.planning/research/`.
 
-**Create `.planning/research/` directory first.**
+**CRITICAL: Create .planning/research/ directory NOW before spawning researchers. Do NOT skip this step.**
 
 **For each research topic, invoke the @researcher agent:**
 
@@ -324,6 +328,9 @@ Each requirement must be:
 - **Specific** — not vague ("fast" is bad, "page loads in <2s" is good)
 
 **7e. Write REQUIREMENTS.md:**
+
+**CRITICAL: Write REQUIREMENTS.md NOW. The roadmap planner depends on this file.**
+
 Read the template from `skills/begin/templates/REQUIREMENTS.md.tmpl` and write `.planning/REQUIREMENTS.md` with:
 - All v1 requirements grouped by category
 - All v2 requirements with deferral reasons
@@ -374,6 +381,10 @@ Read `skills/begin/templates/roadmap-prompt.md.tmpl` for the prompt structure.
 
 Write the project state files from templates:
 
+**CRITICAL: You MUST write all 5 state initialization files (Steps 9a-9e). Do NOT skip any.**
+
+**CRITICAL: Write PROJECT.md NOW. Do NOT skip this step.**
+
 **9a. Write PROJECT.md:**
 1. Read `skills/begin/templates/PROJECT.md.tmpl`
 2. Fill in:
@@ -386,6 +397,8 @@ Write the project state files from templates:
 3. Write to `.planning/PROJECT.md`
 4. Ensure the `## Milestones` section is filled in with the project name and phase count from the roadmap
 
+**CRITICAL: Write STATE.md NOW. Do NOT skip this step.**
+
 **9b. Write STATE.md:**
 1. Read `skills/begin/templates/STATE.md.tmpl`
 2. Fill in:
@@ -398,6 +411,8 @@ Write the project state files from templates:
 4. Fill in the `## Milestone` section with the project name and total phase count
 5. **STATE.md size limit**: Follow size limit enforcement rules in `skills/shared/state-update.md` (150 lines max).
 
+**CRITICAL: Write CONTEXT.md NOW. Do NOT skip this step.**
+
 **9c. Write CONTEXT.md:**
 Create `.planning/CONTEXT.md` from information gathered during questioning:
 
@@ -422,6 +437,8 @@ Create `.planning/CONTEXT.md` from information gathered during questioning:
 | {feature} | {reason} |
 ```
 
+**CRITICAL: Write HISTORY.md NOW. Do NOT skip this step.**
+
 **9d. Write HISTORY.md:**
 Create `.planning/HISTORY.md` with an initial entry:
 
@@ -435,6 +452,8 @@ Create `.planning/HISTORY.md` with an initial entry:
 - Roadmap: {N} phases planned
 ```
 
+**CRITICAL: Create phase directories NOW. Do NOT skip this step.**
+
 **9e. Create phase directories:**
 For each phase in the roadmap, create the directory structure:
 ```
@@ -478,6 +497,10 @@ If `gates.confirm_project` is true in config:
 
 ---
 
+## Cleanup
+
+Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.
+
 ## Completion
 
 After all steps complete, present the final summary:
@@ -485,9 +508,9 @@ After all steps complete, present the final summary:
 Use the branded stage banner from `references/ui-formatting.md`:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► PROJECT INITIALIZED
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PROJECT INITIALIZED                        ║
+╚══════════════════════════════════════════════════════════════╝
 
 **{name}**