delegation

Original source / Raw SKILL.md

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

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

```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

```yaml
---
# 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:

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:

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

For programmatic delegation (from AI agents):

```bash
# 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 send claude "Here is the analysis..." --reply-to <task_id> --from gemini
```

**Important:** When responding to a `--response` request, the receiver MUST use `--reply-to <task_id>` to link the response.

## Modes

### Orchestrator Mode (Recommended)

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

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

### Passthrough Mode

Direct forwarding without processing.

```text
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` or `synapse list --watch` (Rich TUI with real-time status)
2. **Check file locks**: `synapse file-safety locks` (for file edits)
3. **Verify branch**: `git branch --show-current` (for coding tasks)

**Note:** Use `synapse list --watch` for real-time agent monitoring. The TRANSPORT column shows active communication (UDS→/→UDS or TCP→/→TCP). Press 1-9 to view agent details, ESC to close, Ctrl+C to exit.

## 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 |
|-------|-----------|------------|
| codex | Coding, file editing, refactoring | 8120-8129 |
| gemini | Research, web search, documentation | 8110-8119 |
| claude | Code review, analysis, planning | 8100-8109 |

## 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


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/modes.md

```markdown
# Delegation Modes

## Configuration

Delegation is configured via files, not CLI commands:

| File | Purpose |
|------|---------|
| `.synapse/settings.json` | Enable delegation with `"delegation": {"enabled": true}` |
| `.synapse/delegate.md` | Define delegation rules in natural language |

### Setup Steps

1. **Initialize settings** (if not done):
   ```bash
   synapse init
   ```

2. **Enable delegation** in `.synapse/settings.json`:
   ```json
   {
     "delegation": {
       "enabled": true
     }
   }
   ```
   Or use interactive TUI: `synapse config`

3. **Define rules** in `.synapse/delegate.md`:
   ```markdown
   # Delegation Rules

   Coding tasks (file editing, creation, refactoring) go to Codex.
   Research and web searches go to Gemini.
   Code reviews stay with Claude.
   ```

4. **Start agents** with the settings applied:
   ```bash
   synapse claude  # Will read .synapse/delegate.md if enabled
   ```

## Orchestrator Mode Workflow

```
1. Analyze user request
2. Run pre-delegation checklist
3. If target agent not READY:
   a. Inform user: "Target agent (<agent>) is processing. Wait?"
   b. Wait or queue based on user preference
4. If matches delegation rule and agent is READY:
   a. Acquire file locks if needed (File Safety)
   b. Send to target agent with appropriate priority
   c. Wait for response (monitor with synapse list --watch)
   d. Review and integrate response
   e. Release file locks
   f. Report final result to user
5. If no match: Process directly
```

## Passthrough Mode Workflow

```
1. Analyze user request
2. Check agent availability (skip if not READY)
3. If matches delegation rule:
   a. Forward to target agent with original request
   b. Relay response directly to user
4. If no match: Process directly
```

## Applying Delegation Rules

When delegation is active:

1. **Analyze the request** against configured rules
2. **Run pre-delegation checklist** (agent status, file locks)
3. **Determine target agent** (codex, gemini, or self)
4. **Select priority level** based on urgency
5. **Execute delegation** with appropriate method

## A2A Communication Methods

### Method 1: synapse send (Recommended)

**Use `synapse send` command for inter-agent communication.** This works reliably from any environment including sandboxed agents.

```bash
synapse send <agent> "<message>" [--from <sender>] [--priority <1-5>] [--response | --no-response] [--reply-to <task_id>]
```

Examples:
```bash
# Normal task (priority 3, fire and forget)
synapse send codex "Refactor src/auth.py" --priority 3 --from claude

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

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

# Critical task (priority 5 - sends SIGINT first)
synapse send codex "URGENT: Fix production bug" --priority 5 --from claude

# Reply to a --response request (receiver uses --reply-to)
synapse send claude "Analysis result: ..." --reply-to abc123 --from gemini
```

**Important:** Always use `--from` to identify yourself so the recipient knows who sent the message and can reply. When replying to a `--response` request, use `--reply-to <task_id>` to link the response.

### Method 2: @Agent Pattern (User Input Only)

When typing directly in the terminal (not from agent code), you can use:

```
@codex Please refactor this file
@gemini Research this API
```

> **Note**: The `@agent` pattern only works for user input. Agents should use `synapse send` command.

## Configuration Files

### `.synapse/settings.json`

```json
{
  "a2a": {
    "flow": "auto"
  },
  "delegation": {
    "enabled": true
  }
}
```

### `.synapse/delegate.md`

```markdown
# Delegation Rules

Coding tasks (file editing, creation) go to Codex.
Research, web searches, documentation go to Gemini.
Code reviews, design decisions stay with Claude.

## File Safety

Check lock status before delegating file edits.

