cc-os/docs/adr-system/05-plugin-prd.md

PRD: os-adr Plugin

Last updated: 2026-07-03

Product requirements for the os-adr Claude Code plugin — the "what and why," to direct a future openspec-propose when the user is ready to implement. Built on the research (01–03), the locked requirements (04-plugin-requirements.md), and a review pass from Fable (external reviewer consult, 2026-07-03) that shaped the gaps and sequencing called out below. Do not silently narrow or reverse anything in 04-plugin-requirements.md — this doc specifies how those requirements get built, not a re-decision of what they are.

Problem statement

~43% of this user's own projects have ADR-like content, in 5+ mutually-incompatible shapes; the rest have none. No project uses ADR tooling. The user works with AI agents across every one of these projects, not just themselves — so decision records need to be discoverable and writable consistently by an agent that has never seen a given project before, which no current project provides. cc-os's own 19-ADR/601-line file is already near the point research says monolithic logs stop working. This plugin exists to fix that, once, and mechanically enough that it doesn't become another bespoke-per-project thing.

Goals

• One template, one location convention, enforced the same way in every project.
• New ADRs get written (by the AI, largely unprompted) using that template with no per-project relearning.
• Existing ADR content in every project — no matter its current shape — converts into the new template non-destructively.
• An AI agent working in any onboarded project surfaces the correct relevant ADR without being told to look, and recognizes when its own in-progress decision warrants a new one.

Non-goals (explicit, out of scope for this PRD)

• Per-project or per-client template variants (rejected in 04-plugin-requirements.md; not revisited here).
• Multi-editor / handed-off-repo governance. This plugin assumes the user is the primary ADR author (directly, or via their AI agents) in every project it's installed in. A repo where other humans independently maintain ADR conventions is out of scope for Phase 1 — flag this assumption in the plugin's own docs rather than silently breaking there.
• Mirroring ADRs into an enforceable-constraints surface (AGENTS.md-style hard rules). The research surfaced this as a real tension (ADRs record "why," not "must never happen"), but nothing today gives ADRs a severity field or an enforcement mechanism. Note as a candidate Phase 2 if a severity field gets added later and high-severity decisions accumulate — not part of this build.
• Retrofitting cc-os's own ADR file as part of building the plugin. Per the README's build order note: build first against a small pilot, retrofit cc-os and everything else after.

Requirements → build phases

Phase 1 — Template + location (mechanical, no LLM)

• Ship the customized-Nygard template and docs/adr/NNNN-title.md + index file convention from 04-plugin-requirements.md, as a copy-paste-ready generator (os-adr:new or similar skill).
• Index file is maintained mechanically (append/update on every write) — never hand-edited.

Phase 2 — SessionStart existence-check hook

• Deterministic only: check for docs/adr/ + index file. No LLM call in the hook itself.
• Present → inject the smallest possible context note (existence + one-line "how to use it"). Budget this like os-doc-hygiene's reminder: near-zero tokens.
• Absent → notify the user, suggest running the setup/migration skill. Needs a suppression mechanism (flagged by Fable review) so a project that deliberately has no ADR system yet doesn't re-nag every session — a per-project dismiss flag (e.g. a marker file or config line), same shape as os-doc-hygiene's snooze state.

Phase 3 — Non-destructive migration

This is the highest-friction requirement (Fable review flags it as the one with the most edge cases) — resolve these before implementation starts, not during:

• Detection: what counts as "an existing ADR" in an unknown project must be defined per known shape from 01-current-state-survey.md (numbered per-file dirs, dated single files, monolithic multi-decision files, prose-embedded-in-other-docs) — plus a fallback path for shapes not yet seen.
• Field-mapping threshold (mechanical vs. LLM boundary — the vaguest part of requirement 4a as originally stated): define a concrete rule before build, e.g. heuristic-fill fields that are structurally unambiguous (Status/Date via frontmatter or clear heading), LLM-fill only fields requiring interpretation (Consequences, Alternatives-rejected) with the result flagged, never silently invent a Decision or Context field from nothing.
• Flagging format: a single, consistent surface for uncertain guesses — a per-file frontmatter field (e.g. migration_confidence: low) plus one migration report file, not scattered inline comments. Decide the exact shape during build, but it must be one mechanism, not several.
• Non-destructiveness: old ADR content is never deleted or moved during migration — new files are written alongside it under docs/adr/. Deletion of the old system happens only on an explicit, separate user-approved step.
• Pilot before shipping broadly: run the migration on 2-3 real projects (candidates: the ones already surveyed with ADR content — viking-warrior-training-log, delta-refinery, llf-schema) and check the uncertain-flag rate before treating the heuristic as good enough. If a large share of fields end up flagged, tighten the heuristic before wider rollout — this is a build-phase gate, not a shipped feature.

Phase 4 — Retrieval (deterministic-first, per the research's layering)

1. Path/component match against each ADR's affected-paths/affected-components frontmatter.
2. Status filter — only Accepted by default.
3. Graph traversal via Graphify once ADRs are indexed as graph nodes (reuses the os-vault infrastructure rather than a parallel retrieval system).
4. AI judgment only over the already-narrowed candidate set from 1-3 — never the full corpus.

Deferred: unprompted-behavior evaluation (requirements 4d/4e)

Per the locked sequencing in 04-plugin-requirements.md: this is a distinct stage after the plugin is built and believed correct, not concurrent with the build. However, per Fable's review, sketch (not implement) the held-out test scenarios before finalizing the plugin skeleton, so Phase 4's retrieval surfaces aren't accidentally missing something the eval will need later. Two example scenario shapes to sketch now:

• Write-trigger scenario: give the AI a task that touches a decision of real consequence (irreversible, cross-cutting, contested) without saying "write an ADR" — check whether it proposes one unprompted.
• Retrieval scenario: give the AI a task or question that conflicts with an already-written, Accepted ADR without naming the ADR or the constraint directly — check whether it (a) surfaces the ADR system at all, and (b) retrieves the specific correct one, not merely a plausible one.

If sketching these surfaces a plugin surface Phase 1-4 doesn't yet provide (e.g. a query tool callable mid-task, not just at SessionStart), fold that surface into the initial build. Do not fold the evaluation itself in — that stays a separate, later stage using the autoresearch skill's modify→verify→keep/discard loop against held-out scenarios, per the locked sequencing.

Architecture / implementation style

• Object-oriented, Sandi Metz principles (small classes/methods, single responsibility, dependency injection over globals, tell-don't-ask, duck typing over type-checks) — see the ruby-and-sandi-metz-oop-preference memory.
• Ruby preferred; Python acceptable for hook entry points where it's the more native fit (matching the existing os-vault/os-doc-hygiene Python hook pattern) — decided per-component, not as a global language choice. A Python hook script may thinly wrap an OO-designed Ruby or Python core.

Success criteria

• Every surveyed project with existing ADR content converts with zero data loss (old system fully intact until user-approved deletion).
• Migration uncertain-flag rate stays low enough to be trustworthy (define and check an explicit threshold during the Phase 3 pilot — do not ship on an unmeasured guess).
• SessionStart hook overhead is near-zero-token and adds no perceptible session-start latency.
• A new ADR can be written, correctly templated and indexed, in one skill invocation.
• (Deferred, Eval stage) unprompted write-trigger and retrieval accuracy measured against a held-out scenario set — no numeric target set yet; the held-out methodology itself is the Phase 5 deliverable.

Rollout order

Matches the README's locked build order: build and pilot this plugin on a small/clean project first, then use it to retrofit cc-os itself, then other ~/dev/ projects, then ~/clients//~/projects/, then any project encountered going forward — one at a time.