scan

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 subagents
• 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 subagents

---

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:

node ${CLAUDE_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:

node ${CLAUDE_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: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:

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