cc-os/docs/adr-system/04-plugin-requirements.md

Plugin Requirements (locked, pre-build)

Last updated: 2026-07-03

Captured from the requirements-gathering conversation following the research phase (00-README.md–03-synthesis-and-opportunities.md). These are decided; do not re-litigate them in a future session without a new discussion that explicitly revisits one.

Template decision

One standardized template for every project, no client/tooling-mode split. Superseding the "two modes" option floated in 03-synthesis-and-opportunities.md — that split was an artifact of projects independently improvising with no shared plugin, not a real requirement. The user is not a solo operator but works with a team of AI agents across every project; those agents need to discover and write ADRs consistently, which a single template serves better than per-project variants ever could.

• Customized Nygard: Status · Context · Decision · Consequences + Alternatives rejected as a first-class section (highest-value-per-word field per 02-external-research.md).
• Frontmatter: supersedes: / superseded-by:, affected-paths:/affected-components: (for deterministic retrieval), date, sequential ID.
• MADR's RACI fields (Deciders/Consulted/Informed) explicitly rejected — no project run by this user has the team-coordination problem those fields solve.
• One-file-per-decision + a mechanically-maintained index, always — including for small/client projects. A monolithic single-file log is rejected outright for every project, not just large ones: even a small client project's decisions log will bloat over time, and per-file+index costs nothing extra at low decision counts (an index with 2 rows is fine).

Location

docs/adr/, not a root-level adr/. Matches the actual industry convention (Nygard, adr-tools, MADR, Log4brains, Backstage all default to doc/adr//docs/adr/) and matches every one of this user's own surveyed projects that already nests decision docs under docs/. Riding the well-known convention matters here specifically because one goal is agent discoverability without the plugin's help.

Five requirements for the os-adr plugin

1. As mechanical as possible. Deterministic scripts/parsing/index maintenance; reserve LLM calls for genuine judgment (classification, ambiguous field-mapping during migration, "is this ADR-worthy" nudges). Same shape as the os-doc-hygiene plugin's deterministic scanner + generative-only-where-needed split.
2. SessionStart hook, existence-check only. Deterministically checks whether the ADR system already exists in the current project (path + index file check, no LLM). If present: inject the smallest possible context note that the ADR system exists and is usable, plus how to use it — no bloat. If absent: notify the user and suggest setting it up. Same shape as os-doc-hygiene's zero-token SessionStart reminder.
3. Non-destructive migration, dual-existence until explicit go-ahead. Build the new system fresh, then convert every existing ADR (whatever shape/project it's in) into the new template — best-guess fill-in for missing expected attributes, flagged where the guess is uncertain. The old system stays in place, untouched, until the user explicitly approves deleting it. Matches the build-first/migrate-incrementally precedent already set for the vault (ADR-013).
4. Effective at writing — unprompted trigger recognition. The AI should recognize on its own, without being told directly, when a decision in progress warrants writing a new ADR.
5. Effective at retrieval — unprompted, correct surfacing. The AI should recognize on its own, without being told directly, when an existing ADR is relevant to a task or question in progress (including cases where the right move is "stop, this conflicts with a locked decision, adjust the approach") — and retrieve the correct one, not merely a plausible one.

Sequencing: eval is a distinct final stage, not folded into the build

Requirements 4 and 5 are an evaluation methodology, not a build task, and happen after the plugin is built and the design is believed sound — not concurrently with initial design. Sequence:

1. Build the plugin (template, hooks, migration tooling) against the requirements above.
2. Only once there's a working, believed-correct design: design held-out test scenarios — prompts/tasks that are relevant to a written ADR but never name it or the exact constraint directly — and check whether the AI (a) consults the ADR system unprompted at all, and (b) retrieves the specific correct ADR, not just a plausible-looking one.
3. This eval stage uses the autoresearch skill (modify → verify → keep/discard against a metric) to iterate on retrieval/trigger heuristics against that held-out test set.

Do not attempt to validate retrieval/write-trigger effectiveness informally during initial build — it needs the dedicated held-out-scenario methodology above to mean anything.

Implementation style

• Object-oriented, following Sandi Metz's approach to OOP (small classes/methods, single responsibility, dependency injection over reaching for globals, tell-don't-ask, duck typing over type-checking) — the user's standing preference, ruby-and-sandi-metz-oop-preference.
• Language: Ruby preferred; Python acceptable where it's the more native fit for Claude Code tooling (e.g. hook scripts invoked directly by settings.json, matching the existing os-vault/os-doc-hygiene hook pattern in this repo, which are Python). Decide per-component, not globally — a hook entry point can be a thin Python script that still delegates to an OO-designed core, in either language, if that core is more naturally Ruby.