aiwf

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 milestone spec's wrap-side sections, promotes status to done, prepares the wrap commit. Use when the user says "wrap M-NNNN" or "finish the cache milestone" and the readiness check per `aiwfx-start-milestone` has passed. Commit and push require explicit human approval.

The aiwf per-repo code-health ritual — the whole-codebase companion to wf-review-code's per-diff gate. A stack-agnostic field guide of code-health principles: module boundaries, contracts, data discipline, tests that pin behavior, errors/logs/audit, reasoning aids, operational properties. Use when designing a new module, planning a refactor, reviewing a non-trivial diff, writing a spec that introduces new boundaries, or scoring an inherited codebase Strong/Weak/Missing with file:line evidence. These are advisory forces, not rules — consult them, don't enforce them; the project's own conventions win.

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.

Use when terminal-status entities have accumulated in the active tree and the operator wants to sweep them into per-kind `archive/` subdirs, or when `aiwf check` reports `archive-sweep-pending`. Explains dry-run vs `--apply`, the no-reverse rule, the `archive.sweep_threshold` knob, merge edge cases, and the per-kind storage layout.

Use when the user wants to edit (rewrite or replace) the markdown body of an existing entity — goal/scope/context prose, AC body sections inside a milestone, ADR rationale, gap problem statement, etc. Runs `aiwf edit-body` so the change rides through a verb route with proper trailers, instead of a plain `git commit` that triggers a `provenance-untrailered-entity-commit` warning.

One-off branch-and-merge ritual for fixes, chores, or tweaks too small to warrant a milestone — typos, config nudges, single-line bug fixes, dependency bumps. Creates a patch/ branch (patch/G-NNNN-<slug> when it closes a gap), lands one focused change, gates commit, wrap, 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 change is proposed for merge.

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 its 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".

Use when the user wants to fix or change an entity's title — "the title doesn't match anymore", "fix the title", "retitle to reflect new scope", "correct the title", or change an AC's title inside its parent milestone. Runs `aiwf retitle` so the frontmatter mutation rides through a verb route with proper trailers, instead of a hand-edit that triggers a `provenance-untrailered-entity-commit` warning.

Use when `aiwf check` reports a finding you've judged to be intentional and want a sovereign, reasoned exemption recorded in git. Two subverbs — `aiwf acknowledge illegal <sha>` exempts a historical commit from the fsm-history-consistent / provenance audit rules; `aiwf acknowledge mistag <id>` accepts an `area-mistag` warning as legitimate cross-cutting work. Each records a current-day empty commit carrying `aiwf-verb` / `aiwf-actor` / `aiwf-reason` (+ the target trailer) that the matching check rule walks to exempt the named target. Both require a `human/...` actor and a non-empty `--reason` — sovereign acts trace to a named human with written rationale.

Use when the user wants to rename an entity's slug (the human-readable suffix in the file/dir name). Runs `aiwf rename` so the id is preserved and references stay valid.

Use when the user wants to add a new aiwf entity (epic, milestone, ADR, gap, decision, or contract) or an acceptance criterion under an existing milestone, or to declare a milestone's `depends_on` edges. Runs `aiwf add` (or `aiwf milestone depends-on` for post-allocation edits) so the id allocation, frontmatter, and commit happen mechanically.

Use when the user wants to advance an entity (or acceptance criterion) to a new status, or step an AC's TDD phase. Runs `aiwf promote` so the transition is checked against the kind's legal moves and recorded as a single commit.

Use when the user wants to set, change, or clear a gap or decision's priority — "mark this urgent", "bump the priority", "this isn't that important, lower it", "clear the priority tag". Runs `aiwf set-priority` so the frontmatter mutation rides through a verb route with proper trailers, instead of a hand-edit that triggers a `provenance-untrailered-entity-commit` warning.

