@sienklogic/plan-build-run 2.0.0

package/plugins/pbr/skills/setup/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: setup
+description: "Onboarding wizard. Initialize project, select models, verify setup."
+allowed-tools: Read, Write, Bash, Glob, AskUserQuestion
+---
+
+# /pbr:setup — Plan-Build-Run Setup Wizard
+
+You are running the **setup** skill. This is an interactive onboarding wizard that guides users through Plan-Build-Run project setup. Use AskUserQuestion at each step for clear choices.
+
+---
+
+## Step 1: Detect Project State
+
+Check if `.planning/` directory exists in the current working directory.
+
+**If `.planning/` exists**:
+- Read `.planning/config.json` to check current settings
+- Tell the user: "Existing Plan-Build-Run project detected. This wizard will review your configuration."
+- Skip to Step 3 (model selection)
+
+**If `.planning/` does NOT exist**:
+- Ask the user:
+
+```
+AskUserQuestion:
+  question: "No Plan-Build-Run project found. Would you like to initialize one?"
+  header: "Initialize"
+  options:
+    - label: "Yes, initialize here"
+      description: "Creates .planning/ directory with default config, STATE.md, and ROADMAP.md"
+    - label: "No, just exploring"
+      description: "Exit the wizard — you can run /pbr:begin later for full project setup"
+```
+
+If "No", display: "Run `/pbr:begin` when you're ready to start a project. It includes deep requirements gathering and roadmap creation." Then stop.
+
+If "Yes", create the minimal `.planning/` structure:
+
+```bash
+mkdir -p .planning/phases .planning/todos/pending .planning/todos/done .planning/logs .planning/research
+```
+
+Create `.planning/config.json` with defaults:
+```json
+{
+  "version": 2,
+  "depth": "standard",
+  "mode": "guided",
+  "features": {
+    "structured_planning": true,
+    "goal_verification": true,
+    "integration_verification": false,
+    "context_isolation": true,
+    "atomic_commits": true,
+    "session_persistence": true,
+    "research_phase": true,
+    "plan_checking": true,
+    "tdd_mode": false,
+    "status_line": true,
+    "auto_continue": false,
+    "auto_advance": false,
+    "team_discussions": false,
+    "inline_verify": false
+  },
+  "models": {
+    "executor": "sonnet",
+    "researcher": "sonnet",
+    "planner": "sonnet",
+    "verifier": "sonnet",
+    "synthesizer": "haiku"
+  },
+  "parallelization": {
+    "max_concurrent_agents": 3,
+    "allow_parallel_plans": true
+  },
+  "planning": {
+    "max_plans_per_phase": 4,
+    "min_must_haves": 3
+  },
+  "git": {
+    "auto_commit": true,
+    "commit_format": "conventional",
+    "branching_strategy": "none"
+  },
+  "gates": {
+    "verification": true,
+    "review": true,
+    "plan_approval": false,
+    "pre_build_checklist": false
+  },
+  "safety": {
+    "block_sensitive_files": true,
+    "require_tests": false
+  },
+  "hooks": {}
+}
+```
+
+Create `.planning/STATE.md`:
+```markdown
+---
+version: 2
+current_phase: 0
+total_phases: 0
+status: "initialized"
+progress_percent: 0
+last_activity: "{today's date}"
+last_command: "/pbr:setup"
+blockers: []
+---
+# Project State
+
+## Current Position
+Phase: 0 of 0
+Status: initialized
+
+Plan-Build-Run project initialized via /pbr:setup. Run /pbr:begin to start requirements gathering and roadmap creation.
+```
+
+---
+
+## Step 2: Project Type (new projects only)
+
+```
+AskUserQuestion:
+  question: "What kind of project is this?"
+  header: "Project type"
+  options:
+    - label: "Greenfield"
+      description: "Starting from scratch — full planning cycle recommended"
+    - label: "Existing codebase"
+      description: "Adding Plan-Build-Run to an existing project — run /pbr:scan first"
+    - label: "Prototype/experiment"
+      description: "Quick iteration — lighter workflow with fewer gates"
+```
+
+Based on selection:
+- **Greenfield**: Keep defaults (full gates, structured planning)
+- **Existing codebase**: Suggest running `/pbr:scan` after setup to map the codebase
+- **Prototype**: Set `depth: "quick"`, disable `gates.verification`, disable `gates.review`, set `features.research_phase: false`
+
+Update config.json with any changes.
+
+---
+
+## Step 3: Model Selection
+
+```
+AskUserQuestion:
+  question: "Which model profile should Plan-Build-Run use for agents?"
+  header: "Models"
+  options:
+    - label: "Balanced (Recommended)"
+      description: "Sonnet for most agents, Haiku for synthesizer. Good quality/cost tradeoff."
+    - label: "Quality"
+      description: "Opus for executor and planner, Sonnet for others. Best results, highest cost."
+    - label: "Budget"
+      description: "Haiku for most agents. Fastest and cheapest, but lower quality."
+```
+
+Apply the selected profile to `config.json`:
+- **Balanced**: executor=sonnet, researcher=sonnet, planner=sonnet, verifier=sonnet, synthesizer=haiku
+- **Quality**: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet
+- **Budget**: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku
+
+---
+
+## Step 4: Workflow Preferences
+
+```
+AskUserQuestion:
+  question: "Which workflow features do you want enabled?"
+  header: "Features"
+  multiSelect: true
+  options:
+    - label: "Auto-continue"
+      description: "Automatically chain commands (build → review → next phase) without prompting"
+    - label: "TDD mode"
+      description: "Write tests before implementation in executor agents"
+    - label: "Strict gates"
+      description: "Require verification AND review to pass before advancing phases"
+    - label: "Git branching"
+      description: "Create a branch per phase for cleaner PR history"
+```
+
+Apply selections:
+- **Auto-continue**: Set `features.auto_continue: true`
+- **TDD mode**: Set `features.tdd_mode: true`
+- **Strict gates**: Set `gates.verification: true`, `gates.review: true`, `gates.plan_approval: true`
+- **Git branching**: Set `git.branching_strategy: "phase"`
+
+---
+
+## Step 5: Verification
+
+Run a quick health check:
+
+1. Verify `.planning/config.json` is valid JSON
+2. Verify `.planning/STATE.md` exists and is parseable
+3. Verify hook scripts are accessible: `node ${CLAUDE_PLUGIN_ROOT}/scripts/progress-tracker.js` from the project directory
+4. Check that `npm test` works (if package.json exists)
+
+Display results:
+
+```
+Setup Complete!
+
+Project: {cwd basename}
+Model profile: {balanced/quality/budget}
+Depth: {quick/standard/comprehensive}
+Features: {list of enabled non-default features}
+
+Next steps:
+  /pbr:begin  — Full project setup with requirements and roadmap
+  /pbr:scan   — Analyze existing codebase (if adding to existing project)
+  /pbr:help   — Command reference
+  /pbr:config — Fine-tune individual settings
+```
+
+---
+
+## Error Handling
+
+- If `.planning/` creation fails (permissions): Tell user to create it manually and retry
+- If config.json write fails: Display the JSON content and ask user to save it manually
+- If health check fails: Display specific failure and suggest `/pbr:health` for diagnostics

