# Code Doc

> Generates comprehensive documentation for any codebase via hybrid analysis (native extractors + LLM agents). Triggers on phrases like "document this codebase", "generate documentation", "create docs for this repo", "write documentation", "document the code", "generate codebase docs", "create architecture docs", "write a developer guide", "document this project".

- Skill: `leninkhaidem/code-doc` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add leninkhaidem/code-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leninkhaidem/code-doc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: leninkhaidem (https://skillmd.com/u/leninkhaidem)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/leninkhaidem/code-doc

---


# Code-Doc — Adaptive Codebase Documentation

A hybrid documentation generator that combines language-native extractors for API-level accuracy
with LLM agents for synthesis, architecture narratives, and developer guides. Zero-config default —
just point at a repo.

---

## Delegation Model

**Scout orchestrates. Analysts write to files. Doc Writers fan out.**

- **You are the Scout** — handle detection, planning, synthesis, and coordination
- **Analyst agents** (`task(agent_type='explore')`) read code and write full analysis to
  `{project}/.codedoc/` files. They return only compact summaries (max 15 lines) to you.
  You hold summaries, not full analysis — this prevents context overflow.
- **Doc Writer agents** (`task(agent_type='general-purpose')`) each read assigned `.codedoc/`
  files and produce one output document
- **Reviewer agents** (`task(agent_type='explore')`) validate generated docs
- All agents are stateless — provide complete context in each spawn

The `.codedoc/` directory is transient — created at analysis start, consumed by doc writers,
and cleaned up before handoff. Never commit it. Prefer adding `.codedoc/` to
`.git/info/exclude` for the local run; only modify project `.gitignore` if the user explicitly
approves that as part of the documentation plan or commit proposal.

### Analyst Output Protocol

Every analyst agent must:

1. Write full analysis to their assigned `.codedoc/{name}-analysis.md` file
2. Cite source paths for material claims and include confidence (`high`/`medium`/`low`) where evidence is incomplete or inferred
3. Return ONLY a compact summary to you (max 15 lines):
   - File written path
   - Key stats (counts, patterns found)
   - Notable findings or anomalies
   - Lowest-confidence claims needing synthesis/reviewer attention

### Secret Redaction Rules

Generated docs must never expose secret values, tokens, credentials, private URLs, or production-only
connection strings. For config/security/env docs, document only variable names, purpose, expected
format, safe defaults, and source file paths. Redact observed values as `<redacted>` and flag
suspected secrets for user handling instead of copying them into `.codedoc/` or final docs.

---

## Workflow

### Step 1 — Scout & Detect

Accept the repository path (defaults to cwd). Scan the codebase:

1. Detect project type, languages, frameworks, and libraries
2. Identify architecture patterns, entry points, and module boundaries
3. Detect monorepo structure if present
4. `--with-build` flag (optional) — enables build-assisted analysis for resolved types

**Monorepo handling:** If workspace patterns detected (`pnpm-workspace.yaml`, `lerna.json`,
`packages/*/package.json`, etc.), list sub-projects and let user choose **unified** (single doc set)
or **per-project** (separate docs per package). Per-project repeats Steps 2–8 for each.

---

### Step 2 — Assess Existing Docs

Inventory existing documentation and classify:

| Level | Action |
|-------|--------|
| **No docs** | Fresh generation |
| **Partial** | Fill gaps, preserve existing |
| **Comprehensive** | Augment-only — propose additions, never overwrite. Preserve `<!-- human -->` blocks entirely. |

**README protection default:** Do not blindly overwrite an existing human README. Generate or rewrite
`README.md` only when it is missing, tiny/template-like, already code-doc-generated, or explicitly approved
by the user. Otherwise preserve it, generate supporting docs, and optionally propose a small
link section for user approval.

---

### Step 3 — Propose Doc Plan

Present the plan to the user for confirmation before proceeding.

**Core targets** (generated by default, except protected README):

| Document | Purpose | Generation rule |
|----------|---------|-----------------|
| `README.md` | Project overview, quick start | Protected core target: generate/rewrite only if missing, tiny/template-like, already code-doc-generated, or explicitly approved; otherwise preserve and optionally propose a small link/index patch |
| `docs/architecture-guide.md` | System design, component relationships | Always generated |
| `docs/developer-guide.md` | Setup, development workflow | Always generated |
| `docs/codebase-context.md` | LLM-optimized codebase summary | Always generated |

**Artifact catalog** (scout recommends based on codebase analysis):

| Document | Purpose | Condition |
|----------|---------|-----------|
| `docs/navigation.md` | Entry points, capability-to-file map, "how do I add X" guides | Codebase has >10 source files |
| `docs/patterns.md` | Naming conventions, code patterns, anti-hallucination index, inconsistencies | Always recommended |
| `docs/config.md` | Env vars, config files, feature flags with defaults and locations | `process.env`/config file usage detected |
| `docs/errors.md` | Error taxonomy, throw/catch mapping, unhandled gaps | Custom error classes or >5 distinct throw sites |
| `docs/flows.md` | Request lifecycle, state machines, event propagation | HTTP middleware, state enums, or event emitters detected |
| `docs/boundaries.md` | Layer rules, module contracts, import violations | Multi-directory architecture with >3 top-level modules |
| `docs/inventory.md` | Utility registry — "before you write it, we have it" | `utils/`, `lib/`, `helpers/`, or `shared/` directories |
| `docs/security.md` | Route auth matrix, input validation audit, concerns | Auth middleware, route definitions, or secrets handling |

**Scout recommendation process:**

1. After detection (Step 1), evaluate each catalog artifact's condition against the codebase
2. Recommend artifacts whose conditions are met, with a one-line justification per selection
3. Optionally propose up to **3 custom artifacts** not in the catalog — each requires a name,
   purpose, and justification explaining why this codebase warrants it
4. Present the full doc plan (core targets, including README decision, + recommended artifacts) to the user for confirmation

Example scout output:

```
Core: README.md (protected target; conditional writer), architecture-guide.md, developer-guide.md, codebase-context.md

Recommended artifacts:
  ✅ navigation.md — 47 source files across 8 directories
  ✅ patterns.md — always recommended
  ✅ config.md — 12 process.env references found
  ✅ flows.md — Express middleware chain + 3 state enums detected
  ⬚ errors.md — only 2 throw sites, insufficient for standalone doc
  ⬚ boundaries.md — flat directory structure
  ⬚ inventory.md — no utils/lib/helpers directories
  ⬚ security.md — no auth middleware detected

Custom: (none proposed)
```

Wait for user confirmation before proceeding.

---

### Step 4 — Analyze

**Always delegate analysis to sub-agents.** Do not attempt to analyze the codebase yourself.

1. Create analysis directory: `mkdir -p {project}/.codedoc`
2. Run **native extractors** first (if available): TypeDoc, Sphinx, godoc, javadoc, rustdoc, DocFX.
   Save output to `.codedoc/native-extractors/`. This provides ground-truth for signatures and types.
   Also write `.codedoc/native-extractors/report.md` listing each extractor considered with status
   (`attempted`, `ran`, `failed`, or `skipped`), command, output path, and failure/skip reason.
   Treat `.codedoc/native-extractors/*` as transient unless explicitly exported in the confirmed plan;
   before cleanup, copy extractor status/transparency into persisted synthesis/handoff data.
3. **Spawn analyst agents** in parallel based on the confirmed doc plan:

| Agent | Condition | Output File |
|-------|-----------|-------------|
| Architecture Analyst | Always | `.codedoc/architecture-analysis.md` |
| Catalog Artifact Analyst (×N) | One per selected artifact from Step 3 | `.codedoc/{artifact-name}-analysis.md` |
| Custom Artifact Analyst (×M) | One per approved custom artifact | `.codedoc/{custom-name}-analysis.md` |

For example, if Step 3 selected `navigation`, `patterns`, `config`, and `flows`, spawn 5 analysts:
Architecture + Navigation + Patterns + Config + Flows.

Each analyst is spawned with a complete stateless prompt containing:
- Confirmed doc plan, selected artifact/custom artifact, and assigned `.codedoc/{name}-analysis.md` path
- Update mode (`Fresh`, `Regenerate`, or `Augment`), protected paths, README protection decision, and approved/non-approved output locations relevant to their scope
- Project context: repository path, framework/language detections, monorepo scope, entry points, file/include/exclude scope, and synthesis questions to answer
- Native extractor context: `.codedoc/native-extractors/` output path plus report/status summary when available; prefer extractor evidence for signatures/types
- Secret redaction rules and any known sensitive files/values to avoid copying into analysis
- Citation/confidence protocol: cite source paths for material claims, mark inferred or incomplete claims `high`/`medium`/`low`, and list evidence gaps
- Source/path evidence requirements: verify referenced files exist, distinguish observed code facts from inferred architecture, and include path evidence for APIs, flows, config, and dependencies
- Output/report structure: overview, key findings, source inventory, relationships/flows, risks/anomalies, evidence table, and low-confidence items requiring synthesis/reviewer attention

They write full analysis and return a compact summary.

---

### Step 5 — Synthesize

Read `.codedoc/` files selectively (not all at once) and build a unified model:

1. Unify data models — merge native extractor types with analyst findings
2. Correlate cross-cutting concerns — trace flows across components
3. Detect inconsistencies between analyst outputs
4. Identify documentation-worthy flows and key paths
5. Include native extractor transparency from `.codedoc/native-extractors/report.md`, including
   statuses, commands, output paths, and failure/skip reasons, so this evidence survives cleanup
6. Write synthesis to `{project}/.codedoc/synthesis.md`

---

### Step 6 — User Checkpoint

Present synthesis summary: architecture pattern, component count, data flows, API endpoints,
key findings, and any inconsistencies. User confirms, aborts, or requests re-analysis of a
specific area.

---

### Step 7 — Generate

Fan out documentation generation to parallel doc writer agents.

Each writer is spawned via `task(agent_type='general-purpose')` with a complete stateless prompt containing:
- Confirmed doc plan and assigned output file path
- Update mode (`Fresh`, `Regenerate`, or `Augment`) and merge/preservation instructions
- Protected paths, README protection decision, and whether README writing was explicitly approved
- Target audience, tone/style, terminology preferences, and desired depth
- Frontmatter/metadata schema and required version/hash/timestamp values
- Secret redaction rules and any project-specific sensitive files or values to avoid
- Source/path citation expectations for material claims and API details
- No-placeholder rule: no TODO/TBD/filler sections; omit or mark low-confidence with evidence instead
- Relevant `.codedoc/` analysis files, native extractor report/status summary, and synthesis summary

Spawn the README writer only if README is missing, tiny/template-like, already code-doc-generated, or
explicitly approved. If README is protected, preserve it and optionally propose a small link/index
patch for user approval. Architecture, Developer Guide, and Codebase Context writers always spawn.
Optional writers spawn based on the doc plan from Step 3.

All generated docs **must** include frontmatter (the Accuracy reviewer will flag missing fields as 🔴 BLOCKER):

```yaml
---
codedoc_version: 1
generated: "<ISO 8601 timestamp>"
project_hash: "<short git hash from `git rev-parse --short HEAD`, or `uncommitted`/`no-git` when unavailable>"
---
```

**Update mode** (re-generation):

IF existing docs detected, READ `references/update-merge.md` for archive, human block preservation, and augmentation logic.

| Mode | Condition | Behavior |
|------|-----------|----------|
| **Fresh** | No existing docs | Generate approved targets; still apply README protection if a README exists |
| **Regenerate** | Existing code-doc output (`codedoc_version` frontmatter) | Archive to `.docs-archive/v{N}/`, regenerate, merge `<!-- human -->` blocks |
| **Augment** | Existing human docs (no frontmatter, high quality) | Preserve entirely, add only to `docs/codedoc/` subdirectory |

---

### Step 8 — Review & Handoff

Spawn 3 reviewer agents (`task(agent_type='explore')`) in parallel. Each reviewer is spawned with a complete stateless prompt containing:
- Confirmed doc plan, generated/modified doc paths, update mode (`Fresh`, `Regenerate`, or `Augment`), protected paths, README decision, and approved output scope
- Frontmatter/metadata expectations, including `codedoc_version`, `generated`, `project_hash`, and `augmentation_mode: true` where relevant
- Secret redaction rules and the requirement to flag leaked values without repeating the secret value
- Native extractor report/status summary, synthesis summary, and relevant `.codedoc/` analysis file paths or excerpts needed for the review focus
- Citation/confidence protocol: require path/source evidence for challenged claims, confidence labels for uncertain findings, and no unsupported reviewer assertions
- Source/path evidence requirements: verify cited source paths and generated doc paths exist, cross-check API/signature claims against native extractor output where available, and distinguish missing evidence from false claims
- Output/report structure: verdict, blocker/warning/info findings, affected docs, challenged claims, evidence paths/sources, confidence, recommended fixes, and explicit pass/fail on their focus area


| Reviewer | Focus |
|----------|-------|
| **Accuracy** | Cross-reference against native extractor output, verify code paths exist, confirm every generated doc has valid frontmatter (`codedoc_version`, `generated`, `project_hash`) |
| **Completeness** | All planned sections populated, no TODO placeholders |
| **Clarity** | Writing quality, consistent terminology, actionable instructions |

Each reviewer finding must include: severity, affected doc, claim being challenged, evidence
path/source, confidence (`high`/`medium`/`low`), and recommended fix.

Severity: 🔴 BLOCKER (must fix) · 🟠 WARNING (should fix) · 🟡 INFO (optional).
Fix all 🔴s. User decides on 🟠s. Maximum 2 fix iterations.

If blockers remain after 2 iterations, summarize unresolved items and recommend adding a
`## Known Issues` section. Do not append Known Issues or proceed with degraded docs until the
user explicitly approves.

After review is ready:

1. Persist native extractor transparency from `.codedoc/native-extractors/report.md` into the
   synthesis/handoff notes before cleanup; `.codedoc/native-extractors/*` paths are transient unless
   the confirmed plan explicitly exported them
2. Clean transient analysis artifacts first: `rm -rf {project}/.codedoc`
3. Re-check git state with `git status --short` and verify `.codedoc/` is absent
4. Present a **Documentation Handoff Contract**:
   - Generated/modified documentation files
   - Any archive paths (`.docs-archive/`) and whether they are excluded from the proposed commit
   - Any `.gitignore` change and why it is needed
   - Native extractor transparency: attempted/ran/failed/skipped extractors, commands, output paths, and reasons
   - Review result summary and unresolved warnings
   - Proposed commit message: `docs: generate codebase documentation via code-doc`
5. Ask the user what to do next

**Commit policy:**

- Never run `git add`, `git commit`, or `git add .` automatically.
- If the user declines a commit, leave the generated docs uncommitted and report changed paths.
- If the user explicitly approves a commit:
  1. Stage only approved pathspecs, never broad `git add .`
  2. Exclude `.codedoc/` always
  3. Exclude `.docs-archive/` by default unless the user explicitly approves archiving it
  4. Run `git diff --cached --stat` (or equivalent status summary) and confirm staged scope is correct
  5. Commit with the approved message
  6. Report the commit hash and changed files

---

## Sub-Agent Summary

| Role | Agent Type | Model |
|------|-----------|-------|
| Analyst | `explore` | Haiku |
| Doc Writer | `general-purpose` | Sonnet |
| Reviewer | `explore` | Sonnet |

---

_Designed for multi-agent orchestration. Requires: `git`, native extractors per language (optional)._