adr-author — Claude Code skill: ADRs and installation
The adr-author skill guides ADR drafting from decision context through option review to a finished record. Use it when a team needs to capture why an architecture choice was made and what follows from it.
MIT ★ 1,627 updated 2026-10-25
npx skills add microsoft/hve-core --skill adr-author -a claude-codeWhat adr-author does
The workflow has Frame, Decide, and Govern phases. It gathers scope, decision-makers, drivers, and constraints, then requires at least two options and a record of both positive and negative consequences. The user confirms each phase summary before the workflow advances. A decision with only one considered option cannot pass Decide.
Choose a compact Y-Statement or a full MADR v4.0.0 format. With MADR, the skill evaluates architectural-significance triggers; the final record also uses a selected diagram format and can track ADR supersession. Entry modes cover interactive authoring, planner handoff, and adopting an existing project template. Direct invocation follows session recovery through .copilot-tracking/adr-plans/{projectSlug}/state.json.
What it helps with
- capture the scope and constraints behind an architecture choice
- compare decision options against stated drivers
- record rationale and downsides for the chosen option
- draft an ADR in Y-Statement or MADR format
- adopt a project’s existing ADR template
Example prompts for the agent
- Guide me through an ADR for the service architecture and help compare the options.
- Create a MADR v4.0.0 record and evaluate its architectural-significance triggers.
- Use the project’s existing ADR template to prepare its first decision record.
How to install adr-author
1Skills CLI (Vercel)
npx skills add microsoft/hve-core --skill adr-author -a claude-code2Manually: put the files in place
~/.claude/skills/adr-author/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/adr-author/
1Skills CLI (Vercel)
npx skills add microsoft/hve-core --skill adr-author -a codex2Manually: put the files in place
.agents/skills/adr-author/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add microsoft/hve-core --skill adr-author -a cursor2Manually: put the files in place
.cursor/skills/adr-author/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install microsoft/hve-core .github/skills/project-planning/adr-author2Manually: put the files in place
.github/skills/adr-author/SKILL.md1Skills CLI (Vercel)
npx skills add microsoft/hve-core --skill adr-author -a gemini-cli2Platform CLI
gemini skills install https://github.com/microsoft/hve-core --path .github/skills/project-planning/adr-authorManually: put the files in place
.devin/skills/adr-author/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about adr-author
How do I install adr-author in Claude Code?
Run npx skills add microsoft/hve-core --skill adr-author -a claude-code. The skill file is at ~/.claude/skills/adr-author/SKILL.md.
What does adr-author do?
It guides the author through gathering decision context, weighing options, and producing an ADR. The user confirms phase summaries before the workflow continues.
How do Y-Statement and MADR differ in adr-author?
Y-Statement produces a compact decision record. MADR v4.0.0 uses a longer format and requires an architectural-significance trigger evaluation.
Source text
SKILL.md · MIT
---
name: adr-author
description: Authoring skill for Architecture Decision Records (ADRs) supporting capture, from-planner-handoff, and adopt-template entry modes with selectable Y-Statement or MADR v4.0.0 output templates, supersession lineage, and ASR trigger evaluation.
---
# adr-author
## Overview
This skill encodes the per-phase authoring conventions for Architecture Decision Records consumed by the ADR Creator agent. It also supports direct invocation when no ADR Creator state file exists. Direct callers first run the session recovery and bootstrap protocol from `adr-identity.instructions.md`: resolve or create `.copilot-tracking/adr-plans/{projectSlug}/state.json`, confirm `entryMode`, `projectSlug`, and `outputTemplate`, then continue at the phase recorded in state. It supports three entry modes and two output templates and converges all of them at the Govern phase, where the final ADR file is written and lineage is updated atomically.
Entry modes (`state.entryMode`):
- **capture** — Interactive authoring driven by user answers to Frame and Decide questions.
- **from-planner-handoff** — Entry from an upstream planner (Security, RAI, SSSC) with pre-populated Frame fields. Frame still requires user confirmation before exit.
- **adopt-template** — One-time setup mode that ingests a project's pre-existing ADR template and emits both the first ADR and a committed `.adr-config.yml`.
Output templates (`state.outputTemplate`):
- **y-statement** — Compact Y-Statement-shaped ADR for low-stakes or reversible decisions. Compressed Frame; ASR triggers optional.
- **madr-v4** — Long-form MADR v4.0.0 ADR for architecturally significant decisions. ASR trigger evaluation required during Frame.
Entry mode and output template are independent: a `from-planner-handoff` session can target either `y-statement` or `madr-v4`, and a `capture` session can do the same. The `adopt-template` mode produces output shaped by the user's normalized template.
Lifecycle at a glance:
| Mode | Phase sequence | Output |
|------------------------|-------------------------------------------------------|-----------------------------------------------------|
| `capture` | Frame → Decide → Govern | Shaped by `outputTemplate` (y-statement or madr-v4) |
| `from-planner-handoff` | Frame (confirm pre-populated) → Decide → Govern | Shaped by `outputTemplate` (y-statement or madr-v4) |
| `adopt-template` | Ingest → Normalize → Derive Questions → Fill → Govern | First ADR + `.adr-config.yml` per the BYO contract |
The state machine, hard exit gates, autonomy tiers (`manual`, `partial`, `full`), and the canonical `state.json` schema are defined in `adr-identity.instructions.md`. This skill provides the authoring activities and artifact contracts; it does not redefine the state machine.
## Frame
Activities:
- **Scope** — capture the decision in one or two sentences; bound it to a single project.
- **Decision-makers** — record `deciders`, `consulted`, `informed` (RACI-aligned). Prefer a role or team handle over a personal name, and never record personal contact details, secrets, credentials, or third-party or customer PII in any ADR field.
- **Drivers** — list decision drivers (functional needs, business goals).
- **Constraints** — list non-negotiables (regulatory, platform, contractual, time).
- **ASR trigger evaluation** — required when `state.outputTemplate == 'madr-v4'`. Evaluate triggers against the rubric in `adr-standards.instructions.md` and record results in `state.asrTriggers[]`. Defer the rubric and full taxonomy to that file and to `references/asr-trigger-taxonomy.md`.
- **Diagram-format prompt** — when `state.userPreferences.diagramFormat` is unset, check the architecture-diagrams root state at `.copilot-tracking/architecture-diagrams/state.json`; if that file provides `userPreferences.diagramFormat`, use it. Otherwise ask the user for `ascii` or `mermaid`, persist the answer to `state.userPreferences.diagramFormat`, and persist it to the architecture-diagrams root state for standalone reuse. When a caller, handoff, or existing ADR state already provides `state.userPreferences.diagramFormat`, treat that value as authoritative and do not ask again. Required before Frame can exit.
Hard exit gate (restated from `adr-identity.instructions.md`):
> The Frame phase cannot advance without all of the following recorded: scope statement, deciders list, decision drivers, ASR triggers determination (when `outputTemplate == 'madr-v4'`), and `userPreferences.diagramFormat`. The user must confirm the Frame summary before advancing.
Output artifacts:
- Frame section of the in-progress ADR draft (working draft only; not yet written to disk).
- Updated `state.json` fields: `scope`, `deciders`, `consulted`, `informed`, `drivers`, `constraints`, `asrTriggers` (when `outputTemplate == 'madr-v4'`), `userPreferences.diagramFormat`.
## Decide
Activities:
- **Option enumeration** — at least two considered options. A single-option ADR is rejected at this gate.
- **Evaluation criteria** — score each option against the drivers and constraints captured in Frame.
- **Decision outcome selection** — name the chosen option and articulate the rationale.
- **Consequences** — document positive, negative, and neutral consequences. Negative consequences are not optional; an ADR with no documented downside is rejected at this gate.
Y-Statement assembly (when `state.outputTemplate == 'y-statement'`):
- Compose the chosen option using the verbatim six-slot formula in `templates/y-statement.md`:
> In the context of (USE CASE), facing (CONCERN), we decided for (OPTION) and against (ALTERNATIVES), to achieve (QUALITY), accepting (DOWNSIDE).
- The Y-Statement is the entire Decide output for the `y-statement` template. The full MADR options table is omitted.
Hard exit gate:
> The Decide phase cannot advance without at least two considered options, the chosen option, and the decision rationale recorded. The user must confirm the Decide summary before advancing.
## Govern
This phase converges all three entry modes and is the only phase that writes ADR files to disk.
Activities:
1. **MADR v4 frontmatter assembly** — render the ADR frontmatter from `templates/madr-v4.md`. The template is reproduced verbatim from MADR v4.0.0 (CC0); see `references/standards-excerpts.md` for attribution. Merge `templates/madr-v4-frontmatter-overlay.md` on top to inject hve-core extension fields (`id`, `deciders`, `tags`, `supersedes`, `superseded-by`, `related`, `asr_triggers`) without modifying the verbatim upstream template (GP-17).
2. **Diagram render** — based on `state.userPreferences.diagramFormat`, embed the diagram body from either `templates/diagram-ascii.md` or `templates/diagram-mermaid.md`. Skill callers do not branch on platform; the template selection is purely data-driven. When the diagram is derived from infrastructure source files (Terraform, Bicep, ARM), invoke the `architecture-diagrams` skill with the authoritative format recorded in `state.userPreferences.diagramFormat`, and embed that output in place of the scaffold fragment. Standalone diagram generation uses the architecture-diagrams root state contract rather than ADR state.
3. **Lineage validation** — apply the six supersession rules summarized below; full text is in `references/lineage-rules.md`.
4. **Frontmatter validation** — invoke `scripts/validate_frontmatter.py` against the staged ADR file. The script returns a non-zero exit code on schema or enum violations and is the single authority for frontmatter shape.
5. **Lineage allocator** — invoke `scripts/update_lineage.py` to mutate `.adr-config.yml`. The allocator is the only writer of `last_decision_id`. Manual edits to `last_decision_id` are forbidden.
6. **Final write** — write the ADR to `docs/planning/adrs/{NNNN}-{slug}.md`. The path is derived from the allocator-issued `NNNN` and the slugified ADR title.
7. **Handoff trigger** — emit the dual-format (ADO + GitHub) work items per `adr-handoff.instructions.md`. This skill stops at handoff emission; routing is the agent's responsibility.
Govern uses the autonomy and disclaimer banners required by `adr-identity.instructions.md` and `shared/disclaimer-language.instructions.md`. Do not duplicate those texts here; load them at runtime.
## Supersession Lineage Rules (Summary)
Brief enumeration. Full normative text and edge cases live in `references/lineage-rules.md`.
1. `supersedes` and `superseded-by` are each a scalar string or `null`.
2. Single-parent supersession — a given ADR has at most one `superseded-by`.
3. Status transition — the superseding ADR's `status` becomes `accepted`; the superseded ADR's `status` becomes `superseded`.
4. Lineage updates are atomic — both ADR files MUST be updated in the same Govern phase.
5. The lineage allocator (`scripts/update_lineage.py`) is the single writer of `last_decision_id` in `.adr-config.yml`; manual edits are forbidden.
## Status Taxonomy
ADR `status` is one of six closed values. Full definitions and lifecycle transitions live in `adr-standards.instructions.md`.
- `proposed` — under active drafting; not yet decided.
- `accepted` — decision adopted; current authority for the scope.
- `rejected` — considered and declined; retained for historical context.
- `deprecated` — no longer recommended but not yet replaced.
- `superseded` — replaced by a newer ADR via the lineage rules below.
- `withdrawn` — proposal withdrawn before decision.
## ASR Trigger Catalog (Summary)
ASR (Architecturally Significant Requirement) triggers are evaluated only when `state.outputTemplate == 'madr-v4'`. The closed enum has eight values:
- `cost`
- `performance`
- `security`
- `compliance`
- `availability`
- `scalability`
- `maintainability`
- `evolvability`
The trigger rubric, evaluation prompts, and example mappings are defined in `adr-standards.instructions.md` and elaborated in `references/asr-trigger-taxonomy.md`. Do not introduce trigger values outside the closed enum.
## Adopt-Template Lifecycle
Five-step pointer. Full lifecycle, including GP-13 (the `.adr-config.yml` schema and the 2-layer config resolution), lives in `adr-byo-template.instructions.md`.
1. **Ingest** — accept the user's existing ADR template file or template directory.
2. **Normalize** — invoke `scripts/normalize_template.py` to convert the template into the canonical ADR frontmatter and section structure.
3. **Derive Questions** — generate the Frame and Decide question set from the normalized template's required fields.
4. **Fill** — execute the derived questions to populate the first ADR.
5. **Govern** — run the standard Govern phase. When `lineage_fields` are absent from the adopted template, the agent MUST warn the user and require an explicit confirmation before writing; this is the warn-and-confirm Govern behavior referenced in `adr-byo-template.instructions.md`.
## Templates
- `templates/madr-v4.md` — MADR v4.0.0 ADR template (verbatim, CC0). Used by Govern frontmatter assembly when `state.outputTemplate == 'madr-v4'`.
- `templates/y-statement.md` — Six-slot Y-Statement formula for Decide assembly when `state.outputTemplate == 'y-statement'`.
- `templates/diagram-ascii.md` — ASCII diagram block, selected when `state.userPreferences.diagramFormat == "ascii"`.
- `templates/diagram-mermaid.md` — Mermaid diagram block, selected when `state.userPreferences.diagramFormat == "mermaid"`.
## References
- `references/standards-excerpts.md` — MADR v4.0.0 verbatim text and CC0 attribution; Y-Statement attribution; status taxonomy.
- `references/lineage-rules.md` — Full text of the six supersession rules with edge cases and worked examples.
- `references/asr-trigger-taxonomy.md` — Full ASR trigger taxonomy, rubric prompts, and examples for each of the eight enum values.
## Scripts
- `scripts/render_template.py` — Renders a template from `templates/` against a Frame+Decide payload to produce an in-memory ADR draft. Path-traversal guarded: refuses any output path outside `docs/planning/adrs/`.
- `scripts/validate_frontmatter.py` — Validates ADR frontmatter against the MADR v4 schema and the closed enums. Returns non-zero on violation. Path-traversal guarded against the same root.
- `scripts/update_lineage.py` — Single writer of `last_decision_id` in `.adr-config.yml`. Mutates predecessor ADRs' `superseded-by` atomically with the new ADR's `supersedes`. Path-traversal guarded.
- `scripts/normalize_template.py` — Converts a user-supplied ADR template into the canonical structure used by `templates/madr-v4.md`. Used only by the `adopt-template` lifecycle. Path-traversal guarded.
- `scripts/scan_sensitive_content.py`: deterministic disclosure-risk scanner accepting file paths or stdin and emitting masked JSON findings. Base behavior detects high-confidence PII. `--public` adds internal URL detection. `--data` independently adds structured sensitive-column, connection, credential, sample-row, and international identifier detection. `--denylist <path>` independently adds case-insensitive literal customer-term detection from a UTF-8 file, resolved through the same allow-root guard as scanned paths and capped by file size, term count, and minimum term length. `--allow-root <dir>` adds a directory to that guard. The flags combine by union without changing no-flag ADR behavior. Required before durable ADR writes and external or handoff emission.
### Scanner report contract
The scanner prints one JSON object to standard output on every terminal path, including error paths, so callers can assert on fields rather than parse prose. The object carries `schema_version` (`scan-sensitive-content-v1`), `status` (`completed` or `error`), `modes` (booleans for `public`, `data`, and `denylist`), `denylist_rule_count`, `findings`, and `summary` with `high`, `warn`, and `total` counts. On `status` `error` it also carries `error` with a stable `code` and a `message`. Exit codes are `0` for a completed scan with no high-confidence finding, `1` for a completed scan with at least one high-confidence finding, and `2` for an error. A caller that requires denylist enforcement asserts `modes.denylist` is `true` and `denylist_rule_count` is greater than zero, so an empty or unloaded denylist cannot silently disable the gate.
All scripts treat their working directory as untrusted input. The ADR authoring scripts reject paths that resolve outside the project ADR root. `scan_sensitive_content.py` scans content that is not an ADR, so it rejects paths that resolve outside its allow roots: this skill's directory, the repository root, the parent directory of each path passed on the command line, and any directory supplied through `--allow-root`.
## Source Attribution
- `templates/madr-v4.md` — reproduced byte-identical from [MADR v4.0.0](https://github.com/adr/madr/blob/4.0.0/template/adr-template.md) (tag `4.0.0`, file `template/adr-template.md`), released under [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/). CC0 does not require attribution; it is recorded here for transparency. Upstream typographical anomalies (for example, the unbalanced quotation in the `status:` placeholder) are preserved intentionally to keep the file diff-clean against the upstream release.
## Mandatory Load Directives
The ADR Creator agent enforces a phase→section load contract per `adr-identity.instructions.md`. Each phase MUST load its section of this skill before executing phase work, and MUST append the section anchor to `state.phaseSkillsLoaded`:
| Phase | Section anchor | Required `phaseSkillsLoaded` entry |
|--------|----------------|------------------------------------|
| Frame | `#frame` | `adr-author#frame` |
| Decide | `#decide` | `adr-author#decide` |
| Govern | `#govern` | `adr-author#govern` |
The agent loads sections via `read_file` against this skill file and records the entry in `state.phaseSkillsLoaded` before any phase work executes. `phaseSkillsLoaded` is durable load history, not proof that the guidance is present in the current model context. Within one live context, re-entering a phase whose section was already read does not require reloading. After a cold start, resume, or context summarization, the agent reloads the current phase section even when its entry is recorded.
© microsoft · MIT · microsoft/hve-core