voyage/docs/voyage-vs-cc-balance-analysis.md

Voyage-vs-CC Balance Analysis

Status: Analysis — recommendations only, operator-gated before any implementation. Date: 2026-06-20. Baseline: Claude Code 2.1.183 (latest; 2.1.182 never shipped). Charter: docs/voyage-vs-cc-balance-charter.md. Method substrate: Dynamic Workflow (wf_41bb3936-e6d, 96 agents, ~2.97M subagent tokens, 4.6 min) + inline scout + an over-keeping meta-critic.

---

TL;DR

• Voyage's existence is justified by ONE thing the audit confirms end-to-end: typed, versioned, cross-stage/cross-session structured-artifact handovers (brief → research → plan → execute → review → continue) plus multi-session discipline. CC 2.1.183 has no native analog for a semver-stable public artifact contract or a typed work-state checkpoint. This matches the plugin's own CLAUDE.md self-admission and the operator's primary real use (large tasks across many sessions).
• It is NOT justified by the swarm-relieves-context claim (measured Δ ≈ 0, unchanged here) and not by re-implementing CC engines. Wherever CC ships the engine, Voyage's only defensible role is a thin policy layer that lowers the expertise bar — never a re-implementation.
• Disposition tally (35 capabilities, post-adversarial): KEEP 25 · THIN_WRAP 6 · SIMPLIFY 4 · DROP→NATIVE 0.
• The zero-DROP result is over-keeping at the edges. A meta-critic flags 4 genuine downgrade candidates (V09 Gemini-bridge, V15 text-export variants, V32 observability export, V35 dormant synthesis-agent). Acting on all of them trims the edges; it does not move the headline.
• Nothing recommended here breaks Handover 1 (the public brief contract). Every operator-pinned decision the analysis brushes is flagged, never silently overridden.

---

1. Method & evidence base (Phase 0–1)

