rippled/.github/scripts/doc-agent

doc-agent

Automated documentation agent for the xrpld C++ codebase. Built on the Claude Agent SDK.

What it does

Three modes:

• document — Add Doxygen /** */ documentation to a C++ file or directory. For each target file, the agent reads the sibling <file>.ai.md (high-signal prose generated by the athenah-ai pipeline), the module skill, and the file itself, then writes Doxygen comments per the standards in docs/DOCUMENTATION_STANDARDS.md.
• review — Given a git diff range, detect documentation drift. Used by the doc-review GitHub Action and locally for testing.
• regen-skills — Rebuild a module's skill file at docs/skills/soul/<module>.md from the .ai.md files in that module and the existing skill content.

Requirements

• Node.js >= 20.12 (for native --env-file support)
• ANTHROPIC_API_KEY (in .env or exported in shell)
• Tools the agent uses: git, gh (for --pr)

Install

cd .github/scripts/doc-agent
npm install
cp .env.example .env
# edit .env and set ANTHROPIC_API_KEY

The npm scripts auto-load .env via Node's --env-file-if-exists flag. You can also export the variables in your shell — both work.

Build and lint

npm run typecheck     # type check without emitting
npm run build         # compile to dist/
npm run lint          # biome lint
npm run format        # biome format --write
npm run check         # lint + format check (read-only)
npm run check:fix     # lint + format + fix

Usage

# Document a single file (reads sibling .ai.md if present)
npm run document include/xrpl/basics/base_uint.h

# Document an entire module
npm run document include/xrpl/basics/

# Review a git range
npm run review develop..HEAD

# Review a PR
npm run review -- --pr 1234

# Regenerate a skill file from this module's .ai.md inputs
npm run regen-skills protocol
npm run regen-skills ledger

When invoked outside the xrpld repo, set XRPLD_ROOT in .env to the path of the checkout you want to operate on.

ai.md context files

The doc-agent reads a sibling <file>.ai.md next to each source file when documenting it. These are produced by the upstream athenah-ai pipeline and treated as the authoritative source of intent. They are gitignored (*.ai.md in .gitignore) and should be removed once the initial documentation pass is complete.

Outputs

The review mode writes two files in the current directory:

• doc-review-report.md — markdown summary, posted as the PR comment
• doc-review-comments.json — array of inline review comments, posted individually on the PR diff

Layout

doc-agent/
├── package.json
├── tsconfig.json
├── biome.json
├── prompts/
│   ├── document-file.md     # System prompt for documentation mode
│   ├── review-diff.md       # System prompt for review mode
│   └── regen-skill.md       # System prompt for regen-skills mode
└── src/
    ├── index.ts             # CLI entry point
    ├── config.ts            # Paths, model, module-skill map
    ├── prompt-loader.ts     # Loads prompts + module skill context
    ├── document.ts          # Document mode
    ├── review.ts            # Review mode
    ├── regen-skills.ts      # Regen-skills mode
    └── types.ts             # Shared types

Module skills

The agent injects per-module context from docs/skills/soul/*.md into its system prompt based on the file path being processed. The mapping lives in src/config.ts (MODULE_SKILL_MAP).

Notes

• Prompts live in markdown files, not source, so they can be edited without touching code.
• The document mode uses permissionMode: 'acceptEdits' so the agent writes directly to the target files. Run against a clean git tree so you can review and revert if needed.