# How Firstmate Crew-Dispatch Profiles Route Tasks to the Right LLM Harness

> Discover how Firstmate crew-dispatch profiles map tasks to LLM harnesses using ordered rules and fallback defaults. Learn how Firstmate resolves ambiguous matches for efficient routing.

- Repository: [Kun Chen/firstmate](https://github.com/kunchenguid/firstmate)
- Tags: deep-dive
- Published: 2026-08-13

---

**Firstmate uses a JSON-based crew-dispatch configuration with ordered rules and a fallback default to map task descriptions to specific LLM harnesses, models, and effort levels, resolving ambiguous matches through quota-aware selection.**

The `kunchenguid/firstmate` repository implements an intelligent routing system that automatically selects the optimal Large Language Model (LLM) harness for each development task. This **crew-dispatch profile** system evaluates task characteristics against predefined rules to determine whether to use Claude, Codex, Grok, or other harnesses with appropriate model sizes and effort levels. Understanding how these profiles are structured and resolved is essential for customizing Firstmate's behavior to match your team's quota constraints and performance requirements.

## Understanding the Crew-Dispatch Configuration Structure

The crew-dispatch configuration resides in [`docs/examples/crew-dispatch.json`](https://github.com/kunchenguid/firstmate/blob/main/docs/examples/crew-dispatch.json) and defines three core components that govern task routing, as specified in [`docs/configuration.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/configuration.md).

### The Rules Array

The `rules` section contains an ordered list of human-readable conditions evaluated sequentially against task descriptions. Each rule specifies:
- A `when` clause describing the task context (e.g., "The task depends on fresh news, current events")
- A `use` field containing one or more candidate profiles
- A `why` field documenting the rationale for the selection

Rules are evaluated in array order, with the first matching rule determining the candidate set.

### Profile Objects

Each profile within a `use` array or the `default` array specifies three key properties:
- **`harness`**: The LLM provider identifier (e.g., `claude`, `codex`, `grok`)
- **`model`**: An optional specific model designation (e.g., `haiku`, `claude-sonnet-5`, `gpt-5.5`)
- **`effort`**: The computational intensity level (`low`, `medium`, or `high`)

### The Default Fallback

The `default` array provides fallback profiles applied when no `rules` match the task description. Like rule-based candidates, this array can contain single or multiple profile objects subject to quota-aware selection through the **quota-array-dispatch** skill.

## How Profile Resolution Works

The resolution process implemented in `.agents/skills/harness-adapters` follows a deterministic four-step pipeline from task creation to worker spawning.

### Step 1: Rule Matching Against Task Briefs

When Firstmate spawns a task, the [`bin/fm-brief.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-brief.sh) script generates a task description that the **harness-adapters** skill compares against the `when` clauses in [`crew-dispatch.json`](https://github.com/kunchenguid/firstmate/blob/main/crew-dispatch.json). The system evaluates rules in array order and selects the first rule whose `when` text appears within the task brief.

For example, a brief containing "trivial mechanical edit" matches the corresponding rule, while "big or ambiguous multi-file feature" triggers the high-effort coding profile rule.

### Step 2: Candidate Selection and Quota-Aware Dispatch

Once a rule matches, the system examines the `use` field to determine the final profile:
- **Single profile**: Used directly when the field contains one object
- **Multiple profiles**: When `use` contains an array (as in the "big/ambiguous" rule example), the **quota-array-dispatch** skill queries the `quota-axi` service to check available quotas for each listed harness-model combination. The skill selects the first profile satisfying current quota constraints and effort requirements.

### Step 3: Fallback to Default Profiles

If no rule matches the task description, the system processes the `default` array using identical quota-aware logic. The `quota-array-dispatch` skill iterates through default candidates until finding a harness with sufficient remaining quota, preventing task failures due to rate limiting.

### Step 4: Worker Spawning with Resolved Profile

The final resolved profile—containing the specific `harness`, `model`, and `effort` values—is passed to [`bin/fm-spawn.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-spawn.sh). This script launches the worker process under the selected LLM configuration, ensuring appropriate computational resources are allocated based on the task's complexity and context requirements.

## Practical Implementation Example

The following implementation illustrates how the harness-adapters skill resolves profiles at runtime:

```python
import json
import pathlib
from typing import List, Dict, Any

DISPATCH_FILE = pathlib.Path("docs/examples/crew-dispatch.json")

def resolve_profile(task_brief: str) -> Dict[str, Any]:
    """Resolve the appropriate LLM profile for a given task brief."""
    dispatch_cfg = json.loads(DISPATCH_FILE.read_text())
    
    # Step 1: Sequential rule matching

    candidates = None
    for rule in dispatch_cfg["rules"]:
        if rule["when"].lower() in task_brief.lower():
            candidates = rule["use"]
            break
    else:
        # Step 2: Fallback to defaults when no rule matches

        candidates = dispatch_cfg["default"]
    
    # Normalize single objects to lists for uniform processing

    if not isinstance(candidates, list):
        candidates = [candidates]
    
    # Step 3: Quota-aware selection from candidates

    return quota_array_dispatch(candidates)

def quota_array_dispatch(profiles: List[Dict]) -> Dict[str, Any]:
    """Select the first profile with available quota."""
    quotas = get_quota_axi()  # Interface to quota-axi service

    
    for profile in profiles:
        harness = profile["harness"]
        model = profile.get("model")
        
        if quotas.can_run(harness, model):
            return profile
    
    raise RuntimeError("No suitable crew-dispatch profile found with available quota")

```

For a task brief such as:

```markdown

# Task Brief

Rename the variable `fooBar` to `barFoo` in `utils.js`.

```

The system matches the "trivial mechanical edit" rule and resolves to:

```json
{ "harness": "claude", "model": "haiku", "effort": "low" }

```

## Summary

- **Firstmate crew-dispatch profiles** are defined in [`docs/examples/crew-dispatch.json`](https://github.com/kunchenguid/firstmate/blob/main/docs/examples/crew-dispatch.json) with three sections: ordered `rules`, `default` fallbacks, and reusable profile objects specifying harness, model, and effort.
- The **harness-adapters** skill evaluates rules sequentially against task briefs generated by [`bin/fm-brief.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-brief.sh), selecting the first matching condition.
- When multiple profiles are available, the **quota-array-dispatch** skill queries `quota-axi` to select the harness with available capacity.
- The resolved profile determines which LLM configuration [`bin/fm-spawn.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-spawn.sh) uses to launch the worker process.
- Configuration schema and integration contracts are documented in [`docs/configuration.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/configuration.md).

## Frequently Asked Questions

### What file format does Firstmate use for crew-dispatch profiles?

Firstmate uses a JSON configuration file located at [`docs/examples/crew-dispatch.json`](https://github.com/kunchenguid/firstmate/blob/main/docs/examples/crew-dispatch.json). This file defines an object with `rules` and `default` arrays containing profile specifications that map task descriptions to LLM harness configurations, as detailed in [`docs/configuration.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/configuration.md).

### How does Firstmate handle tasks that match multiple dispatch rules?

Firstmate evaluates the `rules` array in strict sequential order and applies the **first** rule whose `when` clause matches the task brief. This ordered evaluation ensures predictable routing behavior, with specific conditions placed before general ones in the configuration file.

### What happens when no crew-dispatch rule matches the task description?

When no rules match, the system falls back to the `default` array defined in the crew-dispatch configuration. The `quota-array-dispatch` skill processes these default candidates using the same quota-awareness logic applied to rule-based selections, ensuring the task still executes under an appropriate LLM harness.

### How does the quota-array-dispatch skill select between multiple LLM harnesses?

The `quota-array-dispatch` skill queries the `quota-axi` service to check available quotas for each candidate profile in the array. It selects the first profile where `quotas.can_run(harness, model)` returns true, ensuring the system respects rate limits and usage constraints while selecting the preferred LLM configuration.