@jabworks/condux 0.6.0 → 0.8.0

package/README.md

@@ -3,10 +3,11 @@
 OpenCode plugin for the [condux](https://github.com/jabworks/agentic-toolkit)
 workflow toolkit. One plugin line installs everything condux needs:
 
-- **Skills** — bundles the 12 condux workflow skills (`workflow`, `discovery`,
+- **Skills** — bundles the 14 condux workflow skills (`workflow`, `discovery`,
   `draft-plan`, `test-first-development`, `subagent-execution`,
-  `subagent-deployment`, `finalize`, `code-review`, `preflight`,
-  `root-cause-analysis`, `plan-review`, `technical-spec`) and registers them on
+  `subagent-deployment`, `finalize`, `live-verification`, `code-review`,
+  `preflight`, `root-cause-analysis`, `plan-review`, `technical-spec`,
+  `condux-doctor`) and registers them on
   `config.skills.paths` via the `config` hook — no separate `npx skills add`
   step. A skill you install yourself under the same name still wins; OpenCode
   dedupes by name.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jabworks/condux",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "OpenCode plugin for the condux workflow toolkit — bundles the condux skills and injects the specialist agents (coder, explorer, planner, researcher) plus an opt-in plan-review listener.",
   "type": "module",
   "publishConfig": {

package/skills/condux-doctor/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: condux-doctor
+description: "Health check for the condux plugin on the host it is installed on. Runs the SessionStart routing hook on both hosts and checks each wire format, confirms Codex's hooks flag is on and plan-review's Stop hook resolves, checks the OpenCode registration and its bundled agents and skills, verifies the four specialist agents shipped, compares the installed version against the marketplace clone, and flags conflicting skill libraries installed. Offline; read-only unless --fix. Checking whether condux itself works on this machine: is condux working, the routing rule stopped appearing, /workflow is not being reached, did the SessionStart hook fire, check my condux install, the agents are missing, does condux clash with superpowers. Run it after installing or updating. Not for routing a dev task (that is workflow); not for diagnosing this repo's own build or dist drift (that is toolkit-debugging-playbook)."
+argument-hint: "[--host claude|codex|opencode] [--fix]"
+---
+
+# /condux-doctor
+
+Answers one question: **is condux actually working on this host?**
+
+```bash
+node <skill-base>/doctor.mjs                    # every host, every probe
+node <skill-base>/doctor.mjs --host codex       # one host
+node <skill-base>/doctor.mjs --quiet            # only what is not fine
+node <skill-base>/doctor.mjs --fix              # run the installer, then re-probe
+```
+
+Exit 0 when nothing is broken, 1 when something is, 2 when the doctor cannot
+find condux's own hooks.
+
+`--fix` performs no registration itself — it runs condux's plugin-level
+`install.mjs` and probes again, so idempotency, backups and atomic writes stay
+in one place. If the installer fails, the report says how it failed rather than
+re-probing in silence, and the re-probe still decides the exit code. Without an
+installer beside the plugin (an `npx skills add` tree has none), it says so and
+changes nothing.
+
+## Reading the report
+
+One row per probe: `host  status  detail`, fix on an indented continuation
+line. `done` works · `broken` needs the fix · `absent` is not there and not a
+failure · `skipped` deliberately needs nothing · `warn` works but something
+else on the machine competes with it. Only `broken` affects the exit code.
+
+## What it probes
+
+- **The SessionStart routing hook, by running it.** Claude Code must get a
+  `hookSpecificOutput` envelope carrying non-empty context; Codex must get
+  the raw routing payload. Each host's manifest must use its own root
+  variable — `${CLAUDE_PLUGIN_ROOT}` or `${PLUGIN_ROOT}`, never the other.
+- **Codex's `features.hooks` flag**, before anything else on that host. A
+  plugin manifest can declare hooks; nothing in a plugin can enable them. With
+  the flag off, the manifest parses, every path resolves, and no hook fires —
+  which this doctor scored `done` until it learned to read the flag. It proves
+  the flag is set, not that Codex has restarted since.
+- **plan-review's Codex Stop hook** — resolved, never executed. It blocks a
+  turn for up to four days waiting on a human by design.
+- **OpenCode** — `@jabworks/condux` in the plugin array, and when a local
+  copy exists, that it ships its bundled `agents/` and `skills/`.
+- **The four specialist agents** — `coder`, `explorer`, `planner`,
+  `researcher`. They live in a plugin-level directory reached by its own sync
+  step, which is exactly the mirror that drifted once before.
+- **Version** — installed against the local marketplace clone, with that
+  clone's own last-fetch date printed beside it. Never fetches.
+- **Conflicting skill libraries** — anything in
+  `conflicts.json` that is already on this machine, matched by name against
+  the host plugin registrations and the loose skill directories. The one entry
+  today is `superpowers`, which condux is derived from and which registers a
+  competing `SessionStart` router. Reported `warn`, never `broken`: condux is
+  fine, and the removal command is printed rather than run.
+
+## Why running the hook matters
+
+`session-start.mjs` fails open on purpose: if its payload is missing it exits
+0 and prints nothing, because a hook that breaks the session is worse than a
+hook that does nothing. Every static check passes in that state. Only
+executing it reveals that condux's routing rule is silently absent — which is
+the difference between `/workflow` being the entry point and being a lucky
+guess from the catalog.
+
+## What it cannot prove
+
+That the host *invoked* the hook. Nothing readable from a child process says
+whether Claude Code or Codex loaded a registration this session. If every
+probe is green and the routing rule still never appears, the fault is
+host-side and this report is the evidence.
+
+## Boundaries
+
+Routing an actual dev task is `workflow`. Problems with this *repo's* build —
+dist drift, a manifest that will not parse, a skill that will not trigger —
+belong to `toolkit-debugging-playbook`: that one needs the source tree, this
+one needs only the install.

package/skills/condux-doctor/conflicts.json

@@ -0,0 +1,52 @@
+{
+  "note": "Known-conflicting skill libraries, as data. Both plugins/condux/install.mjs and doctor.mjs read this one file — adding an entry is a data edit, not a code edit in two places. Detection is name matching against what is already on disk: no network, no semantic comparison (that is docket #10, an open research question). Every entry must be verified against an installed copy before it ships; a wrong skill name in a shipped warning is worse than no warning.",
+  "conflicts": [
+    {
+      "id": "superpowers",
+      "title": "superpowers",
+      "author": "obra (Jesse Vincent)",
+      "homepage": "https://github.com/obra/superpowers",
+      "verified": "6.2.0, read from an installed copy on 2026-08-11",
+      "relationship": "condux reworks its skill-orchestration ideas around proportional effort — tiered routing, lazy loading, soft gates — rather than always-on maximalism. The debt is real and credited; the consequence is that the two are near-complete functional twins.",
+      "impact": "Both ship a SessionStart hook on the same matcher (startup|clear|compact), and each injects a router telling the agent every dev task starts with it. Whichever is read last wins, per session, unpredictably. 11 of superpowers' 14 skills also overlap 8 of condux's 14, so the agent picks between two competing contracts at every step of a task.",
+      "recommendation": "Run one or the other. They are not layered libraries — they are two answers to the same question.",
+      "detect": {
+        "plugin": "superpowers",
+        "minSkills": 2,
+        "skills": [
+          "brainstorming",
+          "dispatching-parallel-agents",
+          "executing-plans",
+          "finishing-a-development-branch",
+          "receiving-code-review",
+          "requesting-code-review",
+          "subagent-driven-development",
+          "systematic-debugging",
+          "test-driven-development",
+          "using-git-worktrees",
+          "using-superpowers",
+          "verification-before-completion",
+          "writing-plans",
+          "writing-skills"
+        ]
+      },
+      "overlaps": [
+        { "theirs": "using-superpowers", "ours": "workflow", "both": "the entry-point router — each injected at SessionStart" },
+        { "theirs": "brainstorming", "ours": "discovery", "both": "rough idea to signed-off design" },
+        { "theirs": "writing-plans", "ours": "draft-plan", "both": "design to plan document" },
+        { "theirs": "executing-plans", "ours": "subagent-execution", "both": "working through a plan task by task" },
+        { "theirs": "subagent-driven-development", "ours": "subagent-execution", "both": "delegating implementation to agents" },
+        { "theirs": "dispatching-parallel-agents", "ours": "subagent-deployment", "both": "fanning out independent tasks" },
+        { "theirs": "test-driven-development", "ours": "test-first-development", "both": "tests before implementation" },
+        { "theirs": "systematic-debugging", "ours": "root-cause-analysis", "both": "root-cause-first investigation" },
+        { "theirs": "verification-before-completion", "ours": "preflight", "both": "the am-I-actually-done checklist" },
+        { "theirs": "requesting-code-review", "ours": "code-review", "both": "review of the implemented diff" },
+        { "theirs": "receiving-code-review", "ours": "code-review", "both": "acting on review findings" }
+      ],
+      "remedy": {
+        "plugin": "/plugin uninstall {key}",
+        "skills": "remove the overlapping directories under {dir}, or uninstall the library that installed them"
+      }
+    }
+  ]
+}

package/skills/condux-doctor/conflicts.mjs

@@ -0,0 +1,192 @@
+// Detects skill libraries that compete with condux for the same routing
+// decisions, so the installer and the doctor can warn in the same words.
+//
+// The registry is data (conflicts.json) and this is the logic that reads it —
+// the same split as routing.md against session-start.mjs, and for the same
+// reason: adding a conflict is a data edit, and neither of the two callers
+// grows its own copy of the table.
+//
+// Name matching only. No network, no version resolution, no comparing skill
+// descriptions by meaning — that last one is a real question (docket #10) and
+// an unanswered one, and a doctor that advertises itself as offline and
+// read-only is not where it gets prototyped.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// A single skill directory name proves nothing — "brainstorming" is a word
+// before it is a library. The floor is per-entry so a future entry with one
+// very distinctive skill name can lower it deliberately.
+const DEFAULT_MIN_SKILLS = 2;
+
+export function loadRegistry(file) {
+  if (!file || !fs.existsSync(file)) return { error: 'no conflicts.json beside this script' };
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!Array.isArray(parsed?.conflicts)) return { error: 'conflicts.json has no conflicts array' };
+
+    return { entries: parsed.conflicts };
+  } catch (err) {
+    return { error: String(err?.message ?? err) };
+  }
+}
+
+// Claude Code records installed plugins as JSON keys, Codex as TOML table
+// headers, and both spell the key the same way: <name>@<marketplace>. Reading
+// the registration rather than the plugins/cache/ directory is deliberate — a
+// cache entry outlives the install that created it.
+function installedPluginKeys(hosts) {
+  const keys = [];
+
+  if (hosts.claude) {
+    const file = path.join(hosts.claude, 'plugins', 'installed_plugins.json');
+    if (fs.existsSync(file)) {
+      try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        for (const key of Object.keys(parsed?.plugins ?? {})) keys.push({ key, host: 'claude' });
+      } catch {
+        // An unreadable host registry is that host's problem, not a conflict.
+      }
+    }
+  }
+
+  if (hosts.codex) {
+    const file = path.join(hosts.codex, 'config.toml');
+    if (fs.existsSync(file)) {
+      try {
+        for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+          const match = /^\s*\[plugins\."([^"]+)"\]/.exec(line);
+          if (match) keys.push({ key: match[1], host: 'codex' });
+        }
+      } catch {
+        // Same.
+      }
+    }
+  }
+
+  return keys;
+}
+
+// Every place a host will load a loose skill from. `npx skills add` and the
+// shared ~/.agents tree both land here, which is how a machine carries the
+// conflict without the plugin ever being installed.
+function skillDirs(hosts, home) {
+  return [
+    hosts.claude && path.join(hosts.claude, 'skills'),
+    home && path.join(home, '.agents', 'skills'),
+    hosts.codex && path.join(hosts.codex, 'skills'),
+    hosts.opencode && path.join(hosts.opencode, 'skills'),
+  ].filter((dir) => dir && fs.existsSync(dir));
+}
+
+// ~/.claude/skills/<name> is routinely a symlink into ~/.agents/skills/<name>,
+// so one skill is visible from two directories. Resolving is what counts it
+// once, and the resolved path is also the one the report quotes — see where
+// `home` is set below for why that, and not the directory it was listed in.
+function realPath(file) {
+  try {
+    return fs.realpathSync(file);
+  } catch {
+    return file;
+  }
+}
+
+export function detectConflicts(entries, hosts, home) {
+  const pluginKeys = installedPluginKeys(hosts);
+  const dirs = skillDirs(hosts, home);
+  const findings = [];
+
+  for (const entry of entries) {
+    const wanted = entry?.detect?.plugin;
+    const plugin = wanted ? pluginKeys.find(({ key }) => key.split('@')[0] === wanted) ?? null : null;
+
+    const seen = new Map();
+    for (const dir of dirs) {
+      let names = [];
+      try {
+        names = fs.readdirSync(dir);
+      } catch {
+        continue;
+      }
+
+      for (const name of names) {
+        if (!(entry?.detect?.skills ?? []).includes(name)) continue;
+
+        // existsSync follows the link, so a dangling one is false. That is the
+        // point: ~/.claude/skills is full of symlinks into a shared tree, and
+        // when that tree is pruned the links stay behind. A host cannot load a
+        // skill through a broken link, so neither may this count it as one —
+        // warning about a library that is not really there is the fastest way
+        // to teach someone to ignore the warning.
+        const entryPath = path.join(dir, name);
+        if (!fs.existsSync(entryPath)) continue;
+
+        const resolved = realPath(entryPath);
+        // Report where removal would actually have an effect. Deleting
+        // ~/.claude/skills/<name> when it is a symlink removes the link and
+        // leaves the skill sitting in ~/.agents/skills, which is both useless
+        // and confusing when the next run warns about it again.
+        if (!seen.has(resolved)) seen.set(resolved, { name, dir, home: path.dirname(resolved) });
+      }
+    }
+
+    const floor = entry?.detect?.minSkills ?? DEFAULT_MIN_SKILLS;
+    const skills = seen.size >= floor ? [...seen.values()] : [];
+
+    if (plugin || skills.length > 0) findings.push({ entry, plugin, skills });
+  }
+
+  return findings;
+}
+
+function fill(template, values) {
+  return String(template ?? '').replace(/\{(\w+)\}/g, (whole, key) => values[key] ?? whole);
+}
+
+// One row, phrased identically wherever it is printed. The status is `warn`
+// and never `broken`: condux is installed correctly, and the installer's own
+// verify beat keys its exit code on `broken` — a conflict must be loud without
+// failing an install that in fact succeeded.
+export function describe(findings) {
+  if (findings.length === 0) {
+    return { status: 'done', detail: 'no known-conflicting skill library found on this machine' };
+  }
+
+  const details = [];
+  const fixes = [];
+
+  for (const { entry, plugin, skills } of findings) {
+    const where = [];
+    if (plugin) where.push(`installed as ${plugin.key} on ${plugin.host}`);
+    if (skills.length > 0) {
+      const dirs = [...new Set(skills.map(({ home }) => home))];
+      where.push(`${skills.length} of its skills present in ${dirs.join(', ')}`);
+    }
+
+    const pairs = (entry.overlaps ?? []).length;
+    details.push(`${entry.title} — ${where.join('; ')}${pairs > 0 ? `; ${pairs} skills overlap condux` : ''}`);
+
+    if (plugin) fixes.push(fill(entry.remedy?.plugin, { key: plugin.key }));
+    if (skills.length > 0) {
+      const dirs = [...new Set(skills.map(({ home }) => home))];
+      fixes.push(fill(entry.remedy?.skills, { dir: dirs.join(', ') }));
+    }
+  }
+
+  return {
+    status: 'warn',
+    detail: details.join(' · '),
+    // Printed, never run. Removing another vendor's registration is outside
+    // what this installer registered, and so outside what it may reverse.
+    fix: `${fixes.filter(Boolean).join(' — or ')} (run one library or the other; condux does not remove it for you)`,
+  };
+}
+
+// The whole probe, so a caller adds a host label and nothing else.
+export function probe(file, hosts, home) {
+  const { entries, error } = loadRegistry(file);
+  if (error) return { status: 'skipped', detail: `conflict registry unavailable: ${error}` };
+
+  return describe(detectConflicts(entries, hosts, home));
+}

