aria-knowledge

/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 ~/.claude/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 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.

1. Route prefix grouping: Frontend routes that share a prefix map to the same feature:
2. /dashboard/ai-interviews/* → same feature as interview/ backend app
3. /dashboard/bookings/ + /client/dashboard/bookings/ → same feature as booking/ backend app

1. Cross-cutting detection: Some concerns span all features and get their own sections:
2. Auth (login, registration, JWT) → standalone section
3. Data flow (request lifecycle) → standalone section
4. 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 tree overview,