/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

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:

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:

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.