# Proposal: add-os-adr-plugin

## Why

~43% of the user's projects carry ADR-like content in 5+ mutually-incompatible shapes; the rest
have none, and no project uses ADR tooling. Because AI agents (not just the user) work across
every project, decision records must be discoverable and writable *consistently* by an agent
that has never seen a given repo — and cc-os's own 19-ADR/601-line monolithic file is already
near the size where research says monolithic logs stop working. The requirements are locked
(`docs/adr-system/04-plugin-requirements.md`) and the PRD is written
(`docs/adr-system/05-plugin-prd.md`); this change builds the plugin.

## What Changes

- New global Claude Code plugin **`os-adr`** at `cc-os/plugins/os-adr/`, following the
  established cc-os plugin conventions: `os-` prefix, verb-first skills, no `commands/`
  dispatcher, symlink into `~/.claude/plugins/`, registered in the `local-plugins` marketplace
  manifest (the three-place rename/registration procedure in CLAUDE.md).
- **Phase 1 — authoring**: customized-Nygard template (Status/Context/Decision/Consequences +
  Alternatives rejected; frontmatter with `supersedes`/`superseded-by`,
  `affected-paths`/`affected-components`, `date`, sequential ID), `docs/adr/NNNN-title.md`
  one-file-per-decision convention, mechanically-maintained index file, and a `new` skill that
  writes a correctly templated + indexed ADR in one invocation. No LLM in the mechanical path.
- **Phase 2 — SessionStart hook**: deterministic existence check for `docs/adr/` + index. Present
  → near-zero-token context note; absent → suggest setup, with a per-project suppression flag so
  a deliberately ADR-less project doesn't re-nag (same shape as `os-doc-hygiene` snooze state).
- **Phase 3 — non-destructive migration**: a `migrate` skill converting existing ADR content of
  any surveyed shape into the new template alongside (never replacing) the old system; heuristic
  fill for structurally unambiguous fields, LLM fill only for interpretive fields, one consistent
  uncertainty-flagging mechanism (`migration_confidence` frontmatter + a migration report file);
  deletion of the old system only as an explicit, separate user-approved step. Piloted on 2–3
  real projects with an uncertain-flag-rate gate before wider rollout.
- **Phase 4 — retrieval**: deterministic-first layering — path/component frontmatter match →
  status filter (Accepted by default) → Graphify graph traversal (reusing `os-vault`
  infrastructure) → AI judgment only over the already-narrowed candidate set. Exposed as a query
  surface callable mid-task, not just at SessionStart.
- Implementation style: OO per Sandi Metz principles; Ruby-preferred core with Python acceptable
  for hook entry points, decided per-component (thin hook scripts wrapping an OO core).
- Held-out eval scenarios (write-trigger, retrieval) are **sketched** as part of this change so
  the plugin surface isn't missing what the eval needs — but the evaluation itself stays a
  separate later stage (locked sequencing in `04-plugin-requirements.md`).

## Capabilities

### New Capabilities

- `adr-authoring`: the ADR template, `docs/adr/NNNN-title.md` + index location convention, and
  the one-invocation new-ADR generator skill with mechanical index maintenance.
- `adr-session-awareness`: the deterministic SessionStart existence-check hook — minimal context
  injection when the ADR system exists, setup suggestion with per-project suppression when it
  doesn't.
- `adr-migration`: non-destructive conversion of existing ADR content (all surveyed shapes plus
  a fallback) into the new template, with the mechanical/LLM field-mapping boundary, single
  uncertainty-flagging mechanism, and pilot gate.
- `adr-retrieval`: the deterministic-first retrieval stack (frontmatter path match → status
  filter → Graphify traversal → narrowed AI judgment) exposed as a mid-task query surface.
- `adr-plugin-packaging`: plugin structure, naming, marketplace registration, and install
  procedure per cc-os conventions (`os-` prefix, verb-first skills, symlink + `local-plugins`
  manifest + `settings.json` enablement).

### Modified Capabilities

<!-- none — os-adr is a new plugin; no existing spec's requirements change -->

## Impact

- New code: `cc-os/plugins/os-adr/` (hooks, skills, OO core, template assets, tests/fixtures).
- Host config: `~/.claude/plugins/os-adr` symlink, `~/.claude/plugins/.claude-plugin/marketplace.json`
  entry, `settings.json` `enabledPlugins` (and hook wiring if hooks are registered by absolute
  path like os-vault, or via plugin `hooks.json` like os-doc-hygiene — decided in design).
- Reuses: Graphify / `os-vault` graph infrastructure for the retrieval layer; `os-doc-hygiene`
  patterns for deterministic SessionStart reminders and snooze state.
- Target projects (pilot, later phases): viking-warrior-training-log, delta-refinery, llf-schema;
  cc-os itself is retrofitted only after the pilot, per the locked rollout order.
- Out of scope: per-project template variants, multi-editor governance, enforceable-constraints
  mirroring, the unprompted-behavior evaluation itself, and retrofitting cc-os's ADR file.