On-demand whole-codebase discovery pass for dead paths, convergent duplication, and unconsumed data flow — the findings a per-diff review and an exact-clone linter both structurally miss. Runs four lenses (whole-program reachability, the clone-detector's known-duplication catalogue, a convergence-scoring pass over the code-health rubric, and a producer→consumer data-flow trace for dropped values and orphan stages), triages each finding against tracked ownership, and emits a scorecard plus gap candidates. Use when auditing an inherited or fast-changing codebase, before a large refactor, or when a module feels heavy. Discovery only — it proposes, it does not auto-fix.

Red/green/refactor for a single acceptance criterion or feature unit, ending with a hard-rule branch-coverage audit and a required vacuity check (does a covered assertion actually catch the bug). 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.

Use when the user wants to validate the planning tree or asks why `aiwf check` reported a finding. Explains each finding code and the typical fix.

Use whenever the user mentions contracts — onboarding, authoring, verifying, evolving schemas, debugging findings, registering, deprecating, lifecycle, recipes, custom validators, or adopting an existing contract-verification setup. Authoritative for the contract verification surface.

Use when the user asks to render the planning state as a static HTML site, publish governance views, or generate the project status page.

Use to filter the planning tree by kind, status, parent, area, priority, or archive flag — answers prompts like "list every milestone with status X", "find all entities matching Y", "show me proposed ADRs under an epic", "filter milestones by parent epic", "everything in the platform workstream", "every gap that's still open", "every urgent gap", "show high-priority decisions", "every contract", "every AC that's met". Runs `aiwf list` and returns one row per matching entity (or a per-kind count summary when called with no flags). Read-only; no commit.

Use when the user asks "show me X" / "what does this entity look like?" / "describe Y" for any aiwf entity (or acceptance criterion). Runs `aiwf show <id>`, the canonical per-entity inspection verb. Returns frontmatter + ACs + recent history + active findings + referenced_by in one aggregate view.

Use for narrative-shaped state questions — "what's next?", "where are we?", "what are we working on?", "current status?", "what's in flight?", "give me a summary", "what's urgent right now?", "any high-priority gaps?". Runs `aiwf status`, which prints a one-screen snapshot of in-flight epics + their milestones, open decisions (proposed ADRs and D-NNN), open gaps, the last 5 events from git history, and tree-health counts. Curated for human readers, not for programmatic filter queries — for those, use `aiwf list`. Read-only; no commit.

Activates an aiwf epic — runs the preflight checks (epic body complete, drafted-milestone present, kernel `aiwf check` clean), defaults the worktree placement to in-repo (overridable) and cuts the epic branch, 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 the auth epic". The promote step requires a `human/` actor unless `--force --reason "..."` is used; commit and any agent delegation require explicit human approval.

Mechanical checks over the project's narrative documentation tree (`docs/` plus hand-authored root files like `README.md`). Reports broken code references, removed-feature docs, orphan files, documentation TODOs, broken markdown links, stale CLI invocations, and structural drift (table of contents, heading hierarchy). Reports only — never rewrites prose. Use before proposing a change for merge 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. Use when the user says "cut a release", "let's ship", "ship it", "let's release", "release v1.2", "make a new version", "tag a release", or "publish". Dispatch the `deployer` subagent to run it. Never tags or pushes without explicit human approval.

Use whenever a ritual, subagent dispatch, or ad-hoc fix needs a new git worktree in this repo. Runs `aiwf worktree add` so the worktree is created AND has aiwf's rituals (skills, agents, templates, guidance) materialized into it in one atomic step — a bare `git worktree add` leaves those absent with no warning.

Adversarially audit whether a unit's existing tests and assertions can actually fail — break the implementation and confirm a test goes red, and flag tautological or over-narrowed assertions. Use after tests exist and before declaring done, when you don't trust an LLM-authored suite, or when the user invokes wf-vacuity.

Re-evaluate one unit's design (a file, module, function, or decision) by reconstructing it from intent against a list of pinned obligations, then keep or rewrite — biased to keep, with any rewrite gated behind explicit human approval. Use when code works but feels over-complex or shaped by its edit history, before committing a non-trivial design, or when the user invokes wf-rethink.

Scopes, refines, and documents a new aiwf epic. Allocates the next E-NN id via `aiwf add epic`, scaffolds an epic spec from its 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 — requires the aiwf binary.

Emits a short paste-ready "compaction prime" block for `/compact` — a volatile-first handoff carrying the live reasoning thread, the gotchas found this session, and the exact next action, that points into the tree for everything git and aiwf already reconstruct. Fires on request anywhere ("give me a handoff", "prime the compact", "where are we for /compact", "hand off before I compact", "compaction prime"), and is referenced at the milestone and AC boundary by the start- and wrap-milestone rituals. Read-only over the planning tree — no mutation, no commit, no file written.

Use when a human wants to delegate autonomous work on an entity to an AI assistant or other non-human agent — opening, pausing, resuming, or ending an authorization scope.

Records a decision that surfaces during planning, implementation, or review — as an ADR (architectural, long-lived) or as an aiwf D-NNNN entity (project-scoped). Allocates the id via `aiwf add`, fills the body from the appropriate 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.

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 over the planning tree — no mutation, no commit; writes a gitignored `WHITEBOARD.md` cache (regenerated each run, never committed).

Use when choosing which `area` to tag an entity with, or to understand how aiwf's area feature works — the closed member set, the optional `paths:` oracle, the `areas.required` knob, and the area checks (mistag, dead-glob, overlap, area-unknown). Areas are aiwf's per-workstream / per-project grouping axis: you write code anywhere, but once you touch aiwf an entity belongs to a declared area (exactly one under `areas.required`), and `aiwf check` enforces that the tag matches where the work landed. Covers picking the area at `aiwf add` (explicit `--area`, or `--path-hint` derivation), fixing it with `aiwf set-area`, renaming a member with `aiwf rename-area`, and acknowledging legitimate cross-cutting with `aiwf acknowledge mistag`.

Use when the user asks "what happened to <entity>" or wants the timeline of an aiwf entity (or acceptance criterion). Runs `aiwf history` which reads `git log` filtered by structured commit trailers.

Turn a unit's crisp invariant into a generative property or metamorphic test — one that fabricates many inputs and asserts the property across all of them, not a single example. Use while implementing parsers, ledgers, state machines, allocators, or serializers, when hardening invariant-bearing code, or when the user invokes wf-property-test.

Use when `aiwf check` reports an `ids-unique` finding (two entities share an id, typically after a branch merge). Runs `aiwf reallocate` to renumber one of them and rewrite all references.