@jabworks/condux 0.27.0 → 0.28.0

package/agents/scout.md

@@ -0,0 +1,64 @@
+---
+description: "Use this agent when a research lead needs one angle of a multi-source survey investigated and written down. The lead hands it a brief; it searches the web, reads primary sources, and writes a notes file. Dispatch several in one message so the angles run in parallel. Not for a single API lookup — that is the researcher agent."
+mode: subagent
+permission: {"bash":"deny"}
+---
+
+You are a survey-research worker. A lead hands you one angle of a larger question. You investigate it on the open web, then write what you found to a notes file. You report only what a source says — never what you remember.
+
+## The brief
+
+Every dispatch carries five parts. If one is missing, work with the rest and record the hole as a Gap.
+
+| Part | Meaning |
+|---|---|
+| Objective | the one angle you own — stay inside it |
+| Key questions | what the notes must answer |
+| Suggested sources | where to start, not where to stop |
+| Constraints | version, date, or scope bounds — carry them into every query |
+| Notes path | an absolute path; the only file you write |
+
+## Method
+
+- **Budget**: 10–15 tool calls. Stop early once the key questions are answered; unused budget is not a target.
+- **Tools**: use the search and fetch tools the host exposes. Do not depend on a particular tool name.
+- **Queries**: short and varied. Start broad, see what exists, then narrow. Rephrase rather than repeat.
+- **Depth**: open and read the full page of a promising result. A search snippet is a pointer, not evidence.
+- **Source quality**: prefer primary sources — official docs, changelogs, release notes, maintainer posts, source repositories. Treat aggregators, listicles, and SEO content as leads to a primary source, not as sources.
+- **Version or date**: every finding records the version or date of its source. A dev claim with neither is unreliable — say so.
+- **Disagreement**: when sources disagree, record both with their citations under Conflicts. Never pick a winner silently.
+- **Blocked fetch**: if the host blocks, redirects, or fails a fetch, record a Gap with the reason, carry on with search results, and move to the next source. Do not retry the same fetch in a loop and do not stop the run.
+
+## Notes file
+
+Write the notes to the path in the brief, and nowhere else. One block per key question:
+
+````
+## <key question>
+
+**Answer**: <1–2 lines>
+
+**Findings**
+- <claim> — <source URL> — <source version or date>
+
+**Conflicts**
+- <source A says X (URL, version/date); source B says Y (URL, version/date)>
+
+**Gaps**
+- <what could not be found, and why>
+````
+
+- A finding without a URL is not a finding. Move it to Gaps.
+- Keep claims short and specific. No narrative padding.
+- Leave a section empty with `None` rather than dropping it.
+
+## Final message
+
+Two or three lines: what you covered, the headline answer, and how many gaps or conflicts remain. Do not paste the notes — the lead reads them from disk.
+
+## Constraints
+
+- **Write scope** — the notes file only. Never create or edit any other project file.
+- **Stay in your angle** — do not widen into neighbouring questions; note them as Gaps if they matter.
+- **Failure** — if nothing usable turns up, still write the notes file with the Gaps and what you tried.
+- **Honesty** — if the budget runs out with questions open, say so in Gaps. Never fill them from memory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jabworks/condux",
-  "version": "0.27.0",
+  "version": "0.28.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

@@ -1,6 +1,6 @@
 ---
 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)."
+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 five 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]"
 ---
 
@@ -50,8 +50,8 @@ else on the machine competes with it. Only `broken` affects the exit code.
   routing reminder it injects names the OpenCode verb, `skill(name="workflow")`
   — a payload still saying `/condux:workflow` is the docket #72 under-firing
   shape, reported broken with an upgrade as the fix.
-- **The four specialist agents** — `coder`, `explorer`, `planner`,
-  `researcher`. They live in a plugin-level directory reached by its own sync
+- **The five specialist agents** — `coder`, `explorer`, `planner`,
+  `researcher`, `scout`. 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.

package/skills/condux-doctor/doctor.mjs

@@ -363,7 +363,7 @@ function probeOpencode(hosts) {
   };
 }
 
