flow-code-map

name	flow-code-map
description	Use when user says 'map this codebase', 'document the architecture', 'create codebase map', or /flow-code:map.
tier	2
user-invocable	false
context	fork

Codebase Map

Maps codebases of any size using parallel Sonnet subagents. Produces docs/CODEBASE_MAP.md — a persistent architecture reference that accelerates planning, reviews, and auto-improve experiments.

Based on Cartographer (MIT license), integrated into flow-code.

CRITICAL: Opus orchestrates, Sonnet reads. Never read codebase files directly. Always delegate to Sonnet subagents.

Input

Full request: $ARGUMENTS

Examples:

/flow-code:map
/flow-code:map src/
/flow-code:map --update

Param	Default	Description
path	.	Directory to map
--update	auto-detect	Force update mode (only re-map changed files)

Workflow

Step 1: Check for Existing Map

if [[ -f docs/CODEBASE_MAP.md ]]; then
  echo "Map exists — checking for changes..."
  # Read last_mapped timestamp from frontmatter
  head -5 docs/CODEBASE_MAP.md
  # Check git changes since
  LAST_MAPPED=$(sed -n 's/^last_mapped: //p' docs/CODEBASE_MAP.md)
  git log --oneline --since="$LAST_MAPPED" -- . ':!docs/CODEBASE_MAP.md' 2>/dev/null | head -20
fi

If map exists and no changes: Inform user map is current. If map exists with changes: Update mode — only re-analyze changed modules. If no map: Full mapping.

Step 2: Scan the Codebase

PLUGIN_ROOT="$HOME/.codex"
SCANNER="$PLUGIN_ROOT/skills/flow-code-map/scripts/scan-codebase.py"

# Try uv first (auto-installs tiktoken), fallback to python3
uv run "$SCANNER" . --format json 2>/dev/null || python3 "$SCANNER" . --format json

If tiktoken is missing and uv not available:

pip3 install tiktoken
python3 "$SCANNER" . --format json

Step 3: Plan Subagent Assignments

From the scan output:

1. Group files by directory/module — keep related code together
2. Balance token counts — ~150k tokens max per subagent (safe under Sonnet's 200k)
3. Small codebases (<100k tokens): Still use one Sonnet subagent (Opus never reads files directly)

Example assignment:

Subagent 1: src/api/, src/middleware/ (~120k tokens)
Subagent 2: src/components/, src/hooks/ (~140k tokens)
Subagent 3: src/lib/, src/utils/, tests/ (~100k tokens)

Step 4: Spawn Sonnet Subagents in Parallel

CRITICAL: Spawn ALL subagents in a SINGLE message with multiple Task tool calls.

Use subagent_type: "Explore" and model: "sonnet" for each group.

Each subagent prompt:

You are mapping part of a codebase. Read and analyze these files:
[list files]

For each file, document:
1. **Purpose**: One-line description
2. **Exports**: Key functions, classes, types
3. **Imports**: Notable dependencies
4. **Patterns**: Design patterns used
5. **Gotchas**: Non-obvious behavior, warnings

Also identify:
- How these files connect to each other
- Entry points and data flow
- Configuration or environment dependencies

Return your analysis as markdown with clear headers.

Step 5: Synthesize and Write Map

After all subagents complete:

1. Merge all reports
2. Deduplicate overlapping analysis
3. Build architecture diagram (Mermaid) showing module relationships
4. Extract navigation paths ("To add an API endpoint: touch these files")

Get timestamp:

date -u +"%Y-%m-%dT%H:%M:%SZ"

Create docs/CODEBASE_MAP.md:

---
last_mapped: YYYY-MM-DDTHH:MM:SSZ
total_files: N
total_tokens: N
---

# Codebase Map

> Auto-generated by flow-code:map. Last mapped: [date]

## System Overview

[Mermaid architecture diagram]

## Directory Structure

[Tree with purpose annotations]

## Module Guide

### [Module Name]
**Purpose**: ...
**Entry point**: ...
**Key files**:
| File | Purpose | Tokens |
|------|---------|--------|

**Exports**: ...
**Dependencies**: ...

## Data Flow

[Mermaid sequence diagrams for key flows]

## Conventions

[Naming, patterns, style]

## Gotchas

[Non-obvious behaviors, warnings]

## Navigation Guide

**To add a new API endpoint**: [files to touch]
**To add a new component**: [files to touch]
**To modify auth**: [files to touch]

Step 6: Update AGENTS.md

Add or update codebase summary in AGENTS.md (or AGENTS.md):

## Codebase Overview

[2-3 sentence summary]

**Stack**: [key technologies]
**Structure**: [high-level layout]

For detailed architecture, see [docs/CODEBASE_MAP.md](docs/CODEBASE_MAP.md).

Step 7: Show Summary

Codebase mapped!

  Files: N | Tokens: N | Subagents: N
  Map: docs/CODEBASE_MAP.md

  The map is now available to:
  - Planning scouts (repo-scout, context-scout)
  - Auto-improve experiments
  - Future /flow-code:map --update runs

Update Mode

When updating an existing map:

1. Identify changed files from git or scanner diff
2. Spawn subagents only for changed modules
3. Merge new analysis with existing map sections
4. Update last_mapped timestamp
5. Preserve unchanged sections