Adr

Architecture Decision Records

Record why the current architecture exists without turning every code change into documentation.

Classify first

Create or update an ADR when a decision changes a cross-cutting system property, including:

• trust boundaries, authorization, isolation, or privileged credentials;
• persistence, storage, backup, or recovery architecture;
• deployment topology, release flow, or environment promotion;
• a provider or platform choice that constrains multiple features;
• a security or processing boundary reused by multiple features.

Use an FDR for implemented user-visible behavior or a feature-local choice. Use no decision record for a local implementation detail, ordinary refactor, dependency patch, or bug fix that preserves architecture and behavior.

When uncertain, state the classification and evidence before writing. Do not create a record merely because a source document exists.

Read narrowly

1. Follow the repository's instruction files and discovery conventions.
2. Read docs/adr/INDEX.md when it exists.
3. Read only ADRs related to the decision.
4. For a current change, inspect its implementation, tests, and supporting documentation.
5. For retrospective work, also verify release or rollout evidence before claiming the decision is deployed.

Source documents identify intent and rationale. They do not prove current state by themselves.

For retrospective work, do not use Proposed as a substitute for missing implementation or release evidence. Leave the candidate unresolved. Proposed is only for a decision that is currently under review.

Operations

Create

Use the next unused three-digit ID from docs/adr/INDEX.md and existing filenames. Create docs/adr/ADR-NNN-kebab-case-title.md and add it to the index in the same change.

Update

Correct clarification, evidence, or consequences in place only when the decision itself is unchanged. Refresh the index if status or title changes.

Supersede

Do not rewrite an incompatible accepted decision. Create a new ADR, mark the old status Superseded by ADR-NNN, link both records, and update both index rows. Preserve the old context and decision.

Audit

Compare the selected ADRs with current implementation and release evidence. Report confirmed, drifted, superseded, and unresolved records. Do not silently edit records unless the user also authorized changes.

Backfill preview

Invoke as backfill preview [sources...].

This mode is read-only:

1. If sources are supplied, use only those sources for candidate discovery unless the user permits broader discovery. Required verification of current code, migrations, configuration, tests, and release evidence remains in scope.
2. Otherwise, discover likely history under docs/superpowers/specs/, docs/superpowers/plans/, architecture or security documentation, runbooks, release notes, and any production plan referenced by repository instructions.
3. Verify candidates against current code, migrations, configuration, tests, and release evidence as applicable.
4. Return the sources consulted and group candidates as confirmed, rejected, duplicate, planned-only, or unresolved.
5. For each confirmed candidate, propose a title and cite supporting evidence.
6. Store a JSON preview manifest under $(git rev-parse --git-common-dir)/decision-previews/ using the exact schema below. Do not reserve record IDs.

Do not create records, update indexes, reserve IDs, or edit source documents in preview mode. The manifest is the preview's only file write and lives outside the working tree. Report its path and SHA-256 digest so the user can review and authorize that exact candidate set.

Preview manifest schema

Use these exact snake_case fields so another supported agent can validate and apply the same manifest:

{
  "format_version": 2,
  "record_type": "ADR",
  "operation": "backfill-preview",
  "created_at": "ISO-8601 UTC timestamp",
  "repository": {
    "identity": "origin URL, or absolute repository root when no origin exists",
    "head": "full Git commit SHA"
  },
  "discovery_sources": [{ "path": "repository-relative POSIX path or canonical file URI", "sha256": "hex" }],
  "verification_evidence": [{ "path": "repository-relative POSIX path or canonical file URI", "sha256": "hex" }],
  "record_snapshot": {
    "entries": [{ "path": "repository-relative path", "sha256": "hex" }],
    "aggregate_sha256": "hash of the ordered path and content-hash entries"
  },
  "candidates": [{
    "key": "stable preview-local key",
    "classification": "confirmed | rejected | duplicate | planned-only | unresolved",
    "proposed_title": "title or null",
    "proposed_status": "Accepted | Deprecated | null",
    "related_adrs": ["ADR-NNN"],
    "evidence_paths": ["repository-relative POSIX path or canonical file URI"]
  }],
  "record_ids_reserved": false
}

For a file inside the repository, path is its normalized POSIX path relative to the repository root. For an external file explicitly supplied by the user or referenced by repository instructions, resolve symlinks with the platform realpath operation and encode that absolute path as an RFC 8089 file: URL; that URL is path. Files within the repository still use the repository form, even if supplied by absolute path. Expand a supplied directory to the regular files actually consulted and record each file separately. Reject other URI schemes, relative paths that escape the repository, a file URL that does not round-trip to the same realpath, and external files that were neither supplied nor referenced. Apply resolves each entry by these rules and hashes its bytes again before writing.

For a confirmed candidate, proposed_title and proposed_status are non-null, related_adrs contains sorted unique existing ADR identifiers or is empty, and evidence_paths is non-empty. For every other classification, proposed_status is null and related_adrs is empty. These fields remain in every candidate object so ADR and FDR manifests have the same field names.

record_snapshot.entries must be a complete sorted inventory of docs/adr/, including docs/adr/INDEX.md; additions and removals must therefore change the aggregate hash. Sort entries bytewise by path, encode each as UTF-8 <path>\t<sha256>\n, concatenate without a header or trailing data beyond each entry's newline, and SHA-256 that byte sequence. Producers and validators must use this exact serialization.

Backfill apply

Invoke as backfill apply <manifest-path> --manifest-sha256 <sha256> --authorize <key>[,<key>...] only when the user supplies that exact command or explicitly approves its exact path, digest, and unique comma-separated candidate-key set. Treat the authorization list as a set; it may be a strict subset of confirmed candidates, but every key must be confirmed in the manifest. Do not rediscover candidates during apply.

Before parsing or writing, hash the exact manifest bytes and require an exact match with --manifest-sha256. Then reject a missing or malformed manifest (including unknown or missing schema fields), the wrong repository or record type, duplicate authorization keys, any changed discovery-source or verification-evidence hash, any changed record/index snapshot, or any authorized key that is not confirmed. The records written must match the authorized key set exactly. A stale or mismatched manifest requires a new preview; do not repair it in place. Allocate IDs at write time and update the index atomically in the same change. Omit unresolved, duplicate, planned-only, unverified, and confirmed-but-unauthorized candidates. Applying a subset makes the snapshot stale, so remaining candidates require a new preview.

Record format

# ADR-NNN: Decision title

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-NNN
**Date:** YYYY-MM-DD

## Context

What forced a choice, including the constraints that matter.

## Decision

The chosen architecture and its boundary.

## Consequences

The benefits, costs, risks, and follow-up constraints.

## Evidence

- [Current implementation](relative/path)
- [Test or migration](relative/path)
- [Release or operational evidence](relative/path)

Use repository-relative links. Keep operational procedures in their runbooks and link them instead of copying them into the ADR.

Completion checks

• The decision meets the ADR threshold.
• Current and deployment claims have evidence.
• The ID and filename are unique and sequential.
• Required sections are present with no unresolved placeholders.
• Superseded history is preserved.
• docs/adr/INDEX.md contains exactly one matching row.
• For a current decision, the record changes in the same pull request as the qualifying change. A retrospective backfill instead requires historical implementation and release evidence through its authorized manifest.
• A backfill apply is bound to one valid, unchanged, explicitly authorized preview manifest.
• Every validation command required by the repository's governing instructions passes; running only a subset is not completion.