name: role-definitions description: 'Detailed model routing role definitions, decision flowchart, model tier grid, and fallback chain best practices. Load when authoring agents or debugging model routing.' version: 1.0.0

Model Routing Role Definitions

Reference for choosing the right model_role when writing agent frontmatter or delegating to sub-agents. There are 13 roles organized into 5 categories.

Quick Decision Flowchart

What does your agent primarily DO?
│
├─ Writes code?
│   ├─ Frontend/UI code (components, layouts, CSS)? → ui-coding
│   ├─ Security vulnerability scanning? → security-audit
│   └─ General code (backend, IaC, tests, debugging)? → coding
│
├─ Thinks deeply / designs systems?
│   ├─ Designing architecture or solving complex problems? → reasoning
│   ├─ Reviewing/critiquing existing work for flaws? → critique
│   └─ Investigating and synthesizing from multiple sources? → research
│
├─ Creates content?
│   ├─ Aesthetic/design direction (visual, brand, style)? → creative
│   └─ Long-form writing (docs, marketing, case studies)? → writing
│
├─ Works with images?
│   ├─ Needs to understand/analyze images? → vision
│   └─ Needs to generate images? → image-gen
│
├─ Orchestrates high-stakes operations?
│   └─ Infrastructure, deployments, shadow environments? → critical-ops
│
├─ Quick utility task (parsing, classification, file ops)?
│   └─ → fast
│
└─ None of the above / genuinely varied work?
    └─ → general

Role-by-Role Reference

Foundation Roles

These two roles are required in every matrix and serve as universal fallbacks.

general

• Description: Versatile catch-all, no specialization needed
• Model tier: Mid (Sonnet, gpt-5.5, Gemini Pro)
• When to use: The agent's work is genuinely varied — knowledge experts, ecosystem consultants, integration specialists
• When NOT to use: If you can name what the agent primarily does (codes, designs, reviews), use that role instead
• Example agents: explorer, foundation-expert, amplifier-expert, core-expert
• Example chains: general (terminal — no fallback needed)

fast

• Description: Quick utility tasks — parsing, classification, file ops, bulk work
• Model tier: Cheap (Haiku, gpt-5-mini, Gemini Flash)
• When to use: Well-defined, low-ambiguity, high-volume, or latency-sensitive tasks — file operations, git commands, notification triage, data extraction
• When NOT to use: If the agent needs judgment calls, synthesis, or quality prose
• Example agents: file-ops, git-ops, shell-exec, health-checker, triage-manager
• Example chains: fast (terminal — fast agents rarely need fallback)

Coding Domain Roles

For agents whose primary output is code.

coding

• Description: Code generation, implementation, debugging
• Model tier: Mid, code-specialized (Sonnet, gpt-5.5, Gemini Pro)
• When to use: The agent writes, modifies, or debugs code as its primary activity — bug fixing, feature implementation, test writing, infrastructure-as-code
• When NOT to use: If the agent primarily reviews code (use critique), designs UI layouts (use ui-coding), or audits for vulnerabilities (use security-audit)
• Example agents: bug-hunter, modular-builder, test-coverage, python-dev, rust-dev
• Example chains: [coding, general]

ui-coding

• Description: Frontend/UI code — components, layouts, styling, spatial reasoning
• Model tier: Mid, code-specialized (same as coding today — will diverge as visually-tuned models emerge)
• When to use: The agent builds user-facing interfaces — components, layouts, responsive design, CSS, accessibility
• When NOT to use: If the agent writes backend code that serves a frontend (use coding). If it evaluates design aesthetics without writing code (use creative)
• Example agents: component-designer, layout-architect, responsive-strategist
• Example chains: [ui-coding, coding, general]

security-audit

• Description: Vulnerability assessment, attack surface analysis, code auditing
• Model tier: Mid, code-specialized + high reasoning
• When to use: The agent examines code or systems for security vulnerabilities, reviews authentication flows, assesses attack surfaces
• When NOT to use: If the agent is doing general code review (use critique). If it's implementing security features (use coding)
• Example agents: security-guardian
• Example chains: [security-audit, critique, general]

Cognitive Mode Roles

For agents whose primary value is in HOW they think.

reasoning

• Description: Deep architectural reasoning, system design, complex multi-step analysis
• Model tier: Heavy (Opus, gpt-5.5-pro, Gemini Pro) with high reasoning effort
• When to use: The agent designs systems, plans architectures, breaks complex problems into steps, or needs extended chain-of-thought
• When NOT to use: If the agent evaluates existing work (use critique), writes prose (use writing), or generates creative concepts (use creative)
• Example agents: zen-architect, brainstormer, plan-writer, recipe-author
• Example chains: [reasoning, general]

critique

