@jabworks/condux 0.2.0 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hieu Vi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,37 +1,30 @@
 # @jabworks/condux
 
 OpenCode plugin for the [condux](https://github.com/jabworks/agentic-toolkit)
-workflow toolkit. It provides two pieces that OpenCode cannot pick up from a
-skill tree alone:
-
+workflow toolkit. One plugin line installs everything condux needs:
+
+- **Skills** — bundles the 12 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
+  `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.
 - **Agents** — injects the four condux specialist agents (`coder`, `explorer`,
-  `planner`, `researcher`) as subagents via the `config` hook, carrying the tool
+  `planner`, `researcher`) as subagents via the same hook, carrying the tool
   restrictions their canonical definitions declare: `explorer` and `researcher`
   are read-only (no `edit`, `write`, or `bash`) and `planner` cannot run shell
   commands. If your `opencode.json` already defines an agent with the same name,
   yours wins — injection is skip-if-present.
 - **Plan-review listener (opt-in)** — with `CONDUX_PLAN_REVIEW=1`, when the
   primary `plan` agent finishes a turn, spawns the plan-review annotate server
-  from your installed condux skills. Best-effort: OpenCode does not await event
-  hooks, so this cannot block the next turn on the review outcome (unlike the
-  Codex Stop hook).
+  (from the bundled skills, or any discoverable skill tree). Best-effort:
+  OpenCode does not await event hooks, so this cannot block the next turn on the
+  review outcome (unlike the Codex Stop hook).
 
 ## Install
 
-### 1. Install skills
-
-Install the OpenCode-facing skill variants (trigger conditions folded into each
-description):
-
-```sh
-npx skills add https://github.com/jabworks/agentic-toolkit/tree/main/dist/opencode/skills -a opencode
-```
-
-This copies skills into `~/.config/opencode/skills/`.
-
-### 2. Add the plugin
-
-Add `@jabworks/condux` to your `opencode.json`:
+Add `@jabworks/condux` to your `opencode.json` and restart OpenCode:
 
 ```jsonc
 // opencode.json
@@ -40,7 +33,13 @@ Add `@jabworks/condux` to your `opencode.json`:
 }
 ```
 
-Restart OpenCode after adding the plugin.
+That's the whole install — skills and agents come with the plugin. The other
+agentic-toolkit skills (git-commit, session-handoff, release, spec-browser, …)
+are not part of condux; install those separately if you want them:
+
+```sh
+npx skills add https://github.com/jabworks/agentic-toolkit/tree/main/dist/opencode/skills -a opencode
+```
 
 ## Notes
 
@@ -54,12 +53,11 @@ Restart OpenCode after adding the plugin.
   (`edit` covers edit/write/patch). Read-side tools keep OpenCode's defaults,
   because the Claude allowlists omit `Grep`/`Glob` while the prompts still expect
   to search — denying those would break the agents rather than constrain them.
-- The plan-review listener needs the `plan-review` skill installed in a
-  discoverable skill tree (`.opencode/skills/`, `.agents/skills/`,
-  `.claude/skills/`, or their global equivalents) — it runs
-  `plan-review/references/annotate-server.js` from there.
+- The plan-review listener finds `plan-review/references/annotate-server.js` in
+  the bundled skills first, then any discoverable skill tree (`.opencode/skills/`,
+  `.agents/skills/`, `.claude/skills/`, or their global equivalents).
 - OpenCode caches npm plugins under `~/.cache/opencode/`. If an upgrade seems
   to have no effect, clear that cache and restart OpenCode.
-- The agent definitions in `agents/` are generated from the toolkit's canonical
-  sources — edit them in `skills/subagent-execution/agents/` in the toolkit
-  repo, not here.
+- The `agents/` and `skills/` trees are generated from the toolkit's canonical
+  sources by `scripts/build-opencode.mjs` — edit the sources in the toolkit repo
+  (`skills/subagent-execution/agents/` and `skills/<name>/`), not here.

package/index.js

@@ -7,6 +7,12 @@
 // including the tool restrictions those sources declare.
 // User-defined agents with the same name always win — injection is skip-if-present.
 //
+// The same `config` hook registers the bundled skills/ tree (the 12 condux
+// skills, generated alongside the agents) onto config.skills.paths, so
+// `plugin: ["@jabworks/condux"]` alone installs both agents and skills — no
+// separate `npx skills add` step for condux. This works because the config hook
+// mutates the cached config before OpenCode lazily discovers skills.
+//
 // Optional plan-review listener (CONDUX_PLAN_REVIEW=1): when the primary
 // `plan` agent finishes a turn (session.idle), spawns the plan-review annotate
 // server from an installed condux skill tree. Best-effort only — OpenCode does
@@ -21,6 +27,7 @@ import { fileURLToPath } from 'node:url';
 
 const PKG_DIR = path.dirname(fileURLToPath(import.meta.url));
 const AGENTS_DIR = path.join(PKG_DIR, 'agents');
+const SKILLS_DIR = path.join(PKG_DIR, 'skills');
 
 // Bundled agent files use exactly the frontmatter the toolkit generator emits:
 // a JSON-quoted `description`, a plain `mode`, an optional `permission` deny map
@@ -55,6 +62,9 @@ function findAnnotateServer(worktree) {
     path.join(worktree, '.claude', 'skills'),
     path.join(os.homedir(), '.config', 'opencode', 'skills'),
     path.join(os.homedir(), '.claude', 'skills'),
+    // The plan-review skill now also ships bundled in this package, so the
+    // listener works even when the user never ran a separate skills install.
+    SKILLS_DIR,
   ];
   for (const root of roots) {
     const candidate = path.join(root, 'plan-review', 'references', 'annotate-server.js');
@@ -86,6 +96,17 @@ export const ConduxPlugin = async ({ worktree }) => {
           ...(def.permission ? { permission: def.permission } : {}),
         };
       }
+
+      // Register the bundled condux skills so OpenCode discovers them without a
+      // separate install. Guarded on existsSync because a source checkout runs
+      // this file before the generator has produced skills/. Idempotent — the
+      // includes() check keeps re-fires (the hook runs per config load) from
+      // pushing duplicates, and never disturbs a user-provided paths entry.
+      if (existsSync(SKILLS_DIR)) {
+        cfg.skills ??= {};
+        cfg.skills.paths ??= [];
+        if (!cfg.skills.paths.includes(SKILLS_DIR)) cfg.skills.paths.push(SKILLS_DIR);
+      }
     },
 
     'chat.params': async (input) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jabworks/condux",
-  "version": "0.2.0",
-  "description": "OpenCode plugin for the condux workflow toolkit — injects the condux specialist agents (coder, explorer, planner, researcher) and an opt-in plan-review listener.",
+  "version": "0.3.1",
+  "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": {
     "access": "public",
@@ -11,14 +11,16 @@
   "exports": "./index.js",
   "files": [
     "index.js",
-    "agents/"
+    "agents/",
+    "skills/"
   ],
   "keywords": [
     "opencode",
     "opencode-plugin",
     "condux",
     "workflow",
-    "agents"
+    "agents",
+    "skills"
   ],
   "author": "jabworks",
   "repository": {

package/skills/code-review/SKILL.md

@@ -0,0 +1,136 @@
+---
+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. After /finalize, ask once: \"Want a code review before merging?\" Trigger phrases: \"review this\", \"review before merge\", \"check this PR\"."
+argument-hint: "<PR URL, diff, branch, or file path>"
+---
+
+# /code-review
+
+One review pass. Categorized findings. You decide what to action. No fixing, no re-review, no loop.
+
+## Usage
+
+```
+/code-review                    # review current changes
+/code-review <branch or path>   # review specific scope
+```
+
+## When This Runs
+
+After `/finalize` completes, ask once:
+
+> "Want a code review before merging?"
+
+If yes → run this skill.
+If no → done.
+
+Do not ask again. Do not auto-trigger. Do not re-review after fixes unless explicitly requested.
+
+## How It Works
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                       CODE REVIEW                               │
+├──────────────────────────────────────────────────────────────────┤
+│  Step 1: SCOPE                                                  │
+│  Read the diff or changed files.                                │
+│  Understand what the change is trying to do.                    │
+│                                                                  │
+│  Step 2: REVIEW                                                 │
+│  Evaluate across four dimensions (see below).                   │
+│                                                                  │
+│  Step 3: CATEGORIZE                                             │
+│  Assign each finding to Critical, Important, or Minor.         │
+│                                                                  │
+│  Step 4: REPORT AND STOP                                        │
+│  Output the report. Done.                                       │
+│  Do not fix anything. Do not suggest re-reviewing.             │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Review Dimensions
+
+**Security**
+
+- Auth and authorization gaps
+- Injection risks (SQL, XSS, CSRF)
+- Secrets or credentials in code
+- Unsafe deserialization, path traversal, SSRF
+
+**Correctness**
+
+- Edge cases (null, empty, overflow, concurrent access)
+- Error handling and propagation
+- Off-by-one errors
+- Type safety gaps not caught by the type system
+
+**Performance**
+
+- N+1 queries
+- Unbounded loops or queries
+- Unnecessary re-renders or allocations
+- Missing indexes
+
+**Maintainability**
+
+- Naming clarity
+- Single responsibility violations
+- Duplication
+- Non-obvious logic without explanation
+
+## Severity Definitions
+
+| Severity         | Meaning                                                                          |
+| ---------------- | -------------------------------------------------------------------------------- |
+| 🔴 **Critical**  | Must fix before merging. Security risk, data loss potential, or broken behavior. |
+| 🟡 **Important** | Should fix soon. Not a blocker today, but will cause problems.                   |
+| 🔵 **Minor**     | Worth noting. Style, small improvements, future-proofing.                        |
+| ✅ **Good**      | Patterns worth keeping. Positive signal.                                         |
+
+## Output Format
+
+```markdown
+## Code Review: [feature or branch name]
+
+### Summary
+
+[1-2 sentences: what the change does and overall quality signal]
+
+### Findings
+
+| Severity     | File               | Line | Finding       |
+| ------------ | ------------------ | ---- | ------------- |
+| 🔴 Critical  | `path/to/file.ts`  | 42   | [description] |
+| 🟡 Important | `path/to/other.ts` | 18   | [description] |
+| 🔵 Minor     | `path/to/file.ts`  | 67   | [description] |
+
+### What Looks Good
+
+- [Positive observations]
+
+### Verdict
+
+[Approve / Request Changes]
+```
+
+## What Does NOT Happen
+
+```
+✗ Auto-triggering after finalize without asking
+✗ Fixing any finding automatically
+✗ Requesting a re-review after fixes
+✗ Looping: review → fix → re-review → fix → re-review
+✗ Blocking merge on Minor findings
+✗ Spawning a reviewer subagent (do the review inline)
+```
+
+## After the Report
+
+The report is yours to action. Common next steps:
+
+- **Critical findings** → fix via `/workflow` (new SMALL task), then decide if you want another review
+- **Important findings** → create a follow-up task or fix now, your call
+- **Minor findings** → note for later or ignore, your call
+- **Nothing blocking** → merge
+
+The agent does not manage this process. You do.

package/skills/code-review/evals/trigger_eval.json

@@ -0,0 +1,22 @@
+[
+  { "query": "review this before merging", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "code review the diff", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "check this PR", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "review branch feature/sso", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "any security issues in this change?", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "give me a severity report on these changes", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "re-review now that I applied the fixes", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "was the approach in this diff right?", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "review this function for perf problems", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "lgtm?", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "find n+1 queries in this diff", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "reveiw pls", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "auto review every commit from now on", "should_trigger": true, "expected_skill": "code-review", "kind": "in-context" },
+  { "query": "keep reviewing in a loop until its perfect", "should_trigger": true, "expected_skill": "code-review", "kind": "in-context" },
+  { "query": "fix the critical findings from the review", "should_trigger": true, "expected_skill": "workflow" },
+  { "query": "review the plan before implementation", "should_trigger": true, "expected_skill": "plan-review" },
+  { "query": "review the spec folder", "should_trigger": true, "expected_skill": "plan-review", "accept": ["spec-browser"] },
+  { "query": "merge it into main", "should_trigger": true, "expected_skill": "git-operations" },
+  { "query": "review my resume", "should_trigger": false, "expected_skill": null },
+  { "query": "what is a csrf token", "should_trigger": false, "expected_skill": null }
+]

package/skills/discovery/SKILL.md

@@ -0,0 +1,242 @@
+---
+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; 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."
+argument-hint: "<rough idea or feature description>"
+effort: high
+---
+
+# /discovery
+
+Turn a rough idea into a clear, agreed-upon design. Nothing gets planned or built until you sign off.
+
+## Usage
+
+```
+/discovery $ARGUMENTS
+```
+
+## How It Works
+
+Before Step 1, check for an existing design: glob `.condux/designs/*<slug>*.md`
+and `specs/<slug>/` (slug = kebab-case of the feature name). If either
+exists, offer: "Found an existing design for this feature at `<path>` —
+resume from there, or start a fresh discovery?" Accept either answer, same
+as any other soft gate in this skill.
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                        DISCOVERY                                │
+├──────────────────────────────────────────────────────────────────┤
+│  Step 1: SCOPE CHECK                                            │
+│  Before asking detailed questions, assess:                      │
+│    - Does this describe multiple independent subsystems?        │
+│      → Flag decomposition opportunity before going deeper       │
+│    - Is the request already well-defined (ticket, spec doc)?    │
+│      → Ask: "This looks well-defined. Skip discovery and       │
+│        go straight to planning?"                                │
+│    - Is the scope genuinely unclear?                            │
+│      → Proceed to Step 2                                        │
+│                                                                  │
+│  Step 2: CLARIFY — GOAL ROUND                                   │
+│  Ask targeted questions — one batch, not one at a time.        │
+│  Focus on: goals, constraints, what "done" looks like,         │
+│  known unknowns, and what should explicitly NOT be built.      │
+│  No implementation detail yet — that's Step 4's job.           │
+│                                                                  │
+│  Step 3: PROPOSE                                                │
+│  Present 2-3 approaches with tradeoffs.                        │
+│  Show design in sections — get acknowledgment per section      │
+│  before moving on.                                              │
+│                                                                  │
+│  Step 4: DETAIL ROUND — feed the spec                           │
+│  With the approach chosen, ask ONE more batch, grouped by      │
+│  spec concern — only concerns this feature touches,            │
+│  max ~2 questions each:                                         │
+│    api.md → contracts, error shapes, external calls            │
+│    fields.md → source-to-UI mappings, transformations          │
+│    quirks.md → edge cases, failure modes, known gotchas        │
+│    implementation.md → key files, patterns to follow           │
+│  Skip the round entirely if nothing is decidable yet.           │
+│                                                                  │
+│  Step 5: INLINE SELF-REVIEW                                     │
+│  Before presenting the final design for sign-off, silently      │
+│  check — and fix anything that fails:                           │
+│    ✓ No placeholders or TBDs in the design                     │
+│    ✓ All requirements covered                                   │
+│    ✓ Out-of-scope items explicitly noted                        │
+│    ✓ No subsystems that should be separate tasks               │
+│    ✓ Every contract, mapping, or edge case named in the        │
+│      design has a home in a spec concern file                   │
+│    ✓ Unanswered detail questions surface as open questions,    │
+│      never silently dropped                                     │
+│                                                                  │
+│  Step 6: SIGN-OFF                                               │
+│  Get explicit approval: "Looks good, proceed to planning"      │
+│  Do not proceed to /draft-plan without this.                    │
+│                                                                  │
+│  Step 7: SAVE DESIGN + SPEC (mandatory)                         │
+│  Write the design summary to                                    │
+│  .condux/designs/YYYY-MM-DD-<feature>.md — this is the         │
+│  artifact /draft-plan's gate check globs for.                   │
+│  Spec write-back is default-on: persist the concern files       │
+│  too (Spec Integration below) unless the user opts out.         │
+│  Then offer the browser review loop (Design Review Loop).       │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Clarifying Questions — Good vs Bad
+
+```
+Good (goal-oriented, unambiguous):
+  ✓ "What does success look like for the user?"
+  ✓ "Are there any libraries or patterns already in use we should follow?"
+  ✓ "What should this explicitly NOT do?"
+  ✓ "Is there a deadline or constraint that affects the approach?"
+
+Bad (too detailed too early):
+  ✗ "Should the button be primary or secondary variant?"
+  ✗ "What exact file should this go in?"
+  ✗ "Should we use useCallback here?"
+```
+
+**Two rounds, two altitudes.** The examples above govern Step 2 — goal
+altitude only. Step 4's detail round is the deliberate exception: once an
+approach is chosen, contract/mapping/edge-case questions ("what shape does
+the API error return?", "which field feeds the status badge?", "what happens
+when the upstream times out?") are exactly right, and their answers land in
+the matching spec concern file. What stays bad at *every* stage:
+micro-decisions the agent should make itself (button variants, hook choices,
+file placement).
+
+## Soft Gate Behavior
+
+If the user jumps straight to `/draft-plan` or starts describing implementation without running discovery:
+
+> "We haven't run discovery on this yet — want to quickly align on the design first, or do you already have a clear picture and want to go straight to planning?"
+
+Accept either answer. Never block. Never lecture.
+
+## What Does NOT Happen
+
+```
+✗ Writing any code
+✗ Writing a plan doc (that's /draft-plan)
+✗ Asking questions one at a time in a long back-and-forth
+✗ Proceeding to planning without explicit sign-off
+✗ Treating a well-defined ticket as needing full discovery
+```
+
+## Output
+
+A short design summary covering:
+
+- What we're building and why
+- Approach chosen + why alternatives were rejected
+- Key constraints and out-of-scope items
+- Open questions (if any remain after sign-off)
+
+Detail-round answers (Step 4) belong in the spec concern files, not the
+summary — the summary stays short; the spec carries the detail.
+
+Save to: `.condux/designs/YYYY-MM-DD-<feature>.md` — always, at sign-off
+(Step 7). The saved file is what `/draft-plan`'s gate check globs for; a
+design that lives only in conversation doesn't count as signed off.
+
+`.condux/` is gitignored working state, created on demand at the git root
+(see `/workflow` → Artifacts). Before the first write, make sure it's
+ignored — see the bootstrap step there. Honour an `AGENTS.md` path override
+if the project defines one.
+
+For side-by-side layout comparisons or architecture diagrams during the design phase, see `references/mockup-picker.md`.
+
+## Design Review Loop
+
+After saving, always offer — mirroring `/draft-plan`'s post-save review:
+
+> "Design saved to `<path>`. Want to review it in the browser before we plan,
+> or go straight to /draft-plan?"
+
+**If review chosen:** locate `annotate-server.js` from the installed
+`plan-review` skill (`find ~/.claude ~/.codex ~/.agents -name
+annotate-server.js -path '*plan-review*' 2>/dev/null | head -1`) and launch
+it in `--steer` mode against the saved design file (or the spec directory,
+if the design was saved as a tech spec — see Spec Integration below):
+
+```bash
+node /path/to/plan-review/references/annotate-server.js .condux/designs/<file>.md --steer
+```
+
+Poll `GET http://127.0.0.1:7777/api/decision` (long-poll — blocks until a
+decision is submitted) and branch on the result. Design review is
+**accept-or-fix** — there is no Reject at this stage:
+
+- **Approve** → design is signed off; proceed to `/draft-plan`, carrying any
+  feedback notes into the plan.
+- **Request Revisions** → revise the design file in place per the feedback
+  (the open tab live-reloads over SSE), then poll again.
+
+**If straight to planning chosen:** proceed directly, no server launch.
+
+## Spec Integration (Live Preview)
+
+Integrates with the `technical-spec` skill to persist the design and render it live while discovery runs.
+
+### At discovery start
+
+Infer the feature slug (kebab-case from `$ARGUMENTS`). Specs live under
+`<git-root>/specs/`, mirroring the repo structure: check
+`<git-root>/specs/<pkg-relpath>/<feature-slug>/` (pkg-relpath = the nearest
+package root's path relative to the git root, empty at the root) and
+`<git-root>/specs/<feature-slug>/` for an existing spec.
+
+If found, offer:
+
+> "Found an existing spec for this feature. Open live preview while we refine the design? [y/n]"
+
+If yes, go straight to **Launch preview** below (skip scaffold + write — spec already exists).
+
+### At sign-off
+
+The Markdown design doc (Step 7) is always written. The spec write-back is
+**default-on** — announce it rather than ask:
+
+> "Saving this as a tech spec too (decisions + the concern files from the
+> detail round) and opening the live preview — say no to skip."
+
+Unless the user opts out (the spec directory then becomes the target for the
+Design Review Loop above, in directory mode):
+
+1. **Find scripts** — the scaffold from technical-spec, the preview from
+   plan-review (its annotate server renders spec directories):
+   ```bash
+   SCAFFOLD=$(find ~/.claude ~/.codex ~/.agents -name "scaffold.sh" -path "*technical-spec*" 2>/dev/null | head -1)
+   PREVIEW=$(find ~/.claude ~/.codex ~/.agents -name "annotate-server.js" -path "*plan-review*" 2>/dev/null | head -1)
+   ```
+   If either is missing, tell the user: "the `technical-spec` / `plan-review` skills weren't found — install the condux plugin to enable spec integration."
+
+2. **Scaffold** the spec dir and capture the output:
+   ```bash
+   SCAFFOLD_OUT=$(bash "$SCAFFOLD" "<FeatureName>")
+   SPEC_PATH=$(echo "$SCAFFOLD_OUT" | sed 's/^[^:]*://; s/ .*//')
+   ```
+   `SPEC_PATH` is an absolute path (e.g. `/repo/specs/apps/web/wan-config`).
+   The scaffold script places specs under `<git-root>/specs/`, mirroring the
+   repo structure, automatically.
+
+3. **Write initial spec files** from the design into `$SPEC_PATH/`.
+   `decisions.md` always (chosen approach + rationale). Then every concern
+   the detail round produced answers for gets its file: `api.md`,
+   `fields.md`, `quirks.md`, `implementation.md`. A detail-round answer
+   that never lands in a spec file is a bug in the flow, not a judgment call.
+
+4. **Launch preview** in the background, pointing at the absolute spec path:
+   ```bash
+   node "$PREVIEW" "$SPEC_PATH"
+   ```
+   Tell user: "Preview is live. The browser updates automatically as spec files change, and you can annotate any file and submit a decision. Ctrl+C in the terminal to stop."
+
+### Keeping the spec current
+
+As discovery continues and design details shift, update the relevant spec files — the preview re-renders on every save. This is the main benefit: the spec stays in sync with the conversation instead of being written once at the end.
+
+If the user submits a decision in the preview, read `$SPEC_PATH/review.feedback.md` (notes grouped by file) and action it. Spec review is accept-or-fix (directory mode has no Reject): **Approve** = design is signed off, proceed; **Request Revisions** = fix the spec files, then continue the loop.

package/skills/discovery/evals/trigger_eval.json

@@ -0,0 +1,24 @@
+[
+  { "query": "lets figure out the design for the billing revamp", "should_trigger": true, "expected_skill": "discovery" },
+  { "query": "not sure what the scope is, help me think this through", "should_trigger": true, "expected_skill": "discovery" },
+  { "query": "i have a rough idea for an activity feed", "should_trigger": true, "expected_skill": "discovery" },
+  { "query": "clarify the requirements before we build anything", "should_trigger": true, "expected_skill": "discovery" },
+  { "query": "surface some alternatives for the state management approach", "should_trigger": true, "expected_skill": "discovery" },
+  { "query": "design session for the new onboarding", "should_trigger": true, "expected_skill": "discovery" },
+  { "query": "brainstorm ideas for the notifications feature", "should_trigger": true, "expected_skill": "discovery" },
+  { "query": "whats done look like for this feature? lets align first", "should_trigger": true, "expected_skill": "discovery" },
+  { "query": "resume the design we started yesterday", "should_trigger": true, "expected_skill": "discovery" },
+  { "query": "found an existing design doc for this, continue from it", "should_trigger": true, "expected_skill": "discovery" },
+  { "query": "design a database schema for multi-tenancy", "should_trigger": true, "expected_skill": "discovery" },
+  { "query": "big refactor, unclear boundaries — where do we even start", "should_trigger": true, "expected_skill": "discovery" },
+  { "query": "resume where we left off last session", "should_trigger": true, "expected_skill": "session-handoff" },
+  { "query": "pick up from the handoff doc", "should_trigger": true, "expected_skill": "session-handoff" },
+  { "query": "we already have a signed off design, write the plan", "should_trigger": true, "expected_skill": "draft-plan" },
+  { "query": "skip discovery, just plan it", "should_trigger": true, "expected_skill": "draft-plan" },
+  { "query": "small tweak to the button color", "should_trigger": true, "expected_skill": "workflow" },
+  { "query": "review the plan in the browser", "should_trigger": true, "expected_skill": "plan-review" },
+  { "query": "save what we decided as a spec", "should_trigger": true, "expected_skill": "technical-spec" },
+  { "query": "why does checkout 500 on submit", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "help me write my resume", "should_trigger": false, "expected_skill": null },
+  { "query": "design a logo for the app", "should_trigger": false, "expected_skill": null }
+]