Skip to content
Weaveweave / docs
Get started ↗
Docs/Guides/Categories and Delegation

Categories and Delegation

Domain routing via categories, generated shuttle agents, and delegation topology rules

Categories define domain routing in Weave. Each category automatically generates a specialized shuttle agent that inherits from the base shuttle agent with category-specific overrides. This page covers how categories work, how shuttle agents are generated, and the delegation filtering rules that govern which agents can delegate to whom.

Category Syntax

Section titled “Category Syntax”

Categories are declared in .weave configuration files using the category block:

category backend {
  description "Backend APIs, services, persistence"
  models ["anthropic/claude-sonnet-4-5"]
  triggers ["API endpoints and request handling", "Database schemas and migrations"]
  prompt_append "Focus on API contracts, data integrity, and backwards compatibility."
  temperature 0.2


  tool_policy {
    read allow
    write allow
    delegate deny
  }
}


category frontend {
  description "Frontend UI, styling, accessibility"
  models ["openai/gpt-5"]
  triggers ["UI components and pages", "Styling and accessibility fixes"]
  prompt_append "Preserve accessibility, responsive behavior, and design-system consistency."
}

Category Fields

Section titled “Category Fields”
Field Type Description
description string Required. Describes the domain; the orchestrator routes work by it
triggers string[] Optional routing instructions for this category’s shuttle agent (the base shuttle triggers are not inherited)
models string[] Model preference list for this category’s shuttle agent
prompt_append string Text appended to the base shuttle prompt for this category
prompt_append_file string File path appended to the base shuttle prompt (mutually exclusive with prompt_append)
temperature number Temperature hint for this category’s shuttle agent
variant string Free-form string for model variant selection, passed through to the generated shuttle agent.
tool_policy block Tool policy overrides for this category’s shuttle agent

Generated Shuttle Agents

Section titled “Generated Shuttle Agents”

Each category automatically generates a shuttle agent descriptor named shuttle-{category-name}. For example:

  • category backend generates shuttle-backend
  • category frontend generates shuttle-frontend
  • category infrastructure generates shuttle-infrastructure

These generated agents inherit from the base shuttle agent and apply category-specific overrides:

  • Models: The category’s models list replaces the base shuttle’s model preferences
  • Triggers: The category’s triggers replace the base shuttle’s triggers
  • Prompt: The category’s prompt_append or prompt_append_file is appended to the base shuttle prompt
  • Temperature: The category’s temperature overrides the base shuttle’s temperature
  • Tool Policy: The category’s tool_policy is merged with the base shuttle’s policy

The generated shuttle agent is a first-class agent descriptor available for delegation routing. Adapters decide how these descriptors are materialized in a concrete harness.

Delegation Filtering Rules

Section titled “Delegation Filtering Rules”

Delegation targets are computed during prompt composition and filtered according to these rules:

1. No Self-Delegation

Section titled “1. No Self-Delegation”

An agent cannot delegate to itself. The composing agent’s own name is excluded from the delegation target list.

2. No Primary-to-Primary Delegation

Section titled “2. No Primary-to-Primary Delegation”

Agents with mode: "primary" are excluded from delegation target lists. Primary agents are user-facing orchestrators, not delegation targets.

3. No Shuttle-to-Shuttle Cross-Delegation

Section titled “3. No Shuttle-to-Shuttle Cross-Delegation”

If the target agent name starts with shuttle- and the composing agent is either shuttle or already a shuttle-* agent, that target is excluded. This prevents the shared shuttle agent and generated category shuttles from advertising one another as delegation targets.

4. Shuttle-to-Primary Allowed

Section titled “4. Shuttle-to-Primary Allowed”

Shuttle agents can delegate back to primary agents (such as loom or pattern) when appropriate. This enables shuttles to escalate complex decisions or request planning assistance.

5. Disabled Agents Excluded

Section titled “5. Disabled Agents Excluded”

Any agent listed in config.disabled.agents is removed from delegation target lists.

6. Delegation Must Be Allowed

