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

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

27
agents/planning-orchestrator.md
View file

@ -2,13 +2,15 @@
name: planning-orchestrator name: planning-orchestrator
description: | description: |
Inline reference (v2.4.0) — documents the planning workflow that Inline reference (v2.4.0) — documents the planning workflow that
/trekplan executes in main context. This file is NOT spawned as a /trekplan executes in main context. Historically not spawned as a
sub-agent anymore. The Claude Code harness does not expose the Agent tool sub-agent: before Claude Code 2.1.172 the harness did not expose the
to sub-agents, so an orchestrator launched with run_in_background: true Agent tool to sub-agents, so a background orchestrator could not spawn
cannot spawn the exploration swarm (architecture-mapper, task-finder, the exploration swarm (architecture-mapper, task-finder, plan-critic,
plan-critic, etc.) and would degrade to single-context reasoning. The etc.). As of CC 2.1.172 sub-agents can spawn sub-agents (up to 5 levels
/trekplan command now orchestrates the phases below directly in the deep), so a delegated-orchestration redesign is under evaluation (see
main session. docs/cc-upgrade-2.1.181-decision-matrix.md, W1/CC-26). Until then the
/trekplan command orchestrates the phases below directly in the main
session.
model: opus model: opus
color: cyan color: cyan
tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate", "TaskUpdate"] tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate", "TaskUpdate"]
@ -29,9 +31,14 @@ tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate",
This document is the canonical workflow description for the trekplan This document is the canonical workflow description for the trekplan
pipeline as of v2.4.0. The `/trekplan` command reads it as reference pipeline as of v2.4.0. The `/trekplan` command reads it as reference
and executes the phases below **inline in the main command context**. It is and executes the phases below **inline in the main command context**. It was
no longer spawned as a background sub-agent — that mode silently lost the moved out of background sub-agent mode because, before Claude Code 2.1.172,
Agent tool and degraded the exploration swarm to single-context reasoning. that mode silently lost the Agent tool and degraded the exploration swarm to
single-context reasoning. As of CC 2.1.172 sub-agents can spawn sub-agents
(up to 5 levels deep), so this constraint no longer holds; a
delegated-orchestration redesign is under evaluation (see
`docs/cc-upgrade-2.1.181-decision-matrix.md`, W1/CC-26). Until then,
orchestration stays inline.
The role of the "orchestrator" now belongs to the command markdown itself: The role of the "orchestrator" now belongs to the command markdown itself:
the main Opus session launches exploration and review agents via the Agent the main Opus session launches exploration and review agents via the Agent

14
agents/research-orchestrator.md
View file

@ -2,12 +2,14 @@
name: research-orchestrator name: research-orchestrator
description: | description: |
Inline reference (v2.4.0) — documents the research workflow that Inline reference (v2.4.0) — documents the research workflow that
/trekresearch executes in main context. This file is NOT spawned as /trekresearch executes in main context. Historically not spawned as
a sub-agent anymore. The Claude Code harness does not expose the Agent tool a sub-agent: before Claude Code 2.1.172 the harness did not expose the
to sub-agents, so an orchestrator launched with run_in_background: true Agent tool to sub-agents, so a background orchestrator could not spawn
cannot spawn the research swarm and would degrade to single-context the research swarm. As of CC 2.1.172 sub-agents can spawn sub-agents
reasoning. The /trekresearch command now orchestrates the phases (up to 5 levels deep), so a delegated-orchestration redesign is under
below directly in the main session. evaluation (see docs/cc-upgrade-2.1.181-decision-matrix.md, W1/CC-26).
Until then the /trekresearch command orchestrates the phases below
directly in the main session.
model: opus model: opus
color: cyan color: cyan
tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash"] tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash"]

41
agents/review-orchestrator.md
View file

