synapse-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Synapse Manager

Orchestrate multi-agent work with structured delegation, monitoring, and quality gates.

通过结构化的任务分配、监控和质量关卡来编排多Agent工作。

Task Board Rule

任务看板规则

Every delegation MUST have a matching task board entry.

Before sending work to any agent via

synapse send

, you must:

synapse tasks create "<task>" -d "<description>"

— register the work unit

```
synapse tasks assign <id> <agent>
```
— record ownership
Only then
```
synapse send <agent> "..." --force
```

Task board is the team contract — it makes ownership, blocking, and completion state visible to every agent. TodoList is for your personal micro-step tracking only.

每一项任务分配都必须有对应的任务看板条目。

在通过

synapse send

向任何Agent发送工作之前，你必须：

synapse tasks create "<task>" -d "<description>"

— 登记工作单元

```
synapse tasks assign <id> <agent>
```
— 记录任务归属
完成上述步骤后，才能执行
```
synapse send <agent> "..." --force
```

任务看板是团队契约——它让所有Agent都能清晰看到任务归属、阻塞状态和完成状态。待办列表仅用于你个人的微步骤跟踪。

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

协调2个及以上Agent完成相关子任务
监控已分配工作的进度
验证Agent的输出结果（测试、文件变更、集成）
发送包含错误详情和修复指导的针对性反馈
编排Agent之间的交叉评审
实施多阶段计划（3个及以上阶段或10个及以上文件变更）
为多文件变更规划Agent分配

Workflow (7 Steps)

工作流（7个步骤）

Step 1: Plan, Spec, and Setup

步骤1：规划、制定规格与准备

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):

bash

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:

bash

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:

bash

cd plugins/synapse-a2a/skills/synapse-manager
scripts/wait_ready.sh Impl 30
scripts/wait_ready.sh Tester 30

先编写新测试。对于每个实现任务，请遵循以下顺序：创建测试 -> 提交并确认规格 -> 再进行实现。

先编辑

plugins/synapse-a2a/skills/

，然后使用

sync-plugin-skills

同步生成的副本。

任务看板是管理者主导工作的默认协作界面。在开始分配任务前，创建或刷新任务看板条目，让整个团队都能看到任务归属、阻塞状态和完成状态。

在生成新Agent前先检查现有Agent——复用现有Agent速度更快（避免启动开销、指令注入和就绪等待）：

bash

synapse list --json

查看WORKING_DIR、ROLE、STATUS、TYPE。只有状态为READY的Agent才能立即接受工作。

仅当没有现有Agent能处理任务时才生成新Agent：

bash

synapse spawn claude --worktree --name Impl --role "feature implementation"
synapse spawn gemini -w --name Tester --role "test writer"

跨模型生成Agent（例如Claude生成Gemini）可利用不同模型的优势，并在多个供应商之间分配令牌使用量，避免速率限制。

使用辅助脚本等待Agent就绪。从技能根目录执行该脚本，这样无论你在插件源目录还是同步副本目录，命令都能正常工作：

bash

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.

cd .agents/skills/synapse-manager scripts/wait_ready.sh Impl 30


查看`references/auto-approve-flags.md`获取各CLI权限跳过标志。

Step 2: Create Tests and Confirm the Spec

步骤2：创建测试并确认规格

Task board makes work visible to the entire team, prevents duplication, and ensures implementation is blocked on confirmed tests/spec:

bash

synapse tasks create "Write auth tests" \
  -d "Create tests/spec for valid login, invalid credentials, token expiry, refresh flow" \
  --priority 5

任务看板让工作对整个团队可见，避免重复工作，并确保实现任务会被阻塞，直到测试/规格得到确认：

bash

synapse tasks create "Write auth tests" \
  -d "Create tests/spec for valid login, invalid credentials, token expiry, refresh flow" \
  --priority 5

Returns: 3f2a1b4c (displayed prefix of a UUID such as 3f2a1b4c-1111-2222-3333-444444444444)

