Superdocs: Deep Project Documentation Generator

Generate a docs/ directory of markdown files that give AI agents and human contributors deep context on any project.

References: See RESEARCH-PROMPTS.md for codebase exploration prompts, DOC-TEMPLATES.md for document templates, EXAMPLE-OUTPUT.md for a sample output walkthrough.

Philosophy

Documentation should answer three questions at every level:

Most documentation answers WHAT. Good documentation answers HOW. Great documentation answers WHY. Docgen targets all three.

Invocation

/superdocs                         # Interactive - prompts for project root
/superdocs @README.md @CLAUDE.md   # With context files as hints

Headless / CI Usage

# From the project root
./scripts/generate-docs.sh

# Or with options
./scripts/generate-docs.sh --project-dir /path/to/project --output-dir docs --mode full

See scripts/generate-docs.sh for CI integration details.

Output Structure

Docgen produces the following files in the output directory (default: docs/):

docs/
  overview.md          # WHAT: Project identity, purpose, scope
  architecture.md      # HOW + WHY: System design, component relationships
  getting-started.md   # HOW: Setup, prerequisites, first run
  development.md       # HOW: Contributing, testing, deploying
  adr/                 # WHY: Architecture Decision Records
    README.md          #   Index of all ADRs with status summary
    0001-[title].md    #   Individual ADR per significant decision
    0002-[title].md    #   ...numbered sequentially
  glossary.md          # WHAT: Domain terms, acronyms, project-specific jargon

Each file is self-contained and cross-linked. AI agents can read any single file for focused context, or read all files for full project understanding.

Core Workflow

+-----------------------------------------------------------------------+
|                          SUPERDOCS WORKFLOW                               |
+-----------------------------------------------------------------------+
|                                                                       |
|  1. DISCOVER       ->  Scan project structure, detect stack, read     |
|        |               existing docs                                  |
|        v                                                              |
|  2. RESEARCH       ->  Deep-dive with parallel agents: architecture,  |
|        |               patterns, decisions, domain concepts           |
|        v                                                              |
|  3. OUTLINE        ->  Plan doc structure, identify gaps, confirm     |
|        |               with user (interactive) or proceed (headless)  |
|        v                                                              |
|  4. GENERATE       ->  Write all markdown files with WHAT/HOW/WHY    |
|        |               coverage at every level                        |
|        v                                                              |
|  5. VERIFY         ->  Cross-check completeness, validate links,     |
|                        report coverage summary                        |
|                                                                       |
+-----------------------------------------------------------------------+

Reference Index

Read the relevant reference BEFORE starting each phase.

Phase 1: DISCOVER – Scan the Project

Step 1: Identify Project Root and Existing Documentation

DISCOVERY CHECKLIST
--------------------

1. Confirm project root directory (cwd or user-specified)
2. Read existing docs in priority order:
   - README.md (primary project description)
   - CLAUDE.md / AGENTS.md (agent context)
   - CONTRIBUTING.md (development workflow)
   - CHANGELOG.md / HISTORY.md (evolution)
   - docs/ directory (existing documentation)
   - .github/ (CI, issue templates, PR templates)
3. Record what already exists vs what needs generating

Step 2: Detect Technology Stack

Identify the primary language, framework, and tooling:

Step 3: Build Project Tree

Generate a .gitignore-aware tree snapshot:

tree --gitignore -a -L 3

If --gitignore is unavailable, use tree -a -L 3 --prune and manually exclude ignored paths.

Save the tree output for use in architecture documentation.

Step 4: Estimate Project Scope

CHECKPOINT – Phase 1

DISCOVERY COMPLETE
-------------------

