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.