update-codemap

name	update-codemap
description	Update docs/technical/CODEMAP.md by scanning the current codebase structure. Run after a significant feature merge, refactor, or when CODEMAP feels stale. Owned by @technical-director and @lead-programmer.
argument-hint	[optional: specific module or area to update]
user-invocable	true
allowed-tools	Read, Write, Edit, Glob, Grep, Bash
effort	3

Update docs/technical/CODEMAP.md to accurately reflect the current state of the codebase.

A stale CODEMAP misleads agents more than having none. Run this skill after any significant feature merge, refactor, or directory restructure.

Steps

1. Determine scope

If $ARGUMENTS is provided, update only the section(s) relevant to the named module or area.

If $ARGUMENTS is empty, perform a full CODEMAP refresh.

2. Read current CODEMAP

Read docs/technical/CODEMAP.md to understand what is currently documented.

3. Scan the codebase

Run the following to get the current structure:

# Top-level src/ structure
find src/ -type f -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.go" 2>/dev/null | sort | head -100

# API routes / handlers
grep -r "router\.\|app\.\|@Get\|@Post\|@Put\|@Delete\|@Patch" src/ --include="*.ts" --include="*.js" --include="*.py" -l 2>/dev/null

# Exported utilities
grep -r "^export function\|^export const\|^def \|^func " src/ --include="*.ts" --include="*.js" --include="*.py" --include="*.go" -l 2>/dev/null | head -30

Also read docs/technical/API.md and docs/technical/DATABASE.md if they exist — they contain authoritative specs for the API and schema sections.

4. Update CODEMAP sections

For each section in CODEMAP.md, update the table rows to reflect what actually exists:

• Application Modules: One row per top-level module/feature directory in src/
• API Endpoints: One row per route group (not every individual endpoint — use route prefixes)
• Shared Utilities: One row per utility file or helper module
• Data Models: One row per major entity/table
• External Integrations: One row per third-party service

Rules:

• Remove rows for modules/files that no longer exist
• Add rows for new modules/files
• Keep descriptions concise — one sentence max
• If a section has no entries yet, keep the *(not yet populated)* placeholder row
• Do not over-document — only include modules that other agents would need to find

5. Update Revision History

Append a row to the Revision History table:

| [today's date] | @lead-programmer (or @technical-director) | [brief summary: "added X module, removed Y, updated API section"] |

6. Confirm

Print:

CODEMAP updated. [N] modules documented across [M] sections.
Stale entries removed: [list or "none"]
New entries added: [list or "none"]

---

Staleness indicators

CODEMAP should be re-run when:

• A new feature directory is added to src/
• An existing module is renamed, moved, or deleted
• New API route groups are added
• New third-party integrations are wired in
• An agent says "I couldn't find X" when X should exist

Tip: After running /orchestrate on a large feature, run /update-codemap as the final step before closing the feature branch.