@@ -19,6 +19,49 @@ When implementing phases from a plan document, the orchestrator must:
1919
2020---
2121
22+ ## CRITICAL: Mandatory Sub-Agent Requirement
23+
24+ ** YOU MUST USE THE TASK TOOL TO SPAWN A SUB-AGENT FOR EVERY PHASE IMPLEMENTATION.**
25+
26+ This is a non-negotiable requirement. The orchestrator (main agent) is ONLY responsible for:
27+ - Reading and parsing the plan document
28+ - Analyzing dependencies
29+ - Determining execution strategy
30+ - Presenting the plan to the user
31+ - Spawning Task() sub-agents for each phase
32+ - Aggregating results after sub-agents complete
33+
34+ ** The orchestrator MUST NOT:**
35+ - Implement any phase directly in the main conversation
36+ - Write code, create files, or make changes for any phase
37+ - Skip sub-agent spawning for "simple" phases
38+ - Combine multiple phases into a single implementation
39+
40+ ** Why this matters:**
41+ - Context isolation: Each sub-agent has fresh context, preventing saturation
42+ - Parallelization: Independent phases can run in parallel via multiple Task() calls
43+ - Failure isolation: A failed phase doesn't corrupt the main agent's state
44+ - Results tracking: Sub-agents write structured results to coordination directory
45+
46+ ** Correct pattern:**
47+ ```
48+ # For each phase (or group of parallel phases), spawn Task() sub-agents
49+ Task(
50+ subagent_type="general-purpose",
51+ prompt="[Phase implementation prompt with full spec and acceptance criteria]",
52+ description="Implement phase-1: [name]"
53+ )
54+ ```
55+
56+ ** WRONG pattern (never do this):**
57+ ```
58+ # Never implement phases directly
59+ Edit(file_path="src/feature.ts", ...) # WRONG - orchestrator should not edit files
60+ Write(file_path="src/new-file.ts", ...) # WRONG - orchestrator should not create files
61+ ```
62+
63+ ---
64+
2265## Step 1: Parse the Plan Document
2366
2467Extract from the plan file:
@@ -243,6 +286,8 @@ Proceed? [Y/n/modify]
243286
244287## Step 4: Execute Phases
245288
289+ ** REMINDER: You MUST use Task() sub-agents for ALL phase implementations. Never implement directly.**
290+
246291### Coordination Setup
247292
248293``` bash
@@ -251,7 +296,7 @@ mkdir -p .claude/phase-coordination/{artifacts,results}
251296
252297### Sub-Agent Prompt Template
253298
254- When spawning Task() for each phase:
299+ When spawning Task() for each phase (REQUIRED for every phase) :
255300
256301``` markdown
257302## Phase Implementation Task
@@ -310,20 +355,38 @@ Write your artifacts to: `.claude/phase-coordination/artifacts/{phase_id}/`
310355
311356### Parallel Execution Pattern
312357
313- ```
314- # Spawn all phases in current level simultaneously
315- tasks = []
316- for phase in current_level_phases:
317- task = Task(prompt=build_phase_prompt(phase))
318- tasks.append(task)
319-
320- # All tasks run in parallel
358+ ** Use multiple Task() calls in a SINGLE message to execute phases in parallel:**
359+
360+ ```
361+ # Spawn all phases in current level simultaneously using multiple Task() calls in ONE message
362+ # This is the ONLY way to achieve true parallelization
363+
364+ # In your response, include ALL of these Task() calls together:
365+ Task(
366+ subagent_type="general-purpose",
367+ prompt=build_phase_prompt(phase_1),
368+ description="Implement phase-1: [name]"
369+ )
370+ Task(
371+ subagent_type="general-purpose",
372+ prompt=build_phase_prompt(phase_2),
373+ description="Implement phase-2: [name]"
374+ )
375+ Task(
376+ subagent_type="general-purpose",
377+ prompt=build_phase_prompt(phase_3),
378+ description="Implement phase-3: [name]"
379+ )
380+
381+ # All tasks run in parallel when called in the same message
321382# Wait for all to complete
322383# Collect results from .claude/phase-coordination/results/
323384```
324385
325386### Sequential Execution Pattern
326387
388+ ** Each phase STILL requires its own Task() sub-agent, just called one at a time:**
389+
327390```
328391for phase in topologically_sorted_phases:
329392 # Build context from dependencies
@@ -332,10 +395,15 @@ for phase in topologically_sorted_phases:
332395 dep_results = read(f".claude/phase-coordination/results/{dep.id}.md")
333396 dependency_context += f"\n### Context from {dep.id}\n{dep_results}"
334397
335- # Execute with dependency context
336- Task(prompt=build_phase_prompt(phase, dependency_context))
398+ # Execute with dependency context - MUST use Task(), never implement directly
399+ Task(
400+ subagent_type="general-purpose",
401+ prompt=build_phase_prompt(phase, dependency_context),
402+ description="Implement {phase.id}: {phase.name}"
403+ )
337404
338- # Verify before proceeding
405+ # Wait for sub-agent to complete
406+ # Verify results before proceeding to next phase
339407 verify_phase_results(phase)
340408```
341409
0 commit comments