Synapse A2A Communication

Inter-agent communication framework via Google A2A Protocol.

Quick Reference

Collaboration Decision Framework

Evaluate collaboration opportunities before starting work:

Recommended Collaboration Gate (3+ phases OR 10+ file changes): Consider these steps before diving into large work:

1. synapse list --json or MCP list_agents — check available agents
2. synapse memory search "<topic>" — check if someone already solved this
3. Build Agent Assignment Plan (Phase / Agent / Rationale) when delegation is beneficial
4. Spawn specialists if needed (prefer different model types for diversity)

Skip this gate for small/medium tasks where the overhead exceeds the benefit.

Use Synapse Features Actively

When to Use Canvas

Use Canvas when the output benefits from visual structure or will be referenced later:

• Use Canvas for: diagrams, comparison tables, multi-step plans, design docs, results with rich formatting
• Skip Canvas for: simple completion reports, single-file changes, quick status updates (use broadcast or reply instead)

Template selection guide:

• briefing — structured reports, status updates, release summaries
• comparison — before/after, option trade-offs, review diffs
• steps — plans, migration sequences, execution checklists
• slides — walkthroughs, demos, page-by-page narratives
• dashboard — multi-widget operational snapshots, compact status boards
• plan — task DAGs with Mermaid visualization and step tracking

Use raw synapse canvas post <format> for single blocks; templates for multi-section content.

Spawning Decision Table

Default spawn policy: When using synapse spawn, pass the underlying CLI's tool-specific automation args after -- so spawned agents can run unattended. For most CLIs this is an approval-skip / auto-approve flag; for OpenCode use --agent build to select the build agent profile and rely on OpenCode's permission config for approval behavior.

Apply the same rule to synapse team start: include the appropriate forwarded CLI args by default, and keep teams homogeneous when those args are CLI-specific.

Common defaults:

• Claude Code: synapse spawn claude --name <n> --role "<r>" -- --dangerously-skip-permissions
• Gemini CLI: synapse spawn gemini --name <n> --role "<r>" -- --approval-mode=yolo
• Codex CLI: synapse spawn codex --name <n> --role "<r>" -- --full-auto
• OpenCode: synapse spawn opencode --name <n> --role "<r>" -- --agent build (selects the build agent profile; not a skip-approval flag)
• Copilot CLI: synapse spawn copilot --name <n> --role "<r>" -- --allow-all-tools
• Claude team: synapse team start claude claude -- --dangerously-skip-permissions
• Gemini team: synapse team start gemini gemini -- --approval-mode=yolo
• Codex team: synapse team start codex codex -- --full-auto
• OpenCode team: synapse team start opencode opencode -- --agent build (selects the build agent profile; permission prompts still depend on OpenCode config)
• Copilot team: synapse team start copilot copilot -- --allow-all-tools

Spawn lifecycle: spawn → confirm in synapse list --json or synapse status <target> --json → wait for READY → send task → evaluate result → kill → confirm cleanup in synapse list --json

Killing spawned agents after completion frees ports, memory, and PTY sessions, and prevents orphaned agents from accidentally accepting future tasks.

# Spawn, delegate, verify, cleanup
synapse spawn gemini --name Tester --role "test writer" -- --approval-mode=yolo
synapse list --json                       # Verify agent appears (AI-safe)
# Wait for readiness (or rely on server-side Readiness Gate)
synapse send Tester "Write tests for src/auth.py" --wait
# Evaluate result, then cleanup
synapse kill Tester -f
synapse list --json                       # Verify cleanup (AI-safe)

If synapse kill fails or the agent still appears in synapse list --json, retry with -f, check the agent status/logs, and report the cleanup failure instead of leaving an orphaned agent behind.

Response Mode Guide

Choose based on whether you need the result:

Worker Agent Guide

When you receive a task from a manager:

On Task Receipt

1. Start work immediately ([REPLY EXPECTED] requires a reply; otherwise no reply needed)
2. Check shared knowledge: synapse memory search "<task topic>"
3. Lock files before editing: synapse file-safety lock <file> $SYNAPSE_AGENT_ID

During Work

• Report progress if task takes >5 minutes: synapse send <manager> "Progress: <update>" --silent
• Report blockers immediately: synapse send <manager> "<question>" --wait
• Save findings: synapse memory save <key> "<finding>" --tags <topic>
• You can delegate subtasks too — spawn helpers (prefer different model types)
• Always clean up agents you spawn: synapse kill <name> -f

On Completion

1. Report to manager: synapse send <manager> "Done: <summary>" --silent

On Failure

1. Report details: synapse send <manager> "Failed: <error details>" --silent

Related Skills

References

For detailed information, consult these reference files: