ai-workflow-rituals

Mechanical checks over the project's narrative documentation tree (`docs/`). Reports broken code references, removed-feature docs, orphan files, and documentation TODOs. Reports only — never rewrites prose. Use before opening a PR that touches code with documentation impact, or as a periodic doc-hygiene pass.

Tags a release after an aiwf epic is closed and merged. Determines the semver bump, updates CHANGELOG.md, creates an annotated git tag, runs health checks. The aiwf epic is already `done` at this point — this skill captures the release act in CHANGELOG and git, not in aiwf state. Never tags or pushes without explicit human approval.

Closes an aiwf epic — verifies all milestones done, scaffolds a wrap artefact, harvests ADR candidates, runs scoped doc-lint, merges the epic branch into mainline with a trailered merge commit, promotes the epic to done. Use when the user says "wrap E-NN" or "close the auth epic" and every milestone in the epic is wrapped. Commit and push require explicit human approval.

Closes an aiwf milestone — verifies all ACs met, runs scoped doc-lint, finalizes the tracking doc, promotes status to done, prepares the wrap commit. Use when the user says "wrap M-NNNN" or "finish the cache milestone" and self-review per `aiwfx-start-milestone` has passed. Commit and push require explicit human approval.

Scopes, refines, and documents a new aiwf epic. Allocates the next E-NN id via `aiwf add epic`, scaffolds an epic spec from the plugin's template, fills in goal/context/scope/constraints/success criteria, and stages the spec for the user's review. Use when the user says "plan feature X", "design the system for Y", or "I need to build Z". Calls aiwf — install only with the aiwf-extensions plugin.

Decomposes an approved aiwf epic into a sequenced set of independently-shippable milestones. Allocates each M-NNNN via `aiwf add milestone --epic E-NNNN`, scaffolds each milestone spec from the plugin's template, sequences them by dependency. Use after `aiwfx-plan-epic` when the user says "break this into milestones" or "plan the work for E-NNNN".

Records a decision that surfaces during planning, implementation, or review — as an ADR (architectural, long-lived) or as an aiwf D-NNN entity (project-scoped). Allocates the id via `aiwf add`, fills the body from the appropriate plugin template, commits. Invoke in-flow whenever a decision worth keeping for future readers becomes clear; the calling skill (start-milestone, wrap-milestone, review-code, plan-epic, etc.) just hands off and continues.

Sets up and begins an aiwf milestone — preflight checks, branch setup, status promotion to in_progress, then iterative TDD via wf-tdd-cycle. Use when the user says "start milestone M-NNNN" or "implement M-NNNN" and a draft milestone spec exists. Commits and pushes require explicit human approval.

Open-work synthesis ritual — answers direction questions like "what should I work on next?", "give me the landscape", "where should we focus?", "what's the critical path?", "synthesise the open work", "draw the whiteboard". Loads tree state via `aiwf status` / `aiwf list` / `aiwf show` / `aiwf history`; produces a tiered open-work landscape, a recommended sequence, a first-decision fork, and an optional Q&A gate over pending decisions. Read-only; no commit; no persisted artefact.

One-off branch-and-PR ritual for fixes, chores, or tweaks too small to warrant a milestone — typos, config nudges, single-line bug fixes, dependency bumps. Creates a fix/patch/chore branch, lands one focused change, gates commit and push behind explicit human approval. Use when the user describes a single focused change tied to one issue (or none).

Code review checklist with verdict (approve / request-changes / questions). Reviews a diff for correctness, AC coverage, branch-coverage discipline, conventions, and documentation hygiene. Findings are classified blocking vs. non-blocking with file:line references. Use when the user says "review this", "check my changes", or before a PR is opened.

Red/green/refactor for a single acceptance criterion or feature unit, ending with a hard-rule branch-coverage audit. Write a failing test, write the minimum code to pass, refactor, then walk every reachable conditional branch and confirm an explicit test exercises it. Use during milestone implementation and inside `wf-patch` when the change touches logic.

Activates an aiwf epic — runs the preflight checks (epic body complete, drafted-milestone present, kernel `aiwf check` clean), asks the operator to choose a worktree placement and branch shape, optionally opens an `aiwf authorize` delegation scope, and lands the sovereign `aiwf promote E-NN active` commit. Use when the user says "start E-NN", "activate the auth epic", or "let's begin work on E-03". The promote step requires a `human/` actor unless `--force --reason "..."` is used; commit and any agent delegation require explicit human approval.