ADR Author Skill

The adr-author skill is the authoritative authoring layer for Architecture Decision Records (ADRs). It writes and edits ADRs that match the structure, tone, and depth of the project’s existing records — and it is the only skill that creates or modifies ADR files. Every other skill that needs an ADR written or changed delegates to adr-author rather than editing files directly.

What It Does

The skill takes responsibility for ADR quality end to end:

• Understands the decision context — researches the codebase, existing ADRs, and the problem space before writing
• Writes thorough ADRs — produces complete records with all required sections at production quality
• Maintains consistency — follows the exact structure, frontmatter field order, and domain ID conventions of the project
• Edits surgically — when updating an ADR, it preserves the record’s identity (ID and filename never change)

Operation Modes

Create Mode

Used when a new ADR is needed. The skill writes the full body from scratch, determines the next ADR ID from the existing list, generates the filename slug from the title, and writes the complete file to .archgate/adrs/<ID>-<slug>.md. The next ID is computed by listing existing ADRs, filtering by the domain prefix, and incrementing the highest number (zero-padded to three digits).

Edit Mode

Used when an existing ADR needs modification. The skill reads the current record, applies the requested changes, and writes the result back to the same path — using surgical edits for small changes or a full rewrite when restructuring. The ADR’s ID and filename are immutable.

The mode is chosen by intent: an ADR ID to update means Edit Mode; a new decision to document means Create Mode.

The Six Required Sections

Every ADR the skill produces follows this exact section order:

1. Context — the problem statement, pain points without standardization, an analysis of 3–4 competing alternatives with specific criticisms, project-specific motivation, and cross-references to related ADRs.

2. Decision — the concrete, prescriptive mandate in strong language (“MUST”, “will”), the scope (what it covers and what it does not), integration with other ADRs, and key capabilities.

3. Do’s and Don’ts — 5–10 Do’s (each prefixed DO, naming exact commands/APIs/patterns) and 5–8 Don’ts (each prefixed DON'T, naming a specific anti-pattern). Each item must be objectively verifiable.

4. Consequences — Positive (5–10 items), Negative (3–5 honest trade-offs), and Risks (2–4 items, each with an explicit mitigation — no orphan risks).

5. Compliance and Enforcement — automated enforcement (Archgate checks, CI, linting), manual review checklist items, scaffolding, and the exceptions process.

6. References — related ADRs via relative paths and external documentation.

Optional sections — Implementation Pattern (good/bad code examples), Key Definitions, Approved Exceptions, and Review Checklist — are added when they add value.

Frontmatter and Naming

Every ADR file lives at .archgate/adrs/<ID>-<slug>.md and opens with YAML frontmatter in a fixed field order: id → title → domain → rules → files (if present). rules is never omitted; it defaults to false.

---
id: BE-002
title: Backend Framework
domain: backend
rules: true
files:
  - "src/backend/**"
---

The ID prefix is derived from the domain — architecture → ARCH, backend → BE, frontend → FE, data → DATA, general → GEN. Projects may register custom domains; the skill always consults the merged domain list before choosing, and confirms with you before registering a new one.

Companion Rules Files

When rules: true, the skill creates the companion .rules.ts file at .archgate/adrs/<ID>-<slug>.rules.ts in the same invocation — never one without the other. The rules file references the ambient type declarations and exports a RuleSet whose checks run during archgate check. Each rule can be error (a hard blocker), warning (surfaced but non-blocking), or info.

Note

The RuleContext and RuleSet APIs used in .rules.ts files are newer than most model training cutoffs. The skill loads the authoritative rules-authoring guide — see the cli-reference skill and the reference at cli.archgate.dev for the exact API.

Tone and Quality Calibration

ADRs are written in prescriptive, specific, balanced language: “MUST” and “will” instead of “should” or “could” (ambiguity that automated checks cannot verify), exact tool and file names instead of vague guidance, and honest trade-offs instead of one-sided advocacy. Length matches scope — roughly 80–120 lines for a conceptual decision, up to ~400 lines for a framework choice with multiple code examples.

How It Fits the Workflow

adr-author is the shared writing layer beneath the rest of the governance system:

• The onboard skill calls it (via parallel sub-agents) to author the initial ADR backlog.
• The lessons-learned skill calls it whenever a captured pattern becomes a new or extended ADR.
• The reviewer skill checks code against the ADRs adr-author produces.

This single-authoring-layer design guarantees that every ADR — however it originates — meets the same quality bar.

Architecture Decision Records The authoritative ADR concept and CLI reference at cli.archgate.dev.