adr
- Repo stars 2
- Author repo anton
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @wcygan · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# ADR
Anton-local skill for the architectural decision record lifecycle. Owns three workflows: **new**, **list**, **supersede**. ADRs live at `context/adrs/NNNN-kebab-slug.md` and are immutable — once accepted, the body never changes. Supersession is the only way to revise a decision.
## Why this skill exists
Anton needs **one durable home** for architectural decisions so that:
- `cluster-intake-gatekeeper` has somewhere to hand off its ADD/DEFER/REJECT verdicts (instead of stopping at "ADR-ready").
- Future Codex sessions can discover prior decisions automatically via the SessionStart hook (`.Codex/hooks/inject_adr_index.py`) without the operator typing them in.
- `cluster-intake` Step 2 can query past `Reverted` decisions by category instead of grepping a single shared file.
- The operator (and future-Will) can recover *why* the cluster looks the way it does without mining `git log`.
The skill is anton-local and has **no runtime dependency** on `~/.Codex/skills/context-repo-adr` — the format is intentionally compatible with the global context-repo conventions, but invoking this skill never delegates to that one.
## Hard rules
- **ADRs are immutable.** Once an ADR's `status:` is `Accepted` (or `Reverted` / `Rejected` / `Deferred`), the body never changes. The *only* edit allowed on an existing ADR is flipping the `status:` line to `Superseded-by NNNN`. Any other change must go through `supersede`.
- **Numbers are never reused.** The next number is always `max(existing) + 1`, zero-padded to four digits, regardless of whether earlier numbers were superseded.
- **`Status: Reverted`** is anton-specific. Use it for any decision that was once live and is now removed. Standard MADR has no equivalent.
References:
- Field reference and immutability rule → [conventions](references/conventions.md)
- Canonical template for new ADRs → [template](references/template.md)
## Workflow — `new`
Triggered by:
- The user says "create an ADR" / "record this decision" / `/adr new "<title>"`
- `cluster-intake-gatekeeper` hands off an ADD / DEFER / REJECT verdict (the verdict object substitutes for the interactive interview — see "Handoff from intake" below)
### Steps
1. **Allocate the next number.** `Glob('context/adrs/0[0-9][0-9][0-9]-*.md')`. Sort. The next number is `max + 1`, zero-padded to 4 digits. Never reuse a number.
2. **Generate the slug.** Lowercase the title, kebab-case it, drop articles and prepositions, take the first 4–6 meaningful words. Example: "Adopt Cilium over Calico for CNI" → `adopt-cilium-over-calico-for-cni` → file `0018-adopt-cilium-over-calico-for-cni.md`.
3. **Interview the user** (skip this when invoked from intake — see Handoff from intake). Ask only the questions whose answers aren't already known:
- Title (one short sentence)
- One-sentence summary (the blockquote after the H1)
- `status` — usually `Accepted` for forward-looking decisions; `Deferred` / `Rejected` / `Reverted` if known
- `affects` — pick the broadest applicable category from: `storage`, `observability`, `databases`, `registries`, `demos`, `networking`, `security`, `compute`, `all`, or a new category if none fit
- `intent` — `concrete-need` / `learning` / `unknown`
- `supersedes` — list of NNNNs being superseded by this one (usually empty)
- **Context** (1–3 paragraphs — what situation prompts this decision, what forces are in play)
- **Decision** (active voice, one or two sentences — "We will adopt X" / "We will not")
- **Alternatives considered** (do-nothing + 1–2 alternatives, with a one-line "why rejected" each)
- **Consequences** — accepted costs, lessons (if `Reverted`), follow-ups
4. **Write the ADR file** at `context/adrs/NNNN-slug.md` using the shape from [template](references/template.md). Frontmatter is mandatory; missing frontmatter fields default to the template's defaults.
5. **If `supersedes:` is non-empty**, also flip the `status:` line of each superseded ADR to `Superseded-by NNNN`. This is the *only* allowed in-place edit on an existing ADR. Use `Edit` with a precise old/new string for the status line only — never touch the body.
6. **Confirm to the user** with the file path and the new ADR number.
### Handoff from intake
When `cluster-intake-gatekeeper` invokes this skill at the end of its evaluation, it passes the verdict object directly. Map the verdict to ADR fields without re-interviewing:
| Gatekeeper verdict | ADR `status:` | Notes |
|---|---|---|
| Add (concrete need) | `Accepted` | `intent: concrete-need`. Decision section names the hand-off skill (`add-flux-app` / `flux-app-author`). Consequences section includes the Renovate-PR tax line. |
| Add (learning) | `Accepted` | `intent: learning`. Consequences section *must* include the timebox, exit plan, and review date — these are load-bearing under the contained-learning rubric. The frontmatter should add a `review-by:` field with the review date. |
| Defer | `Deferred` | Body holds the exact measurable unblock conditions (what would have to be true to convert to Accepted). |
| Reject | `Rejected` | Body holds the failed gate (1–7) or known-bad pattern, and — if appropriate — whether reframing as a learning intake would change the answer. |
After writing the ADR, return to the gatekeeper with the ADR number so it can include it in its memory append.
## Workflow — `list`
Triggered by:
- `/adr list` or `/adr list --status Reverted` or `/adr list --affects databases`
- `cluster-intake` Step 2 (the removal-detection lookup) — internally invokes this with `--status Reverted --affects <candidate-category>` to find prior reverts
### Steps
1. `Glob('context/adrs/0[0-9][0-9][0-9]-*.md')`.
2. For each file, read the frontmatter and extract `status`, `date`, `affects`, `intent`, and the H1 title.
3. Apply filters:
- `--status <X>` → keep only ADRs whose `status:` matches `X` (case-insensitive)
- `--affects <X>` → keep only ADRs whose `affects:` contains `X`
- With no filter, return all
4. Format as a markdown table sorted by NNNN (columns: #, Title, Status, Date, Affects, Intent).
5. If used as the data source for `cluster-intake` Step 2: also read the matching ADRs' "Re-adoption guidance" section so the intake can surface the conditions under which a re-attempt would be valid.
## Workflow — `supersede`
Triggered by:
- `/adr supersede <NNNN> "<reason>"` — the user wants to revise an existing decision
### Steps
1. **Verify the target exists.** `Read` `context/adrs/NNNN-*.md`. If missing, abort with a clear error.
2. **Verify the target's current status.** If it is already `Superseded-by NNNN`, abort — supersession chains exist (NNNN can be superseded by MMMM which is superseded by PPPP), so the user must supersede the *latest* in the chain.
3. **Author the replacement** by invoking the `new` workflow with `supersedes: [<NNNN>]` pre-populated. Walk the interview as normal.
4. **Flip the old ADR's status line** — and *only* the status line — from `Accepted` (or whatever it was) to `Superseded-by <new NNNN>`. Use `Edit` with the precise old/new strings. Do not touch the body, the date, or any other field.
5. **Confirm to the user** with both ADR numbers (old → new) and the file paths.
## What this skill does NOT do
- Does not write Flux manifests — that is `add-flux-app`.
- Does not run cluster intake — that is `cluster-intake` (which hands off here).
- Does not edit ADR bodies after the fact. Ever. Use `supersede`.
- Does not auto-detect when a decision should be superseded. Manual via `/adr supersede`.
- Does not push, commit, or tag — the user owns git operations.
- Does not delete ADRs. ADRs are append-only forever, even superseded ones.
## Related skills and agents
- `cluster-intake` / `cluster-intake-gatekeeper` — the dominant authoring path. Hand off here on every verdict.
- `add-flux-app` / `flux-app-author` — invoked *after* an `Accepted` ADR that involves new manifests.
- `~/.Codex/skills/context-repo-adr` (user-level) — format-compatible but not invoked at runtime. If the user adopts the full context-repo convention later, the existing ADRs will Just Work.
## Anti-patterns
- **Editing an ADR body to reflect a changed decision.** That's what `supersede` is for. Editing in place destroys the historical record.
- **Re-using a number after a delete.** ADRs are never deleted, so this shouldn't come up — but if it does, allocate the next number, never the gap.
- **Authoring an ADR before the decision is actually made.** ADRs document decisions that happened, not aspirations. If the user is still considering, they're not ready for an ADR.
- **Verbose ADRs.** One screen of body is the target. If the decision genuinely needs more context, link to a doc — don't inline it.
Sections and files
Listed in source order.
sections -> Why this skill exists → Hard rules → Workflow — new → Steps → Handoff from intake → Workflow — list
terms -> new · list · supersede · one durable home · no runtime dependency · ADRs are immutable. · Numbers are never reused. · Status: Reverted
files/cmd -> context/adrs/NNNN-kebab-slug.md · cluster-intake-gatekeeper · .Codex/hooks/inject_adr_index.py · cluster-intake · Reverted · git log · ~/.Codex/skills/context-repo-adr · status:
body sha256 -> 9f92441e50f2
Why this skill exists
Anton needs one durable home for architectural decisions so that:
cluster-intake-gatekeeperhas somewhere to hand off its ADD/DEFER/REJECT verdicts (instead of stopping at "ADR-ready"). Future Codex sessions can discover prior decisions automatically via the SessionStart hook (.Codex/hooks/inject_adr_index.py) without the operator typing them in.cluster-intakeStep 2 can query pastReverteddecisions by category instead of grepping a single shared file.Hard rules
ADRs are immutable. Once an ADR's
status:isAccepted(orReverted/Rejected/Deferred), the body never changes. The only edit allowed on an existing ADR is flipping thestatus:line toSuperseded-by NNNN. Any other change must go throughsupersede. Numbers are never reused. The next number is alwaysmax(existing) + 1, zero-padded to four digits, regardless of whether earlier numbers were superseded.Workflow — new
Triggered by: The user says "create an ADR" / "record this decision" /
/adr new "<title>"cluster-intake-gatekeeperhands off an ADD / DEFER / REJECT verdict (the verdict object substitutes for the interactive interview — see "Handoff from intake" below)Steps
Allocate the next number.
Glob('context/adrs/0[0-9][0-9][0-9]-*.md'). Sort. The next number ismax + 1, zero-padded to 4 digits. Never reuse a number. Generate the slug. Lowercase the title, kebab-case it, drop articles and prepositions, take the first 4–6 meaningful words. Example: "Adopt Cilium over Calico for CNI" →adopt-cilium-over-calico-for-cni→ file0018-adopt-cilium-over-calico-for-cni.md.Handoff from intake
When
cluster-intake-gatekeeperinvokes this skill at the end of its evaluation, it passes the verdict object directly. Map the verdict to ADR fields without re-interviewing: Gatekeeper verdict · ADRstatus:· Notes Add (concrete need) ·Accepted·intent: concrete-need. Decision section names the hand-off skill (add-flux-app/flux-app-author). Consequences section includes the Renovate-PR tax line.