role-definitions

---
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 luna, 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:** setup-digital-twin, dtu-profile-builder, 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`