Agent Orchestration Rules
When the user asks to implement something, use implementation agents to preserve main context.
The Pattern
Wrong - burns context:
Main: Read files → Understand → Make edits → Report (2000+ tokens consumed in main context)
Right - preserves context:
Main: Spawn agent("implement X per plan") ↓ Agent: Reads files → Understands → Edits → Tests ↓ Main: Gets summary (~200 tokens)
When to Use Agents Task Type Use Agent? Reason Multi-file implementation Yes Agent handles complexity internally Following a plan phase Yes Agent reads plan, implements New feature with tests Yes Agent can run tests Single-line fix No Faster to do directly Quick config change No Overhead not worth it Key Insight
Agents read their own context. Don't read files in main chat just to understand what to pass to an agent - give them the task and they figure it out.
Example Prompt Implement Phase 4: Outcome Marking Hook from the Artifact Index plan.
Plan location: thoughts/shared/plans/2025-12-24-artifact-index.md (search for "Phase 4")
What to create: 1. TypeScript hook 2. Shell wrapper 3. Python script 4. Register in settings.json
When done, provide a summary of files created and any issues.
Trigger Words
When user says these, consider using an agent:
"implement", "build", "create feature" "follow the plan", "do phase X" "use implementation agents"