chukaofili/agent-plugins

Sync docs

Docs drift silently. Nothing fails when a README names a file that moved. Run this after every stacked-PR stage or completed feature, before the PR opens.

This skill's contract includes committing. It may commit without asking, always to the current branch, never main.

When to skip

• Nothing a doc references changed (pure internal logic). Still write "docs checked, no drift" in the PR's Testing section, so the reviewer knows it ran.
• The user explicitly doesn't want a docs commit yet.

The inventory: docs/DOCS.md

The list of docs in scope lives in docs/DOCS.md, not in AGENTS.md, so the always-on context doesn't grow with every sync.

# Docs inventory

| Path | Owns | Generated by |
|---|---|---|
| README.md | Pitch, setup, env vars, layout | |
| AGENTS.md | Agent rules + project gates | |
| packages/api/README.md | Endpoints, scripts, env vars | |
| docs/api/openapi.json | API reference | `pnpm generate:openapi` |

## Frozen (never edited by a sync)
- docs/plans/

## Drift checks
<!-- one grep per mistake that has actually happened, with a comment saying why -->

First run: build it. Sweep for root and per-package README.md / AGENTS.md / CLAUDE.md, contributor docs, API docs (OpenAPI descriptions, llms.txt), skills and rules directories, and env-var references (.env.example, config schemas). Write down what each one owns.

Every run: a doc you find that isn't listed gets added, in the same commit.

Procedure

1. Audit. Diff the branch against its base (git diff <base>...HEAD --stat), and list what changed that a doc could mention: paths, package names, routes, commands and scripts, env vars, exported APIs, behaviour, conventions.
2. Verify. For each doc in the inventory, check every concrete claim against the code: each named file exists at that path, each command exists in the manifest, each env var is actually read, each route and export exists as described. Read the code; don't trust the prose, including prose you wrote earlier.
3. Edit. Fix the drift. Describe what the code does, and never invent behaviour to make a doc read better. If code and doc disagree and you can't tell which is wrong, flag it instead of guessing.
4. Regenerate. Run each generator command listed in the inventory. Never hand-edit a generated doc.
5. Run the drift checks listed in docs/DOCS.md. When a sync finds a mistake that's likely to recur (an old path, a renamed command), add a grep for it with a comment saying why.
6. Commit. Stage the files by path, never git add -A. Make one atomic commit, docs(<scope>): sync <what> with <change>, on the current branch.
7. Push if the branch already tracks a remote (git pull --rebase first). Never push to main.

Rules

• Frozen history: designs, plans and handoffs in docs/plans/ are snapshots of what was decided at the time. They will turn up in greps; that's expected, not drift. Never edit them in a sync.
• Spikes and prototypes are deleted once their direction ships or is dropped, not kept as reference. A spike's conclusions are the least reliable text in the repo once production knows better. Anything still worth knowing moves into the shipped code's docs.
• Size budget: doc lines count toward the PR budget. If the sync pushes a stage past 500 lines, land it as a docs-only stage on top of the stack (see stacked-prs).
• Pointer files stay tiny. A CLAUDE.md or GEMINI.md that just points at AGENTS.md should stay that way. Don't copy content into it.