feat(trekresearch): parse --engine {swarm|deep-research} flag

commands/trekresearch.md

@@ -1,7 +1,7 @@
 ---
 name: trekresearch
 description: Deep research combining local codebase analysis with external knowledge, producing structured research briefs with triangulation and confidence ratings
-argument-hint: "[--project <dir>] [--quick | --local | --external | --fg] <research question>"
+argument-hint: "[--project <dir>] [--quick | --local | --external | --fg] [--engine swarm|deep-research] <research question>"
 model: opus
 allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion, WebSearch, WebFetch, mcp__tavily__tavily_search, mcp__tavily__tavily_research
 ---
@@ -80,6 +80,16 @@ Supported flags:
    enforcement only fires at `≥ 2.2`. Absent → no version check. See
    `docs/HANDOVER-CONTRACTS.md` §Handover 1 for the pre-2.2 enforcement hole.
 
+8. `--engine <name>` — opt-in external-research engine. Accepts `--engine <name>`
+   where `<name>` is `swarm` or `deep-research`. **Default: `swarm`** (unchanged
+   behavior). `swarm` runs Voyage's own external-research agent swarm;
+   `deep-research` delegates the external phase to Claude Code's built-in
+   `/deep-research` dynamic workflow and adapts its report into the research-brief
+   schema (requires Claude Code 2.1.154+ and dynamic workflows enabled; falls back
+   to `swarm` and notes the fallback if unavailable — never hard-fails). Orthogonal
+   to `--profile`/`phase_signals`; only affects the external phase. Set
+   **engine = {swarm|deep-research}** (the *requested* engine).
+
 Flags can be combined:
 - `--local` — local-only research
 - `--external --quick` — external-only, lightweight
@@ -87,7 +97,7 @@ Flags can be combined:
 - `--quick` alone implies both local and external (lightweight)
 
 Defaults: **scope = both**, **execution = foreground** (only mode as of
-v2.4.0), **project_dir = none**.
+v2.4.0), **project_dir = none**, **engine = swarm**.
 
 After stripping flags, the remaining text is the **research question**.
 
@@ -108,6 +118,7 @@ Modes:
   --external    Only external research agents (skip codebase analysis)
   --fg          No-op alias (foreground is the only mode as of v2.4.0)
   --project     Write brief into an trekbrief project folder (auto-indexed)
+  --engine      Opt-in external-research engine: swarm (default) | deep-research
 
 Flags can be combined: --local, --external --quick, --project <dir> --external
 
@@ -118,6 +129,7 @@ Examples:
   /trekresearch --external What are the security implications of using Redis for sessions?
   /trekresearch --fg --local What patterns does this codebase use for database access?
   /trekresearch --project .claude/projects/2026-04-18-jwt-auth --external What JWT library is best for Node.js?
+  /trekresearch --project <dir> --external --engine deep-research <research question>
 ```
 
 Do not continue past this step if no question was provided.
@@ -126,6 +138,7 @@ Report the detected mode:
 ```
 Mode: {default | quick}, Scope: {both | local | external}, Execution: foreground
 Project: {project_dir or "-"}
+Engine (requested): {swarm | deep-research}
 Question: {research question}
 ```
 
@@ -418,6 +431,7 @@ Record format (one JSON line):
   "question": "{research question (first 100 chars)}",
   "mode": "{default|quick}",
   "scope": "{both|local|external}",
+  "engine": "{effective engine: swarm|deep-research}",
   "slug": "{brief slug}",
   "project_dir": "{project_dir or null}",
   "brief_path": "{brief_destination}",
@@ -455,8 +469,8 @@ VOYAGE_PROFILE=balanced /trekresearch
 ```
 
 Stats records emit `profile`, `phase_models`, `parallel_agents`,
-`external_research_enabled`, and `profile_source` so operators can audit
-which profile drove which session.
+`external_research_enabled`, `profile_source`, and `engine` so operators can
+audit which profile and engine drove which session.
 
 ## Composition rule (v5.1)