@sienklogic/plan-build-run 2.0.2 → 2.1.1

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-map-codebase — 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 `${CLAUDE_SKILL_DIR}/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 `${CLAUDE_SKILL_DIR}/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-map-codebase` 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-brand.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-new-project`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `$pbr-new-milestone` — create a milestone to address concerns
+- `$pbr-progress` — 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-new-project
+- 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,235 @@
+---
+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-new-project
+
+$pbr-new-project 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
+
+Note: These profiles control agent models, not the orchestrator. The orchestrator uses your Claude Code session model. For cost optimization, consider running your session on Sonnet -- agents with `inherit` will follow. See `references/model-profiles.md` for details.
+
+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-progress` 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: Platform Settings
+
+Manage Claude Code platform settings that PBR recommends for optimal token usage.
+
+**Read `.planning/config.json`** (already loaded in Step 1). Check for a `platform_settings` block:
+- If absent, treat it as `{}` (no managed settings).
+
+**Check for existing `.claude/settings.json`**:
+- If it exists, read its contents. Parse as JSON (or `{}` if empty/missing).
+- If it does not exist, start from `{}`.
+
+**Compute the merge**:
+- Start with the existing `.claude/settings.json` content.
+- Apply each key from `platform_settings` in config.json on top.
+- If `platform_settings` is absent or empty, skip the write entirely.
+
+**Report drift** (compare before/after):
+- List keys being ADDED (were absent in .claude/settings.json)
+- List keys being CHANGED (differ from existing .claude/settings.json value)
+- List keys that MATCH (already correct — no change needed)
+
+Display the report:
+
+```
+Platform Settings:
+  Keys added:   includeGitInstructions → false
+  Keys matched: (none)
+  Keys changed: (none)
+
+Writing .claude/settings.json...
+```
+
+If all keys already match, display:
+
+```
+Platform Settings: .claude/settings.json is already in sync — no changes needed.
+```
+
+**Conflict detection**: If an existing `.claude/settings.json` has a key from `platform_settings` set to the OPPOSITE value (e.g., `"includeGitInstructions": true` when PBR wants `false`), display a WARNING before overwriting:
+
+```
+WARNING: .claude/settings.json has includeGitInstructions: true
+         PBR recommends false (removes redundant built-in git instructions).
+         Overwriting with PBR recommended value.
+```
+
+**Write the merged settings.json**:
+- Write to `.claude/settings.json` in the project root (alongside `.planning/`).
+- Ensure the directory `.claude/` exists (create it if needed with Bash `mkdir -p .claude`).
+- Write with 2-space indentation. Include a `$schema` key at the top:
+  ```json
+  {
+    "$schema": "https://json.schemastore.org/claude-code-settings.json",
+    "includeGitInstructions": false
+  }
+  ```
+  (Merge in any pre-existing keys from .claude/settings.json that are NOT managed by PBR — pass them through unchanged at the bottom of the object.)
+
+**Drift detection note**: On subsequent $pbr-setup runs, if `.claude/settings.json` has drifted from `platform_settings` (e.g., user manually changed it), this step will detect and re-apply the PBR values with a drift warning. This is by design — platform_settings in config.json is the source of truth.
+
+---
+
+## Step 6: 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 7: 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}
+- Platform settings: {".claude/settings.json updated" or "already in sync" or "no managed settings"}
+
+Run $pbr-progress 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,43 @@
+# 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
+```
+
+**Note:** CLI state commands (`state advance-plan`, `phase complete`, `state update-progress`) automatically update STATE.md and ROADMAP.md. The commit step here covers planning artifacts (PLAN.md, SUMMARY.md, VERIFICATION.md), not state files -- those are updated atomically by CLI commands.
+
+## Session Affinity
+
+When a session ID is available (from `.planning/.session.json`), append `[session:{short_id}]` to the commit description, where `short_id` is the first 8 characters of the session_id. This enables conflict tracing when multiple sessions modify planning docs concurrently.
+
+Example: `docs(planning): capture phase 3 discussion decisions [session:a1b2c3d4]`
+
+## 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` |