oduffy-delphi/setup

/coordinator:setup

Chain-walker skill for coordinator-claude (chain position 5 of 5 — root of the OSS plugin-adoption chain). Reads the install manifest, walks direct_deps (ONE hard entry — the control-plane engine), and emits the chain-complete terminal banner once satisfied, or fails loud with remediation if the engine is unresolvable. Does NOT replace coordinator:install (OSS plugin bootstrap into ~/.claude/) or coordinator:repo-setup (consumer-project first-time scaffolding) — three distinct verbs; disambiguation rationale: wiki.

setup_skill in the manifest is informational, not the dispatch primitive — it tells humans what to type. This skill uses direct Bash calls, not subagent dispatch (the single engine dependency self-confirms via the claude_klabauter_seam_resolvable probe kind — no recursive chain-walk).

Registry-key resolution: a dev-tree session resolves the engine via repos.claude_klabauter / REPO_CLAUDE_KLABAUTER; an OSS install has no such registry entry and resolves the same engine (published as claude-klabauter) via docs/install/AGENT.md instead. Both paths resolve the identical dependency.

---

Out-of-scope for all dispatched agents in this skill

DO NOT run gh pr create, gh pr merge, git push origin main, gh release create, or any gh command mutating GitHub state beyond pushing the current branch. DO NOT commit to main directly. Surface a needed merge to the EM instead of doing it.

• Writing outside plugins/coordinator/.
• Modifying docs/install/agent-install-manifest.json at runtime (static artifact, read-only here).
• Touching the DR, example-game-repo, ue-addon, or project-rag trees.
• Any git commit or git push.

---

Step 1 — Detect layout

PLUGIN_ROOT is two levels up from this skill file (coordinator/skills/setup/SKILL.md → coordinator/); resolve it relative to wherever this file lives on disk.

On a PowerShell host, invoke the .exe launcher through the call operator (Shape W) for every setup-verify invocation on this page, never the ${...} POSIX-shell form shown. Ladder and shapes: snippets/resolve-coordinator-bin.md.

Run & "$env:COORDINATOR_SETTINGS_HOME\bin\setup-verify.exe" layout --plugin-root "<PLUGIN_ROOT>" (Shape W; ladder and POSIX shapes: snippets/resolve-coordinator-bin.md). Prints Layout: <flat|nested> and Manifest path: <path>; exits 1 with a "Manifest not found" remediation if docs/install/agent-install-manifest.json is absent under the resolved repo root. Surface an exit-1 error verbatim.

---

Step 2 — Read the install manifest

Verify ${MANIFEST} exists (error and exit if missing), then parse it. Extract: agent_install_contract_version (must be 1, 2, or 3 — reject otherwise), repo_id (should be "coordinator-claude"), direct_deps (the walk list — one hard entry), override_flags (the consent-gate flag-pair names). On a JSON parse failure, surface the error and exit — do not continue with a corrupt manifest.

---

Step 3 — Initialise the visited-set

Disk-resident, for diamond-DAG and cycle detection across recursive subagent dispatches: <settings-home>/coordinator-claude/chain-walk-<session-id>.json, where <settings-home> is resolved per snippets/resolve-coordinator-bin.md (Shape W on PowerShell hosts).

Run & "$env:COORDINATOR_SETTINGS_HOME\bin\setup-verify.exe" visited-init (Shape W) — generates a session id, prunes chain-walk-*.json files older than 60 minutes, writes the new file with an empty visited array, prints Session ID: and Visited-set:.

---

Step 4 — Walk direct_deps and resolve system prerequisites

Python is pre-verified (hard exit if absent — the sole hard gate on this path). Run python3 $CLAUDE_KLABAUTER_ROOT/coordinator/scripts/chain-walk.py (resolve CLAUDE_KLABAUTER_ROOT via machine-local get repos.claude_klabauter, or the REPO_CLAUDE_KLABAUTER/CLAUDE_KLABAUTER_ROOT env override — the trampoline re-resolves CLAUDE_KLABAUTER_ROOT itself; from a shell already rooted in the engine repo, python3 -m coordinator_core.ops.setup_chain_walker is the same walker without the trampoline). Never the deprecated setup.py forwarder.

This calls _co_run_prereq_gate post-consumer, which emits one dep row (the engine, hard) and the prereq probe rows (git, python, uv, gh, node, pwsh, ue, clone_auth, longpaths, git_lfs) at the severities the Step 5 terminal report shows below.

Advisory failures print [WARN] to stderr and do not block exit 0. A missing/broken engine dependency triggers the [FAIL] hard-fail path — exit 1 (--preflight/--check) or consent-gate codes 90/91/92 (full install), remediation pointing at the CLAUDE_KLABAUTER_ROOT resolution ladder. Full contract detail (severity taxonomy, consent-gate banner, exit codes): wiki.

