multi-agent-sync

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