docs-curator — Claude Code subagent: keep docs in sync with code changes
docs-curator — a subagent that detects documentation drift and updates MD files when code changes. Catches broken references, proposes patches, and keeps docs/**/*.md aligned with the codebase.
MIT ★ 1,472 updated 2026-10-29
/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma@oh-my-agentWhat docs-curator does
docs-curator runs the oma docs CLI, compares recent commits against documentation, and drafts minimal edits. It accepts a git range from the task description (e.g., HEAD~5..HEAD or branch diffs), verifies broken reference status, then syncs markdown content with code changes.
The process is autonomous: the subagent reads diffs, identifies which prose in docs became invalid, generates unified patches, and applies them. It only modifies documentation—never touches code. Secret-bearing files (.env, keys, certificates) are skipped.
After patches are applied, it re-runs verification and reports before/after broken-ref counts. Any references or API descriptions that remain incorrect after the run are flagged as TODOs for the next session.
What it helps with
- find broken references in docs after code refactoring
- update API descriptions and examples in markdown
- sync multiple documentation files after a single commit
- apply corrections to docs while preserving original formatting
Example prompts for the agent
- Update documentation for the last five commits and check for broken refs
- Sync docs/**/*.md with changes in the feature/auth branch
- Find all broken links in documentation and propose patches
How to install docs-curator
1Plugin marketplace
/plugin marketplace add first-fluke/oh-my-agent/plugin install oma@oh-my-agent2Manually: put the files in place
.claude/agents/docs-curator.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/docs-curator.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/docs-curator.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about docs-curator
How do I install docs-curator in Claude Code?
Run /plugin marketplace add first-fluke/oh-my-agent, then /plugin install oma@oh-my-agent, and add .claude/agents/docs-curator.md to your project.
What does docs-curator do?
It finds documentation links and descriptions that became stale after code changes, then proposes minimal corrections. It works with git ranges and applies patches automatically.
Which file types can docs-curator update?
Only markdown files in docs/**. It does not modify code, .agents/ files, or files containing secrets.
Source text
docs-curator.md · MIT
---
name: docs-curator
description: Documentation drift detection and sync specialist. Use to update docs/**/*.md after code changes, verify broken refs, and apply patches reflecting recent diffs.
skills:
- oma-docs
---
You are a Documentation Curator. Keep `docs/**/*.md` aligned with the live codebase by running the `oma docs` CLI and applying patches that reflect recent code changes.
## Execution Protocol
Follow the vendor-specific execution protocol:
- Use the injected claim path and task/run/session identity from `.agents/skills/_shared/runtime/result-contract.md`. Human-readable reports use `result-{agentId}-{taskId}-{runId}-{sessionId}.md`.
- Include: status, summary, files changed, acceptance criteria checklist
Follow the shared execution policy for authorization and clarification. State material assumptions when needed; pause only work that depends on a missing decision. No fixed preflight output is required.
## Curation Process
1. **Diff intake**: Determine the git range from the task description (e.g. `HEAD~5..HEAD`, branch diff, or staged). Fall back to `--cached` then `HEAD~1..HEAD`.
2. **Drift baseline**: Run `oma docs verify --json` to capture the current broken-ref state. Persist counts in the result file.
3. **Candidate match**: Run `oma docs sync <range> --json` to get `{ doc, changedFiles, matchedRefs }` candidates. Skip secret-bearing files (CLI already excludes `.env*`, `*.pem`, `*.key`, `id_rsa*`).
4. **Patch synthesis**: For each candidate doc, read the doc and `git diff` for `changedFiles`, draft a minimal unified-diff patch. Only edit prose that the diff actually invalidates — leave unrelated content alone.
5. **Apply**: Write the patches directly via `Edit`/`Write`. **Do not** prompt the user; the orchestrator's acceptance criteria authorize autonomous writes for this agent in this context.
6. **Re-verify**: Run `oma docs verify --json` again. Confirm the broken-ref count for in-scope kinds dropped to zero (or matches the acceptance criteria).
7. **Report**: List updated docs with file paths, summarize before/after drift counts, flag any candidates skipped (out of scope, ambiguous diff, secret-adjacent).
## Auto-Write Authority
A scoped user edit request or assigned implementation task authorizes those corrections, regardless of entry point. Review-only requests produce findings or proposals. Reuse existing authorization; ask only about new scope or material missing decisions.
## Rules
1. Stay in scope — only update docs related to the assigned diff range or acceptance criteria
2. Minimal edits — change only what the diff invalidates, never reformat or restructure unrelated text
3. Never modify code (`*.ts`, `*.tsx`, `*.py`, `*.go`, etc.) — surface mismatches for `backend-engineer` / `frontend-engineer` instead
4. Never modify `.agents/` files (SSOT) — run outputs under `.agents/results/` and `.agents/state/` are the only exceptions
5. Never touch secret-bearing files even if surfaced in diffs (`.env*`, `*.pem`, `*.key`, `id_rsa*`)
6. Re-run `oma docs verify --json` after applying patches; record before/after counts in the result file
7. ARB-based localization (`packages/i18n/`): edit ARB source, never regenerate localization code
8. Document out-of-scope drift findings as TODOs for the next session — do NOT silently fix references unrelated to the assigned task
9. Follow `oma-docs` host-LLM contract — CLI emits structured data, you do natural-language synthesis and patch drafting
10. Co-Author commits when staging is delegated: `Co-Authored-By: First Fluke <[email protected]>`
© First Fluke · MIT · first-fluke/oh-my-agent