## Priority Guidelines

- Normal tasks: priority 3
- Follow-ups: priority 4
- Emergencies: priority 5
```

```

### references/file-safety.md

```markdown
# File Safety Integration

When delegating file modification tasks, use File Safety to prevent conflicts.

## Before Delegation

```bash
# Check existing locks
synapse file-safety locks

# Acquire lock for the target file
synapse file-safety lock /path/to/file.py <agent_name> --intent "Task description"
```

## In Delegation Message

Include file context:

```
@codex Please refactor src/auth.py.
Note: File is locked by claude for this task. Lock will be released after you complete.
Recent changes: claude fixed authentication logic (2026-01-09)
```

## After Delegation Completes

```bash
# Verify changes were recorded
synapse file-safety history /path/to/file.py

# Release lock if held
synapse file-safety unlock /path/to/file.py <agent_name>
```

## Handling Lock Conflicts

If target file is locked by another agent:

```
File /path/to/file.py is locked by <agent>.
Options:
1. Wait for completion
2. Work on different files first
3. Check with lock holder: @<agent> What's your progress?
```

## Pre-Delegation File Safety Check

When delegating file edits:

1. **Check lock status**:
   ```bash
   synapse file-safety locks
   ```

2. **If locked by another agent**: Inform user and wait or work on other files

3. **If unlocked**: Include lock instruction in delegation message

4. **After completion**: Verify lock was released

## Error Handling

### Lock Already Held

```
Error: File is locked by gemini (expires: 12:30:00)
```

**Solutions:**
- Wait for lock to expire
- Work on different files
- Coordinate with lock holder

### Failed to Acquire Lock

```
Error: Could not acquire lock for /path/to/file.py
```

**Solutions:**
- Check if file exists
- Check permissions
- Retry after brief delay

```

### references/examples.md

```markdown
# Delegation Examples

## Setup Example

### Step 1: Initialize Settings (if not done)

```bash
synapse init
# Select: Project scope (./.synapse/)
```

### Step 2: Enable Delegation

Edit `.synapse/settings.json`:
```json
{
  "delegation": {
    "enabled": true
  }
}
```

Or use interactive TUI:
```bash
synapse config
# Select: Delegation
# Set: enabled = true
```

### Step 3: Define Rules

Edit `.synapse/delegate.md`:
```markdown
# Delegation Rules

Coding goes to Codex, research goes to Gemini.
Code reviews stay with Claude.
```

### Step 4: Start Agents and Delegate

```text
> Implement user authentication

[Pre-check]
- Codex: READY ✓
- File Safety: src/auth.py - not locked ✓

Delegating coding task to Codex...
synapse send codex "Please implement user authentication. Target file: src/auth.py" --response --from claude

[Codex processing... monitor with synapse list --watch]

Response from Codex:
- Created src/auth.py
- Created tests/test_auth.py

Integrated result:
✓ User authentication implemented
  - New files: src/auth.py, tests/test_auth.py
  - Tests: 5 passed
```

## Status Display Example

Check current delegation status:

```bash
# View settings
synapse config show

# View running agents
synapse list

# With watch mode (shows TRANSPORT during communication)
synapse list --watch
```

Example output:
```text
TYPE       PORT     STATUS       TRANSPORT   PID      WORKING_DIR              ENDPOINT
claude     8100     READY        -           12345    /path/to/project         http://localhost:8100
codex      8120     READY        -           12346    /path/to/project         http://localhost:8120
gemini     8110     PROCESSING   -           12347    /path/to/project         http://localhost:8110
```

Check file safety status:
```bash
synapse file-safety locks
```

## Error Handling Examples

### Agent Not Responding

If agent doesn't respond within reasonable time:

1. Check agent status:
   ```bash
   synapse list
   ```

2. If PROCESSING for too long, send priority 4-5 follow-up:
   ```bash
   synapse send <agent> "Status update?" --priority 4 --from <your-agent>
   ```

3. If agent appears stuck, inform user and suggest alternatives

### Agent Not Available

If target agent is not running:

```text
Target agent (<agent>) not found.
Solutions:
1. Start in another terminal: synapse <agent>
2. Delegate to different agent
3. Process manually
```

### Task Failed

If delegated task fails:

1. Review error message from agent
2. Provide context and retry with adjusted instructions
3. If repeated failures, process directly or suggest user intervention

## Monitoring Examples

### Real-time Status

```bash
# Watch agent status changes
synapse list --watch

# Check specific agent
synapse list | grep <agent>
```

### Task History

If history is enabled:

```bash
# Recent tasks by agent
synapse history list --agent <agent> --limit 10

# Task details
synapse history show <task_id>

# Statistics
synapse history stats --agent <agent>
```

### Git Activity

Monitor file changes from delegated tasks:

```bash
git status
git log --oneline -5
git diff
```

```