@ -2,14 +2,16 @@
name: review-orchestrator name: review-orchestrator
description: | description: |
Inline reference (v3.2.0) — documents the review workflow that Inline reference (v3.2.0) — documents the review workflow that
/trekreview executes in main context. This file is NOT spawned /trekreview executes in main context. Historically not spawned
as a sub-agent. The Claude Code harness does not expose the Agent tool as a sub-agent: before Claude Code 2.1.172 the harness did not expose
to sub-agents, so a background orchestrator launched with the Agent tool to sub-agents, so a background orchestrator could not
run_in_background: true cannot spawn the reviewer swarm spawn the reviewer swarm (brief-conformance-reviewer,
(brief-conformance-reviewer, code-correctness-reviewer, review-coordinator) code-correctness-reviewer, review-coordinator). As of CC 2.1.172
and would degrade silently to single-context reasoning. The sub-agents can spawn sub-agents (up to 5 levels deep), so a
/trekreview command now orchestrates the phases below directly in delegated-orchestration redesign is under evaluation (see
the main session. docs/cc-upgrade-2.1.181-decision-matrix.md, W1/CC-26). Until then the
/trekreview command orchestrates the phases below directly in the main
session.
model: opus model: opus
color: red color: red
tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate", "TaskUpdate"] tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate", "TaskUpdate"]
@ -31,9 +33,13 @@ tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate",
This document is the canonical workflow description for the trekreview This document is the canonical workflow description for the trekreview
pipeline as of v3.2.0. The `/trekreview` command reads it as pipeline as of v3.2.0. The `/trekreview` command reads it as
reference and executes the phases below **inline in the main command reference and executes the phases below **inline in the main command
context**. It is not spawned as a background sub-agent — that mode would context**. It was moved out of background sub-agent mode because, before
silently lose the Agent tool and degrade the reviewer swarm to Claude Code 2.1.172, that mode would silently lose the Agent tool and degrade
single-context reasoning. the reviewer swarm to single-context reasoning. As of CC 2.1.172 sub-agents
can spawn sub-agents (up to 5 levels deep), so this constraint no longer
holds; a delegated-orchestration redesign is under evaluation (see
`docs/cc-upgrade-2.1.181-decision-matrix.md`, W1/CC-26). Until then,
orchestration stays inline.
The role of the "orchestrator" now belongs to the command markdown itself: The role of the "orchestrator" now belongs to the command markdown itself:
the main Opus session launches reviewer agents via the Agent tool, runs the the main Opus session launches reviewer agents via the Agent tool, runs the
@ -217,11 +223,14 @@ Append a stats line to `${CLAUDE_PLUGIN_DATA}/trekreview-stats.jsonl`:
## Hard rules ## Hard rules
- **Never spawn in background.** This orchestrator file is reference, not - **Currently runs inline, not in background.** This orchestrator file is
a runnable sub-agent. Background mode silently degrades — the harness reference, not a runnable sub-agent. Original reason: before Claude Code
does not expose the Agent tool to sub-agents, so the reviewer swarm 2.1.172, background mode silently lost the Agent tool and the reviewer
collapses to single-context reasoning. Always run review agents from swarm collapsed to single-context reasoning. As of CC 2.1.172 sub-agents
the main /trekreview command context. can spawn sub-agents (up to 5 levels deep), so that hard block is gone — a
delegated redesign is under evaluation (see
`docs/cc-upgrade-2.1.181-decision-matrix.md`, W1/CC-26). Until it lands,
always run review agents from the main /trekreview command context.
- **Reviewers run independently.** No cross-feeding of findings. The - **Reviewers run independently.** No cross-feeding of findings. The
coordinator is the only place where reviewer outputs are combined. coordinator is the only place where reviewer outputs are combined.
- **Coordinator scope is bounded.** Dedup, severity ranking, reasonableness - **Coordinator scope is bounded.** Dedup, severity ranking, reasonableness

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 `{PROJECT_DIR}/research/{NN}-{topic-slug}.md` before moving to the next
topic. topic.
> **Why sequential inline instead of parallel background?** Background > **Why sequential inline instead of parallel background?** Historically,
> orchestrator-agents cannot spawn the research swarm — the Claude Code > background orchestrator-agents could not spawn the research swarm —
> harness does not expose the Agent tool to sub-agents, so a background > before Claude Code 2.1.172 the harness did not expose the Agent tool to
> run silently degrades to single-context reasoning without WebSearch / > sub-agents, so a background run silently degraded to single-context
> Tavily / WebFetch / Gemini (see v2.4.0 release notes). Running each > reasoning without WebSearch / Tavily / WebFetch / Gemini (see v2.4.0
> research pass inline in main context keeps the swarm intact. For true > release notes). As of CC 2.1.172 sub-agents can spawn sub-agents (up to 5
> parallel execution, use `claude -p` invocations in separate terminal > levels deep), so a delegated redesign is under evaluation (see
> windows. > `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 ### 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. Then continue to the next phase inline.
> **Why foreground?** As of v2.4.0 the planning-orchestrator is no longer > **Why foreground (for now)?** The planning-orchestrator was moved out of
> spawned as a background agent. The Claude Code harness does not expose the > background mode in v2.4.0 because, before Claude Code 2.1.172, the harness
> Agent tool to sub-agents, so an orchestrator launched with > did not expose the Agent tool to sub-agents, so an orchestrator launched
> `run_in_background: true` cannot spawn the documented exploration swarm > with `run_in_background: true` could not spawn the documented exploration
> (`architecture-mapper`, `task-finder`, `plan-critic`, etc.) and silently > swarm (`architecture-mapper`, `task-finder`, `plan-critic`, etc.) and
> degrades to single-context reasoning. Running the phases inline in main > silently degraded to single-context reasoning. As of CC 2.1.172 sub-agents
> context keeps the swarm intact. Use `claude -p` in a separate terminal > can spawn sub-agents (up to 5 levels deep), so that block no longer holds —
> window for long-running headless work. > 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. Then continue to the next phase inline.
> **Why foreground?** As of v2.4.0 the research-orchestrator is no longer > **Why foreground (for now)?** The research-orchestrator was moved out of
> spawned as a background agent. The Claude Code harness does not expose the > background mode in v2.4.0 because, before Claude Code 2.1.172, the harness
> Agent tool to sub-agents, so an orchestrator launched with > did not expose the Agent tool to sub-agents, so an orchestrator launched
> `run_in_background: true` cannot spawn the documented research swarm > with `run_in_background: true` could not spawn the documented research
> (`docs-researcher`, `community-researcher`, etc.) and silently degrades to > swarm (`docs-researcher`, `community-researcher`, etc.) and silently
> single-context reasoning without WebSearch / Tavily / WebFetch / Gemini. > degraded to single-context reasoning without WebSearch / Tavily / WebFetch
> Running the phases inline in main context keeps the swarm intact. Use > / Gemini. As of CC 2.1.172 sub-agents can spawn sub-agents (up to 5 levels
> `claude -p` in a separate terminal window for long-running headless work. > 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.
--- ---