@sienklogic/plan-build-run 2.54.0 → 2.55.0

package/plugins/codex-pbr/skills/scan/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: scan
+description: "Analyze an existing codebase. Maps structure, architecture, conventions, and concerns."
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SCANNING CODEBASE                          ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+# $pbr-scan — Codebase Analysis
+
+You are running the **scan** skill. Your job is to analyze an existing codebase and produce a comprehensive map of its structure, architecture, conventions, and concerns. This is the entry point for brownfield projects — codebases that already have code before Plan-Build-Run is introduced.
+
+This skill **spawns 4 parallel Task(subagent_type: "pbr:codebase-mapper")** agents for analysis.
+
+---
+
+## Context Budget
+
+Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+
+Additionally for this skill:
+- **Never** analyze the codebase yourself — delegate ALL analysis to the 4 parallel codebase-mapper agents
+- **Minimize** reading mapper outputs — read only frontmatter or first 20 lines of each output document
+- **Delegate** all file reading, pattern analysis, and architecture mapping to the codebase-mapper agents
+
+---
+
+## Core Principle
+
+**Understand before you change.** Scanning a codebase is about building a mental model of what exists. Every file produced by this skill becomes context that the planner and executor use to make informed decisions. Accuracy matters more than speed.
+
+---
+
+## Flow
+
+### Step 1: Check for Existing Analysis
+
+Check if `.planning/codebase/` directory exists:
+
+**If it exists and has files:**
+
+First, resolve the depth profile so you know which areas are available:
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
+```
+Read `profile["scan.mapper_areas"]` to determine available areas (quick: tech, arch; standard/comprehensive: tech, arch, quality, concerns).
+
+Then present to user via AskUserQuestion:
+  ```
+  A codebase analysis already exists (from {date based on file modification}).
+
+  Files found:
+  - {list of .md files in the directory}
+
+  Options:
+  1. Refresh the full analysis (overwrites existing)
+  2. Refresh a specific area ({list available areas from depth profile})
+  3. Keep existing analysis
+  ```
+- If user chooses "Keep": display a summary of existing analysis and stop
+- If user chooses "Refresh specific": present the available areas based on the already-resolved depth profile (quick mode only offers tech/arch; standard/comprehensive offers all 4). Only spawn the selected agent. Skip re-resolving depth in Step 3 since it was already resolved here.
+- If user chooses "Refresh all": proceed with full scan
+
+**If it doesn't exist:**
+- Create `.planning/codebase/` directory
+- Also create `.planning/` if it doesn't exist (scan can be run before begin)
+- Proceed with full scan
+
+### Step 2: Initial Reconnaissance
+
+Reference: `skills/shared/context-loader-task.md` (Scan Reconnaissance variation) for the underlying pattern.
+
+Before spawning agents, do a quick scan to identify what we're working with. This gives agents better context.
+
+1. **Detect project type** — check for language-specific config files (package.json, requirements.txt, go.mod, Cargo.toml, etc.)
+2. **Detect project scale** — count source files (exclude node_modules, venv, .git, build, dist). Categories: Small (<50), Medium (50-200), Large (200-1000), Very Large (1000+)
+3. **Detect key directories** — identify src, test, docs, config, scripts, public, migrations directories
+4. **Read existing docs** — README.md, architecture docs, .env.example
+5. **Write `.planning/codebase/RECON.md`** with project type, scale, key directories, entry points, and quick stats
+
+Refer to the "Reconnaissance Detection Reference" section of `skills/scan/templates/mapper-prompt.md.tmpl` for the full detection checklists.
+
+### Step 3: Spawn Analysis Agents
+
+**Resolve mapper configuration:** Before spawning, resolve the depth profile:
+```bash
+node ${PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
+```
+
+Read `profile["scan.mapper_count"]` and `profile["scan.mapper_areas"]` to determine how many mappers to spawn and which focus areas to cover.
+
+**Default mappings by depth:**
+- `quick` (budget): 2 mappers -- `tech` and `arch` only. Produces STACK.md, INTEGRATIONS.md, ARCHITECTURE.md, STRUCTURE.md. Skips quality and concerns analysis.
+- `standard` (balanced): 4 mappers -- all areas. Full analysis.
+- `comprehensive` (thorough): 4 mappers -- all areas. Full analysis.
+
+Display to the user:
+```
+◐ Spawning {mapper_count} codebase mapper(s) in parallel...
+  → Technology stack analysis
+  → Architecture patterns
+  → Code quality assessment
+  → Concerns & risks
+```
+
+(Only list the focus areas that will actually be spawned based on the depth profile.)
+
+Spawn `{mapper_count}` parallel `Task(subagent_type: "pbr:codebase-mapper")` agents, one for each area in `scan.mapper_areas`. All should be spawned in a single response for maximum parallelism.
+
+For each agent, read `skills/scan/templates/mapper-prompt.md.tmpl` and fill in the placeholders:
+- `{focus_area}`: one of `tech`, `arch`, `quality`, `concerns`
+- `{project_path}`: the working directory
+- `{recon_data}`: contents of RECON.md
+- `{scale}`: detected scale from Step 2
+- `{output_path}`: `.planning/codebase/`
+
+**Prepend this block to each mapper prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/codebase/RECON.md — baseline reconnaissance data (if exists)
+</files_to_read>
+```
+
+| Agent | Focus | Output Files | When |
+|-------|-------|-------------|------|
+| 1 | tech | STACK.md, INTEGRATIONS.md | Always |
+| 2 | arch | ARCHITECTURE.md, STRUCTURE.md | Always |
+| 3 | quality | CONVENTIONS.md, TESTING.md | standard + comprehensive |
+| 4 | concerns | CONCERNS.md | standard + comprehensive |
+
+### Step 4: Wait for Agents
+
+All agents run in parallel. As each completes, display:
+```
+✓ Technology stack analysis complete
+✓ Architecture patterns complete
+✓ Code quality assessment complete
+✓ Concerns & risks complete
+```
+
+(Only display lines for the focus areas that were actually spawned.)
+
+### Step 4b: Check Completion Markers
+
+After each codebase-mapper Task() completes, check the Task() output for the `## MAPPING COMPLETE` marker:
+
+- If `## MAPPING COMPLETE` is present: the mapper finished successfully, proceed normally
+- If the marker is missing: warn the user that the mapper may not have completed successfully:
+  ```
+  ⚠ Codebase mapper ({focus_area}) did not report MAPPING COMPLETE.
+  Output may be incomplete — check .planning/codebase/ for partial results.
+  ```
+  Continue to Step 5 verification regardless (the file existence checks will catch truly missing output).
+
+### Step 5: Verify Output
+
+After all agents complete, verify the expected files exist:
+
+**Required files (always):**
+- `.planning/codebase/RECON.md` (created in Step 2)
+- `.planning/codebase/STACK.md` (tech mapper)
+- `.planning/codebase/INTEGRATIONS.md` (tech mapper)
+- `.planning/codebase/ARCHITECTURE.md` (arch mapper)
+- `.planning/codebase/STRUCTURE.md` (arch mapper)
+
+**Required files (standard + comprehensive only):**
+- `.planning/codebase/CONVENTIONS.md` (quality mapper)
+- `.planning/codebase/TESTING.md` (quality mapper)
+- `.planning/codebase/CONCERNS.md` (concerns mapper)
+
+Check only the files that correspond to the mapper areas that were actually spawned.
+
+For any missing files, display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Missing analysis output: {filename}
+Agent that failed: {focus_area} mapper
+
+**To fix:** Re-run with `$pbr-scan` and select "Refresh a specific area" → {focus_area}.
+```
+
+### Step 6: Present Summary
+
+Read key findings from each file (frontmatter or first section) and display using the branded stage banner from `references/ui-formatting.md`:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SCAN COMPLETE ✓                            ║
+╚══════════════════════════════════════════════════════════════╝
+
+Project: {type} ({scale})
+Stack: {primary language} + {framework}
+Architecture: {style}
+
+Key Stats:
+- {file count} source files, {test count} test files
+- {dependency count} dependencies
+- {integration count} external integrations
+
+Full analysis: .planning/codebase/
+```
+
+**Concerns section** (only display if ALL of these conditions are true: (1) the concerns mapper was included in `scan.mapper_areas` for the resolved depth profile, (2) the concerns mapper was actually spawned, AND (3) `.planning/codebase/CONCERNS.md` exists and contains at least one concern entry). If any condition is false, skip this entire section silently — do NOT display an empty concerns block or a "no concerns" message:
+
+```
+Concerns: {critical} critical, {high} high, {medium} medium
+
+Top concerns:
+1. {most critical concern}
+2. {second concern}
+3. {third concern}
+```
+
+Then use the "Next Up" routing block:
+```
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Start a project** — use the scan results to plan your work
+
+`$pbr-begin`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `$pbr-milestone new` — create a milestone to address concerns
+- `$pbr-status` — see project status
+
+
+```
+
+### Step 7: Git Integration
+
+Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
+
+If `.planning/config.json` exists and `planning.commit_docs: true`:
+
+```bash
+git add .planning/codebase/
+git commit -m "docs(planning): map existing codebase"
+```
+
+If no config exists yet (scan before begin), use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
+  question: "Commit the codebase analysis to git?"
+  header: "Commit?"
+  options:
+    - label: "Yes"  description: "Stage and commit .planning/codebase/ files"
+    - label: "No"   description: "Skip commit — files are saved but not committed"
+- If "Yes": run `git add .planning/codebase/ && git commit -m "docs(planning): map existing codebase"`
+- If "No" or "Other": skip commit
+
+---
+
+## Edge Cases
+
+### Monorepo with multiple projects
+- Detect by multiple package.json, separate src directories, workspace config
+- Ask user via AskUserQuestion: "This looks like a monorepo. Scan the whole repo or a specific project?"
+- If specific: scope all agents to that subdirectory
+- If whole: note the monorepo structure in ARCHITECTURE.md
+
+### Empty or near-empty codebase
+- If fewer than 5 source files: "This codebase is very small. A scan may not be necessary."
+- Still allow it if user wants
+- Output will be minimal
+
+### No source code (config-only repo, docs repo)
+- Detect: no recognized source file extensions
+- Adapt: focus on documentation quality, config structure
+- Skip code quality analysis
+
+### Codebase has existing analysis
+- Check for architectural docs, ADRs, design docs
+- Reference them in the scan output
+- Don't contradict existing docs without strong evidence
+
+### Binary files, large assets
+- Skip binary files in analysis
+- Note their existence in STRUCTURE.md
+- Flag large committed binaries as a concern
+
+### Scan before $pbr-begin
+- This is a valid and encouraged workflow
+- Scan results become input for the begin skill
+- Create `.planning/` and `.planning/codebase/` if needed
+- Don't require config.json
+
+---
+
+## Anti-Patterns
+
+Reference: `skills/shared/universal-anti-patterns.md` for rules that apply to ALL skills.
+
+Additionally for this skill:
+
+1. **DO NOT** modify any source code — scan is read-only analysis
+2. **DO NOT** run the project (no `npm start`, `python app.py`, etc.) — analyze statically
+3. **DO NOT** install dependencies — analyze package files, don't install
+4. **DO NOT** generate concerns without evidence — every concern needs a file reference
+5. **DO NOT** ignore positive observations — knowing what works well is valuable
+6. **DO NOT** produce generic output — every finding should be specific to THIS codebase
+7. **DO NOT** scan node_modules, venv, .git, or build output directories
+8. **DO NOT** read every file in large codebases — sample and extrapolate
+9. **DO NOT** skip the RECON step — agents need baseline context
+10. **DO NOT** combine agents — the 4 agents must run in parallel with separate focuses

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

@@ -0,0 +1,169 @@
+---
+name: setup
+description: "Reconfigure an existing Plan-Build-Run project (models, features, CLAUDE.md)."
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes tokens. Begin executing Step 1 immediately.**
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► RECONFIGURE                                ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+# $pbr-setup — Plan-Build-Run Reconfigure
+
+You are running the **setup** skill in **reconfigure mode**. This wizard lets existing Plan-Build-Run projects change model profiles, workflow features, and CLAUDE.md integration. It does NOT re-initialize or overwrite project state.
+
+---
+
+## Step 1: Detect Project State
+
+Check if `.planning/config.json` exists.
+
+**If `.planning/config.json` does NOT exist:**
+Display:
+```
+No Plan-Build-Run project found in this directory.
+
+$pbr-setup is for reconfiguring existing projects.
+To start a new project, run: $pbr-begin
+
+$pbr-begin includes everything $pbr-setup used to do, plus deep requirements gathering and roadmap creation.
+```
+Stop. Do not proceed further.
+
+**If `.planning/config.json` exists:**
+- Read `.planning/config.json`
+- Display the current settings summary:
+  ```
+  Current configuration:
+  - Model profile: {derived from models block — balanced/quality/budget or custom}
+  - Depth: {depth}
+  - Mode: {mode}
+  - Auto-continue: {features.auto_continue}
+  - TDD mode: {features.tdd_mode}
+  - Git branching: {git.branching}
+  ```
+- Proceed to Step 2.
+
+---
+
+## Step 2: Model Selection
+
+Use AskUserQuestion:
+  question: "Which model profile should agents use?"
+  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."
+    - label: "Keep current"
+      description: "Leave model settings unchanged."
+
+Apply the selected profile to the models block in 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
+- **Keep current**: no change to models block
+
+---
+
+## Step 3: Workflow Features
+
+Use 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 (others unchanged):
+- **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: "phase"`
+
+---
+
+## Step 4: CLAUDE.md Integration
+
+Check if a `CLAUDE.md` file exists in the project root.
+
+**If it exists**: Read it. If it does NOT already contain a "Plan-Build-Run" section, offer to append the integration block.
+**If it does NOT exist**: Offer to create `CLAUDE.md` with the integration block.
+
+Use AskUserQuestion:
+  question: "Update CLAUDE.md with Plan-Build-Run integration notes?"
+  header: "CLAUDE.md"
+  options:
+    - label: "Yes"
+      description: "Add or update the Plan-Build-Run section in CLAUDE.md"
+    - label: "No"
+      description: "Skip — leave CLAUDE.md as-is"
+
+If "Yes", append/create:
+```markdown
+## Plan-Build-Run
+
+This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run) for structured development.
+
+- Project state: `.planning/STATE.md` (source of truth for current phase and progress)
+- Configuration: `.planning/config.json`
+- Run `$pbr-status` to see current project state and suggested next action.
+
+**After compaction or context recovery**: Read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
+```
+
+---
+
+## Step 5: Write Updated Config
+
+**CRITICAL: Write `.planning/config.json` NOW with all changes from Steps 2-3. Do NOT skip this step.**
+
+Write the updated config.json to disk with all applied changes.
+
+---
+
+## Step 6: Verification
+
+Run a quick check:
+1. Verify `.planning/config.json` is valid JSON (read it back)
+2. Display updated settings summary
+
+Display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► RECONFIGURE COMPLETE ✓                     ║
+╚══════════════════════════════════════════════════════════════╝
+
+Updated:
+- Model profile: {new profile}
+- Features changed: {list or "none"}
+- CLAUDE.md: {updated/skipped}
+
+Run $pbr-status to see current project state.
+```
+
+---
+
+## Error Handling
+
+- If config.json parse fails: Display the raw content and ask user to fix it manually, then retry
+- If config.json write fails: Display the JSON content and ask user to save it manually

package/plugins/codex-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 the format from the **Commit Messages by Skill** table below (most use `docs({scope}):` but some skills like pause use `wip(planning):`)
+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 | `wip(planning): save session state — phase {N} plan {M}` |
+| todo | `docs(planning): add/complete todo {NNN}` |
+| milestone | `docs(planning): start/complete/audit milestone` |

package/plugins/codex-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 ${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 |