automagik-dev/docs

/docs — Documentation Generation

Audit existing documentation, identify gaps, generate what's missing, and validate every claim against actual code. Can be invoked standalone or as part of /work.

When to Use

• Codebase has undocumented modules, APIs, or workflows
• Existing documentation is stale or references removed features
• A wish deliverable includes documentation
• After significant code changes that invalidate existing docs
• After /work completes — suggest /docs to document what changed

Documentation Surfaces

Audit and maintain these doc types:

| Type | Location | Purpose | |------|----------|---------| | README | README.md, */README.md | Project/module overview, setup, usage | | CLAUDE.md | CLAUDE.md, */CLAUDE.md | Project conventions, commands, gotchas for AI agents | | API docs | docs/api/, inline JSDoc/TSDoc | Endpoint contracts, request/response schemas | | Architecture | docs/architecture.md, ARCHITECTURE.md | System design, data flow, component relationships | | Inline docs | JSDoc, TSDoc, docstrings | Function/class/module-level documentation |

CLAUDE.md is a first-class documentation surface. When the codebase changes significantly (new commands, changed conventions, removed features), flag CLAUDE.md for update. CLAUDE.md should always reflect the current state of the project.

Flow

1. Audit existing docs: scan all documentation surfaces above — map what exists.
2. Identify gaps: compare documentation against actual code — find what's missing, outdated, or wrong. Pay special attention to CLAUDE.md accuracy.
3. Generate: write documentation to fill the gaps, matching project conventions.
4. Validate against code: verify every claim — file paths exist, APIs match, behaviors are accurate.
5. Report: return list of created/updated files with validation results.

Dispatch

# Spawn a docs subagent
genie agent spawn docs

Example

After shipping a new genie work dispatch fix, the orchestrator runs /docs to update documentation:

# 1. Spawn a docs subagent
genie agent spawn docs

# 2. Send the task
genie agent send 'Audit and update docs after PR #746 (initialPrompt added to dispatch). Check: README.md, CLAUDE.md, CO-ORCHESTRATION-GUIDE.md, skills/work/SKILL.md — verify dispatch examples match current code. Fix any stale references.' --to docs

The docs agent:

1. Scans all doc surfaces for references to genie work, dispatch, protocolRouter.sendMessage
2. Finds CO-ORCHESTRATION-GUIDE.md still references the old dispatch flow
3. Updates the guide with the new initialPrompt pattern
4. Validates every file path and API reference exists in the codebase
5. Reports: "Updated 1 file (CO-ORCHESTRATION-GUIDE.md). 3 files verified current. 0 dead references."

Rules

• Validate every claim against actual code — no fiction.
• No dead references — every path, function, and API mentioned must exist in the codebase.
• Match existing project conventions for documentation style and structure.
• Never document features that don't exist yet.
• Include validation evidence in the report — not just "docs written" but "docs written and verified."

Turn close (required)

Every session MUST end by writing a terminal outcome to the turn-session contract. This is how the orchestrator reconciles executor state — skipping it leaves the row open and blocks auto-resume.

• genie done — work completed, acceptance criteria met
• genie blocked --reason "<why>" — stuck, needs human input or an unblocking signal
• genie failed --reason "<why>" — aborted, irrecoverable error, or cannot proceed

Rules:

• Call exactly one close verb as the last action of the session.
• blocked / failed require --reason.
• genie done inside an agent session (GENIE_AGENT_NAME set) closes the current executor; it does not require a wish ref.