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

ADR System — Research Phase

Last updated: 2026-07-03

This directory captures research for standardizing how Architecture Decision Records (ADRs) are organized and used across the user's projects, as a precursor to building a Claude Code plugin that automates ADR creation and relevance-scoped retrieval. Nothing here is built yet — this is the survey/research phase only, requested to answer "what do we have, and what could we have with a little engineering elbow grease."

• 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.

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.