package/plugins/pbr/skills/shared/commit-planning-docs.md

@@ -0,0 +1,35 @@
+# Commit Planning Docs Pattern
+
+Standard pattern for committing planning artifacts to git. Reference this fragment in skills that create or modify `.planning/` files.
+
+---
+
+## Pattern
+
+```
+If `planning.commit_docs: true` in config.json:
+1. Stage the relevant .planning/ files for this skill's output
+2. Commit with format: `docs({scope}): {description}`
+3. Use the appropriate scope from the skill's commit conventions
+
+If `planning.commit_docs: false` or config.json missing:
+- Skip the commit step
+```
+
+## Commit Messages by Skill
+
+| Skill | Commit message format |
+|-------|----------------------|
+| build | `docs({phase}): add build summaries and verification` |
+| plan | `docs({phase}): add phase plans` |
+| review | `docs({phase}): add verification report` |
+| begin | `chore: initialize plan-build-run project planning` |
+| import | `docs({phase}): import external plans` |
+| quick | `docs(planning): quick task {NNN} - {slug}` |
+| scan | `docs(planning): initial codebase analysis` |
+| explore | `docs(planning): capture explore session outputs` |
+| debug | `docs(planning): open/resolve debug session {NNN}` |
+| discuss | `docs(planning): capture phase {N} discussion decisions` |
+| pause | `docs(planning): checkpoint phase {N} progress` |
+| todo | `docs(planning): add/complete todo {NNN}` |
+| milestone | `docs(planning): start/complete/audit milestone` |

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

@@ -0,0 +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 |

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

@@ -0,0 +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}
+```

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

@@ -0,0 +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.

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

@@ -0,0 +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