Section titled “6. Delegation Must Be Allowed”

If the composing agent’s tool_policy.delegate is not "allow", the delegation target list is empty regardless of other rules.

Delegation Topology Example

Section titled “Delegation Topology Example”

Consider this configuration:

agent loom {
  description "Loom (Main Orchestrator)"
  prompt_file "loom.md"
  models ["anthropic/claude-sonnet-4-5"]
  mode primary
  tool_policy {
    delegate allow
  }
}


agent shuttle {
  description "Shuttle (Domain Specialist)"
  prompt_file "shuttle.md"
  models ["anthropic/claude-sonnet-4-5"]
  mode subagent
  tool_policy {
    delegate allow
  }
}


category backend {
  description "Backend APIs, services, persistence"
  triggers ["API and database work"]
}


category frontend {
  description "Frontend UI, styling, accessibility"
  triggers ["UI components and styling"]
}

This configuration generates the following delegation topology:

graph TD
  loom[loom<br/>primary]
  shuttle[shuttle<br/>subagent]
  backend[shuttle-backend<br/>subagent]
  frontend[shuttle-frontend<br/>subagent]


  loom -->|can delegate to| shuttle
  loom -->|can delegate to| backend
  loom -->|can delegate to| frontend


  shuttle -.->|cannot delegate to| backend
  shuttle -.->|cannot delegate to| frontend
  backend -.->|cannot delegate to| shuttle
  backend -.->|cannot delegate to| frontend
  frontend -.->|cannot delegate to| shuttle
  frontend -.->|cannot delegate to| backend


  shuttle -->|can delegate to| loom
  backend -->|can delegate to| loom
  frontend -->|can delegate to| loom

Key observations:

  • loom (primary) can delegate to all shuttle agents
  • shuttle, shuttle-backend, and shuttle-frontend cannot delegate to one another (shuttle-to-shuttle cross-delegation is blocked)
  • All shuttle agents can delegate back to loom (shuttle-to-primary is allowed)

Delegation Triggers

Section titled “Delegation Triggers”

Agents and categories can declare triggers: a list of plain strings that tell the orchestrator when to delegate to them.

agent loom {
  description "Loom (Main Orchestrator)"
  prompt_file "loom.md"
  models ["anthropic/claude-sonnet-4-5"]
  mode primary


  tool_policy {
    delegate allow
  }


  triggers [
    "Complex multi-step tasks that span multiple files or components"
    "System design decisions that need to be made before implementation"
  ]
}

Each trigger is used exactly as written. Weave doesn’t trim, sort, or parse it. A generated shuttle-{category} agent uses its category’s triggers instead of the base shuttle triggers.

Triggers are included in the delegation.targets template context, so agent prompts can render them with Mustache:

## Delegation


{{#delegation.targets}}
- **{{name}}**{{#description}} - {{.}}{{/description}}
  {{#triggers}}
  - {{.}}
  {{/triggers}}
{{/delegation.targets}}

Routing

Section titled “Routing”

Categories don’t route by file path. The orchestrator picks a category shuttle from the category’s description and triggers, so describe each domain clearly and add triggers for the cases you want routed there.

Category-Specific Overrides

Section titled “Category-Specific Overrides”

Categories allow you to specialize shuttle behavior for different domains:

Backend category (focus on data integrity):

category backend {
  description "Backend APIs, services, persistence"
  models ["anthropic/claude-sonnet-4-5"]
  triggers ["API endpoints and request handling"]
  prompt_append "Focus on API contracts, data integrity, and backwards compatibility."
  temperature 0.2
}

Frontend category (focus on accessibility):

category frontend {
  description "Frontend UI, styling, accessibility"
  models ["openai/gpt-5"]
  triggers ["UI components and styling"]
  prompt_append "Preserve accessibility, responsive behavior, and design-system consistency."
  temperature 0.3
}

Each generated shuttle agent receives the category-specific guidance in its composed prompt, enabling domain-appropriate behavior without duplicating the entire shuttle prompt.

Section titled “Related Documentation”