Coordinate multi-agent tasks with visible group updates. Use when delegating work across multiple topic agents and the user needs transparent progress in-gro...
---
name: multi-agent-sync
description: Coordinate multi-agent tasks with visible group updates. Use when delegating work across multiple topic agents and the user needs transparent progress in-group (start update, mid-progress update, final summary).
---
# Multi-Agent Sync
Use this skill when running multi-agent collaboration in chat groups.
## Objective
Keep execution transparent: do not only run background session calls. Always mirror key progress back to the group thread.
Primary delivery rule:
- In multi-agent tasks, post progress and final summary in the group topic thread (e.g., topic1).
- Keep main/direct chat lightweight for control messages only, because user may continue other tasks there.
- Main session must not block waiting for all agents to finish; dispatch then return immediately with a short status note.
## Mandatory workflow
0. **Planning defaults (must declare in assignment)**
- For coding subtasks, explicitly state: use `openai-codex-operator` (Codex skill).
- For multi-agent orchestration, explicitly state: this run follows `multi-agent-sync`.
1. **Kickoff sync**
- Post a visible group message with:
- task objective
- role split (who does what)
- expected deliverables
- default skills used in this run (Codex + multi-agent-sync when applicable)
- Auto-start a temporary watcher job at kickoff (cron/timer) for this task.
2. **Dispatch tasks**
- Send detailed instructions to each agent session.
- Include required skill constraints in task text (e.g., coding agent must use Codex skill).
- Use non-blocking dispatch behavior (do not wait on long `sessions_send` timeouts).
- After dispatch, immediately send a non-blocking acknowledgment in main/direct chat and release control.
3. **Mid-progress sync**
- Each agent must post its own progress updates in its own topic (do not replace with a single orchestrator summary).
- Mandatory milestone labels per agent: `started` → `partial` → `done` (or `blocked`).
- Also post periodic heartbeat-style updates if an agent is still running.
- High-frequency mode (user requested): continuously post intermediate updates for each material step/change (no long interval waiting).
- If a tool call returns timeout, explicitly say "timeout != failure" and continue tracking.
- If any milestone is missing, orchestrator must immediately backfill a status-correction message and record the miss.
4. **Collect outputs**
- Use session history/log checks to confirm outputs from each agent.
- Ensure each agent has at least one visible mid-progress message in the group thread (not only final output).
4.5 **Coordinator periodic rollup (topic1)**
- Coordinator must post periodic cross-agent rollups in summary topic (topic1):
- who is started / partial / done / blocked
- latest artifact or evidence from each agent
- next checkpoint
- Rollups complement (not replace) per-agent own progress messages.
- Recommended cadence: every 1–2 minutes while task is active (adaptive by task length).
- Hard requirement: after each poll cycle, publish a rollup immediately (do not delay publish after status is known).
- Prefer a temporary scheduled watcher for active tasks (timer/cron-style).
- Watcher tick action: poll agent session history (e.g., topic3/topic5), then immediately publish rollup to topic1.
- Completion action: when all agents are done/blocked, publish final closure and remove watcher immediately.
- This watcher lifecycle is mandatory whenever this skill is used.
- Expected behavior in practice: watcher tick posts rollup to topic1; when both worker topics reach done/blocked, watcher publishes closure and is removed in the same flow.
4.6 **Dual mechanism (push + pull)**
- Push: each agent must proactively post milestone updates in its own topic.
- Pull: coordinator must poll session history to detect silent completions or stuck states.
- Do not rely on only one mechanism.
5. **Final sync**
- Keep agent-level outputs in each agent topic.
- Post one structured cross-agent final summary in the designated summary topic (usually topic1) with:
- implementation result
- test/validation result
- delivery artifact paths (absolute or repo-relative)
- implementation principle/approach analysis
- next actions
- Do not keep final summary only in main/direct chat.
## State handling rules
- Treat `timeout` as "no reply in window", not hard failure.
- Continue with follow-up checks (`sessions_history` / process logs).
- If no output after retries, post a blocked-status update with missing dependencies.
- Never keep main session waiting for long-running agent completion; use async follow-ups in group thread.
- Rule enforcement: do not close the task until each agent topic has visible `started` + `partial` + `done/blocked` entries.
- If an agent finishes work but did not proactively post `done`, coordinator must immediately issue a status-correction message and mark cause (e.g., timeout window, silent reply).
- If an agent repeatedly misses proactive updates, resend task with explicit milestone format and require immediate `started` ack.
- Coordinator failure mode to avoid: "status known but not published". If detected, immediately send a status-correction post in topic1.
## Output template (group-visible)
Use this 3-part structure in group chat:
1) 任务启动(分工)
2) 执行进度(中间状态)
3) 最终汇总(结果与后续)
## References
- `references/message-templates.md`
don't have the plugin yet? install it then click "run inline in claude" again.