Skip to content

Architecture Decision Records

Significant design decisions are captured as Architecture Decision Records (ADRs) in docs/adr/. Each ADR records the context, the decision, and the consequences so future contributors can understand why the project is shaped the way it is. This page is the single canonical index.

Index

The Status column uses one vocabulary — Accepted, Superseded by NNNN, Deprecated, or an amendment relationship (Amended by NNNN / Amends NNNN).

ADR Title Status
0001 Alpine Linux as Base Image Accepted
0002 mise for Runtime Version Management Amended by 0014
0003 Chef Tools Installed as Ruby Gems Accepted
0004 Checkov over tfsec for IaC Scanning Accepted
0005 Colima SSH Agent Forwarding Chain Accepted
0006 Reusable Image Architecture Accepted
0007 Rootless Podman Replaces Docker-Outside-of-Docker Accepted
0008 In-Image Binaries for All Pre-Commit Hooks Accepted
0009 In-Container Proxy, MITM, and Monitor Services Accepted
0010 Semantic Versioning and Tag-Driven Releases Accepted
0011 CI/CD via GitHub Actions, Docker Hub Registry, Self-Hosted Daily Renovate Amended by 0012
0012 Native arm64 Release Builds on Hosted arm64 Runners Amends 0011
0013 OpenTelemetry for Claude Code Accepted
0014 Do Not Volume-Mount the mise Runtime Directory Amends 0002
0015 Inject the Image Version at Scaffold Time Accepted
0016 Headless Browser for HTML Testing Accepted
0017 PowerShell and Microsoft Graph Modules (amd64-only) Accepted

Writing a new ADR

When making an architecturally significant change (new tool, base image change, security policy change, egress model change), create a new ADR rather than burying the rationale in a commit message.

  1. Create docs/adr/NNNN-short-title.md using the next sequential number, with the template below. Use the NNNN. Title heading style and the four standard sections.
  2. Fill in all four sections.
  3. Add a row to the index table above with the matching title and status.
  4. If the new ADR supersedes or amends an existing one, update both the new ADR's Status and the existing ADR's Status so the relationship is visible from the index.
  5. Reference the ADR in CHANGELOG.md [Unreleased] and in the relevant code comment or README section.

Template

# NNNN. Title

## Status

Accepted | Superseded by NNNN | Deprecated | Amends NNNN | Amended by NNNN

## Context

What is the issue that we are seeing that is motivating this decision or change?

## Decision

What is the change that we are proposing and/or doing?

## Consequences

What becomes easier or more difficult to do because of this change?