open/voyage
1
0
Fork 0
Code Issues Releases 2 Activity
voyage/CLAUDE.md
Kjell Tore Guttormsen 1ca48e0cd0 release(v5.10.1): drop gemini-bridge from the pipeline; correct the T1 §6 PoC status 
gemini-bridge is dropped by operator directive (three repetitions). The drop is
permanent, not a wait-for-SDK-upgrade state, so the change clears every LIVE
surface that could still steer a run toward the agent and leaves the historical
record alone.

Live surfaces cleared: agents/gemini-bridge.md deleted; trekresearch (bridge
launch block, --local help, high-effort always-on pair, stats record,
degradation list), trekplan, trekbrief, research-orchestrator (mode table,
agent table, prompting block, summary line), README (feature prose, mode table,
agent prose, mermaid EXTERNAL node, conditional legend, optional-MCP
requirement, --local section), CLAUDE.md, settings.json (the whole
trekresearch.geminiBridge block), both templates, architecture.md,
command-modes.md.

trekplan high-effort Adversarial Pass 2 now degrades EXPLICITLY: it emits its
section with status "unavailable, skipped" instead of failing or vanishing. A
high-effort plan carrying no Pass 2 marker is indistinguishable from one whose
Pass 2 crashed, which is the failure mode this wording exists to prevent.

gemini_used is deliberately KEPT as a vestigial trekresearch stats field pinned
to false. Removing it would break the observability export schema for existing
consumers, and the directive was about the agent, not the field.

Not touched: CHANGELOG history and the measurement/decision docs keep their
gemini references. They record what a past version did or what was measured
then; rewriting them is the same defect class as bumping a version string
inside a measurement doc.

Driven test-first. Five new pins in tests/lib/doc-consistency.test.mjs, verified
RED before the edits, including a KNOWN-POSITIVE CONTROL asserting the
historical records still DO carry gemini references — so the empty result on
live surfaces is a measurement and not a broken query (Verifiseringsloven
ansikt 4). Agent inventory 24 -> 23 (20 spawnable + 3 orchestrator reference
docs); the <example>-block floor moves 34 -> 32 because an agent legitimately
left the inventory, not because examples went missing from a surviving one.

Docs: docs/T1-cc26-delegated-orchestration.md §8 item 3 claimed both the §6
synthesis-agent PoC and the §5 bake-off were "designed but unbuilt". That was
written in S7 and falsified the same afternoon by S12, which ran the §6 PoC and
recorded Δ main-context (faithful flow) = 0.0%, NEGATIVE. The stale wording is
what caused the settled PoC to be re-ordered as new work on 2026-09-02, so it is
struck rather than deleted and §6 gained a RUN AND DECLINED status block. The
finding is structural, not stochastic: Phase 5 spawns the exploration swarm
foreground (trekplan.md:158,338-341), so the outputs are already resident in
main before Phase 7 — delegating only the Phase-7 digest evicts nothing.

Also measured 2026-09-03 (CC 2.1.259): claude -p --output-format stream-json
runs on subscription auth with no ANTHROPIC_API_KEY and now emits a
subagent_stats block, so S12's environment-block premise is half stale. Recorded
in §8 item 4. It lowers the cost of §5; it changes nothing about §6.

Suite 1041 (1039/0/2), up from 1036 by exactly the five tests added.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-03 20:29:39 +02:00

8.1 KiB
Raw Blame History

trekplan

Voyage — a contract-driven Claude Code pipeline: brief, research, plan, execute, review, continue. Deep implementation planning and research with specialized agent swarms, external research, adversarial review, session decomposition, disciplined execution, and headless support.

Design principle: Context Engineering — build the right context by orchestrating specialized agents. Each step in the pipeline (brief → research → plan → execute) produces a structured artifact that the next step consumes. The load-bearing benefit is the parallel wall-clock + structured artifact handoffs; main-context relief is asserted-by-design, not measured (Δ ≈ 0 in the one PoC — see docs/T1-synthesis-poc-results.md).

Architecture slot. The plan command auto-discovers architecture/overview.md if present — any compatible producer plugs in (the architect plugin is no longer publicly distributed). Migration history (v3.0.0 extraction) → CHANGELOG.md.

Trinity context (informational). Voyage is Tier 1 (per-task) of a three-tier architecture. Asymmetry is a hard invariant: Voyage stays unaware of Tier 2/3; Handover 1 (brief format) is the only integration point, no producer is privileged, and brief-schema changes are breaking for downstream consumers (formalized as a public contract in v5.5.0). Tier 2/3 producer detail + the public contract → docs/HANDOVER-CONTRACTS.md §Handover 1 (PUBLIC CONTRACT).

Cross-cutting invariant: brief framing must match operator intent. The brief is the pipeline's source of truth; operator intent lives in memory files — the pipeline must not polish a wrong premise. Enforced as the brief_version 2.2 gate (v5.5), all BLOCKER for briefs declaring ≥ 2.2: (1) explicit framing: preserve|refine|replace|new-direction frontmatter, AskUserQuestion-validated in /trekbrief Phase 2.5; (2) memory-alignment as brief-reviewer dimension 6; (3) mandatory ## TL;DR. Existing 2.0/2.1 briefs stay valid; trekreview briefs are exempt. Full implementation + contract evolution → docs/HANDOVER-CONTRACTS.md §Handover 1 (PUBLIC CONTRACT).

Commands

