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:

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):

Artifact catalog (scout recommends based on codebase analysis):

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:

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):

---
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.

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

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

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