package/skills/condux-doctor/doctor.mjs

@@ -0,0 +1,540 @@
+#!/usr/bin/env node
+// condux's health check — "is condux actually working on this host?"
+//
+// Follows the toolkit health-check convention (toolkit-skill-standards):
+// detect → probe → report → fix. Probes are static parse PLUS execution, and
+// condux is the case that needs it — session-start.mjs fails open by design,
+// so a hook whose payload has gone missing exits 0 and says nothing. Static
+// checks call that healthy; running it does not.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SKILL_BASE = path.dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = path.resolve(SKILL_BASE, '..', '..', '..');
+const HOME = os.homedir();
+const EXEC_TIMEOUT = 5000;
+const PACKAGE = '@jabworks/condux';
+
+// Imported dynamically so a doctor whose sibling has gone missing still runs.
+// A health check is what you reach for when an install is already suspect —
+// dying at module load is the one failure mode it cannot afford, and a static
+// import would do exactly that.
+let conflicts = null;
+try {
+  conflicts = await import('./conflicts.mjs');
+} catch {
+  conflicts = null;
+}
+
+const USAGE = `usage: doctor [options]
+
+  --host <claude|codex|opencode>   probe one host only
+  --quiet                          print only broken and absent rows
+  --fix                            run condux's installer, then re-probe
+`;
+
+function parseFlags(argv) {
+  const flags = {};
+
+  for (let i = 0; i < argv.length; i++) {
+    if (!argv[i].startsWith('--')) continue;
+    const key = argv[i].slice(2);
+    const next = argv[i + 1];
+
+    if (next !== undefined && !next.startsWith('--')) {
+      flags[key] = next;
+      i++;
+    } else {
+      flags[key] = true;
+    }
+  }
+
+  return flags;
+}
+
+function firstExisting(candidates) {
+  return candidates.find((candidate) => candidate && fs.existsSync(candidate)) ?? null;
+}
+
+// The hooks directory is plugin-level in an install and skill-level in the
+// source tree (workflow owns the canonical copy), so search both.
+function findHook(file) {
+  return firstExisting([
+    path.join(PLUGIN_ROOT, 'hooks', file),
+    path.join(SKILL_BASE, '..', 'workflow', 'hooks', file),
+  ]);
+}
+
+function detectHosts() {
+  const configHome = process.env.XDG_CONFIG_HOME || path.join(HOME, '.config');
+  const dirs = {
+    claude: path.join(HOME, '.claude'),
+    // CODEX_HOME is honoured by both sub-installers and by install.mjs. Without
+    // it here, the installer's verify beat would probe a different directory
+    // than the one it just wrote to, and report a pass for the wrong config.
+    codex: process.env.CODEX_HOME || path.join(HOME, '.codex'),
+    opencode: path.join(configHome, 'opencode'),
+  };
+
+  return Object.fromEntries(
+    Object.entries(dirs).map(([host, dir]) => [host, fs.existsSync(dir) ? dir : null]),
+  );
+}
+
+function readJson(file) {
+  try {
+    return { value: JSON.parse(fs.readFileSync(file, 'utf8')) };
+  } catch (err) {
+    return { error: String(err?.message ?? err) };
+  }
+}
+
+// Pulls the first hook command for an event out of either host's manifest —
+// the two dialects differ only in the root variable they interpolate.
+function hookCommand(manifest, event) {
+  const entries = manifest?.hooks?.[event] ?? [];
+
+  for (const entry of entries) {
+    for (const hook of entry.hooks ?? []) {
+      if (typeof hook.command === 'string') return hook.command;
+    }
+  }
+
+  return null;
+}
+
+function resolveCommandPath(command, rootVariable) {
+  const match = command.match(/"([^"]+)"/);
+  const raw = match ? match[1] : command.split(/\s+/).slice(1)[0] ?? '';
+
+  return raw.replace(rootVariable, PLUGIN_ROOT);
+}
+
+function runSessionStart(script, hostFlag) {
+  const res = spawnSync(process.execPath, [script, hostFlag], {
+    timeout: EXEC_TIMEOUT,
+    encoding: 'utf8',
+  });
+
+  if (res.error) {
+    const why = res.error.code === 'ETIMEDOUT' ? 'no answer within 5s' : String(res.error.message);
+
+    return { ok: false, why };
+  }
+
+  const stdout = (res.stdout ?? '').trim();
+  if (stdout === '') {
+    // The documented fail-open path: routing.md missing or empty. Harmless to
+    // the session and invisible without this probe.
+    return { ok: false, why: 'hook produced no output — it is failing open, so routing.md is missing or empty' };
+  }
+
+  if (hostFlag === '--codex') {
+    return stdout.includes('/condux:workflow')
+      ? { ok: true, why: 'SessionStart emits the routing payload' }
+      : { ok: false, why: 'hook output does not carry the routing rule' };
+  }
+
+  try {
+    const payload = JSON.parse(stdout);
+    const context = payload?.hookSpecificOutput?.additionalContext ?? '';
+
+    if (payload?.hookSpecificOutput?.hookEventName !== 'SessionStart') {
+      return { ok: false, why: 'hook output is JSON but not a SessionStart envelope' };
+    }
+
+    return context.trim() === ''
+      ? { ok: false, why: 'SessionStart envelope carries an empty context' }
+      : { ok: true, why: 'SessionStart emits a valid envelope with the routing payload' };
+  } catch {
+    return { ok: false, why: 'hook output is not the JSON envelope Claude Code expects' };
+  }
+}
+
+// Hooks are registered by the plugin manifest, so outside a plugin install
+// there is nothing registered to probe — and the root variables the manifest
+// interpolates have no meaning there either.
+const IS_PLUGIN = fs.existsSync(path.join(PLUGIN_ROOT, '.claude-plugin', 'plugin.json'));
+
+function probeHookManifest(host, { file, event, rootVariable, foreignVariable, hostFlag }) {
+  if (!IS_PLUGIN) {
+    return { host, status: 'absent', detail: 'not a plugin install — this tree registers no hooks' };
+  }
+
+  const manifest = findHook(file);
+  if (!manifest) {
+    return { host, status: 'absent', detail: `not a plugin install — no hooks/${file}` };
+  }
+
+  const { value, error } = readJson(manifest);
+  if (error) {
+    return { host, status: 'broken', detail: `${file} is unparseable: ${error}`, fix: 'reinstall the plugin' };
+  }
+
+  const command = hookCommand(value, event);
+  if (!command) return { host, status: 'broken', detail: `${file} declares no ${event} hook`, fix: 'reinstall the plugin' };
+
+  if (command.includes(foreignVariable)) {
+    return {
+      host,
+      status: 'broken',
+      detail: `${event} uses ${foreignVariable}, which this host never expands`,
+      fix: `the manifest must use ${rootVariable} — reinstall the plugin`,
+    };
+  }
+
+  const script = resolveCommandPath(command, rootVariable);
+  if (!fs.existsSync(script)) {
+    return { host, status: 'broken', detail: `${event} points at a missing script: ${script}`, fix: 'reinstall the plugin' };
+  }
+
+  const verdict = runSessionStart(script, hostFlag);
+
+  return verdict.ok
+    ? { host, status: 'done', detail: verdict.why }
+    : { host, status: 'broken', detail: verdict.why, fix: 'reinstall the plugin — its routing payload did not ship' };
+}
+
+function probeClaude(hosts) {
+  if (!hosts.claude) return { host: 'claude', status: 'absent', detail: 'no ~/.claude on this machine' };
+
+  return probeHookManifest('claude', {
+    file: 'hooks.json',
+    event: 'SessionStart',
+    rootVariable: '${CLAUDE_PLUGIN_ROOT}',
+    foreignVariable: '${PLUGIN_ROOT}',
+    hostFlag: '--claude',
+  });
+}
+
+// Codex's hook support sits behind an experimental feature flag. A plugin
+// manifest can declare hooks; nothing in a plugin can enable them. With the
+// flag off, the manifest parses, every path resolves, and no hook fires — which
+// this doctor scored `done` until docket #9. It is the static-parse blind spot
+// the probe-depth decision names, applied to an input rather than to a path.
+//
+// The claim is narrow on purpose: the flag is set. Nothing on disk records
+// whether Codex has restarted since, and a running Codex does not re-read it.
+function probeCodexFeatureFlag(codexHome) {
+  const config = path.join(codexHome, 'config.toml');
+  const fix = `run condux's install.mjs, or add [features] hooks = true to ${config}`;
+
+  if (!fs.existsSync(config)) {
+    return { host: 'codex', status: 'broken', detail: 'no config.toml — the hooks feature is not enabled', fix };
+  }
+
+  let text = '';
+  try {
+    text = fs.readFileSync(config, 'utf8');
+  } catch (err) {
+    return { host: 'codex', status: 'broken', detail: `cannot read config.toml: ${err.message}`, fix };
+  }
+
+  const lines = text.split('\n');
+  const start = lines.findIndex((line) => /^\s*\[features\]\s*(#.*)?$/.test(line));
+  if (start === -1) {
+    return { host: 'codex', status: 'broken', detail: 'config.toml declares no [features] table — hooks cannot fire', fix };
+  }
+
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*\[/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+
+  const enabled = lines.slice(start + 1, end).some((line) => /^\s*hooks\s*=\s*true\s*(#.*)?$/.test(line));
+
+  return enabled
+    ? null
+    : { host: 'codex', status: 'broken', detail: 'features.hooks is not true — the manifest resolves but no hook fires', fix };
+}
+
+function probeCodex(hosts) {
+  if (!hosts.codex) return { host: 'codex', status: 'absent', detail: 'no ~/.codex on this machine' };
+
+  // Runs first: with the flag off, how well the manifest parses is moot.
+  const flag = probeCodexFeatureFlag(hosts.codex);
+  if (flag) return flag;
+
+  const row = probeHookManifest('codex', {
+    file: 'codex-hooks.json',
+    event: 'SessionStart',
+    rootVariable: '${PLUGIN_ROOT}',
+    foreignVariable: '${CLAUDE_PLUGIN_ROOT}',
+    hostFlag: '--codex',
+  });
+
+  if (row.status !== 'done') return row;
+
+  // plan-review's Stop hook blocks a turn for up to four days waiting on a
+  // human, so it is resolved and never executed.
+  const manifest = findHook('codex-hooks.json');
+  const stop = hookCommand(readJson(manifest).value, 'Stop');
+  if (!stop) return { ...row, detail: `${row.detail}; no Stop hook for plan-review` };
+
+  const server = resolveCommandPath(stop, '${PLUGIN_ROOT}');
+
+  return fs.existsSync(server)
+    ? { ...row, detail: `${row.detail}; plan-review Stop hook resolves` }
+    : {
+        host: 'codex',
+        status: 'broken',
+        detail: `SessionStart is fine but the Stop hook points at a missing annotate-server.js: ${server}`,
+        fix: 'reinstall the plugin',
+      };
+}
+
+function findPackage(configDir) {
+  return firstExisting([
+    path.join(configDir, 'node_modules', ...PACKAGE.split('/')),
+    path.join(HOME, '.local', 'share', 'opencode', 'node_modules', ...PACKAGE.split('/')),
+    path.join(HOME, '.cache', 'opencode', 'node_modules', ...PACKAGE.split('/')),
+  ]);
+}
+
+function probeOpencode(hosts) {
+  if (!hosts.opencode) return { host: 'opencode', status: 'absent', detail: 'no opencode config dir on this machine' };
+
+  const config = path.join(hosts.opencode, 'opencode.json');
+  const fix = `add ${PACKAGE} to the plugin array in ${config}`;
+  if (!fs.existsSync(config)) return { host: 'opencode', status: 'absent', detail: 'no opencode.json — condux is not registered', fix };
+
+  const { value, error } = readJson(config);
+  if (error) return { host: 'opencode', status: 'broken', detail: `opencode.json is unparseable: ${error}`, fix };
+
+  const registered = (value?.plugin ?? []).some((entry) => String(entry).startsWith(PACKAGE));
+  if (!registered) return { host: 'opencode', status: 'absent', detail: `${PACKAGE} is not in the plugin array`, fix };
+
+  const pkg = findPackage(hosts.opencode);
+  if (!pkg) {
+    return {
+      host: 'opencode',
+      status: 'absent',
+      detail: 'registered, but no local copy to verify — OpenCode fetches plugins at startup',
+    };
+  }
+
+  for (const dir of ['agents', 'skills']) {
+    const bundled = path.join(pkg, dir);
+    if (!fs.existsSync(bundled) || fs.readdirSync(bundled).length === 0) {
+      return { host: 'opencode', status: 'broken', detail: `the installed package ships no ${dir}/`, fix: `reinstall ${PACKAGE}` };
+    }
+  }
+
+  const check = spawnSync(process.execPath, ['--check', path.join(pkg, 'index.js')], { timeout: EXEC_TIMEOUT, encoding: 'utf8' });
+  if (check.status !== 0) {
+    return { host: 'opencode', status: 'broken', detail: 'the installed package entry point does not parse', fix: `reinstall ${PACKAGE}` };
+  }
+
+  return { host: 'opencode', status: 'done', detail: 'registered, and the installed package ships its agents and skills' };
+}
+
+// The four specialist agents are plugin-level and reached by their own sync
+// step, not by the skill copy — the mirror that drifted in 6ba6572.
+function probeAgents() {
+  const dir = firstExisting([
+    path.join(PLUGIN_ROOT, 'agents'),
+    path.join(SKILL_BASE, '..', 'subagent-execution', 'agents'),
+  ]);
+
+  if (!dir) return { host: 'all', status: 'absent', detail: 'no agents/ directory — not a plugin install' };
+
+  const agents = fs.readdirSync(dir).filter((entry) => entry.endsWith('.md'));
+  const expected = ['coder', 'explorer', 'planner', 'researcher'];
+  const missing = expected.filter((name) => !agents.includes(`${name}.md`));
+
+  return missing.length === 0
+    ? { host: 'all', status: 'done', detail: `all four specialist agents present (${dir === path.join(PLUGIN_ROOT, 'agents') ? 'plugin-level' : 'source tree'})` }
+    : { host: 'all', status: 'broken', detail: `missing agent definitions: ${missing.join(', ')}`, fix: 'reinstall the plugin' };
+}
+
+// Not a condux fault, so never `broken` — the exit code stays clean and the
+// installer's verify beat keeps passing. It is reported because two libraries
+// racing to route the same task is invisible from inside a session: nothing
+// errors, the agent simply follows whichever contract it read last.
+function probeConflicts(hosts) {
+  if (!conflicts) return { host: 'conflicts', status: 'skipped', detail: 'conflicts.mjs is not beside this doctor' };
+
+  return { host: 'conflicts', ...conflicts.probe(path.join(SKILL_BASE, 'conflicts.json'), hosts, HOME) };
+}
+
+function compareVersions(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0) return diff < 0 ? -1 : 1;
+  }
+
+  return 0;
+}
+
+// Offline by design: the clone the host already fetched is the only reference,
+// and its age is printed so a stale answer reads as stale.
+function marketplaceVersion(name) {
+  const root = path.join(HOME, '.claude', 'plugins', 'marketplaces');
+  if (!fs.existsSync(root)) return null;
+
+  for (const entry of fs.readdirSync(root)) {
+    const manifest = path.join(root, entry, '.claude-plugin', 'marketplace.json');
+    if (!fs.existsSync(manifest)) continue;
+
+    const { value } = readJson(manifest);
+    const plugin = (value?.plugins ?? []).find((candidate) => candidate.name === name);
+    if (!plugin) continue;
+
+    const clone = path.join(root, entry);
+    const log = spawnSync('git', ['-C', clone, 'log', '-1', '--format=%cs'], { timeout: EXEC_TIMEOUT, encoding: 'utf8' });
+    const fetched = log.status === 0 && log.stdout.trim()
+      ? log.stdout.trim()
+      : fs.statSync(manifest).mtime.toISOString().slice(0, 10);
+
+    const source = String(plugin.source ?? '');
+    const offered = source.startsWith('.')
+      ? readJson(path.join(clone, source, '.claude-plugin', 'plugin.json')).value?.version ?? null
+      : null;
+
+    return { version: offered, clone: entry, fetched, remote: !source.startsWith('.') };
+  }
+
+  return null;
+}
+
+function probeVersion() {
+  const manifest = path.join(PLUGIN_ROOT, '.claude-plugin', 'plugin.json');
+  if (!fs.existsSync(manifest)) {
+    return { host: 'all', status: 'absent', detail: 'not a plugin install — nothing to compare a version against' };
+  }
+
+  const installed = readJson(manifest).value?.version ?? null;
+  const market = marketplaceVersion('condux');
+
+  if (!installed) return { host: 'all', status: 'broken', detail: 'plugin.json carries no version', fix: 'reinstall the plugin' };
+  if (!market) return { host: 'all', status: 'absent', detail: `installed ${installed}; no local marketplace clone to compare against` };
+  if (!market.version) {
+    const why = market.remote ? 'its source is remote and this check never fetches' : 'its manifest carries no version';
+
+    return { host: 'all', status: 'absent', detail: `installed ${installed}; marketplace clone ${market.clone} offers no comparable version — ${why}` };
+  }
+
+  const order = compareVersions(installed, market.version);
+  const stamp = `marketplace clone ${market.clone} as of ${market.fetched}`;
+
+  if (order < 0) {
+    return {
+      host: 'all',
+      status: 'broken',
+      detail: `installed ${installed}, marketplace offers ${market.version} (${stamp})`,
+      fix: '/plugin update condux@jabworks-agentic-toolkit',
+    };
+  }
+
+  const lead = order > 0 ? ` (ahead of marketplace ${market.version} — local build)` : '';
+
+  return { host: 'all', status: 'done', detail: `installed ${installed}${lead}; ${stamp}` };
+}
+
+const WIDTH_HOST = 10;
+const WIDTH_STATUS = 8;
+
+function report(rows, quiet) {
+  for (const row of rows) {
+    if (quiet && row.status === 'done') continue;
+    process.stdout.write(
+      row.host.padEnd(WIDTH_HOST) + ' ' + row.status.padEnd(WIDTH_STATUS) + ' ' + row.detail + '\n',
+    );
+    if (row.fix) {
+      process.stdout.write(' '.repeat(WIDTH_HOST + WIDTH_STATUS + 2) + '↳ ' + row.fix + '\n');
+    }
+  }
+}
+
+function summarize(rows) {
+  const broken = rows.filter((row) => row.status === 'broken').length;
+  const warned = rows.filter((row) => row.status === 'warn').length;
+  // A warning never claims a clean bill of health, and never withholds one
+  // either: condux works, something else on this machine competes with it.
+  const clean = warned === 0 ? 'condux is healthy on every host present' : `condux is healthy on every host present, with ${warned} warning(s)`;
+  const verdict = broken === 0 ? clean : `${broken} probe(s) broken`;
+
+  return `\n${verdict} — probes are static-parse plus execution; they cannot prove the host invoked anything.\n`;
+}
+
+// --fix performs no registration itself: it runs condux's installer and probes
+// again, so idempotency, backups and atomic writes stay in one place. The
+// installer's own verify beat calls this doctor back with --host <h> --quiet
+// and never --fix, so the two cannot ping-pong.
+function findInstaller() {
+  return firstExisting([
+    path.join(PLUGIN_ROOT, 'install.mjs'),
+    path.join(SKILL_BASE, '..', '..', 'plugins', 'condux', 'install.mjs'),
+  ]);
+}
+
+function runInstaller(only) {
+  const installer = findInstaller();
+  if (!installer) {
+    process.stdout.write('no install.mjs found beside this plugin — nothing to run for --fix\n\n');
+
+    return;
+  }
+
+  const args = [installer];
+  if (only) args.push('--host', only);
+
+  process.stdout.write(`running ${installer}${only ? ` --host ${only}` : ''}\n`);
+  const result = spawnSync(process.execPath, args, { timeout: 60000, encoding: 'utf8' });
+
+  // Report the delegate's failure rather than re-probing in silence: `running …`
+  // followed by nothing reads as a repair that happened.
+  if (result.error) process.stdout.write(`the installer could not be run: ${result.error.message}\n`);
+  else if (result.signal) process.stdout.write(`the installer was killed by ${result.signal}\n`);
+  else if (result.status !== 0) process.stdout.write(`the installer exited ${result.status}\n`);
+
+  process.stdout.write('\n');
+}
+
+function main(argv) {
+  const flags = parseFlags(argv);
+  if (flags.help) {
+    process.stdout.write(USAGE);
+
+    return 0;
+  }
+
+  if (!findHook('session-start.mjs')) {
+    report([{ host: 'all', status: 'broken', detail: `condux's hooks are not reachable from ${SKILL_BASE}` }], false);
+
+    return 2;
+  }
+
+  const only = typeof flags.host === 'string' ? flags.host : null;
+  if (flags.fix === true) runInstaller(only);
+
+  // Detected after the installer runs — it may have created a host directory
+  // that was not there when this process started.
+  const hosts = detectHosts();
+  const perHost = [
+    ['claude', () => probeClaude(hosts)],
+    ['codex', () => probeCodex(hosts)],
+    ['opencode', () => probeOpencode(hosts)],
+  ];
+
+  const rows = perHost.filter(([host]) => !only || host === only).map(([, probe]) => probe());
+  if (!only) rows.push(probeAgents(), probeVersion(), probeConflicts(hosts));
+
+  report(rows, flags.quiet === true);
+  process.stdout.write(summarize(rows));
+
+  return rows.some((row) => row.status === 'broken') ? 1 : 0;
+}
+
+process.exit(main(process.argv.slice(2)));

package/skills/condux-doctor/evals/trigger_eval.json

@@ -0,0 +1,17 @@
+[
+  { "query": "is condux actually working on this machine?", "should_trigger": true, "expected_skill": "condux-doctor" },
+  { "query": "check my condux install", "should_trigger": true, "expected_skill": "condux-doctor" },
+  { "query": "the routing rule stopped showing up at session start", "should_trigger": true, "expected_skill": "condux-doctor" },
+  { "query": "did the condux SessionStart hook actually fire?", "should_trigger": true, "expected_skill": "condux-doctor" },
+  { "query": "the specialist agents are missing after I updated the plugin", "should_trigger": true, "expected_skill": "condux-doctor" },
+  { "query": "run a health check on condux", "should_trigger": true, "expected_skill": "condux-doctor" },
+  { "query": "verify condux registered properly on codex", "should_trigger": true, "expected_skill": "condux-doctor" },
+  { "query": "add a search filter to the invoice table", "should_trigger": true, "expected_skill": "workflow" },
+  { "query": "how do condux tiers work?", "should_trigger": true, "expected_skill": "workflow" },
+  { "query": "why isn't my skill triggering", "should_trigger": true, "expected_skill": "toolkit-debugging-playbook" },
+  { "query": "dist drifted from skills after my edit", "should_trigger": true, "expected_skill": "toolkit-debugging-playbook" },
+  { "query": "what should I work on next?", "should_trigger": true, "expected_skill": "groom" },
+  { "query": "what is a git hook?", "should_trigger": false, "expected_skill": null },
+  { "query": "my laptop fan is loud when node runs", "should_trigger": false, "expected_skill": null },
+  { "query": "check the health of the kubernetes cluster", "should_trigger": false, "expected_skill": null }
+]

package/skills/draft-plan/evals/trigger_eval.json

@@ -16,7 +16,7 @@
   { "query": "review the plan in the browser before implementing", "should_trigger": true, "expected_skill": "plan-review" },
   { "query": "execute the plan with agents", "should_trigger": true, "expected_skill": "subagent-execution" },
   { "query": "design isnt agreed yet, help me align first", "should_trigger": true, "expected_skill": "discovery" },
-  { "query": "add a task to my todo list", "should_trigger": false, "expected_skill": null },
+  { "query": "add a task to my todo list", "should_trigger": false, "expected_skill": null, "accept": ["record"] },
   { "query": "plan my sprint for next week", "should_trigger": false, "expected_skill": null },
   { "query": "make a project timeline gantt chart", "should_trigger": false, "expected_skill": null }
 ]

package/skills/plan-review/references/install-codex-hook.sh

@@ -1,28 +1,37 @@
 #!/usr/bin/env bash
-# Install the plan-review Stop hook into Codex.
+# Install (or remove) the plan-review Stop hook in Codex.
 #
 # Codex has no ExitPlanMode interception point, so plan review runs off Codex's
 # experimental `Stop` hook: when a planning turn ends, annotate-server.js
 # (--codex-stop) opens the review UI and returns a continuation reason on deny.
 #
 # This script:
-#   1. validates and merges a Stop hook into <CODEX_HOME>/hooks.json pointing at
-#      this skill's annotate-server.js (absolute paths — Codex Desktop doesn't
-#      inherit PATH)
+#   1. validates and merges (or removes) a Stop hook entry in
+#      <CODEX_HOME>/hooks.json pointing at this skill's annotate-server.js
+#      (absolute paths — Codex Desktop doesn't inherit PATH)
 #   2. enables the experimental hooks feature in <CODEX_HOME>/config.toml
+#      (install only — hooks.json and the feature flag are shared host state
+#      with other plugins, so uninstall never turns the flag back off)
 #
-# Usage:  bash install-codex-hook.sh
+# Usage:  bash install-codex-hook.sh [--uninstall]
 # Notes:  experimental; disabled on Windows. Restart Codex and trust the hook
 #         after running. Honors $CODEX_HOME (falls back to ~/.codex).
 set -euo pipefail
 umask 077
 
+report() { printf '%-10s %-8s %s\n' "$1" "$2" "$3"; }
+
 SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 SERVER="$SCRIPT_DIR/annotate-server.js"
-[[ -f "$SERVER" ]] || { echo "error: annotate-server.js not found next to this script" >&2; exit 1; }
+
+MODE="install"
+[[ "${1:-}" == "--uninstall" ]] && MODE="uninstall"
+
+# --- 0. detect --------------------------------------------------------------
+[[ -f "$SERVER" ]] || { report codex failed "annotate-server.js not found next to this script"; exit 1; }
 
 NODE_BIN=$(command -v node || true)
-[[ -n "$NODE_BIN" ]] || { echo "error: node not found on PATH" >&2; exit 1; }
+[[ -n "$NODE_BIN" ]] || { report codex failed "node not found on PATH"; exit 1; }
 
 CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
 mkdir -p "$CODEX_HOME"
@@ -30,51 +39,100 @@ CONFIG="$CODEX_HOME/config.toml"
 HOOKS="$CODEX_HOME/hooks.json"
 COMMAND="$NODE_BIN \"$SERVER\" --codex-stop"
 
-# --- 1. validate + merge the Stop hook (idempotent) via node --------------------
-"$NODE_BIN" - "$HOOKS" "$COMMAND" <<'NODE'
+# --- 1. validate + merge/remove the Stop hook (idempotent) via node ---------
+HOOKS_RC=0
+HOOKS_OUT=$("$NODE_BIN" - "$HOOKS" "$COMMAND" "$MODE" <<'NODE'
 const fs = require('fs');
-const [, , hooksPath, command] = process.argv;
+const [, , hooksPath, command, mode] = process.argv;
 let cfg = {};
 try {
   cfg = JSON.parse(fs.readFileSync(hooksPath, 'utf8'));
 } catch (e) {
   if (e.code !== 'ENOENT') {
-    console.error('error: refusing to overwrite invalid hooks JSON at ' + hooksPath + ': ' + e.message);
+    console.error('refusing to overwrite invalid hooks JSON at ' + hooksPath + ': ' + e.message);
     process.exit(1);
   }
 }
 if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) {
-  console.error('error: hooks config must be a JSON object: ' + hooksPath);
+  console.error('hooks config must be a JSON object: ' + hooksPath);
   process.exit(1);
 }
 if (cfg.hooks === undefined) cfg.hooks = {};
 if (!cfg.hooks || typeof cfg.hooks !== 'object' || Array.isArray(cfg.hooks)) {
-  console.error('error: "hooks" must be a JSON object: ' + hooksPath);
+  console.error('"hooks" must be a JSON object: ' + hooksPath);
   process.exit(1);
 }
 if (cfg.hooks.Stop === undefined) cfg.hooks.Stop = [];
 if (!Array.isArray(cfg.hooks.Stop)) {
-  console.error('error: "hooks.Stop" must be an array: ' + hooksPath);
+  console.error('"hooks.Stop" must be an array: ' + hooksPath);
   process.exit(1);
 }
-const has = JSON.stringify(cfg.hooks.Stop).includes('--codex-stop');
-if (!has) {
-  cfg.hooks.Stop.push({ hooks: [{ type: 'command', command, timeout: 345600 }] });
-  const tmp = hooksPath + '.tmp-' + process.pid;
-  let mode = 0o600;
-  try { mode = fs.statSync(hooksPath).mode & 0o777; } catch (e) {
-    if (e.code !== 'ENOENT') throw e;
+
+// Marker used to find our own entry again — matching on the command string
+// (never array position) keeps this from touching Stop entries any other
+// plugin (e.g. concord) registered on the same shared hooks.json.
+const isOurs = (entry) => JSON.stringify(entry).includes('--codex-stop');
+
+let changed;
+if (mode === 'uninstall') {
+  const before = cfg.hooks.Stop.length;
+  cfg.hooks.Stop = cfg.hooks.Stop.filter((e) => !isOurs(e));
+  changed = cfg.hooks.Stop.length !== before;
+  if (!changed) {
+    process.stdout.write('skipped\tno --codex-stop entry found in ' + hooksPath + '\n');
+    process.exit(0);
   }
-  fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2) + '\n', { mode });
-  fs.chmodSync(tmp, mode);
-  fs.renameSync(tmp, hooksPath);
-  console.log('set   merged Stop hook into ' + hooksPath);
+  // An empty array still reads as "a Stop hook is registered here" to the
+  // next reader, and an empty hooks object the same way for "hooks" — drop
+  // both rather than leave a stub behind.
+  if (cfg.hooks.Stop.length === 0) delete cfg.hooks.Stop;
+  if (Object.keys(cfg.hooks).length === 0) delete cfg.hooks;
 } else {
-  console.log('ok    Stop hook already present in ' + hooksPath);
+  const has = cfg.hooks.Stop.some(isOurs);
+  if (has) {
+    process.stdout.write('skipped\tStop hook already present in ' + hooksPath + '\n');
+    process.exit(0);
+  }
+  cfg.hooks.Stop.push({ hooks: [{ type: 'command', command, timeout: 345600 }] });
+  changed = true;
 }
+
+const tmp = hooksPath + '.tmp-' + process.pid;
+let fileMode = 0o600;
+try { fileMode = fs.statSync(hooksPath).mode & 0o777; } catch (e) {
+  if (e.code !== 'ENOENT') throw e;
+}
+fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2) + '\n', { mode: fileMode });
+fs.chmodSync(tmp, fileMode);
+fs.renameSync(tmp, hooksPath);
+process.stdout.write(
+  'done\t' + (mode === 'install' ? 'merged' : 'removed') + ' the Stop hook in ' + hooksPath + '\n',
+);
 NODE
