Kjell Tore Guttormsen db3b8f5491 feat(commands): drop orchestrator model pins - inherit session model

2026-07-02 17:09:49 +02:00

29 KiB

Raw Permalink Blame History

name	description	argument-hint	allowed-tools
trekresearch	Deep research combining local codebase analysis with external knowledge, producing structured research briefs with triangulation and confidence ratings	[--project <dir>] [--quick \| --local \| --external \| --fg] [--engine swarm\|deep-research] <research question>	Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion, WebSearch, WebFetch, mcp__tavily__tavily_search, mcp__tavily__tavily_research

Ultraresearch Local v1.0

Deep, multi-phase research that combines local codebase analysis with external knowledge. Uses specialized agent swarms to investigate multiple dimensions in parallel, then triangulates findings to produce insights that neither local nor external research could provide alone.

Design principle: Context Engineering — build the right context by orchestrating specialized agents, each seeing only what they need. The value is in triangulation (cross-checking local vs. external) and synthesis (insights from combining both).

Pipeline integration: Research briefs feed into trekplan via --research:

/trekresearch <question> → brief → /trekplan --research <brief> <task>

Phase 1 — Parse mode and validate input

Parse $ARGUMENTS for mode flags. Flags can appear in any order before the research question. Collect all flags first, then treat the remainder as the research question.

Supported flags:

--quick — lightweight research, no agent swarm. The command itself does 3-5 targeted searches inline. Set mode = quick.
--local — only codebase research. Skip external agents and gemini bridge. Set scope = local.
--external — only external research. Skip codebase analysis agents. Set scope = external.
--fg — accepted as a no-op alias for backwards compatibility. Execution is always foreground as of v2.4.0. Set execution = foreground (the only mode).

--project <dir> — attach this research to an trekbrief project folder. The brief will be written to {dir}/research/{NN}-{slug}.md (auto-incremented index) instead of the default .claude/research/ path. Set project_dir = {dir}.

If {dir} does not exist:

Error: project directory not found: {dir}
Run /trekbrief first to create it.

Create {dir}/research/ if it does not already exist.

When {dir}/brief.md exists, ALWAYS run the brief-validator (soft mode) AND the composed phase-model resolver for this command's phase before continuing. The resolver's JSON output {effort, model, source} (brief signal > profile > default) is captured as phase_signal_result and used at Agent-spawn sites in Phase 4 to inject the resolved model:

# When --min-brief-version was passed, append --min-version {min_brief_version}
# so an older brief raises BRIEF_VERSION_BELOW_MINIMUM (warn, never block).
node ${CLAUDE_PLUGIN_ROOT}/lib/validators/brief-validator.mjs --soft --json [--min-version {min_brief_version}] "{dir}/brief.md"
# v5.9 — composed resolver: ONE call returns {effort, model, source}.
# Append --profile {profile} when the operator passed --profile.
node ${CLAUDE_PLUGIN_ROOT}/lib/profiles/resolver.mjs --resolve-phase-model --phase research --brief-path "{dir}/brief.md" [--profile {profile}] --json

--gates — autonomy control. When present, set gates_mode = true. The research command will pause after each topic completes ("Topic N complete. Proceed to topic N+1? (yes/no)"). Default gates_mode = false means topics run continuously. The flag is consumed by the autonomy-gate state machine via the CLI shim: node ${CLAUDE_PLUGIN_ROOT}/lib/util/autonomy-gate.mjs --state X --event Y --gates {true|false}.
--min-brief-version <ver> — (optional) version floor for an attached --project brief. Set min_brief_version = {ver} (e.g. 2.2). Forwarded to the brief-validator below as --min-version {ver}; an older brief emits a BRIEF_VERSION_BELOW_MINIMUM warning (never blocks) because framing enforcement only fires at ≥ 2.2. Absent → no version check. See docs/HANDOVER-CONTRACTS.md §Handover 1 for the pre-2.2 enforcement hole.
--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
--project <dir> --external — attach external research to a project
--quick alone implies both local and external (lightweight)