Project: [name]
Stack: [language/framework]
Size: [small/medium/large]
Existing docs: [list what already exists]
Docs to generate: [list what's missing]

Phase 2: RESEARCH – Deep Codebase Analysis

STOP. Read RESEARCH-PROMPTS.md NOW for exact agent prompts.

Launch Parallel Research Agents

Launch 5 parallel Explore agents to gather comprehensive project context:

LAUNCHING RESEARCH AGENTS
--------------------------

Agent 1: Architecture & Structure      [scanning...]
Agent 2: Patterns & Conventions        [scanning...]
Agent 3: Domain & Business Logic       [scanning...]
Agent 4: Build, Test & Deploy Pipeline [scanning...]
Agent 5: Decision Archaeology          [scanning...]

Estimated time: 2-5 minutes

Agent 1: Architecture & Structure

Discovers the high-level system design:

• Entry points (main files, server startup, CLI entry)
• Module/package boundaries
• Data flow (request lifecycle, event flow, pipeline stages)
• External dependencies and integrations
• Database schemas and data models

Agent 2: Patterns & Conventions

Identifies how code is written:

• Naming conventions (files, functions, variables)
• Error handling patterns
• Logging approach
• Configuration management
• Code organization style (feature-based, layer-based, etc.)

Agent 3: Domain & Business Logic

Captures what the project actually does:

• Core domain concepts and entities
• Business rules and validation logic
• User-facing features and capabilities
• API surface area (endpoints, commands, exports)
• Key algorithms or processing pipelines

Agent 4: Build, Test & Deploy Pipeline

Maps the development lifecycle:

• How to install dependencies
• How to run the project locally
• How to run tests (unit, integration, e2e)
• How to build for production
• How to deploy (if applicable)
• CI/CD pipeline stages

Agent 5: Decision Archaeology

Mines project history and artifacts for architecture decisions:

• Git history: significant commits, merge commits, tag messages, large refactors
• Plan files: any planning documents, RFCs, design docs in the repo
• Code comments: // WHY:, // DECISION:, // NOTE:, rationale in docstrings
• Dependency choices: why specific libraries were chosen (README, commit messages)
• Configuration patterns: why certain tools/configs are used
• CHANGELOG / HISTORY entries explaining breaking changes
• Existing ADRs or decision records (if any)
• PR/MR descriptions referenced in merge commits

Verify Research Results

After agents complete, compile and cross-check:

• Architecture findings are consistent across agents
• No contradictory claims about project structure
• Domain concepts align with actual code
• Build/test commands are accurate (verify by reading config files)
• Decision archaeology findings have supporting evidence (commits, code, docs)

CHECKPOINT – Phase 2

RESEARCH COMPLETE
------------------

Architecture style: [monolith/microservices/serverless/library/CLI/etc.]
Key components: [list top 5-8]
Domain concepts: [list core entities]
Build pipeline: [list key commands]
Decisions found: [count] from git history, [count] from code/docs, [count] inferred
ADR candidates: [list decision titles]

Phase 3: OUTLINE – Plan Documentation Structure

Determine Which Documents to Generate

Based on project size and existing documentation:

Outline Each Document

For each document, plan the sections based on research findings:

DOCUMENT OUTLINE
-----------------

overview.md:
  - Project name and one-line description
  - Problem statement (WHY this exists)
  - Key features / capabilities (WHAT it does)
  - Target audience
  - Project status and maturity

architecture.md:
  - System diagram (text-based)
  - Component breakdown
  - Data flow
  - Key interfaces and boundaries
  - Design decisions (WHY these components)

getting-started.md:
  - Prerequisites
  - Installation steps
  - Configuration
  - First run / hello world
  - Common issues

development.md:
  - Repository structure
  - Development workflow
  - Testing strategy
  - Code style and conventions
  - CI/CD pipeline

adr/README.md:
  - Index of all ADRs with status and summary
  - Link to each individual ADR file

adr/NNNN-[title].md (one per decision):
  - Status (Accepted / Superseded / Deprecated)
  - Context: situation, constraints, forces at play
  - Decision: what was chosen
  - Consequences: benefits, trade-offs, alternatives considered
  - Sources: git commits, plan files, code references that evidence the decision

glossary.md:
  - Alphabetical term list
  - Each entry: Term, Definition, Context/Usage

Interactive Mode: Confirm with User

In interactive mode, present the outline and ask:

DOCUMENTATION PLAN
-------------------

I'll generate the following docs:
  1. overview.md      - Project identity and purpose
  2. architecture.md  - System design and components
  3. getting-started.md - Setup and first run
  4. development.md   - Contributing and testing
  5. adr/             - Architecture Decision Records
  6. glossary.md      - Domain terminology

Output directory: docs/

Proceed with this plan? (y/n)
Any documents to skip or add?

Headless Mode: Proceed Automatically

In headless mode (CI), generate all applicable documents without prompting.

Phase 4: GENERATE – Write Documentation

STOP. Read DOC-TEMPLATES.md NOW for document templates.

Writing Principles

1. Facts over opinions – State what IS, not what SHOULD BE
2. Specific over general – Use actual file paths, command names, config values
3. WHY alongside WHAT – Every structural choice deserves rationale
4. Cross-link liberally – Reference other docs in the set
5. Code examples from the actual codebase – Not hypothetical snippets
6. Keep it current-state – Document what exists now, not aspirations
7. Concise but complete – No fluff, no gaps

Writing Order

Generate documents in this order (each builds on the previous):

1. glossary.md first – establishes shared vocabulary
2. overview.md – uses glossary terms, sets context
3. architecture.md – references overview for scope, links to glossary
4. getting-started.md – references architecture for understanding
5. development.md – references getting-started for setup, architecture for structure
6. adr/ last – each ADR references relevant docs, captures cross-cutting rationale
   • Write adr/README.md index first
   • Write individual adr/NNNN-title.md files, numbered sequentially

Per-Document Process

For each document:

1. Read the template from DOC-TEMPLATES.md
2. Fill in sections using research findings from Phase 2
3. Add cross-links to other documents in the set
4. Include actual paths, commands, and code snippets from the project
5. Flag any sections where information was uncertain with <!-- TODO: verify -->

Output Location

Write all files to the output directory:

mkdir -p docs/adr/

Write each file using the Write tool.

CHECKPOINT – Phase 4

After all documents are written:

GENERATION COMPLETE
--------------------

Files written:
  docs/overview.md              [X lines]
  docs/architecture.md          [X lines]
  docs/getting-started.md       [X lines]
  docs/development.md           [X lines]
  docs/adr/README.md            [X lines]
  docs/adr/0001-[title].md      [X lines]
  docs/adr/0002-[title].md      [X lines]
  ...
  docs/glossary.md              [X lines]

Total: [N] files ([M] ADRs), [L] total lines

Phase 5: VERIFY – Validate Documentation

Completeness Check

Verify WHAT/HOW/WHY coverage across all documents:

COVERAGE MATRIX
----------------

                    WHAT    HOW     WHY
overview.md         [x]     [ ]     [x]
architecture.md     [x]     [x]     [x]
getting-started.md  [x]     [x]     [ ]
development.md      [x]     [x]     [ ]
adr/                [ ]     [ ]     [x]     [N] ADR files
glossary.md         [x]     [ ]     [ ]

Legend: [x] = covered, [ ] = not applicable for this doc

Cross-Link Validation

Verify that documents reference each other where appropriate:

• overview.md links to architecture.md for deeper technical context
• overview.md links to getting-started.md for setup
• architecture.md links to glossary.md for domain terms
• architecture.md links to adr/README.md for design rationale
• getting-started.md links to development.md for next steps
• development.md links to architecture.md for structure context
• adr/README.md links to each individual ADR file
• Individual ADRs link back to relevant docs (architecture.md, development.md, etc.)

Accuracy Spot-Check

For each document, verify at least 2 claims against the actual codebase:

• File paths mentioned actually exist
• Commands listed actually work (check package.json/Makefile/Justfile)
• Dependencies listed match actual package files
• Architecture description matches actual directory structure

TODO Audit

Search all generated docs for <!-- TODO: verify --> markers:

• List all TODOs found
• In interactive mode: ask user to clarify
• In headless mode: leave markers in place and list in summary

Final Summary

SUPERDOCS COMPLETE
================

Project: [name]
Output: docs/
Files: [N]
Total lines: [M]

WHAT coverage: [X/N] documents
HOW coverage:  [X/N] documents
WHY coverage:  [X/N] documents

Cross-links: [X/Y] verified
TODOs remaining: [N] (items needing human verification)

Documents generated:
  docs/overview.md
  docs/architecture.md
  docs/getting-started.md
  docs/development.md
  docs/adr/README.md
  docs/adr/0001-[title].md
  docs/adr/...
  docs/glossary.md

Headless Mode (CI / Automation)

When invoked via scripts/generate-docs.sh, superdocsruns without user interaction:

1. No confirmation prompts – generates all applicable documents
2. Stdout progress – prints phase progress to stdout for CI logs
3. Exit codes – 0 on success, non-zero on failure
4. TODO markers – places <!-- TODO: verify --> instead of asking
5. Idempotent – safe to run repeatedly; overwrites existing docs/

See scripts/generate-docs.sh for implementation.

Incremental Updates

When docs/ already exists, superdocscan update rather than regenerate:

1. Read existing docs to understand current state
2. Diff against codebase to find what changed
3. Update only stale sections rather than rewriting everything
4. Preserve manual edits outside of generated sections

In incremental mode, wrap generated content with markers:

<!-- superdocs:start:section-name -->
Generated content here...
<!-- superdocs:end:section-name -->

Content outside markers is preserved during updates.

Tone and Style

Key Principles

1. WHAT + HOW + WHY – Answer all three at every level of documentation
2. Actual over aspirational – Document what exists, not what’s planned
3. Self-contained files – Each doc is useful on its own
4. Cross-linked set – Together they form a complete picture
5. Machine-readable – AI agents can parse and use the docs effectively
6. Human-readable – Developers can navigate and understand quickly
7. CI-friendly – Automatable via shell script for continuous freshness