hub-spoke

Implement a central Coordinator (Hub) that manages, distributes, and merges tasks performed by specialized worker sessions (Spokes). Spokes communicate only with the Hub and not with each other. Usefu

SKILL.md

GitHub

Hub-and-Spoke

The Hub-and-Spoke pattern designates a central Coordinator session (Hub) to manage planning, task distribution, progress checking, and final result merging. The Worker sessions (Spokes) execute their specific assignments independently and communicate only with the Hub.

5-Stage Workflow

         ┌───────────────┐
         │  Coordinator  │ ◄── Planning, task queue, and spoke bridging
         └───────┬───────┘
       ┌─────────┼─────────┐
       ▼         ▼         ▼
    Worker    Worker    Worker
     (A)       (B)       (C)
  1. Role Definition: Spawn a dedicated Coordinator session (Hub) and define specialized Spoke Worker configs.
  2. Task Planning: The Hub analyzes the goal, creates a task dependency list, and allocates work.
  3. Execution Routing:
    • Before spawning, inspect agent__listAgents(type="sessions") for an Idle child with the same assistant ID and a compatible workspace contract. Route new work to a suitable child with agent__messageToSession(..., complexity=...); use reset=true only when its previous conversation and runtime state should be discarded.
    • The Hub spawns a new Spoke asynchronously using agent__spawnSession(complexity=..., waitForResult=false) only when no suitable child exists, a different role or workspace isolation is needed, or another parallel capacity slot is required. Always pass complexity (low|normal|high).
    • Plain spokes get isolated workspaces by default. For repo/code work, pass workspaceOverride to the Hub's workspace (or a spoke-specific subdir). For research/write-ups, require the primary deliverable in the spoke's final text (Result:), not only a relative file path.
    • When sharing a workspace across parallel spokes, use unique filenames or per-spoke subdirectories to avoid collisions.
    • If inter-spoke coordination is needed, the Hub routes messages. See routing.md.
  4. Monitoring: The Hub polls Spoke statuses via agent__checkSession and reads the Metadata workspace line (SHARED vs ISOLATED) before assuming files exist in the Hub root.
  5. Synthesis: The Hub merges all finished spoke artifacts from Result text (and agent__messageToSession follow-ups when needed). For ISOLATED spokes, do not attempt parent workspace__readFile on the child Metadata path — ask the spoke for contents or require the deliverable in Result text. For SHARED spokes, relative paths in the Hub root are safe.

🛠️ MCP Tools Guide

  • Session Reuse: Match on assistantId, status, and workspace compatibility before creating a Spoke. A reset reuses the session's identity and workspace files but closes its browser session; do not reuse a child whose prior workspace or runtime state is incompatible.
  • Context Management: Do not let the Hub read all conversation logs from all Spokes to prevent context overflow. Instruct the Hub to only request summarized status reports and file list results.
  • Message Bridging: If Worker B depends on Worker A's output, the Hub collects the artifact details from A and injects them to B via agent__messageToSession.

References