• Description: Analytical evaluation — finding flaws in existing work, not generating solutions
• Model tier: Mid with extra-high reasoning effort
• When to use: The agent reviews, evaluates, or finds flaws in existing code, architecture, or plans
• When NOT to use: If the agent builds something new (use reasoning or coding). If it checks for security vulnerabilities specifically (use security-audit)
• Example agents: spec-reviewer, code-quality-reviewer, friction-detector
• Example chains: [critique, reasoning, general] or [critique, general]

creative

• Description: Design direction, aesthetic judgment, high-quality creative output
• Model tier: Heavy (Opus, gpt-5.5, Gemini Pro)
• When to use: The agent makes aesthetic judgments, establishes design direction, creates visual concepts
• When NOT to use: If the agent writes long-form content (use writing). If it writes UI code (use ui-coding)
• Example agents: art-director, style-curator, storyboard-writer, character-designer
• Example chains: [creative, general] or [creative, writing, general]

writing

• Description: Long-form content — documentation, marketing, case studies, storytelling
• Model tier: Heavy (Opus, gpt-5.5, Gemini Pro)
• When to use: The agent produces sustained written content — documentation, blog posts, case studies, release notes
• When NOT to use: If the output is code with comments (use coding). If the writing is short utility text (use fast)
• Example agents: technical-writer, marketing-writer, release-manager
• Example chains: [writing, creative, general] or [writing, general]

research

• Description: Deep investigation, information synthesis across multiple sources
• Model tier: Heavy (Opus, gpt-5.5-pro, Gemini Pro) with high reasoning effort
• When to use: The agent investigates and synthesizes from multiple sources. Extended context windows matter
• When NOT to use: If the agent designs based on what it already knows (use reasoning)
• Example agents: browser-researcher, story-researcher
• Example chains: [research, general]

Capability Roles

For agents that need specific model capabilities beyond text.

vision

• Description: Understanding visual input — screenshots, diagrams, UI mockups
• Model tier: Mid, multimodal (Gemini Flash, Sonnet, gpt-5.5)
• When to use: The agent analyzes screenshots, reads diagrams, interprets UI mockups
• When NOT to use: If the agent generates images (use image-gen). If it writes UI code without seeing existing UI (use ui-coding)
• Example agents: browser-operator, visual-documenter
• Example chains: [vision, general]

image-gen

• Description: Image generation, visual mockup creation, visual ideation
• Model tier: Specialized (gemini-3-pro-image-preview) — sparse provider coverage
• When to use: The agent creates images — generating mockups, producing comic panels, visual prototypes
• When NOT to use: If the agent analyzes existing images (use vision)
• IMPORTANT: Always include a non-image-gen fallback. Google-only in most matrices today.
• Example agents: panel-artist, cover-artist
• Example chains: [image-gen, creative, general] (NEVER image-gen alone)

Operational Role

critical-ops

• Description: High-reliability operational tasks — infrastructure, orchestration, coordination where mistakes are costly
• Model tier: Heavy (Opus, gpt-5.5-pro, Gemini Pro)
• When to use: The agent orchestrates infrastructure, manages deployments, verifies shadow environments, or performs operational tasks where failures cascade
• When NOT to use: If the agent writes IaC as its primary activity (use coding). If it does quick operational checks (use fast)
• Example agents: shadow-operator, shadow-smoke-test, container-operator
• Example chains: [critical-ops, coding, general]

Model Tier Grid

Every role maps to a unique (model-tier x reasoning-config) cell:

                default reasoning        high reasoning         extra-high reasoning
             ┌──────────────────────┬──────────────────────┬──────────────────────┐
  Heavy      │  creative            │  reasoning           │                      │
  (Opus)     │  writing             │  research            │                      │
             │  critical-ops        │                      │                      │
             ├──────────────────────┼──────────────────────┼──────────────────────┤
  Mid        │  general   coding    │  security-audit      │  critique            │
  (Sonnet)   │  ui-coding           │                      │                      │
             ├──────────────────────┤                      │                      │
  Flash      │  fast     vision     │                      │                      │
  (Haiku)    │                      │                      │                      │
             ├──────────────────────┤                      │                      │
  Specialized│  image-gen           │                      │                      │
             └──────────────────────┴──────────────────────┴──────────────────────┘

Fallback Chain Best Practices

1. Every chain should end with general (or fast for utility agents)
2. Go specific → general: [ui-coding, coding, general] not [general, ui-coding]
3. Sparse roles need fallbacks: [image-gen, creative, general] — image-gen has limited provider coverage
4. Don't over-chain: 2-3 roles is typical. More than 4 suggests confusion about the agent's purpose
5. Single role is fine when the agent's need is unambiguous: fast, general, coding