# 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

```sh
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

```sh
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

```sh
# 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.