cc-os/plugins/os-adr/CLAUDE.md

os-adr

ADR (architecture decision record) system for cc-os and pilot projects: numbered docs/adr/ files + generated index, migration of legacy decision logs, deterministic find/create/init workflows. Full design/build history: docs/implementation-status/os-adr.md.

Component map

• skills/ — four verbs, each /os-adr:<verb>: create, find, init, migrate.
• lib/adr.rb + lib/adr/{detector,finder,index,migration_report,migrator,record, repository,template}.rb — single Adr namespace, require_relative loading, stdlib-only (no external gems).
• bin/ — per-verb scripts (adr-new, adr-find, adr-init, adr-migrate, adr-detect), invoked as ruby ${CLAUDE_PLUGIN_ROOT}/bin/adr-<verb> from skills. This is not the single-dispatcher pattern ADR-0025 requires of newer plugins — os-adr is explicitly grandfathered (see below).
• templates/adr.md — the ADR template migration and creation write against.
• hooks/hooks.json — SessionStart entry is intentionally empty; the check itself moved to os-status's adr-system-present (hooks/session_start.py here is kept only as the wording source of record).
• tests/ — minitest, ruby tests/all.rb (glob-runs *_test.rb) + test_helper.rb tmpdir fixtures; hook_test.py covers the hooks-parity case.
• invariants.md — reversion-protection contract; read before touching detection, migration, indexing, or find-filtering logic.
• eval/, eval-b/, eval-c/ — Eval A/B/C harnesses (prompted grid, held-out unprompted-behavior, ambiguity-ladder). See docs/implementation-status/os-adr.md for what each measures; eval discipline (reserves never read informally) per root CLAUDE.md.

ADR-0025 exemption

The per-verb bin/ layout (rather than a single bin/os-adr dispatcher) is grandfathered by ADR-0025: the exemption is recorded there explicitly ("not worth a retrofit until os-adr is next touched for other reasons"), not an oversight. Don't "fix" the dispatcher shape as a drive-by — fold it into whatever unrelated work next touches os-adr's bin/.

Pointers

• Decisions: docs/adr/0025-...md (Ruby structure), docs/adr/0020 and its amendment (cc-os retrofit).
• Status/build history: docs/implementation-status/os-adr.md.