@jabworks/condux 0.5.2 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jabworks/condux",
-  "version": "0.5.2",
+  "version": "0.6.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/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/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)));