Map Codebase
Deep architecture report. Fans out parallel inspections across different aspects of the codebase, synthesizes their findings, and writes .turbo/codebase-map.md and .turbo/codebase-map.html. Analysis-only.
Task Tracking
At the start, use TaskCreate to create a task for each phase:
- Scope
- Launch inspection agents
- Synthesize and generate markdown report
- Generate HTML report
Step 1: Scope
If $ARGUMENTS specifies paths, use those directly (skip the question).
Otherwise, use AskUserQuestion to confirm scope:
- Entire codebase — inspect everything
- Specific paths — user provides directories or file patterns
Once scope is determined, glob for source files in the selected scope. Exclude generated and vendored directories (node_modules/, dist/, build/, vendor/, __pycache__/, .build/, DerivedData/, target/, .tox/, and others appropriate to the project).
Build a file manifest grouped by top-level source directory. This manifest is shared with all agents as a starting point. Agents may explore beyond it based on what they discover.
Step 2: Launch Inspection Agents
Use the Agent tool to launch all 7 agents below in a single assistant message so they run concurrently. Each Agent call uses model: "opus" and does not set run_in_background. Each agent receives the scoped file manifest and its exploration brief.
Dimensions
Launch one agent per dimension. Each agent's prompt provides the file manifest and the exploration brief below. Agents explore adaptively: go deeper where complexity warrants it, stay high-level where things are straightforward. Findings should be concrete (reference specific files and directories) rather than generic.
| # |
Dimension |
Exploration Brief |
| 1 |
Project Structure |
Map directory layout, module organization, naming conventions, and file roles. Identify the organizing principle (feature-based, layer-based, hybrid). Note generated or build output directories. |
| 2 |
Tech Stack and Build System |
Identify languages, frameworks, package managers, build tools, and runtime requirements. Note version constraints and compatibility targets. |
| 3 |
Entry Points and Public API |
Find how the system is invoked: CLI commands, HTTP endpoints, event handlers, exported modules, main functions. Map the public surface area. |
| 4 |
Core Abstractions and Patterns |
Identify key types, classes, interfaces, and design patterns. Note architectural patterns (MVC, plugin system, pipeline, etc.) and how they shape the code. |
| 5 |
Data Flow and State |
Trace how data enters, transforms, persists, and exits the system. Identify state management approaches, storage layers, and data boundaries. |
| 6 |
External Dependencies and Integrations |
Map third-party services, APIs, databases, and system boundaries. Note how external dependencies are abstracted or coupled. |
| 7 |
Testing and Quality Infrastructure |
Describe the test strategy: frameworks, coverage approach, test organization, CI/CD pipeline. Note gaps or unusual patterns. |
Each agent writes its findings as structured markdown with sections and subsections.
Step 3: Synthesize and Generate Markdown Report
After all agents complete:
- Read all agent reports.
- Identify cross-cutting themes, connections between dimensions, and architectural trade-offs.
- Write a brief executive summary (3-5 sentences) capturing the system's essential character.
- Resolve contradictions or overlaps between dimension reports.
- Write
.turbo/codebase-map.md using the report template. Output the executive summary as text before writing the file.
Report Template
# Codebase Map
**Date:** <date>
**Scope:** <what was inspected>
## Executive Summary
<3-5 sentences: what the system is, how it's organized, what architectural choices define it>
## Project Structure
<from dimension 1>
## Tech Stack
<from dimension 2>
## Entry Points and API
<from dimension 3>
## Core Abstractions
<from dimension 4>
## Data Flow
<from dimension 5>
## External Dependencies
<from dimension 6>
## Testing and Quality
<from dimension 7>
## Cross-Cutting Observations
<themes, trade-offs, and connections identified during synthesis>
Step 4: Generate HTML Report
Convert the markdown report into a styled, interactive HTML page.
- Run the
/frontend-design skill to load design principles.
- Read
.turbo/codebase-map.md for the full report content.
- Write a self-contained
.turbo/codebase-map.html (single file, no external dependencies beyond Google Fonts) that presents the architecture report with:
- Executive summary card
- Sticky navigation between sections
- Collapsible dimension sections
- File and directory references as styled inline code
- Entrance animations and hover states
- Print-friendly styles via
@media print
- Responsive layout for mobile
Rules
- If any agent fails, proceed with findings from the remaining agents and note the failure in the report.
- Each dimension agent operates independently. Overlapping observations from different angles are expected. The synthesis step resolves overlaps.
- Does not modify source code, stage files, or commit.
1---2name: map-codebase3description: Deep architecture report that fans out parallel inspections across different aspects of the codebase (structure, tech stack, APIs, patterns, data flow, dependencies, testing) and synthesizes findings into a comprehensive document at .turbo/codebase-map.md and .turbo/codebase-map.html. Use when the user asks to "map the codebase", "map codebase", "architecture report", "codebase overview", "architecture overview", "what am I looking at", or "explain this codebase".4---5
6# Map Codebase
7
8Deep architecture report. Fans out parallel inspections across different aspects of the codebase, synthesizes their findings, and writes `.turbo/codebase-map.md` and `.turbo/codebase-map.html`. Analysis-only.
9
10## Task Tracking
11
12At the start, use `TaskCreate` to create a task for each phase:
13
141. Scope
152. Launch inspection agents
163. Synthesize and generate markdown report
174. Generate HTML report
18
19## Step 1: Scope
20
21If `$ARGUMENTS` specifies paths, use those directly (skip the question).
22
23Otherwise, use `AskUserQuestion` to confirm scope:
24
25- **Entire codebase** — inspect everything
26- **Specific paths** — user provides directories or file patterns
27
28Once scope is determined, glob for source files in the selected scope. Exclude generated and vendored directories (`node_modules/`, `dist/`, `build/`, `vendor/`, `__pycache__/`, `.build/`, `DerivedData/`, `target/`, `.tox/`, and others appropriate to the project).
29
30Build a file manifest grouped by top-level source directory. This manifest is shared with all agents as a starting point. Agents may explore beyond it based on what they discover.
31
32## Step 2: Launch Inspection Agents
33
34Use the Agent tool to launch all 7 agents below in a single assistant message so they run concurrently. Each Agent call uses `model: "opus"` and does not set `run_in_background`. Each agent receives the scoped file manifest and its exploration brief.
35
36### Dimensions
37
38Launch one agent per dimension. Each agent's prompt provides the file manifest and the exploration brief below. Agents explore adaptively: go deeper where complexity warrants it, stay high-level where things are straightforward. Findings should be concrete (reference specific files and directories) rather than generic.
39
40| # | Dimension | Exploration Brief |
41|---|---|---|
42| 1 | Project Structure | Map directory layout, module organization, naming conventions, and file roles. Identify the organizing principle (feature-based, layer-based, hybrid). Note generated or build output directories. |
43| 2 | Tech Stack and Build System | Identify languages, frameworks, package managers, build tools, and runtime requirements. Note version constraints and compatibility targets. |
44| 3 | Entry Points and Public API | Find how the system is invoked: CLI commands, HTTP endpoints, event handlers, exported modules, main functions. Map the public surface area. |
45| 4 | Core Abstractions and Patterns | Identify key types, classes, interfaces, and design patterns. Note architectural patterns (MVC, plugin system, pipeline, etc.) and how they shape the code. |
46| 5 | Data Flow and State | Trace how data enters, transforms, persists, and exits the system. Identify state management approaches, storage layers, and data boundaries. |
47| 6 | External Dependencies and Integrations | Map third-party services, APIs, databases, and system boundaries. Note how external dependencies are abstracted or coupled. |
48| 7 | Testing and Quality Infrastructure | Describe the test strategy: frameworks, coverage approach, test organization, CI/CD pipeline. Note gaps or unusual patterns. |
49
50Each agent writes its findings as structured markdown with sections and subsections.
51
52## Step 3: Synthesize and Generate Markdown Report
53
54After all agents complete:
55
561. Read all agent reports.
572. Identify cross-cutting themes, connections between dimensions, and architectural trade-offs.
583. Write a brief executive summary (3-5 sentences) capturing the system's essential character.
594. Resolve contradictions or overlaps between dimension reports.
605. Write `.turbo/codebase-map.md` using the report template. Output the executive summary as text before writing the file.
61
62### Report Template
63
64```markdown
65# Codebase Map
66
67**Date:** <date>
68**Scope:** <what was inspected>
69
70## Executive Summary
71
72<3-5 sentences: what the system is, how it's organized, what architectural choices define it>
73
74## Project Structure
75
76<from dimension 1>
77
78## Tech Stack
79
80<from dimension 2>
81
82## Entry Points and API
83
84<from dimension 3>
85
86## Core Abstractions
87
88<from dimension 4>
89
90## Data Flow
91
92<from dimension 5>
93
94## External Dependencies
95
96<from dimension 6>
97
98## Testing and Quality
99
100<from dimension 7>
101
102## Cross-Cutting Observations
103
104<themes, trade-offs, and connections identified during synthesis>
105```
106
107## Step 4: Generate HTML Report
108
109Convert the markdown report into a styled, interactive HTML page.
110
1111. Run the `/frontend-design` skill to load design principles.
1122. Read `.turbo/codebase-map.md` for the full report content.
1133. Write a self-contained `.turbo/codebase-map.html` (single file, no external dependencies beyond Google Fonts) that presents the architecture report with:
114 - Executive summary card
115 - Sticky navigation between sections
116 - Collapsible dimension sections
117 - File and directory references as styled inline code
118 - Entrance animations and hover states
119 - Print-friendly styles via `@media print`
120 - Responsive layout for mobile
121
122## Rules
123
124- If any agent fails, proceed with findings from the remaining agents and note the failure in the report.
125- Each dimension agent operates independently. Overlapping observations from different angles are expected. The synthesis step resolves overlaps.
126- Does not modify source code, stage files, or commit.
majiayu000