Skip to main content

ADR-0020: Intent to ASR, ADR, Spec, Contract, and planning governance chain

  • Status: Accepted
  • Date: 2026-07-17
  • Deciders: Michel Gillet

Context​

ADR-0019 establishes Architecture Significant Requirements (ASRs) as first-class artifacts. A2C already has ADRs, optional Specs (templates/spec/), and planning artifacts under planning/. Without an explicit chain, teams and AI agents improvise how intent becomes requirements, decisions, behavior specs, interfaces, and delivery work.

This ADR defines that governance chain for A2C. It does not mandate Specs or Contracts in every repository. Detailed Amends vs Supersede status semantics are in ADR-0021. Narrative architecture stories are ADR-0022. PRs as architecture control points are ADR-0023.

Decision​

  1. Intent → ASRs

    High-level intent (problems, goals, objectives, constraints) is translated into ASRs. ASRs are the canonical representation of architecture-significant requirements when a project adopts ASR practice (ADR-0019).

  2. ASRs → ADRs

    ADRs record architectural decisions that satisfy, refine, or change ASRs. Material ASR changes require a corresponding ADR (ADR-0019); amendment vs supersession mechanics for ADRs are ADR-0021.

  3. ADRs → Specs and Contracts (optional branch)

    ADRs are the bridge from ASRs to:

    • Specs — feature-level behavior (functional and non-functional requirements) constrained by ASRs/ADRs
    • Contracts — interface and ABI definitions implied by ADRs

    Specs and Contracts are optional. If a project uses them, they must follow A2C conventions (templates, cross-references to ASRs/ADRs, docs-as-code under the project’s chosen paths). ADRs should list Specs and Contracts they materially influence when those artifacts exist and the relationship is known.

  4. Specs / plans → delivery → feedback

    When Specs exist, they feed planning (Epics, Tasks, Sprints under planning/) and implementation batches. Implementation feedback updates Specs where appropriate and, when architecture must change, produces new ADRs (and ASR updates only via those ADRs).

    When Specs are omitted, planning and implementation still reference governing ASRs/ADRs directly.

  5. ProductPhase (optional metadata)

    ASRs and ADRs may record an optional ProductPhase (e.g. 1.0, 2.0) to tie artifacts to product evolution. ProductPhase does not replace Status lifecycle; status semantics remain as defined by ADR conventions and ADR-0021.

  6. A2C tooling and agents

    A2C workflows (prompts, CLI, AI agents) treat existing Accepted ASRs and ADRs as constraints: generate or refine Specs, Contracts, plans, and code under those constraints, and propose new ADRs when architectural change is required rather than silently editing Accepted requirements or decisions.

Consequences​

Positive​

  • Explicit path from intent to delivery reduces architectural drift
  • Branching Specs/Contracts from ADRs matches real systems (behavior + interfaces)
  • Optional Specs/Contracts keep small or docs-only repos light
  • Clear hand-off to ADR-0021 for amendment semantics

Negative​

  • Authors must maintain cross-references when Specs/Contracts are used
  • Until ADR-0021 is Accepted, amendment vocabulary may still vary across drafts
  • ProductPhase is advisory metadata unless a project defines stricter local rules

References​

Supersedes​

  • (none)

Superseded by​

  • (none)