adr-author
adr-author guides you through structured architecture decision authoring in three phases: Frame captures scope and drivers, Decide evaluates options and rationale, and Govern writes the final ADR file with lineage tracking. Choose between compact Y-Statement or detailed MADR v4.0.0 output, and enter via interactive capture, planner handoff, or template adoption.
adr-author structures architecture decision authoring through Frame, Decide, and Govern phases with Y-Statement or MADR v4.0.0 output.
AI-generated summary based on this skill's SKILL.md
Install
microsoft/hve-core/adr-author · repository language: PowerShell
git clone https://github.com/microsoft/hve-core
cp -r hve-core/.github/skills/project-planning/adr-author ~/.claude/skills/adr-authornpx skillfed install microsoft/hve-core/adr-authorFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to write architecture decision records with adr-author?
adr-author guides you through structured authoring in three phases: Frame captures scope and drivers, Decide evaluates options and rationale, and Govern writes the final ADR file with lineage tracking. You choose between compact Y-Statement or detailed MADR v4.0.0 output format, then enter via interactive capture, planner handoff, or template adoption to generate validated decision records.
What ADR formats does adr-author support?
adr-author generates ADRs in two formats: Y-Statement for concise decisions, and MADR v4.0.0 for detailed architecture decision records. Both formats include frontmatter validation and can be generated through the Frame-Decide-Govern workflow, ensuring consistent structure and traceability across your decision documentation.
Can adr-author adopt existing ADR templates?
Yes. adr-author normalizes existing ADR templates into its canonical structure through template adoption mode. This lets you migrate legacy decision records into standardized Y-Statement or MADR v4.0.0 format while preserving content and establishing lineage tracking for superseded decisions.
Does adr-author track decision history and supersession?
adr-author manages ADR supersession lineage and decision history, allowing you to track which decisions replace earlier ones and maintain a complete audit trail. This capability integrates with the Govern phase to document decision evolution and dependencies across your architecture documentation.
What triggers ADR authoring in adr-author?
adr-author evaluates architecturally significant requirements (ASR) triggers to identify when ADR authoring is needed. You can enter the workflow via interactive capture for new decisions, planner handoff for decisions emerging from planning sessions, or template adoption to normalize existing records into canonical format.
Is adr-author open source?
Yes, adr-author is released under the MIT license, making it freely available for commercial and personal use. You can modify, distribute, and integrate it into your architecture decision documentation workflows without licensing restrictions.
SKILL.md
rendered from the published skill — quoted content, verbatim
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
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 15 files
.github/skills/project-planning/adr-author/SKILL.md
.github/skills/project-planning/adr-author/pyproject.toml
.github/skills/project-planning/adr-author/references/asr-trigger-taxonomy.md
.github/skills/project-planning/adr-author/references/authoring-rubric.md
.github/skills/project-planning/adr-author/references/lineage-rules.md
.github/skills/project-planning/adr-author/references/standards-excerpts.md
.github/skills/project-planning/adr-author/scripts/__init__.py
.github/skills/project-planning/adr-author/scripts/_utils.py
.github/skills/project-planning/adr-author/scripts/normalize_template.py
.github/skills/project-planning/adr-author/scripts/render_template.py
.github/skills/project-planning/adr-author/scripts/scan_sensitive_content.py
.github/skills/project-planning/adr-author/scripts/update_lineage.py
.github/skills/project-planning/adr-author/scripts/validate_config.py
.github/skills/project-planning/adr-author/scripts/validate_frontmatter.py
.github/skills/project-planning/adr-author/templates/diagram-ascii.md