Command Description Model
/trekbrief Brief — interactive interview produces a task brief with explicit research plan; optionally orchestrates the pipeline opus
/trekresearch Research — deep local + external research, produces structured research brief. Opt-in --engine {swarm|deep-research} delegates the external phase to Claude Code's built-in /deep-research workflow (swarm default) opus
/trekplan Plan — brief-reviewer, explore, plan, review. Requires --brief or --project. Auto-discovers architecture/overview.md if present opus
/trekexecute Execute — disciplined plan/session-spec executor with failure recovery opus
/trekreview Review — independent post-hoc review of delivered code against the brief. Produces review.md with severity-tagged findings (Handover 6) opus
/trekcontinue Continue — resumes the next session of a multi-session voyage project. Reads .session-state.local.json (Handover 7) and immediately begins executing opus
/trekendsession End-session — mark the current session complete and write session-state pointing at the next session. Helper for informal multi-session flows opus

Full flag reference for each command (modes, --gates, --profile, breaking changes): see docs/command-modes.md.

STORM bounded loop — default-off, env-gated. /trekresearch Phase 4.5 (dimension discovery, under the existing maxDimensions: 8 ceiling) and Phase 5 (bounded multi-turn follow-up) run only at effort: high and only when VOYAGE_STORM_ENABLED=1; unset, both are inert — Phase 5 because lib/util/research-loop-cap.mjs grants a budget of 0, Phase 4.5 because its skip-guard reads the flag directly (it never calls the cap). TREKRESEARCH_MAX_CONV_TURNS (default 3, invalid values fall back to 3) sets turns per dimension; the budget is that × maxDimensions. VOYAGE_DISABLE_CAP_HOOK=1 switches off hooks/scripts/pre-agent-cap.mjs, the PreToolUse gate that enforces the budget in the harness rather than trusting prose. The cap counts turns from its own append-only ledger. Adoption as a default is gated on the pre-registered measurement in docs/storm-measurement.md — decline is a no-op, adopt is one constant.

Agents

Agent Model Role
planning-orchestrator opus Inline reference documentation for the planning pipeline workflow (brief-driven)
research-orchestrator opus Inline reference documentation for the research pipeline workflow
review-orchestrator opus Inline reference documentation for the review pipeline workflow
architecture-mapper opus Codebase structure, tech stack, patterns
dependency-tracer opus Import chains, data flow, side effects
task-finder opus Task-relevant files, functions, reuse candidates
risk-assessor opus Risks, edge cases, failure modes
test-strategist opus Test patterns, coverage gaps, strategy
git-historian opus Recent changes, ownership, hot files
research-scout opus External docs for unfamiliar tech (conditional, planning only)
convention-scanner opus Coding conventions: naming, style, error handling, test patterns
brief-reviewer opus Task brief quality (6 dimensions: completeness, consistency, testability, scope clarity, research plan validity, memory alignment)
brief-conformance-reviewer opus Brief conformance review (SC + Non-Goal traceability)
code-correctness-reviewer opus Code correctness review (7 dimensions)
review-coordinator opus Judge Agent — dedup + reasonableness filter + verdict
plan-critic opus Adversarial plan review (10 dimensions)
scope-guardian opus Scope alignment (creep + gaps)
session-decomposer opus Splits plans into headless sessions with dependency graph
synthesis-agent opus Distills Phase-5/7 exploration outputs into a findings digest (NW3 PoC — dormant, not wired; delegating Phase 7 alone yields Δ main-context ≈ 0, see docs/T1-synthesis-poc-results.md)
docs-researcher opus Official documentation, RFCs, vendor docs (Tavily, MS Learn)
community-researcher opus Community experience: issues, blogs, discussions
security-researcher opus CVEs, audit history, supply chain risks
contrarian-researcher opus Counter-evidence, overlooked alternatives

Inventory (S33 reconcile, updated v5.10.1). 23 agent files = 20 spawnable (one, synthesis-agent, ships dormant — Δ≈0, wired to nothing) + 3 orchestrator reference docs (planning-/research-/review-orchestrator document the inline /trek* workflow, not spawnable capabilities). All 23 stay model: opus (operator pin 40d8742); the glue/mechanical/retrieval/dormant roles were reconsidered for a sonnet downgrade and kept opus — decision record: docs/voyage-vs-cc-balance-analysis.md §10.

Model & effort. opus = Opus 4.8 (default reasoning effort high); sonnet = Sonnet 4.6; fable = Fable 5 (Mythos-class, above Opus — reasoning effort inherits from the session; xhigh requires a session-level setting). Select agents carry native per-spawn effort: (retrieval → medium, adversarial-reasoning → high) — a different axis from brief phase_signals.effort (orchestration shape: which agents/passes run). Per-agent table + axes → docs/profiles.md §Model & effort axes.

Reference docs (read on demand)

  • Architecture, workflows, project-directory contract, state, terminology: docs/architecture.md
  • Quality infrastructure (lib/ validators, parsers, autonomy primitives, hooks): docs/architecture.md §Quality infrastructure
  • Autonomy gates (--gates), Path A/B/C decision: docs/operations.md
  • Profile system (--profile economy/balanced/premium/fable), lookup order, custom profiles: docs/operations.md
  • Observability (Stop hook, OTLP/textfile export, SSRF mitigation): docs/operations.md
  • Handover contracts (the 7 pipeline handovers): docs/HANDOVER-CONTRACTS.md