Categories and Delegation

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.

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

category backend {
  description "Backend APIs, services, persistence"
  models ["anthropic/claude-sonnet-4-5"]
  patterns ["src/api/**", "src/server/**", "src/db/**", "**/*.go"]
  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"]
  patterns ["src/components/**", "src/pages/**", "**/*.tsx", "**/*.css"]
  prompt_append "Preserve accessibility, responsive behavior, and design-system consistency."
}

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
• 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 targets are computed during prompt composition and filtered according to these rules:

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

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

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.

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.

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

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

Consider this configuration:

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

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

category backend {
  description "Backend APIs, services, persistence"
  patterns ["src/api/**", "**/*.go"]
}

category frontend {
  description "Frontend UI, styling, accessibility"
  patterns ["src/components/**", "**/*.tsx"]
}

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)

Agents can declare triggers to provide routing guidance for delegation decisions:

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

  tool_policy {
    delegate allow
  }

  triggers [
    {
      domain "Orchestration"
      trigger "Complex multi-step tasks"
      routing_hint "Use for work spanning multiple files or components"
    }
    {
      domain "Architecture"
      trigger "System design and planning"
      routing_hint "Use when design decisions need to be made before implementation"
    }
  ]
}

Each trigger entry includes:

• domain: A high-level category for the trigger (e.g. “Orchestration”, “Architecture”)
• trigger: A concise description of when to delegate to this agent
• routing_hint: Optional prescriptive “Use when…” guidance for delegation routing

These triggers are included in the delegation.targets template context and can be rendered in agent prompts using Mustache templates:

## Delegation

{{#delegation.targets}}
- **{{name}}**{{#description}} - {{description}}{{/description}}
  {{#triggers}}
  - {{domain}}: {{trigger}}{{#routing_hint}} ({{routing_hint}}){{/routing_hint}}
  {{/triggers}}
{{/delegation.targets}}

Category patterns use glob syntax to match file paths:

• **/*.go matches all Go files in any directory
• src/api/** matches all files under src/api/
• src/components/**/*.tsx matches all TypeScript React files under src/components/

When a task involves files matching a category’s patterns, the orchestrator can route that work to the corresponding shuttle agent.

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"]
  patterns ["src/api/**", "src/server/**", "**/*.go"]
  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"]
  patterns ["src/components/**", "**/*.tsx", "**/*.css"]
  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.

• DSL Configuration - Categories - Full category DSL specification
• Prompt Composition - How category prompts are composed
• Tool Policy - How tool policies are resolved
• Adapters - How adapters materialize shuttle agents