Adr Author

MicrosoftOfficialPublished by Microsoft

Skill
Content generator
Software development
MIT
Medium risk
Has scripts

From the author

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.

— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The adr-author skill provides a phase-gated workflow for creating and maintaining Architecture Decision Records (ADRs). It guides users through Frame, Decide, and Govern phases to ensure architectural decisions are documented with consistent rationale, consequences, and lineage. The skill supports multiple entry modes, including interactive capture, planner handoffs, and template adoption, while enforcing schema validation and automated lineage tracking for project documentation.

What it does

Guides users through Frame, Decide, and Govern phases for ADR creation.
Supports MADR v4.0.0 and Y-Statement output templates.
Automates lineage tracking and supersession rules for ADRs.
Validates ADR frontmatter and configuration against defined schemas.
Integrates with architecture-diagrams for visual documentation.
Scans content for sensitive information before writing files.

When to use it

When you need to document architectural decisions in a standardized format.
When transitioning from an existing ADR template to a new project structure.
When you need to link a new decision to a previous one via supersession.
When you need to evaluate Architecturally Significant Requirement (ASR) triggers.

Advantages

Enforces consistent documentation structure across a project.
Automates the management of ADR lineage and status transitions.
Provides clear gates for decision-making and rationale capture.
Includes built-in validation for frontmatter and sensitive content.

Usage examples

“I need to start a new ADR for our database migration.”: The agent initiates a capture session, prompting for scope, decision-makers, and drivers to begin the Frame phase.
“Adopt my existing ADR template for this project.”: The agent enters adopt-template mode, ingests your template, normalizes it, and generates the first ADR and configuration file.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/microsoft/adr-author/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip adr-author.zip -d .agents/skills

Documentation by Microsoft

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 references/adr-identity.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 references/adr-identity.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 references/adr-identity.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:

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).
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.
Lineage validation — apply the six supersession rules summarized below; full text is in references/lineage-rules.md.
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.
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.
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.
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 references/adr-identity.md and the disclaimer-language skill. 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.

supersedes and superseded-by are each a scalar string or null.
Single-parent supersession — a given ADR has at most one superseded-by.
Status transition — the superseding ADR's status becomes accepted; the superseded ADR's status becomes superseded.
Lineage updates are atomic — both ADR files MUST be updated in the same Govern phase.
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.

Ingest — accept the user's existing ADR template file or template directory.
Normalize — invoke scripts/normalize_template.py to convert the template into the canonical ADR frontmatter and section structure.
Derive Questions — generate the Frame and Decide question set from the normalized template's required fields.
Fill — execute the derived questions to populate the first ADR.
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/adr-identity.md — ADR Creator identity, three-phase state machine, six-step per-turn protocol, autonomy tiers, and the canonical state.json schema. Read it at session start.
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 (tag 4.0.0, file template/adr-template.md), released under CC0-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 references/adr-identity.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 reads sections of 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.

Files

ATTRIBUTION.mdAdded by AutoGineer872 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md16.4 KiB
pyproject.toml756 B
references/adr-identity.md20.2 KiB
references/asr-trigger-taxonomy.md5.1 KiB
references/authoring-rubric.md4.2 KiB
references/lineage-rules.md7.0 KiB
references/standards-excerpts.md4.1 KiB
scripts/__init__.pyScript136 B
scripts/_utils.pyScript2.0 KiB
scripts/normalize_template.pyScript6.9 KiB
scripts/render_template.pyScript5.2 KiB
scripts/scan_sensitive_content.pyScript26.5 KiB
scripts/update_lineage.pyScript10.3 KiB
scripts/validate_config.pyScript2.8 KiB
scripts/validate_frontmatter.pyScript14.7 KiB
templates/diagram-ascii.md1005 B
templates/diagram-mermaid.md628 B
templates/madr-v4-frontmatter-overlay.md1.7 KiB
templates/madr-v4.md3.2 KiB
templates/y-statement.md660 B
tests/__init__.pyScript148 B
tests/conftest.pyScript3.6 KiB
tests/corpus/0_frontmatter_minimal46 B
tests/corpus/1_markdown_anchors64 B
tests/corpus/2_slug_valid31 B
tests/corpus/README.md1.0 KiB
tests/fuzz_harness.pyScript4.2 KiB
tests/test_normalize_template.pyScript5.5 KiB
tests/test_render_template.pyScript5.3 KiB
tests/test_scan_sensitive_content.pyScript31.5 KiB
tests/test_update_lineage.pyScript10.4 KiB
tests/test_utils.pyScript3.3 KiB
tests/test_validate_frontmatter.pyScript15.2 KiB
uv.lock107.8 KiB

tests/fuzz_harness.py