+) || HOOKS_RC=$?
+
+if [[ "$HOOKS_RC" -ne 0 ]]; then
+  report codex failed "could not update $HOOKS (reason above); nothing was changed"
+  exit 1
+fi
+report codex "${HOOKS_OUT%%$'\t'*}" "${HOOKS_OUT#*$'\t'}"
 
-# --- 2. enable the hooks feature ------------------------------------------------
+if [[ "$MODE" == "uninstall" ]]; then
+  # [features] hooks = true is shared host state — concord's installer and
+  # condux's front door both read and write it, and none of the three owns
+  # it. Report whether it's still on without touching it either way.
+  if [[ -f "$CONFIG" ]] && grep -Eq '^[[:space:]]*hooks[[:space:]]*=[[:space:]]*true' "$CONFIG"; then
+    report features warn "hooks = true left as-is in $CONFIG — concord and condux may still need it"
+  else
+    report features absent "hooks feature not enabled in $CONFIG"
+  fi
+
+  echo ""
+  echo "done. Restart Codex to drop the hook."
+  exit 0
+fi
+
+# --- 2. enable the hooks feature (install only) ------------------------------
 if [[ -f "$CONFIG" ]] && grep -Eq '^[[:space:]]*\[features\][[:space:]]*($|#)' "$CONFIG"; then
   cp -p "$CONFIG" "$CONFIG.tmp"
   awk '
