From aiwf-extensions
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.
How this skill is triggered — by the user, by Claude, or both
Slash command
/aiwf-extensions:aiwfx-record-decisionThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A thin recipe. The skill exists so the mechanical steps of capturing a decision (allocate the id, pick the right template, fill it in, commit) happen consistently from any caller.
A thin recipe. The skill exists so the mechanical steps of capturing a decision (allocate the id, pick the right template, fill it in, commit) happen consistently from any caller.
A decision becomes clear that future readers (six months from now) would regret not finding written down. Triggers:
The decision can surface anywhere — during planning (aiwfx-plan-epic), mid-implementation (aiwfx-start-milestone), at review (wf-review-code), at wrap (aiwfx-wrap-milestone or aiwfx-wrap-epic). Wherever it surfaces, hand off to this skill and continue.
| Pick | When |
|---|---|
ADR (docs/adr/ADR-NNNN-<slug>.md) | Architectural. Durable across multiple epics. Cross-cutting concern (sec, perf, data model, dependency choice, language idiom). The kind of thing a new contributor reads to understand "why is this code shaped this way?" |
D-NNN (work/decisions/D-NNN-<slug>.md) | Project-scoped. Tied to a specific epic or milestone. Sequencing decisions, scope cuts, mid-implementation pivots, deliberate trade-offs that don't rise to architectural weight. |
If you're unsure, ADR is usually the right call — durability is the cheap-to-add side. The cost of writing one ADR that turns out to be project-scoped is small; the cost of failing to record an architectural decision is large.
Ask the user (or, if the calling skill knows, just pick): ADR or D-NNN?
For an ADR:
aiwf add adr --title "<imperative title>"
For a D-NNN:
aiwf add decision --title "<imperative title>"
aiwf creates the file with the minimal body skeleton, sets frontmatter, produces one commit with aiwf-verb: add trailers.
For an ADR: read this plugin's templates/adr.md. Fill in:
proposed while the decision is open for ratification; flip to accepted once it's in force.For a D-NNN: read this plugin's templates/decision.md. Fill in:
In the body, just under the # ADR-NNNN — <title> (or # D-NNN — <title>) heading, add a one-line block-quote header capturing date and the person making the call:
> **Date:** YYYY-MM-DD · **Decided by:** <role/name>
These do not go in frontmatter. aiwf core's frontmatter parser is strict — it rejects unknown fields so typos don't go silent — and date / decided_by are not part of the validated entity schema. Putting them in frontmatter would fail aiwf check.
The canonical timestamp and actor are also recoverable from git via aiwf history <id> (commit author + ISO date), so the body header is redundant-but-friendly: it lets a human reading the file see when and by whom the decision was made without dropping to the CLI.
aiwf core only validates these frontmatter fields on ADR / D-NNN entries: id, title, status, plus the cross-reference fields. Set the cross-references when relevant:
supersedes: [ADR-NNNN]. Then edit the superseded ADR to set superseded_by: ADR-NEW and promote it to superseded via aiwf promote.relates_to: [E-NN, M-NNN] so cross-references resolve.Skip both if no cross-references apply.
aiwf check
Catches things like a misnamed reference, an out-of-set status, or a broken supersession chain.
The aiwf add already produced one commit (the scaffold). The body fill is a second commit:
git add docs/adr/ADR-NNNN-<slug>.md # or work/decisions/D-NNN-<slug>.md
git commit -m "docs(adr): ADR-NNNN — <title>"
The two-commit shape is intentional: the first commit is "id allocated"; the second is "decision authored." aiwf history ADR-NNNN shows both.
If invoked from aiwfx-start-milestone mid-flight: add the new id under ## Decisions made during implementation in the tracking doc.
If from aiwfx-wrap-epic's ADR harvest: add to ## ADRs ratified or ## Decisions captured in wrap.md.
If from wf-review-code: list it under "Track for later" in the review report.
The decision now exists; the calling skill resumes its workflow.
ADRs and D-NNN decisions start as proposed. They're promoted via aiwf promote:
aiwf promote ADR-NNNN accepted # in force
aiwf promote ADR-NNNN superseded # replaced (set superseded_by first)
aiwf cancel ADR-NNNN # rejected (terminal)
Same for D-NNN. aiwf validates each transition; illegal moves error out.
superseded and gets a superseded_by: pointer. Both edits.proposed. If it's in force, promote to accepted. Otherwise it never feels "decided."aiwf add adr, when the decision is real. The body fill is what makes the record useful; the id alone isn't.Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
npx claudepluginhub 23min/ai-workflow-rituals --plugin aiwf-extensions