codument: Instructions file for Codex

Codument Agent Guide

This is the canonical cross-agent guide for working on Codument. CLAUDE.md may exist for Claude-specific tooling, but this file is the shared contract.

Product Direction

Codument is a docs-backed delivery workflow for AI coding agents. The core loop is:

grill -> plan -> approve -> implement -> verify -> document -> review -> commit -> repeat

Do not treat docs as an afterthought. The docs are the control plane that lets an agent resume work without relying on chat history.

Build & Test

npm run typecheck
npm run build
npm test

Project Structure

• src/commands/ — CLI commands (init, scan, update)
• src/lib/ — Core libraries for profiles, registry, scaffolding, detection, codemods, markers, and versioning
• src/hooks/ — Claude profile hook script
• skills/ — Workflow skills shipped with the package
• agents/ — Claude profile subagent definitions
• rules/ — Claude profile path-scoped rule templates
• templates/ — Documentation templates copied on init
• tests/ — Node test runner tests

Working Rules

• Use the approved feature plan before source edits.
• Keep implementation slices small enough to review and commit independently.
• Ground the affected paths once with codument context --paths <paths...> and refresh when routing changes. Use --owner for lean answers; the staged boundary checks every affected owner. Read docs/.registry.json when editing or inspecting the map itself.
• Update mapped docs as part of the same change.
• Keep docs compact and durable; do not preserve working chatter.
• Use conventional commit prefixes.

Codument Delivery Workflow

Core loop

Use Codument as the durable control plane for agent-led engineering work:

1. Grill the request against existing docs, code, ADRs, and project language.
2. Plan the feature in docs before changing source code.
3. Wait for explicit user approval before implementation.
4. Implement one planned step at a time.
5. Build the strongest practical feedback loop, preferring red-green-refactor when it fits.
6. Update the mapped docs + docs/.registry.json as part of the same step: register new sources together with codument map materialize <files...>; when a contract changed, update its doc at intent altitude (a move that changed no contract owes nothing at all — the gate reports it and never blocks, so there is no signature to write). Never a junk mirror edit to clear the gate.
7. Review the diff against the approved plan, tests, docs, and architecture.
8. Commit focused work with a conventional commit, authored as the user with no AI Co-Authored-By trailer.
9. Move to the next unchecked step.