agent-orchestration

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"