@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/skills/review/templates/verifier-prompt.md.tmpl

@@ -112,4 +112,11 @@ must_haves_human: {count}
 {List of all commands executed with their results — for auditability}
 </instructions>
 
+**Verification depth:** {verification_depth}
+- light: Check L1 (existence) and basic frontmatter only. Skip L2/L3/L4 and anti-pattern scan. Budget: <=400 tokens output.
+- standard: Full 3-layer verification (L1-L3). Current default behavior.
+- thorough: Full 4-layer verification (L1-L4) + cross-phase regression check (even if context_window_tokens < 500000) + full anti-pattern scan.
+
+Include `verification_depth` in the VERIFICATION.md frontmatter.
+
 Use the Write tool to create the verification report. Use Bash, Grep, and Glob for checks.

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

@@ -18,7 +18,7 @@ allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
 
 Then proceed to Step 1.
 
-# /pbr:scan — Codebase Analysis
+# /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.
 
@@ -29,6 +29,7 @@ This skill **spawns 4 parallel Task(subagent_type: "pbr:codebase-mapper")** agen
 ## Context Budget
 
 Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.
 
 Additionally for this skill:
 - **Never** analyze the codebase yourself — delegate ALL analysis to the 4 parallel codebase-mapper subagents
@@ -45,66 +46,59 @@ Additionally for this skill:
 
 ## Flow
 
-### Step 1: Check for Existing Analysis
+### Step 1: Load Init Context
 
-Check if `.planning/codebase/` directory exists:
+Run the CLI to get scan metadata:
 
-**If it exists and has files:**
-
-First, resolve the depth profile so you know which areas are available:
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init map-codebase
 ```
-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}).
+Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`, `intel_enabled`, `has_intel_dir`, `depth_profile`.
 
-  Files found:
-  - {list of .md files in the directory}
+If the CLI fails, display a branded ERROR box: "Failed to load scan context. Ensure pbr-tools.js is available." and stop.
 
-  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
+### Step 2: Check for Existing Analysis
 
-**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
+Use `has_maps` from init context.
 
-### Step 2: Initial Reconnaissance
+**If `has_maps` is true:**
 
-Reference: `skills/shared/context-loader-task.md` (Scan Reconnaissance variation) for the underlying pattern.
+Present to user via AskUserQuestion:
 
-Before spawning agents, do a quick scan to identify what we're working with. This gives agents better context.
+  question: "A codebase analysis already exists. What would you like to do?"
+  header: "Scan"
+  options:
+    - label: "Refresh all"       description: "Delete existing and remap codebase"
+    - label: "Refresh specific"  description: "Re-scan only one area (tech, arch, quality, or concerns)"
+    - label: "Keep existing"     description: "Use existing codebase map as-is"
 
-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
+- If user chooses "Keep existing": display a summary of existing analysis and stop
+- If user chooses "Refresh specific": ask which area, then spawn only that agent in Step 4
+- If user chooses "Refresh all": proceed with full scan
 
-Refer to the "Reconnaissance Detection Reference" section of `skills/scan/templates/mapper-prompt.md.tmpl` for the full detection checklists.
+**If `has_maps` is false:**
+**CRITICAL: Create the codebase directory NOW. Do not skip this step.**
 
-### Step 3: Spawn Analysis Agents
+- Create `.planning/codebase/` directory if needed:
+  ```bash
+  mkdir -p .planning/codebase
+  ```
+- Also create `.planning/` if it doesn't exist (scan can be run before begin)
+- Proceed with full scan
 
-**Resolve mapper configuration:** Before spawning, resolve the depth profile:
-```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
-```
+### Step 3: Resolve Mapper Configuration
 
-Read `profile["scan.mapper_count"]` and `profile["scan.mapper_areas"]` to determine how many mappers to spawn and which focus areas to cover.
+Use `depth_profile` from init context to determine how many mappers to spawn and which focus areas.
 
 **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.
+- `quick`: 2 mappers — `tech` and `arch` only. Produces STACK.md, INTEGRATIONS.md, ARCHITECTURE.md, STRUCTURE.md.
+- `standard`: 4 mappers — all areas. Full analysis.
+- `comprehensive`: 4 mappers — all areas. Full analysis.
+
+**Extended context override:** If `features.extended_context` is `true` in `.planning/config.json`, always spawn 4 mappers regardless of depth profile.
+
+### Step 4: Spawn Analysis Agents
 
 Display to the user:
 ```
@@ -115,15 +109,13 @@ Display to the user:
   → Concerns & risks
 ```
 
-(Only list the focus areas that will actually be spawned based on the depth profile.)
+(Only list the focus areas that will actually be spawned.)
 
