---
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:

   ```python
   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.