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"