@sienklogic/plan-build-run 2.0.0 → 2.0.1

package/plugins/pbr/skills/shared/config-loading.md

@@ -1,102 +1,102 @@
-# Config Loading Pattern
-
-Standard pattern for loading `.planning/config.json` fields at the start of a skill invocation.
-
-> Referenced by: build, plan, review, import, begin, quick, milestone, scan skills
-
----
-
-## Tooling Shortcut
-
-Instead of reading and parsing STATE.md, ROADMAP.md, and config.json manually, run:
-```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load
-```
-This returns a JSON object with `config`, `state`, `roadmap`, `current_phase`, and `progress`. Falls back gracefully if the script is missing -- parse files manually in that case.
-
-Additional tooling shortcuts:
-- `plan-index <phase>` -- returns plan inventory (plan_id, wave, depends_on, autonomous, must_haves_count per plan)
-- `phase-info <phase>` -- returns comprehensive phase status (verification, summaries, roadmap_status, filesystem_status, plan_count, completed)
-
----
-
-## Standard Config Fields
-
-These are the config.json fields commonly read by workflow skills. Each skill reads a subset depending on its needs.
-
-### Core Settings
-```
-depth                 -- quick | standard | comprehensive
-mode                  -- interactive | autonomous
-```
-
-### Feature Flags
-```
-features.research_phase        -- run researcher before planning
-features.plan_checking         -- validate plans via plan-checker agent
-features.goal_verification     -- run verifier after build
-features.inline_verify         -- per-task verification after each executor commit (opt-in)
-features.atomic_commits        -- require atomic commits per task
-features.auto_continue         -- write .auto-next signal on phase completion
-features.auto_advance          -- chain build->review->plan in autonomous mode
-features.integration_verification -- check cross-phase integration
-```
-
-### Gate Flags
-```
-gates.confirm_plan             -- require user approval before building
-gates.confirm_execute          -- require user confirmation before executing build
-gates.confirm_transition       -- require confirmation before advancing to next phase
-```
-
-### Parallelization
-```
-parallelization.enabled        -- whether to run plans in parallel
-parallelization.plan_level     -- parallel at plan level (within a wave)
-parallelization.max_concurrent_agents -- max simultaneous executors
-```
-
-### Planning
-```
-planning.commit_docs           -- commit planning docs after operations
-planning.max_tasks_per_plan    -- maximum tasks in a single plan
-```
-
-### Git
-```
-git.commit_format              -- commit message format
-git.branching_strategy         -- none | phase | milestone
-```
-
-### Models
-```
-models.researcher              -- model for researcher agent
-models.planner                 -- model for planner agent
-models.executor                -- model for executor agent
-models.verifier                -- model for verifier agent
-```
-
----
-
-## Config Field Matrix by Skill
-
-| Field | build | plan | review | import | begin | quick | milestone |
-|-------|-------|------|--------|--------|-------|-------|-----------|
-| depth | | X | | | X | | |
-| mode | X | X | X | | X | | |
-| features.research_phase | | X | | | | | |
-| features.plan_checking | | X | | X | | | |
-| features.goal_verification | X | | X | | | | |
-| features.inline_verify | X | | | | | | |
-| features.atomic_commits | X | | | | | | |
-| features.auto_continue | X | | | | | | |
-| features.auto_advance | X | X | X | | | | |
-| features.integration_verification | | | X | | | | X |
-| gates.confirm_plan | | X | | | | | |
-| gates.confirm_execute | X | | | | | | |
-| gates.confirm_transition | | | X | | | | |
-| parallelization.* | X | | | | | | |
-| planning.commit_docs | X | | | | | X | X |
-| git.commit_format | X | | | | X | X | |
-| git.branching_strategy | X | | | | | | |
-| models.* | | X | X | | X | | X |
+# Config Loading Pattern
+
+Standard pattern for loading `.planning/config.json` fields at the start of a skill invocation.
+
+> Referenced by: build, plan, review, import, begin, quick, milestone, scan skills
+
+---
+
+## Tooling Shortcut
+
+Instead of reading and parsing STATE.md, ROADMAP.md, and config.json manually, run:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load
+```
+This returns a JSON object with `config`, `state`, `roadmap`, `current_phase`, and `progress`. Falls back gracefully if the script is missing -- parse files manually in that case.
+
+Additional tooling shortcuts:
+- `plan-index <phase>` -- returns plan inventory (plan_id, wave, depends_on, autonomous, must_haves_count per plan)
+- `phase-info <phase>` -- returns comprehensive phase status (verification, summaries, roadmap_status, filesystem_status, plan_count, completed)
+
+---
+
+## Standard Config Fields
+
+These are the config.json fields commonly read by workflow skills. Each skill reads a subset depending on its needs.
+
+### Core Settings
+```
+depth                 -- quick | standard | comprehensive
+mode                  -- interactive | autonomous
+```
+
+### Feature Flags
+```
+features.research_phase        -- run researcher before planning
+features.plan_checking         -- validate plans via plan-checker agent
+features.goal_verification     -- run verifier after build
+features.inline_verify         -- per-task verification after each executor commit (opt-in)
+features.atomic_commits        -- require atomic commits per task
+features.auto_continue         -- write .auto-next signal on phase completion
+features.auto_advance          -- chain build->review->plan in autonomous mode
+features.integration_verification -- check cross-phase integration
+```
+
+### Gate Flags
+```
+gates.confirm_plan             -- require user approval before building
+gates.confirm_execute          -- require user confirmation before executing build
+gates.confirm_transition       -- require confirmation before advancing to next phase
+```
+
+### Parallelization
+```
+parallelization.enabled        -- whether to run plans in parallel
+parallelization.plan_level     -- parallel at plan level (within a wave)
+parallelization.max_concurrent_agents -- max simultaneous executors
+```
+
+### Planning
+```
+planning.commit_docs           -- commit planning docs after operations
+planning.max_tasks_per_plan    -- maximum tasks in a single plan
+```
+
+### Git
+```
+git.commit_format              -- commit message format
+git.branching         -- none | phase | milestone
+```
+
+### Models
+```
+models.researcher              -- model for researcher agent
+models.planner                 -- model for planner agent
+models.executor                -- model for executor agent
+models.verifier                -- model for verifier agent
+```
+
+---
+
+## Config Field Matrix by Skill
+
+| Field | build | plan | review | import | begin | quick | milestone |
+|-------|-------|------|--------|--------|-------|-------|-----------|
+| depth | | X | | | X | | |
+| mode | X | X | X | | X | | |
+| features.research_phase | | X | | | | | |
+| features.plan_checking | | X | | X | | | |
+| features.goal_verification | X | | X | | | | |
+| features.inline_verify | X | | | | | | |
+| features.atomic_commits | X | | | | | | |
+| features.auto_continue | X | | | | | | |
+| features.auto_advance | X | X | X | | | | |
+| features.integration_verification | | | X | | | | X |
+| gates.confirm_plan | | X | | | | | |
+| gates.confirm_execute | X | | | | | | |
+| gates.confirm_transition | | | X | | | | |
+| parallelization.* | X | | | | | | |
+| planning.commit_docs | X | | | | | X | X |
+| git.commit_format | X | | | | X | X | |
+| git.branching | X | | | | | | |
+| models.* | | X | X | | X | | X |

package/plugins/pbr/skills/shared/context-budget.md

@@ -1,40 +1,40 @@
-# Context Budget Rules
-
-Standard rules for keeping orchestrator context lean. Reference this fragment in skills that spawn Task() subagents.
-
-See also: `skills/shared/universal-anti-patterns.md` for the complete set of universal rules (context budget + file reading + behavioral rules).
-
----
-
-## Universal Rules
-
-Every skill that spawns agents or reads significant content must follow these rules:
-
-1. **Never** read agent definition files (`agents/*.md`) — `subagent_type` auto-loads them
-2. **Never** inline large files into Task() prompts — tell agents to read files from disk instead
-3. **Minimize** reading subagent output into main context — read only frontmatter, not full content
-4. **Delegate** heavy work to subagents — the orchestrator routes, it doesn't execute
-5. **Before spawning agents**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider running `/pbr:pause` to checkpoint progress." Suggest pause proactively rather than waiting for compaction.
-
-## Customization
-
-Skills should add skill-specific rules below the reference line. Common skill-specific additions:
-
-- **build**: "Minimize reading executor output — read only SUMMARY.md frontmatter, not full content"
-- **plan**: "Minimize reading subagent output — read only plan frontmatter for summaries"
-- **review**: "Minimize reading subagent output — read only VERIFICATION.md frontmatter for summaries"
-- **scan**: "Delegate ALL analysis to the 4 parallel codebase-mapper subagents"
-- **quick**: "Never implement the task yourself — ALL code changes go through a spawned executor"
-- **debug**: "Never perform investigation work yourself — delegate ALL analysis to the debugger subagent"
-
-Format in the SKILL.md:
-
-```markdown
-## Context Budget
-
-Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
-
-Additionally for this skill:
-- {Skill-specific rule 1}
-- {Skill-specific rule 2}
-```
+# Context Budget Rules
+
+Standard rules for keeping orchestrator context lean. Reference this fragment in skills that spawn Task() subagents.
+
+See also: `skills/shared/universal-anti-patterns.md` for the complete set of universal rules (context budget + file reading + behavioral rules).
+
+---
+
+## Universal Rules
+
+Every skill that spawns agents or reads significant content must follow these rules:
+
+1. **Never** read agent definition files (`agents/*.md`) — `subagent_type` auto-loads them
+2. **Never** inline large files into Task() prompts — tell agents to read files from disk instead
+3. **Minimize** reading subagent output into main context — read only frontmatter, not full content
+4. **Delegate** heavy work to subagents — the orchestrator routes, it doesn't execute
+5. **Before spawning agents**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider running `/pbr:pause` to checkpoint progress." Suggest pause proactively rather than waiting for compaction.
+
+## Customization
+
+Skills should add skill-specific rules below the reference line. Common skill-specific additions:
+
+- **build**: "Minimize reading executor output — read only SUMMARY.md frontmatter, not full content"
+- **plan**: "Minimize reading subagent output — read only plan frontmatter for summaries"
+- **review**: "Minimize reading subagent output — read only VERIFICATION.md frontmatter for summaries"
+- **scan**: "Delegate ALL analysis to the 4 parallel codebase-mapper subagents"
+- **quick**: "Never implement the task yourself — ALL code changes go through a spawned executor"
+- **debug**: "Never perform investigation work yourself — delegate ALL analysis to the debugger subagent"
+
+Format in the SKILL.md:
+
+```markdown
+## Context Budget
+
+Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+
+Additionally for this skill:
+- {Skill-specific rule 1}
+- {Skill-specific rule 2}
+```

package/plugins/pbr/skills/shared/context-loader-task.md

@@ -1,86 +1,86 @@
-# Context Loader Task Pattern
-
-Standard pattern for spawning a lightweight Task() to build a project briefing before the main skill logic runs. Used by skills that need project context but want to keep the orchestrator lean.
-
-> Referenced by: explore, scan, discuss skills (and any skill that needs a project briefing before interactive work)
-
----
-
-## When to Use
-
-Use this pattern when:
-- The skill runs mostly inline (conversation, presentation) rather than delegating to agents
-- The skill needs awareness of project state, decisions, and progress
-- Reading all context files directly would consume too much orchestrator context
-
-Do NOT use this pattern when:
-- The skill already uses `pbr-tools.js state load` (build, plan, review, import)
-- The skill reads only STATE.md lines 1-20 (continue, status, resume)
-- The skill has no project dependency (note with `--global`)
-
----
-
-## Pattern: Briefing Task
-
-```
-Task({
-  prompt: "Read the following files and return a ~500 token briefing summarizing the project state, key decisions, and any context relevant to {skill_purpose}:
-    - .planning/STATE.md
-    - .planning/ROADMAP.md
-    - .planning/REQUIREMENTS.md
-    - .planning/CONTEXT.md
-    - Any .planning/phases/*/CONTEXT.md files
-    - .planning/research/SUMMARY.md (if exists)
-    - .planning/NOTES.md (if exists)
-    - .planning/HISTORY.md (if exists — scan for decisions relevant to current work only, do NOT summarize all history)
-
-  Return ONLY the briefing text. No preamble, no suggestions."
-})
-```
-
-### Key Rules
-
-1. **Only runs if `.planning/` directory exists.** Skills invoked on fresh projects with no planning directory skip this entirely.
-2. **Budget: ~500 tokens.** The briefing must be concise. The subagent reads full files in its own context; the orchestrator receives only the summary.
-3. **No suggestions.** The briefing reports state, it does not recommend actions. The skill logic decides what to do.
-4. **Read-only.** The briefing task must not write any files.
-
-### Using the Briefing
-
-After the task completes:
-- Use the briefing to inform conversation -- reference existing decisions, avoid re-litigating settled questions
-- Connect new ideas or findings to existing project structure
-- Identify relevant phases, requirements, or decisions without reading the source files yourself
-
----
-
-## Variation: Topic-Scoped Briefing
-
-When the skill has a specific topic (e.g., `/pbr:explore auth`), scope the briefing:
-
-```
-Task({
-  prompt: "Read the following files and return a ~500 token briefing focused on {topic}:
-    - .planning/STATE.md
-    - .planning/ROADMAP.md
-    - .planning/REQUIREMENTS.md
-    - .planning/CONTEXT.md
-    - Any .planning/phases/*/CONTEXT.md files
-    - .planning/HISTORY.md (if exists — scan for decisions relevant to '{topic}' only, do NOT summarize all history)
-
-  Focus on: decisions, requirements, and phase goals related to '{topic}'.
-  Return ONLY the briefing text. No preamble, no suggestions."
-})
-```
-
----
-
-## Variation: Scan Reconnaissance
-
-For `/pbr:scan`, the pattern adapts to codebase analysis rather than project state:
-
-1. The orchestrator performs a quick inline scan (detect project type, scale, key directories)
-2. Writes the results to `.planning/codebase/RECON.md`
-3. Passes RECON.md content to the spawned analysis agents as baseline context
-
-This is the same principle (build context before main work) but the source is the codebase rather than planning files.
+# Context Loader Task Pattern
+
+Standard pattern for spawning a lightweight Task() to build a project briefing before the main skill logic runs. Used by skills that need project context but want to keep the orchestrator lean.
+
+> Referenced by: explore, scan, discuss skills (and any skill that needs a project briefing before interactive work)
+
+---
+
+## When to Use
+
+Use this pattern when:
+- The skill runs mostly inline (conversation, presentation) rather than delegating to agents
+- The skill needs awareness of project state, decisions, and progress
+- Reading all context files directly would consume too much orchestrator context
+
+Do NOT use this pattern when:
+- The skill already uses `pbr-tools.js state load` (build, plan, review, import)
+- The skill reads only STATE.md lines 1-20 (continue, status, resume)
+- The skill has no project dependency (note with `--global`)
+
+---
+
+## Pattern: Briefing Task
+
+```
+Task({
+  prompt: "Read the following files and return a ~500 token briefing summarizing the project state, key decisions, and any context relevant to {skill_purpose}:
+    - .planning/STATE.md
+    - .planning/ROADMAP.md
+    - .planning/REQUIREMENTS.md
+    - .planning/CONTEXT.md
+    - Any .planning/phases/*/CONTEXT.md files
+    - .planning/research/SUMMARY.md (if exists)
+    - .planning/NOTES.md (if exists)
+    - .planning/HISTORY.md (if exists — scan for decisions relevant to current work only, do NOT summarize all history)
+
+  Return ONLY the briefing text. No preamble, no suggestions."
+})
+```
+
+### Key Rules
+
+1. **Only runs if `.planning/` directory exists.** Skills invoked on fresh projects with no planning directory skip this entirely.
+2. **Budget: ~500 tokens.** The briefing must be concise. The subagent reads full files in its own context; the orchestrator receives only the summary.
+3. **No suggestions.** The briefing reports state, it does not recommend actions. The skill logic decides what to do.
+4. **Read-only.** The briefing task must not write any files.
+
+### Using the Briefing
+
+After the task completes:
+- Use the briefing to inform conversation -- reference existing decisions, avoid re-litigating settled questions
+- Connect new ideas or findings to existing project structure
+- Identify relevant phases, requirements, or decisions without reading the source files yourself
+
+---
+
+## Variation: Topic-Scoped Briefing
+
+When the skill has a specific topic (e.g., `/pbr:explore auth`), scope the briefing:
+
+```
+Task({
+  prompt: "Read the following files and return a ~500 token briefing focused on {topic}:
+    - .planning/STATE.md
+    - .planning/ROADMAP.md
+    - .planning/REQUIREMENTS.md
+    - .planning/CONTEXT.md
+    - Any .planning/phases/*/CONTEXT.md files
+    - .planning/HISTORY.md (if exists — scan for decisions relevant to '{topic}' only, do NOT summarize all history)
+
+  Focus on: decisions, requirements, and phase goals related to '{topic}'.
+  Return ONLY the briefing text. No preamble, no suggestions."
+})
+```
+
+---
+
+## Variation: Scan Reconnaissance
+
+For `/pbr:scan`, the pattern adapts to codebase analysis rather than project state:
+
+1. The orchestrator performs a quick inline scan (detect project type, scale, key directories)
+2. Writes the results to `.planning/codebase/RECON.md`
+3. Passes RECON.md content to the spawned analysis agents as baseline context
+
+This is the same principle (build context before main work) but the source is the codebase rather than planning files.

package/plugins/pbr/skills/shared/digest-select.md

@@ -1,79 +1,79 @@
-# Digest-Select Pattern
-
-Selective reading depth for prior phase SUMMARY.md files. Saves tokens by reading only what is needed based on the relationship to the current phase.
-
-> Referenced by: plan, build, import skills
-
----
-
-## Depth Rules
-
-Not all prior phase SUMMARYs need the same level of detail. Use selective depth based on dependency distance:
-
-| Relationship to current phase | Read depth |
-|-------------------------------|------------|
-| Direct dependency (listed in `depends_on` in ROADMAP.md) | Frontmatter + "Key Decisions" section. The subagent reads full bodies from disk in its own context. |
-| 1 phase back from a dependency (transitive) | Frontmatter only (`provides`, `key_files`, `key_decisions`, `patterns`) |
-| 2+ phases back | Skip entirely |
-
----
-
-## Example
-
-If planning Phase 5 which depends on Phase 4, and Phase 4 depends on Phase 3:
-- Phase 4 SUMMARYs: frontmatter + "Key Decisions" section
-- Phase 3 SUMMARYs: frontmatter only
-- Phases 1-2 SUMMARYs: skip
-
-This saves ~500 tokens per skipped SUMMARY for large projects.
-
----
-
-## How to Determine Dependency Distance
-
-1. Read ROADMAP.md and find the current phase's `depends_on` list
-2. Those are the **direct dependencies** (distance 1) -- read frontmatter + key decisions
-3. For each direct dependency, find ITS `depends_on` list -- those are **transitive** (distance 2) -- read frontmatter only
-4. Everything else (distance 3+) -- skip
-
----
-
-## Frontmatter Fields to Extract
-
-When reading frontmatter only (transitive dependencies), extract these fields:
-
-```yaml
-status: complete
-provides:
-  - "user authentication API"
-  - "session management middleware"
-key_files:
-  - src/auth/controller.ts
-  - src/auth/middleware.ts
-key_decisions:
-  - "JWT with refresh tokens"
-  - "bcrypt for password hashing"
-patterns:
-  - "repository pattern for data access"
-  - "middleware chain for auth checks"
-```
-
-These fields give downstream skills enough context to build on prior work without reading the full SUMMARY body.
-
----
-
-## Skill-Specific Notes
-
-### /pbr:plan
-- Direct dependencies: frontmatter + "Key Decisions" section (planner reads full bodies from disk)
-- Used in Step 2: Load Context
-
-### /pbr:build
-- Direct dependencies (completed earlier waves): frontmatter only for prior work table
-- Used in Step 6a: Spawn Executors (prior_work section of executor prompt)
-
-### /pbr:import
-- Direct dependencies: full SUMMARY body (needed for conflict detection)
-- Transitive: frontmatter only
-- 2+ back: skip
-- Used in Step 2: Load Full Project Context
+# Digest-Select Pattern
+
+Selective reading depth for prior phase SUMMARY.md files. Saves tokens by reading only what is needed based on the relationship to the current phase.
+
+> Referenced by: plan, build, import skills
+
+---
+
+## Depth Rules
+
+Not all prior phase SUMMARYs need the same level of detail. Use selective depth based on dependency distance:
+
+| Relationship to current phase | Read depth |
+|-------------------------------|------------|
+| Direct dependency (listed in `depends_on` in ROADMAP.md) | Frontmatter + "Key Decisions" section. The subagent reads full bodies from disk in its own context. |
+| 1 phase back from a dependency (transitive) | Frontmatter only (`provides`, `key_files`, `key_decisions`, `patterns`) |
+| 2+ phases back | Skip entirely |
+
+---
+
+## Example
+
+If planning Phase 5 which depends on Phase 4, and Phase 4 depends on Phase 3:
+- Phase 4 SUMMARYs: frontmatter + "Key Decisions" section
+- Phase 3 SUMMARYs: frontmatter only
+- Phases 1-2 SUMMARYs: skip
+
+This saves ~500 tokens per skipped SUMMARY for large projects.
+
+---
+
+## How to Determine Dependency Distance
+
+1. Read ROADMAP.md and find the current phase's `depends_on` list
+2. Those are the **direct dependencies** (distance 1) -- read frontmatter + key decisions
+3. For each direct dependency, find ITS `depends_on` list -- those are **transitive** (distance 2) -- read frontmatter only
+4. Everything else (distance 3+) -- skip
+
+---
+
+## Frontmatter Fields to Extract
+
+When reading frontmatter only (transitive dependencies), extract these fields:
+
+```yaml
+status: complete
+provides:
+  - "user authentication API"
+  - "session management middleware"
+key_files:
+  - src/auth/controller.ts
+  - src/auth/middleware.ts
+key_decisions:
+  - "JWT with refresh tokens"
+  - "bcrypt for password hashing"
+patterns:
+  - "repository pattern for data access"
+  - "middleware chain for auth checks"
+```
+
+These fields give downstream skills enough context to build on prior work without reading the full SUMMARY body.
+
+---
+
+## Skill-Specific Notes
+
+### /pbr:plan
+- Direct dependencies: frontmatter + "Key Decisions" section (planner reads full bodies from disk)
+- Used in Step 2: Load Context
+
+### /pbr:build
+- Direct dependencies (completed earlier waves): frontmatter only for prior work table
+- Used in Step 6a: Spawn Executors (prior_work section of executor prompt)
+
+### /pbr:import
+- Direct dependencies: full SUMMARY body (needed for conflict detection)
+- Transitive: frontmatter only
+- 2+ back: skip
+- Used in Step 2: Load Full Project Context