synapse-a2a

Synapse A2A Communication

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "synapse-a2a" with this command: npx skills add s-hiraoku/synapse-a2a/s-hiraoku-synapse-a2a-synapse-a2a

Synapse A2A Communication

Inter-agent communication framework via Google A2A Protocol.

Quick Reference

Task Command

List agents synapse list (auto-refresh, interactive: arrows/1-9 select, Enter jump, k kill, / filter; --json for machine-readable output). MCP alternative: list_agents tool (via tools/call )

Agent detail synapse status <target> [--json]

Send message synapse send <target> "<msg>" (default: --notify ; --from auto-detected)

Send with task synapse send <target> "<msg>" --task / -T (auto-creates board task, auto-claim on receive, auto-complete on finalize)

Broadcast synapse broadcast "<msg>"

Wait for reply synapse send <target> "<msg>" --wait

Fire-and-forget synapse send <target> "<msg>" --silent

Reply synapse reply "<response>"

Reply to specific synapse reply "<response>" --to <sender_id>

Interrupt (priority 4) synapse interrupt <target> "<msg>"

Spawn agent synapse spawn <type> --name <n> --role "<r>" -- <tool-specific-automation-args>

Spawn with worktree synapse spawn <type> --worktree --name <n> --role "<r>" -- <tool-specific-automation-args>

Team start synapse team start <homogeneous-profiles...> [--worktree] -- <tool-specific-automation-args>

Create task synapse tasks create "<subject>" -d "<desc>" --priority <n> [--group G] [--component C] [--milestone M]

List tasks synapse tasks list [--verbose] [--format json] [--group-by COL] [--group G] [--component C] [--milestone M]

Assign task synapse tasks assign <id> <agent>

Complete task synapse tasks complete <id>

Purge tasks synapse tasks purge [--status STATUS] [--older-than DURATION] [--dry-run]

Approve plan synapse approve <id>

Reject plan synapse reject <id> --reason "<feedback>"

Save knowledge synapse memory save <key> "<content>" --tags <t> --notify

Search knowledge synapse memory search "<query>"

Lock file synapse file-safety lock <file> <agent_id> --intent "..."

Check locks synapse file-safety locks

Task history synapse history list --agent <name>

Kill agent synapse kill <name> -f

Attach files synapse send <target> "<msg>" --attach <file> --wait

Saved agents synapse agents list / synapse spawn <agent_id>

Post to Canvas synapse canvas post <format> "<body>" --title "<title>"

Link preview synapse canvas link "<url>" --title "<title>"

Post template synapse canvas briefing '<json>' --title "<title>"

Post plan card synapse canvas plan '<json>' --title "<title>" (Mermaid DAG + step list with status tracking)

Open Canvas synapse canvas open (auto-starts server, opens browser)

Accept plan synapse tasks accept-plan <plan_id> (register plan steps as task board tasks)

Sync plan progress synapse tasks sync-plan <plan_id> (sync task board status back to plan card)

Collaboration Decision Framework

Evaluate collaboration opportunities before starting work:

Situation Action

Small task within your role Do it yourself

Task outside your role, READY agent exists Delegate: synapse send --notify or --silent

No suitable agent exists Spawn: synapse spawn <type> --name <n> --role "<r>" -- <tool-specific-automation-args>

Stuck or need expertise Ask: synapse send <target> "<question>" --wait

Completed a milestone Report: synapse send <manager> "<summary>" --silent

Discovered a pattern Share: synapse memory save <key> "<pattern>" --tags ... --notify

Mandatory Collaboration Gate (3+ phases OR 10+ file changes):

  • synapse list — check available agents

  • synapse memory search "<topic>" — check shared knowledge

  • synapse tasks create — register work on the task board

  • Build Agent Assignment Plan (Phase / Agent / Rationale)

  • Spawn specialists if needed (prefer different model types for diversity)

Use Synapse Features Actively

Feature Why It Matters Commands

Task Board Transparent work tracking prevents duplication; grouping (--group, --component, --milestone), verbose/JSON output, age-based purge synapse tasks create/assign/complete/fail/reopen/purge/list

Shared Memory Collective knowledge survives agent restarts synapse memory save/search/list

File Safety Locking prevents data loss when two agents edit the same file synapse file-safety lock/unlock/locks

Worktree File isolation eliminates merge conflicts in parallel editing synapse spawn --worktree

Broadcast Team-wide announcements reach all agents instantly synapse broadcast "<msg>"

History Audit trail tracks what happened and when synapse history list/show/stats

Plan Approval Gated execution ensures quality before action synapse approve/reject

Canvas Visual dashboard for sharing rich cards and templates (briefing, comparison, dashboard, steps, slides, plan) synapse canvas post/link/briefing/plan/open/list

Admin Command Center Browser-based agent management via Canvas #/admin view (select agents, send messages, view responses) synapse canvas open → navigate to #/admin

Plan Cards Mermaid DAG + step list with accept/sync workflow for task board integration synapse canvas plan / synapse tasks accept-plan / synapse tasks sync-plan

