@sienklogic/plan-build-run 2.12.0 → 2.12.1

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

@@ -1,194 +0,0 @@
-# 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/pbr/references/planning-config.md

@@ -1,213 +0,0 @@
-# Planning Config Reference
-
-Schema, fields, defaults, and behavioral effects of Plan-Build-Run's `config.json`.
-
----
-
-## Overview
-
-Plan-Build-Run's configuration lives at `.planning/config.json` in the project root. It is created by `/pbr:begin` and can be modified via `/pbr:config` or by editing the file directly. The config controls workflow behavior, model selection, parallelization, git integration, and confirmation gates.
-
----
-
-## Schema Version
-
-```json
-{ "version": 2 }
-```
-
-The `version` field tracks schema migrations. Current version is `2`. When loading a config with an older version, Plan-Build-Run runs automatic migration (e.g., v1 to v2 adds missing fields with defaults, renames `model_profile` to per-agent `models` object).
-
----
-
-## Top-Level Fields
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `version` | number | `2` | Config schema version |
-| `context_strategy` | string | `"aggressive"` | Context budget strategy: `aggressive`, `balanced`, `minimal` |
-| `mode` | string | `"interactive"` | Workflow mode: `interactive` |
-| `depth` | string | `"standard"` | Research/planning depth: `quick`, `standard`, `comprehensive` |
-
-### depth
-
-Controls how thorough research and planning phases are:
-
-| Value | Behavior |
-|-------|----------|
-| `quick` | Minimal research, smaller plans, faster execution |
-| `standard` | Balanced research depth, standard plan detail |
-| `comprehensive` | Deep research with multiple sources, detailed plans with more tasks |
-
-### context_strategy
-
-Controls how aggressively Plan-Build-Run manages context budget:
-
-| Value | Behavior |
-|-------|----------|
-| `aggressive` | Proactive compaction warnings, strict context isolation, minimal file reads in main context |
-| `balanced` | Moderate context management with some inline reads |
-| `minimal` | Relaxed context management, more inline content allowed |
-
----
-
-## features
-
-Boolean toggles that enable or disable specific workflow capabilities.
-
-| Field | Default | Description |
-|-------|---------|-------------|
-| `structured_planning` | `true` | Use phased planning with ROADMAP and plan files |
-| `goal_verification` | `true` | Run verifier agent after builds to check goals are met |
-| `integration_verification` | `true` | Run cross-phase integration checks |
-| `context_isolation` | `true` | Isolate work into subagents to protect main context |
-| `atomic_commits` | `true` | Require one commit per task (vs. batched commits) |
-| `session_persistence` | `true` | Persist state across sessions via STATE.md |
-| `research_phase` | `true` | Run research before planning |
-| `plan_checking` | `true` | Run plan-checker agent before execution |
-| `tdd_mode` | `false` | Enable Test-Driven Development for all tasks (Red-Green-Refactor) |
-| `status_line` | `true` | Show status line in session UI |
-| `auto_continue` | `false` | Write `.auto-next` signal on phase completion for automatic continuation |
-| `auto_advance` | `false` | Chain build→review→plan automatically in autonomous mode (requires `mode: autonomous`) |
-| `team_discussions` | `false` | Enable team-based discussion workflows (never used for execution) |
-| `inline_verify` | `false` | Run per-task verification after each executor commit (opt-in, adds latency) |
-
-### Notable interactions
-
-- `goal_verification: false` skips the post-build verification step. The build skill appends a note suggesting `/pbr:review` manually.
-- `tdd_mode: true` causes all task types to follow Red-Green-Refactor, producing 3 commits per task instead of 1.
-- `auto_continue: true` writes a `.planning/.auto-next` file containing the next command (e.g., `/pbr:plan 4`), allowing wrapper scripts to chain phases.
-- `auto_advance: true` + `mode: autonomous` enables full phase cycling: build completes → auto-invoke review → if verification passes → auto-invoke plan for next phase. Hard stops at: checkpoints, verification gaps, errors, milestone boundaries.
-- `inline_verify: true` spawns a haiku-model verifier after each plan completes within a wave. Adds ~10-20s latency per plan but catches issues before dependent plans run.
-
----
-
-## models
-
-Per-agent model selection. See `references/model-profiles.md` for full details.
-
-```json
-{
-  "models": {
-    "researcher": "sonnet",
-    "planner": "inherit",
-    "executor": "inherit",
-    "verifier": "sonnet",
-    "integration_checker": "sonnet",
-    "debugger": "inherit",
-    "mapper": "sonnet",
-    "synthesizer": "haiku"
-  }
-}
-```
-
-Valid values: `sonnet`, `opus`, `haiku`, `inherit`.
-
----
-
-## parallelization
-
-Controls whether and how plans execute concurrently.
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `enabled` | boolean | `true` | Enable parallel plan execution within a wave |
-| `plan_level` | boolean | `true` | Parallelize at plan level (multiple plans in same wave) |
-| `task_level` | boolean | `false` | Parallelize at task level within a plan (not currently used) |
-| `max_concurrent_agents` | number | `3` | Maximum simultaneous executor subagents |
-| `min_plans_for_parallel` | number | `2` | Minimum plans in a wave to trigger parallel execution |
-| `use_teams` | boolean | `false` | Use Agent Teams for coordination (discussion only, never execution) |
-
-### Behavior
-
-When `enabled: true` and a wave has >= `min_plans_for_parallel` plans, the build orchestrator spawns up to `max_concurrent_agents` executor Task() calls in parallel using `run_in_background: true`.
-
-When `enabled: false` or a wave has only 1 plan, executors run sequentially.
-
-Git lock conflicts can occur with parallel execution. Executors handle this with retry logic (wait 2s, max 3 attempts). If conflicts persist, reduce `max_concurrent_agents` to 1.
-
----
-
-## planning
-
-Controls planning behavior and documentation.
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `commit_docs` | boolean | `true` | Commit planning docs (SUMMARY, VERIFICATION) after builds |
-| `max_tasks_per_plan` | number | `3` | Maximum tasks per plan (keeps plans focused and atomic) |
-| `search_gitignored` | boolean | `false` | Include gitignored files in codebase scanning |
-
-### commit_docs
-
-When `true`, after all plans in a phase complete, the build orchestrator stages and commits planning artifacts:
-```
-docs({phase}): add build summaries and verification
-```
-
-When `false`, planning docs remain unstaged/uncommitted.
-
----
-
-## git
-
-Controls git integration and branching.
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `branching` | string | `"none"` | Branching strategy: `none`, `phase`, `milestone`, `disabled` |
-| `commit_format` | string | `"{type}({phase}-{plan}): {description}"` | Commit message template |
-| `phase_branch_template` | string | `"plan-build-run/phase-{phase}-{slug}"` | Phase branch naming |
-| `milestone_branch_template` | string | `"plan-build-run/{milestone}-{slug}"` | Milestone branch naming |
-| `mode` | string | `"enabled"` | Git mode: `enabled` or `disabled` |
-
-See `references/git-integration.md` for full branching strategy details.
-
-### mode: disabled
-
-When `git.mode` is `"disabled"`, no git commands are run at all -- no commits, no branching, no hook validation. Useful for prototyping or non-git projects.
-
----
-
-## gates
-
-Confirmation gates that pause execution to ask the user before proceeding.
-
-| Field | Default | When Triggered |
-|-------|---------|----------------|
-| `confirm_project` | `true` | Before creating a new Plan-Build-Run project (`/pbr:begin`) |
-| `confirm_roadmap` | `true` | Before finalizing a roadmap |
-| `confirm_plan` | `true` | Before finalizing plans for a phase |
-| `confirm_execute` | `false` | Before starting phase execution (`/pbr:build`) |
-| `confirm_transition` | `true` | Before transitioning to the next phase |
-| `issues_review` | `true` | Before proceeding when issues are detected |
-
-Setting a gate to `false` makes that step automatic (no user prompt).
-
----
-
-## safety
-
-Safety controls for destructive or external operations.
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `always_confirm_destructive` | boolean | `true` | Always ask before destructive git operations |
-| `always_confirm_external_services` | boolean | `true` | Always ask before calling external APIs or services |
-
-These cannot be disabled via `/pbr:config` -- they require manual editing of `config.json` as a deliberate action.
-
----
-
-## Validation Rules
-
-When modifying config (via `/pbr:config` or direct edit):
-
-| Field | Valid Values |
-|-------|-------------|
-| `depth` | `quick`, `standard`, `comprehensive` |
-| `models.*` | `sonnet`, `inherit`, `haiku`, `opus` |
-| `context_strategy` | `aggressive`, `balanced`, `minimal` |
-| `git.branching` | `none`, `phase`, `milestone`, `disabled` |
-| `git.mode` | `enabled`, `disabled` |
-| All boolean fields | `true`, `false` |