返回：3f2a1b4c（UUID的前8位前缀，完整UUID示例：3f2a1b4c-1111-2222-3333-444444444444）

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 3f2a1b4c

Returns: 7a9d2e10 (displayed prefix of a UUID such as 7a9d2e10-5555-6666-7777-888888888888)

返回：7a9d2e10（UUID的前8位前缀，完整UUID示例：7a9d2e10-5555-6666-7777-888888888888）


`synapse tasks create` stores a full UUID and prints its first 8 characters.
Use that prefix (or the full UUID) for `--blocked-by`, `synapse tasks assign`,
and `synapse tasks complete`.
In practice that means the implementation task should use a dependency like
`--blocked-by 3f2a1b4c`, where `3f2a1b4c` is the created test task's UUID prefix.
Conceptually this is still "implementation --blocked-by tests"; the concrete
value just needs to be the created test task's UUID prefix.

**Assign the test/spec task and confirm scope before implementation starts:**
```bash
TESTS_ID=3f2a1b4c
IMPL_ID=7a9d2e10

synapse tasks assign "$TESTS_ID" Tester
synapse send Tester "Write the tests first and confirm the spec for task $TESTS_ID (Write auth tests).
- 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

--notify

once execution is unblocked.

Default expectation:

```
synapse tasks create
```
for each meaningful work unit
```
synapse tasks assign
```
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


`synapse tasks create`会存储完整UUID并打印其前8个字符。可使用该前缀（或完整UUID）执行`--blocked-by`、`synapse tasks assign`和`synapse tasks complete`命令。

实际操作中，实现任务应使用类似`--blocked-by 3f2a1b4c`的依赖项，其中`3f2a1b4c`是已创建的测试任务的UUID前缀。从概念上讲，这仍然是“实现任务——被测试任务阻塞”；具体值只需是已创建测试任务的UUID前缀即可。

**分配测试/规格任务，并在开始实现前确认范围：**
```bash
TESTS_ID=3f2a1b4c
IMPL_ID=7a9d2e10

synapse tasks assign "$TESTS_ID" Tester
synapse send Tester "Write the tests first and confirm the spec for task $TESTS_ID (Write auth tests).
- Cover valid login, invalid credentials, token expiry, refresh flow
- Report any scope gaps before implementation starts" --attach synapse/server.py --force --wait

使用

--attach

发送Agent需要参考的文件。在确认测试/规格时使用

--wait

，在执行任务解除阻塞后使用

--silent

或

--notify

。

默认要求：

为每个有意义的工作单元执行
```
synapse tasks create
```
当任务归属变更时执行
```
synapse tasks assign
```
当验证通过时执行
```
synapse tasks complete
```
当任务被阻塞或出现问题时执行
```
synapse tasks fail
```
，并提供下一个Agent可以据此采取行动的原因

Step 3: Delegate Implementation and Monitor

步骤3：分配实现任务并监控

After tests/spec are confirmed, assign the implementation task:

bash

synapse tasks assign "$IMPL_ID" Impl
synapse send Impl "Implement auth module — tests/spec are confirmed in task $TESTS_ID (Write auth tests).
- Add OAuth2 flow in synapse/auth.py
- Follow existing patterns" --attach synapse/server.py --force --silent

Shortcut — task-linked send: For simple delegations, use

--task

-T

to create, assign, and send in one step (auto-claim on receive, auto-complete on finalize):

bash

synapse send Impl "Implement auth module" --task --attach synapse/server.py --force --silent

bash

synapse list --json                       # AI-safe snapshot
synapse tasks list                        # Task board progress and dependencies
synapse history list --agent Impl         # Completed work

Or use the aggregation script:

bash

cd plugins/synapse-a2a/skills/synapse-manager && scripts/check_team_status.sh

If an agent stays PROCESSING >5 min, send an interrupt:

bash

