Routing Matrix

Routing Matrix — Model Dispatch Configuration

This skill defines a routing matrix: which AI models are assigned to which agent roles, how fallback chains resolve, and what policies govern model selection at dispatch time.

What this is

A structured YAML configuration that maps model pools (cloud, local, direct API, MLX) onto agent roles (orchestrator, advisor, builder, qa, linter, kaizen, logger) and declares the policies that shape dispatch behavior.

This skill ships as a template. The role structure and governance policies are pre-configured. You fill in model names, provider lanes, and ban lists.

Quick start

1. Copy templates/routing-matrix.template.yaml to your project root.
2. Rename it to routing-matrix.yaml.
3. Fill in the <...> placeholders with your model names, providers, and context windows.
4. Run the schema validator: python3 routing-matrix/scripts/validate.py routing-matrix.yaml

Role structure

The matrix pre-defines 10 roles in a fixed sequence. Each role has:

Additional optional roles: researcher (can run in parallel), council_deliberator, council_chairman.

Policies

These are pre-configured in the template and should be adjusted to your preferences:

no_repeat_model_in_sequence

Default: true. No model may appear in two consecutive roles. This forces perspective diversity — each voice in the chain uses a different model, catching blind spots that a single model's training data would miss.

team_shape

Default: 3 advisors + 2 kaizen (8 voices total). Defines how many instances of each role type run. You can shrink this to 2+1 for lighter tasks or expand for critical work.

always_be_testing

Default: true. Every new model is tested in real work — never synthetic benchmarks. A model under test is used in actual tasks alongside the team so quality is evaluated by other voices. The team's convergence verdict determines whether a model stays in the rotation or is removed.

parallel_allowed_roles

Default: [researcher]. Which roles can run in parallel. Researchers can fan out because research is isolated analysis — no sequential dependency.

single_model_mode

Default: false. When true, all roles use the same model (first available from a configured pool). This bypasses the diversity policies. Useful for rapid prototyping, low-stakes tasks, or when only one model is available. The orchestrator still dispatches sequentially — only the model assignment changes.

reject_dispatch_for_banned

Default: true. If a dispatch request names a model in the banned list, reject the dispatch instead of silently substituting.

Fallback logic

When the primary model for a role is unavailable (provider down, rate-limited, context window exhausted), the dispatcher walks the fallback_chain in order:

1. Check if provider is reachable (HTTP 200 on health endpoint).
2. If reachable and model is not in banned list → use it.
3. If unreachable or banned → advance to next entry in chain.
4. If chain exhausted → escalate: use the orchestrator's fallback chain instead.
5. If orchestrator chain also exhausted → abort with an error that lists every model tried and why each failed.

A model is "unavailable" when:

• Provider returns 5xx or timeout on three successive health checks
• Provider reports the model as not found
• Rate limit headers indicate exhaustion with no retry window
• Context window is smaller than the task requires

A model is NOT unavailable just because another instance is busy — queue, don't fall back.

Provider lanes

The matrix supports these provider types:

Template file

The fillable template is at templates/routing-matrix.template.yaml. It includes:

• All role entries with <PLACEHOLDER> values
• Commented example rows showing realistic model assignments
• The full policy block with defaults
• A banned list (initially empty)
• Schema version tracking

Scripts

• scripts/validate.py — Validates a routing-matrix.yaml against the schema. Reports missing required fields, duplicate roles, malformed fallback chains, and banned models inadvertently assigned to roles.

Works best with…

• provision-team — after defining your routing matrix, provision a team that uses it
• provision-agent — each agent references the matrix for its model assignments
• hooks-guide — add a pre-dispatch validation hook that checks the matrix before routing

© IncredAgents. This skill is part of the IncredAgents-Skills repository. Distributable, user-agnostic, platform-agnostic. Fill in your own models and providers.