# Map Codebase

> Writes 10 documents with Mermaid diagrams and an INDEX.md entry point into .codebase-map/. TRIGGER WHEN: the user asks to onboard to an unfamiliar project, generate a codebase tour, or produce a full narrative guide for new contributors. DO NOT TRIGGER WHEN: the user wants structured AST/dependency analysis (use /codebase-xray:analyze) or just API docs (use /codebase-mapper:docs-create).

- Skill: `acaprino/map-codebase` (Agent Skill)
- Install (CLI): `npx skillmds@latest add acaprino/map-codebase`
- Raw SKILL.md: https://api.skillmd.com/api/skills/acaprino/map-codebase/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: acaprino (https://skillmd.com/u/acaprino)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/acaprino/map-codebase

---


> `<plugin-root>` names the directory that holds this plugin's `.codex-plugin/plugin.json`. Resolve it once from where this file was loaded, then substitute it into every path below that starts with it.
> Arguments: `[target-path]`. Wherever `<arguments>` appears below, substitute the text the user typed after the skill name.

<!-- Generated by the Daodan compiler for codex. Edit the kernel, never this file. -->

# Map Codebase

Generate a human-readable guide for an unfamiliar codebase. Produces 10 narrative documents with inline Mermaid diagrams, organized for progressive learning.

## Pre-flight

1. **Determine target path**: Use the argument if provided, otherwise use the current working directory.

2. **Check for existing output**:
   ```bash
   ls .codebase-map/ 2>/dev/null
   ```
   - If `.codebase-map/` exists with content, ask the user: "A codebase map already exists. Overwrite it? (y/n)"
   - If user declines, stop here

3. **Create output directories**:
   ```bash
   mkdir -p .codebase-map/_internal
   ```

## Phase 1: Explore (sequential)

Spawn a single `codebase-explorer` agent:

**Agent task:**
> Explore this project and write a context brief to `.codebase-map/_internal/context-brief.md`. Follow your exploration strategy to understand what the project does, its tech stack, directory structure, key entry points, data model, and main workflows. Read actual code - do not guess from file names. Include file paths for every claim.

**Verify:** Check that `.codebase-map/_internal/context-brief.md` exists and is non-empty.

If the context brief is missing or empty, stop and report the error.

## Phase 1.5: Confirm Project Profile (sequential)

The `codebase-explorer` wrote a `## Project Profile` section as the first section of `.codebase-map/_internal/context-brief.md`. Surface it for a quick confirmation before the writers run.

1. Read the `## Project Profile` section from `.codebase-map/_internal/context-brief.md`.
2. Present a compact summary to the user: project type and domain, primary audience, register, scope, and any items the explorer marked low-confidence.
3. Ask the user to confirm or adjust (use AskUserQuestion). The default is the inferred profile; the user only corrects.
4. If the user adjusts anything, overwrite the `## Project Profile` section in `context-brief.md` with the corrected values, so the writers read the confirmed profile.

This is the only interactive checkpoint. Profiling itself is autonomous; this step is a light safety net, not a questionnaire. Keep it to one question.

## Phase 1b: Interconnect Map (sequential)

Spawn a single `codebase-xray:semantic-interconnect-mapper` agent. This produces structured facts (contracts, invariants, domain rules, integration hot-spots) that the writer agents cite instead of paraphrasing code.

