fix: prevent orchestrator context overflow from TaskOutput polling (#187)

Subagent orchestration instructions were telling Claude to poll or wait
for subagent results using TaskOutput/AgentOutputTool, which dumps the
subagent's entire working context into the orchestrator's context window.
Updated commands/tasks.md, commands/spotless.md, and templates/tasks-template.md
to instruct the orchestrator to post a status message and STOP, letting
the notification system wake it when subagents complete.

Co-authored-by: Craig Haseler <cahaseler@users.noreply.github.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: cahaseler

commands/spotless.md

@@ -209,7 +209,7 @@ You are investigating recent changes in {area_name} for dead code artifacts.
 Save your report to: .cc-track/analysis/spotless/area_reports/{area_name}_report.md
 ```
 
-**Wait** for all investigation subagents to complete.
+Post a status message: "Waiting for investigation subagents to complete." and **STOP**. Do NOT call TaskOutput to poll. The system will wake you when each subagent completes.
 
 ---
 
@@ -251,7 +251,7 @@ You are validating a finding from dead code analysis.
 Save to: .cc-track/analysis/spotless/validations/{finding_id}_validation.md
 ```
 
-**Wait** for all validation subagents to complete.
+Post a status message: "Waiting for validation subagents to complete." and **STOP**. Do NOT call TaskOutput to poll. The system will wake you when each subagent completes.
 
 ---
 

commands/tasks.md

@@ -293,9 +293,9 @@ TaskUpdate: "P3: Tests" addBlockedBy: ["P3: Stub"]
 
 **Use `TaskList`** to see what's unblocked and ready to dispatch. The native system enforces dependencies automatically - you can't accidentally start Tests before Stub completes.
 
-**Pipeline flow**: As each step completes, its dependents become unblocked. Dispatch newly-unblocked tasks immediately for maximum parallelism.
+**Pipeline flow**: Dispatch all unblocked tasks, post a status message ("Waiting for task completion."), and **STOP**. Do NOT call TaskOutput to watch or poll subagents - this dumps their entire working context into the orchestrator's context window, causing rapid context overflow. When a subagent completes, the system wakes the orchestrator automatically. At that point, update task status, check `TaskList` for newly unblocked tasks, dispatch them, and wait again.
 
-See `${CLAUDE_PLUGIN_ROOT}/templates/tasks-template.md` for additional orchestration patterns (polling fallback, dependency diagrams). These are included in the generated tasks.md.
+See `${CLAUDE_PLUGIN_ROOT}/templates/tasks-template.md` for additional orchestration patterns (dependency diagrams). These are included in the generated tasks.md.
 
 ### For Waived Phases
 

templates/tasks-template.md

@@ -176,15 +176,15 @@ When multiple phases are marked [P], use **pipeline flow** with native task coor
 
 1. **Create all native tasks upfront** with `blockedBy` dependencies (see Setup above)
 2. **Use `TaskList`** to see all unblocked tasks ready to dispatch
-3. **Dispatch** all unblocked stub writers with `run_in_background: true` in a single message
-4. **Post status** to user: "Dispatched stub writers for Phases X, Y, Z."
-5. **Orchestration loop**:
+3. **Dispatch** all unblocked stub writers in a single message
+4. **Post status** to user: "Dispatched stub writers for Phases X, Y, Z. Waiting for task completion."
+5. **STOP and wait** - Do NOT call TaskOutput or poll agents. When a subagent completes, the system will wake you automatically with its results. At that point:
+   - `TaskUpdate` the completed step's status to completed
    - `TaskList` to find newly unblocked tasks (e.g., Tests for completed Stubs)
-   - Dispatch unblocked tasks, `TaskUpdate` status to in_progress
-   - As agents complete, `TaskUpdate` status to completed
-   - Repeat until all tasks complete
+   - Dispatch any newly unblocked tasks, `TaskUpdate` their status to in_progress
+   - Post another status message and wait again if tasks remain
 
-The native `blockedBy` system automatically tracks what's ready - no manual dependency checking needed. As each step completes, its dependents become unblocked and appear in `TaskList`.
+**CRITICAL**: Never use TaskOutput to watch subagent progress. This dumps the subagent's entire working context into the orchestrator's context window, causing rapid context overflow. The notification system handles completion automatically.
 
 ### Dependency Enforcement