@jabworks/condux 0.5.2 → 0.7.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.5.2",
+  "version": "0.7.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/code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: "One-shot code review. Produces a diagnostic report categorized by severity (Critical / Important / Minor). Never fixes issues automatically. On-request only — never auto-triggers. At workflow CP-2 (pre-finalize, on request) or after /finalize, ask once: \"Want a code review before merging?\" Trigger phrases: \"review this\", \"review before merge\", \"check this PR\". Not for reviewing a plan or spec before implementation — that is plan-review. Not for running the change to watch it work — that is live-verification."
+description: "One-shot code review. Produces a diagnostic report categorized by severity (Critical / Important / Minor). Never fixes issues automatically. On-request only — never auto-triggers. At workflow CP-2 or after /finalize, ask once: \"Want a code review before merging?\" Trigger phrases: \"review this\", \"review before merge\", \"check this PR\". Not for a plan or spec before implementation (plan-review); not for running the change to watch it work (live-verification)."
 argument-hint: "<PR URL, diff, branch, or file path>"
 ---
 

package/skills/condux-doctor/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: condux-doctor
+description: "Health check for the condux plugin on the host it is installed on. Probes the SessionStart routing hook on Claude Code and Codex by running it and checking the wire format each host expects, confirms plan-review's Codex Stop hook resolves, checks the OpenCode npm registration and its bundled agents and skills, verifies the four specialist agent definitions shipped, and compares the installed version against the local marketplace clone. Offline and read-only. 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 specialist agents are missing. Run it after installing or updating the plugin. 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]"
+---
+
+# /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
+```
+
+Exit 0 when nothing is broken, 1 when something is, 2 when the doctor cannot
+find condux's own hooks.
+
+## 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. 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.
+- **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.
+
+## 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/doctor.mjs

@@ -0,0 +1,425 @@
+#!/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';
+
+const USAGE = `usage: doctor [options]
+
+  --host <claude|codex|opencode>   probe one host only
+  --quiet                          print only broken and absent rows
+`;
+
+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: 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',
+  });
+}
+
+function probeCodex(hosts) {
+  if (!hosts.codex) return { host: 'codex', status: 'absent', detail: 'no ~/.codex on this machine' };
+
+  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' };
+}
+
+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 verdict = broken === 0 ? 'condux is healthy on every host present' : `${broken} probe(s) broken`;
+
+  return `\n${verdict} — probes are static-parse plus execution; they cannot prove the host invoked anything.\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 hosts = detectHosts();
+  const only = typeof flags.host === 'string' ? flags.host : null;
+  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());
+
+  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/discovery/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: discovery
-description: "Refine a rough idea into a signed-off design. Asks goal-level questions, surfaces alternatives, then runs a post-approach detail round (contracts, mappings, edge cases) that feeds the tech spec (written via technical-spec at sign-off); presents the design in sections for sign-off before any planning or code begins. Trigger for LARGE tasks, when scope is unclear, or when the user wants to brainstorm or explore a rough idea. Also when resuming or continuing an existing design or design doc — the existing-design check offers resume-or-fresh. Acts as a soft gate before /draft-plan — if discovery hasn't run, ask the user if they want to skip it consciously."
+description: "Refine a rough idea into a signed-off design, presented in sections for sign-off before any planning or code begins. Feeds the tech spec, written via technical-spec at sign-off. Trigger for LARGE tasks, when scope is unclear, or when the user wants to brainstorm or explore a rough idea. Also when resuming an existing design or design doc — the existing-design check offers resume-or-fresh. A soft gate before /draft-plan: if discovery has not run, ask whether to skip it consciously."
 argument-hint: "<rough idea or feature description>"
 effort: high
 ---

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/live-verification/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: live-verification
-description: "Verify a change by actually running it — drive the real UI or endpoint, check each claim against observed behaviour, and capture evidence before pushing. Detects what's runnable, checks light mode then dark, and reports claim → evidence → verdict with unverifiable claims named rather than hidden. After /finalize, before committing, pushing, or merging a change that has a runnable surface — UI, page, component, endpoint, CLI. Triggers include \"verify it live\", \"did this actually work\", \"check it in the browser\", \"verify on preview\", \"check the preview env then merge\", \"live verify before pushing\", \"does it render right\". Not for typecheck/lint/test (that's finalize), not for auditing plan completeness (preflight), not for reading code to judge it (code-review)."
+description: "Verify a change by actually running it — drive the real UI or endpoint, check each claim against observed behaviour, and capture evidence before pushing. After /finalize, before committing, pushing, or merging a change with a runnable surface — UI, page, component, endpoint, CLI. Triggers include \"verify it live\", \"did this actually work\", \"check it in the browser\", \"verify on preview\", \"live verify before pushing\", \"does it render right\". Not for typecheck/lint/test (finalize), auditing plan completeness (preflight), or reading code to judge it (code-review)."
 argument-hint: "[what to verify — optional; defaults to the current diff]"
 ---
 

