From synapse-a2a
Multi-agent management workflow — task delegation, progress monitoring, quality verification with regression testing, feedback delivery, and cross-review orchestration. Use this skill when coordinating multiple agents on a shared task, monitoring delegated work, ensuring quality across agent outputs, or implementing a multi-phase plan (3+ phases or 10+ file changes).
npx claudepluginhub s-hiraoku/synapse-a2a --plugin synapse-a2aThis skill uses the workspace's default tool permissions.
Orchestrate multi-agent work with structured delegation, monitoring, and quality gates.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Generates original PNG/PDF visual art via design philosophy manifestos for posters, graphics, and static designs on user request.
Orchestrate multi-agent work with structured delegation, monitoring, and quality gates.
Prefer test-first when the scope is clear: create tests -> present/confirm spec -> then implement. For exploratory work, prototypes, or trivial fixes, writing tests after implementation is acceptable.
Edit plugins/synapse-a2a/skills/ first, then sync generated copies with sync-plugin-skills.
Check existing agents before spawning — reuse is faster (avoids startup overhead, instruction injection, and readiness wait):
synapse list --json
Review WORKING_DIR, ROLE, STATUS, TYPE. Only READY agents can accept work immediately.
Spawn only when no existing agent can handle the task:
synapse spawn claude --worktree --name Impl --role "feature implementation"
synapse spawn gemini -w --name Tester --role "test writer"
Cross-model spawning (Claude spawns Gemini, etc.) provides diverse strengths and distributes token usage across providers, avoiding rate limits.
Wait for readiness using the helper script. Resolve it from the skill root so the command works from any working directory, whether you are in the plugin source or a synced copy:
cd plugins/synapse-a2a/skills/synapse-manager
scripts/wait_ready.sh Impl 30
scripts/wait_ready.sh Tester 30
# Synced copy example
cd .agents/skills/synapse-manager
scripts/wait_ready.sh Impl 30
See references/auto-approve-flags.md for per-CLI permission skip flags.
Assign the test/spec task and confirm scope before implementation starts:
synapse send Tester "Write the tests first and confirm the spec for auth module.
- Cover valid login, invalid credentials, token expiry, refresh flow
- Report any scope gaps before implementation starts" --attach synapse/server.py --force --wait
Use --attach to send reference files the agent should study.
Use --wait while confirming tests/spec, then --silent or --notify once execution is unblocked.
After tests/spec are confirmed, delegate the implementation task:
synapse send Impl "Implement auth module — tests/spec are confirmed.
- Add OAuth2 flow in synapse/auth.py
- Follow existing patterns" --attach synapse/server.py --force --silent
synapse list --json # AI-safe snapshot
synapse history list --agent Impl # Completed work
Or use the aggregation script:
cd plugins/synapse-a2a/skills/synapse-manager && scripts/check_team_status.sh
If an agent stays PROCESSING >5 min, send an interrupt:
synapse interrupt Impl "Status update — what is your current progress?" --force
synapse approve <task_id>
synapse reject <task_id> --reason "Use refresh tokens instead of long-lived JWTs."
Run the tests created in Step 2 first for fast feedback, then consider broader regression coverage if the changes touch shared modules or public interfaces:
# New tests first (fast feedback)
pytest tests/test_auth.py -v
# Full regression (catches cross-module breakage)
pytest --tb=short -q
Regression triage — distinguish new breakage from pre-existing issues:
cd plugins/synapse-a2a/skills/synapse-manager && scripts/regression_triage.sh tests/test_failing_module.py -v
Concrete, actionable feedback saves iteration cycles:
synapse send Impl "Issues found — please fix:
1. FAILING TEST: test_token_expiry (tests/test_auth.py)
ERROR: TypeError: cannot unpack non-iterable NoneType object
FIX: Add None guard at the top of validate_token()
2. REGRESSION: test_existing_endpoint broke
ERROR: expected 200, got 401
CAUSE: auth middleware intercepts all routes
FIX: Exclude health-check endpoints from auth" --force --silent
Save patterns for the team:
synapse memory save auth-middleware-pattern \
"Auth middleware must exclude /status and /.well-known/* endpoints" \
--tags auth,middleware --notify
After sending feedback, return to Step 3 (Monitor).
Cross-review catches blind spots — each agent reviews the other's work:
synapse send Tester "Review implementation. Focus on: correctness, edge cases" --force \
--attach synapse/auth.py --wait
synapse send Impl "Review test coverage. Focus on: missing cases, assertion quality" --force \
--attach tests/test_auth.py --wait
Final verification and cleanup:
pytest --tb=short -q # All tests pass
synapse kill Impl -f && synapse kill Tester -f
synapse list --json # Verify cleanup
Killing spawned agents frees ports, memory, and PTY sessions. Orphaned agents may accidentally accept future tasks intended for other agents.
| Situation | Action |
|---|---|
| Agent stuck PROCESSING >5min | synapse interrupt <name> "Status?" |
| Check all agents at once | synapse broadcast "Status check" -p 4 |
| New test fails | Feedback with error + suggested fix (Step 6) |
| Regression test fails | scripts/regression_triage.sh to classify |
| Agent READY but no output | Check git diff, re-send if needed |
| Agent submits a plan | synapse approve or synapse reject --reason "..." |
| Discovered a reusable pattern | synapse memory save <key> "<pattern>" --notify |
| Cross-review finds issue | Send fix request with --attach, re-verify |
| All tests pass, reviews clean | Kill agents, report done |
| Reference | Contents |
|---|---|
references/auto-approve-flags.md | Per-CLI permission skip flags |
references/worker-guide.md | Worker agent responsibilities and communication patterns |
references/features-table.md | A2A features with commands |
references/commands-quick-ref.md | All manager-relevant commands |
scripts/wait_ready.sh | Poll until agent reaches READY status |
scripts/check_team_status.sh | Aggregate team status |
scripts/regression_triage.sh | Classify test failure as regression or pre-existing |