Defaults: scope = both, execution = foreground (only mode as of v2.4.0), project_dir = none, engine = swarm.

After stripping flags, the remaining text is the research question.

If no research question is provided, output usage and stop:

Usage: /trekresearch <research question>
       /trekresearch --quick <research question>
       /trekresearch --local <research question>
       /trekresearch --external <research question>
       /trekresearch --fg <research question>
       /trekresearch --project <dir> [--external|--local|--quick|--fg] <research question>

Modes:
  default       Interview → foreground research (local + external) → brief
  --quick       Interview (short) → inline research (no agent swarm)
  --local       Only codebase analysis agents (skip external + Gemini)
  --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

Examples:
  /trekresearch Should we migrate from Express to Fastify?
  /trekresearch --quick What auth libraries are popular for Node.js?
  /trekresearch --local How is error handling structured in this codebase?
  /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.

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}

Compute brief destination

If project_dir is set:

Scan {project_dir}/research/ for existing files matching NN-*.md.
Find the highest existing index; set N = highest + 1. If no files exist, N = 1.
Zero-pad to 2 digits: 01, 02, ...
Brief destination: {project_dir}/research/{NN}-{slug}.md

If project_dir is not set:

Brief destination: .claude/research/trekresearch-{YYYY-MM-DD}-{slug}.md

Store as brief_destination for use in later phases.

Phase 2 — Research interview

Use AskUserQuestion to clarify the research question. Ask one question at a time.

The interview is shorter than trekplan's (2-4 questions, not 3-8) because research is more focused than planning.

Interview flow

Start with the research question itself. If the user provided a clear, specific question, you may skip directly to follow-ups.

Core questions (pick 2-4 based on clarity of initial question):

Decision context: "What decision does this research feed? Are you evaluating options, investigating feasibility, or building understanding?" Skip if the question itself makes this obvious.
Dimensions: "Are there specific aspects you care about most? (e.g., performance, security, migration cost, team learning curve)" Skip if the question is narrow enough that dimensions are obvious.
Prior knowledge: "What do you already know about this topic? What have you tried or ruled out?" Always useful — prevents redundant research.
Constraints: "Are there constraints that should guide the research? (e.g., must be open-source, must support X, budget limitations)" Skip if no constraints are apparent.

Rules:

If the user says "just research it", "skip", or similar — stop interviewing. Use the research question as-is.
For --quick mode: ask 1-2 questions maximum.
Never ask about things you can discover from the codebase.

Determine research dimensions

Based on the interview, identify 3-8 research dimensions. These are the facets of the question that will be investigated in parallel. Examples:

"Should we use Redis?" → dimensions: performance, reliability, operational complexity, security, cost, team familiarity
"How should we handle auth?" → dimensions: standards compliance, implementation complexity, library ecosystem, security posture, scalability

Report dimensions:

Research dimensions identified:
1. {Dimension 1}
2. {Dimension 2}
...

Phase 3 — Slug and destination (foreground)

Generate a slug from the research question (first 3-4 meaningful words, lowercase, hyphens). Confirm the brief_destination computed in Phase 1.

Report to the user:

Research pipeline running in foreground.

  Question: {research question}
  Dimensions: {N} identified
  Scope: {both | local | external}
  Project: {project_dir or "-"}
  Brief:   {brief_destination}

Then continue to the next phase inline.

Why foreground (for now)? The research-orchestrator was moved out of background mode in v2.4.0 because, before Claude Code 2.1.172, the harness did not expose the Agent tool to sub-agents, so an orchestrator launched with run_in_background: true could not spawn the documented research swarm (docs-researcher, community-researcher, etc.) and silently degraded to single-context reasoning without WebSearch / Tavily / WebFetch / Gemini. As of CC 2.1.172 sub-agents can spawn sub-agents (up to 5 levels deep), so that block no longer holds — a delegated redesign is under evaluation (see docs/cc-upgrade-2.1.181-decision-matrix.md, W1/CC-26). Until then, running the phases inline in main context keeps the swarm intact. Use claude -p in a separate terminal window for long-running headless work.