synapse interrupt Impl "Status update — what is your current progress?" --force

测试/规格确认后，分配实现任务：

bash

synapse tasks assign "$IMPL_ID" Impl
synapse send Impl "Implement auth module — tests/spec are confirmed in task $TESTS_ID (Write auth tests).
- Add OAuth2 flow in synapse/auth.py
- Follow existing patterns" --attach synapse/server.py --force --silent

快捷方式——关联任务的发送命令： 对于简单的任务分配，使用

--task

-T

一步完成创建、分配和发送（接收时自动认领，完成时自动标记完成）：

bash

synapse send Impl "Implement auth module" --task --attach synapse/server.py --force --silent

bash

synapse list --json                       # AI安全快照
synapse tasks list                        # 任务看板进度和依赖关系
synapse history list --agent Impl         # 已完成的工作

或使用聚合脚本：

bash

cd plugins/synapse-a2a/skills/synapse-manager && scripts/check_team_status.sh

如果Agent处于PROCESSING状态超过5分钟，发送中断命令：

bash

synapse interrupt Impl "Status update — what is your current progress?" --force

Step 4: Approve Plans

步骤4：审批计划

bash

synapse approve <task_id>
synapse reject <task_id> --reason "Use refresh tokens instead of long-lived JWTs."

Plan Card workflow — for structured plans posted to Canvas:

bash

undefined

bash

synapse approve <task_id>
synapse reject <task_id> --reason "Use refresh tokens instead of long-lived JWTs."

计划卡片工作流——对于发布到Canvas的结构化计划：

bash

undefined

Accept a plan card and register its steps as task board tasks

接受计划卡片并将其步骤注册为任务看板任务

synapse tasks accept-plan <plan_id>

Sync task board progress back to the plan card

将任务看板进度同步回计划卡片

synapse tasks sync-plan <plan_id>


**Update task board after decision:**
```bash

synapse tasks sync-plan <plan_id>


**决策后更新任务看板：**
```bash

After approve — keep the approved plan moving via assignment/delegation.

审批通过后——通过分配/委派让已批准的计划继续推进。

The task board changes at lifecycle checkpoints (assign, complete, fail, reopen).

任务看板在生命周期检查点（分配、完成、失败、重新打开）时更新。

After reject — mark for rework

拒绝后——标记为需要重新工作

synapse tasks reopen <task_id>

undefined

synapse tasks reopen <task_id>

undefined

Step 5: Verify

步骤5：验证

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:

bash

undefined

测试是关键的质量关卡——先运行预先创建的新测试/规格，然后运行更全面的回归测试，因为Agent的变更可能会通过导入链或共享状态破坏不相关的模块：

bash

undefined

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:
```bash
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:

bash

synapse tasks complete <task_id>
synapse tasks fail <task_id> --reason "test_refresh_token fails — TypeError on line 42"

pytest --tb=short -q


**回归问题分类**——区分新引入的问题和预先存在的问题：
```bash
cd plugins/synapse-a2a/skills/synapse-manager && scripts/regression_triage.sh tests/test_failing_module.py -v

退出码0 = 回归问题（你的变更导致了故障）→ 进入步骤6
退出码1 = 预先存在的问题（原本就有故障）→ 记录问题并继续

更新任务看板：

bash

synapse tasks complete <task_id>
synapse tasks fail <task_id> --reason "test_refresh_token fails — TypeError on line 42"

Step 6: Feedback

步骤6：反馈

Concrete, actionable feedback saves iteration cycles:

bash

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:

bash

synapse memory save auth-middleware-pattern \
  "Auth middleware must exclude /status and /.well-known/* endpoints" \
  --tags auth,middleware --notify

After sending feedback, reopen the task and return to Step 3 (Monitor):

bash

synapse tasks reopen <task_id>

具体、可操作的反馈能减少迭代周期：

bash

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

为团队保存可复用的模式：

bash

