name: delegation
description: This skill configures automatic task delegation between agents in Synapse A2A. Configure delegation rules via settings files (.synapse/settings.json and .synapse/delegate.md) or the interactive config TUI (synapse config). Supports orchestrator mode (Claude coordinates) and passthrough mode (direct forwarding). Includes agent status verification, priority levels, error handling, and File Safety integration.

Delegation Skill

Configure automatic task delegation to other agents based on natural language rules.

Configuration

Delegation is configured via settings files, managed using:
- synapse init - Create .synapse/ with template files
- synapse config - Interactive TUI for editing settings
- Direct file editing

Configuration Files

Settings Structure

In .synapse/settings.json:

{
  "a2a": {
    "flow": "auto"  // "roundtrip" | "oneway" | "auto"
  },
  "delegation": {
    "enabled": true  // Enable automatic task delegation
  }
}

Delegate Rules Structure

The .synapse/delegate.md file defines delegation rules in YAML frontmatter followed by optional markdown documentation.

Schema

---
# Delegate rules configuration
version: 1  # Schema version (required)

# Agent definitions with their responsibilities
agents:
  codex:
    responsibilities:
      - "Code implementation and refactoring"
      - "File editing and creation"
      - "Bug fixes"
    default_priority: 3

  gemini:
    responsibilities:
      - "Research and web search"
      - "Documentation review"
      - "API exploration"
    default_priority: 3

  claude:
    responsibilities:
      - "Code review and analysis"
      - "Architecture planning"
      - "Complex problem solving"
    default_priority: 3

# Delegation rules (evaluated in order, first match wins)
rules:
  - name: "coding-tasks"
    description: "Route coding tasks to Codex"
    match:
      keywords: ["implement", "refactor", "fix", "edit", "create file"]
      file_patterns: ["*.py", "*.ts", "*.js"]
    target: codex
    priority: 3
    flow: roundtrip  # Wait for response

  - name: "research-tasks"
    description: "Route research to Gemini"
    match:
      keywords: ["research", "search", "find", "look up", "documentation"]
    target: gemini
    priority: 2
    flow: oneway  # Fire and forget

  - name: "review-tasks"
    description: "Route reviews to Claude"
    match:
      keywords: ["review", "analyze", "evaluate", "assess"]
    target: claude
    priority: 3
    flow: roundtrip

# Fallback behavior when no rules match
fallback:
  action: manual  # "manual" | "ask" | "default_agent"
  default_agent: claude  # Used when action is "default_agent"
---

# Delegation Rules Documentation

Additional markdown content here for human-readable documentation...

Field Reference

Rule Evaluation

Rules are evaluated in order from top to bottom. The first matching rule is applied:

1. Keyword matching: Case-insensitive substring match against task text
2. File pattern matching: Glob patterns matched against mentioned file paths
3. Combined conditions: All specified conditions must match (AND logic)

If no rules match, the fallback behavior is applied.

Delegating Tasks

Use the @agent pattern to send tasks to other agents:

@codex Please refactor this function
@gemini Research the latest API changes
@claude Review this design document

For programmatic delegation (from AI agents):

# Fire and forget (default)
synapse send codex "Refactor this function" --from claude

# Wait for response (roundtrip)
synapse send gemini "Analyze this code" --response --from claude

# Urgent follow-up
synapse send gemini "Status update?" --priority 4 --from claude

# Reply to a --response request
synapse reply "Here is the analysis..." --from gemini

Important: When responding to a --response request, the receiver MUST use synapse reply to send the response.

Modes

Orchestrator Mode (Recommended)

Claude analyzes tasks, delegates to appropriate agent, waits for response, integrates results.

User → Claude (analyze) → @codex/@gemini → Claude (integrate) → User

Passthrough Mode

Direct forwarding without processing.

User → Claude (route) → @codex/@gemini → User

Manual Mode (Default)

No automatic delegation. User explicitly uses @agent patterns.

Pre-Delegation Checklist

Before delegating any task:

1. Verify agent is READY: synapse list (Rich TUI with auto-refresh on changes)
2. Check file locks: synapse file-safety locks (for file edits)
3. Verify branch: git branch --show-current (for coding tasks)

Agent Status:

Note: synapse list provides real-time agent monitoring with auto-refresh. Press 1-9/↑↓ to select agent, Enter/j to jump, k to kill, / to filter, ESC to clear, q to quit.

Priority Levels

Available Agents

References

For detailed documentation, read:

• references/modes.md - Delegation modes and workflows
• references/file-safety.md - File Safety integration
• references/examples.md - Example sessions and configurations