All remaining phases run inline in the main command context.

Phase 3.5 — Quick mode (inline research)

Skip this phase entirely unless mode = quick.

For quick mode, do NOT launch an agent swarm. Instead, do lightweight research directly using available tools.

Quick local research (if scope includes local)

Glob for files matching key terms from the research question (up to 3 patterns)
Grep for relevant definitions, patterns, or usage (up to 5 patterns)
Read the 2-3 most relevant files found

Quick external research (if scope includes external)

Use available search tools directly (in this priority order):

mcp__tavily__tavily_search — if available, use for 2-3 targeted queries
WebSearch — fallback for 2-3 targeted queries
WebFetch — fetch 1-2 specific pages if URLs were found

Quick synthesis

Synthesize findings inline. Write a lightweight research brief to the destination path, following the research-brief-template but with shorter sections and fewer dimensions.

Skip to Phase 8 (stats tracking) after writing the brief.

Phase 4 — Parallel research (agent swarm)

Determine which agents to launch based on scope:

Local agents (scope = both or local)

Reuse existing plugin agents with research-focused prompts. These agents are designed for planning, but work equally well for research when prompted differently.

Agent	Purpose in research context
`architecture-mapper`	How the architecture relates to the research question
`dependency-tracer`	Dependencies and integrations relevant to the topic
`task-finder`	Existing code that relates to the research question
`git-historian`	Recent changes and ownership relevant to the topic
`convention-scanner`	Coding patterns relevant to evaluating options

For each local agent, prompt with the research question, NOT a task description:

architecture-mapper: "Analyze the architecture relevant to this research question: {question}. Focus on how {topic} relates to current patterns and constraints."
dependency-tracer: "Trace dependencies relevant to this research question: {question}. Identify which modules would be affected by {topic}."
task-finder: "Find existing code relevant to this research question: {question}. Look for prior implementations, patterns, or utilities related to {topic}."
git-historian: "Analyze git history relevant to this research question: {question}. Who owns the relevant code? What has changed recently in related areas?"
convention-scanner: "Discover coding conventions relevant to evaluating {question}. What patterns would a solution need to follow?"

Engine selection (scope = both or external)

