docs(voyage): correct now-false harness-constraint claims (W0/CC-01)
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:
parent
c452f75628
commit
3f77b68727
6 changed files with 84 additions and 56 deletions
|
|
@ -2,13 +2,15 @@
|
|||
name: planning-orchestrator
|
||||
description: |
|
||||
Inline reference (v2.4.0) — documents the planning workflow that
|
||||
/trekplan executes in main context. This file is NOT spawned as a
|
||||
sub-agent anymore. 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 exploration swarm (architecture-mapper, task-finder,
|
||||
plan-critic, etc.) and would degrade to single-context reasoning. The
|
||||
/trekplan command now orchestrates the phases below directly in the
|
||||
main session.
|
||||
/trekplan executes in main context. Historically not spawned as a
|
||||
sub-agent: before Claude Code 2.1.172 the harness did not expose the
|
||||
Agent tool to sub-agents, so a background orchestrator could not spawn
|
||||
the exploration swarm (architecture-mapper, task-finder, plan-critic,
|
||||
etc.). As of CC 2.1.172 sub-agents can spawn sub-agents (up to 5 levels
|
||||
deep), so a delegated-orchestration redesign is under evaluation (see
|
||||
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
|
||||
color: cyan
|
||||
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
|
||||
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
|
||||
no longer spawned as a background sub-agent — that mode silently lost the
|
||||
Agent tool and degraded the exploration swarm to single-context reasoning.
|
||||
and executes the phases below **inline in the main command context**. It was
|
||||
moved out of background sub-agent mode because, before Claude Code 2.1.172,
|
||||
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 main Opus session launches exploration and review agents via the Agent
|
||||
|
|
|
|||
|
|
@ -2,12 +2,14 @@
|
|||
name: research-orchestrator
|
||||
description: |
|
||||
Inline reference (v2.4.0) — documents the research workflow that
|
||||
/trekresearch executes in main context. This file is NOT spawned as
|
||||
a sub-agent anymore. 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 research swarm and would degrade to single-context
|
||||
reasoning. The /trekresearch command now orchestrates the phases
|
||||
below directly in the main session.
|
||||
/trekresearch executes in main context. Historically not spawned as
|
||||
a sub-agent: before Claude Code 2.1.172 the harness did not expose the
|
||||
Agent tool to sub-agents, so a background orchestrator could not spawn
|
||||
the research swarm. As of CC 2.1.172 sub-agents can spawn sub-agents
|
||||
(up to 5 levels deep), so a delegated-orchestration redesign is under
|
||||
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
|
||||
color: cyan
|
||||
tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash"]
|
||||
|
|
|
|||
|
|
@ -2,14 +2,16 @@
|
|||
name: review-orchestrator
|
||||
description: |
|
||||
Inline reference (v3.2.0) — documents the review workflow that
|
||||
/trekreview executes in main context. This file is NOT spawned
|
||||
as a sub-agent. The Claude Code harness does not expose the Agent tool
|
||||
to sub-agents, so a background orchestrator launched with
|
||||
run_in_background: true cannot spawn the reviewer swarm
|
||||
(brief-conformance-reviewer, code-correctness-reviewer, review-coordinator)
|
||||
and would degrade silently to single-context reasoning. The
|
||||
/trekreview command now orchestrates the phases below directly in
|
||||
the main session.
|
||||
/trekreview executes in main context. Historically not spawned
|
||||
as a sub-agent: before Claude Code 2.1.172 the harness did not expose
|
||||
the Agent tool to sub-agents, so a background orchestrator could not
|
||||
spawn the reviewer swarm (brief-conformance-reviewer,
|
||||
code-correctness-reviewer, review-coordinator). As of CC 2.1.172
|
||||
sub-agents can spawn sub-agents (up to 5 levels deep), so a
|
||||
delegated-orchestration redesign is under evaluation (see
|
||||
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
|
||||
color: red
|
||||
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
|
||||
pipeline as of v3.2.0. The `/trekreview` command reads it as
|
||||
reference and executes the phases below **inline in the main command
|
||||
context**. It is not spawned as a background sub-agent — that mode would
|
||||
silently lose the Agent tool and degrade the reviewer swarm to
|
||||
single-context reasoning.
|
||||
context**. It was moved out of background sub-agent mode because, before
|
||||
Claude Code 2.1.172, that mode would silently lose the Agent tool and degrade
|
||||
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 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
|
||||
|
||||
- **Never spawn in background.** This orchestrator file is reference, not
|
||||
a runnable sub-agent. Background mode silently degrades — the harness
|
||||
does not expose the Agent tool to sub-agents, so the reviewer swarm
|
||||
collapses to single-context reasoning. Always run review agents from
|
||||
the main /trekreview command context.
|
||||
- **Currently runs inline, not in background.** This orchestrator file is
|
||||
reference, not a runnable sub-agent. Original reason: before Claude Code
|
||||
2.1.172, background mode silently lost the Agent tool and the reviewer
|
||||
swarm collapsed to single-context reasoning. As of CC 2.1.172 sub-agents
|
||||
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
|
||||
coordinator is the only place where reviewer outputs are combined.
|
||||
- **Coordinator scope is bounded.** Dedup, severity ranking, reasonableness
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue