@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/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>" }`.

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.