package/skills/plan-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan-review
-description: "Render a plan in a local browser for inline annotation, then return an approve / request-revisions / deny decision to the agent. Auto-captures the plan via a Claude Code ExitPlanMode hook or a Codex Stop hook, or runs manually on any markdown file or spec directory. Self-contained — no network egress, no third-party runtime deps. When the agent finishes planning (Claude Code ExitPlanMode, or a Codex planning turn) and you want to review/annotate before it implements, or when you invoke /plan-review on a markdown plan or spec directory. Also owns its own machinery — steer-mode review loops, the live spec preview, and installing or troubleshooting the ExitPlanMode / Codex Stop hooks. Phrases include \"let's review the plan\", \"walk me through the plan before we build\", \"annotate the plan\" — use these when the ExitPlanMode or Codex Stop hook doesn't fire. Not for cataloging a whole specs tree; use spec-browser. Not for the implemented diff; use code-review."
+description: "Render a plan in a local browser for inline annotation, then return an approve / request-revisions / deny decision to the agent. Auto-captured via a Claude Code ExitPlanMode or Codex Stop hook, or run manually on a markdown file or spec directory. When the agent finishes planning and you want to review or annotate before it implements, or on /plan-review for a markdown plan or spec directory. Also owns its machinery — steer-mode loops, the live spec preview, and installing or troubleshooting the ExitPlanMode / Codex Stop hooks. Phrases: \"let's review the plan\", \"walk me through the plan\", \"annotate the plan\". Not for cataloging a whole specs tree (spec-browser); not for the implemented diff (code-review)."
 ---
 
 # /plan-review

package/skills/preflight/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: preflight
-description: "Lightweight \"am I actually done?\" checklist before calling /finalize. Prevents premature completion — catches skipped steps, missing behavior, and silent regressions. Runs before /finalize at the end of every /workflow tier (automatic on SMALL; the recommended CP-2 choice on MEDIUM/LARGE). Also trigger standalone on \"verify this\", \"am I done?\", or \"preflight\". Not for executing typecheck, lint, format, and tests; use finalize. Not for actually running the change and observing it work in a browser or CLI; that's live-verification, after finalize."
+description: "Lightweight \"am I actually done?\" checklist before calling /finalize. Prevents premature completion — catches skipped steps, missing behavior, and silent regressions. Runs before /finalize at the end of every /workflow tier (automatic on SMALL; the recommended CP-2 choice on MEDIUM/LARGE). Also standalone on \"verify this\", \"am I done?\", \"preflight\". Not for executing typecheck, lint, format, and tests (finalize); not for running the change and observing it work (live-verification, after finalize)."
 argument-hint: "[task or feature name]"
 ---
 

