synapse-a2a

What this skill does

# Synapse A2A Communication

Inter-agent communication framework via Google A2A Protocol.

## Worktree Discipline (subagents, read this first)

> **NEVER `cd` into `.synapse/worktrees/<name>/` directories.**
>
> Subagents (Claude Code Agent tool, Codex subprocess, and any other
> sub-process driven by the parent session) inherit a persistent shell
> from the parent. A stray `cd` into a worktree leaks out of the subagent
> turn and silently corrupts the parent's working directory — `git status`,
> `git diff`, and even `git commit` then land on the wrong worktree, which
> wastes debugging time and can put commits on the wrong branch.
>
> Rules for working with `.synapse/worktrees/`:
>
> - Do **not** `cd` into a worktree, ever. Stay in the original working
>   directory for the entire session.
> - Read and write files inside a worktree using **absolute paths only**
>   (for example `Read /Volumes/.../.synapse/worktrees/foo/src/bar.py`,
>   not `cd .synapse/worktrees/foo && cat src/bar.py`).
> - Run `git` against a worktree with `git -C /abs/path/to/worktree ...`
>   instead of changing directory.
> - Worktrees are managed by Synapse (`synapse spawn --worktree`,
>   `synapse team start --worktree`). Treat them as read/write data
>   surfaces, not as places to live.
>
> If you need to operate from inside a worktree (e.g. running `pytest`
> there), spawn a dedicated agent for it with `synapse spawn --worktree`
> rather than changing the parent shell's directory.


## Quick Reference

| Task | Command |
|------|---------|
| List agents | `synapse list` for humans (auto-refresh, interactive: arrows/1-9 select, Enter jump, k kill, / filter). For AI/scripts use `synapse list --json`, `synapse list --plain`, or MCP `list_agents` |
| Agent detail | `synapse status <target> [--json]` |
| Stuck-agent watchdog (Stage 1) | `synapse watchdog check [--alarm-only] [--json]` (one-shot heuristic scan; #646) |
| Send message | `synapse send <target> "<msg>"` (default: `--notify`; `--from` auto-detected) |
| 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>` |
| Reply with failure | `synapse reply --fail "<reason>"` |
| Interrupt (priority 4) | `synapse interrupt <target> "<msg>"` |
| Send keys to PTY (escape hatch for TUI dialogs; #695) | `synapse send-keys <target> <keys>` (e.g. `a` for codex "don't ask again", `\r` for Enter; bypasses A2A — use when an agent is stuck on an interactive dialog without `synapse jump`) |
| Spawn agent | `synapse spawn <type> --name <n> --role "<r>" -- <tool-specific-automation-args>` |
| **Spawn + send first task** (preferred for delegation) | `synapse spawn <type> --name <n> --role "<r>" --task-file <path> --task-timeout 600 --notify` |
| 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>` |
| 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` |
| Cleanup orphans | `synapse cleanup --dry-run` (list); `synapse cleanup -f` (kill all orphans whose parent crashed/cleared) |
| Attach files | `synapse send <target> "<msg>" --attach <file> --wait` |
| Saved agents | `synapse agents list` / `synapse agents set <profile>` / `synapse agents unset <profile>` / `synapse agents roles` / `synapse spawn <agent_id>`; live agents expose `agent_definition_id` as a stable target alias |
| Shared session handoff | `synapse session publish <name>` / `synapse session import <name>` using `SYNAPSE_SHARED_SESSION_DIR` |
| 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) |
| Restart Canvas | `synapse canvas restart` (stop + start; use when `canvas status` reports `⚠ STALE` after upgrade) |
| Sync workflow skills | `synapse workflow sync` (regenerate skills from workflow YAMLs, remove orphans) |
| Run workflow (auto-spawn) | `synapse workflow run <name> --auto-spawn` (supports DAG steps with `depends_on` and `condition`) |
| Multi-agent patterns | `synapse map init/list/show/run/status/stop` (built-in: `generator-verifier`, `orchestrator-subagent`, `agent-teams`, `message-bus`, `shared-state`) |
| Wiki ingest | `synapse wiki ingest <source> [--scope project\|global]` (ingest a source file into the wiki) |
| Wiki query | `synapse wiki query "<question>" [--scope project\|global]` (search wiki pages) |
| Wiki lint | `synapse wiki lint [--scope project\|global]` (validate wiki consistency) |
| Wiki status | `synapse wiki status [--scope project\|global]` (show wiki index stats) |

## 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, need to delegate a task | Spawn + task in one command: `synapse spawn <type> --name <n> --role "<r>" --task-file <spec.md> --task-timeout 600 --notify`. This spawns, waits for READY, and sends the first task — no manual readiness polling needed. |
| Need a bare agent (no initial task) | `synapse spawn <type> --name <n> --role "<r>"` (send tasks later via `synapse send`) |
| 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` |

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

| Feature | Why It Matters | Commands |
|---------|---------------|----------|
| **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 -- skip inside worktrees (`SYNAPSE_WORKTREE_PATH`) | `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` |
| **Probabilistic Recall** | Recall relevant past task observations by recency, importance, and keyword overlap without dumping all history | `HistoryManager.recall_observations` |
| **Plan Approval** | Gated execution ensures quality before action | `synapse approve/reject` |
| **Canvas** | Visual dashboard for sharing rich c