← Docs hub

Maintainer guide

This directory is the governance scaffold for llmwiki maintainers. Contributors should read ../../CONTRIBUTING.md first — it has the short version of what this folder covers in detail.

Docs at a glance

Slash commands

Three commands drive maintainer work, and all three live in .claude/commands/. Both Claude Code and Cursor read top-level .claude/commands/*.md, so one file per command serves both surfaces and no per-surface duplicate is needed; Cursor also reads .claude/skills/ and .claude/agents/ natively. Only a nested .claude/commands/<ns>/ namespace is invisible to Cursor and needs a flat wrapper — the full discovery model, the symptoms it explains, and how to re-verify it live in AWOS-CURSOR.md. llmwiki install-agent-kit ships none of them — the vault commands it does ship are in ../reference/slash-commands.md.

• /release <version> — .claude/commands/release.md is thin and loads the shared .claude/skills/release/SKILL.md, then follows RELEASE_PROCESS.md: preflight on main → version bump → CHANGELOG/UPGRADING editorial → local commit+tag → human gate before push → watch release.yml. One top-level file serves both harnesses.
• /fix-bug <issue> — .claude/commands/fix-bug.md: one bug through diagnosis → scoped fix + regression test → verify → independent review → PR, amending the owning spec when behaviour changed.
• /implement-feature <spec-or-issue> — .claude/commands/implement-feature.md: one feature through the AWOS chain (spec → tech → tasks → implement → verify) → independent review → PR.

Both delivery commands are generated by AWOS from the decisions in ../../context/product/delivery-flow.md — to change how they behave, change those decisions (and record the edit under that file's Local Customizations), then re-run /awos:flow instead of hand-editing the command files.

/awos:flow itself is plugin-provided, not a file in this repo's .claude/commands/. On Claude Code it arrives with /plugin install awos@awos-marketplace; Cursor has no plugin runtime, so ./scripts/update-awos.sh --plugin generates .cursor/commands/awos-flow.md via scripts/sync-awos-plugin-cursor.sh and the slash name there is /awos-flow. See AWOS-CURSOR.md.

Code review uses REVIEW_CHECKLIST.md directly (or via the single independent review stage inside /implement-feature / /fix-bug, where the coding agent picks its own most suitable review skill or command).

The nine /awos:* commands are the one exception to the single-file rule: Cursor does not read nested .claude/commands/<ns>/, so each also needs a flat .cursor/commands/awos-*.md wrapper, and the slash name differs per surface — /awos:product on Claude, /awos-product on Cursor. Both trees are generated from .awos/commands/ by scripts/sync-awos-cursor-commands.sh. Of those, product, roadmap, architecture and hire are the human-invoked ones that populate context/product/; spec, tech, tasks, implement and verify are invoked internally by /implement-feature and are not normal entry points. tests/test_command_surface_parity.py guards both halves: every nested namespace keeps its flat wrapper, and no top-level command grows a redundant Cursor duplicate.

When things go wrong

• CI red on main → fix-first, roll forward, never force-push
• Security issue reported → see SECURITY.md in the repo root
• Contributor PR stuck > 7 days → escalate via the triage pass (there's a rule in TRIAGE.md)
• Someone re-proposes a declined idea → link them to the entry in DECLINED.md

Why a dedicated maintainer folder?

Because maintainer docs have a different audience than user docs. User docs go in docs/ (rendered on the site). Maintainer docs stay here — they're less polished, more operational, and they change with the team rather than with releases.

Keep this folder short. When a doc is over one screen, prune.