Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

AI Agent Guide

This repository is designed for use by AI coding agents (primarily Goose) to assist with architecture decisions and implementation.

Philosophy

This guide aligns with pragmatic engineering principles:

  • The Grug Brained Developer: Prefer simplicity over complexity. “Complexity very bad.” Choose boring technology, avoid over-engineering, and make systems easy to understand and debug.
  • CNCF / Linux Foundation: Preference for open-source, cloud-native technologies with strong community governance. Avoid vendor lock-in where practical.

Getting Started

  1. Review the Architecture Principles - Foundation for all decisions
  2. Browse Reference Architectures - Project kickoff templates combining multiple ADRs
  3. Search ADRs by domain - security/, operations/, development/

Essential Commands

mise tasks
    build  Build the book (just build with tool prereqs for CI)
just --list
    default       # Show all available commands

    [build]
    build         # Build documentation website (includes link checking)
    clean         # Clean generated files

    [development]
    next-number   # Get next ADR number for new files
    serve         # Preview documentation locally (port 8080)

    [quality]
    check-summary # Verify SUMMARY.md includes all markdown files
    lint          # Run all checks and fixes

    [setup]
    setup         # Install required tools and dependencies

Workflow

  1. Get ADR number - just next-number
  2. Create file - Use pattern ###-short-name.md in correct directory
  3. Follow workflow - See CONTRIBUTING.md for complete workflow, templates, and writing guidelines

PDF Generation

  • Build - just build creates both website and PDF at book/pandoc/pdf/architecture-decision-records.pdf
  • Live PDF - Available at architecture-decision-records.pdf
  • Format - A4 ISO standard with D2 diagrams

Troubleshooting

Validation Issues:

  • Run just lint to check all issues

Automated Workflows

  • Website deployment - Automatically builds and deploys to GitHub Pages on push to main
  • PDF generation - Automatically creates and attaches PDFs to GitHub releases
  • Chapter ordering - Files sorted numerically by ADR number

mdBook Project Notes

  • Book Format - Project uses mdBook, navigation defined in SUMMARY.md
  • Manual Updates - Add new ADR files to SUMMARY.md for navigation (required)
  • Diagram Support - Use D2 diagrams in code blocks for universal compatibility

D2 Diagram Guidelines

When to use: System relationships, data flows, workflows, or architecture patterns where text alone isn’t sufficient.

Keep simple: Maximum 5-7 components, clear labels, logical flow, consistent colors.

Example:

Quality check: Adds value, easy to follow, clear labels, logical connections.