3.7 KiB
| id | date | status | supersedes | superseded-by | affected-paths | affected-components | migration_confidence | migration_source |
|---|---|---|---|---|---|---|---|---|
| 0026 | 2026-07-12 | Accepted | medium | docs/memory-system/03-architecture-decisions.md### ADR-026 — Unified project setup/update command: `/os-status:fix` remediates what the os-status checks flag |
0026 — Unified project setup/update command: /os-status:fix remediates what the os-status checks flag
Context
Bringing a project up to cc-os standards currently requires knowing and running each plugin's own onboarding surface separately (/os-adr:init, /os-vault:onboard-project, a manual hub-note write, the os-backlog routing skill — which is itself still unbuilt, issue #14, so the os-status tracker warning points at a skill that does not exist). The SessionStart warnings (ADR-022) name a different remediation per line, and only os-adr's names a real command. The user wants one command that brings any project up to date with the current cc-os approach, without per-plugin ceremony. A literal /cc-os:init is impossible under the naming convention (os-[domain] plugins only).
Decision
(1) New skill /os-status:fix in the os-status plugin: it runs the same check registry the SessionStart hook runs, then for each non-ok result drives the owning plugin's remediation — invoking that plugin's existing skill (/os-adr:init, /os-vault:onboard-project, the routing skill once built) or performing the small direct action (hub-note creation via /os-vault:write conventions). Decision-bearing steps (tracker destination, ignore-list confirmation) keep their human gates; mechanical steps run autonomously. (2) Idempotent by construction: re-running fix on a configured project is the update path — no separate update command. (3) Each Check in hooks/checks.py gains a remediation pointer so check and fix stay co-located in one registry; SessionStart warn output suggests /os-status:fix as the single entry point (per-check detail remains for context). (4) .cc-os/config gains a version key stamped by fix; a future check can warn when a project was configured under an older approach.
- Rationale: os-status already owns the per-project precondition registry (ADR-022); the fix skill is the write-side of the same seam, so checks and remediations cannot drift apart. Idempotent fix collapses setup/update into one verb. Per-plugin init skills remain the implementation (composition per ADR-023's cooperation goal) —
fixorchestrates, it does not reimplement.
Consequences
A new /os-status:fix skill runs the same check registry as the SessionStart hook and drives each non-ok result's remediation by invoking the owning plugin's existing onboarding skill or a small direct action, functioning as both the initial setup path and, by being idempotent, the update path. Each check gains a co-located remediation pointer in the registry, and .cc-os/config gains a version key so future checks can detect projects configured under an older approach; implementation was queued as a Forgejo issue with the tracker remediation depending on issue #14.
Alternatives rejected
New os-project plugin with /os-project:init — reads slightly more naturally but splits remediations from the check registry they mirror and adds a seventh plugin for glue. /os-status:configure — same home, weaker verb; fix reads as "fix what the status check flagged", which is exactly the contract. Literal /cc-os:init — violates the os-[domain] naming convention.
- Cross-references: ADR-022 (check registry), ADR-023 (cross-plugin cooperation),
cc-os-plugin-skill-naming-convention.md; Forgejo issue #14 (routing skill — the tracker remediationfixwill delegate to).