1.1 Post-2.1.181 CC delta (Verification #4)

Latest CC = 2.1.183 (June 19 2026). 2.1.182 never existed (skipped build). 2.1.183 = bugfixes + auto-mode git safety guards only. No new features touch the Workflow tool, plan mode, Artifacts, subagent nesting, or session checkpointing. Several 2.1.183 fixes actually repair Voyage swarm failure modes (subagent-spawn 400s, empty WebSearch-in-subagent, silent thinking-only completions, tmux teammate launch, background-task premature termination) — no Voyage code change needed. Conclusion: the CC-native overlap baseline is unchanged from the 2.1.181 decision matrix.

1.2 Anchor verdicts carried in (not re-derived)

Prior finding	Verdict	Source
Sub-agents can nest ≤5 deep	true since CC 2.1.172 (old "harness hides Agent tool" premise is FALSE)	cc-upgrade-2.1.181-decision-matrix.md CC-01
Delegate the orchestration loop to a sub-agent (CC-26)	lean NO — only upside is main-context relief, measured Δ=0; new proliferation-classifier risk	T1-cc26-delegated-orchestration.md
Workflow tool as substrate (CC-27)	selective hybrid — schema-contract win real; wholesale swap DECLINED	T2-cc27-workflow-substrate.md
Synthesis delegated to a sub-agent (T1 PoC)	Δ main-context = 0.0% (exploration already runs foreground; digest returns on top) → dormant	T1-synthesis-poc-results.md
Flagship "swarm relieves context"	unproven; structured-artifact handovers are the load-bearing benefit	root CLAUDE.md (verbatim self-admission)

1.3 The two decision axes

• Axis A — Duplication: does CC 2.1.183 do this natively? does it do it better?
• Axis B — Expertise-bar: does Voyage's wrapper let a non-CC-expert get the value without knowing CC internals?

Disposition vocabulary: KEEP (Voyage-unique/clearly better) · THIN_WRAP (CC is the engine; keep a thin accessibility layer, delegate the engine) · DROP→NATIVE (CC better + no real expertise gap; remove + document native path) · SIMPLIFY (keep, shed complexity CC now handles).

The tension the analysis was forced to resolve per capability: a feature CC does "better" raw can still deserve THIN_WRAP if raw CC requires expertise — accessibility can justify a wrapper, never a re-implementation.

1.4 How the classification ran

35 canonical capabilities (consolidated from 42 command-level + ~30 infra inventory rows). Each ran a 3-stage pipeline: (A) CC-overlap map (sonnet) → (B) A×B classification → disposition (opus) → (C) adversarial verify of every KEEP/DROP→NATIVE (opus, high effort). Stage-B/C agents read the actual Voyage code (validators, hooks, command prose) and cite file:line. A final over-keeping meta-critic then attacked the zero-DROP outcome holistically (§4).

---

2. The balance thesis

Voyage sits on a host (CC) that has absorbed most of what a 2024-era "agent orchestration" plugin differentiated on: parallel sub-agent spawn, nesting, native effort:, plan mode, MCP, hooks, the Workflow tool. The audit's structural finding is that CC absorbed the primitives, not the contracts. Across all 35 capabilities, every CC overlap is cc_partial or cc_absent — CC ships the spawn/ask/hook/MCP engine, but never:

• a versioned, semver-stable, PUBLIC artifact schema an unrelated upstream producer can target (Handover 1),
• a typed cross-session work-state checkpoint with auto-discovery and zero-confirm resume (Handover 7),
• a standing per-handover validator library that gates the pipeline on written-artifact frontmatter,
• or the opinionated domain policy (research angles, review taxonomy, manifest predicates) a user would otherwise hand-author every run.

So the balance is:

• Where CC has no engine (most KEEPs) — brief contract, plan-schema enforcement, manifest audit, progress/resume, session-state, triangulation, the handover contract itself — Voyage is genuinely additive. KEEP.
• Where CC has the engine (the THIN_WRAPs) — research/exploration/reviewer swarms, the research interview, the Gemini bridge, observability — Voyage's job is to ride the native primitive and add only the thin policy, never to re-host the engine. THIN_WRAP, with a standing obligation to delegate the engine to CC.
• Where the wrapper's own contract layer is thin or empty (the over-keeping edge) — a "do-not-editorialize" pass-through agent, text reformatting, a re-hosted telemetry collector, a dormant measured-dead agent — the accessibility defense is rhetorical, and these are the DROP/downgrade candidates.

---

3. Phase 3 disposition matrix (Verification #1)

Each capability appears exactly once. Inventory count (35) = matrix rows (35). Axis A: nb=cc_native_better, eq=cc_native_equal, pt=cc_partial, ab=cc_absent. Axis B gap: H/M/L/none. Adv = per-capability adversarial verdict (— = not in KEEP/DROP scope). B = acting on it would change a handover contract. P = touches an operator-pinned decision.

ID	Capability	A	B	Disposition	Adv	B	P	Why (one line) + evidence-ref
V01	Interactive brief interview	pt	M	KEEP	upheld	·	P	Engine = AskUserQuestion; value = the completeness loop that emits Handover-1 brief.md. brief-validator.mjs
V02	Framing-intent gate	ab	H	KEEP	upheld	·	P	No native typed-enum non-skippable input gate; BRIEF_*FRAMING codes. brief-validator.mjs:110-154
V03	Per-phase effort signals	ab	H	KEEP	upheld	·	P	Native effort: is per-spawn reasoning, a different axis; no pipeline-wide phase signal. HANDOVER-CONTRACTS.md §1
V04	Brief quality review + revise loop	ab	H	KEEP	upheld	·	P	No native draft→review→revise rubric loop; spawn ≠ engine. brief-reviewer.md
V05	Memory-alignment defense	ab	H	KEEP	upheld	B	P	MEMORY.md is passive context; no native brief-vs-memory contradiction gate. brief-reviewer.md:160-186
V06	Brief→pipeline auto-orchestration	ab	M	KEEP	upheld	·	·	Skill tool is one-shot; Workflow can't span slash-command/handover boundaries. T2
V07	Research interview	pt	M	THIN_WRAP	—	·	·	AskUserQuestion is the engine; keep only the 4-dim/2-4-Q interview policy. trekresearch.md §2
V08	External research swarm	pt	H	THIN_WRAP	—	·	P	CC ships parallel-spawn+WebSearch+MCP; keep the 4-angle decomposition + schemas. docs/community/security/contrarian
V09	Gemini second opinion	eq	M	THIN_WRAP ⚠	—	·	P	Engine = third-party gemini-mcp; agent is pure glue ("do not editorialize"). DROP candidate (§4).
V10	Triangulation + confidence	ab	H	KEEP	upheld	·	·	No native per-dimension confidence enum + weighted scalar. trekresearch.md §6
V11	Local exploration swarm	pt	H	THIN_WRAP	—	·	P	CC ships parallel Agent spawn; keep 7 typed roles + effort defaults + scaling. agents/*
V12	Plan synthesis + schema enforcement	ab	H	KEEP	upheld	·	·	No native plan schema/--strict validator; load-bearing handover. plan-validator.mjs
V13	Adversarial plan review	pt	H	KEEP	upheld	·	P	Spawn ≠ a 10-dim critic + scope-guardian + dedup workflow. plan-critic.md
V14	Architecture-note auto-discovery	ab	M	KEEP	upheld	·	·	No native canonical-path + fallback + drift-WARN discovery. architecture-discovery.mjs
V15	Plan export	pt	L	SIMPLIFY ⚠	—	·	·	pr/issue/markdown = text reflow CC does ad-hoc; only headless(=decompose) has value. DROP text variants (§4).
V16	Session decomposition	ab	H	KEEP	upheld	·	P	--resume/TodoWrite carry no dependency parse/wave/spec/launch.sh. session-decomposer.md
V17	Disciplined step-execution loop	pt	H	KEEP	upheld	·	·	Manifest predicate (git-diff completion gate) has no CC-native analog. trekexecute.md §6
V18	Pre-exec + runtime safety guardrails	pt	H	KEEP	upheld	·	·	Native permissions.deny is a glob matcher; denylist is semantic regex. pre-bash-executor.mjs
V19	Multi-session parallel orchestration	ab	H	KEEP	upheld	·	·	git worktree+claude -p are leaves; wave/merge-gate/lock-race orchestration is Voyage. trekexecute.md §2.6
V20	Manifest audit + recovery dispatch	ab	H	KEEP	upheld	·	·	No native post-exec audit / self-report-distrust / depth-capped recovery. trekexecute.md §7.5-7.6
V21	Progress/resume contract	ab	H	KEEP	upheld	·	·	CC resume = conversation-level; no step status/attempts/SHA/drift. progress + pre-compact-flush.mjs
V22	Dry-run / validate modes	ab	M	KEEP	upheld	·	·	No native read-only preview of a multi-session execution strategy. trekexecute.md §5/§2.3
V23	Deterministic review triage gate	ab	M	KEEP	upheld	·	·	Native /code-review has no path classifier / refuse-gate / Coverage. trekreview.md §4
V24	Independent reviewer swarm	pt	H	THIN_WRAP	—	·	·	CC ships fan-out; keep rule-catalogue + schema + no-cross-feed + taxonomy. lib/review/*
V25	Review coordinator / Judge	ab	H	KEEP	upheld	·	·	No native multi-reviewer dedup + filter + verdict layer. review-coordinator.md
V26	Review→remediation handover	ab	H	KEEP	upheld	·	·	No native typed cross-stage handover (severity→goal, source_findings). review-validator.mjs
V27	Review Workflow substrate option	pt	H	SIMPLIFY	—	·	·	Opt-in port; +4.4% tokens/+54% wall-time, CC≥2.1.154 floor. Keep as opt-in, don't expand. T2
V28	Session-state + zero-friction resume	ab	H	KEEP	upheld	·	·	--resume replays a transcript, not a typed work-state. session-state-validator.mjs
V29	Structured-artifact handover contract	ab	H	KEEP	upheld	·	·	The load-bearing value. Workflow types I/O within one session, not a public cross-stage contract. HANDOVER-CONTRACTS.md
V30	Profile system + native effort axis	pt	M	KEEP	upheld	·	P	Native model key is single-spawn; profiles span the whole multi-session run. resolver.mjs
V31	Autonomy gates	ab	H	KEEP	upheld	·	P	Plan mode gates one boundary; no mid-exec per-phase/wave pause policy. autonomy-gate.mjs
V32	Observability export	pt	H	THIN_WRAP ⚠	—	·	·	CC ships Stop-hook+OTEL passthrough; exporters/guards re-host collector logic. DROP candidate (§4).
V33	Operator annotation HTML	ab	M	SIMPLIFY	revised (KEEP→SIMPLIFY)	·	·	No native line-anchored note UI, but it's a generic md tool, not a pipeline capability. scripts/annotate.mjs
V34	Artifact schema validators	ab	M	KEEP	upheld	·	·	Workflow schemas type one tool boundary; these validate persistent artifacts. lib/validators/*
V35	Internal architecture artifacts	ab	none	SIMPLIFY ⚠	—	·	P	Dormant synthesis-agent (Δ=0) + non-spawned orchestrator docs. DROP dormant half (§4).

⚠ = flagged by the over-keeping meta-critic as a downgrade candidate beyond its workflow disposition (§4).

---

4. The zero-DROP finding & over-keeping meta-review (Verification #5)

The honest gap: the per-capability adversarial pass challenged all 26 KEEP classifications (25 upheld, 1 revised: V33 KEEP→SIMPLIFY) — but because the classification produced zero DROP→NATIVE, the charter's "challenge ≥1 DROP→NATIVE" criterion had nothing to operate on. A self-audit concluding "drop nothing" is the exact pattern a skeptic should distrust. So a dedicated over-keeping meta-critic attacked the outcome and the recurring "primitive vs typed-contract" defense.

Meta-critic verdict: the zero-DROP outcome is over-keeping at the edges. The "primitive vs typed-contract" distinction is load-bearing for V08/V11/V24 (real policy a user must re-author every run) but rhetorical where the contract layer is itself thin or empty. Four downgrade candidates:

Cap	Workflow said	Meta-critic says	Native path / what's lost	Contested?
V09 Gemini bridge	THIN_WRAP	DROP→NATIVE	Call gemini-mcp tools inline; agent explicitly doesn't reason → opus-on-glue is pure waste. The classify pass also flagged opus wasted here.	Low — both passes agree
V15 plan export (pr/issue/markdown)	SIMPLIFY	DROP the 3 text variants	Ask auto-mode to reformat ad-hoc; only --export headless (=decomposition) survives, and that's V16 wearing a flag.	Low
V32 observability export	THIN_WRAP	DROP→NATIVE candidate	Point OTEL env vars at a standard OTLP collector (which owns allowlists/egress); exporters re-host the collector.	High — code-verified pass says SSRF/path/field guards are net-new; this is a genuine direct-export-vs-collector architecture choice. Operator decision.
V35 dormant synthesis-agent	SIMPLIFY	DROP the dormant agent	It's already dead (Δ=0, wired to nothing); orchestrator docs are docs, not capabilities.	Low

Caveat for the operator: the meta-critic reasoned from the disposition table, not from re-reading the code, whereas the per-capability passes cite file:line. Treat V32 as genuinely contested. V09/V15/V35 are low-contest because both layers of analysis converge.

Bottom line (meta-critic, verbatim sense): dropping V09 + V15-text + (probably) V32 and demoting V35's dead agent trims the edges decisively but does not move the headline — the typed-handover + multi-session core is untouched and remains the only thing that justifies the plugin's existence.

---

5. Target-form for Voyage

What Voyage should be, given modern CC:

1. A contract layer, not an orchestration engine. Lead with the 7 typed handovers + multi-session discipline (V28/V29 + the validators V34). Stop marketing swarm-context-relief; it's measured Δ≈0.
2. A thin accessibility skin over native CC engines for everything CC now does well: research/exploration/reviewer swarms should visibly delegate to native parallel Agent spawn + AskUserQuestion + Stop hooks, adding only the opinionated policy (angles, roles, taxonomy, schemas). Never re-host an engine.
3. Opinionated defaults that encode best practice so a non-CC-expert gets disciplined planning/execution/review without knowing the harness — this is the durable Axis-B justification, confirmed high_gap on the execution and review cores.
4. Lean at the edges: no pass-through agents paying opus to forward bytes (V09), no hand-written reformatters for what auto-mode does ad-hoc (V15-text), no re-hosted telemetry collector unless the direct-export design is a deliberate, defended choice (V32), no dormant agents padding the capability count (V35).

---

6. Prioritized change backlog (Verification #6)

All items are operator-gated (scope-guard: analysis only). Tagged [non-breaking] / [breaking] and [pinned] where they touch an operator-pinned decision.

Tier 1 — over-keeping trims (highest value, mostly non-breaking)

1. [non-breaking][pinned] V09 — drop gemini-bridge as an opus agent; call gemini-mcp tools inline (or, if kept, downgrade opus→sonnet, since it explicitly does not reason). Touches the 24-opus pin → flag.
2. [non-breaking] V15 — drop the pr/issue/markdown export variants (auto-mode does the reflow ad-hoc); keep --export headless and relabel it as the decomposition entry it actually is.
3. [non-breaking, contested] V32 — decide direct-export-vs-collector explicitly. If a standard OTLP collector is acceptable, drop the custom exporters + reimplemented guards to native OTEL env-var passthrough; if direct export is a deliberate requirement, keep and document why (this is the one genuinely contested call).
4. [non-breaking][pinned] V35 — strip the dormant synthesis-agent's model:opus/effort:high frontmatter (or collapse it to a docs note); reclassify the 3 orchestrator reference docs as docs, not capabilities. Touches the 24-opus pin → flag.

Tier 2 — THIN_WRAP hygiene (ensure delegate-the-engine, non-breaking)

5. [non-breaking] Audit V07/V08/V11/V24 implementations to confirm they ride native parallel-spawn / AskUserQuestion rather than hand-rolling, keeping only the policy layer. (Mostly already true — this is a standing guard against engine re-implementation, not a known defect.)
6. [non-breaking][pinned] Reconsider opus-for-all on mechanical/retrieval roles: V11 retrieval agents (already effort:medium), V16 session-decomposer (dependency parsing is mechanical), V08 researchers. Each touches the 24-opus pin → flag, don't override.

Tier 3 — surfaced risks (no action mandated)

7. [non-breaking][pinned] V30 — the economy profile's Jaccard floor (0.55) is grounded in parked synthetic fixtures (Step 17 calibration deferred). It is self-declared experimental; either calibrate or label clearly. → RESOLVED (S34): label, not calibrate. Empirical calibration is v4.2-budget-gated ($60–120, unauthorized); instead lib/profiles/economy.yaml now carries experimental: true (validator type-checks it) and every profile doc flags the economy row. Pinned in profile-validator.test.mjs + doc-consistency.test.mjs — the flag must track the calibration's parked-synthetic status.
8. [non-breaking] V01 — minor: delegate the literal Q&A turn-taking to AskUserQuestion rather than a hand-rolled selection loop (internal hygiene; does not change the framing-gate or reviewer contract).

Explicitly NOT recommended

• No change to Handover 1 (brief schema) — the only public contract; any change is breaking. V02/V03/V05 stay.
• No wholesale Workflow substrate swap (CC-27 DECLINED stands); keep V27 as opt-in only.
• No delegated-orchestration redesign (CC-26 lean-NO stands; Δ=0).
• No reopening of the premium-default-profile or framing-gate operator pins — flagged where touched, never overridden.

---

7. Verification checklist (charter §Verifisering)

#	Criterion	Status
1	Each capability appears exactly once with disposition + rationale + evidence-ref; inventory count == matrix rows	✅ 35 == 35 (§3)
2	Each "CC duplicate / does better" cites a specific CC feature + version	✅ cc_citation per row (e.g. AskUserQuestion 2.0+, parallel Agent 2.1.154+, nesting 2.1.172, Workflow 2.1.154+, effort: 2.1.154, PreToolUse ~2.1.97, PreCompact 2.1.105)
3	Each "lowers expertise bar" names the concrete native steps a non-expert would otherwise do	✅ captured in expertise_steps_if_native / concrete_native_steps_saved per capability
4	Post-2.1.181 delta actually run; latest version stated + each new item triaged	✅ §1.1 — CC 2.1.183, 17 items triaged, none balance-relevant
5	Adversarial pass challenged ≥1 KEEP and ≥1 DROP→NATIVE, with verdict	⚠️ 26 KEEPs challenged (1 revised); zero DROP→NATIVE were produced, so that half was addressed by the over-keeping meta-critic (§4) which named 4 DROP/downgrade candidates with verdicts. Honest deviation from the literal criterion, documented.
6	Output ends with a prioritized backlog, each item tagged breaking/non-breaking + operator-gated	✅ §6

---

8. Hard constraints honored

• Trinity asymmetry: no recommendation changes the brief schema (Handover 1). Voyage stays unaware of Tier 2/3. The one capability marked breaking (V05, memory-alignment, bound to brief_version 2.2) is recommended KEEP-as-is — no breaking change proposed.
• Operator-pinned decisions: premium default profile, 24-opus agents, framing-gate, plan-critic=10-dim, brief-reviewer=6-dim — all preserved. Where a backlog item brushes a pin (V09/V35 model frontmatter; opus-on-mechanical-roles; economy calibration), it is flagged [pinned] and operator-gated, never overridden.
• Analysis only: every item in §6 requires an explicit operator gate before implementation.

---

9. Meta-note (dogfooding the Workflow tool)

Running this analysis on the CC Workflow tool produced first-hand evidence for the audit's own V27/V29 rows: the pipeline() shape gave clean coverage (35/35, no row dropped), schema-forced output eliminated JSON-parse fragility (the CC-27 F2 win, reconfirmed), and the conditional adversarial stage worked. Costs also reconfirmed: ~2.97M subagent tokens / 96 agents / 4.6 min for a 35×3 fan-out — Workflow is a good substrate for bounded, verifiable, parallel fan-out, exactly the ~20% core CC-27 identified, and a poor fit for the ~80% judgment-heavy glue (scout + synthesis, which ran inline in main context here). This is dogfooding of the Workflow tool, not of Voyage's pipeline (the latter was declined by the operator).

---

10. Decision record — resolved forks (operator, 2026-06-20)

§4/§6 deferred three forks to the operator. All three resolved to the conservative option (preserve the capability / the security code / the deliberate pin). The model and observability work therefore collapses from code-deletion to a documentation record; the only real code changes in the backlog are V15 (export trim, S31) and V30 (economy calibration, S34). These decisions are now the implemented baseline of the multi-session backlog plan (docs/balance-backlog-plan.md), shipped across S31–S34.

Fork	Item	Resolution	What changed
D1	V09 gemini-bridge	Keep it as an agent.	No removal / inline-rewiring. The capability count stays 24; its model is governed by D3 (stays opus).
D2	V32 observability export	Keep lib/exporters/* + otel-export.mjs; document the direct-export rationale.	Doc-only — no deletion of S21 security code. The rationale (preserve the in-process path / SSRF / field-allowlist guards rather than re-host a collector) is recorded in docs/observability.md §"Why direct export rather than a native collector".
D3	24-agent model: opus pin (40d8742)	Keep the pin firm.	Document-only. opus on V09 (glue — does not reason), V35 (dormant synthesis-agent), V11 (retrieval agents, already effort:medium), V16 (session-decomposer, mechanical parsing), and V08 (researchers) was reconsidered for a sonnet downgrade and kept opus. No agent frontmatter is changed — tests/lib/agent-frontmatter.test.mjs remains the structural source-of-truth and is untouched.

Inventory framing (V35 doc half, reconciled). The "24 agents" headline is 21 spawnable + 3 orchestrator reference docs. The three orchestrators (planning-/research-/review-orchestrator) document the inline /trek* workflow and are not spawned as sub-agents. Of the 21 spawnable, one — synthesis-agent — ships dormant (Δ≈0, wired to nothing; docs/T1-synthesis-poc-results.md). Reconciled across README.md, CLAUDE.md, and this doc; pinned in tests/lib/doc-consistency.test.mjs (S33).

V30 outcome (S34, the lone Tier-3 code item). The economy-calibration fork also resolved conservatively: label, do not calibrate. The empirical run is v4.2-budget-gated ($60–120, unauthorized) and was never in scope here. Instead economy's experimental status — previously prose-only in docs/profiles.md — now lives in the profile data (lib/profiles/economy.yaml experimental: true, type-checked by the profile-validator) and on every profile-doc economy row, pinned so the flag tracks the calibration's parked-synthetic status and is dropped in the same change that lands real calibration. This closes the backlog: all 8 §6 items disposed across S31–S34 (2 code: V15+V30; the rest doc/audit).

Still explicitly NOT done (out of scope, per the plan): no gemini-bridge removal (D1), no exporter deletion (D2), no model downgrade (D3), no Handover-1 change, no Workflow substrate swap (CC-27 declined), no delegated-orchestration redesign (CC-26 lean-NO), no reopening of the premium-default / framing-gate pins.