From aria-knowledge
Generates or updates a feature-organized CODEMAP.md for any codebase, detecting frameworks and tracing end-to-end flows. Supports create, inventory, update, and section modes.
How this skill is triggered — by the user, by Claude, or both
Slash command
/aria-knowledge:codemap <mode: create|inventory|update|section> [section-name]<mode: create|inventory|update|section> [section-name]This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
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.
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:
Locate or create CODEMAP.md:
{project_root}/CODEMAP.mdFor 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.
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 backendCargo.toml → Rustgo.mod → GoGemfile with rails → RailsFrontend detection:
next.config.* or package.json with next → Next.js (extract version)package.json with react but no next → React SPApackage.json with vue/nuxt/svelte/sveltekit → respective frameworkapp.json or expo in package.json → React NativeRepo structure detection:
package.json or manage.py → multi-repopackage.json with workspaces → monorepoPresent 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.
For each confirmed repo, scan for key file categories using framework-aware patterns.
| 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 |
| 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 |
Apply analogous patterns:
routes/, controllers/, models/, middleware/app/controllers/, app/models/, config/routes.rbsrc/screens/, src/navigation/, src/api/Group discovered apps into tiers:
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.
Using the indexed files from Step 2, identify features by clustering related files across repos.
Detection heuristics:
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.
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 appCross-cutting detection: Some concerns span all features and get their own sections:
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.
post_save/pre_save handlers), Migration state (latest migration per app), Env matrix (grouped env var names, no values)Add these to the Cn. cross-cutting block. E.g., C6. URLConf Tree, C7. Signal Registry, C8. Env Matrix.
Present proposed feature list to user:
## Proposed Features
0. Project Identity & Stack
1. Data Flow Overview (request lifecycle, auth hydration, token refresh)
2. Entity Model (all models, ER diagram, app registry)
3. Auth & User Management (JWT, social login, registration, profiles)
4. AI Interviews (expert/client interviews, Ribbon, OpenAI)
5. Expert Sessions & Bookings (session lifecycle, calendar, Zoom)
6. Kodex Panels (async Q&A, expert answers, client management)
7. Expert Storefronts & Profiles (public profiles, storefront, marketplace)
8. Knowledge Library & Notation (search, transcripts, notes)
9. Insights / Feed (posts, social interactions)
10. Works & Research (works CRUD, purchases, downloads)
11. Payments (Stripe Connect, checkout, payouts)
12. Search (Algolia indexing and search UI)
13. Notifications (email, SMS, WebSocket)
14. Admin Tools (admin dashboard, approvals, content management)
15. Client Projects (project briefs, expert selection)
Cross-cutting:
C1. Shared Patterns & Conventions
C2. Common Change Patterns
C3. Integrations
C4. File Index
C5. Dependency Graph
Confirm, rename, merge, split, reorder, or add?
User validates the feature list. This becomes the section structure for the CODEMAP.
Write sections in the order they appear in the final file. Write each section to CODEMAP.md immediately after mapping it — don't buffer everything for the end. This prevents context loss on long mapping sessions.
Start by writing the file header (populated fully in Step 5):
# {Project Name} Codemap
> Feature-organized codebase reference for AI-assisted development.
> Last updated: YYYY-MM-DD | Sections: N | Features: M
>
> **How to use:** Read the directory below (~N lines), then load specific
> sections with `Read CODEMAP.md offset=X limit=Y`.
> To find a section's line: `Grep "^## {number}\." CODEMAP.md`
## Directory
(placeholder — rebuilt in Step 5 after all sections are written)
---
Then write sections in this order:
Write from Step 1 detection results: framework versions, languages, key config files, env vars. If CLAUDE.md already covers this, keep brief and reference CLAUDE.md.
Read these to build the section:
Use Mermaid for all diagrams — renderable in GitHub/Obsidian for team members, formally structured for Claude:
flowchart LR
Browser["Browser Component"] --> APILayer["API Layer (RTK Query / fetch)"]
APILayer --> Middleware["Backend Middleware Chain"]
Middleware --> View["View → Response"]
flowchart LR
Request --> CheckPermission
CheckPermission -->|"no auth"| PublicCheck["PublicUrlAccess check"]
PublicCheck -->|"public path"| View
PublicCheck -->|"not public"| Reject["Reject (401)"]
CheckPermission -->|"Bearer token"| JWT["JWT validation → User load"] --> View
Build from the model files indexed in Step 2.
App Registry table — categorized by tier (Core Domain / Reference-Taxonomy / Support):
| App | Domain | Route prefix | Purpose |
|---|---|---|---|
| user | Accounts, auth, profiles | api/user/ | Central user entity |
Mermaid ER diagram — show core entity relationships:
erDiagram
User ||--|| Profile : has
User ||--o{ Post : authors
User ||--o{ ExpertProfile : configures
User ||--o{ Follow : initiates
User ||--o{ Experience : has
Company ||--o{ CompanyUserAccess : grants
Company ||--o{ Project : owns
Project ||--o{ Booking : generates
Booking ||--|| BookingBrief : describes
Booking ||--o{ BookingSchedule : proposes
Booking ||--o{ BookingKodexAnswer : contains
Booking ||--o{ PaymentGatewayBooking : "paid via"
Interview ||--o{ Invite : sends
Focus on core domain models only (10-15 entities max). Taxonomy and support models are listed in the App Registry table but don't need ER representation.
For each confirmed feature from Step 3, read the key files and trace the full stack. Process one feature at a time to manage context.
Reading strategy per feature:
^def or ^class first, then read key functions selectively.Each feature section contains:
Frontend spine:
| Route | Purpose |
|---|---|
/path/to/page | What the page does |
| Hook | What it does |
|---|---|
use-feature.ts | Key behavior, which API endpoints it calls |
| Redux / API Endpoints | Method | Backend URL |
|---|---|---|
useXxxMutation | POST | /api/xxx |
Backend spine:
| URL | View | Notes |
|---|---|---|
POST /api/xxx | view_function() | Key behavior, permissions, issues |
Models: Key fields and relationships. Tables for simple listings, prose for complex relationships.
Integrations: If the feature touches external services — which service, what operations, key files, env vars.
Security issues (inline): Flag at the point they occur — IDOR, exposed secrets, missing validation, permission bypasses, anti-patterns. Bold the issue type:
IDOR:
user_settings.pyacceptsuser_idfrom POST body without checkingrequest.user.id
After writing all feature sections, scan them for repeating patterns:
Document each pattern once with a brief description and an example file reference.
For each detected framework, produce "how to" recipes:
Django: add endpoint, add model, add cron job, add email template, modify auth — which files to touch, which patterns to follow.
Next.js / React: add page, add API endpoint (frontend), add component, modify auth — directory structure, route constants, conventions.
Adapt to whatever frameworks were detected in Step 1.
Summary table of all external services:
| Integration | Env Key(s) | Used by | Key files |
|---|---|---|---|
| Stripe | STRIPE_KEY, STRIPE_SECRET | Payments (Section N) | payment_gateway/views/ |
Per-repo "looking for X? it's in Y" tables:
| Looking for... | Location |
|---|---|
| Django settings | project/settings.py |
| API base config | redux/services/apiSlice.ts |
Mermaid flowchart of app-to-app dependencies:
flowchart TD
user --> booking
user --> project
user --> company
user --> interview
booking --> payment_gateway
booking --> industry
interview --> algolia
project --> company
meeting --> booking
notification --> user
Build from import statements observed during deep mapping. Focus on app-to-app, not file-to-file.
Write at the end of the file:
| # | Section | Status | Updated |
|---|---|---|---|
| 0 | Project Identity & Stack | Complete | YYYY-MM-DD |
| 1 | Data Flow Overview | Complete | YYYY-MM-DD |
| ... | ... | ... | ... |
After all sections are written, go back to the top of the file and:
## Directory
| # | Section | Covers | Key paths |
|---|---------|--------|-----------|
| 0 | Project Identity & Stack | frameworks, env vars, config | settings.py, next.config.js |
| 1 | Data Flow Overview | request lifecycle, auth, token refresh | apiSlice.ts, check_permission.py |
| ... | ... | ... | ... |
| C1 | Shared Patterns | conventions, anti-patterns | cross-cutting |
| C2 | Common Change Patterns | how to add endpoints, models, pages | procedural recipes |
| C3 | Integrations | external services, env keys | service summary |
| C4 | File Index | quick lookup tables | per-repo reference |
| C5 | Dependency Graph | app-to-app imports | adjacency list |
The Covers column should have enough keywords for Claude to match a task to a section without reading section content. The Key paths column lists file paths so Claude can match files it's already working on.
Count the directory lines (from ## Directory to the first --- separator) and update the "How to use" instruction with the actual count.
Update the header with final section/feature counts and today's date.
Report stats:
CODEMAP.md written: {total_lines} lines, {sections} sections, {features} features
Directory: lines 1-{N} (~{tokens} tokens to load)
Full file: ~{total_tokens} tokens
"Mapping complete. I found {N} security issues and {N} patterns during scanning. Want me to run /extract to stage these to ARIA backlogs?"
When the user runs /codemap update:
Read the directory section (first ~80 lines). Extract:
Run: git log --name-only --since="{last_update_date}" --pretty=format:"" -- {repo_paths}
This gives all files changed since the last CODEMAP update. Also check for:
For each changed file, determine which section(s) it affects:
## Update Plan
Changes detected since YYYY-MM-DD:
- 12 files modified, 3 new files, 1 deleted file
Sections to refresh:
- ## 4. AI Interviews — interview/views/interview.py modified, 1 new model
- ## 11. Payments — payment_gateway/views/checkout.py modified
- ## C4. File Index — 3 new files to add
- ## Build Log — update dates
Sections unchanged: 0, 1, 2, 3, 5-10, 12-15, C1-C3, C5
Proceed? (all / numbers to skip / cancel)
For each section to refresh:
## N. to next ## )After all sections are updated:
Last updated date in the headerWhen the user runs /codemap section <name>:
<name> against section names (fuzzy match — "interviews" matches "AI Interviews")^def , ^class , export function ), then read key functions selectively.--- separators between sections are mandatory — they serve as visual breaks and as Grep anchors for section boundaries.npx claudepluginhub mikeprasad/aria-knowledge --plugin aria-knowledgeOrchestrates parallel subagents to map any codebase, creating docs/CODEBASE_MAP.md with architecture, file roles, dependencies, and navigation. Updates incrementally via git or scans.
Produces evidence-cited maps of unfamiliar codebase areas with file:line references for every claim. Use before non-trivial changes, onboarding, or multi-module refactors.
Persists codebase knowledge across sessions to avoid re-discovery. Use after exploration to record, before tasks to consult, or when dispatching subagents with module-specific context.