Agent Guide

Agent Guide

This guide covers agent configuration, model routing, and best practices for working with Claude Copilot agents.

Agent Frontmatter

Every agent file (.claude/agents/*.md) includes YAML frontmatter with configuration:

---
name: agent-id
description: Brief description of agent's role
tools: tool1, tool2, tool3
model: opus | sonnet | haiku
iteration:
  enabled: true
  maxIterations: 15
  completionPromises:
    - "<promise>COMPLETE</promise>"
    - "<promise>BLOCKED</promise>"
---

Model Field

The model field specifies the default Claude model for the agent:

Model Override Priority

When executing a task, the effective model is resolved in this order:

1. Task metadata override - task.metadata.modelOverride (highest priority)
2. Agent default - agent.model field from frontmatter
3. System default - sonnet (fallback if not specified)

Example:

# Task with model override (uses haiku regardless of agent default)
tc task create --title "Quick bug fix" --prd <id> --json
# Then set metadata: modelOverride: "haiku"

# Task without override (uses agent's default model)
tc task create --title "Implement feature" --prd <id> --json
# Uses 'sonnet' from me.md frontmatter

Iteration Configuration

Agents can opt into the iteration loop for test-driven development:

iteration:
  enabled: true              # Enable iteration support
  maxIterations: 15          # Maximum iterations before circuit breaker
  completionPromises:        # Signals that trigger loop exit
    - "<promise>COMPLETE</promise>"
    - "<promise>BLOCKED</promise>"
  validationRules:           # Optional validation checks
    - tests_pass
    - compiles
    - lint_clean

Model Routing Heuristics

The framework includes an automatic model router (ecomode/model-router.ts) that recommends models based on task complexity.

Complexity Scoring

Tasks are scored 0.0-1.0 based on:

• Title keywords - "architecture", "refactor", "design" → higher score
• File count - More files → higher score
• Agent type - ta → higher base score
• Magic keywords - opus:, sonnet:, haiku: force models; eco:, fast:, max: set effort

Routing Thresholds

Magic Keywords (BREAKING CHANGE v2.8.0)

Effort-level keywords (auto-select model):

Model-selection keywords (force model):

Example:

/protocol eco: fix typo in login page
# → Auto-selects model (likely haiku), low effort

/protocol max: design multi-tenant architecture
# → Auto-selects model (likely opus), max effort

/protocol haiku: implement user profile
# → Forces haiku model, effort from complexity

# BREAKING: Old fast: keyword behavior changed
# OLD: /protocol fast: fix bug → forced haiku model
# NEW: /protocol fast: fix bug → auto-selects model, medium effort
# MIGRATION: Use haiku: to force haiku model

Agent Selection Matrix

Choose the right agent for each task type:

Best Practices

When to Use Model Overrides

Use task-level overrides when:

• Quick fix needed (use eco: for low effort or haiku: to force haiku)
• Complex reasoning needed (use max: for maximum effort or opus: to force opus)
• Orchestration workflows (use max: or force opus for coordination)

Don't override when:

• Agent's default model is already appropriate
• Task complexity matches agent's normal workload
• No specific performance or cost constraint

Cost Optimization

Model Performance Characteristics

Model Usage Tracking

Work products automatically track which model was used via metadata.modelUsed.

Query model usage:

# Get progress summary with model breakdown
tc progress --json

# Returns JSON with work product counts, types, and model usage breakdown

Use this data to:

• Identify cost optimization opportunities
• Validate model routing decisions
• Tune complexity thresholds
• Analyze agent performance by model

Adding New Agents

When creating a new agent:

1. Choose default model based on agent's typical work complexity
2. Document model choice in agent's README or comments
3. Set iteration config if agent needs TDD loop
4. Add to agent matrix in this guide

Example agent frontmatter:

---
name: my-agent
description: Custom agent for specific domain
tools: Read, Write, Grep, Bash
model: sonnet  # Standard complexity work
---

Note: Agents use the tc CLI via Bash for task operations (e.g., tc task get <id> --json, tc wp store ...). Iteration tools have been removed; agents self-manage their loops.

Troubleshooting

Model Override Not Working

Symptom: Task uses wrong model despite override

Causes:

1. Override in wrong field - use metadata.modelOverride, not metadata.model
2. Magic keyword typo - must be exact (case-insensitive)
3. Caching issue - restart MCP server

Solution:

# Correct override -- set modelOverride in task metadata
tc task update TASK-xxx --status in_progress --json
# Ensure metadata field is modelOverride, not model

High Costs with Auto-Routing

Symptom: More opus usage than expected

Causes:

1. Thresholds too low - increase medium threshold
2. Keywords triggering opus - review task titles
3. Agent defaults set to opus unnecessarily

Solution:

// Lower thresholds for more haiku/sonnet usage
const result = routeToModel({
  title: task.title,
  thresholds: {
    low: 0.4,    // Was 0.3 - more haiku
    medium: 0.8  // Was 0.7 - less opus
  }
});

Reference

• Model Router Implementation: ecomode/model-router.ts
• Complexity Scorer: ecomode/complexity-scorer.ts
• Agent Definitions: .claude/agents/*.md