| name | langertha-adr |
| description | How Langertha records Architecture Decision Records: the house docs/adr/ format, what counts as ADR-worthy in an LLM-engine framework, and the structure-first method for backfilling decisions already baked into the engine/role/value-object mesh. |
| user-invocable | false |
| allowed-tools | Read, Grep, Glob, Bash |
| model | sonnet |
ADRs capture the WHY behind architecturally-significant Langertha decisions, so the
rationale survives refactors, releases and the next person who is tempted to "simplify" a seam
back into the engines. Read the existing docs/adr/ entries as the canonical examples —
codify the format, do not reinvent it.
Format
- File:
docs/adr/NNNN-kebab-title.md — NNNN zero-padded 4 digits, monotonic per repo
- H1:
# ADR NNNN — Title (em-dash)
- Metadata as a bullet list, directly under H1:
- Status: proposed | accepted | superseded | deprecated- Date: YYYY-MM-DD- Tags: a, b, c (optional)
- Sections (
##): Context · Decision · Rationale (optional — may fold into Decision) · Consequences
- Optional last section:
## Future work — drift to reconcile or follow-ups that should not
block; name the karr ticket and stop. Don't do that work in the ADR.
What counts as ADR-worthy
Two sorts, both count:
- Deliberate centralization / seam — a decision to route many engines through one place:
the
tool_wire_format tag and the Tool/ToolCall/ToolResult/ToolChoice value objects; the
%ROLE_TO_CAPS capability registry; Response.tool_calls as the single tool-call shape;
the chat_f auto-rewrite matrix; the TranscriptionBase split; the Raider history model.
- Deliberate keep — structure a review tempted us to change and we chose not to (e.g.
keeping a per-format branch explicit rather than over-abstracting it).
Architecturally significant = touches the public API, engine/role composition, the tool
wire-translation seam, capabilities, structured-output handling, streaming, async, or the
Raider loop. Not ADR-worthy: local style, naming, single-use code.
Where ADRs come from — backfill, structure first
Langertha is not a fork, so there is no upstream baseline to diff against. Recover decisions
already living in the structure:
- Structure first — walk the
Langertha:: namespaces: what is centralized, what each
base class / role owns, which seam every engine routes through.
- Code is the ground truth — read the actual dispatch (
Role::Tools, Role::Capabilities,
the value objects). Public method names matter: cite them exactly.
CONTEXT.md is the distilled vocabulary of the tools-lane discussion — the strongest
single record of intent for that area. Hold it against the code; where they disagree, that
drift is a finding (record it, or file a karr reconciliation ticket).- Git history — the refactor commits and their messages confirm the WHY.
- To judge significance, load the architecture skill on demand — [[perl-ai-langertha]].
Two run modes
- audit-only — report which significant decisions lack an ADR (a gap list); file gaps as
karr tickets. Write no files. Good for a gentle first pass and recurring drift checks.
- audit+write — the same survey, then write the missing ADRs in the format above.
Numbering
Per repo, monotonic from 0001. Read the existing docs/adr/ for the highest number; never reuse.
Companion
CONTEXT.md is the domain language (ubiquitous terms), not a decision log — ADRs link to it,
they don't restate it. Langertha architecture vocabulary → [[perl-ai-langertha]].
