Architecture Decision Records
Architecture as a first-class concern. Owns the ADR lifecycle under docs/architecture/adr/
and the impact analysis of a proposed change against the decisions already taken.
The architect agent authors the decision content; this skill owns the lifecycle — numbering,
file layout, status transitions and the impact read. docs/architecture/ is the architect
agent's directory, so ADR bodies are written by that agent, never by another one.
Usage
mk:arch new [title]
mk:arch list
mk:arch review [number]
mk:arch impact [change description]
new [title]
- Scan
docs/architecture/adr/ and assign the next sequential ADR number.
- Gather context before writing anything: what decision is being made, what constrains it,
what options exist. If any of the three is unknown, ask — an ADR with an invented context
records a decision nobody took.
- Delegate the body to the
architect agent, with the sections: Title, Status (Proposed),
Context, Decision, Consequences, Alternatives Considered.
- Write
docs/architecture/adr/YYMMDD-title.md.
- Print the path and a one-paragraph summary, then ask for review. A Proposed ADR is not an
approved one.
list
Scan docs/architecture/adr/.
Print one row per ADR — number, title, status — with superseding links resolved:
# | Title | Status
1 | Use PostgreSQL for persistence | Accepted
2 | Event-driven architecture | Proposed
3 | Monorepo structure | Superseded by #5
review [number]
- Read the ADR.
- Evaluate three things explicitly: is the decision still valid, has the context changed, are
there alternatives that did not exist when it was taken.
- Update the status when the answer demands it — Proposed → Accepted, Accepted → Deprecated,
Accepted → Superseded by #N. A status left alone is also a result; say so.
- Append dated review notes. Never rewrite the original Context or Decision text: an ADR
records what was decided when it was decided, and editing that history makes it describe a
system it never approved.
impact [change description]
- Parse the change description into the components and boundaries it touches.
- Resolve which ADRs cover those components.
- Name every boundary the change crosses.
- Assess alignment per affected ADR: consistent, extends, or conflicts. A conflict is the
finding — do not soften it into "mostly aligned".
- Print affected components, affected ADRs, risk level, and a recommendation that names the
ADR to revisit when one conflicts.
Output
| Mode |
Output |
new |
docs/architecture/adr/YYMMDD-title.md plus a printed summary awaiting review |
list |
table of every ADR with status |
review |
the updated ADR with dated review notes |
impact |
printed assessment: components, ADRs, risk, recommendation |
Safety notes
- An ADR is documentation, not authority: recording a decision never approves a gate.
docs/architecture/adr/ is append-mostly. A superseded decision stays in the tree with its
status changed, so the record of what was believed at the time survives.
1---2name: mk-arch3description: ADR lifecycle under docs/architecture/adr/ — create, list, review, impact-analyse. NOT for mk:improve-codebase-architecture.4argument-hint: new [title] | list | review [number] | impact [change description]5source: local6trust_level: kit-authored7injection_risk: low8allowed-tools:9 - Read10 - Write11 - Edit12 - Glob13 - Grep14keywords:15 - adr16 - adr-lifecycle17 - decision-record18 - impact-analysis19 - boundary-review20when_to_use: A non-obvious architectural choice needs a durable record, or a change must be checked against past ADRs.21user-invocable: true22owner: docs23criticality: medium24status: active25runtime: claude-code26metadata:27 source: https://skillmd.com/skills/ngocsangyem/mk-arch28---2930# Architecture Decision Records3132Architecture as a first-class concern. Owns the ADR lifecycle under `docs/architecture/adr/`33and the impact analysis of a proposed change against the decisions already taken.3435The `architect` agent authors the decision content; this skill owns the lifecycle — numbering,36file layout, status transitions and the impact read. `docs/architecture/` is the architect37agent's directory, so ADR bodies are written by that agent, never by another one.3839## Usage4041```42mk:arch new [title]43mk:arch list44mk:arch review [number]45mk:arch impact [change description]46```4748## new [title]49501. Scan `docs/architecture/adr/` and assign the next sequential ADR number.512. Gather context before writing anything: what decision is being made, what constrains it,52 what options exist. If any of the three is unknown, ask — an ADR with an invented context53 records a decision nobody took.543. Delegate the body to the `architect` agent, with the sections: Title, Status (Proposed),55 Context, Decision, Consequences, Alternatives Considered.564. Write `docs/architecture/adr/YYMMDD-title.md`.575. Print the path and a one-paragraph summary, then ask for review. A Proposed ADR is not an58 approved one.5960## list61621. Scan `docs/architecture/adr/`.632. Print one row per ADR — number, title, status — with superseding links resolved:6465 ```66 # | Title | Status67 1 | Use PostgreSQL for persistence | Accepted68 2 | Event-driven architecture | Proposed69 3 | Monorepo structure | Superseded by #570 ```7172## review [number]73741. Read the ADR.752. Evaluate three things explicitly: is the decision still valid, has the context changed, are76 there alternatives that did not exist when it was taken.773. Update the status when the answer demands it — Proposed → Accepted, Accepted → Deprecated,78 Accepted → Superseded by #N. A status left alone is also a result; say so.794. Append dated review notes. Never rewrite the original Context or Decision text: an ADR80 records what was decided when it was decided, and editing that history makes it describe a81 system it never approved.8283## impact [change description]84851. Parse the change description into the components and boundaries it touches.862. Resolve which ADRs cover those components.873. Name every boundary the change crosses.884. Assess alignment per affected ADR: consistent, extends, or conflicts. A conflict is the89 finding — do not soften it into "mostly aligned".905. Print affected components, affected ADRs, risk level, and a recommendation that names the91 ADR to revisit when one conflicts.9293## Output9495| Mode | Output |96| --- | --- |97| `new` | `docs/architecture/adr/YYMMDD-title.md` plus a printed summary awaiting review |98| `list` | table of every ADR with status |99| `review` | the updated ADR with dated review notes |100| `impact` | printed assessment: components, ADRs, risk, recommendation |101102## Safety notes103104- An ADR is documentation, not authority: recording a decision never approves a gate.105- `docs/architecture/adr/` is append-mostly. A superseded decision stays in the tree with its106 status changed, so the record of what was believed at the time survives.