cc-os/plugins/os-status/skills/fix/SKILL.md

description
Bring the current project up to the current cc-os approach by remediating whatever /os-status checks flag — idempotent, doubles as the update path. Invoked by /os-status:fix.

fix

Unified project setup/update. Runs the same check registry the SessionStart hook runs, then drives each failing check's remediation. Per ADR-026: fix orchestrates existing per-plugin skills — it never reimplements them. Idempotent by construction: re-running fix on an already-configured project is the update path, not a separate command.

Flow

1. Get machine-readable results. From the project root, run:

   python3 ${CLAUDE_PLUGIN_ROOT}/hooks/checks.py --json
   

   This prints a JSON array of {name, status, message, remediation} for every check applicable to the current project (project-scoped checks are skipped outside a git project, same rule the SessionStart hook uses).

2. All ok (and only note/ok)? Report "this project is up to date" and go straight to step 4 (version stamp) — nothing else to do.

3. Otherwise, walk the non-ok entries in this order (mechanical → decision- bearing, so autonomous fixes land before anything needing a human gate):

   a. adr-system-present → invoke /os-adr:init (or /os-adr:migrate if the project already has decision-log-like content the message/context suggests — use judgment, this is mechanical either way).

   b. vault-hub-note-present → either invoke /os-vault:write to create a hub note (tags type/hub + project/<name>), or if the user says a hub note already exists under a different name, set hub = <slug> in .cc-os/config via the config-write helper (see step 4).

   c. project-graph-present → invoke /os-vault:onboard-project.

   d. tracker-configured → human gate. Do not guess a tracker. Ask the user which tracker this project uses, then invoke /os-backlog:route (the os-backlog routing skill) with that answer. If /os-backlog:route does not exist yet in this installation (issue #14 not yet landed), tell the user and skip — do not fabricate a .cc-os/config tracker value yourself.

   e. subagent-model-env-override → human gate, and typically out of scope for a project-level fix. This is an environment/settings.json condition, not a per-project one. Report it and ask the user to remove the env var themselves; do not edit ~/.claude/settings.json from this skill.

   f. config-version-current → resolved automatically by step 4 below; no separate action.

   Re-run the JSON check after each remediation that plausibly changed state, so later steps see fresh results (e.g. don't act on a stale vault-hub-note-present warning after already creating the note).

4. Stamp the config version. Once the mechanical/human-gated fixes above are done (or were already ok), write the current version into .cc-os/config, preserving every other key. Use the helper:

   import sys
   sys.path.insert(0, "${CLAUDE_PLUGIN_ROOT}/hooks")
   from state import write_config_value, find_project_root
   from checks import CURRENT_CONFIG_VERSION
   from pathlib import Path
   
   root = find_project_root(Path.cwd())
   write_config_value(root, "version", str(CURRENT_CONFIG_VERSION))
   

   (Equivalently, run it as a one-off python3 -c "..." from the project root.) This is what makes config-version-current pass on the next run and what makes re-running fix on a fully-configured project a fast, silent no-op.

5. Report a short summary: which checks were already ok, which were fixed and how, which were skipped pending a human decision, and confirm the config version was stamped.

Notes

• Never edit .cc-os/config by hand-writing the whole file — always go through write_config_value (or the equivalent read-modify-write) so unrelated keys (hub, tracker, vault_path, ...) are preserved.
• Decision-bearing steps (tracker destination, anything destructive) keep their human gate even when this skill is otherwise running autonomously. Mechanical steps (running /os-adr:init, /os-vault:onboard-project, stamping the version) proceed without asking.
• This skill does not touch subagent-model-env-override state — that's a machine environment condition, not a per-project one, and editing global settings.json is out of scope.