package/skills/subagent-deployment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: subagent-deployment
-description: "Fan out 2+ independent tasks across named agents (explorer/researcher/planner/coder) in a single message when they share no files and no dependencies. Use for ad-hoc independent work discovered outside a formal plan — unrelated bug fixes, parallel lookups, independent small tasks. Trigger when two or more genuinely independent tasks are on the table — nothing shared between them, no ordering — and any mix of named agents fits. Not for executing an ordered plan task-by-task (that's subagent-execution)."
+description: "Fan out 2+ independent tasks across named agents (explorer/researcher/planner/coder) in a single message when they share no files and no dependencies. For ad-hoc independent work discovered outside a formal plan. Trigger when two or more genuinely independent tasks are on the table — nothing shared between them, no ordering — and any mix of named agents fits. Not for executing an ordered plan task-by-task (that's subagent-execution)."
 argument-hint: "<list of independent tasks>"
 ---
 

package/skills/subagent-execution/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: subagent-execution
-description: "Execute a plan using named specialist agents. Default is to implement yourself — only spawn when there is a concrete justification. Agents must be pre-defined; never create generic subagents with injected system prompts. Trigger when implementing a LARGE plan with tasks that benefit from agent specialization or parallel exploration — including task briefs, review packages, spawn rules, and resuming an interrupted plan from the `.condux/progress/` ledger (not session-handoff). Not for ad-hoc independent tasks outside a plan (that's subagent-deployment)."
+description: "Execute a plan using named specialist agents. Default is to implement yourself — only spawn when there is a concrete justification. Trigger when implementing a LARGE plan with tasks that benefit from agent specialization or parallel exploration — including task briefs, review packages, spawn rules, and resuming an interrupted plan from the `.condux/progress/` ledger (not session-handoff). Not for ad-hoc independent tasks outside a plan (that's subagent-deployment)."
 argument-hint: "<plan file path>"
 ---
 
@@ -16,6 +16,12 @@ Execute a plan using specialist agents. Default is to do the work yourself. Spaw
 
 ## Core Principle
 
