Step 0 — Immediate Output

Before ANY tool calls, display this banner:

code

╔══════════════════════════════════════════════════════════════╗
║  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:

code

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.

•Detect project type — check for language-specific config files (package.json, requirements.txt, go.mod, Cargo.toml, etc.)
•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+)
•Detect key directories — identify src, test, docs, config, scripts, public, migrations directories
•Read existing docs — README.md, architecture docs, .env.example
•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:

code

◐ 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/

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:

code

✓ 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 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:

code

╔══════════════════════════════════════════════════════════════╗
║  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:

code

╔══════════════════════════════════════════════════════════════╗
║  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:

code

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:

code


╔══════════════════════════════════════════════════════════════╗
║  ▶ 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:

•DO NOT modify any source code — scan is read-only analysis
•DO NOT run the project (no npm start, python app.py, etc.) — analyze statically
•DO NOT install dependencies — analyze package files, don't install
•DO NOT generate concerns without evidence — every concern needs a file reference
•DO NOT ignore positive observations — knowing what works well is valuable
•DO NOT produce generic output — every finding should be specific to THIS codebase
•DO NOT scan node_modules, venv, .git, or build output directories
•DO NOT read every file in large codebases — sample and extrapolate
•DO NOT skip the RECON step — agents need baseline context
•DO NOT combine agents — the 4 agents must run in parallel with separate focuses