-// The four specialist agents are plugin-level and reached by their own sync
+// The five 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([
@@ -374,11 +374,11 @@ function probeAgents() {
   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 expected = ['coder', 'explorer', 'planner', 'researcher', 'scout'];
   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: 'done', detail: `all five 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' };
 }
 

package/skills/research/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: research
+description: "Multi-source dev research with parallel scouts. Scales effort to the question's shape, writes a plan and per-angle notes to a run folder, then synthesizes a cited report with a recommendation first. Every claim traces to a note finding with a URL. Inferred triggers are confirmed before a deep run. Comparing libraries, frameworks or approaches; surveying how others solve X; \"research X\"; ecosystem or standards surveys that need several sources. Not for a single API or signature lookup (researcher agent, or answer directly); not for implementation tasks (/workflow); not for explaining code (answer directly)."
+argument-hint: "[question to research]"
+---
+
+# /research
+
+Break a question into angles, send scouts at them in parallel, and return a report you can trust.
+
+## 1. Clarify (only if it changes the research)
+
+Ask only when the answer would change *what gets researched*: which options to compare, a version or time bound, the deciding criterion. Max 3 questions, all at once. Otherwise state your assumptions in `plan.md` and go.
+
+## 2. Classify the shape
+
+| Shape | Example | Scouts |
+|---|---|---|
+| Single fact or API | "what does `useId` return" | **0** — answer directly or hand to `researcher` |
+| Comparison | "Zustand vs Jotai vs Valtio" | **2–4** — one per option, plus one for criteria if needed |
+| Survey | "how do teams handle offline sync in 2026" | **5–6** — one per distinct angle |
+
+More than 6 needs the user's yes first. Name the cost when you ask: multi-agent research ran at about 15x the tokens of a chat turn in Anthropic's own measurement.
+
+**Depth gate.** How the skill was reached decides whether to fan out:
+
+| Reached by | What happens |
+|---|---|
+| **Explicit** — the user named the skill (`/condux:research`, "use the research skill", "condux:research") or asked for depth in words ("deep research", "thorough", "comprehensive", "cited report", "dig into") | Proceed with the classified scout count. Do not ask. |
+| **Inferred** — the skill loaded because a question sounded like research (routing hook or trigger description) | Single fact or API: answer directly, never ask. Comparison or survey: ask ONCE, recommendation marked: "Quick answer (one pass, about 1x cost) or deep research (N scouts, about 15x cost)?" N is the classified count. Recommend quick for a comparison of well-known options, deep for a survey or a comparison where the user's constraints decide it. |
+
+**Quick answer** means: the main session answers in one pass, with a few searches and fetches through the host's search and fetch tools, sources cited inline, no run folder and no scouts. Same honesty rules: a version or date on dev claims, and say what could not be verified. If the user picks quick, answer and stop; offer deep research in one line only if the answer is visibly thin.
+
+## 3. Open the run folder
+
+```
+.condux/research/<YYYY-MM-DD>-<slug>/
+  plan.md
+  notes/<angle>.md
+  report.md
+```
+
+Never overwrite a run folder. A follow-up opens a new one and names the earlier run as background in its `plan.md`.
+
+**Bootstrap.** `.condux/` is created on demand at the git root. Before the first write, check it is ignored:
+
+```bash
+git check-ignore -q .condux/ || echo "not ignored"
+```
+
+If not, offer once: "condux keeps its working files in `.condux/` — add it to `.gitignore` so they stay out of your commits?" On yes, append `.condux/` to `.gitignore`; if the user would rather not touch a tracked file, use `.git/info/exclude`. Never edit either without asking. Not a git repo: fall back to CWD and say so once.
+
+## 4. Write `plan.md`
+
+Before any dispatch, write: the sub-questions, the scout count with the reason, and **every brief verbatim**. Recording the notes paths here also makes a stray write by a scout visible later.
+
+## 5. Dispatch — all scouts in ONE message
+
+Parallel only works if every call goes out together. Dispatch the named `scout` agent and nothing else — never a general-purpose or custom-prompt agent.
+
+A vague brief makes scouts repeat each other or wander. Each brief carries:
+
+| Part | Rule |
+|---|---|
+| Objective | one angle, with a clear boundary against its siblings |
+| Key questions | the specific things the notes must answer |
+| Suggested sources | starting points (official docs, changelogs, repos) |
+| Constraints | the user's version and time bounds, carried through unchanged |
+| Notes path | absolute: `<git-root>/.condux/research/<run>/notes/<angle>.md` |
+
+Wait for every scout to return before step 6. Their summaries say what was covered; the evidence is in the notes files.
+
+## 6. Gap round (at most one)
+
+Read every notes file. If a *critical* gap remains — one that blocks the recommendation — dispatch a single follow-up round of scouts aimed at only those gaps. Minor gaps go into the report as unknowns. A second round needs the user's consent.
+
+## 7. Synthesize `report.md`
+
+Read the notes from disk, not from scout summaries.
+
+| Part | Contains |
+|---|---|
+| Recommendation / answer | first, decision-ready, with the deciding reason |
+| Comparison table | when the question has options |
+| Evidence sections | claims with inline `([source](url))` |
+| Risks and unknowns | unresolved conflicts and gaps, stated plainly |
+| Sources | the full list, each with its version or date |
+
+When notes conflict, present both sides — don't pick one quietly.
+
+## 8. Citation check
+
+Walk the report claim by claim. Each must trace to a note finding that has a URL. Drop any claim that doesn't, or keep it visibly flagged as unverified. No re-fetching — the notes are the evidence.
+
+## 9. Deliver
+
+In chat: 3–5 lines (the answer, the confidence, the biggest unknown) and the report path.
+
+Offer promotion **once**: "Does this feed a spec? If so, which one?" On a named spec:
+
+1. Copy the report to `specs/<that-spec>/research-<YYYY-MM-DD>-<topic>.md`.
+2. Add a link row to that spec's `index.md`.
+3. The copy keeps external URLs only. It must never cite a `.condux/` path.
+
+No fitting spec: the report stays in `.condux/`.
+
+## Sequential fallback
+
+If `scout` cannot be spawned — no agent tool, or no scout agent (Cursor, or Codex before the agent installer is re-run) — say so once: "no scout agent here — researching sequentially, slower, same output."
+
+Then do the work yourself: take each angle in turn, using the host's search and fetch tools under the same rules (10–15 calls per angle, primary sources, version or date on every finding, conflicts recorded). Write the same `notes/<angle>.md` files in the scout's shape, one block per key question, then continue from step 7:
+
+```
+## <key question>
+**Answer**: <1–2 lines>
+**Findings**
+- <claim> — <source URL> — <source version or date>
+**Conflicts**
+- <source A says X; source B says Y — both cited>
+**Gaps**
+- <what could not be found, and why>
+```
+
+A finding without a URL goes under Gaps.
+
+## What does NOT happen
+
+- No scouts for a single fact — answer it or use `researcher`
+- No fan-out from an inferred trigger without asking
+- No more than 6 scouts without the user's yes and the cost named
+- No dispatch before `plan.md` holds the briefs
+- No general-purpose or custom-prompt agent standing in for `scout`
+- No overwriting a run folder
+- No second gap round without consent
+- No claim in the report without a URL in the notes
+- No `.condux/` path cited from a promoted copy
+- No promotion without asking which spec

package/skills/research/evals/gate_eval.json

@@ -0,0 +1,7 @@
+[
+  { "id": "inferred-comparison", "expect": "ask", "query": "tanstack query vs swr — which should we use for an app with lots of optimistic updates?" },
+  { "id": "inferred-survey", "expect": "ask", "query": "how do other monorepos handle versioning for independently installable plugins?" },
+  { "id": "inferred-options", "expect": "ask", "query": "what are the options for auth on cloudflare workers these days?" },
+  { "id": "single-fact", "expect": "direct", "query": "does vitest support the --shard flag?" },
+  { "id": "single-api", "expect": "direct", "query": "what's the signature of zod's .max() on strings?" }
+]

package/skills/research/evals/quality_eval.json

@@ -0,0 +1,14 @@
+[
+  { "id": "server-state-libs", "shape": "comparison", "query": "TanStack Query vs SWR vs RTK Query for a React app with heavy optimistic updates and offline support — which fits best, and why?" },
+  { "id": "ts-orms", "shape": "comparison", "query": "Drizzle vs Prisma vs Kysely for a Postgres-backed TypeScript service: migrations, type safety, edge runtime support, and performance." },
+  { "id": "js-linters", "shape": "comparison", "query": "Oxlint vs Biome vs ESLint for a large TypeScript monorepo in 2026: rule coverage, speed, plugin support, and migration cost." },
+  { "id": "monorepo-tools", "shape": "comparison", "query": "Turborepo vs Nx vs moon for a pnpm monorepo with about 30 packages: caching, task graphs, and remote cache options." },
+  { "id": "edge-auth", "shape": "survey", "query": "What are the current options for authentication on edge runtimes (Cloudflare Workers, Vercel Edge), and what are the tradeoffs of each?" },
+  { "id": "plugin-versioning", "shape": "survey", "query": "How do popular open-source monorepos version and release independently installable plugins or packages?" },
+  { "id": "design-tokens", "shape": "survey", "query": "How do open-source design systems ship design tokens to both web and React Native?" },
+  { "id": "rsc-support", "shape": "survey", "query": "What is the current state of React Server Components support across Next.js, Remix/React Router, Waku, and TanStack Start?" },
+  { "id": "local-first-sync", "shape": "survey", "query": "What are teams using for local-first sync in web apps (CRDT libraries and sync engines), and what are the tradeoffs?" },
+  { "id": "test-runners-fallback", "shape": "comparison", "fallback": true, "query": "Vitest vs Jest vs the Node.js built-in test runner for a TypeScript library: speed, ESM support, mocking, and coverage." },
+  { "id": "feature-flags-fallback", "shape": "survey", "fallback": true, "query": "What are the main open-source feature-flag platforms, and how do they compare on self-hosting, SDK coverage, and pricing?" },
+  { "id": "bundlers-fallback", "shape": "comparison", "fallback": true, "query": "Vite vs Rspack vs Turbopack for a large React application: build speed, plugin ecosystem, and maturity." }
+]

package/skills/research/evals/trigger_eval.json

@@ -0,0 +1,18 @@
+[
+  { "query": "compare tanstack query vs swr for a next.js app with heavy optimistic updates", "should_trigger": true, "expected_skill": "research" },
+  { "query": "how do other monorepos version and release their plugins?", "should_trigger": true, "expected_skill": "research" },
+  { "query": "research the options for edge-compatible auth in a cloudflare workers app", "should_trigger": true, "expected_skill": "research" },
+  { "query": "survey the current state of react server components support across frameworks", "should_trigger": true, "expected_skill": "research" },
+  { "query": "what are teams using instead of eslint these days, and what did they give up switching?", "should_trigger": true, "expected_skill": "research" },
+  { "query": "drizzle vs prisma vs kysely for a postgres app — which fits a small team better?", "should_trigger": true, "expected_skill": "research" },
+  { "query": "how do popular CLIs handle plugin discovery and sandboxing? I want a cited overview", "should_trigger": true, "expected_skill": "research" },
+  { "query": "dig into how open-source design systems ship tokens to both web and react native", "should_trigger": true, "expected_skill": "research" },
+  { "query": "what's the signature of zod's .max() on strings?", "should_trigger": false, "expected_skill": null, "note": "A single API lookup: answer directly or hand to the researcher agent. The near-miss this corpus exists for." },
+  { "query": "does vitest support the --shard flag?", "should_trigger": false, "expected_skill": null, "note": "One fact from one source — no fan-out." },
+  { "query": "add retry with backoff to the fetch client", "should_trigger": false, "expected_skill": null, "accept": ["workflow"] },
+  { "query": "migrate our forms from formik to react-hook-form", "should_trigger": false, "expected_skill": null, "accept": ["workflow"], "note": "A dev task that names two libraries — still an implementation request, not a survey." },
+  { "query": "explain what this reducer does", "should_trigger": false, "expected_skill": null },
+  { "query": "why is the build failing on CI", "should_trigger": false, "expected_skill": null, "accept": ["root-cause-analysis", "workflow"] },
+  { "query": "look up what changed in node 24's fetch implementation", "should_trigger": false, "expected_skill": null, "note": "One changelog, one answer — a lookup, not multi-source research." },
+  { "query": "how does human memory consolidation work?", "should_trigger": false, "expected_skill": null, "note": "General research outside dev — condux:research is dev-tuned; answering directly or another installed research skill is fine." }
+]

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. For ad-hoc independent work discovered outside a formal plan. Trigger when the fan-out is already the ask — \"in parallel\", \"fan out\", \"dispatch these together\", \"kick off explorer and researcher\" — over two or more genuinely independent tasks, nothing shared, no ordering. Independence alone is not the signal: a plain implementation request goes to workflow first, which loads this when the tier warrants it. Also owns which agent gets dispatched: asking to spawn a generic or custom-prompt subagent routes here, where the answer is one of the four named agents instead. 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 the fan-out is already the ask — \"in parallel\", \"fan out\", \"dispatch these together\", \"kick off explorer and researcher\" — over two or more genuinely independent tasks, nothing shared, no ordering. Independence alone is not the signal: a plain implementation request goes to workflow first, which loads this when the tier warrants it. Also owns which agent gets dispatched: asking to spawn a generic or custom-prompt subagent routes here, where the answer is one of condux's named agents instead — unless another installed skill mandates its own spawn type. Not for executing an ordered plan task-by-task (that's subagent-execution)."
 argument-hint: "<list of independent tasks>"
 ---
 
@@ -45,7 +45,9 @@ the fan-out — parallel, dispatch, fan out, these agents at once.
 │  Read-only lookup → explorer or researcher.                     │
 │  Isolated implementation/fix → coder.                           │
 │  Never a generic subagent with an injected prompt — only        │
-│  condux's four named agents.                                    │
+│  condux's named agents (scout is research-only). A skill        │
+│  that mandates its own spawn type runs as written (see          │
+│  subagent-execution).                                           │
 │                                                                  │
 │  Step 4: DISPATCH TOGETHER                                      │
 │  Issue every checklist-cleared dispatch in the SAME message —   │

package/skills/subagent-execution/SKILL.md

@@ -17,11 +17,21 @@ 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
+(`explorer`, `researcher`, `planner`, `coder`, `scout`). 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.
 
+**The exception: another skill's mandated spawn.** When a different installed
+skill tells you to spawn a specific agent type *and* ships that worker's contract
+as a file the worker reads first — `anthropic-skills:deep-research` spawns
+`general-purpose` workers whose first step is reading its own worker
+reference — run it as written. That contract is reviewable; it
+lives in the skill. Substituting a named agent breaks both sides: condux's agents
+carry their own contracts (researcher stops at the first source and never writes
+files), which contradict the brief. The ban is on condux writing an agent's
+behaviour at call time, not on honouring another skill's.
+
 **You implement by default.** Spawning is an explicit decision with a stated reason — not the default mode of operation.
 
 ```

package/skills/subagent-execution/agents/scout.md

@@ -0,0 +1,67 @@
+---
+name: "scout"
+description: "Use this agent when a research lead needs one angle of a multi-source survey investigated and written down. The lead hands it a brief; it searches the web, reads primary sources, and writes a notes file. Dispatch several in one message so the angles run in parallel. Not for a single API lookup — that is the researcher agent.\n\n<example>\nContext: The lead is comparing three state libraries and has split the question into one angle per library.\nuser: \"Compare Zustand, Jotai and Valtio for a mid-size React app\"\nassistant: \"I'll dispatch three scout agents in one message, one per library, each with its own brief and notes path.\"\n<commentary>\nA comparison needs several independent angles researched at once. Each scout gets an objective, key questions, constraints and an absolute notes path, then writes its findings to disk.\n</commentary>\n</example>"
+tools: CronCreate, CronDelete, CronList, EnterWorktree, ExitWorktree, ListMcpResourcesTool, LSP, Monitor, PushNotification, Read, ReadMcpResourceTool, RemoteTrigger, Skill, TaskCreate, TaskGet, TaskList, TaskStop, TaskUpdate, ToolSearch, WebFetch, WebSearch, Write
+model: sonnet
+color: green
+memory: user
+---
+
+You are a survey-research worker. A lead hands you one angle of a larger question. You investigate it on the open web, then write what you found to a notes file. You report only what a source says — never what you remember.
+
+## The brief
+
+Every dispatch carries five parts. If one is missing, work with the rest and record the hole as a Gap.
+
+| Part | Meaning |
+|---|---|
+| Objective | the one angle you own — stay inside it |
+| Key questions | what the notes must answer |
+| Suggested sources | where to start, not where to stop |
+| Constraints | version, date, or scope bounds — carry them into every query |
+| Notes path | an absolute path; the only file you write |
+
+## Method
+
+- **Budget**: 10–15 tool calls. Stop early once the key questions are answered; unused budget is not a target.
+- **Tools**: use the search and fetch tools the host exposes. Do not depend on a particular tool name.
+- **Queries**: short and varied. Start broad, see what exists, then narrow. Rephrase rather than repeat.
+- **Depth**: open and read the full page of a promising result. A search snippet is a pointer, not evidence.
+- **Source quality**: prefer primary sources — official docs, changelogs, release notes, maintainer posts, source repositories. Treat aggregators, listicles, and SEO content as leads to a primary source, not as sources.
+- **Version or date**: every finding records the version or date of its source. A dev claim with neither is unreliable — say so.
+- **Disagreement**: when sources disagree, record both with their citations under Conflicts. Never pick a winner silently.
+- **Blocked fetch**: if the host blocks, redirects, or fails a fetch, record a Gap with the reason, carry on with search results, and move to the next source. Do not retry the same fetch in a loop and do not stop the run.
+
+## Notes file
+
+Write the notes to the path in the brief, and nowhere else. One block per key question:
+
+````
+## <key question>
+
+**Answer**: <1–2 lines>
+
+**Findings**
+- <claim> — <source URL> — <source version or date>
+
+**Conflicts**
+- <source A says X (URL, version/date); source B says Y (URL, version/date)>
+
+**Gaps**
+- <what could not be found, and why>
+````
+
+- A finding without a URL is not a finding. Move it to Gaps.
+- Keep claims short and specific. No narrative padding.
+- Leave a section empty with `None` rather than dropping it.
+
+## Final message
+
+Two or three lines: what you covered, the headline answer, and how many gaps or conflicts remain. Do not paste the notes — the lead reads them from disk.
+
+## Constraints
+
+- **Write scope** — the notes file only. Never create or edit any other project file.
+- **Stay in your angle** — do not widen into neighbouring questions; note them as Gaps if they matter.
+- **Failure** — if nothing usable turns up, still write the notes file with the Gaps and what you tried.
+- **Honesty** — if the budget runs out with questions open, say so in Gaps. Never fill them from memory.

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

@@ -19,7 +19,8 @@
 //   - tuning keys on an existing TOML (model, model_reasoning_effort,
 //     sandbox_mode, nickname_candidates) are preserved; otherwise
 //     sandbox_mode defaults to read-only for explorer/researcher and
-//     workspace-write for planner/coder, and model / model_reasoning_effort
+//     workspace-write for planner/coder/scout (scout writes its notes file),
+//     and model / model_reasoning_effort
 //     default per MODEL_DEFAULTS (Free/Go plans get Luna only — edit down)
 //   - existing files are backed up to <name>.toml.bak first
 //
@@ -53,6 +54,7 @@ const SANDBOX_DEFAULTS = {
   researcher: 'read-only',
   planner: 'workspace-write',
   coder: 'workspace-write',
+  scout: 'workspace-write',
 };
 // Model tiers per spawn-rules.md → Codex Model Defaults. Applied per key,
 // only when the existing TOML doesn't set it.
@@ -61,6 +63,7 @@ const MODEL_DEFAULTS = {
   researcher: { model: 'gpt-6-astra', model_reasoning_effort: 'high' },
   planner: { model: 'gpt-6.1-sol', model_reasoning_effort: 'medium' },
   coder: { model: 'gpt-6.1-sol', model_reasoning_effort: 'medium' },
+  scout: { model: 'gpt-6.1-sol', model_reasoning_effort: 'medium' },
 };
 const PRESERVE_KEYS =['model', 'model_reasoning_effort', 'sandbox_mode', 'nickname_candidates'];
 

package/skills/subagent-execution/references/spawn-rules.md

@@ -10,6 +10,7 @@ Reference for deciding when and which agent to spawn. Read this before every spa
 | **CHEAP**     | `explorer`                | sonnet, `effort: low`                      | Read-only, narrow scope, clear output. Good for lookup tasks that would bloat your context  |
 | **EXPENSIVE** | `researcher`              | opus                                       | Read-only, but source judgment decides the result — conflicting docs, version drift         |
 | **EXPENSIVE** | `coder`, `planner`        | sonnet (default) — see Model Selection     | Write-capable or high-context output. Justify carefully                                     |
+| **FAN-OUT**   | `scout`                   | sonnet                                     | Only via `/condux:research` — cheap per worker, but 2–6 run at once (about 15× chat tokens) |
 
 No agent uses haiku. Sonnet at low effort beats it at the same job in fewer
 turns, and turn count costs more than token price on multi-step work.
@@ -42,7 +43,7 @@ redispatch the same brief with `opus`. When unsure, use `opus`.
 | Agent                | `model`        | `model_reasoning_effort` |
 | -------------------- | -------------- | ------------------------ |
 | `explorer`           | `gpt-6-luna`   | `low`                    |
-| `planner`, `coder`   | `gpt-6.1-sol`  | `medium`                 |
+| `planner`, `coder`, `scout` | `gpt-6.1-sol`  | `medium`          |
 | `researcher`         | `gpt-6-astra`  | `high`                   |
 
 Free and Go plans get Luna only, and Astra's plan gating is not settled in
@@ -57,6 +58,7 @@ documented fallback for an unavailable model either.
 | `researcher` | ✓ MCP, web, docs  | ✗            | ✗          | External research: library docs, API specs, best practices      |
 | `coder`      | ✓                 | ✓ full file  | ✓          | Implementation tasks with isolated scope                        |
 | `planner`    | ✓                 | ✓ write only | ✗          | Architecture decisions, task breakdowns, ADRs                   |
+| `scout`      | ✓ MCP, web, docs  | ✓ notes only | ✗          | Survey research for `/condux:research` — one angle, cited notes |
 
 **Hard rule:** Specialists receive task context via delegation prompt only. They do not and should not query the plan file directly.
 

package/skills/workflow/SKILL.md

@@ -226,8 +226,10 @@ override always wins over these defaults.
 
 ## Agents
 
-Four **named specialist agents** ship with condux — never invent a generic subagent
-with an injected prompt. Implement yourself by default; spawn only with concrete
+Five **named specialist agents** ship with condux — never invent a generic subagent
+with an injected prompt. (Another installed skill that mandates its own spawn type
+and ships the worker's contract, like deep-research, runs as written — see
+`subagent-execution`.) Implement yourself by default; spawn only with concrete
 justification (unfamiliar codebase, external API to verify, genuinely parallel
 exploration, or a LARGE plan via `subagent-execution`).
 
@@ -238,6 +240,8 @@ exploration, or a LARGE plan via `subagent-execution`).
   researcher when external libs are involved, before planning).
 - `coder` — executes a provided plan only (sonnet; no exploration, no
   typecheck/lint/test — that's finalize's job).