Smart Suggest MCP tool that analyzes prompts and suggests team/task splits for large work MCP tool: analyze_task

Proactive Mode Mandatory feature usage checklist for every task (SYNAPSE_PROACTIVE_MODE_ENABLED=true ) See references/features.md

MCP Bootstrap Distribute instructions via MCP resources for compatible clients (opt-in, including Copilot via tools-only). MCP tools: bootstrap_agent , list_agents , analyze_task

synapse mcp serve / python -m synapse.mcp

Task Board Default Triggers

Use the Task Board by default when any of these are true:

  • 2+ agents will work on the task

  • The work is likely to run longer than 30 minutes

  • The task spans 3+ files , multiple phases, or distinct subtasks

  • A handoff, manager review, or resume later workflow is likely

  • You need the team to see pending / in_progress / completed / failed state at a glance

Minimum pattern:

synapse tasks create "<subject>" -d "<shared scope and done criteria>" synapse tasks assign <id> <agent> synapse tasks complete <id> synapse tasks fail <id> --reason "<blocker or failure>"

Shortcut — task-linked send: Use --task / -T to create a board task and link it to the message in one step. The receiver auto-claims the task on receipt, and it auto-completes when the A2A task finalizes. The PTY displays a [Task: XXXXXXXX] tag so both agents can see the link.

synapse send Impl "Implement auth module" --task --silent

Equivalent to: tasks create + tasks assign + send with board_task_id

Cleanup: Use synapse tasks purge to remove stale tasks from the board.

synapse tasks purge # Delete all tasks synapse tasks purge --status completed # Delete only completed tasks synapse tasks purge --status failed # Delete only failed tasks synapse tasks purge --older-than 7d # Delete tasks older than 7 days synapse tasks purge --dry-run # Preview what would be deleted

If none of the triggers apply and the work is a small single-agent change, you can skip the task board.

Canvas Template Default Triggers

Use Canvas templates by default when the output should be read by another agent or a human later, not just glanced at once in the terminal.

  • briefing for structured reports, status updates, and release summaries

  • comparison for before/after, option trade-offs, and review diffs

  • steps for plans, migration sequences, and execution checklists

  • slides for walkthroughs, demos, and page-by-page narratives

  • dashboard for multi-widget operational snapshots and compact status boards

  • plan for task DAGs with Mermaid visualization, step tracking, and task board integration (accept-plan / sync-plan )

Prefer raw synapse canvas post <format> only when a single block is enough. If the message has multiple sections or needs stronger information hierarchy, use a template.

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

Condition Action

Existing READY agent can handle it synapse send — reuse is faster (avoids startup overhead)

Need parallel execution synapse spawn with --worktree -- <tool-specific-automation-args> for file isolation

Task needs a different model's strengths Spawn a different type (Claude spawns Gemini, etc.)

User specified agent count Follow exactly

Single focused subtask Spawn 1 agent

N independent subtasks Spawn N agents

Spawn lifecycle: spawn → confirm in synapse list → wait for READY → send task → evaluate result → kill → confirm cleanup in synapse list

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 # Verify agent appears

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

If synapse kill fails or the agent still appears in synapse list , 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:

Mode Flag Use When

Wait --wait

You need the answer before continuing (questions, reviews)

Notify --notify (default) Async — you'll be notified on completion

Silent --silent

Fire-and-forget delegation (no response needed; sender history still updates best-effort on completion)

Worker Agent Guide

When you receive a task from a manager or pick one from the task board:

On Task Receipt

  • Start work immediately ([REPLY EXPECTED] requires a reply; otherwise no reply needed)

  • If the message contains [Task: XXXXXXXX] , the board task was auto-claimed for you — no manual tasks assign needed

  • Check shared knowledge: synapse memory search "<task topic>"

  • 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

  • Update task board: synapse tasks complete <task_id>

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

On Failure

  • Update task board: synapse tasks fail <task_id> --reason "<reason>"

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

Related Skills

Skill Purpose

synapse-manager

Multi-agent orchestration workflow (delegation, monitoring, verification)

synapse-reinst

Re-inject instructions after /clear or context reset

References

For detailed information, consult these reference files:

Reference Contents

references/commands.md

Full CLI command documentation with all options

references/api.md

A2A endpoints, readiness gate, error handling

references/examples.md

Multi-agent workflow examples and patterns

references/file-safety.md

File locking workflow and commands

references/messaging.md

Sending, replying, priorities, status states, interactive controls

references/spawning.md

Spawn lifecycle, patterns, worktree, permissions, API

references/collaboration.md

Agent naming, external agents, auth, resume, path overrides

references/features.md

Sessions, workflows, saved agents, tokens, skills, settings, Canvas

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

General

synapse-reinst

No summary provided by upstream source.

Repository SourceNeeds Review
83-s-hiraoku
General

frontend-design

No summary provided by upstream source.

Repository SourceNeeds Review
60-s-hiraoku
General

system-design

No summary provided by upstream source.

Repository SourceNeeds Review
53-s-hiraoku
General

sync-plugin-skills

No summary provided by upstream source.

Repository SourceNeeds Review
51-s-hiraoku