Add docs maintenance agent: AGENTS.md, skills, and rule files

[brandonjackson]

Short Description

Adds an AGENTS.md orchestrator and seven skill files under .agents/skills/ so an LLM agent can maintain the docs one section at a time. Seeds glossary.yml and adds empty style-exceptions.yml and translation-rules.yml with schema comments.

The skills

Each skill is a plain-language instruction file, 50 to 90 lines, that stands alone.

Skill	What it does	Why it's worth having
Lint	Mechanical checks: terminology against the glossary, heading levels, broken links, orphan pages, missing front matter, untagged code blocks, missing alt text.	Catches the cheap, common mistakes automatically so human review time goes on content, not formatting.
Accuracy check	Lists every claim on a page (flags, defaults, labels, versions, limits) and verifies each one against the code in Lightning, kit, or adaptors.	Docs drift silently as the product changes. This is the only skill that finds out-of-date facts before a user does.
Fresh-user evaluation	Reads a page with no prior OpenFn knowledge and tries to complete the task. Records every point of confusion and scores readability and completeness.	Authors can't see what they've assumed. This surfaces the missing prerequisite or undefined term that makes a newcomer give up.
Gap analysis	Compares what a section covers against what exists in the product and what users ask about. Ranks gaps by users affected, severity, and evidence, with ease as a tiebreaker.	Turns "we should write more docs" into a prioritised list with a home and an outline for each item. Tested end to end on the CLI section; found six real gaps traced to source.
Screenshot triage	Scans all screenshots by default, dates each one, maps it to the UI code that draws that screen, and flags images older than the last UI change. Remembers classifications in screenshot-map.yml so repeat scans are cheap.	Stale screenshots are the most visible sign of neglected docs. This tells you which ones to retake first, without anyone opening 350 images.
Translate	Generates Spanish and French versions of English pages, with governance: content-hash source tracking, review status, never overwriting human-reviewed pages, honouring do-not-retranslate fences.	Makes translation affordable while keeping humans in control of what they've reviewed. Translations stay current with the English automatically.
Release review	Reads the changelogs for every release in the last month across Lightning, kit, and adaptors, works out what changed for users, and finds the docs pages that now need updating. Can be narrowed to one repo, tag, or PR.	Closes the loop between shipping and documenting on a schedule, without anyone having to remember to ask per PR. Changelog-first keeps it cheap.

How they fit together

• One section per run; the agent asks which section if none is named.
• Order: lint → accuracy → fresh-user eval → gap analysis → translate. Screenshot triage and release review run on their own schedule (monthly is the intended cadence) rather than per section.
• Every finding is a fix (applied), a suggestion (recorded in the PR for a human), or a question (asked, not guessed).
• Stop and open a PR when the section is done or at 20 file changes. Translations get their own PR per locale and are exempt from the cap.

Boundaries the agent respects

• Never edits pages marked translation_review_status: human-reviewed; offers a diff instead.
• Never edits generated adaptor pages (adaptors/packages/**, adaptors/library/**); drafts issues for OpenFn/adaptors instead. Hand-written adaptors/*.md overviews stay editable.
• Never edits versioned_docs/ (frozen v1).
• Never changes build or deploy config without asking.
• Never retakes screenshots.
• Feature-flagged or deliberately hidden functionality is never a docs gap.

Translation source tracking

translation_source_hash is the content hash of the English file (git hash-object), not a commit SHA. The original spec said commit SHA, but the first trial run showed the problem: this repo squash-merges, so a hash pointing at a branch commit dangles the moment the PR lands. A content hash is the same wherever the file lives, and a reviewer can still recover the English they approved with git cat-file -p <hash> to see what changed since.

Rule files

glossary.yml (seeded with product terms that must never be translated), style-exceptions.yml, and translation-rules.yml are read by lint and translate and maintained by humans directly. Each explains its format in a header comment.

Things to look at carefully

• .gitignore no longer ignores /i18n. The old rule contradicted committing translations in-repo. No i18n/ directory exists yet, so nothing changes until the translate skill runs.
• docusaurus.config.js has no i18n block. I did not add one, since enabling locales changes what yarn build produces and deploys. The translate skill treats a missing locale as a blocking question.
• The glossary seed goes slightly beyond the spec's list (adds dataclip, Canvas, Inspector, CLI, project, state, operation, collection, sandbox), based on terms already used across docs/. Easy to trim.
• Release review and screenshot triage are designed for a monthly trigger. The trigger itself is not part of this PR.

No existing docs pages were modified.

AI Usage

• I have used Claude Code
• I have used another model
• I have not used AI

You can read more details in our
Responsible AI Policy

🤖 Generated with Claude Code

https://claude.ai/code/session_01CntaKNYyBkumpWvm5mTJa7