microsoft/hve-core

---
description: 'BYO ADR template contract: 2-layer config resolution, .adr-config.yml schema, template frontmatter contract, and adopt-template lifecycle for the ADR Creator - Brought to you by microsoft/hve-core'
applyTo: '**/.copilot-tracking/adr-plans/**, **/docs/planning/adrs/**/.adr-config.yml, **/docs/planning/adrs/**'
---

# ADR Bring-Your-Own-Template Contract

The ADR Creator supports user-supplied (BYO) decision-record templates through the `adopt-template` entry mode. This contract defines how configuration resolves, what fields a project config and a BYO template must declare, and how the `adopt-template` lifecycle ingests, normalizes, and governs a non-default template.

Scope: applies to ADR planning sessions under `.copilot-tracking/adr-plans/`, the committed config at `docs/planning/adrs/.adr-config.yml`, and rendered ADRs under `docs/planning/adrs/`.

## Configuration Resolution Order

Configuration resolves in exactly two layers. Higher-priority layers fully override lower-priority layers on a per-field basis. There is no per-session override and no gitignored override layer.

1. Layer 1 (highest priority): committed per-project config at `docs/planning/adrs/.adr-config.yml`. This file is checked in and shared across the team. It is the source of truth for everything the ADR Creator needs to know about a project.
2. Layer 2 (fallback): workspace defaults baked into the `adr-author` skill's starter templates. These defaults ship with the skill and provide values when the per-project config omits a field that has a documented default.

> [!IMPORTANT]
> Required fields in `.adr-config.yml` cannot be filled by Layer 2. Validation hard-fails when any required field is missing from Layer 1.

## `.adr-config.yml` Schema (GP-13)

Every per-project ADR config declares these six fields as top-level YAML keys. All six are REQUIRED. The validator hard-fails when a field is missing, blank, or malformed.

```yaml
project_slug: <kebab-case; required>
owner: <github-handle-or-team; required>
default_status: proposed | accepted   # required; default `proposed`
decision_id_format: 'NNNN'            # required; 4-digit zero-padded enforced by allocator
template_source: madr-v4 | y-statement | <relative-path-to-byo>
last_decision_id: '<NNNN; required; 4-digit zero-padded monotonic allocator state>'
```

Field rules:

* `project_slug` is kebab-case.
* `owner` is a GitHub handle (for example, `@octocat`) or a team slug (for example, `@org/team-name`).
* `default_status` accepts `proposed` or `accepted`. The default value is `proposed` when the field is set to a literal default marker; the field itself is still required.
* `decision_id_format` is the literal string `'NNNN'`. The allocator emits 4-digit zero-padded IDs (`0001`, `0002`, ...).
* `template_source` is one of the two starter template identifiers (`madr-v4` or `y-statement`) or a workspace-relative path to a BYO template. Diagram rendering inside `madr-v4` is selected separately via `state.userPreferences.diagramFormat` and composed at render time from the matching diagram fragment; do not encode the diagram variant in `template_source`.
* `last_decision_id` records the highest decision ID issued for this project. It is updated by `scripts/update_lineage.py` after each successful ADR write.

> [!CAUTION]
> Manual edits to `last_decision_id` are rejected. The allocator owns this field; out-of-band changes break monotonic ID allocation and are flagged by the validator.

## BYO Template Frontmatter Contract

A BYO template MUST declare these three frontmatter fields so the `adopt-template` lifecycle can ingest, normalize, and govern it.

```yaml
---
template: <string identifier for the template>
placeholders:
  - <placeholder-name-used-in-body>
  - <another-placeholder-name>
lineage_fields:
  - <frontmatter-field-name-that-participates-in-supersession>
---
```

Field rules:

* `template` is a string identifier used by the agent and skill scripts to refer to the template.
* `placeholders` lists every named placeholder the template body uses. The Normalize step verifies this list against the body and emits a derived placeholders manifest.
* `lineage_fields` lists the frontmatter field names that participate in supersession (for example, `supersedes`, `superseded-by`, `related`). When this field is absent, the Govern phase emits the warning described below.

## Govern-Phase Warning for Missing `lineage_fields`

When a BYO template lacks `lineage_fields`, Govern phase cannot auto-validate supersession links. The agent emits a warning to the user:

> Govern phase cannot auto-validate supersession links because the BYO template did not declare `lineage_fields`. Confirm manually that any supersession references in this ADR resolve to existing decisions before publishing.

The agent then offers manual confirmation. The user either confirms each lineage link by hand or declines and returns to the Normalize step to amend the BYO template.

## Starter Templates Inventory

The starter templates ship inside the `adr-author` skill bundle. The legacy template under `docs/templates/` remains available as a workspace-level fallback for compatibility.

| Template Identifier | Location                                   | Purpose                                                                                                                                                                            |
|---------------------|--------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `madr-v4`           | Skill: `templates/madr-v4.md`              | MADR v4.0.0 verbatim (CC0). Diagram slot is composed at render time with `templates/diagram-ascii.md` or `templates/diagram-mermaid.md` per `state.userPreferences.diagramFormat`. |
| `y-statement`       | Skill: `templates/y-statement.md`          | Y-Statement six-slot template (context, facing, decided for, achieve, accepting, contrast).                                                                                        |
| Workspace fallback  | `docs/templates/adr-template-solutions.md` | Legacy solutions-analysis template retained for repositories that already reference it.                                                                                            |

Frontmatter overlay `templates/madr-v4-frontmatter-overlay.md` adds ADR Creator workflow fields (`asrTriggers`, lineage links) to the verbatim MADR v4 frontmatter without modifying the upstream template body.

## `adopt-template` Lifecycle (GP-08)

The `adopt-template` entry mode runs five sequential steps. Each step has clear inputs, outputs, and failure behavior.

### Step 1: Ingest

Read the user-provided BYO template path. Verify the file exists and contains YAML frontmatter. Reject the template when frontmatter is absent or unparseable, and prompt the user for a corrected path.

### Step 2: Normalize

Delegate to `scripts/normalize_template.py` (GP-05). The normalizer performs four tasks:

1. Parses the BYO template frontmatter and body.
2. Maps non-MADR sections to MADR v4.0.0 canonical sections.
3. Emits `template_source: <relative-path>` and a derived placeholders manifest.
4. Hard-fails on unmappable required sections and surfaces the gap list to the agent for user dialogue.

When the normalizer hard-fails, the agent presents the gap list to the user, asks how to resolve each unmappable section (for example, drop, alias, or amend the template), and then re-runs the normalizer.

### Step 3: Derive Questions

Generate the question backlog the agent will ask during the Frame phase. Inputs are the normalized template and the derived placeholders manifest. Outputs are an ordered list of questions whose answers fill the placeholders.

### Step 4: Fill

Run the standard Frame to Decide flow using the normalized template. Frame collects answers to the derived questions; Decide renders the template with the collected answers.

### Step 5: Govern

Run the standard Govern phase with lineage validation. When `lineage_fields` is absent from the BYO template frontmatter, emit the warning described in the Govern-Phase Warning section and offer manual confirmation.

## Diagram-Format Selection

In the Frame phase, the agent asks the user once per session:

> Diagram format for this ADR: ASCII art or Mermaid?

Capture the answer into `state.userPreferences.diagramFormat` (GP-04). At Decide-phase render time, use the captured value to compose `templates/madr-v4.md` with the matching diagram fragment from `templates/diagram-ascii.md` or `templates/diagram-mermaid.md`. BYO templates that supply their own diagram slot ignore this selection; the prompt still runs so the captured value is available to downstream tooling and review artifacts.