Tagout

Architectural Decision Records

When an ADR is warranted. All three must hold: the decision is hard to reverse, it is surprising without context, and it involved a real trade-off. A decision that fails any of the three belongs in the code or in the file it governs, not here. (Ported from mattpocock/skills, domain-modeling/ADR-FORMAT.md, MIT.)

Files are MADR 4.0: NNNN-<kebab-title>.md, YAML frontmatter (id, title, status, date, tags, optional links and code_refs), body sections Context and Problem Statement / Considered Options / Decision Outcome / Consequences. Keep the Decision Outcome to one paragraph. Numbering is the highest existing id + 1 — create_adr does this for you.

Author and amend these through the adr MCP server (create_adr, validate_adr, set_status, supersede_adr, render_index); python3 tests/adr/check-adrs.py is CI’s structural mirror of validate_adr, since a runner cannot start the server. The table below is exactly what render_index emits — re-running it with previewOnly: false rewrites the whole file, so put this preamble back afterwards.

ID Title Status Date
0001 The repo profile is committed data, not a skill accepted 2026-08-31
0002 The roseline gate fails open, always accepted 2026-08-31
0003 One plugin version; no per-skill version accepted 2026-08-31
0004 Squash-only merges: the PR title is the release commit accepted 2026-08-31
0005 The lifecycle skills run hands-off; triage-backlog does not accepted 2026-08-31
0006 The kit targets Claude Code only superseded 2026-08-31
0007 Workers are in-process sub-agents, never claude -p accepted 2026-08-31
0008 Idea-tree search rejected 2026-07-23
0009 Interaction modes rejected 2026-07-23
0010 Novelty search rejected 2026-07-23
0011 Hook gates are recorded rather than registered decisions accepted 2026-08-31
0012 Two skill naming rules: verb-object, and family-role accepted 2026-08-31
0013 profile-repo and setup-repo stay a reader and a writer proposed 2026-09-02
0014 The kit is Claude Code-first and reaches other hosts through thin adapters accepted 2026-09-11
0015 The lifecycle skills reach the tracker through one contract accepted 2026-09-13
0016 Tagout: one tree, two disjoint plugins, one version accepted 2026-09-14
0017 The two plugin trees ship as generated copies accepted 2026-09-15