/map-codebase

name: map-codebase
description: Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents
argument-hint: "[--fast [--focus tech|arch|quality|concerns]] [area]"
allowed-tools:
  - Read
  - Bash
  - Glob
  - Grep
  - Write
  - Task

Objective

Analyze existing codebase using parallel codebase-mapper agents to produce structured codebase documents.

Each mapper agent explores a focus area and **writes documents directly** to `.planning/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.

Output: `.planning/codebase/` folder with up to 7 structured documents about the codebase state.

Flags

• **--fast**: Lightweight scan mode — spawns one mapper agent instead of four. Accepts an optional `--focus` value: `tech`, `arch`, `quality`, `concerns`, or `tech+arch` (default). Faster and lower-context than the full map.
• **(no flag)**: Full parallel map — spawns 4 mapper agents to produce all 7 codebase documents.

Context

Arguments: $ARGUMENTS

Parse the first token of $ARGUMENTS:

• If it is `--fast`: strip the flag, run lightweight scan (passing remaining args including optional --focus).
• Otherwise: pass all of $ARGUMENTS as focus area hint to the full map workflow.

**Load project state if exists:** Check for `.planning/STATE.md` — loads context if project is already initialized.

**This command can run:**

• Before `/new-project` (brownfield codebases) — create codebase map first
• After `/new-project` (greenfield codebases) — update codebase map as code evolves
• Anytime to refresh codebase understanding

When to Use

**Use map-codebase for:**

• Brownfield projects before initialization (understand existing code first)
• Refreshing codebase map after significant changes
• Onboarding to an unfamiliar codebase
• Before major refactoring (understand current state)

**Skip map-codebase for:**

• Greenfield projects with no code yet (nothing to map)
• Trivial codebases (fewer than 5 files)

Process

**Full map (no flags):**

1. Check if `.planning/codebase/` already exists — if yes, offer to refresh or skip. 2. Create `.planning/codebase/` directory if it doesn't exist. 3. Spawn 4 parallel `codebase-mapper` agents:

• Agent 1: `tech` focus → writes `STACK.md`, `INTEGRATIONS.md`
• Agent 2: `arch` focus → writes `ARCHITECTURE.md`, `STRUCTURE.md`
• Agent 3: `quality` focus → writes `CONVENTIONS.md`, `TESTING.md`
• Agent 4: `concerns` focus → writes `CONCERNS.md`

4. Wait for all agents to complete, collect confirmations (NOT document contents). 5. Verify all 7 documents exist with line counts. 6. Present summary and suggest next steps (typically: `/new-project` or `/plan-phase`).

**Fast scan (--fast flag):**

1. Determine focus from `--focus` value (default: `tech+arch`). 2. Spawn a single `codebase-mapper` agent with the specified focus. 3. Wait for agent completion and report.

Success Criteria

• [ ] `.planning/codebase/` directory created
• [ ] All documents for chosen mode written by mapper agents
• [ ] Documents follow template structure (see `templates/` directory)
• [ ] Parallel agents completed without errors
• [ ] User knows next steps