53 lines
3.6 KiB
Markdown
53 lines
3.6 KiB
Markdown
# 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.
|