docflow

add-convention

Assess and add a CONVENTION (a reusable rule, practice, or naming/process standard) to a documentation-led repo — decides FIRST whether it is worth codifying at all, then routes it to the right home (AGENTS.md hard rule, CONVENTIONS.md guidance, GLOSSARY term, or to /new-adr if it is really a one-off decision). Pushes back on premature or duplicate conventions. Use when the user says "add a convention", "make this a rule", "document this practice", "we should always X", or invokes /add-convention. NOT for recording a single architectural/product decision (use /new-adr) and NOT for queueing work (use /new-plan).

AI & Automation Listed

agent-wave

Orchestrate a wave of parallel agents over the plan/todo queue in a documentation-led repo — asks how many agents, the budget (items/waves, with hours as a soft cap), and whether to checkpoint after each wave or run continuously. Spawns isolated worktree subagents, assigns one queue item each, collects results. Use when the user says "spawn a wave of agents", "run the queue in parallel", "fan out the work", "agent wave", or invokes /agent-wave.

audit

Audit a documentation-led repo against its own conventions — contiguous ADR numbering, INDEX sync, plan/ coverage, required sections, status validity, cross-reference resolution, language mandate, ADR-privacy leaks into user-visible code, cross-worktree collisions (duplicate numbers, duplicate plan ownership, same ADR edited on two branches), and — for a multi-repo product — cross-repo federation checks (bidirectional membership, identity collisions, dangling cross-repo references, roll-up drift, convention drift). Reports a punch list and offers to fix the mechanical issues. Use when the user says "audit the ADRs", "lint the conventions", "check repo consistency", "are the ADRs in sync", or invokes /audit.

Code & Development Listed

bootstrap

Scaffold or retrofit documentation-led conventions (AGENTS.md, CLAUDE.md, CONVENTIONS.md, ADR catalogue, plan/ queue, _agent/ coordination) into a repo. Use when the user asks to "set up conventions", "bootstrap ADRs", "scaffold the documentation-led layout", "add AGENTS.md and a plan queue", or invokes /bootstrap. Works on fresh repos and existing ones — preserves existing content and merges rather than overwrites. Opens with an express / guided / full depth choice, so a quick conservative setup needs almost no questions.

AI & Automation Listed

brainstorm

Decompose a problem, feature, or goal into candidate ADRs and plan items for a documentation-led repo — one decision per ADR, dependency edges, suggested ordering. Proposes drafts for review and writes nothing until approved. Use when the user says "brainstorm ADRs", "break this down into decisions", "what ADRs do we need for X", "plan out the work", or invokes /brainstorm.

Testing & QA Listed

challenge

Interrogate — pressure-test a DRAFT record, or elicit the boundaries a human has not stated — in a documentation-led repo. Advisory only; writes nothing and gates nothing; hands every finding to the owning writer skill. Use when the user says "poke holes in this", "pressure-test this draft", "grill me", "challenge this", "what are we missing here", "is this solid", or invokes /challenge. NOT for generating candidates from a fuzzy idea (use /brainstorm — it generates, this interrogates), NOT for checking the written record against the conventions (use /audit — it checks what IS, this probes what is proposed or unstated), and NOT for writing any artefact (route findings to /new-adr, /new-spec, /new-plan, /add-convention).

Web & Frontend Listed

new-adr

Author a new ADR — record a DECISION (what the system must do, or how it is built) in a documentation-led repo. Picks the next contiguous number, chooses the shape (capability vs technology), fills the template, sets status Proposed, regenerates INDEX, updates domain READMEs, handles supersede/deprecate linkage, commits. Use when the user says "add an ADR", "new ADR", "record a decision", "create an architecture decision record", or invokes /new-adr. NOT for queueing a unit of work against an existing decision (use /new-plan) and NOT for recording a reusable rule, practice, or naming/process standard (use /add-convention).

new-plan

Queue a UNIT OF WORK in the plan/todo queue of a documentation-led repo, tracing to an existing ADR — names the owning ADR(s), scope, exit criteria mapped to acceptance criteria, dependencies, and queue position. Use when the user says "add a plan item", "queue this work", "create a todo for ADR X", "new plan", "put this on the backlog", or invokes /new-plan. NOT for recording the decision itself (use /new-adr) and NOT for shipping/completing an item already queued (use /ship-item).

Testing & QA Listed

new-spec

Author a new CAPABILITY SPEC — a living, slug-identified record of what the system must do — in a documentation-led repo whose record model separates decisions from specs. Picks a unique slug, fills the spec template, sets status Draft, walks Draft→Agreed as a human gate, regenerates INDEX, commits. Use when the user says "add a spec", "new spec", "record a capability", "write the spec for X", or invokes /new-spec. NOT for recording a decision or its rationale (use /new-adr), NOT for queueing a unit of work (use /new-plan), and NOT for a reusable rule or term (use /add-convention). Refuses cleanly in repos whose record model has no specs.

rollup

Generate the federation roll-up catalogue for a multi-repo product — aggregate every member repo's ADR metadata into one derived, product-wide view, run from the home repo. Use when the user says "roll up the federation", "generate the product-wide ADR view", "aggregate ADRs across the repos", "refresh the roll-up", or invokes /rollup. NOT for regenerating a single repo's own INDEX (that happens in place during authoring/ship) and NOT for linting consistency (use the audit skill).

ship-item

Ship a plan/todo item in a documentation-led repo — run the verify gate, integrate per the repo's model (fast-forward or PR), git mv todo→done with a shipped footer, advance the owning ADR(s) to Implemented, regenerate INDEX, append WORKLOG, update the live snapshot. Use when the user says "ship this", "complete the plan item", "mark done", "close out the queue item", or invokes /ship-item.