update-docs

name

update-docs

description

Audit and update every documentation surface in the APEX repo against the current state of skills, steering workflows, README marker tables, and the Docusaurus site under misc/website/. After any change to a skill (rename, retire, add, edit description), walk the repo, re-run script-managed surfaces if their --check fails, and reason through every tracked prose *.md to catch references that need updating. Use after adding/removing/renaming a skill, after editing SKILL.md frontmatter, after editing README marker blocks, or before publishing a docs change. Also use when the user says "update docs", "sync docs", "check docs", "run update-docs", or mentions that documentation might be stale.

Update Docs

Walk the APEX repo after any content change and bring every documentation surface back into sync. Two categories of surface exist: script-managed (deterministic, re-runnable) and prose (requires reasoning). Handle both in a single pass.

When to use

• A skill was added, removed, renamed, or had its frontmatter edited
• A steering workflow was added, removed, or renamed
• README marker blocks were edited manually
• Before opening a PR that touches skills/ or steering/
• The user asks to "check docs", "update docs", or "sync documentation"

Modes

Coding-agent mode (default in Claude Code): walk the repo, re-run scripts, propose diffs, ask before writing user-facing prose. Auto-apply mechanical fixes (script outputs, simple name substitutions in fenced code blocks).

Chat-only mode (no file-write tools available): emit the PASS/STALE table + a fix checklist of one-line commands. No file edits.

Step 1: Detect the change set

Determine what changed. Default comparison base is origin/main:

git diff --name-status origin/main...HEAD -- 'skills/**/SKILL.md' 'steering/workflows/*.md' 'steering/commands/**/*.md' 'devops-agent/**'

If the user specifies a different scope ("since my last commit", "just the rename I did"), adjust the base accordingly. Also include any paths the user explicitly names.

Step 2: Tier 1 — Script-managed surfaces

Two scripts own deterministic regeneration. Detect staleness and re-run them. Never duplicate their logic.

Surface	Stale when	Fix
Marker blocks (README.md, skills/README.md, steering/**/*.md)	./misc/update-all-references.sh --check exits non-zero	./misc/update-all-references.sh
Docusaurus wrappers, manifest, skills index	./misc/update-pages.sh --check exits non-zero	./misc/update-pages.sh

Run both --check commands. If either exits non-zero, re-run the corresponding script. In coding-agent mode, apply the changes directly. In chat-only mode, emit the fix command.

Step 3: Tier 2 — Prose ripple

Read each file in the candidate set below. Hold the change set in mind and look for stale references.

What "stale" looks like

• A skill name in prose that no longer matches a skills/<name>/ directory
• A frontmatter description that was edited, where the old phrasing still appears verbatim elsewhere
• A retired steering workflow still referenced in a list
• A skill count or coverage claim ("APEX ships six skills") that no longer matches reality
• A path link skills/old-name/ after a rename
• A removed or renamed concept still mentioned in contributor guidance

Candidate set (tracked files only — use git ls-files)

In scope:

• README.md
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• THIRD_PARTY_NOTICES.md
• skills/README.md
• Every skills/<name>/README.md where present
• Every skills/<name>/SKILL.md
• Every tracked *.md under steering/
• devops-agent/README.md
• Every devops-agent/<name>/SKILL.md
• misc/README.md
• misc/evals/README.md
• misc/evals/_template/README.md
• Every misc/evals/<skill>/README.md
• misc/website/docs/intro.md
• misc/website/docs/getting-started.md
• misc/website/src/pages/index.tsx (not markdown but contains skill-name copy)

Excluded (generated by scripts — never hand-edit):

• misc/website/docs/skills/*.md
• misc/website/docs/steering/*.md
• misc/website/docs/skills/index.md
• misc/website/static/manifests/skills.json

For each file, if you find stale content:

• In coding-agent mode: propose the diff. For user-facing prose changes, ask before applying. For mechanical substitutions (path renames in code fences, skill-name swaps in lists), apply directly.
• In chat-only mode: add to the checklist with file, line, and what to change.

Step 4: Final output

Always end with a summary table:

| Surface | Status | Action taken | Confirm? |
|---|---|---|---|
| Marker blocks | PASS | — | — |
| Docusaurus wrappers | STALE | Re-ran ./misc/update-pages.sh | — |
| README.md | STALE | Proposed diff | yes (line 42 prose) |
| CONTRIBUTING.md | PASS | — | — |
| skills/README.md | PASS | — | — |
| misc/evals/*/README.md | PASS | — | — |
| ... | | | |

Status values: PASS (no changes needed), STALE (changes applied or proposed), SKIP (file doesn't exist yet).

Rows marked Confirm? yes require the user's approval before the change is final. Wait for their response before moving on.