/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:

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

Next.js / React Frontend Scanning

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 business logic)
• Reference/Taxonomy — apps that primarily serve lookup data (small models, simple CRUD)
• Support — utility apps, content management, tracking

Report inventory to user:

## Inventory Summary

### backend/ (Django 4.2)
Core Domain: user (30+ models), booking (12+ models), interview, project, company, payment_gateway, meeting
Reference: expertise, industry, market, school, degree, job_title
Support: event_code, fee, blocks, issue, link_redirect, notification, rating

### frontend/ (Next.js 13)
Pages: ~137 page.tsx files across /admin, /client, /dashboard, /auth, /profile
Hooks: ~58 custom hooks
Components: ~243 .tsx files in 18 areas
Redux: 14 slices + RTK Query

Total: 7 core apps, 6 taxonomy apps, 7 support apps, 137 pages, 58 hooks

In inventory mode, stop here and output the report. Do not write any files.

Step 3: Feature Detection

Using the indexed files from Step 2, identify features by clustering related files across repos.

Detection heuristics:

1. Backend app → feature mapping: Each Core Domain app is a candidate feature. Some apps combine into one feature (e.g., booking + meeting → "Expert Sessions & Bookings"). For non-Django backends, use controller/route directories as the grouping unit.

2. Route prefix grouping: Frontend routes that share a prefix map to the same feature:

   • /dashboard/ai-interviews/* → same feature as interview/ backend app
   • /dashboard/bookings/* + /client/dashboard/bookings/* → same feature as booking/ backend app

3. Cross-cutting detection: Some concerns span all features and get their own sections:

   • Auth (login, registration, JWT) → standalone section
   • Data flow (request lifecycle) → standalone section
   • Shared patterns (conventions that repeat everywhere) → standalone section

Stack-aware cross-cutting candidates: Before presenting the feature list, include these stack-level concerns as candidate cross-cutting sections. They tend to be under-documented in feature organization because they span all features. Offer each as proposed; user accepts/declines per item.

• Django detected: URLConf tree overview, Signal registry (post_save/pre_save handlers), Migration state (latest migration per app), Env matrix (grouped env var names, no values)
• Next.js / React detected: Route tree overview, API client & interceptors configuration, Env matrix
• Laravel detected: Route file overview, Job/queue registry, Service providers, Env matrix
• Expo / React Native detected: Screen tr