-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.
+Spawn `{mapper_count}` parallel `Task(subagent_type: "pbr:codebase-mapper")` agents, one for each focus area. 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:
+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/`
 
 | Agent | Focus | Output Files | When |
@@ -133,35 +125,29 @@ For each agent, read `skills/scan/templates/mapper-prompt.md.tmpl` and fill in t
 | 3 | quality | CONVENTIONS.md, TESTING.md | standard + comprehensive |
 | 4 | concerns | CONCERNS.md | standard + comprehensive |
 
-### Step 4: Wait for Agents
+### Step 5: Collect Results
 
-All agents run in parallel. As each completes, display:
-```
-✓ Technology stack analysis complete
-✓ Architecture patterns complete
-✓ Code quality assessment complete
-✓ Concerns & risks complete
-```
+As each agent completes, check the Task() output for the `## MAPPING COMPLETE` marker:
 
-(Only display lines for the focus areas that were actually spawned.)
+- If `## MAPPING COMPLETE` is present: display `✓ {focus_area} analysis complete`
+- If the marker is missing: warn:
+  ```
+  ⚠ Codebase mapper ({focus_area}) did not report MAPPING COMPLETE.
+  Output may be incomplete — check .planning/codebase/ for partial results.
+  ```
 
-### Step 5: Verify Output
+### Step 6: 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)
+```bash
+ls -la .planning/codebase/
+wc -l .planning/codebase/*.md
+```
 
-Check only the files that correspond to the mapper areas that were actually spawned.
+**Verification checklist:**
+- All expected documents exist (7 for standard/comprehensive, 4 for quick)
+- No empty documents (each should have >20 lines)
 
 For any missing files, display:
 ```
@@ -172,31 +158,56 @@ For any missing files, display:
 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}.
+**To fix:** Re-run with `/pbr:map-codebase` and select "Refresh a specific area" → {focus_area}.
+```
+
+### Step 7: Secret Scan
+
+**CRITICAL SECURITY CHECK:** Scan output files for accidentally leaked secrets before committing.
+
+```bash
+grep -E '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|sk_test_[a-zA-Z0-9]+|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]+|AKIA[A-Z0-9]{16}|xox[baprs]-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY|eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.)' .planning/codebase/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false
+```
+
+**If secrets found:**
 ```
+⚠ SECURITY ALERT: Potential secrets detected in codebase documents!
 
-### Step 6: Present Summary
+Found patterns that look like API keys or tokens in:
+{show grep output}
 
-Read key findings from each file (frontmatter or first section) and display using the branded stage banner from `references/ui-formatting.md`:
+This would expose credentials if committed.
+
+Action required:
+1. Review the flagged content above
+2. If these are real secrets, they must be removed before committing
+3. Reply "safe to proceed" if the flagged content is not actually sensitive
+```
+
+Wait for user confirmation before continuing.
+
+**If no secrets found:** Continue to Step 8.
+
+### Step 8: Present Summary
+
+Read key findings from each file (first section or frontmatter) and display:
 
 ```
 ╔══════════════════════════════════════════════════════════════╗
 ║  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/
+Created .planning/codebase/:
+- STACK.md ({N} lines) - Technologies and dependencies
+- INTEGRATIONS.md ({N} lines) - External services and APIs
+- ARCHITECTURE.md ({N} lines) - System design and patterns
+- STRUCTURE.md ({N} lines) - Directory layout and organization
+- CONVENTIONS.md ({N} lines) - Code style and patterns
+- TESTING.md ({N} lines) - Test structure and practices
+- CONCERNS.md ({N} lines) - Technical debt and issues
 ```
 
-**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 section** (only display if concerns mapper was spawned AND CONCERNS.md exists with content):
 
 ```
 Concerns: {critical} critical, {high} high, {medium} medium
@@ -207,48 +218,84 @@ Top concerns:
 3. {third concern}
 ```
 
-Then use the "Next Up" routing block:
-```
+### Step 9: Seed Intel System
 
+If `intel_enabled` is true from init context:
 
-╔══════════════════════════════════════════════════════════════╗
-║  ▶ NEXT UP                                                   ║
-╚══════════════════════════════════════════════════════════════╝
-
-**Start a project** — use the scan results to plan your work
+Display:
+```
+Seeding intel system from scan results...
+```
 
-`/pbr:begin`
+Spawn a `Task(subagent_type: "pbr:intel-updater")` with prompt:
 
-<sub>`/clear` first → fresh context window</sub>
+```
+Seed the intel system from fresh codebase scan results.
 
+Read these files and extract structured intelligence:
+- .planning/codebase/STACK.md → update .planning/intel/stack.json
+- .planning/codebase/ARCHITECTURE.md → update .planning/intel/arch.md
+- .planning/codebase/INTEGRATIONS.md → update .planning/intel/deps.json
+- .planning/codebase/STRUCTURE.md → update .planning/intel/files.json
 
+For each intel file:
+1. Read the codebase analysis document
+2. Extract structured data (dependencies, file graph, API endpoints, architecture patterns)
+3. Write/update the intel JSON/MD file
 
-**Also available:**
-- `/pbr:milestone new` — create a milestone to address concerns
-- `/pbr:status` — see project status
+Update .planning/intel/.last-refresh.json with current timestamp and source: "scan".
+```
 
+When the intel agent completes, display: `✓ Intel system seeded from scan results`
 
-```
+If `intel_enabled` is false: skip silently.
 