# Copyright (c) 2026 Microsoft Corporation. All rights reserved.
# SPDX-License-Identifier: MIT
"""Polyglot Atheris fuzz harness for the ADR Author skill scripts.

Runs as a standalone Atheris fuzzer when invoked from the command line and as
a regular pytest test (importable smoke check) when discovered by pytest. This
matches the convention used elsewhere in the repository (see
`.github/skills/project-planning/jira/tests/fuzz_harness.py`) and satisfies the OSSF
Scorecard requirement for a fuzz harness in every Python skill that has a
`tests/` directory.

Targets:

* ``validate_frontmatter``: parsing arbitrary YAML frontmatter blobs.
* ``normalize_template``: extracting anchors from arbitrary markdown.
* ``update_lineage``: validating arbitrary slug bytes.
* ``_utils``: path-traversal detection and allow-root resolution.
"""

from __future__ import annotations

import sys
from contextlib import suppress
from pathlib import Path

try:
    import atheris
except ImportError:  # pragma: no cover - atheris is optional in pytest mode
    atheris = None  # type: ignore[assignment]
    FUZZING = False
else:
    FUZZING = True

# Make the sibling `scripts/` directory importable when invoked standalone.
_SKILL_ROOT = Path(__file__).resolve().parent.parent
_SCRIPTS_DIR = _SKILL_ROOT / "scripts"
if str(_SCRIPTS_DIR) not in sys.path:
    sys.path.insert(0, str(_SCRIPTS_DIR))


def _fuzz_validate_frontmatter(data: bytes) -> None:
    """Feed arbitrary bytes through the frontmatter parser."""
    with suppress(Exception):
        from scripts import validate_frontmatter  # type: ignore[import-not-found]

        parser = getattr(validate_frontmatter, "parse_frontmatter", None)
        if parser is None:
            return
        with suppress(ValueError, KeyError, TypeError, UnicodeDecodeError):
            parser(data.decode("utf-8", errors="replace"))


def _fuzz_normalize_template(data: bytes) -> None:
    """Feed arbitrary markdown through the anchor extractor."""
    with suppress(Exception):
        from scripts import normalize_template  # type: ignore[import-not-found]

        extract = getattr(normalize_template, "extract_anchors", None)
        if extract is None:
            return
        with suppress(ValueError, KeyError, TypeError, UnicodeDecodeError):
            extract(data.decode("utf-8", errors="replace"))


def _fuzz_update_lineage_slug(data: bytes) -> None:
    """Feed arbitrary bytes through the slug validator."""
    with suppress(Exception):
        from scripts import update_lineage  # type: ignore[import-not-found]

        validate_slug = getattr(update_lineage, "validate_slug", None)
        if validate_slug is None:
            return
        with suppress(ValueError, TypeError, UnicodeDecodeError):
            validate_slug(data.decode("utf-8", errors="replace"))


def _fuzz_utils(data: bytes) -> None:
    """Feed arbitrary path bytes through the traversal guards."""
    with suppress(Exception):
        from scripts import _utils  # type: ignore[import-not-found]

        candidate = Path(data.decode("utf-8", errors="replace"))

        has_traversal = getattr(_utils, "has_traversal_segments", None)
        if has_traversal is not None:
            with suppress(ValueError, TypeError, OSError, UnicodeDecodeError):
                has_traversal(candidate)

        safe_resolve = getattr(_utils, "safe_resolve", None)
        if safe_resolve is not None:
            with suppress(ValueError, TypeError, OSError, UnicodeDecodeError):
                safe_resolve(candidate, [_SKILL_ROOT])


FUZZ_TARGETS = (
    _fuzz_validate_frontmatter,
    _fuzz_normalize_template,
    _fuzz_update_lineage_slug,
    _fuzz_utils,
)


def _entry(data: bytes) -> None:
    """Atheris entrypoint: dispatch to one target per iteration."""
    if not data:
        return
    target = FUZZ_TARGETS[data[0] % len(FUZZ_TARGETS)]
    target(data[1:])


def test_fuzz_harness_importable() -> None:
    """Pytest smoke test: the harness imports and exposes its entrypoint."""
    assert callable(_entry)
    assert FUZZ_TARGETS
    for target in FUZZ_TARGETS:
        assert callable(target)


if __name__ == "__main__" and FUZZING:  # pragma: no cover - exercised by Atheris
    atheris.Setup(sys.argv, _entry)
    atheris.Fuzz()

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

Security

What our scanner noticed· Medium risk

References to credential files
Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

Microsoft

Publisher

Microsoft (Official)

Source

microsoft/hve-core · .github/skills/project-planning/adr-author · commit f425e94

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by Microsoft or Microsoft.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download adr-author.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Microsoft

adr-author

Overview

Frame

Decide

Govern

Supersession Lineage Rules (Summary)

Status Taxonomy

ASR Trigger Catalog (Summary)

Adopt-Template Lifecycle

Templates

References

Scripts

Scanner report contract

Source Attribution

Mandatory Load Directives

Files

tests/fuzz_harness.py

Requirements and compatibility

Security

Attribution and licence

Related skills

Setup TS Deep Modules

To Spec

Improve Codebase Architecture

Domain Modeling

Codebase Design

Prototype

Download ZIP