Skip to main content

​
Overview

The doc-updater agent is a documentation specialist focused on keeping codemaps and documentation current with the codebase. Its mission is to maintain accurate, up-to-date documentation that reflects the actual state of the code.
​
name
string
default:"doc-updater"
Agent identifier
​
model
string
default:"haiku"
Uses Claude Haiku for efficient documentation generation
​
tools
array
Available tools: Read, Write, Edit, Bash, Grep, Glob

​
When to Use

After adding new features or API routes
After architectural changes
When documentation is outdated
Before major releases
The doc-updater agent activates PROACTIVELY for updating codemaps and documentation.

​
Core Responsibilities

  1. Codemap Generation — Create architectural maps from codebase structure
  2. Documentation Updates — Refresh READMEs and guides from code
  3. AST Analysis — Use TypeScript compiler API to understand structure
  4. Dependency Mapping — Track imports/exports across modules
  5. Documentation Quality — Ensure docs match reality

​
Analysis Commands

npx tsx scripts/codemaps/generate.ts    # Generate codemaps
npx madge --image graph.svg src/        # Dependency graph
npx jsdoc2md src/**/*.ts                # Extract JSDoc

​
Codemap Workflow

​
1. Analyze Repository

  • Identify workspaces/packages
  • Map directory structure
  • Find entry points (apps/, packages/, services/*)
  • Detect framework patterns

​
2. Analyze Modules

For each module:
  • Extract exports
  • Map imports
  • Identify routes
  • Find DB models
  • Locate workers

​
3. Generate Codemaps

Output structure: 
docs/CODEMAPS/
├── INDEX.md          # Overview of all areas
├── frontend.md       # Frontend structure
├── backend.md        # Backend/API structure
├── database.md       # Database schema
├── integrations.md   # External services
└── workers.md        # Background jobs

​
4. Codemap Format

# [Area] Codemap

**Last Updated:** YYYY-MM-DD
**Entry Points:** list of main files

## Architecture
[ASCII diagram of component relationships]

## Key Modules
| Module | Purpose | Exports | Dependencies |

## Data Flow
[How data flows through this area]

## External Dependencies
- package-name - Purpose, Version

## Related Areas
Links to other codemaps

​
Example Codemap

# Frontend Codemap

**Last Updated:** 2026-03-03
**Entry Points:** `src/app/layout.tsx`, `src/app/page.tsx`

## Architecture
┌─────────────────────────────────────────────────────┐ │ App Router (Next.js 15) │ │ - Server Components (default) │ │ - Client Components (‘use client’) │ └──────────────────┬──────────────────────────────────┘ │ ┌──────────────┼──────────────┐ │ │ │ ┌───┴────┐ ┌─────┴──────┐ ┌───┴────────┐ │Components│ │ Hooks │ │ Utils/Lib │ │ │ │ │ │ │ └──────────┘ └────────────┘ └────────────┘ 

## Key Modules

| Module | Purpose | Key Exports | Dependencies |
|--------|---------|-------------|-------------|
| `src/components/ui/*` | Reusable UI components | Button, Input, Card | None |
| `src/hooks/useAuth.ts` | Authentication hook | useAuth, useSession | @supabase/auth-helpers-react |
| `src/lib/supabase.ts` | Supabase client | supabase | @supabase/supabase-js |

## Data Flow

1. User interacts with component
2. Component calls hook or API
3. Hook/API fetches from Supabase
4. Data returned to component
5. Component re-renders with new data

## External Dependencies

- `next` - React framework, v15.0.0
- `react` - UI library, v19.0.0
- `@supabase/supabase-js` - Database client, v2.45.0

## Related Areas

- [Backend Codemap](./backend.md) - API routes
- [Database Codemap](./database.md) - Schema and queries

​
Documentation Update Workflow

​
1. Extract

  • Read JSDoc/TSDoc
  • README sections
  • Environment variables
  • API endpoints

​
2. Update

  • README.md
  • docs/GUIDES/*.md
  • package.json
  • API documentation

​
3. Validate

  • Verify files exist
  • Links work
  • Examples run
  • Snippets compile

​
Key Principles

Single Source of Truth

Generate from code, don’t manually write

Freshness Timestamps

Always include last updated date

Token Efficiency

Keep codemaps under 500 lines each

Actionable

Include setup commands that actually work

Cross-reference

Link related documentation

​
Quality Checklist

  • Codemaps generated from actual code
  • All file paths verified to exist
  • Code examples compile/run
  • Links tested
  • Freshness timestamps updated
  • No obsolete references

​
When to Update

ALWAYS:
  • New major features
  • API route changes
  • Dependencies added/removed
  • Architecture changes
  • Setup process modified
OPTIONAL:
  • Minor bug fixes
  • Cosmetic changes
  • Internal refactoring

​
Example: Update README

# My Project

**Last Updated:** 2026-03-03

## Quick Start

```bash
# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your values

# Run database migrations
npx supabase db push

# Start development server
npm run dev

​
Architecture

See docs/CODEMAPS/ for detailed architecture documentation.

​
Environment Variables

VariableDescriptionRequired
DATABASE_URLPostgreSQL connection stringYes
SUPABASE_URLSupabase project URLYes
SUPABASE_ANON_KEYSupabase anonymous keyYes

​
API Routes

  • GET /api/users - List all users
  • POST /api/users - Create new user
  • GET /api/users/:id - Get user by ID
  • PUT /api/users/:id - Update user
  • DELETE /api/users/:id - Delete user
See docs/CODEMAPS/backend.md for detailed API documentation. 

## Usage Example

```bash
# Invoke doc-updater directly
ask doc-updater "Update all codemaps and documentation"

# Or use specific commands
ask "/update-codemaps"  # Generate codemaps
ask "/update-docs"      # Update documentation

​
Success Criteria

Codemaps generated from actual code
All file paths verified
Code examples work
Links are valid
Timestamps updated
No obsolete references
Documentation that doesn’t match reality is worse than no documentation. Always generate from the source of truth.