synapse memory save auth-middleware-pattern \
  "Auth middleware must exclude /status and /.well-known/* endpoints" \
  --tags auth,middleware --notify

发送反馈后，重新打开任务并回到步骤3（监控）：

bash

synapse tasks reopen <task_id>

Step 7: Review & Wrap-up

步骤7：评审与收尾

Cross-review catches blind spots — each agent reviews the other's work:

bash

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:

bash

pytest --tb=short -q                      # All tests pass
synapse tasks list                        # Confirm the UUID prefixes before completion
synapse tasks complete "$TESTS_ID"
synapse tasks complete "$IMPL_ID"
synapse kill Impl -f && synapse kill Tester -f
synapse list --json                       # Verify cleanup
synapse tasks purge --status completed    # Clean up finished tasks
synapse tasks purge --older-than 7d      # Clean up old tasks
synapse tasks purge --dry-run            # Preview what would be deleted

Killing spawned agents frees ports, memory, and PTY sessions. Orphaned agents may accidentally accept future tasks intended for other agents.

交叉评审能发现盲点——每个Agent评审另一个Agent的工作：

bash

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

最终验证与清理：

bash

pytest --tb=short -q                      # 所有测试通过
synapse tasks list                        # 完成前确认UUID前缀
synapse tasks complete "$TESTS_ID"
synapse tasks complete "$IMPL_ID"
synapse kill Impl -f && synapse kill Tester -f
synapse list --json                       # 验证清理完成
synapse tasks purge --status completed    # 清理已完成的任务
synapse tasks purge --older-than 7d      # 清理7天前的任务
synapse tasks purge --dry-run            # 预览将被删除的内容

终止已生成的Agent能释放端口、内存和PTY会话。孤立的Agent可能会意外接受原本为其他Agent准备的未来任务。

Decision Table

决策表

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 "..."`
Agent posts a plan card	`synapse tasks accept-plan <plan_id>` to register steps, `synapse tasks sync-plan <plan_id>` to update
Discovered a reusable pattern	`synapse memory save <key> "<pattern>" --notify`
Cross-review finds issue	Send fix request with `--attach` , re-verify
Delegating work to an agent	`synapse tasks create` + `synapse tasks assign` before `synapse send`
All tests pass, reviews clean	Complete tasks, kill agents, report done

场景	操作
Agent处于PROCESSING状态超过5分钟	`synapse interrupt <name> "Status?"`
一次性检查所有Agent	`synapse broadcast "Status check" -p 4`
新测试失败	发送包含错误和建议修复方案的反馈（步骤6）
回归测试失败	使用 `scripts/regression_triage.sh` 进行分类
Agent状态为READY但无输出	检查 `git diff` ，必要时重新发送任务
Agent提交计划	`synapse approve` 或 `synapse reject --reason "..."`
Agent发布计划卡片	使用 `synapse tasks accept-plan <plan_id>` 注册步骤，使用 `synapse tasks sync-plan <plan_id>` 更新进度
发现可复用模式	`synapse memory save <key> "<pattern>" --notify`
交叉评审发现问题	发送包含 `--attach` 的修复请求，重新验证
向Agent委派工作	在执行 `synapse send` 前先执行 `synapse tasks create` + `synapse tasks assign`
所有测试通过，评审无问题	完成任务，终止Agent，报告任务完成

References

参考资料

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 (agents + task board)
`scripts/regression_triage.sh`	Classify test failure as regression or pre-existing

参考资料	内容
`references/auto-approve-flags.md`	各CLI权限跳过标志
`references/worker-guide.md`	工作Agent的职责和沟通模式
`references/features-table.md`	A2A功能及对应命令
`references/commands-quick-ref.md`	所有与管理者相关的命令
`scripts/wait_ready.sh`	轮询直到Agent进入READY状态
`scripts/check_team_status.sh`	汇总团队状态（Agent + 任务看板）
`scripts/regression_triage.sh`	将测试失败分类为回归问题或预先存在的问题