Read-only flags (--help, --version, --phase-list, --last-status, --check) are serviced before any dep-walking and do not trigger the override check.

Override flags — both must be passed TOGETHER: --skip-dep-check and --accept-missing-deps-risk. Validate via & "$env:COORDINATOR_SETTINGS_HOME\bin\setup-verify.exe" check-override-flags -- $args (Shape W) — exits 93 when exactly one is present, 0 otherwise (printing which path applies). Passing only one degrades most mutating coordinator operations (no bash fallback under the big-bang cutover); both together bypass the consent gate.

---

Step 5 — Terminal report

## /coordinator:setup — chain step 5 of 5

Manifest: plugins/coordinator/docs/install/agent-install-manifest.json
Contract version: <agent_install_contract_version from manifest>
Layout: <flat | nested>
Session ID: <uuid>

### System prerequisite gate (post-consumer mode)

| Probe      | Severity | Result | Notes                                      |
|------------|----------|--------|--------------------------------------------|
| python     | hard     | PASS   | Python 3.11+ (the sole hard gate)          |
| gh         | advisory | PASS/WARN | demoted from hard; WARN does not block  |
| node       | advisory | PASS/WARN | demoted from hard; WARN does not block  |
| git        | advisory | PASS/WARN | demoted from hard; WARN does not block  |
| clone_auth | advisory | PASS/WARN | demoted from semi-hard; WARN does not block |
| uv/pwsh/ue/longpaths/git_lfs | advisory | PASS/WARN | advisory, no change |

### Dependency walk

| Dep | Severity | Probe | Action |
|-----|----------|-------|--------|
| claude-klabauter | hard | PASS/FAIL | claude_klabauter_seam_resolvable — self-confirming (this walker code only runs once claude-klabauter is already resolved) |

### Result

coordinator install-chain walker — chain step 5 of 5: all deps satisfied.

coordinator-claude install chain complete.

Exit 0 (advisory WARN rows do not affect exit code).

---

Step 6 — Live Claude-Code-integration validation

Asserts the plugin is running-in-Claude-Code, not just present on disk, via three testable surfaces (no MCP server for this plugin):

1. Plugin enabled — listed in settings.json/enabledPlugins, not disabled/overridden.
2. Hooks registered and live — this plugin's hooks exist on disk at their expected paths and are included in the Claude Code hooks configuration.
3. Skill discovery preconditions — a representative skill file exists, parses, and exposes a description: field with trigger phrases. Skills are model-invoked, not shell-invoked — the assertion is discovery-preconditions-met, not shell execution.

Restart-batch (emit before the per-item probe table)

Collect every restart-gated finding into one block, emitted only if non-empty:

restart-batch (emit this block if any restart-gated items are found):
────────────────────────────────────────────────────────────────
The following items require a Claude Code restart to take effect.
Restart Claude Code NOW, then re-validate (re-run /coordinator:setup).

  [restart-gated] <item description>
  ...
────────────────────────────────────────────────────────────────

Restart discriminator

• restart-gated-expected — fails, no restart since the config write → restart-batch; not a hard failure.
• configured-but-broken — fails after a restart (or its settle window) → fail loud.
• pending-settle — fails within the settle window → re-probe once, then reclassify.

Probes

Run via Bash. Resolve PLUGIN_ROOT per-probe if not already in scope (each probe must be self-contained). Rationale for probe ordering and design: wiki.

Probe 0 — Plugin reachable. & "$env:COORDINATOR_SETTINGS_HOME\bin\setup-verify.exe" check-plugin-registered --plugin coordinator --marketplace coordinator-claude --marketplace-source dbc-oduffy/coordinator-claude --plugin-dir "<PLUGIN_ROOT>" (Shape W). Asserts reachability (marketplace registration OR live --plugin-dir resolution — PASS (live-resolved) when a manifest plus commands or hooks are present at that path), not mere enablement membership. Runs before Probe 1 deliberately. Never restart-gated — always configured-but-broken on FAIL.

Probe 1 — Plugin enabled in settings.json. & "$env:COORDINATOR_SETTINGS_HOME\bin\setup-verify.exe" check-settings-membership --plugin-dir "<PLUGIN_ROOT>" (Shape W; optional --settings <path>, default ~/.claude/settings.json). Pass the same <PLUGIN_ROOT> Probe 0 got — omitting --plugin-dir FAILs a live-resolved install. PASS/exit 0, [WARN]/exit 0 if settings.json missing/unparseable, FAIL/exit 1 otherwise. A FAIL after a config write with no subsequent restart is restart-gated-expected; after a restart, configured-but-broken. Probe 0's verdict governs this one. enabledPlugins membership is a marketplace-install signal; the dev / --plugin-dir shape never establishes it. When Probe 0 reported PASS (live-resolved), Probe 1 degrades to [WARN]/exit 0 — absence from enabledPlugins is that shape's expected state, never a configured-but-broken install.

