tobihagemann/map-codebase

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 update_plan to track each phase, restating any remaining steps of a parent workflow alongside them:

1. Scope
2. Launch inspection agents
3. Synthesize and generate markdown report
4. Generate HTML report

Step 1: Scope

If $ARGUMENTS specifies paths, use those directly (skip the question).

Otherwise, use request_user_input 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

Before dispatching, read the project's test configuration and CI workflow to identify any test tier that resets a shared external resource between tests, such as a database, a fixed port, or a cache. Such tiers have no cross-process interlock, so agents running them concurrently wipe each other's state and return failures that look like real defects. Name any such tier to every agent as off-limits.

Launch the 7 agents below in parallel. Each agent receives the scoped file manifest and its exploration brief, and its prompt directs it to treat the shared working tree and its git index as read-only — any empirical check runs in an isolated git worktree created under $TMPDIR and discarded afterward. Give that worktree its own dependency install rather than reaching the shared tree's install by any route: removing a worktree deletes through symlinks, and a redirected suite writes into the shared install. When its own install is not possible, the check is left unrun and reported as such. Afterward the agent verifies that git worktree list no longer shows the worktree, that git status --short is clean, and that the shared tree's dependency directory still resolves (a destroyed install leaves git status clean, since it is gitignored). Damage the agent cannot repair is reported with the exact repair command in place of findings.

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:

1. Read all agent reports.
2. Identify cross-cutting themes, connections between dimensions, and architectural trade-offs.
3. Write a brief executive summary (3-5 sentences) capturing the system's essential character.
4. Resolve contradictions or overlaps between dimension reports.
5. 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.

1. Run the $frontend-design skill to load design principles.
2. Read .turbo/codebase-map.md for the full report content.
3. 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.