@@ -99,10 +157,10 @@ if [[ -f "$CONFIG" ]] && grep -Eq '^[[:space:]]*\[features\][[:space:]]*($|#)' "
     }
     END { if (in_features && !hooks_written) print "hooks = true" }
   ' "$CONFIG" > "$CONFIG.tmp" && mv "$CONFIG.tmp" "$CONFIG"
-  echo "set   ensured hooks = true under existing [features] in $CONFIG"
+  report features done "ensured hooks = true under existing [features] in $CONFIG"
 else
   printf '\n[features]\nhooks = true\n' >> "$CONFIG"
-  echo "set   added [features] hooks = true to $CONFIG"
+  report features done "added [features] hooks = true to $CONFIG"
 fi
 
 echo ""
@@ -110,3 +168,5 @@ echo "done. Next steps:"
 echo "  1. Restart Codex (and Codex Desktop if used)."
 echo "  2. Codex will ask you to trust the hook definition — approve it."
 echo "  3. Enter plan mode; when the planning turn ends, the review UI opens."
+echo ""
+echo "To undo:  bash \"$0\" --uninstall"

package/skills/subagent-execution/references/install-codex-agents.mjs

@@ -10,6 +10,7 @@
 //
 // Usage:
 //   node install-codex-agents.mjs [--codex-home <dir>] [--dry-run]
