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 configured docs/aar/ directories, promote to ADRs under each paired docs/adr/ADR-XXXX-*.md, update each 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

• operation (optional, default reconcile): reconcile updates an existing ADR before creating a new one, consolidate backfills ownership and merges judged duplicates, and index deterministically regenerates indexes without an LLM key
• require_ownership (optional, default false): reject missing ownership/domain metadata and catalog conflicts
• publish_mode (optional, default pull-request): pull-request opens a bot PR, direct commits an index result to the base branch, and none only validates/generates in the workspace
• openai_api_key (required for reconcile and consolidate with OpenAI): OpenAI API key
• openai_model (optional, default gpt-5.1): model name
• github_token (required): token to open a PR or directly push an index (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)
• reviewers (optional): comma or newline separated GitHub usernames to request as PR reviewers
• docs_dirs (optional, default docs): comma or newline separated docs directories to process. Each directory must contain aar/ and adr/
• add_paths (optional, default docs/**): paths passed to create-pull-request add-paths
• language (optional, default en): ADR output language (not stored in front matter; applies to generated text)

Permissions

permissions:
  contents: write
  pull-requests: 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@v2.0.0
        with:
          operation: reconcile
          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.
          reviewers: JuHyung-Son
          docs_dirs: |
            apps/backend/docs
            apps/frontend/docs
          add_paths: |
            apps/**/docs/adr/**
            apps/**/docs/aar/**

Flow

1. reconcile: compare each AAR with a bounded existing-ADR shortlist and choose covered, amend, create, reject, or defer
2. consolidate: backfill owns/contracts/applies_to, judge exact ownership collisions, and move merged duplicates under docs/adr/superseded/
3. index: rebuild schema-v2 index.json from active ADR front matter without an LLM key
4. Open a reviewable PR with changed paths; the action never merges its own PR

Environment

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

Caution

• defer keeps the AAR. covered, amend, create, and reject remove it only in the generated PR.

ADR output (agent-friendly)

• Front matter (YAML between ---): existing v1 fields plus owns, contracts, applies_to, and typed relations. Top-level related remains readable during v2 migration.
• Index: deterministic schema v2 with schema_version, source_hash, ownership/contract/relation/rule metadata. Set require_ownership: true after backfill to reject missing ownership, invalid domains, broken relations, and duplicate producers.
• Body: ## Context (for humans) with the same context text (minimal human-readable section)

Running the Action with Amazon Bedrock

Set llm_provider: bedrock to invoke OpenAI models through the Bedrock runtime Responses API. Existing openai (default) and direct claude providers are unchanged.

• bedrock_model: required runtime inference profile ID, for example global.openai.gpt-5.6-terra. This provider uses the OpenAI Responses API, not the Anthropic Messages API; Claude models are not supported by this provider.
• bedrock_reasoning_effort: defaults to medium.
• aws_region: explicit region; otherwise AWS_REGION, then AWS_DEFAULT_REGION.
• Authentication uses SigV4 and the AWS SDK credential chain, including runner roles or temporary credentials from GitHub OIDC. No OpenAI/Anthropic API key is needed. The Action does not assume a role itself.
• The caller needs bedrock:InvokeModel for the selected inference profile, underlying models, and the account's default Bedrock project. Check model access and regional availability before deploying.
• global.* profiles can process requests across commercial AWS Regions; use an appropriate geographic profile when data residency constraints apply.
• Responses use store: false; repository content is not persisted as Responses conversation state. Provider errors do not fall back to another provider.
• operation: index remains deterministic and requires no LLM credentials.

After configuring AWS credentials in the caller job:

- uses: p2achAI/adr-agent@v2.1.0
  with:
    operation: reconcile
    llm_provider: bedrock
    bedrock_model: global.openai.gpt-5.6-terra
    bedrock_reasoning_effort: medium
    aws_region: ap-northeast-2
    github_token: ${{ secrets.RW_TOKEN }}

AWS authentication and GitHub PR permissions are separate. For OIDC, restrict role trust to the intended repository and branch or GitHub environment.