@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plan-build-run/skills/scan/templates/mapper-prompt.md.tmpl

@@ -0,0 +1,201 @@
+<!-- Source: scan/SKILL.md | Purpose: Prompt template for spawning codebase-mapper agents during /pbr:map-codebase -->
+
+You are codebase-mapper with focus="{focus_area}".
+
+<reconnaissance>
+{recon_data}
+</reconnaissance>
+
+<project>
+Working directory: {project_path}
+Scale: {scale}
+</project>
+
+---
+
+## Scale-Aware Guidance
+
+### Small projects (< 50 files)
+- Be thorough — read most files
+- Output should be concise (don't pad)
+- Findings lists may be short — that's fine
+
+### Medium projects (50-200 files)
+- Sample representative files
+- Focus on entry points, configuration, and key modules
+- Use Grep patterns to find conventions rather than reading every file
+
+### Large projects (200-1000 files)
+- Be selective — read key files only
+- Use Glob and Grep extensively for pattern detection
+- Focus on architecture and module boundaries
+- Sample 3-5 files per module for conventions
+
+### Very large projects (1000+ files)
+- Limit file reads aggressively
+- Architecture focus > file-level detail
+- Sample at most 2-3 files per module
+
+---
+
+## Focus Area Instructions
+
+### If focus="tech"
+
+Analyze the codebase technology stack and external integrations.
+
+1. STACK.md — Technology inventory
+   - Languages and versions (from config files, shebang lines, etc.)
+   - Frameworks and their versions
+   - Build tools and configuration
+   - Package manager and dependency count
+   - Runtime requirements
+   - Development tools (linters, formatters, type checkers)
+
+2. INTEGRATIONS.md — External connections
+   - APIs consumed (look for HTTP clients, SDK imports, API keys)
+   - Databases used (look for connection strings, ORM configs, migrations)
+   - Third-party services (auth providers, payment, email, etc.)
+   - Message queues, caches, file storage
+   - CI/CD pipelines (GitHub Actions, Jenkins, etc.)
+   - Deployment targets (Docker, Kubernetes, serverless, etc.)
+
+Write both files to .planning/codebase/
+
+Read `templates/codebase/STACK.md.tmpl` for the STACK.md output format.
+Read `templates/codebase/INTEGRATIONS.md.tmpl` for the INTEGRATIONS.md output format.
+Fill in all placeholder fields with data from your codebase analysis.
+
+### If focus="arch"
+
+Analyze the codebase architecture and structure.
+
+1. ARCHITECTURE.md — High-level architecture
+   - Architecture style (monolith, microservices, serverless, MVC, etc.)
+   - Layer structure (presentation, business logic, data access)
+   - Module boundaries and how they communicate
+   - Data flow through the system
+   - Key abstractions and interfaces
+   - State management approach
+   - Error handling strategy
+   - Authentication/authorization architecture
+
+2. STRUCTURE.md — Directory and file organization
+   - Directory tree with annotations
+   - File naming conventions
+   - Module organization pattern
+   - Entry points and their roles
+   - Configuration file locations
+   - Environment-specific files
+
+Write both files to .planning/codebase/
+
+Read `templates/codebase/ARCHITECTURE.md.tmpl` for the ARCHITECTURE.md output format.
+Read `templates/codebase/STRUCTURE.md.tmpl` for the STRUCTURE.md output format.
+Fill in all placeholder fields with data from your codebase analysis.
+
+### If focus="quality"
+
+Analyze the codebase quality, conventions, and testing approach.
+
+1. CONVENTIONS.md — Coding standards in practice
+   - Naming conventions (files, functions, variables, classes)
+   - Code style (indentation, quotes, semicolons, etc.)
+   - Import/export patterns
+   - Comment style and documentation patterns
+   - Error handling patterns
+   - Logging patterns
+   - Configuration patterns (env vars, config files, constants)
+
+   IMPORTANT: Document what the codebase ACTUALLY does, not what it should do.
+   Look at multiple files to identify the dominant pattern.
+
+2. TESTING.md — Test infrastructure and coverage
+   - Test framework(s) used
+   - Test file organization
+   - Test types present (unit, integration, e2e)
+   - Test coverage (rough estimate from test file count vs source file count)
+   - Mocking patterns
+   - Test data management
+   - CI test configuration
+   - Notable gaps in testing
+
+Write both files to .planning/codebase/
+
+Read `templates/codebase/CONVENTIONS.md.tmpl` for the CONVENTIONS.md output format.
+Read `templates/codebase/TESTING.md.tmpl` for the TESTING.md output format.
+Fill in all placeholder fields with data from your codebase analysis.
+
+### If focus="concerns"
+
+Identify concerns, risks, and improvement opportunities in the codebase.
+
+Write CONCERNS.md to .planning/codebase/
+
+Analyze the codebase for:
+
+1. Security concerns
+   - Hardcoded secrets or credentials
+   - Injection vulnerabilities
+   - Insecure authentication patterns
+   - Missing input validation
+   - Outdated dependencies with known vulnerabilities
+
+2. Technical debt
+   - TODO/FIXME/HACK comments
+   - Dead code (unused exports, unreachable branches)
+   - Copy-pasted code (duplication)
+   - Overly complex functions
+   - Missing error handling
+   - Inconsistent patterns
+
+3. Scalability concerns
+   - N+1 query patterns
+   - Missing pagination
+   - Unbounded data loading
+   - Synchronous blocking operations
+   - Missing caching opportunities
+
+4. Maintainability concerns
+   - Missing documentation
+   - Complex inheritance hierarchies
+   - Tight coupling between modules
+   - Magic numbers/strings
+   - Missing type safety
+
+5. Operational concerns
+   - Missing health checks
+   - Insufficient logging
+   - No monitoring hooks
+   - Unclear deployment process
+
+Read `templates/codebase/CONCERNS.md.tmpl` for the CONCERNS.md output format.
+Fill in all placeholder fields with data from your codebase analysis.
+
+---
+
+## Reconnaissance Detection Reference
+
+### Project Type Detection
+Look for:
+- package.json -> Node.js/JavaScript/TypeScript
+- requirements.txt / setup.py / pyproject.toml -> Python
+- CMakeLists.txt -> C/C++
+- go.mod -> Go
+- Cargo.toml -> Rust
+- pom.xml / build.gradle -> Java
+- *.sln / *.csproj -> .NET
+- Gemfile -> Ruby
+- composer.json -> PHP
+
+### Key Directory Detection
+Look for:
+- src/, lib/, app/ -> source code
+- test/, tests/, __tests__/, spec/ -> tests
+- docs/ -> documentation
+- config/, .config/ -> configuration
+- scripts/ -> build/deploy scripts
+- public/, static/, assets/ -> static assets
+- migrations/ -> database migrations
+
+Write output to: {output_path}

package/plan-build-run/skills/session-report/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: session-report
+description: "Generate post-session summary with work performed, outcomes, and resource usage."
+allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
+argument-hint: "[--since <time>] [--save]"
+---
+
+**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Begin executing Step 1 immediately.**
+
+# /pbr:session-report -- Post-Session Summary
+
+**References:** `@references/ui-brand.md`
+
+You are the orchestrator for `/pbr:session-report`. This read-only skill generates a summary of work performed during the current session. By default it displays the report without writing files.
+
+## Step 0 -- Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
++--------------------------------------------------------------+
+|  PLAN-BUILD-RUN > SESSION REPORT                             |
++--------------------------------------------------------------+
+```
+
+Then proceed to Step 1.
+
+## Step 1: Parse Arguments
+
+1. Parse `$ARGUMENTS` for optional flags:
+   - `--since <time>` -- git log time filter (default: "8 hours ago")
+   - `--save` -- write report to `.planning/reports/session-{date}.md`
+2. Compute the time window for analysis
+
+## Step 2: Gather Session Data
+
+1. Read `.planning/STATE.md` for current position (phase, plan, status)
+2. Count commits in time window:
+   ```bash
+   git log --oneline --since="{since}" --format="%H %s"
+   ```
+3. Get file change stats:
+   ```bash
+   git diff --stat HEAD~{commit_count}..HEAD 2>/dev/null || git diff --stat --since="{since}"
+   ```
+4. Read SUMMARY-*.md files modified during this session:
+   ```bash
+   git log --since="{since}" --diff-filter=AM --name-only --format="" -- ".planning/phases/*/SUMMARY-*.md"
+   ```
+   Extract status and key outcomes from each.
+5. Check for VERIFICATION.md updates:
+   ```bash
+   git log --since="{since}" --diff-filter=AM --name-only --format="" -- ".planning/phases/*/VERIFICATION.md"
+   ```
+6. Check test results if a test command was run recently:
+   ```bash
+   git log --since="{since}" --oneline --grep="test"
+   ```
+
+## Step 3: Compute Metrics
+
+1. **Commit breakdown**: count commits by type (feat, fix, refactor, test, docs, chore)
+2. **File breakdown**: count files by directory/category
+3. **Phase progress**: compare STATE.md current plan vs total plans
+4. **Velocity**: commits per hour estimate
+
+## Step 4: Generate Report
+
+Display the report:
+
+```
+SESSION REPORT
+==============
+
+Session Window:  {since} to now ({duration} estimate)
+Current Phase:   {phase_number} - {phase_name}
+Current Status:  {status}
+
+WORK PERFORMED
+--------------
+Commits:         {total_count}
+  feat:          {feat_count}
+  fix:           {fix_count}
+  refactor:      {refactor_count}
+  test:          {test_count}
+  other:         {other_count}
+
+Files Changed:   {file_count}
+  Insertions:    +{insertions}
+  Deletions:     -{deletions}
+
+PLAN PROGRESS
+-------------
+{For each SUMMARY written during session:}
+  Plan {NN}: {status} - {one-liner}
+
+VERIFICATION
+------------
+{If VERIFICATION.md was updated:}
+  Score:         {score}
+  Status:        {status}
+{Else:}
+  No verification updates this session.
+
+NEXT STEPS
+----------
+{Based on STATE.md status, suggest the logical next command:}
+  - If status is "planned": /pbr:build {N}
+  - If status is "executing": /pbr:build {N} (continue)
+  - If status is "verifying": /pbr:review {N}
+  - If status is "complete": /pbr:milestone or /pbr:plan {N+1}
+```
+
+## Step 5: Optional Save
+
+If `--save` flag was provided:
+1. Create directory: `.planning/reports/` (if not exists)
+2. Write report to `.planning/reports/session-{YYYY-MM-DD-HHmm}.md`
+3. Display: "Report saved to {path}"
+
+If `--save` was NOT provided:
+- Display only. Do not write any files.
+
+## Error Handling
+
+- No commits in time window: "No commits found since {since}. Try --since '24 hours ago'."
+- No STATE.md: "No .planning directory found. Run /pbr:new-project first."
+- Git not available: stop with error

package/plan-build-run/skills/setup/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: setup
+description: "Reconfigure an existing Plan-Build-Run project (models, features, CLAUDE.md)."
+allowed-tools: Read, Write, Bash, Glob, AskUserQuestion
+---
+
+**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, context_window_tokens=200000, agent_checkpoint_pct=50, extended_context=false
+- **Quality**: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet, context_window_tokens=1000000, agent_checkpoint_pct=65, extended_context=true
+- **Budget**: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku, context_window_tokens=200000, agent_checkpoint_pct=50, extended_context=false
+- **Keep current**: no change to models block, no change to context_window_tokens
+
+---
+
+## 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.
+
+### Commit Changes
+
+Reference: `skills/shared/commit-planning-docs.md` for the commit pattern.
+
+If `planning.commit_docs` is true in config.json, commit modified files:
+
+```text
+docs(setup): reconfigure project — {changed_settings}
+```
+
+---
+
+## 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/plan-build-run/skills/shared/agent-type-resolution.md

@@ -0,0 +1,20 @@
+# Agent Type Resolution
+
+PBR agents register under two naming formats depending on how the plugin loads:
+
+- **Plugin format**: `pbr:{name}` (e.g., `pbr:executor`) — when Claude Code loads agents from the plugin's `agents/` directory
+- **Standalone format**: `pbr-{name}` (e.g., `pbr-executor`) — when agents load from a root `agents/` directory
+
+**Resolution rule**: Always use `pbr:{name}` first. If the Task() spawn fails with "Agent type not found", retry the same Task() call with `pbr-{name}`. Do not change anything else in the prompt — only the `subagent_type` value.
+
+Example:
+
+```
+# First attempt (plugin format)
+Task({ subagent_type: "pbr:executor", prompt: ... })
+
+# If "Agent type not found" error, retry with:
+Task({ subagent_type: "pbr-executor", prompt: ... })
+```
+
+This applies to ALL `pbr:*` agent spawns: executor, verifier, planner, researcher, synthesizer, debugger, codebase-mapper, plan-checker, integration-checker, intel-updater, audit, general, ui-checker, ui-researcher.

package/plan-build-run/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` |