adev-document

name	adev:document
description	Generate human-readable developer documentation in docs/ from repomap output. Reads dependency-graph.json and symbol-ranks.json from /adev:repomap, plus charters and manifest. Use when the user says 'generate docs', 'document the codebase', 'create architecture docs', or wants to produce docs/architecture.md and per-module documentation. In Codex, invoke with $adev:document

Generate Developer Documentation

Produce human-readable documentation in docs/ from .context-index/ artifacts.

Arguments

• No arguments: generate all documentation
• --module <slug>: regenerate only docs/modules/<slug>.md
  • Validate slug matches pattern ^[a-z0-9_-]+$ — exit 1 if invalid
  • Prevent path traversal: reject slugs containing ".." or use path.resolve to normalize and verify it stays within docs/modules/
  • Check slug exists in manifest — exit 1 with error " not found in manifest" if missing
• --check: compute what would change, output diff without writing
• --force: regenerate all sections unconditionally

Precondition Checks

1. Check .context-index/hygiene/dependency-graph.json exists
   • If missing: exit 1 with error "Run /adev:repomap first to generate dependency-graph.json"
2. Check .context-index/hygiene/symbol-ranks.json exists (symbol index)

• If missing: exit 1 with error "Run /adev:repomap first to generate symbol-ranks.json"

3. Check .context-index/manifest.yaml exists
   • If missing: exit 1 with error "Run /adev:init first to generate manifest.yaml"
4. If docs/ does not exist, create it

Marker Protocol

Every file uses two-zone layout:

[generated content — owned by /adev:document]

<!-- adev:generated -->

<!-- adev:human -->

[human content — owned by developer, never overwritten]

Rules:

Condition	Action
Both markers present	Preserve content after <!-- adev:human -->, regenerate before
Only <!-- adev:human -->	File is human-owned, do NOT overwrite
Only <!-- adev:generated -->	Regenerate entire file
Neither marker	Write fresh with both markers

Step 1: Generate docs/architecture.md

1.1 Load Inputs

File	Required	Purpose
dependency-graph.json	Yes	Module dependency edges
symbol-ranks.json	Yes	Exported symbols ranked by reference
manifest.yaml	Yes	Module list, project metadata
constitution.md	Optional	Project principles
platform-context.yaml	Optional	Runtime environment

Load Skill Extensions: Load any skill extension instructions before proceeding:

adev skill-ext load --skill document

If the output is not __NONE__, incorporate it as additional standing instructions that apply to this skill's entire execution. Frame it as: "The following skill extension instructions apply to this invocation (source: installed domain extensions and/or project-level overrides)." If the output is __NONE__, continue normally.

1.2 Build Module Map

Markdown table with:

Column	Source
Module	Module name from manifest.yaml
Purpose	"Business Intent" from charter
Key Exports	Top 3 symbols from symbol-ranks
Inbound	Count from dependency-graph
Outbound	Count from dependency-graph

1.3 Build Dependency Flow

Prose paragraph summarizing dependency topology:

• Core modules: high inbound, low outbound
• Leaf consumers: low inbound, high outbound
• Middleware modules: moderate both

1.4 Identify Entry Points

From dependency-graph.json, identify files with zero inbound edges (no other files depend on them). These are entry points — leaf nodes in the dependency graph.

1.5 Build ADR Links

Find .context-index/adrs/*.md (excluding .template.md), extract status, produce markdown links.

1.6 Assemble docs/architecture.md

# Architecture

> Generated by adev:document on <timestamp>.

## Module Map
<table>

## Dependency Flow
<paragraph>

## Entry Points
<list>

## Architecture Decision Records
<links>

<!-- adev:generated -->

<!-- adev:human -->

Step 2: Generate docs/modules/.md

For Each Module:

1. Purpose — From charter's Business Intent or manifest
2. Key Exports — Top 10 symbols from symbol-ranks.json (file begins with module paths)
3. Dependencies — Inbound/outbound from dependency-graph
4. Related Specs — Glob .context-index/specs/features/<slug>/

# Module: <name>

> Generated by adev:document on YYYY-MM-DD.

## Purpose
<charter Business Intent or inferred>

## Key Exports
| Symbol | Kind | Location | Score |
|--------|------|----------|-------|

## Dependencies
**Inbound:** Module A, Module B
**Outbound:** Module C

## Related Specs
- [charter.md](.context-index/specs/features/<slug>/charter.md)

<!-- adev:generated -->

<!-- adev:human -->

Step 3: Generate docs/GENERATED.md

Manifest of all generated doc files:

1. Read existing docs/GENERATED.md if it exists
   • If malformed (cannot be parsed): log warning, treat as empty
2. Get commit SHA: run git rev-parse --short HEAD for 7-character short SHA
3. Assemble table:

# Generated Documentation Manifest

> Managed by adev:document.

| File | Generated Sections | Last Commit | Last Run |
|------|--------------------|-------------|-----------|
| docs/architecture.md | Module Map \| Dependency Flow | abc1234 | 2026-03-23 |

After Generation

Documentation generated:

  docs/architecture.md       — module map, dependency flow, entry points, ADRs
  docs/modules/<slug>.md     — per-module purpose, exports, dependencies, specs
  docs/GENERATED.md          — manifest of all generated doc files

Run /adev:document --check to preview changes.