+//   node install-codex-agents.mjs --uninstall [--codex-home <dir>] [--dry-run]
 //
 // Behavior:
 //   - description = the .md frontmatter description prose (Claude-style
@@ -21,6 +22,14 @@
 //     workspace-write for planner/coder
 //   - existing files are backed up to <name>.toml.bak first
 //
+// --uninstall removes exactly the .toml files this installer would have
+// written — the names are derived from the same ../agents/*.md frontmatter,
+// never hardcoded, since the agent set has already changed once. It never
+// touches unrelated files a user placed in agents/ by hand, and it removes
+// the agents/ directory itself only if that leaves it empty (plain rmdir,
+// never recursive). It does not read or write config.toml — the
+// [features] hooks flag is shared host state this script does not own.
+//
 // Schema per https://developers.openai.com/codex/subagents (verified
 // 2026-07-08): required name/description/developer_instructions; a custom
 // agent named like a built-in (e.g. explorer) takes precedence over it.
@@ -32,6 +41,7 @@ import { fileURLToPath } from 'node:url';
 
 const args = process.argv.slice(2);
 const DRY = args.includes('--dry-run');
+const UNINSTALL = args.includes('--uninstall');
 const homeIdx = args.indexOf('--codex-home');
 const CODEX_HOME = homeIdx >= 0 ? args[homeIdx + 1] : (process.env.CODEX_HOME || path.join(os.homedir(), '.codex'));
 const DEST = path.join(CODEX_HOME, 'agents');
