From 84ca8b441c9e8c71a704078ce8f84844effd0a54 Mon Sep 17 00:00:00 2001
From: Michael Hoennig <michael@hoennig.de>
Date: Tue, 9 Jun 2026 14:31:35 +0200
Subject: [PATCH] add adr-status + direnv

---
 .envrc                                      |  1 +
 README.md                                   | 60 ++++++++++++++++++++-
 docs/adrs/0000-00-00.adr-template.md        |  2 +
 docs/adrs/0001-2026-06-09.test-framework.md |  2 +
 tools/adr-status                            |  5 ++
 5 files changed, 68 insertions(+), 2 deletions(-)
 create mode 100644 .envrc
 create mode 100755 tools/adr-status

diff --git a/.envrc b/.envrc
new file mode 100644
index 0000000..ae4ff57
--- /dev/null
+++ b/.envrc
@@ -0,0 +1 @@
+export PATH="$PWD/tools:$PATH"
diff --git a/README.md b/README.md
index 5c5b873..21a5ef9 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,58 @@
-# gittally
-Lightweight, declarative and highly opinionated software build system (CI/CI).
+# GitTally
+
+Lightweight, declarative and highly opinionated software build system (CI/CD).
+
+## Developer Setup
+
+Source `.envrc` to add `tools/` to your `PATH`, or install [direnv](#direnv) to have this done automatically on `cd`:
+
+```bash
+source .envrc
+```
+
+Common tasks:
+
+```bash
+./gradlew build          # compile and run all checks
+./gradlew test           # run tests
+./gradlew ktlintFormat   # auto-format Kotlin sources
+./gradlew ktlintCheck    # check formatting (also runs as part of build)
+
+adr-status               # show all architecture decisions at a glance
+```
+
+
+
+### direnv
+
+[direnv](https://direnv.net/) sources `.envrc` automatically whenever you enter the repository and unloads it when you leave.
+
+```bash
+# Ubuntu
+sudo apt install direnv
+
+# add to ~/.bashrc or ~/.zshrc
+eval "$(direnv hook bash)"   # or: eval "$(direnv hook zsh)"
+```
+
+Trust the project's `.envrc` once per clone:
+
+```bash
+direnv allow
+```
+
+### Tools (`tools/`)
+
+| Command | Description |
+|---|---|
+| `adr-status` | List all Architecture Decision Records with their status and decision summary |
+
+## Architecture Decision Records
+
+Major technical decisions are documented as ADRs in [`docs/adrs/`](docs/adrs/).
+
+```bash
+adr-status   # show all decisions at a glance
+```
+
+New ADRs follow the template at [`docs/adrs/0000-00-00.adr-template.md`](docs/adrs/0000-00-00.adr-template.md).
diff --git a/docs/adrs/0000-00-00.adr-template.md b/docs/adrs/0000-00-00.adr-template.md
index c3299e0..9d43b46 100644
--- a/docs/adrs/0000-00-00.adr-template.md
+++ b/docs/adrs/0000-00-00.adr-template.md
@@ -6,6 +6,8 @@
 - rejected: -
 - superseded: -
 
+**Decision [proposed]:** CHOSEN-OPTION — one-line rationale.
+
 ## Context and Problem Statement
 
 A short description, why and under which circumstances this decision had to be made.
diff --git a/docs/adrs/0001-2026-06-09.test-framework.md b/docs/adrs/0001-2026-06-09.test-framework.md
index 6203e0c..27e8848 100644
--- a/docs/adrs/0001-2026-06-09.test-framework.md
+++ b/docs/adrs/0001-2026-06-09.test-framework.md
@@ -6,6 +6,8 @@
 - rejected: -
 - superseded: -
 
+**Decision [accepted]:** Kotest — Kotlin-native test runner with richer DSL than JUnit 5; paired with MockK, WireMock, and Testcontainers.
+
 ## Context and Problem Statement
 
 GitTally is a greenfield Kotlin/Spring Boot project.
diff --git a/tools/adr-status b/tools/adr-status
new file mode 100755
index 0000000..88a02ef
--- /dev/null
+++ b/tools/adr-status
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+root=$(git rev-parse --show-toplevel 2>/dev/null) || { echo "Not in a git repo"; exit 1; }
+grep -F '**Decision ' "$root"/docs/adrs/* \
+    | sed "s|$root/docs/adrs/||; s/:/\t/; s/\*\*Decision //; s/:\*\*//" \
+    | column -t -s $'\t'