@sienklogic/plan-build-run 2.22.0 → 2.22.2

package/plugins/copilot-pbr/skills/shared/error-reporting.md

@@ -1,81 +0,0 @@
-# Error Reporting Fragment
-
-Standard error display formats for all skills. Reference `references/ui-formatting.md` for the full brand guide.
-
-## Recoverable Error
-
-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
-
-For errors that stop execution — skill cannot continue:
-
-```
-✗ Error: {short description}
-
-{1-2 line explanation}
-
-What to try:
-  1. {first suggestion}
-  2. {second suggestion}
-  3. {fallback — often /pbr:health or manual fix}
-```
-
-Example:
-```
-✗ 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
-
-For format or schema validation failures (config, plan format, commit message):
-
-```
-✗ Validation failed: {what was validated}
-
-Issues:
-  - {specific issue 1}
-  - {specific issue 2}
-
-Expected format: {brief format description or example}
-```
-
-## Hook Block Message
-
-For PreToolUse hooks that reject a tool call:
-
-```
-Blocked: {short reason}
-
-{explanation}
-
-{how to fix or alternative approach}
-```
-
-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.
-
-Block reasons should always include a "To fix:" line with actionable guidance so the user or agent knows how to resolve the block.

package/plugins/copilot-pbr/skills/shared/progress-display.md

@@ -1,53 +0,0 @@
-# Progress Display Fragment
-
-Standard progress display formats for all skills. Reference `references/ui-formatting.md` for the full brand guide.
-
-## Progress Bar
-
-Always 20 characters wide using `█` (filled) and `░` (empty):
-
-```
-Progress: [████████████░░░░░░░░] 60%
-```
-
-Calculate: `filled = Math.round(percent / 5)`, `empty = 20 - filled`
-
-## Phase Table
-
-Use when displaying multiple phases (status, milestone skills):
-
-```
-| Phase | Name             | Status    | Plans | Progress |
-|-------|------------------|-----------|-------|----------|
-| 01    | Setup            | ✓ complete | 2/2   | 100%     |
-| 02    | Authentication   | ◐ building | 1/3   | 33%      |
-| 03    | Dashboard        | ○ pending  | 0/4   | 0%       |
-```
-
-## Status Indicators
-
-| Symbol | Meaning | When to use |
-|--------|---------|-------------|
-| `✓` | Complete | Phase/plan/task finished |
-| `✗` | Failed | Verification failed |
-| `○` | Pending | Not started |
-| `◐` | In Progress | Currently executing |
-| `?` | Needs Human | Checkpoint requiring user action |
-| `⚠` | Warning | Non-blocking issue |
-| `⊘` | Blocked | Waiting on dependency |
-
-## Wave Progress (build skill)
-
-```
-Wave 1: ✓ Plan 01, ✓ Plan 02
-Wave 2: ◐ Plan 03 (executing)
-Wave 3: ○ Plan 04, ○ Plan 05
-```
-
-## Compact Status Line
-
-For inline status updates:
-
-```
-Phase 3 of 8 (Auth) — building — [████████░░░░░░░░░░░░] 40%
-```

package/plugins/copilot-pbr/skills/shared/state-loading.md

@@ -1,63 +0,0 @@
-<!-- canonical: ../../../pbr/skills/shared/state-loading.md -->
-# State Loading Pattern
-
-Standard pattern for loading project state at the start of a skill invocation. Include this fragment in skills that need project context.
-
----
-
-## Minimal State Read (for simple skills)
-
-Use when the skill only needs to know the current position. Skills: status, help, note, todo, pause, config.
-STATE.md is lean — it contains only current-phase context. Historical data lives in HISTORY.md.
-
-```
-1. Read .planning/STATE.md lines 1-20 only
-2. Extract: current phase, plan, status
-3. If STATE.md missing: inform user, suggest /pbr:begin
-```
-
-## Full State Read (for workflow skills)
-
-Use when the skill needs complete project context. Skills: build, plan, review, begin, milestone, continue, resume, debug.
-
-Reading order (always this sequence):
-
-```
-1. Read .planning/STATE.md
-   - Extract: Current Position section (phase, plan, status)
-   - Extract: Blockers/Concerns section (if not "None")
-   - Extract: Session Continuity section (if present)
-
-2. Read .planning/config.json
-   - Extract: depth, mode, features flags
-   - Extract: models configuration
-   - Extract: gates configuration
-
-3. Read .planning/ROADMAP.md (if exists)
-   - Extract: Phase Overview table (current + next 2 phases)
-   - Extract: dependency chain for current phase
-   - Do NOT read full phase details for past phases
-
-4. Read .planning/HISTORY.md (ONLY when cross-phase context is needed)
-   - Do NOT read HISTORY.md for normal build/plan/review operations
-   - Read ONLY when: debugging a regression that may trace to a prior phase,
-     or when a milestone audit needs historical context
-   - Use: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js history load`
-   - This returns structured JSON -- do not read the raw file
-```
-
-## Error Handling
-
-| File Missing | Action |
-|-------------|--------|
-| STATE.md | Warn user: "No STATE.md found. Run /pbr:begin to initialize." |
-| config.json | Use defaults (depth: standard, mode: interactive) |
-| ROADMAP.md | Continue without roadmap context (acceptable for quick tasks) |
-| .planning/ dir | Exit: "No .planning directory. This is not a Plan-Build-Run project." |
-
-## What NOT to Read During State Loading
-
-- Full SUMMARY.md bodies from prior phases (read frontmatter only if needed)
-- Agent definition files (agents/*.md) — auto-loaded by subagent_type
-- PLAN.md files from other phases (only current phase plans)
-- .planning/logs/ files (only health skill reads these)

package/plugins/cursor-pbr/references/agent-interactions.md

@@ -1,135 +0,0 @@
-<!-- canonical: ../../pbr/references/agent-interactions.md -->
-# Agent Interaction Map
-
-This document shows how Plan-Build-Run agents communicate through files on disk. Agents never message each other directly -- they read and write shared files in `.planning/`.
-
-## Interaction Graph
-
-```
-                    User / Orchestrator
-                     |           ^
-                     v           |
-              +--------------+   |
-              |  researcher  |---+---> planner
-              +--------------+         |    ^
-                     |                 v    |
-              +--------------+   +--------------+
-              | synthesizer  |   | plan-checker |
-              +--------------+   +--------------+
-                                       |
-                                       v
-                                 +-----------+
-                                 |  executor  |
-                                 +-----------+
-                                       |
-                                       v
-                                 +-----------+
-                                 |  verifier  |----> planner (gap closure)
-                                 +-----------+
-                                       |
-                                       v
-                              +--------------------+
-                              | integration-checker|
-                              +--------------------+
-```
-
-## Per-Agent Interaction Details
-
-### researcher
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | User/Orchestrator | Research topics, CONTEXT.md constraints, phase goals |
-| Produces for | planner | Research documents with technology details and recommendations |
-| Produces for | synthesizer | Research documents to be combined |
-| Produces for | User | Direct reading for decision-making |
-
-### synthesizer
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | researcher | Research documents to synthesize |
-| Receives from | Orchestrator | Paths to research documents, synthesis request |
-| Produces for | planner | SUMMARY.md as consolidated research input for planning |
-| Produces for | User | High-level project/phase research overview |
-
-### planner
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | researcher | Research documents with technology details and recommendations |
-| Receives from | plan-checker | Issue reports requiring plan revision |
-| Receives from | verifier | VERIFICATION.md reports requiring gap closure plans |
-| Receives from | User/Orchestrator | Phase goals, CONTEXT.md, planning requests |
-| Produces for | plan-checker | Plan files for quality verification |
-| Produces for | executor | Plan files for execution |
-| Produces for | verifier | Must-have definitions for verification (embedded in plan frontmatter) |
-
-### plan-checker
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Plan files to check, phase context |
-| Receives from | planner | Newly created or revised plan files |
-| Produces for | planner | Issue reports for revision |
-| Produces for | Orchestrator/User | Pass/fail decision on plan quality |
-
-### executor
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator | Plan files to execute, continuation instructions |
-| Receives from | planner | The plans themselves (indirectly, via files) |
-| Produces for | verifier | SUMMARY.md for verification, committed code for inspection |
-| Produces for | Orchestrator | Checkpoint responses, completion status |
-| Produces for | planner | Deferred ideas (in SUMMARY.md) for future planning |
-
-### verifier
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator | Phase to verify, timing trigger |
-| Receives from | executor | Completed work (via codebase and SUMMARY.md) |
-| Receives from | Previous VERIFICATION.md | Gaps to re-check (in re-verification mode) |
-| Produces for | planner | Gap list for gap-closure planning (via VERIFICATION.md) |
-| Produces for | Orchestrator | Phase status (passed/gaps_found/human_needed) |
-| Produces for | User | Human verification items with specific test instructions |
-
-### integration-checker
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator | Phases to check, trigger event (milestone/review) |
-| Receives from | verifier | Phase-level verification reports (for context on per-phase status) |
-| Produces for | planner | Integration gap list for cross-phase fix plans |
-| Produces for | Orchestrator | Integration status for milestone decisions |
-| Produces for | User | Integration health overview and security issues |
-
-### debugger
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Bug reports, symptoms, reproduction steps |
-| Receives from | executor | Errors encountered during execution (via checkpoint responses) |
-| Receives from | verifier | Issues discovered during verification |
-| Produces for | Orchestrator/User | Root cause analysis, fix commits, checkpoint requests |
-| Produces for | planner | Findings requiring architectural changes |
-| Produces for | executor | Simple fix instructions for executor to apply |
-
-### codebase-mapper
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Focus area to analyze, project path |
-| Receives from | researcher | May be invoked alongside researcher for new projects |
-| Produces for | planner | STACK.md, ARCHITECTURE.md, STRUCTURE.md for informed planning |
-| Produces for | executor | CONVENTIONS.md for code style, TESTING.md for test patterns |
-| Produces for | verifier | All documents as reference for what "correct" looks like |
-| Produces for | User | Direct reading for project understanding |
-
-### general
-
-| Direction | Agent/Role | What |
-|-----------|-----------|------|
-| Receives from | Orchestrator/User | Ad-hoc task instructions |
-| Produces for | Orchestrator/User | Task output (files, formatting, config changes) |

package/plugins/cursor-pbr/references/planning-config.md

@@ -1,214 +0,0 @@
-<!-- canonical: ../../pbr/references/planning-config.md -->
-# 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/cursor-pbr/references/subagent-coordination.md

@@ -1,120 +0,0 @@
-<!-- canonical: ../../pbr/references/subagent-coordination.md -->
-# 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.