+**Agents must be pre-defined.** Spawn only the named agents that ship with condux
+(`explorer`, `researcher`, `planner`, `coder`). Never invent a generic subagent by
+injecting a system prompt into a general-purpose one — an agent whose behaviour is
+written at call time has no reviewable contract, no consistent tool restrictions,
+and no way to improve across sessions.
+
 **You implement by default.** Spawning is an explicit decision with a stated reason — not the default mode of operation.
 
 ```

package/skills/test-first-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test-first-development
-description: "Tests-first development — write tests before implementation. Opt-in only. Get one upfront consent (write tests first + auto-run), then run the cycle without re-asking. Still always ask before updating existing test specs. Never silently rewrite test specs to match new behavior. Trigger when the user explicitly asks for tests-first, picks it at a workflow checkpoint, or when implementing logic with clear input/output behavior. Also triggers whenever an existing test spec is about to be edited to make it pass — that decision runs through this skill."
+description: "Tests-first development — write tests before implementation. Opt-in only: one upfront consent (write tests first + auto-run), then run the cycle without re-asking. Trigger when the user explicitly asks for tests-first, picks it at a workflow checkpoint, or when implementing logic with clear input/output behavior. Also triggers whenever an existing test spec is about to be edited to make it pass — that decision runs through this skill."
 argument-hint: "<what to test>"
 ---
 

package/skills/workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workflow
-description: "Routes any dev task into the right execution tier (Small/Medium/Large) and carries condux's operating rules — proportional effort, lazy skill loading, soft gates, implement-yourself-by-default. Confirms the tier with the user, then executes the matching flow, loading downstream skills only when a step needs them. Trigger with any implementation request — feature, bug fix, refactor, new endpoint, UI change. Every dev task starts here; other skills execute within /workflow, not instead of it. Also the operating manual — questions about how condux works, its tiers, soft gates, checkpoints, and named agents."
+description: "Routes any dev task into the right execution tier (Small/Medium/Large) and carries condux's operating rules — proportional effort, lazy skill loading, soft gates, implement-yourself-by-default. Trigger with any implementation request — feature, bug fix, refactor, new endpoint, UI change. Every dev task starts here; other skills execute within /workflow, not instead of it. Also the operating manual — questions about how condux works, its tiers, soft gates, checkpoints, and named agents."
 argument-hint: "<task description>"
 ---
 

package/skills/workflow/hooks/codex-hooks.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/session-start.mjs\" --codex",
+            "additionalContextLimit": 4000
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/skills/condux/plan-review/references/annotate-server.js\" --codex-stop",
+            "timeout": 345600
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills/workflow/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs\" --claude"
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills/workflow/hooks/routing.md

@@ -0,0 +1,28 @@
+<EXTREMELY_IMPORTANT>
+You have condux — this session's agentic workflow system.
+
+**Every implementation request starts at `/condux:workflow`.** Feature, bug fix,
+refactor, new endpoint, UI change, "can you add…", "can you fix…" — all of it
+routes there first. The router infers the tier (Small / Medium / Large), confirms
+it with the user, then executes the matching flow, loading downstream skills only
+when a step needs them.
+
+**These skills execute _within_ workflow, never instead of it:** `discovery`,
+`draft-plan`, `test-first-development`, `subagent-execution`,
+`subagent-deployment`, `preflight`, `finalize`, `code-review`,
+`root-cause-analysis`, `live-verification`, `plan-review`, `technical-spec`.
+
+If you find yourself reaching for one of those as the *first* skill of a task,
+you have skipped the router — go back to `/condux:workflow`. Debugging is the
+most common miss: a crash report, a stack trace, or "why does this fail" is
+still a dev task, so it routes through workflow, which loads
+`root-cause-analysis` at the right moment.
+
+**Not a valid bypass:** your own judgment that a task "seems small". Tier
+inference is the router's job, not yours. The only valid bypasses are explicit
+user instructions — "skip workflow", "just do it", "I've already planned this".
+
+**Not everything is a dev task.** Questions, explanations, code reading, research,
+and one-line factual answers route nowhere — answer them directly. Routing a
+conversation through a workflow is as wrong as skipping the router on a feature.
+</EXTREMELY_IMPORTANT>

package/skills/workflow/hooks/session-start.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// SessionStart hook: puts condux's routing rule in context before the first
+// prompt, so /workflow is reached as the entry point rather than inferred from
+// the skill catalog.
+//
+// Why this exists: the trigger evals (scripts/eval-triggers.mjs, reports in
+// skills/toolkit-research-frontier/references/) put workflow at ~26-27/33 on
+// catalog inference alone. The misses are not silence — they are condux's own
+// siblings winning the query (root-cause-analysis on a crash report, draft-plan
+// on "write the plan", code-review on "fix the findings"). That collision cannot
+// be fixed by strengthening workflow's description without stealing trigger
+// space from those siblings, which toolkit-skill-standards forbids. An
+// always-in-context instruction outranks catalog inference, so the rule goes
+// here instead.
+//
+// The payload is routing.md, edited as prose — never inlined here.
+//
+// Host contracts differ, so the host is passed explicitly rather than sniffed
+// from the environment:
+//   --claude  Claude Code wants a JSON envelope on stdout
+//   --codex   Codex injects raw stdout (bounded by additionalContextLimit)
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+// Resolved relative to this file, not to a plugin-root env var: the script and
+// its payload ship together, so they move together.
+const PAYLOAD = path.join(HERE, 'routing.md');
+
+function main(argv) {
+  let text;
+  try {
+    text = fs.readFileSync(PAYLOAD, 'utf8').trim();
+  } catch {
+    // A hook that breaks the session is worse than a hook that does nothing.
+    // Exit clean and let the skill catalog do its ~80% job.
+    return 0;
+  }
+  if (text === '') return 0;
+
+  if (argv.includes('--codex')) {
+    process.stdout.write(text + '\n');
+    return 0;
+  }
+
+  // Default to Claude Code's envelope. JSON.stringify handles the escaping that
+  // shell-based versions of this hook get wrong.
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: text,
+    },
+  }) + '\n');
+  return 0;
+}
+
+process.exit(main(process.argv.slice(2)));