Thin Orchestrator Pattern

Problem

Orchestrator skills that do heavy lifting inline — reading large files, running verification, accumulating content — exhaust their context window before completing the workflow. This was documented in GSD Issue #501, where inline verification consumed the orchestrator's context mid-run.

Checklist

When building or modifying an orchestrator skill, follow these 5 rules:

1. Pass File Paths, Not Content

Subagents receive file paths and read files themselves. The orchestrator never loads file content into its own context.

# BAD: orchestrator reads file, passes content to subagent
content = read("specs/3-data-import/spec.md")
dispatch_agent(prompt: "Review this: #{content}")

# GOOD: orchestrator passes path, subagent reads it
dispatch_agent(prompt: "Review the spec at specs/3-data-import/spec.md")

2. Every Heavy Operation Runs in a Subagent

Research, analysis, verification, code generation — anything that produces substantial output runs in a dedicated subagent with its own context window.

3. Orchestrator Context Stays Under 50%

The orchestrator's role is coordination: dispatch subagents, collect results, make routing decisions. It should never accumulate enough content to exceed 50% of its context window.

4. Verification Runs in Separate Contexts

Never verify inline. Dispatch a verification subagent that reads the artifacts and reports pass/fail. The orchestrator only receives the verdict, not the full analysis.

5. Orchestrator Avoids O(n) Content Accumulation

If the orchestrator processes N items, it should not grow linearly with N. Results stay in files; the orchestrator tracks completion status, not content.

Anti-Pattern: GSD Issue #501

The GSD framework's orchestrator ran verification inline after each task execution. With 8 tasks, the orchestrator accumulated verification output for all previous tasks, exhausting context by task 5. The fix: dispatch verification to a separate agent that writes results to a file.

Positive Examples from Toolkit

Skill	Pattern
/vt-c-2-plan	Dispatches 4 research agents (best-practices, framework-docs, architecture, spec-flow), collects file paths to their outputs
/vt-c-4-review	Dispatches 6 review agents in parallel, each writes findings to files, orchestrator collects verdicts
/vt-c-3-build	Dispatches implementation to focused subagents per task, tracks completion via state.yaml

When to Apply

• Building a new orchestrator skill
• Adding steps to an existing orchestrator
• Debugging context exhaustion in long-running workflows
• Reviewing pull requests that modify orchestrator skills