Documentation and Codemaps
Overview
The doc-updater agent maintains code maps and documentation in sync with the actual codebase. This guide consolidates three components: the agent definition, the codemap generation workflow, and the documentation update workflow.
Part 2: Codemap Generation
Step 1: Scan Project
- Identify project type (monorepo, single app, library, microservice)
- Find all source directories (src/, lib/, app/, packages/)
- Map entry points (main.ts, index.ts, app.py, main.go, etc.)
Step 2: Generate Codemaps
Output to docs/CODEMAPS/ or .reports/codemaps/:
| File | Contents |
|---|---|
architecture.md |
High-level system diagram, service boundaries, data flow |
backend.md |
API routes, middleware chain, service-to-repository mapping |
frontend.md |
Page tree, component hierarchy, state management flow |
data.md |
Database tables, relationships, migration history |
dependencies.md |
External services, third-party integrations, shared libraries |
Codemap Format (Token-Lean)
# Backend Architecture
## Routes
POST /api/users -> UserController.create -> UserService.create -> UserRepo.insert
GET /api/users/:id -> UserController.get -> UserService.findById -> UserRepo.findById
## Key Files
src/services/user.ts (business logic, 120 lines)
src/repos/user.ts (database access, 80 lines)
## Dependencies
- PostgreSQL (primary data store)
- Redis (session cache, rate limiting)
Step 3: Diff Detection
- If changes > 30%, show diff and request approval before overwriting
- If changes <= 30%, update in place
Step 4: Metadata Header
<!-- Generated: 2026-02-11 | Files scanned: 142 | Token estimate: ~800 -->
Tips
- Focus on high-level structure, not implementation details
- Prefer file paths and function signatures over full code blocks
- Keep each codemap under 1000 tokens
- Use ASCII diagrams for data flow
- Run after major features or refactoring sessions
Part 3: Documentation Updates
Sources of Truth
| Source | Generates |
|---|---|
package.json scripts |
Available commands reference |
.env.example |
Environment variable documentation |
openapi.yaml / route files |
API endpoint reference |
| Source code exports | Public API documentation |
Dockerfile / docker-compose.yml |
Infrastructure setup docs |
Generated Artifacts
- Script Reference -- Table of all commands from package.json/Makefile/pyproject.toml
- Environment Docs -- Variables categorized as required vs optional with formats and examples
- Contributing Guide -- Setup, scripts, testing, code style, PR checklist
- Runbook -- Deployment procedures, health checks, common issues, rollback, escalation
Staleness Check
Find docs not modified in 90+ days, cross-reference with recent code changes, flag for manual review.
Rules
- Single source of truth: Always generate from code
- Preserve manual sections: Only update generated sections
- Mark generated content: Use
<!-- AUTO-GENERATED -->markers - Don't create docs unprompted: Only when explicitly requested