package/plugins/pbr/references/subagent-coordination.md

@@ -1,119 +0,0 @@
-# Subagent Coordination Reference
-
-Patterns for spawning, monitoring, and consuming output from Task() subagents. Used by skills that delegate work to specialized agents.
-
----
-
-## When to Spawn vs Inline
-
-| Condition | Action |
-|-----------|--------|
-| >50 lines of analysis or code generation needed | Spawn a subagent |
-| Simple state read or file write | Do it inline |
-| Multiple files need reading for a decision | Spawn — protect orchestrator context |
-| User interaction needed (questions, confirmations) | Do it inline |
-| Work needs a fresh context window | Spawn |
-
----
-
-## Spawning Pattern
-
-Always use the modern subagent_type syntax. Agent definitions are auto-loaded by Claude Code — never inline them.
-
-```
-Task({
-  subagent_type: "pbr:{agent-name}",
-  prompt: <structured prompt with context>
-})
-```
-
-### Structured Input Format
-
-Provide context to subagents using tagged blocks:
-
-```xml
-<phase_context>
-Phase: {NN}-{slug}
-Goal: {goal from ROADMAP.md}
-</phase_context>
-
-<prior_work>
-{Frontmatter from relevant SUMMARY.md files}
-</prior_work>
-
-<instructions>
-{Specific instructions for this agent invocation}
-</instructions>
-```
-
-### What NOT to Include in Spawn Prompts
-
-- Full agent definition text (auto-loaded via subagent_type)
-- Full SUMMARY.md bodies (agent reads from disk)
-- Full PLAN.md bodies unless the agent needs them (executor does, verifier doesn't)
-- Content from unrelated phases
-
----
-
-## Reading Output
-
-After a subagent completes, read its output file — but only what you need.
-
-| Output Type | Orchestrator Reads | Agent Reads Full |
-|-------------|-------------------|-----------------|
-| SUMMARY.md | Frontmatter only (status, key_files, commits) | Yes, from disk |
-| VERIFICATION.md | Frontmatter only (status, must_haves_passed/failed) | Yes, from disk |
-| PLAN.md | Frontmatter only (wave, depends_on, files_modified) | Yes, from disk |
-| RESEARCH.md | Frontmatter + recommendations section | Yes, from disk |
-| Debug files | Latest hypothesis + result only | Yes, from disk |
-
-### Frontmatter-Only Read Pattern
-
-```
-Read the file, extract YAML frontmatter between --- markers.
-Parse: status, key_files, commits, provides.
-Do NOT read past the closing --- of frontmatter.
-```
-
----
-
-## State Update After Agent Completion
-
-After reading agent output, update STATE.md with minimal information:
-1. Update phase/plan status
-2. Record completion timestamp
-3. Note any blockers or warnings from frontmatter
-4. Do NOT copy agent output into STATE.md
-
----
-
-## Error Handling
-
-| Scenario | Action |
-|----------|--------|
-| Agent times out | Report to user, suggest retry |
-| Agent produces no output file | Report failure, check for partial work |
-| Output file has `status: failed` | Read failure details, present to user |
-| Agent reports warnings | Continue but show warnings in completion summary |
-
-### Retryable vs Fatal
-
-- **Retryable**: Timeout, transient file errors, partial completion
-- **Fatal**: Missing plan files, invalid state, circular dependencies
-- **User decision**: Verification failures, ambiguous requirements
-
----
-
-## Context Budget Impact
-
-Each subagent coordination step has a token cost in the orchestrator:
-
-| Step | Approximate Cost |
-|------|-----------------|
-| Reading state before spawn | 200-500 tokens |
-| Constructing spawn prompt | 500-1000 tokens |
-| Reading output frontmatter | 100-300 tokens |
-| Updating STATE.md | 200-400 tokens |
-| **Total per agent cycle** | **1,000-2,200 tokens** |
-
-Compare to inlining the same work: 5,000-20,000 tokens. Delegation saves 3-10x.