@@ -50,7 +60,8 @@ function fmField(block, key) {
   return m ? m[1].trim().replace(/^['"]|['"]$/g, '') : null;
 }
 
-if (!DRY) fs.mkdirSync(DEST, { recursive: true });
+// --uninstall must never create the directory it is trying to remove.
+if (!DRY && !UNINSTALL) fs.mkdirSync(DEST, { recursive: true });
 
 for (const file of fs.readdirSync(AGENTS_DIR).filter((f) => f.endsWith('.md'))) {
   const src = fs.readFileSync(path.join(AGENTS_DIR, file), 'utf8');
@@ -58,6 +69,28 @@ for (const file of fs.readdirSync(AGENTS_DIR).filter((f) => f.endsWith('.md')))
   if (!fm) { console.error(`skip ${file}: no frontmatter`); continue; }
 
   const name = fmField(fm[1], 'name');
+
+  if (UNINSTALL) {
+    // Same name derivation as install, just aimed at removal — the set of
+    // files this loop owns is exactly the set install would have written.
+    const dest = path.join(DEST, `${name}.toml`);
+    if (!fs.existsSync(dest)) {
+      console.log(`skipped ${dest} (already absent)`);
+      continue;
+    }
+    if (DRY) {
+      console.log(`--- would remove ${dest}`);
+      continue;
+    }
+    try {
+      fs.unlinkSync(dest);
+      console.log(`removed ${dest}`);
+    } catch (err) {
+      console.error(`failed ${dest}: ${err.message}`);
+    }
+    continue;
+  }
+
   let description = fmField(fm[1], 'description') || '';
   // Strip Claude-style example blocks (literal \n escapes inside the YAML
   // string) and unescape what remains into plain prose.
@@ -96,3 +129,18 @@ for (const file of fs.readdirSync(AGENTS_DIR).filter((f) => f.endsWith('.md')))
     console.log(`wrote ${dest}${preserved.length ? '  (preserved: ' + preserved.map((l) => l.split(' ')[0]).join(', ') + ')' : ''}`);
   }
 }
+
+if (UNINSTALL && !DRY) {
+  // Non-recursive on purpose — this only succeeds when every file we didn't
+  // own is also gone, i.e. never for a directory the user is still using.
+  try {
+    fs.rmdirSync(DEST);
+    console.log(`removed ${DEST} (empty)`);
+  } catch (err) {
+    if (err.code === 'ENOTEMPTY') {
+      console.log(`left ${DEST} in place (not empty — files not owned by this installer remain)`);
+    } else if (err.code !== 'ENOENT') {
+      console.error(`warn: could not remove ${DEST}: ${err.message}`);
+    }
+  }
+}