@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/cursor-pbr/references/model-profiles.md

@@ -1,100 +0,0 @@
-<!-- canonical: ../../pbr/references/model-profiles.md -->
-# Model Profiles Reference
-
-How Plan-Build-Run maps agents to models and how to configure model selection.
-
----
-
-## Agent-to-Model Mapping
-
-Each Plan-Build-Run agent has a default model specified in its agent definition frontmatter (`model:` field). These defaults are overridden by the `models` section of `config.json`.
-
-### Default Agent Models
-
-| Agent | Default Model | Rationale |
-|-------|---------------|-----------|
-| `researcher` | `sonnet` | Research requires strong reasoning for source evaluation and synthesis |
-| `planner` | `inherit` | Planning is complex; inherits the session's primary model |
-| `executor` | `inherit` | Execution needs the full capability of the session model |
-| `verifier` | `sonnet` | Verification needs solid reasoning but not the heaviest model |
-| `integration-checker` | `sonnet` | Cross-phase analysis requires strong pattern matching |
-| `plan-checker` | `sonnet` | Plan quality analysis needs good analytical capability |
-| `debugger` | `inherit` | Debugging is complex; inherits session model |
-| `codebase-mapper` | `sonnet` | Codebase analysis requires thorough reasoning |
-| `synthesizer` | `haiku` | Synthesis is mechanical combination; speed over depth |
-| `general` | `inherit` | Lightweight utility; inherits session model |
-
-The `inherit` value means the agent uses whatever model the parent session is running (typically the user's configured Claude model).
-
----
-
-## Model Profile Presets
-
-The `/pbr:config model-profile {preset}` command sets all agent models at once using a preset:
-
-| Profile | Researcher | Planner | Executor | Verifier | Int-Checker | Debugger | Mapper | Synthesizer |
-|---------|-----------|---------|----------|----------|-------------|----------|--------|-------------|
-| `quality` | opus | opus | opus | opus | sonnet | opus | sonnet | sonnet |
-| `balanced` | sonnet | inherit | inherit | sonnet | sonnet | inherit | sonnet | haiku |
-| `budget` | haiku | haiku | haiku | haiku | haiku | haiku | haiku | haiku |
-| `adaptive` | sonnet | sonnet | inherit | sonnet | haiku | inherit | haiku | haiku |
-
-### Preset Descriptions
-
-- **quality**: Maximum capability across all agents. Best results but highest token cost. Use for critical projects or complex architectures.
-- **balanced**: The default preset. Front-loads intelligence in research and verification, inherits session model for planning and execution. Good general-purpose choice.
-- **budget**: All agents use haiku. Fastest and cheapest, but reduced quality for complex reasoning tasks. Suitable for well-defined, mechanical work.
-- **adaptive**: Front-loads intelligence in research and planning (where decisions matter most), uses lighter models for mechanical execution and verification. Good cost-quality tradeoff.
-
----
-
-## Configuring Models
-
-### Per-Agent Configuration
-
-Set an individual agent's model via `/pbr:config`:
-
-```
-/pbr:config model executor sonnet
-/pbr:config model verifier opus
-```
-
-Or edit `config.json` directly:
-
-```json
-{
-  "models": {
-    "researcher": "sonnet",
-    "planner": "inherit",
-    "executor": "inherit",
-    "verifier": "sonnet",
-    "integration_checker": "sonnet",
-    "debugger": "inherit",
-    "mapper": "sonnet",
-    "synthesizer": "haiku"
-  }
-}
-```
-
-### Valid Model Values
-
-| Value | Meaning |
-|-------|---------|
-| `sonnet` | Claude Sonnet (4.5/4.6) -- balanced speed and capability |
-| `opus` | Claude Opus (4.6) -- highest capability, slower |
-| `haiku` | Claude Haiku (4.5) -- fastest, lower capability |
-| `inherit` | Use the session's primary model (whatever the user is running) |
-
-Note: Claude Code 2.1.45+ supports Sonnet 4.6. Model values are abstract names — Claude Code resolves them to the latest available version.
-
----
-
-## Model Selection in Skill Orchestration
-
-Skills that spawn subagents use the `model` parameter in `Task()` calls. Some skills hardcode a lighter model for specific tasks:
-
-- **Build skill**: Spawns inline verifiers with `model: "haiku"` for quick spot-checks
-- **Build skill**: Spawns codebase mapper updates with `model: "haiku"` for incremental map refreshes
-- **Plan skill**: Uses the configured `planner` model for main planning work
-
-The `subagent_type` parameter automatically loads the agent definition, and the model from `config.json` takes precedence over the agent's default `model:` frontmatter field.

package/plugins/cursor-pbr/references/model-selection.md

@@ -1,32 +0,0 @@
-<!-- canonical: ../../pbr/references/model-selection.md -->
-# Model Selection Reference
-
-Plan-Build-Run uses adaptive model selection to balance cost and capability.
-
-## How It Works
-
-1. The planner annotates each task with `complexity="simple|medium|complex"`
-2. The build skill maps complexity to a model via `config.models.complexity_map`
-3. The executor agent is spawned with the selected model
-
-## Default Mapping
-
-| Complexity | Model | Rationale |
-|-----------|-------|-----------|
-| simple | haiku | Fast, cheap — sufficient for mechanical changes |
-| medium | sonnet | Good balance for standard feature work |
-| complex | inherit | Uses session model — typically Opus for critical work |
-
-## Override Mechanisms
-
-1. **Per-task override**: Add `model="sonnet"` attribute to task XML in PLAN.md
-2. **Config override**: Set `models.complexity_map` in config.json to change defaults
-3. **Agent-level override**: Set `models.executor` in config.json to force a single model for all executor spawns (disables adaptive selection)
-
-## Heuristics
-
-The planner uses these signals to determine complexity:
-- File count and types
-- Task name keywords
-- Dependency count
-- Whether the task introduces new patterns vs. follows established ones

package/plugins/cursor-pbr/references/pbr-rules.md

@@ -1,195 +0,0 @@
-<!-- canonical: ../../pbr/references/pbr-rules.md -->
-# Plan-Build-Run Rules
-
-Authoritative rules for all Plan-Build-Run skills, agents, hooks, and workflows.
-Condensed from the 3,100-line `docs/DEVELOPMENT-GUIDE.md`. When in doubt, these rules govern.
-
----
-
-## Philosophy
-
-1. **Context is precious.** The orchestrator stays lean (~15% usage). Delegate heavy work to subagents.
-2. **State lives on disk.** Skills and agents communicate through `.planning/` files, not messages.
-3. **Agents are black boxes.** Clear input/output contracts. Agents never read other agent definitions.
-4. **Gates provide safety.** Users control pace via config toggles. Never skip a gate.
-5. **One task, one commit.** Atomic commits for clean history and easy rollback.
-6. **Cross-platform always.** `path.join()`, CommonJS, test on Windows/macOS/Linux.
-7. **Test everything.** 70% coverage minimum. All 9 CI matrix combinations must pass.
-8. **PLAN-BUILD-RUN branding only.** Always use `PLAN-BUILD-RUN ►` prefix in banners.
-
----
-
-## Context Budget
-
-9. Target 15% orchestrator context usage. Warn user at 30%.
-10. **Never** read agent definitions (`agents/*.md`) in the orchestrator — `subagent_type` auto-loads them.
-11. **Never** inline large files into `Task()` prompts — tell agents to read files from disk.
-12. **Never** read full subagent output — read frontmatter only (first 10-20 lines).
-13. Read STATE.md and config.json fully. Read ROADMAP.md by section. Read PLAN.md/SUMMARY.md/VERIFICATION.md frontmatter only.
-14. Use the `limit` parameter on Read to restrict line counts.
-15. Proactively suggest `/pbr:pause` when context gets heavy — before compaction, not after.
-15b. **After compaction or context recovery**, always read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
-
----
-
-## State Management
-
-16. STATE.md is the **single source of truth** for current position.
-17. **Never** infer current phase from directory listings, git log, or conversation history.
-18. Always read STATE.md before making state-dependent decisions.
-19. Update STATE.md at: begin, plan, build, review, pause, continue, milestone.
-20. **Never** commit STATE.md mid-skill — hooks handle session persistence.
-21. Agents write artifacts (SUMMARY.md, VERIFICATION.md). Only the orchestrator writes STATE.md.
-22. Every ROADMAP.md phase must have a matching `.planning/phases/` directory, and vice versa.
-23. config.json is validated against `scripts/config-schema.json` on load.
-
----
-
-## Agent Spawning
-
-24. Always use `subagent_type: "pbr:{name}"` to spawn agents.
-25. Pass file paths to agents, not file contents.
-26. Agents never read other agent definition files.
-27. Each agent gets a fresh 200k token context window — let them do the heavy reading.
-
----
-
-## User Interaction Patterns
-
-28. Use `AskUserQuestion` for all structured gate checks — never plain-text "Type approved" prompts.
-29. AskUserQuestion is an orchestrator-only tool. It **cannot** be called from subagents (Task contexts).
-30. Max 4 options per AskUserQuestion call. If more options exist, split into a 2-step flow.
-31. `header` field must be max 12 characters. Keep it a single word when possible.
-32. `multiSelect` is always `false` for Plan-Build-Run gate checks.
-33. Always handle the "Other" case — users may type freeform text instead of selecting an option.
-34. Reuse patterns from `skills/shared/gate-prompts.md` by name. Do not reinvent prompts inline.
-35. Do **not** use AskUserQuestion for freeform text input (symptom gathering, Socratic discussion, open-ended questions). Use plain conversation for those.
-36. Skills that do not require user interaction (continue, health, help, pause) intentionally omit AskUserQuestion from allowed-tools.
-
----
-
-## Skill Authoring
-
-37. Every SKILL.md starts with YAML frontmatter: `name`, `description`, `allowed-tools`, `argument-hint`.
-38. Skills that spawn agents **must** have a `## Context Budget` section.
-39. Mark each step as `(inline)` or `(delegate)` — inline for light work, delegate for analysis.
-40. Reference templates and references by filename — never inline them.
-41. Gate checks: read config toggle → display summary → ask user → proceed/abort/revise.
-42. Use branded UI elements from `references/ui-formatting.md`.
-
----
-
-## Agent Authoring
-
-43. Every agent file starts with YAML frontmatter: `name`, `description`, `model`, `memory`, `tools`.
-44. Agent name matches the agent file name (no prefix needed).
-45. `tools` array: only include tools the agent actually uses.
-46. Agents write artifacts to disk. They never modify STATE.md or ROADMAP.md.
-47. Agent definitions are self-contained — no cross-agent references.
-
----
-
-## Hook Development
-
-48. All hooks use **CommonJS** (`require`), never ES modules (`import`).
-49. All hooks call `logHook()` from `hook-logger.js`. No silent exits.
-50. Exit codes: `0` = allow/success, `2` = block (PreToolUse only), other = error (logged, non-blocking).
-51. Hooks receive JSON on stdin, write JSON to stdout.
-52. Fail gracefully: wrap in try/catch, exit 0 on parse errors.
-53. Every hook in `hooks.json` must have a `statusMessage` field (gerund form: "Validating...", keep short).
-54. Windows file deletion: use 3-attempt retry loop to handle AV/indexer locks.
-55. Every hook script must have a corresponding `tests/{name}.test.js`.
-
----
-
-## Commits
-
-56. Format: `{type}({scope}): {description}`.
-57. Valid types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `wip`.
-58. Valid scopes: `{NN}-{MM}` (phase-plan), `quick-{NNN}`, `planning`, or any lowercase word.
-59. **Never** use `git add .` or `git add -A` — stage specific files only.
-60. Blocked files: `.env` (not `.env.example`), `*.key`, `*.pem`, `*.pfx`, `*.p12`, `*credential*`, `*secret*` (unless in `tests/` or `*.example`).
-61. TDD tasks: exactly 3 commits — RED (test), GREEN (feat), REFACTOR.
-62. Executors: one atomic commit per task.
-
----
-
-## Templates
-
-63. Default syntax: `{variable}` placeholders for string substitution.
-64. Only use EJS (`<%= %>`, `<% %>`) when loops or conditionals are genuinely needed.
-65. Template files use `.tmpl` extension. Name matches the output file (e.g., `SUMMARY.md.tmpl` → `SUMMARY.md`).
-66. Templates live in `templates/` (global), `templates/codebase/` (scan), `templates/research/` (research), or `skills/{name}/templates/` (skill-specific).
-
----
-
-## File Naming
-
-67. Skills: `plugins/pbr/skills/{skill-name}/SKILL.md` — lowercase hyphenated dir, uppercase `SKILL.md`.
-68. Agents: `plugins/pbr/agents/{name}.md` — agent name matches file name.
-69. Scripts: `plugins/pbr/scripts/{name}.js` — lowercase, hyphenated, CommonJS.
-70. References: `plugins/pbr/references/{name}.md` — lowercase, hyphenated.
-71. Tests: `tests/{script-name}.test.js` — mirrors the script name.
-
----
-
-## Testing
-
-72. Test files mirror script names: `scripts/foo.js` → `tests/foo.test.js`.
-73. Use the fixture project at `tests/fixtures/fake-project/` for integration tests.
-74. Hook tests: use stdin/stdout protocol with `execSync()`, timeout 5000ms, run in temp dir.
-75. Coverage target: 70% branches/functions/lines/statements.
-76. CI matrix: Node 18/20/22 × ubuntu/macos/windows. All 9 must pass.
-77. Local pre-push: `npm run lint && npm test && npm run validate`.
-
----
-
-## Cross-Platform
-
-78. **Never** hardcode `/` or `\` — always `path.join()`.
-79. Use `\n` in string literals — Node.js and Git normalize line endings.
-80. In `hooks.json`, use `${CLAUDE_PLUGIN_ROOT}` — Claude Code expands this internally on all platforms.
-81. **Never** use `$CLAUDE_PLUGIN_ROOT` (shell expansion is platform-dependent).
-82. **Never** rely on execute bits — always invoke via `node script.js`.
-
----
-
-## Dependencies & Gates
-
-83. Check all `depends_on` plans have SUMMARY.md files before executing.
-84. Checkpoint tasks (`checkpoint:human-verify`) require STOP — write partial SUMMARY.md, return metadata.
-85. Respect all `gates.confirm_*` config toggles. Never auto-proceed when a gate is enabled.
-
----
-
-## Logging
-
-86. Hook scripts → `logHook()` (writes to `logs/hooks.jsonl`, max 200 entries).
-87. Workflow milestones → `logEvent()` (writes to `logs/events.jsonl`, max 1,000 entries).
-88. Rule of thumb: inside a hook? `logHook()`. Tracking a high-level event? `logEvent()`.
-
----
-
-## Gotchas
-
-89. JSDoc `*/` in glob patterns closes Babel comments early — use `//` line comments instead.
-90. Regex anchors: use `\b` word boundaries, not `^` anchors (misses chained commands like `cd && git commit`).
-91. Windows cwd locking in tests: use `cwd` option in `execSync()` instead of `process.chdir()`.
-92. PLAN.md frontmatter must include all required fields: `phase`, `plan`, `type`, `wave`, `depends_on`, `files_modified`, `autonomous`, `must_haves`.
-
----
-
-## Quick Reference: Never Do This
-
-| # | Anti-Pattern | Impact |
-|---|-------------|--------|
-| 1 | Read agent definitions in orchestrator | Context balloons 15% → 88% |
-| 2 | Inline large files into Task() prompts | Wasted orchestrator context |
-| 3 | Read full subagent output | Context bloat |
-| 4 | Use non-Plan-Build-Run branding | User confusion |
-| 5 | Hardcode path separators | Cross-platform breakage |
-| 6 | Use ES modules in hooks | Hook fails to load |
-| 7 | Skip hook logging | Silent failures |
-| 8 | Modify STATE.md in agents | Race conditions, corruption |
-| 9 | Use `git add .` | Sensitive data leaks |
-| 10 | Skip tests for new scripts | CI failures, regressions |

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

@@ -1,285 +0,0 @@
-# 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>" }`.