| name | oad/docs |
| description | OpenAgentd workflow for keeping the compact feature catalogue and README aligned with user-visible changes. |
Sync the small set of product documentation affected by the current code changes. Called automatically by oad/commit — can also be used directly when the feature catalogue drifts.
What to update
Inspect git diff --cached or git diff HEAD, then choose the smallest durable record:
- Shipped user-visible capability → add a concise, version-cited entry to
documents/docs/features.md; it is the canonical catalogue.
- Product story or first-run/setup change → update
README.md when users need to discover or act on it.
- Significant, expensive-to-reverse architecture or security decision → create an ADR with the
adr-writing skill.
- Future work, bugs, or roadmap changes → use GitHub issues; do not add a roadmap or technical-debt document.
- Implementation, API, configuration, CLI, operational, or UI-detail change → keep the source, tests, CLI help, and UI authoritative. Add an inline comment only when it explains a non-obvious invariant or decision.
- Nothing user-visible changed → make no documentation change; note this briefly in the commit body.
Rules
- Do not create deep implementation guides, API references, configuration manuals, styling specifications, troubleshooting pages, or duplicate operational docs under
documents/.
- Do not turn ordinary control flow into comments. A code comment must explain why a non-obvious constraint exists, not restate what the code does.
- Keep feature entries factual, concise, and version-cited; mark removed features (deprecated) for at least one release before deleting them.
- Run
make verify-docs after Markdown, README, feature-catalogue, or ADR changes.
- Complete the documentation pass before handing control back to
oad/commit.
