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.