/codemap

description: "Generate or update a feature-organized CODEMAP.md for any codebase. Scans repos, detects frameworks, identifies features, traces full-stack flows (frontend routes → hooks → state → backend views → models → integrations), and produces a navigable reference with a directory table for selective loading. Supports modes: create (full generation), inventory (quick index only), update (incremental refresh), section (rebuild one section). Trigger: '/codemap', '/codemap create', '/codemap inventory', '/codemap update', '/codemap section {name}'."

/codemap — Codebase Mapping

Systematically scan a codebase and produce a feature-organized CODEMAP.md. Works for any multi-repo or single-repo project, any framework. The output is optimized for AI-assisted development — a new session can load the directory (~50 lines) and selectively read only the sections relevant to its task.

Step 0: Resolve Config & Parse Mode

Read `~/.gemini/antigravity/aria-knowledge.local.md` and extract `knowledge_folder`. If the file doesn't exist, the skill still works — `knowledge_folder` is only needed for the knowledge extraction offer in Step 5.

**Parse the mode from arguments:**

| Argument | Mode | What it does | |----------|------|-------------| | (none) | Auto | If CODEMAP.md exists → prompt: "update or recreate?" Otherwise → `create` | | `create` | Create | Full generation from scratch (Steps 1-8) | | `inventory` | Inventory | Steps 1-2 only — detect + index, report to user, no file written | | `update` | Update | Read existing CODEMAP.md, detect changes, refresh affected sections (Step 6) | | `section <name>` | Section | Rebuild one specific section in an existing CODEMAP.md (Step 7) |

**Locate the project root:**

• If the current working directory contains a project-level CLAUDE.md, use that as the project root
• If inside a subdirectory of a project, walk up to find the nearest CLAUDE.md
• If unclear, ask the user: "Which directory is the project root?"

**Locate or create CODEMAP.md:**

• Default location: `{project_root}/CODEMAP.md`
• If the user specifies a different path, use that

For `inventory` mode, skip to Step 1 and stop after Step 2. For `update` mode, verify CODEMAP.md exists. If it does, skip to Step 6. If not, tell the user: "No CODEMAP.md found — switching to create mode." and proceed with `create`. For `section` mode, verify CODEMAP.md exists. If it does, skip to Step 7. If not, same fallback as update. For `create` mode, proceed through Steps 1-5.

---

Step 1: Detect Project Structure

Scan the project root for framework indicators:

**Backend detection:**

• `manage.py` + `settings.py` → Django (extract version from requirements.txt or pip)
• `package.json` with `express`/`fastify`/`hono`/`nestjs` → Node backend
• `Cargo.toml` → Rust
• `go.mod` → Go
• `Gemfile` with `rails` → Rails

**Frontend detection:**

• `next.config.*` or `package.json` with `next` → Next.js (extract version)
• `package.json` with `react` but no `next` → React SPA
• `package.json` with `vue`/`nuxt`/`svelte`/`sveltekit` → respective framework
• `app.json` or `expo` in package.json → React Native

**Repo structure detection:**

• Multiple directories each with their own `package.json` or `manage.py` → multi-repo
• Single root `package.json` with `workspaces` → monorepo
• Single app directory → single-repo

**Present detection results to user:**

## Project Detection

Root: /path/to/your-project
Structure: Multi-repo (2 repos)

| Repo | Framework | Version | Language |
|------|-----------|---------|----------|
| frontend/ | Next.js (App Router) | 13.x | TypeScript |
| backend/ | Django + DRF | 4.2.x | Python |

Confirm or correct?

User confirms or corrects. Store the confirmed detection for subsequent steps.

---

Step 2: Index Key Files

For each confirmed repo, scan for key file categories using framework-aware patterns.

Django Backend Scanning

| Category | How to find | What to record | |----------|-------------|----------------| | **Apps** | Directories with `models/` or `models.py` + `views/` or `views.py` | App name, whether it has urls.py, admin.py | | **Models** | `*/models/*.py` and `*/models.py` (exclude `__init__.py`) | Model class names via `^class \w+\(` grep | | **Views** | `*/views/*.py` and `*/views.py` | View function/class names | | **URLs** | `*/urls.py` + root `urls.py` | URL patterns, include() targets | | **Config** | `settings.py`, `.env*`, `requirements.txt` | Framework version, installed apps, integrations | | **Middleware** | `MIDDLEWARE` in settings.py, `*/middlewares/` | Custom middleware files | | **Cron** | `CRONJOBS` in settings.py, `*/cron/*.py` | Cron job entries | | **Utils** | `*/utils/*.py`, `*/utils.py` | Utility module names |

Next.js / React Frontend Scanning

| Category | How to find | What to record | |----------|-------------|----------------| | **Pages/Routes** | `app/**/page.tsx` or `pages/**/*.tsx` | Route paths (derive from directory structure) | | **Components** | `components/**/*.tsx` | Component directories and key files | | **Hooks** | `hooks/*.ts` or `hooks/**/*.ts` | Hook names (extract from filenames) | | **State** | `redux/`, `store/`, `context/` | Slice names, store shape | | **API layer** | Files containing `createApi`, `apiSlice`, `fetch(` | API definition files | | **Config** | `next.config.*`, `tsconfig.json`, `tailwind.config.*` | Key config values | | **Middleware** | `middleware.ts` | What it does (read first 20 lines) | | **Models/Types** | `models/`, `types/`, `interfaces/` | Type definition files |

For Other Frameworks

Apply analogous patterns:

• **Express/Fastify:** scan `routes/`, `controllers/`, `models/`, `middleware/`
• **Rails:** scan `app/controllers/`, `app/models/`, `config/routes.rb`
• **React Native:** scan `src/screens/`, `src/navigation/`, `src/api/`

Categorize Apps/Modules

Group discovered apps into tiers:

• **Core Domain** — apps with substantial models + views + URLs (the main busin