77 lines
5.1 KiB
Markdown
77 lines
5.1 KiB
Markdown
# Proposal: add-os-adr-plugin
|
||
|
||
## Why
|
||
|
||
~43% of the user's projects carry ADR-like content in 5+ mutually-incompatible shapes; the rest
|
||
have none, and no project uses ADR tooling. Because AI agents (not just the user) work across
|
||
every project, decision records must be discoverable and writable *consistently* by an agent
|
||
that has never seen a given repo — and cc-os's own 19-ADR/601-line monolithic file is already
|
||
near the size where research says monolithic logs stop working. The requirements are locked
|
||
(`docs/adr-system/04-plugin-requirements.md`) and the PRD is written
|
||
(`docs/adr-system/05-plugin-prd.md`); this change builds the plugin.
|
||
|
||
## What Changes
|
||
|
||
- New global Claude Code plugin **`os-adr`** at `cc-os/plugins/os-adr/`, following the
|
||
established cc-os plugin conventions: `os-` prefix, verb-first skills, no `commands/`
|
||
dispatcher, symlink into `~/.claude/plugins/`, registered in the `local-plugins` marketplace
|
||
manifest (the three-place rename/registration procedure in CLAUDE.md).
|
||
- **Phase 1 — authoring**: customized-Nygard template (Status/Context/Decision/Consequences +
|
||
Alternatives rejected; frontmatter with `supersedes`/`superseded-by`,
|
||
`affected-paths`/`affected-components`, `date`, sequential ID), `docs/adr/NNNN-title.md`
|
||
one-file-per-decision convention, mechanically-maintained index file, and a `new` skill that
|
||
writes a correctly templated + indexed ADR in one invocation. No LLM in the mechanical path.
|
||
- **Phase 2 — SessionStart hook**: deterministic existence check for `docs/adr/` + index. Present
|
||
→ near-zero-token context note; absent → suggest setup, with a per-project suppression flag so
|
||
a deliberately ADR-less project doesn't re-nag (same shape as `os-doc-hygiene` snooze state).
|
||
- **Phase 3 — non-destructive migration**: a `migrate` skill converting existing ADR content of
|
||
any surveyed shape into the new template alongside (never replacing) the old system; heuristic
|
||
fill for structurally unambiguous fields, LLM fill only for interpretive fields, one consistent
|
||
uncertainty-flagging mechanism (`migration_confidence` frontmatter + a migration report file);
|
||
deletion of the old system only as an explicit, separate user-approved step. Piloted on 2–3
|
||
real projects with an uncertain-flag-rate gate before wider rollout.
|
||
- **Phase 4 — retrieval**: deterministic-first layering — path/component frontmatter match →
|
||
status filter (Accepted by default) → Graphify graph traversal (reusing `os-vault`
|
||
infrastructure) → AI judgment only over the already-narrowed candidate set. Exposed as a query
|
||
surface callable mid-task, not just at SessionStart.
|
||
- Implementation style: OO per Sandi Metz principles; Ruby-preferred core with Python acceptable
|
||
for hook entry points, decided per-component (thin hook scripts wrapping an OO core).
|
||
- Held-out eval scenarios (write-trigger, retrieval) are **sketched** as part of this change so
|
||
the plugin surface isn't missing what the eval needs — but the evaluation itself stays a
|
||
separate later stage (locked sequencing in `04-plugin-requirements.md`).
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `adr-authoring`: the ADR template, `docs/adr/NNNN-title.md` + index location convention, and
|
||
the one-invocation new-ADR generator skill with mechanical index maintenance.
|
||
- `adr-session-awareness`: the deterministic SessionStart existence-check hook — minimal context
|
||
injection when the ADR system exists, setup suggestion with per-project suppression when it
|
||
doesn't.
|
||
- `adr-migration`: non-destructive conversion of existing ADR content (all surveyed shapes plus
|
||
a fallback) into the new template, with the mechanical/LLM field-mapping boundary, single
|
||
uncertainty-flagging mechanism, and pilot gate.
|
||
- `adr-retrieval`: the deterministic-first retrieval stack (frontmatter path match → status
|
||
filter → Graphify traversal → narrowed AI judgment) exposed as a mid-task query surface.
|
||
- `adr-plugin-packaging`: plugin structure, naming, marketplace registration, and install
|
||
procedure per cc-os conventions (`os-` prefix, verb-first skills, symlink + `local-plugins`
|
||
manifest + `settings.json` enablement).
|
||
|
||
### Modified Capabilities
|
||
|
||
<!-- none — os-adr is a new plugin; no existing spec's requirements change -->
|
||
|
||
## Impact
|
||
|
||
- New code: `cc-os/plugins/os-adr/` (hooks, skills, OO core, template assets, tests/fixtures).
|
||
- Host config: `~/.claude/plugins/os-adr` symlink, `~/.claude/plugins/.claude-plugin/marketplace.json`
|
||
entry, `settings.json` `enabledPlugins` (and hook wiring if hooks are registered by absolute
|
||
path like os-vault, or via plugin `hooks.json` like os-doc-hygiene — decided in design).
|
||
- Reuses: Graphify / `os-vault` graph infrastructure for the retrieval layer; `os-doc-hygiene`
|
||
patterns for deterministic SessionStart reminders and snooze state.
|
||
- Target projects (pilot, later phases): viking-warrior-training-log, delta-refinery, llf-schema;
|
||
cc-os itself is retrofitted only after the pilot, per the locked rollout order.
|
||
- Out of scope: per-project template variants, multi-editor governance, enforceable-constraints
|
||
mirroring, the unprompted-behavior evaluation itself, and retrofitting cc-os's ADR file.
|