Probe 2 — Hooks registered and live on disk. & "$env:COORDINATOR_SETTINGS_HOME\bin\setup-verify.exe" check-hooks --plugin-root "<PLUGIN_ROOT>" (Shape W). Parses <PLUGIN_ROOT>/hooks/hooks.json, verifies each coordinator-owned hook path exists on disk (named lookup, not a blanket file count). PASS/exit 0, FAIL (lists missing paths)/exit 1, [WARN] (hooks.json absent/unparseable, or no coordinator-owned hooks)/exit 0. Hooks absent from disk → configured-but-broken. Hooks present but not yet loaded by a running session → restart-gated-expected.

Probe 3 — Skill discovery preconditions. Use this skill itself as the representative: <PLUGIN_ROOT>/skills/setup/SKILL.md. & "$env:COORDINATOR_SETTINGS_HOME\bin\setup-verify.exe" check-skill-description --skill-file "<PLUGIN_ROOT>/skills/setup/SKILL.md" (Shape W). PASS/exit 0, FAIL (missing file, no frontmatter, no/empty description:)/exit 1. Missing or unparseable skill file is always configured-but-broken — never restart-gated. Probe 1's WARN propagates here since plugin-enabled is a precondition for the model reaching this skill.

Probe 4 — Windows launch shape (dogfood shape only). python3 "<PLUGIN_ROOT>/bin/check-launch-shape.py". Asserts the interactive claude.exe would be a DIRECT child of the invoking shell: no claude-doe shadowing the real launcher from earlier on PATH, the rendered shim scanning for claude-doe.ps1 rather than taking the first PATH hit, and the launcher consuming --doe-root instead of delegating the interactive launch. PASS/exit 0, FAIL (names the offending directory or file)/exit 1, SKIP/exit 0 on non-Windows or when no rendered launcher pair is on PATH — OSS coordinator-claude and claude-klabauter installs never take the --doe-root seam. Always configured-but-broken on FAIL, never restart-gated: PATH order and rendered launcher content are disk state, and a restart cannot change either. A FAIL here means every session on the box launches into a corrupted console, whose only operator-available mitigation — disabling the shim — silently strips the coordinator plugin entirely.

Validation summary table

### Step 6 — Live Claude-Code-integration validation (running-in-Claude-Code)

| Probe | Surface | Result | Classification |
|-------|---------|--------|----------------|
| Plugin reachable | marketplace registration OR `--plugin-dir` live resolution | PASS/FAIL | live / configured-but-broken (never restart-gated) |
| Plugin enabled | settings.json enabledPlugins | PASS/WARN/FAIL | live / restart-gated-expected or live-resolved (Probe 0 PASS) / configured-but-broken |
| Hooks live on disk | ~/.claude/hooks/ | PASS/WARN/FAIL | live / restart-gated-expected / configured-but-broken |
| Skill discovery preconditions | skills/setup/SKILL.md | PASS/WARN | live / configured-but-broken |
| Windows launch shape | PATH resolution of claude-doe + rendered shim/launcher | PASS/FAIL/SKIP | live / configured-but-broken (never restart-gated) / not-this-shape |

Exit-code semantics

configured-but-broken → [ERROR] to stderr, exit non-zero — the install is incomplete and the chain-walk result is not valid; this is the exception to the Steps 4/5 advisory-WARN model. restart-gated-expected → WARN row in the summary table and restart-batch; does not change the exit code. All probes PASS → emit the summary table, exit 0.

---

Negative-spec

<!-- negative-spec: this skill does NOT dispatch subagents. coordinator-claude's one direct_dep (the engine) self-confirms via the claude_klabauter_seam_resolvable probe kind — there is no recursive chain-walk into the engine's own manifest. The visited-set is initialised for contract-conformance only. --> <!-- negative-spec: this skill does NOT replace coordinator:install (OSS plugin install) or coordinator:repo-setup (consumer-project first-time setup). This skill DOES assert, via Probe 0, that the plugin is actually reachable — by marketplace registration or live --plugin-dir resolution — rather than merely enabled by membership; that assertion is in scope here even though performing the registration itself remains coordinator:install's job. --> <!-- negative-spec: this skill does NOT seed install-leg spinoffs into the install-baton rendezvous (`$(coordinator-settings-home)/state/handoffs/`). Spinoffs are PM-authorized via /spinoff only. --> <!-- negative-spec: the visited-set path is <settings-home>/coordinator-claude/chain-walk-*.json where <settings-home> resolves per snippets/resolve-coordinator-bin.md (Shape W on PowerShell hosts) — canonical per agent-install-contract.md § Visited-set protocol. -->