+- `scout` — one angle of a survey, dispatched only by `/condux:research` (sonnet;
+  writes only its own notes file).
 
 Pipeline: explorer/researcher gather (non-blocking) → planner plans → coder executes
 → finalize validates. Spawn mechanics, model tiering, and the parallel-safety

package/skills/workflow/evals/trigger_eval.json

@@ -21,7 +21,7 @@
   { "query": "how does condux work", "should_trigger": true, "expected_skill": "workflow" },
   { "query": "explain the soft gates", "should_trigger": true, "expected_skill": "workflow" },
   { "query": "can I skip workflow and just start", "should_trigger": true, "expected_skill": "workflow" },
-  { "query": "what are the four named agents", "should_trigger": true, "expected_skill": "workflow" },
+  { "query": "what are the five named agents", "should_trigger": true, "expected_skill": "workflow" },
   { "query": "who wins, my CLAUDE.md or condux rules", "should_trigger": true, "expected_skill": "workflow" },
   { "query": "why does condux ban mid-task test runs", "should_trigger": true, "expected_skill": "workflow" },
   { "query": "what should we improve next in the toolkit repo", "should_trigger": true, "expected_skill": "toolkit-research-frontier" },

package/skills/workflow/hooks/routing.md

@@ -22,9 +22,11 @@ still a dev task, so it routes through workflow, which loads
 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.
+**Not everything is a dev task.** Questions, explanations, code reading, quick
+lookups, and one-line factual answers route nowhere — answer them directly.
+Multi-source research (comparing options, surveying how others solve X) goes to
+the `research` skill — `skill(name="research")`. Routing a conversation through a workflow is as wrong as
+skipping the router on a feature.
 
 **On OpenCode, a `/name` mention of any condux skill means the `skill` tool:** `/workflow` → `skill(name="workflow")`, `/finalize` → `skill(name="finalize")`, and so on. None of them is a slash command here.
 </EXTREMELY_IMPORTANT>