cc-os/docs/adr-system/00-README.md

# ADR System — Research & Build

_Last updated: 2026-07-03 — plugin BUILT (OpenSpec change `add-os-adr-plugin`, ADR-020); real-project migration/rollout remains, per the order below._

This directory captures research for standardizing how Architecture Decision Records (ADRs)
are organized and used across the user's projects, and the requirements/PRD the **now-built**
`os-adr` plugin was implemented from (`cc-os/plugins/os-adr/`, installed as
`os-adr@local-plugins`; see CLAUDE.md Implemented Components). The docs below remain the design
record; the migration pilot passed 2026-07-03 (flag rates: viking 0%, delta-refinery 0%,
llf-schema 8.3% vs. a 25% gate).

- **`01-current-state-survey.md`** — audit of every project under `~/dev/`, `~/clients/`, and
  `~/projects/` for existing ADR practices (organization, templates, tooling, or absence
  thereof).
- **`02-external-research.md`** — research on ADR best practices generally (Nygard, MADR,
  Y-Statements, lifecycle/governance) and on how Claude Code / AI-agent users specifically have
  integrated ADRs into their workflow.
- **`03-synthesis-and-opportunities.md`** — synthesis answering the three "how might we" goals
  (know when to create/query, systematize creation for consistency, and query with high
  relevance/low bloat) and naming concrete design options for a future `os-adr` plugin.
- **`04-plugin-requirements.md`** — locked, pre-build requirements: single standardized template
  (no client/tooling-mode split), `docs/adr/` location, the five plugin requirements (mechanical,
  SessionStart existence-check hook, non-destructive migration, unprompted write/retrieval
  effectiveness), eval-as-final-stage sequencing, and OOP/Sandi-Metz/Ruby-or-Python
  implementation style.
- **`05-plugin-prd.md`** — the PRD to hand to `openspec-propose` when ready to build: problem
  statement, goals/non-goals, requirements broken into build phases, the deferred
  unprompted-behavior eval stage, architecture/success criteria. Incorporates a Fable review pass
  (2026-07-03) that sharpened the migration and sequencing sections.
- **`06-eval-scenarios.md`** — held-out eval scenario *sketches* (write-trigger W1–W3, retrieval
  R1–R4) written before the plugin skeleton froze; the evaluation itself remains a deferred,
  separate stage per `04-plugin-requirements.md`.

Provenance note: `02-external-research.md` cites web sources gathered by research agents in a
single pass; several specific tool/repo names and one incident anecdote are flagged inline as
**[unverified]** because they were not independently checked against the primary source in this
pass. Verify before depending on any specific tool name in that file.

## Build/rollout order (decided 2026-07-03)

1. **Build the `os-adr` plugin first**, against a clean/small pilot — not against cc-os's own
   19-ADR file. cc-os's `docs/memory-system/03-architecture-decisions.md` is known to need
   splitting into one-file-per-decision (per the ~30-decision monolithic-file ceiling noted in
   `02-external-research.md`), but that split is **deliberately deferred**, not forgotten — it
   happens *using* the plugin once built, not by hand beforehand.
2. **Then use the plugin to retrofit**: cc-os itself first, then other Claude Code projects on
   this machine (per the `~/dev/`/`~/clients/`/`~/projects/` survey in `01-current-state-survey.md`),
   then any new project encountered going forward — one at a time, matching the
   build-first/migrate-incrementally precedent already set for the vault (ADR-013).

Do not re-litigate this ordering in a future session — build the tool, then use the tool to fix
the mess the tool was built to fix.