document-project

name	document-project
description	Generate or update project component documentation (README and API docs) by reading source code. Enforces the documentation verification workflow.

Document Project

Usage

/document-project [<component-path>]

If no path is given, use the current directory.

Overview

Lifecycle position: Utility — use after audit-project flags documentation gaps, or when asked to "document a component", "update the README", or "write API docs".

Generates both user-facing component documentation (README with interfaces, configuration, usage) and developer-facing API documentation (class/function reference) by reading the actual source code.

Cardinal rule: No fact without reading the source. Every parameter name, interface name, type, and default value must come from the code, not assumptions. See .agent/knowledge/documentation_verification.md.

Steps

1. Inventory the component

# Detect project type and list source files
find <component_path> -name '*.py' -o -name '*.cpp' -o -name '*.hpp' \
  -o -name '*.h' -o -name '*.ts' -o -name '*.js' -o -name '*.go' \
  -o -name '*.rs' | sort

# Interface/schema definitions
find <component_path> -name '*.proto' -o -name '*.thrift' \
  -o -name '*.graphql' -o -name '*.json' -name 'schema*' | sort

# Configuration files
find <component_path> -name '*.yaml' -o -name '*.toml' -o -name '*.json' \
  -name 'config*' | sort

Record the component name, description, maintainer, license, and dependencies from the project manifest (package.json, pyproject.toml, Cargo.toml, go.mod, etc.).

2. Extract facts from source

Follow the command cookbook in .agent/knowledge/documentation_verification.md to grep for every:

• Configuration parameter: environment variables, config file keys, CLI flags
• Public API endpoint: HTTP routes, gRPC methods, exported functions
• Interface definition: exported types, classes, interfaces, structs
• Event/message schema: event names, payload types

Record each finding with its file path and line number.

3. Analyze entry points and interfaces

Read every entry point file (main file, index file, handler file). Note:

• CLI arguments and flags (with defaults and descriptions)
• Environment variable configuration
• HTTP/gRPC/other interface definitions
• Exported public API surface

4. Analyze API (libraries and modules)

For C++ libraries (headers in include/<component_name>/):

• Public class definitions
• Public methods and their signatures
• Type definitions (struct, enum, typedef)

For Python modules:

• Class definitions and __init__ signatures
• Public methods
• Module-level functions

For TypeScript/JavaScript:

• Exported classes and functions
• Type/interface definitions
• Default export

For Go packages:

• Exported functions and types
• Package-level documentation

For Rust crates:

• pub functions, structs, enums, and traits

5. Generate component README

Use the template at .agent/templates/component_documentation.md (or .agent/templates/package_documentation.md if available):

• Fill in each section from the facts gathered in steps 1–3.
• Omit sections that don't apply (no empty tables).
• If a README already exists, preserve custom sections (e.g., "Theory of Operation", "Background") while standardizing the interface/API/usage sections.

Typical README sections for a component:

• Overview / description
• Installation / setup
• Configuration (parameters, environment variables)
• Usage examples
• Public API (for library components)
• Development / contributing

6. Generate API documentation (if applicable)

If the component contains libraries or modules with public APIs (not just a standalone executable):

1. Create docs/API.md in the component root.
2. Document each public class/function with its signature, parameters, return type, and a usage example.
3. Include type definitions and enums.

Skip this step if the component only contains application executables with no reusable library code.

7. Self-review

Run through the verification checklist:

• Every configuration parameter name matches an actual declaration in source
• Every API endpoint/route matches actual route definitions
• Every type/interface name matches actual type definitions
• Every default value is copied from the source
• Sections with no applicable content have been removed
• CLI arguments match actual argument declarations
• Examples are syntactically valid and accurately reflect the API

References

• .agent/knowledge/documentation_verification.md — Verification workflow and command cookbook
• .agent/templates/component_documentation.md — README template with verification checklist

Guidelines

• Read before writing — complete steps 1–4 before generating any text.
• Omit, don't leave empty — if a component has no CLI flags, remove the CLI flags section entirely.
• Preserve existing work — if a README exists, update rather than replace. Keep custom sections that add value.
• One component at a time — don't batch across components. Each component gets its own focused documentation pass.
• Cite line numbers — when documenting a parameter or interface, note the source file and line so reviewers can verify.