cc-os/openspec/changes/archive/2026-07-03-add-os-adr-plugin/proposal.md

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

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.