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

File Purpose

.synapse/settings.json

Enable/disable delegation and set A2A flow mode

.synapse/delegate.md

Define delegation rules and agent responsibilities

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

Field Type Required Description

version

integer Yes Schema version (currently 1 )

agents

object Yes Agent definitions keyed by agent name

agents.<name>.responsibilities

string[] No List of task types this agent handles

agents.<name>.default_priority

integer No Default priority (1-5) for this agent

rules

array No Ordered list of delegation rules

rules[].name

string Yes Unique rule identifier

rules[].description

string No Human-readable description

rules[].match

object Yes Conditions for rule matching

rules[].match.keywords

string[] No Keywords to match in task text

rules[].match.file_patterns

string[] No Glob patterns for file-related tasks

rules[].target

string Yes Target agent name

rules[].priority

integer No Task priority (1-5, default: 3)

rules[].flow

string No "roundtrip" | "oneway" | "auto"

fallback

object No Behavior when no rules match

fallback.action

string No "manual" | "ask" | "default_agent"

fallback.default_agent

string No Agent to use for "default_agent" action

Rule Evaluation

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

• Keyword matching: Case-insensitive substring match against task text

• File pattern matching: Glob patterns matched against mentioned file paths

• 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:

• Verify agent is READY: synapse list (Rich TUI with auto-refresh on changes)

• Check file locks: synapse file-safety locks (for file edits)

• Verify branch: git branch --show-current (for coding tasks)

Agent Status:

Status Meaning Action

READY Idle, waiting for input Safe to delegate

WAITING Awaiting user input Use terminal jump to respond

PROCESSING Busy handling a task Wait or use --priority 5

DONE Task completed Will return to READY shortly

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

Priority Use Case

1-2 Low priority, background tasks

3 Normal tasks (default)

4 Urgent follow-ups

5 Critical/emergency tasks

Available Agents

Agent Strengths Port Range

claude Code review, analysis, planning 8100-8109

gemini Research, web search, documentation 8110-8119

codex Coding, file editing, refactoring 8120-8129

opencode AI coding, file operations 8130-8139

copilot Code suggestions, completions 8140-8149

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