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
Decision gist · record as of 2026-07-28
adr-author structures architecture decision authoring through Frame, Decide, and Govern phases with Y-Statement or MADR v4.0.0 output. 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.
Use it when
- adr-author generates ADRs in two formats: Y-Statement for concise decisions, and MADR v4.0.0 for detailed architecture decision records.
- Yes.
Verify before relying
Read SKILL.md below before installing (33 files). Open directory: indexed for reading, not audited.
Install
microsoft/hve-core/adr-author · repository language: PowerShell
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently 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)
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
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Author architecture decision records using Frame-Decide-Govern phases”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
Create and maintain architecture decision records (ADRs) using established conventions, templates, and a built-in validator. The skill guides you through prospective and retrospective record creation, enforces quality standards like one decision per record and credible alternatives, and helps manage decision lifecycles with status tracking and supersession links. Use it to build a durable, reviewable record of why architecturally significant choices were made.
This skill walks you through the complete ADR lifecycle—from evaluating whether a decision is ready to record, through structured creation using the MADR template, to quality checks and ongoing log management. It grounds decisions in proven frameworks like START (readiness criteria) and ECADR (completion criteria), helping teams capture architectural rationale rather than just outcomes.
This skill generates Architecture Decision Records (ADRs) that capture the context, decision, and consequences of significant technical choices. It guides you through gathering essential information, selecting from three formats (MADR, Nygard, or Y-Statement), and produces a structured document that preserves reasoning for future engineers.
ADR Author guides you through writing Architectural Decision Records that future developers and automated systems can actually enforce. It covers the full workflow from reading existing ADRs to drafting decisions at the right enforceability level—whether you need automated verification, human review, or reference-only documentation.
Guides you through seven-phase ADR drafting via focused dialogue, asking one question per turn and pressure-testing your reasoning before self-critique. Enforces specificity on components, deciders, and architectural characteristics, then routes to discovery if foundations are shallow.
Adr Skill guides you through a structured four-phase workflow to author Architecture Decision Records that serve as executable specifications for coding agents. It captures decision intent through targeted questioning, scans your codebase for related patterns and existing ADRs, then drafts records with implementation plans concrete enough for agents to act on without follow-up.
More skills adr-writing (Apache-2.0) · architecture-decision-records (MIT) · Adr Skill (unlicensed) · documentation-criteria (MIT)