ADR 2.0 — Core Concepts

ADR 2.0 is a modern evolution of Architecture Decision Records designed for AI-assisted software development. It extends traditional ADRs by introducing automation, agent integration, and machine-verifiable rules, enabling teams to maintain architectural consistency with minimal manual effort.

---

1. Purpose

ADR 2.0 preserves architectural decisions in a way that:

• aligns with modern AI-assisted workflows,
• reduces documentation overhead,
• increases architectural integrity through continuous validation,
• and integrates seamlessly into repository-local development.

---

2. Document Types

2.1 AAR (Agent Analysis Record)

AARs are natural-language design reasoning files generated by AI agents or developers.

Characteristics:

• High-level conceptual reasoning
• Explains why a change was made
• Does not include code or diffs
• Stored only under docs/aar/
• Serves as raw material for ADR creation

---

2.2 ADR (Architecture Decision Record)

A formal, machine-readable decision document.

Characteristics:

• Stored only in docs/adr/
• Created automatically from AARs
• Reviewed through PRs
• Defines long-term architectural constraints
• Contains Validation Rules that CI can enforce

---

3. ADR 2.0 Structure

# Title
# Context
Background, problem, constraints.

# Decision
The architectural decision made.

# Rationale
Why this decision was chosen (trade-offs & reasoning).

# Alternatives Considered
Options evaluated and why they were rejected.

# Consequences
Positive/negative outcomes of the decision.

# Validation Rules
Declarative technical constraints for CI enforcement.

# Agent Playbook
Imperative steps for agents: enforce, detect drift, remediate.

# Agent Signals
- Importance: high | medium | low
- Enforcement: must | should | monitor

---

4. Workflows in ADR 2.0

4.1 AAR Creation

AI agent hooks capture reasoning during development sessions and store AARs automatically.

4.2 ADR Promotion

CI or an automated agent determines whether an AAR includes an architectural decision and generates an ADR draft.

4.3 Human Review

Engineers review the generated ADR via PR, ensuring accuracy and team alignment.

4.4 Continuous Enforcement

ADR Validation Rules are enforced on every PR, preventing architectural drift.

---

5. Benefits of ADR 2.0

• Reduces the need for manual documentation
• Captures implicit agent reasoning
• Ensures architecture remains consistent over time
• Prevents violations through automated validation
• Works independently in each repository
• Reflects real-world design decisions made collaboratively with AI

---

6. Philosophy

ADR 2.0 accepts that:

• Most modern design reasoning originates from AI-assisted workflows.
• Architectural decisions must be captured with minimal friction.
• Documentation should flow naturally from development, not the other way around.
• Architecture governance must be automated to remain relevant.

ADR 2.0 is the natural evolution of architecture documentation in an AI-native development environment.

---

GitHub Action (Marketplace)

Summary

• Name: ADR 2.0 Agent Promotion
• Purpose: detect AARs under docs/aar/, promote to ADRs under docs/adr/ADR-XXXX-*.md, update docs/adr/index.json, and clean up processed AARs
• Features: agent-friendly template (Agent Playbook, Agent Signals, Validation Rules), slim index, progress logs, automatic AAR cleanup

Inputs

• openai_api_key (required): OpenAI API key
• openai_model (optional, default gpt-5.1): model name
• github_token (required): token to open PR (PAT with repo write/PR write recommended; GITHUB_TOKEN may be insufficient in some orgs)
• pr_branch (optional, default adr/auto-update): branch for ADR PR
• pr_title (optional, default chore: ADR auto-update): PR title/commit message
• pr_body (optional): PR body
• pr_base (optional): base branch (defaults to repo default)
• language (optional, default en): ADR output language (not stored in front matter; applies to generated text)

Permissions

permissions:
  contents: write

Example workflow (.github/workflows/adr.yaml)

Note: this repository only provides the Action for Marketplace. Workflows should be added in the consumer repository.

name: ADR 2.0 Agent Promotion
on:
  workflow_dispatch:
  push:
    paths:
      - "docs/aar/**"

permissions:
  contents: write

jobs:
  adr:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: p2achAI/adr-agent@v1  # pin tag/commit
        with:
          openai_api_key: ${{ secrets.OPENAI_API_KEY }}
          openai_model: gpt-5.1
          pr_branch: adr/auto-${{ github.run_id }}
          pr_title: chore: ADR auto-update (#${{ github.run_number }})
          pr_body: Automated ADR updates generated from AARs.

Flow

1. Scan docs/aar/ → detect candidates
2. Generate ADRs (docs/adr/ADR-XXXX-<slug>.md with front matter id/scope/created_at/updated_at/decision/context/rationale/alternatives/consequences/related/validation_rules/agent_playbook/agent_signals/index_terms)
3. Update slim docs/adr/index.json (with decision_summary)
4. Delete promoted AARs and non-candidates
5. Open PR with the ADR/cleanup changes (skipped if no changes)
6. ADR content generated in the selected language (front matter only; no duplicated markdown body)

Environment

• ADR2_REPO_ROOT is auto-set to github.workspace so the action runs against the calling repo.

Caution

• AAR source files under docs/aar/ are deleted after processing; back them up elsewhere if you need to keep originals.

ADR output (agent-friendly)

• Front matter (YAML between ---): id, scope, created_at, updated_at, decision, context, rationale, alternatives, consequences, related, validation_rules, agent_playbook, agent_signals(importance/enforcement), index_terms
• Body: ## Context (for humans) with the same context text (minimal human-readable section)