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

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 and defines three core components that govern task routing, as specified in 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 script generates a task description that the harness-adapters skill compares against the when clauses in 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. 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:

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:

# Task Brief

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

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

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

Summary

• Firstmate crew-dispatch profiles are defined in 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, 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 uses to launch the worker process.
• Configuration schema and integration contracts are documented in 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. 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}