**Agent task:**
> Build the interconnect map for this project.
>
> Primary context source: `.codebase-map/_internal/context-brief.md` (produced by codebase-explorer).
> Target files: the whole project (infer scope from the context brief's directory structure).
> Output path: `.codebase-map/_internal/interconnect.md`
>
> Produce the full structured map following your agent definition: Call Graph (2-3 hop for public entry points), Contracts (formal / structural / implicit), Invariants, Domain Rules, Assumptions (verified / documented / unverified), Integration Hot-Spots, Change Impact Radius, and Reviewer Hints (which anchors each downstream writer should read).
>
> Every claim must cite file:line. No recommendations, no fixes. Empty sections are acceptable if nothing applies.

**Verify:** Check that `.codebase-map/_internal/interconnect.md` exists and contains the required anchors (`## Contracts`, `## Invariants`, `## Domain Rules`, `## Assumptions`, `## Integration Hot-Spots`).

If the file is missing, skip it and continue to Phase 2 in degraded mode -- writers will not receive interconnect facts but can still use the context brief. Log a warning.

## Phase 2: Write (parallel - 6 agents)

Spawn all 6 writer agents simultaneously. Every writer first reads the `## Project Profile` and `## Why / Context` sections of `.codebase-map/_internal/context-brief.md` and `<plugin-root>/skills/codebase-mapper/references/audience-adaptation.md`, then calibrates register, depth, and vocabulary to the confirmed profile (a consumer-app guide favors plain language and user value; a technical-tool guide favors precision and depth).

### Agent 1: `overview-writer`
> Read `.codebase-map/_internal/context-brief.md` (especially `## Project Profile` and `## Why / Context`), then write `.codebase-map/00-executive-summary.md` (plain-language, for anyone, zero jargon), `.codebase-map/01-overview.md`, and `.codebase-map/02-features.md`. Put a "Why this exists / Context" section and a "Scope and Non-Goals" section in 01-overview. Include a Mermaid mindmap in the overview. Follow the writing guidelines - narrative tone, no AI boilerplate, file paths for every claim.

### Agent 2: `tech-writer`
> Read `.codebase-map/_internal/context-brief.md`, then write `.codebase-map/03-tech-stack.md` and `.codebase-map/04-architecture.md`. Include a Mermaid component/layer diagram in the architecture doc. If `.codebase-map/_internal/interconnect.md` exists, read its `## Call Graph`, `## Contracts`, and `## Integration Hot-Spots` anchors and cite those structured facts in the architecture doc instead of paraphrasing code. Follow the writing guidelines - narrative tone, no AI boilerplate, file paths for every claim.

### Agent 3: `flow-writer`
> Read `.codebase-map/_internal/context-brief.md`, then write `.codebase-map/05-workflows.md` and `.codebase-map/06-data-model.md`. Include Mermaid flowcharts and sequence diagrams for workflows, and an ER diagram for the data model. If `.codebase-map/_internal/interconnect.md` exists, read its `## Invariants` (especially temporal), `## Integration Hot-Spots`, and `## Domain Rules` anchors and encode those facts directly in sequence diagrams and data-flow narratives. Follow the writing guidelines - narrative tone, no AI boilerplate, file paths for every claim.

### Agent 4: `onboarding-writer`
> Read `.codebase-map/_internal/context-brief.md`, then write `.codebase-map/07-getting-started.md` and `.codebase-map/08-open-questions.md`. Make getting-started practical with copy-pasteable commands. Make open-questions specific and actionable. Follow the writing guidelines - narrative tone, no AI boilerplate, file paths for every claim.

### Agent 5: `ops-writer`
> Read `.codebase-map/_internal/context-brief.md`, then write `.codebase-map/09-project-anatomy.md`. Document the annotated directory tree, every configuration file and what it controls, all environment variables, scripts and executables, startup sequence, and default ports/URLs. If `.codebase-map/_internal/interconnect.md` exists, read its `## Integration Hot-Spots` anchor (rows of type Env/config) and use it as the authoritative list of env vars and config files. Verify claims by reading actual config files and grepping for env var usage. Follow the writing guidelines - narrative tone, no AI boilerplate, file paths for every claim.

### Agent 6: `config-writer`
> Read `.codebase-map/_internal/context-brief.md`, then write `.codebase-map/10-configuration-guide.md`. Write a practical guide covering configuration walkthrough, environment profiles, configuration recipes, common day-to-day operations with exact commands, troubleshooting with real error messages from the codebase, and a quick-reference cheat sheet. Verify by reading actual config files and grepping for error messages. Follow the writing guidelines - narrative tone, no AI boilerplate, file paths for every claim.

**Verify:** Check that `00-executive-summary.md` and the 10 numbered documents (01-10) exist:
```bash
ls -la .codebase-map/0*.md .codebase-map/10*.md
```

(`11-glossary.md` is produced in Phase 3.) If any are missing, report which ones failed and stop.

## Phase 3: Review (sequential)

Spawn a single `guide-reviewer` agent:

**Agent task:**
> Read all documents in `.codebase-map/` (00 and 01 through 10) and the context brief in `_internal/`. If `.codebase-map/_internal/interconnect.md` exists, also read its `## Invariants` and `## Domain Rules` anchors, and use the `senior-review:defect-taxonomy` skill's `logic-integrity.md` reference to detect documentation-reality drift (docs that describe behavior contradicting documented invariants/contracts). Flag any drift as a "⚠ known inconsistency" note in the relevant doc and add a corresponding item to 08-open-questions.md. Review for terminology consistency, add cross-references between documents, fix any AI boilerplate in tone, validate Mermaid diagram syntax, and detect gaps. Apply edits directly. Also read the `## Project Profile` from the context brief and `<plugin-root>/skills/codebase-mapper/references/audience-adaptation.md`, then: (a) verify register consistency, so the tone across all docs matches the profile's register, and fix drift; (b) verify the plain-language layer serves a non-technical reader; (c) write `.codebase-map/11-glossary.md`, a domain and technical glossary with plain definitions, built from terminology across all docs and the interconnect glossary and domain-rule signals. Then write `.codebase-map/INDEX.md` as the entry point with a navigable summary table that includes 00-executive-summary and 11-glossary, plus per-audience reading paths (a non-technical path starting at 00 and 11, and a developer path).

**Verify:** Check that `.codebase-map/INDEX.md` exists.

## Completion

Print a summary:

```
Codebase map generated in .codebase-map/

  INDEX.md              - Entry point and navigation
  00-executive-summary.md - Plain-language summary for anyone
  01-overview.md        - Project overview with concept mindmap
  02-features.md        - Feature catalog
  03-tech-stack.md      - Technologies and dependencies
  04-architecture.md    - Code organization with component diagram
  05-workflows.md       - User and system flows with diagrams
  06-data-model.md      - Entities and relationships with ER diagram
  07-getting-started.md - Developer onboarding guide
  08-open-questions.md  - Knowledge gaps to clarify
  09-project-anatomy.md - Config files, env vars, scripts, directory tree
  10-configuration-guide.md - Configuration recipes, operations, troubleshooting
  11-glossary.md        - Domain and technical glossary

Start reading from INDEX.md
```