Synapse Manager Orchestrate multi-agent work with structured delegation, monitoring, and quality gates. When to Use Coordinating 2+ agents on related subtasks Monitoring progress of delegated work Verifying agent outputs (tests, file changes, integration) Sending targeted feedback with error details and fix guidance Orchestrating cross-review between agents Implementing a multi-phase plan (3+ phases or 10+ file changes) Planning agent assignment for multi-file changes Workflow (7 Steps) Step 1: Plan, Spec, and Setup New tests first. Follow this order for every implementation task: create tests -> present/confirm spec -> then implement. Edit plugins/synapse-a2a/skills/ first, then sync generated copies with sync-plugin-skills . Task board is the default coordination surface for manager-led work. Create or refresh task board entries before delegation starts so ownership, blocking, and completion state are visible to the whole team. Check existing agents before spawning — reuse is faster (avoids startup overhead, instruction injection, and readiness wait): synapse list 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. Step 2: Create Tests and Confirm the Spec Task board makes work visible to the entire team, prevents duplication, and ensures implementation is blocked on confirmed tests/spec: synapse tasks create "Write auth tests" \ -d "Create tests/spec for valid login, invalid credentials, token expiry, refresh flow" \ --priority 5 synapse tasks create "Implement auth module" \ -d "Add OAuth2 with JWT in synapse/auth.py after tests/spec are confirmed. Follow patterns in synapse/server.py." \ --priority 4 \ --blocked-by 1 Assign the test/spec task and confirm scope before implementation starts: synapse tasks assign 1 Tester synapse send Tester "Write the tests first and confirm the spec for task #1. - 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. Default expectation: synapse tasks create for each meaningful work unit synapse tasks assign or synapse tasks claim when ownership changes synapse tasks complete when verification passes synapse tasks fail when blocked or broken, with a reason the next agent can act on Step 3: Delegate Implementation and Monitor After tests/spec are confirmed, assign the implementation task: synapse tasks assign 2 Impl synapse send Impl "Implement auth module — tests/spec are confirmed in task #1. - Add OAuth2 flow in synapse/auth.py - Follow existing patterns" --attach synapse/server.py --force --silent synapse list
Live status (auto-updates)
synapse tasks list
Task board progress and dependencies
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 Step 4: Approve Plans synapse approve < task_id
synapse reject < task_id
--reason "Use refresh tokens instead of long-lived JWTs." Step 5: Verify Testing is the critical quality gate — start with the new tests/spec that were created up front, then run broader regression coverage because an agent's changes may break unrelated modules through import chains or shared state:
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 Exit 0 = REGRESSION (your changes broke it) → proceed to Step 6 Exit 1 = PRE-EXISTING (already broken) → note it and continue Update task board: synapse tasks complete < task_id
synapse tasks fail < task_id
--reason "test_refresh_token fails — TypeError on line 42" Step 6: Feedback 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). Step 7: Review & Wrap-up 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 tasks complete 1 && synapse tasks complete 2 synapse kill Impl -f && synapse kill Tester -f synapse list
Verify cleanup
Killing spawned agents frees ports, memory, and PTY sessions. Orphaned agents
may accidentally accept future tasks intended for other agents.
Decision Table
Situation
Action
Agent stuck PROCESSING >5min
synapse interrupt