---
name: map
description: Analyze existing codebase for brownfield project support
disable-model-invocation: false
---
# /mz:map
Analyze an existing codebase by spawning parallel mapper agents that produce structured analysis documents. Enables brownfield project onboarding by understanding architecture, tech stack, code quality, and concerns.
Reference `@skills/init/design-system.md` for visual output formatting.
Reference `@skills/map/mapper.md` for agent spawning patterns.
## Step 1: Display Banner
Output the stage banner:
```
╔═══════════════════════════════════════════════╗
║ ⚡ MEGAZORD ► MAP ║
╚═══════════════════════════════════════════════╝
```
## Step 2: Load Context
Read `.planning/megazord.config.json`. If missing, display an error box and stop:
```
╔═══════════════════════════════════════════════╗
║ ✗ Project Not Initialized ║
╠═══════════════════════════════════════════════╣
║ No megazord.config.json found. ║
║ Run /mz:init to set up your project first. ║
╚═══════════════════════════════════════════════╝
```
If config exists, continue loading:
- Read `.planning/megazord.config.json` for project settings.
Determine the plugin path:
1. Read `plugin_path` from the config JSON.
2. If `plugin_path` is not set in config, try `~/.claude/plugins/mz`. Check if `~/.claude/plugins/mz/bin/megazord.mjs` exists.
3. If neither exists, display error and stop:
> Plugin path not configured. Run `/mz:settings` and set `plugin_path`, or re-run `/mz:init`.
Parse the user's message for arguments:
- Optional focus parameter: `/mz:map architecture`, `/mz:map tech`, etc.
- Map focus aliases to canonical names:
- `arch` -> `architecture`
- `conventions` -> `quality`
- Valid focus values: `tech`, `architecture`, `quality`, `concerns`
- Default (no argument): run all 4 areas
Display the target:
```
▸ Target
{focus area name, or "All areas" if no focus specified}
```
## Step 3: Check Existing Map
Check if `.planning/codebase/` directory exists and contains analysis documents.
Use Bash to check: `ls .planning/codebase/*.md 2>/dev/null | wc -l`
**If existing documents found AND no focus parameter was given:**
Use AskUserQuestion to offer 3 options:
- header: "Remap" (5 chars)
- question: "Existing codebase analysis found. What would you like to do?"
- options:
1. "Refresh" -- delete existing, remap all areas from scratch
2. "Update" -- keep existing docs, remap all areas (overwrites)
3. "Skip" -- use existing analysis as-is
Handle each choice:
- **Refresh:** Delete the `.planning/codebase/` directory and recreate it: `rm -rf .planning/codebase/`
- **Update:** Proceed to mapping (agents will overwrite existing files)
- **Skip:** Display "Using existing codebase analysis." and exit
**If existing documents found AND focus parameter was given:**
Use AskUserQuestion:
- header: "Remap" (5 chars)
- question: "Existing analysis found for this area. Update it?"
- options:
1. "Update" -- remap this specific area (overwrites existing)
2. "Skip" -- use existing analysis as-is
Handle each choice:
- **Update:** Proceed to mapping the focused area only
- **Skip:** Display "Using existing analysis." and exit
**If no existing documents:** Proceed to mapping.
## Step 4: Create Output Directory
```bash
mkdir -p .planning/codebase/
```
## Step 5: Spawn Mapper Agents
Read the mapper agent definition ONCE and reuse for all spawns:
```
Read {plugin_path}/agents/mz-mapper.md -> mapper_instructions
```
### Resolve Model for Mapper Agents
Before spawning, determine the model for mapper agents:
1. Read `model_profile` and `model_overrides` from the loaded config.
2. Determine the mapper model: check if `model_overrides.mapper` is set and not `"inherit"`. If so, use that value. Otherwise, use the profile mapping: quality->opus, balanced->sonnet, budget->haiku.
3. Update `{plugin_path}/agents/mz-mapper.md` frontmatter `model` field to the resolved value. Use simple string replacement to rewrite the `model: {value}` line.
For each selected focus area, spawn one Task tool agent. Spawn ALL agents in parallel (or just the focused one if a focus parameter was given).
For each agent, the Task prompt must include:
- The focus area in `<focus>` tags
- The output directory in `<output_dir>` tags
- Specific instructions for what documents to write
**Important:** Use `subagent_type="mz-mapper"` for all agents. The agent definition is loaded from the registered agent file (frontmatter already updated with the resolved model). See `@skills/map/mapper.md` for the exact prompt structure.
**Fallback:** If spawning with `subagent_type="mz-mapper"` fails, fall back to `subagent_type="general-purpose"` with the agent definition embedded inline in `<agent_role>` tags.
Display progress for each active agent:
```
▸ Mapping
◆ Mapping tech...
◆ Mapping architecture...
◆ Mapping quality...
◆ Mapping concerns...
```
Wait for all agents to complete.
After completion, verify that expected output files exist. Use Bash to check file presence and line counts -- do NOT read the file content:
```bash
wc -l .planning/codebase/STACK.md .planning/codebase/INTEGRATIONS.md .planning/codebase/ARCHITECTURE.md .planning/codebase/STRUCTURE.md .planning/codebase/CONVENTIONS.md .planning/codebase/TESTING.md .planning/codebase/CONCERNS.md 2>/dev/null
```
Update the progress display with results:
```
▸ Mapping
✓ tech (STACK.md, INTEGRATIONS.md)
✓ architecture (ARCHITECTURE.md, STRUCTURE.md)
✓ quality (CONVENTIONS.md, TESTING.md)
✓ concerns (CONCERNS.md)
```
If any expected files are missing, display a warning but continue:
```
⚠ Missing: {filename} -- agent may have failed
```
## Step 6: Synthesis
**Only run synthesis when ALL 4 areas were mapped** (not on focused single-area runs).
Spawn the synthesis agent (model is already set from the frontmatter update in Step 5):
```
Task(
prompt="<focus>synthesis</focus>
<output_dir>.planning/codebase/</output_dir>
<instructions>Read all 7 documents in .planning/codebase/ (STACK.md, INTEGRATIONS.md,
ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md, CONCERNS.md).
Produce a compact executive SUMMARY.md with cross-cutting insights.
Write SUMMARY.md to the output directory. Return confirmation only.</instructions>",
subagent_type="mz-mapper",
description="Map codebase: synthesis"
)
```
**Fallback:** If spawning with `subagent_type="mz-mapper"` fails, fall back to `subagent_type="general-purpose"` with the agent definition embedded inline in `<agent_role>` tags.
Display:
```
▸ Synthesis
◆ Synthesizing findings...
```
Wait for completion, then verify SUMMARY.md exists:
```bash
wc -l .planning/codebase/SUMMARY.md 2>/dev/null
```
Update display:
```
▸ Synthesis
✓ SUMMARY.md produced
```
## Step 7: Display Results
Display the results action box showing all produced documents:
```
╔═══════════════════════════════════════════════╗
║ Codebase Mapped ║
╠═══════════════════════════════════════════════╣
║ ║
║ ▸ Documents ║
║ STACK.md ({N} lines) ║
║ INTEGRATIONS.md ({N} lines) ║
║ ARCHITECTURE.md ({N} lines) ║
║ STRUCTURE.md ({N} lines) ║
║ CONVENTIONS.md ({N} lines) ║
║ TESTING.md ({N} lines) ║
║ CONCERNS.md ({N} lines) ║
║ SUMMARY.md ({N} lines) ║
║ ║
║ ▸ Areas Mapped ║
║ ✓ tech ✓ architecture ║
║ ✓ quality ✓ concerns ║
║ ║
╚═══════════════════════════════════════════════╝
```
For focused runs, only show the documents from the mapped area.
End with the Next Up block:
```
═══════════════════════════════════════════════════
▸ Next Up
**Plan from analysis** -- create roadmap from codebase map
`/mz:plan`
═══════════════════════════════════════════════════
```
## Error Handling
- **Config missing:** Step 2 catches this and suggests `/mz:init`. Exit.
- **Plugin path missing:** Step 2 catches this and suggests `/mz:settings`. Exit.
- **Agent failure:** If a mapper agent Task fails, display warning for that area and continue with remaining areas. Do not abort the entire map.
- **Missing output files:** Step 5 warns about missing files but continues to synthesis if enough documents exist.
- **Synthesis failure:** If synthesis agent fails, display warning but still show individual document results. The 7 individual documents are the primary output.
## Notes
- The orchestrator NEVER reads the content of produced map documents. This preserves context budget. Only file existence and line counts are checked (via `wc -l`).
- All agent spawning follows the inline embedding pattern: read agent file content, embed in Task prompt. @file references do NOT work across Task boundaries.
- Use `{plugin_path}` resolution from config (same pattern as /mz:plan Step 2).
- Focus parameter aliases provide user convenience: `arch` for `architecture`, `conventions` for `quality`.
- Re-mapping gives the user control: Refresh (clean slate), Update (overwrite), Skip (reuse).
- Synthesis only runs on full maps, not focused single-area runs. This is because the synthesis agent needs all 7 documents to produce a meaningful summary.