-### Step 7: Git Integration
+### Step 10: Git Integration
 
 Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
 
-If `.planning/config.json` exists and `planning.commit_docs: true`:
+If `commit_docs` is true from init context:
 
 ```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`):
+If no config exists yet (scan before begin):
+Use AskUserQuestion (pattern: yes-no):
   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
+- If "No": skip commit
+
+### Step 11: Next Steps
+
+```
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ 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:intel` — query codebase intelligence
+- `/pbr:new-milestone` — create a milestone to address concerns
+- `/pbr:progress` — see project status
+
+
+```
 
 ---
 
@@ -280,7 +327,7 @@ If no config exists yet (scan before begin), use AskUserQuestion (pattern: yes-n
 - Note their existence in STRUCTURE.md
 - Flag large committed binaries as a concern
 
-### Scan before /pbr:begin
+### 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
@@ -290,8 +337,6 @@ If no config exists yet (scan before begin), use AskUserQuestion (pattern: yes-n
 
 ## 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
@@ -302,5 +347,5 @@ Additionally for this skill:
 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
+9. **DO NOT** combine agents — the agents must run in parallel with separate focuses
+10. **DO NOT** skip the secret scan — leaked credentials in committed docs are a security incident

package/plugins/pbr/skills/scan/templates/mapper-prompt.md.tmpl

@@ -1,40 +1,12 @@
-<!-- Source: scan/SKILL.md | Purpose: Prompt template for spawning codebase-mapper agents during /pbr:scan -->
+<!-- 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
+Analyze this codebase for your focus area. Explore thoroughly. Write documents directly to `.planning/codebase/` using templates. Return confirmation only.
 
 ---
 
@@ -86,7 +58,7 @@ Analyze the codebase architecture and structure.
    - Module organization pattern
    - Entry points and their roles
    - Configuration file locations
-   - Environment-specific files
+   - **Where to add new code** — prescriptive guidance for each code type
 
 Write both files to .planning/codebase/
 
@@ -109,13 +81,14 @@ Analyze the codebase quality, conventions, and testing approach.
 
    IMPORTANT: Document what the codebase ACTUALLY does, not what it should do.
    Look at multiple files to identify the dominant pattern.
+   Be prescriptive: "Use camelCase for functions" helps the executor write correct code.
 
 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
+   - Mocking patterns (include actual code examples)
    - Test data management
    - CI test configuration
    - Notable gaps in testing
@@ -174,28 +147,4 @@ 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/plugins/pbr/skills/seed/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: seed
+description: "Plant forward-looking ideas with trigger conditions that auto-surface at the right milestone."
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+argument-hint: "<idea description>"
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it.**
+
+# /pbr:seed — Plant Ideas for Future Milestones
+
+Capture a forward-looking idea with trigger conditions. Seeds auto-surface during `/pbr:new-milestone` when trigger conditions match the new milestone's scope.
+
+Seeds beat deferred items because they preserve WHY, define WHEN, and auto-present.
+
+## Step 0 — Banner
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SEED                                       ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+## Step 1 — Parse Idea
+
+If `$ARGUMENTS` is empty, ask: "What's the idea? (one sentence)"
+
+## Step 2 — Gather Context
+
+Ask focused questions:
+
+1. **Trigger**: "When should this surface? (e.g., 'when we add user accounts', 'next major version')"
+2. **Why**: "Why does this matter? What problem does it solve?"
+3. **Scope**: Small (quick task) / Medium (phase or two) / Large (full milestone)
+
+## Step 3 — Collect Breadcrumbs
+
+Search codebase for related files. Check STATE.md decisions, ROADMAP.md phases, todos.
+
+## Step 4 — Write Seed
+
+```bash
+mkdir -p .planning/seeds
+```
+
+Find next seed number. Write `.planning/seeds/SEED-{NNN}-{slug}.md`:
+
+```markdown
+---
+id: SEED-{NNN}
+status: dormant
+planted: {ISO date}
+planted_during: {current milestone/phase}
+trigger_when: "{trigger}"
+scope: "{small|medium|large}"
+---
+
+# SEED-{NNN}: {idea}
+
+## Why This Matters
+{why}
+
+## When to Surface
+**Trigger:** {trigger}
+
+## Breadcrumbs
+{related files and references}
+```
+
+## Step 5 — Report
+
+```
+Seed planted: SEED-{NNN} — {idea}
+Trigger: {trigger}
+```
+
+## Integration with /pbr:new-milestone
+
+The new-milestone skill should scan `.planning/seeds/` and present matches:
+1. Read each seed's `trigger_when` field
+2. Compare against the new milestone's name/scope/goals
+3. Present matching seeds to the user for inclusion
+
+## Anti-Patterns
+
+1. DO NOT plant seeds for immediate work — use todos or backlog instead
+2. DO NOT auto-activate seeds — always present to user during milestone creation