--engine affects ONLY the external portion of research. The local agents (### Local agents above) and Phases 6–7 (triangulation, synthesis, brief writing) are engine-agnostic — they run identically regardless of engine.

--engine is moot (treated as swarm) whenever the external phase does not run at all: --local, --quick, effort == 'low', or a profile with external_research_enabled == false (the economy/balanced auto-disable — see Profile below). The profile's on/off switch wins. Initialize effective_engine = {requested engine}.

engine = swarm (default): run the ### External agents + ### Bridge agent blocks below unchanged. This is byte-for-byte the current path, so --engine swarm changes nothing (SC1). Keep the native-swarm anchors intact ("in parallel", "single message", model: "opus").

engine = deep-research:

Coarse pre-gate (best-effort, NOT a trust signal). Bash: claude --version; parse the leading X.Y.Z (e.g. from 2.1.196 (Claude Code)) and compare numerically against 2.1.154 — split each on . and compare major, then minor, then patch as integers (do NOT string-compare; lexical comparison mis-orders multi-digit patch numbers). If the version is < 2.1.154, OR if disableWorkflows: true / CLAUDE_CODE_DISABLE_WORKFLOWS=1 is set, skip to the fallback (step 4). If claude is not on PATH inside the Bash tool (possible under claude -p) or the version cannot be parsed, treat the pre-gate as indeterminate and proceed to step 2 — do NOT hard-fail. There is no positive availability probe (research Dim 4), so a passing pre-gate does not guarantee the workflow runs; the post-hoc check (step 3) is the authoritative guard.
Run. Instruct Claude (in prose, this turn) to run /deep-research <research question> and request per-claim citations. Note: interactive default/acceptEdits triggers a per-run approval prompt; claude -p / SDK / bypass runs immediately.
Post-hoc presence + provenance check (the real guard). Verify a real, cited /deep-research report actually landed in context — substantive findings with citations, not an empty/denied/errored turn and not bare error text. This check must be robust to all failure manifestations (workflow disabled, approval denied, runtime error, empty output), because the disabled-headless behavior is undocumented: no recognizable cited report in context → fall back, regardless of how the failure surfaces.
On no real report (fallback): set effective_engine = swarm, run the swarm blocks below, and log the fallback at this decision point — print Engine: deep-research → swarm (fallback: <reason>) and carry the reason into the Phase-8 Present summary and the brief's ## Executive Summary. NEVER fabricate or synthesize a substitute report — a structurally-valid-but-invented brief passes the structure-only validator and silently poisons /trekplan; that is the worst outcome of this feature.
On a real report: keep effective_engine = deep-research, log Engine: deep-research (active), and carry the report into Phase 6 triangulation as the external-findings input (adapted in Phase 7 — see the Deep-research engine adapter below).

External agents (scope = both or external)

Launch the new research-specialized agents:

Agent	Purpose
`docs-researcher`	Official documentation, RFCs, vendor docs
`community-researcher`	Real-world experience, issues, blog posts
`security-researcher`	CVEs, audit history, supply chain risks
`contrarian-researcher`	Counter-evidence, overlooked alternatives

For each external agent, pass: the research question, specific dimensions to investigate, and any context from the interview.

Bridge agent (scope = both or external, if enabled)

Launch gemini-bridge with the research question. Do NOT include findings from other agents — the value of Gemini is independence.

Launch rules

Launch ALL selected agents in parallel in a single message
Use model: "opus" for all sub-agents (the orchestrator runs on Opus)
Scale maxTurns by codebase size for local agents (same as trekplan): small = halved, medium/large = default
convention-scanner: medium+ codebases only (50+ files)

Phase 5 — Targeted follow-ups

Review all agent results. Identify knowledge gaps — areas where findings are thin, contradictory, or missing.

For each significant gap, launch a targeted follow-up agent (model: "opus") with a narrow, specific brief. Maximum 2 follow-ups.

If no gaps exist, skip: "Initial research sufficient — no follow-ups needed."

Phase 6 — Triangulation

This is the KEY phase that makes trekresearch more than aggregation.

For each research dimension:

Collect — gather relevant findings from local AND external agents
Compare — do local findings agree with external findings?
Flag contradictions — where they disagree, present both sides with evidence
Cross-validate — use codebase facts to validate external claims:
- External says "library X is fast" → local shows the codebase already uses a similar pattern that could benchmark against
- External says "pattern Y is best practice" → local shows the codebase uses pattern Z which conflicts
Rate confidence per dimension:
- high — multiple authoritative sources agree, local evidence confirms
- medium — good sources but limited cross-validation
- low — single source, limited evidence
- contradictory — credible sources actively disagree

Compute overall confidence as a weighted average (0.0-1.0) based on dimension confidence levels and their relative importance.

Phase 7 — Synthesis and brief writing

Read the research brief template: @${CLAUDE_PLUGIN_ROOT}/templates/research-brief-template.md

Write the research brief following the template. Key rules:

Executive Summary — 3 sentences. Answer, confidence, key caveat.
Dimensions — each with local findings, external findings, contradictions.
Synthesis — NOT a summary. NEW insights from triangulation.
Open Questions — what remains unresolved and why.
Recommendation — only if decision-relevant. Omit for exploratory research.
Sources — every claim traced to URL or codebase path.

Generate the slug from the research question (first 3-4 meaningful words). Write the brief to the brief_destination computed in Phase 1:

With --project: {project_dir}/research/{NN}-{slug}.md
Without --project: .claude/research/trekresearch-{YYYY-MM-DD}-{slug}.md

Create the parent directory if it does not exist.

Deep-research engine adapter (engine = deep-research only)

Only when effective_engine == deep-research. The swarm path skips this entirely — its findings already flow through Phases 6–7 unchanged (SC1).

Transform the in-context /deep-research report INTO @${CLAUDE_PLUGIN_ROOT}/templates/research-brief-template.md — do NOT paste the raw report. Specifically:

Reduce the report to ≥ 1 ### {Dimension} -- Confidence: {high|medium|low} entry, each carrying External findings bullets with per-claim source URLs. Local findings still come from the local agents (Phase 4) and are merged in per dimension as usual.
Emit a numeric confidence ∈ [0,1] in frontmatter and a 3-sentence ## Executive Summary (answer, confidence, key caveat).
Populate ## Sources from the report's citations.
If the report lacks per-claim URLs, lower the confidence and note the gap in ## Open Questions — do NOT fabricate URLs. Provenance you cannot cite is not provenance.
If the report is large, bound the transform to the top dimensions to avoid context truncation.

Output self-check (engine = deep-research only)

Only when effective_engine == deep-research. After writing to brief_destination, run the output validator and repair-or-fall-back. This mirrors the trekplan Phase-8 write→validate→repair self-check; the swarm path does NOT run it, so swarm behavior is unchanged (SC1):

node ${CLAUDE_PLUGIN_ROOT}/lib/validators/research-validator.mjs --json "{brief_destination}"

On valid: false, repair the brief to satisfy the reported errors and re-run the validator. If it cannot be made valid (e.g. the report was too thin to yield even one dimension), set effective_engine = swarm, fall back to the swarm engine for this run (and log the fallback per the Engine selection step), rather than emit an invalid brief.

Phase 8 — Present and track

Present a summary to the user:

## Ultraresearch Complete

**Question:** {research question}
**Mode:** {default | quick}, Scope: {both | local | external}
**Brief:** {brief_destination}
**Project:** {project_dir or "-"}
**Engine (effective):** {swarm | deep-research}{, with fallback reason if it fell back}
**Confidence:** {overall confidence 0.0-1.0}
**Dimensions:** {N} researched
**Agents:** {N} local + {N} external + {gemini: used | unavailable | skipped}

### Key Findings
- {Finding 1}
- {Finding 2}
- {Finding 3}

### Contradictions Found
- {Contradiction 1, or "None — findings are consistent across sources."}

### Open Questions
- {Question 1, or "None — all dimensions adequately covered."}

You can:
- Read the full brief at {brief_destination}
- If `--project` was used: run `/trekplan --project {project_dir}` when all research topics are complete
- Otherwise: `/trekplan --research {brief_destination} --brief <your-brief.md>`
- Ask follow-up questions about specific findings

Stats tracking

Write a session record to ${CLAUDE_PLUGIN_DATA}/trekresearch-stats.jsonl (create the file if it does not exist).

Record format (one JSON line):

{
  "ts": "{ISO-8601 timestamp}",
  "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}",
  "dimensions": {N},
  "agents_local": {N},
  "agents_external": {N},
  "gemini_used": {true|false},
  "confidence": {0.0-1.0},
  "contradictions": {N},
  "open_questions": {N}
}

If ${CLAUDE_PLUGIN_DATA} is not set or not writable, skip tracking silently.

Profile (v4.1)

Accepts --profile <name> where <name> is economy, balanced, premium, fable, or a custom profile under voyage-profiles/. Default: premium.

Resolution order (per lib/profiles/resolver.mjs):

--profile flag (source: flag)
VOYAGE_PROFILE env-var (source: env)
premium default (source: default)

The profile dictates phase_models.research, parallel_agents, and external_research_enabled. economy and balanced profiles auto-disable the external research swarm regardless of --external flag (operator override deferred to v4.2).

Examples:

/trekresearch --profile economy --project .claude/projects/2026-05-09-add-auth
VOYAGE_PROFILE=balanced /trekresearch

Stats records emit profile, phase_models, parallel_agents, external_research_enabled, profile_source, and engine so operators can audit which profile and engine drove which session.

Composition rule (v5.1)

Independent of the profile system. When brief.md carries phase_signals (brief_version ≥ 2.1), each downstream phase resolves effort + model as:

effort_for_phase = brief.phase_signals[<phase>]?.effort ?? 'standard'
model_for_phase  = brief.phase_signals[<phase>]?.model  ?? profile.phase_models[<phase>]

The brief signal wins per-phase when present; the profile fills any gaps. Both fields are mechanically resolved by the single composed CLI node ${CLAUDE_PLUGIN_ROOT}/lib/profiles/resolver.mjs --resolve-phase-model invoked in Phase 1; the resolved JSON {effort, model, source} is captured as phase_signal_result and passed to Agent tool calls explicitly. The resolver controls the model parameter at Agent-spawn sites only — the orchestrator's own model is fixed at invocation time (command frontmatter omits model:, so it follows the session model) and cannot be switched mid-turn. Sub-agents fall back to model: in their own agents/*.md frontmatter when no spawn-site injection happens.

For /trekresearch specifically: effort == 'low' activates the existing --quick-equivalent code-path (inline research, no agent swarm). effort == 'standard' (or absent) → no change. effort == 'high' activates the high-effort behavior documented under ### High-effort behavior (v5.1.1) below.

Sequencing gate surface

When /trekresearch --project <dir> is invoked and {dir}/brief.md exists, ALWAYS run brief-validator.mjs --soft --json against it. If BRIEF_V51_MISSING_SIGNALS appears in errors (brief_version ≥ 2.1 without phase_signals or phase_signals_partial: true), halt with: Brief is brief_version 2.1 but does not carry phase_signals — re-run /trekbrief to commit them (Phase 3.5). Enforcement is validator-only; commands surface, don't re-enforce.

High-effort behavior (v5.1.1)

When phase_signal_result.effort == 'high' for the research phase, run the FULL swarm regardless of normal triggering rules: 5 local agents + 4 external agents + 1 bridge agent, AND force contrarian-researcher AND gemini-bridge to always-on. Normally contrarian-researcher triggers conditionally when a leading recommendation is emerging from initial agents; in high-effort mode it runs unconditionally so the final brief always carries an adversarial counter-evidence pass. Similarly, gemini-bridge normally activates on significant architectural questions or when triangulation value is high; in high-effort mode it runs unconditionally to provide an independent second opinion.

Standard effort (or absent): use the existing conditional triggers. Low effort: inline research only, no agent swarm (existing --quick-equivalent code-path).

Hard rules

No planning: This command produces research briefs, not implementation plans. If the user asks to plan, direct them to /trekplan --research <brief>.
Sources required: Every claim must cite a source. No unsourced findings.
Independence: Do not pre-bias external agents with local findings or vice versa. Triangulate AFTER independent research.
Graceful degradation: If MCP tools are unavailable (Tavily, Gemini, MS Learn), proceed with available tools and note limitations in brief metadata.
Cost: Model resolution at Agent-spawn sites is a three-layer fallback: brief phase_signals[<phase>].model > profile.phase_models[<phase>] > agent frontmatter model:. The composed resolver returns the first two layers as phase_signal_result.model; spawn sites inject it, and agent frontmatter is the fallback when no injection happens.
Privacy: Never log secrets, tokens, or credentials.
Honesty: If the question is trivially answerable, say so. Don't inflate research.
Scope of codebase: Only analyze the current working directory for local research.
Research transparency: Clearly distinguish local findings from external findings. Never blend them without attribution.

29 KiB Raw Permalink Blame History Unescape Escape