open/voyage
1
0
Fork 0
Code Issues Pull requests Releases Activity

docs(voyage): correct now-false harness-constraint claims (W0/CC-01)

Browse source 
8 sites across 3 orchestrator agents + trekbrief/trekplan/trekresearch asserted 'the harness does not expose the Agent tool to sub-agents' as present fact -- the rationale for the v2.4.0 inline migration. CC 2.1.172 (verified) lets sub-agents spawn sub-agents up to 5 levels deep, so the claim is false. Replaced each with verified history (pre-2.1.172) + current fact + forward pointer to the decision matrix (W1/CC-26). Decision-neutral: states fact without pre-empting the orchestration redesign. CHANGELOG history left untouched. Tests 578/0/2; claude plugin validate passes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqBYc8Ltrk7LipyJmGxXiB
This commit is contained in:
Kjell Tore Guttormsen 2026-06-18 11:43:17 +02:00
commit 3f77b68727
6 changed files with 84 additions and 56 deletions
Download patch file Download diff file Expand all files Collapse all files

19
commands/trekbrief.md
View file

@ -736,14 +736,17 @@ invocation to finish writing the research brief at
`{PROJECT_DIR}/research/{NN}-{topic-slug}.md` before moving to the next
topic.
> **Why sequential inline instead of parallel background?** Background
> orchestrator-agents cannot spawn the research swarm — the Claude Code
> harness does not expose the Agent tool to sub-agents, so a background
> run silently degrades to single-context reasoning without WebSearch /
> Tavily / WebFetch / Gemini (see v2.4.0 release notes). Running each
> research pass inline in main context keeps the swarm intact. For true
> parallel execution, use `claude -p` invocations in separate terminal
> windows.
> **Why sequential inline instead of parallel background?** Historically,
> background orchestrator-agents could not spawn the research swarm —
> before Claude Code 2.1.172 the harness did not expose the Agent tool to
> sub-agents, so a background run silently degraded to single-context
> reasoning without WebSearch / Tavily / WebFetch / Gemini (see v2.4.0
> release notes). As of CC 2.1.172 sub-agents can spawn sub-agents (up to 5
> levels deep), so a delegated redesign is under evaluation (see
> `docs/cc-upgrade-2.1.181-decision-matrix.md`, W1/CC-26). Until then,
> running each research pass inline in main context keeps the swarm intact.
> For true parallel execution, use `claude -p` invocations in separate
> terminal windows.
### Step 6c — Verify all briefs landed

19
commands/trekplan.md
View file

@ -396,14 +396,17 @@ Planning pipeline running in foreground.
Then continue to the next phase inline.
> **Why foreground?** As of v2.4.0 the planning-orchestrator is no longer
> spawned as a background agent. The Claude Code harness does not expose the
> Agent tool to sub-agents, so an orchestrator launched with
> `run_in_background: true` cannot spawn the documented exploration swarm
> (`architecture-mapper`, `task-finder`, `plan-critic`, etc.) and silently
> degrades to single-context reasoning. Running the phases inline in main
> context keeps the swarm intact. Use `claude -p` in a separate terminal
> window for long-running headless work.
> **Why foreground (for now)?** The planning-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 exploration
> swarm (`architecture-mapper`, `task-finder`, `plan-critic`, etc.) and
> silently degraded to single-context reasoning. 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.
---

20
commands/trekresearch.md
View file

@ -206,14 +206,18 @@ Research pipeline running in foreground.
Then continue to the next phase inline.
> **Why foreground?** As of v2.4.0 the research-orchestrator is no longer
> spawned as a background agent. The Claude Code harness does not expose the
> Agent tool to sub-agents, so an orchestrator launched with
> `run_in_background: true` cannot spawn the documented research swarm
> (`docs-researcher`, `community-researcher`, etc.) and silently degrades to
> single-context reasoning without WebSearch / Tavily / WebFetch / Gemini.
> Running the phases inline in main context keeps the swarm intact. Use
> `claude -p` in a separate terminal window for long-running headless work.
> **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.
---