Kjell Tore Guttormsen
4e5523fb0a
Claude Code 2.1.218 changed /deep-research to start only when invoked
manually; from there the Skill tool refuses a model invocation outright
with `disable-model-invocation` (measured in a real `--engine deep-research`
run 2026-09-01 18:32Z - the SC3 fallback to swarm held). The engine was
built against 2.1.196 and the prose still promised a path Claude Code has
removed ("requires Claude Code 2.1.154+").
The flag is KEPT as an additive opt-in that never hard-fails. Prose only:
no lib/ change, no adapter-contract change, no default change, no version
bump.
- commands/trekresearch.md: flag bullet states the closed window
`2.1.154 <= CC < 2.1.218`; the pre-gate gained an UPPER ceiling (still a
numeric comparison, not a string one) that skips straight to the fallback
with reason `disable-model-invocation`; step 3 names the Skill-tool
refusal as a known failure manifestation; step 4 lists the reason tokens.
- docs/command-modes.md + README.md: same window, one sentence each, on the
reference row itself.
- CHANGELOG.md: Unreleased/Docs entry.
Tests first (Iron Law): tests/lib/doc-consistency.test.mjs gained a pin
requiring 2.1.218 + disable-model-invocation on all three surfaces, on both
reference rows, and in both load-bearing regions of the command (flag
bullet + pre-gate). Seen red on all three surfaces before the prose change.
tests/commands/trekresearch-engine.test.mjs unchanged and green.
New baseline: 1024 tests, 1022 pass / 0 fail / 2 skip (was 1023: 1021/0/2).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
105 lines
8.1 KiB
Markdown
105 lines
8.1 KiB
Markdown
# Voyage — Command flag reference
|
||
|
||
Per-command flag tables, imported from `CLAUDE.md` via pointer.
|
||
|
||
## /trekbrief modes
|
||
|
||
| Flag | Behavior |
|
||
|------|----------|
|
||
| _(default)_ | Dynamic interview until quality gates pass → brief.md with research plan |
|
||
| `--quick` | Compact start; still escalates if required sections are weak or the brief-review gate fails → brief.md with research plan |
|
||
| `--gates {true\|false}` | (v3.4.0) Boolean autonomy-gate flag; present → gating on. Policy (`gates_mode`) detailed under `## Autonomy mode` in `docs/operations.md`. |
|
||
| `--profile <name>` | (v4.1.0) Model profile: `economy` / `balanced` / `premium` / `fable` / `<custom>`. Sets `phase_models` for the brief phase. See `## Profile system` in `docs/operations.md`. |
|
||
|
||
Always interactive. Phase 3 is a section-driven completeness loop (no hard cap on question count); Phase 4 runs a `brief-reviewer` stop-gate with max 3 review iterations. After writing the brief, asks the user to choose manual (print commands) or auto (Claude runs research + plan in foreground).
|
||
|
||
## /trekresearch modes
|
||
|
||
| Flag | Behavior |
|
||
|------|----------|
|
||
| _(default)_ | Interview + research (local + external) + synthesis + brief (foreground) |
|
||
| `--project <dir>` | Write brief to `{dir}/research/{NN}-{slug}.md` (auto-incremented) |
|
||
| `--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 default since v2.4.0) |
|
||
| `--gates {true\|false}` | (v3.4.0) Boolean autonomy-gate flag; present → gating on. Policy (`gates_mode`) detailed under `## Autonomy mode` in `docs/operations.md`. |
|
||
| `--min-brief-version <ver>` | (S18) Warn — never block — if an attached `--project` brief declares a version below `<ver>` (e.g. `2.2`), i.e. sidesteps framing enforcement |
|
||
| `--profile <name>` | (v4.1.0) Model profile for the research phase. |
|
||
| `--engine {swarm\|deep-research}` | (deep-research-engine) Opt-in external-research engine; `deep-research` delegates the external phase to Claude Code's built-in `/deep-research` workflow, which only works on `2.1.154 <= CC < 2.1.218` — from **2.1.218** `/deep-research` is operator-invoked only (the Skill tool refuses with `disable-model-invocation`), so the engine always falls back to `swarm`. Never hard-fails. Default `swarm`. |
|
||
|
||
Flags combine: `--project <dir> --local`, `--external --quick`.
|
||
|
||
### Bounded conversation loop (Phase 4.5 + Phase 5) — env-vars
|
||
|
||
Dimension discovery and the multi-turn follow-up loop are **default-off** and
|
||
have no flag; they are environment-gated, because turning them on costs turns.
|
||
They run only at `effort: high` (resolved from the brief's `phase_signals`).
|
||
|
||
| Env-var | Default | Behavior |
|
||
|---------|---------|----------|
|
||
| `VOYAGE_STORM_ENABLED` | _(unset — default-off)_ | `=1` grants the Phase 5 loop a non-zero turn budget and is the second condition on Phase 4.5's skip-guard. Unset, `research-loop-cap.mjs` grants 0 turns and **both** phases are inert: doing nothing keeps the whole mechanism off. |
|
||
| `TREKRESEARCH_MAX_CONV_TURNS` | `3` | Max turns per under-illuminated dimension. Budget = this × `maxDimensions` (8, `settings.json:16`). Empty, non-numeric, zero, negative, `Infinity`, or any fraction that floors below `1` (`0.5`, `0.9`) fall back to `3` — never to unbounded, and never to `0`. A fraction at or above `1` floors (`2.7` → `2`). |
|
||
| `VOYAGE_DISABLE_CAP_HOOK` | _(unset)_ | `=1` disables `hooks/scripts/pre-agent-cap.mjs`, the `PreToolUse` enforcement of the turn budget. The cap primitive still applies; only the second gate is switched off. |
|
||
|
||
Adoption of the loop as a default is gated on a pre-registered measurement —
|
||
protocol, thresholds, and the exact commands in
|
||
[`docs/storm-measurement.md`](storm-measurement.md).
|
||
|
||
## /trekplan modes
|
||
|
||
| Flag | Behavior |
|
||
|------|----------|
|
||
| `--project <dir>` | **Required path A** — read `{dir}/brief.md`, auto-discover `{dir}/research/*.md`, write `{dir}/plan.md` |
|
||
| `--brief <path>` | **Required path B** — plan from a specific brief file; write to `.claude/plans/trekplan-{date}-{slug}.md` |
|
||
| `--research <brief> [brief2]` | Enrich with extra research briefs beyond what is in `{project_dir}/research/` |
|
||
| `--fg` | No-op alias (foreground is default since v2.4.0) |
|
||
| `--quick` | Plan directly (no agent swarm) |
|
||
| `--min-brief-version <ver>` | (S18) Warn — never block — if the brief declares a version below `<ver>` (e.g. `2.2`), i.e. sidesteps framing enforcement |
|
||
| `--export headless <plan>` | Legacy alias for `--decompose` — the only remaining export format (the `pr` / `issue` / `markdown` variants were removed; Claude reformats a plan ad-hoc on request) |
|
||
| `--decompose <plan>` | Split plan into self-contained headless sessions |
|
||
| `--gates {true\|false}` | (v3.4.0) Boolean autonomy-gate flag; present → gating on. Policy (`gates_mode`) detailed under `## Autonomy mode` in `docs/operations.md`. |
|
||
| `--profile <name>` | (v4.1.0) Model profile for the plan phase (and others, since plan emits `profile:` to plan.md frontmatter). |
|
||
|
||
**Breaking change (v2.0):** one of `--brief` or `--project` is required. There is no interview inside `/trekplan`. The `--spec` flag has been removed — use `/trekbrief` to produce a brief instead.
|
||
|
||
If `{project_dir}/architecture/overview.md` exists (typically produced by an opt-in upstream architect plugin, not bundled), the plan command auto-discovers it and treats `cc_features_proposed` as priors. Missing file is fine — discovery is additive, not required.
|
||
|
||
## /trekexecute modes
|
||
|
||
| Flag | Behavior |
|
||
|------|----------|
|
||
| _(default)_ | Execute plan — auto-detects Execution Strategy for multi-session |
|
||
| `--project <dir>` | Read `{dir}/plan.md`, write `{dir}/progress.json` |
|
||
| `--resume` | Resume from last progress checkpoint |
|
||
| `--dry-run` | Validate plan structure without executing |
|
||
| `--validate` | Schema-only check — parse steps + manifests, report `READY \| FAIL`, no execution |
|
||
| `--step N` | Execute only step N |
|
||
| `--fg` | Force foreground — run all steps sequentially, ignore Execution Strategy |
|
||
| `--session N` | Execute only session N from plan's Execution Strategy |
|
||
| `--gates {true\|false}` | (v3.4.0) Boolean autonomy-gate flag; present → gating on. Policy (`gates_mode`) detailed under `## Autonomy mode` in `docs/operations.md`. |
|
||
| `--profile <name>` | (v4.1.0) Model profile for the execute phase. Inherited from plan.md frontmatter `profile:` if present. |
|
||
|
||
## /trekreview modes
|
||
|
||
| Flag | Behavior |
|
||
|------|----------|
|
||
| _(default)_ | Run brief-conformance + code-correctness reviewers in parallel, coordinator dedup + verdict, write `{project_dir}/review.md` |
|
||
| `--project <dir>` | **Required.** Path to trekplan project folder containing `brief.md`. Review is written to `{dir}/review.md` |
|
||
| `--since <ref>` | Override "before" SHA for the diff range. Validated via `git rev-parse --verify` |
|
||
| `--quick` | Skip brief-conformance reviewer; skip coordinator's reasonableness filter — fast correctness-only pass |
|
||
| `--validate` | Schema-only check on existing `{dir}/review.md`. No LLM calls |
|
||
| `--dry-run` | Print discovered scope + triage map; skip writes |
|
||
| `--fg` | No-op alias (foreground is default) |
|
||
| `--workflow` | (opt-in, NW2) Run Phase 5–6 on the bake-off-validated Workflow substrate (`scripts/trekreview-armB.workflow.mjs`) instead of the default prose path. Default stays prose; requires **Claude Code 2.1.154+** (raises the consumer floor — opt-in for portability). Fidelity-equivalent per `docs/T2-bakeoff-results.md` |
|
||
| `--profile <name>` | (v4.1.0) Model profile for the review phase. |
|
||
|
||
## /trekcontinue modes
|
||
|
||
| Flag | Behavior |
|
||
|------|----------|
|
||
| _(default)_ | Auto-discover active project's `.session-state.local.json` and resume |
|
||
| `<project-dir>` | Resume the next session of an explicit project directory |
|
||
| `--profile <name>` | (v4.1.0) Model profile for the resumed session. Inherited from the previous session's plan.md frontmatter when absent. |
|
||
|
||
The triage gate is deterministic — path-pattern classifier produces `{file → deep-review|summary-only|skip}`. Hard refuse-with-suggestion above 100 files / 100K diff tokens.
|