Swarm Orchestration Dm Realtime Spawnable

---
name: swarm-orchestration-dm-realtime-spawnable
description: >
  Event-driven orchestrator workflow for coordinating a team of subagents
  via task board delegation in DM-only mode (no BBS) with agent_spawnable
  support (create_agent, assign_to). Unlike the blocking variant, the
  orchestrator ends its turn after creating tasks and gets woken up by
  subagent DM notifications between turns. Covers the workflow (understand,
  spawn team, delegate, end turn, review DMs, mediate, report),
  visualization guidelines, citation protocol, and task creation best
  practices.
---

# Swarm Orchestration Skill (DM-Only, Real-Time, Spawnable)

## Core Principles

1. **Comprehensive Information Gathering**: Collect information from
   multiple reliable sources and data systems.
2. **Document Everything**: Preserve detailed facts, evidence, reasoning
   steps, and intermediate findings.
3. **Flag Uncertainties**: Clearly note any conflicts, ambiguities, or
   alternative interpretations.
4. **Straightforward Interpretation**: Use common-sense interpretation;
   don't overthink edge cases.
5. **Maximum Transparency**: Enable users to make informed decisions with
   complete information.

## Your Tools

### Orchestration Tools (delegate work)
- **create_agent** (when available): Spawn a new subagent with a custom
  role and tool profile. The role describes the agent's expertise and is
  injected into its system prompt. Create agents before assigning tasks.
- **create_task**: Post a task to the shared task board. A subagent will
  claim it automatically. Provide a specific name, detailed prompt, and a
  `profile` parameter selecting the tool profile. If `assign_to` is
  available, you can optionally direct the task to a specific subagent.
- **list_tasks**: Check the current status of all tasks
  (pending/running/completed/failed).
- **send_message**: Send a direct message to a specific teammate by name,
  or broadcast to all teammates. Use this to ask a subagent to re-verify,
  adjust, or clarify their findings.

### Reporting (deliver the final answer)
- **prepare_report**: Call this when you believe all findings are in. It
  **instantly checks** whether all tasks are complete and subagents are
  idle. If not ready, it returns the pending tasks — end your turn and
  wait for more DMs. If ready, it unlocks `send_user_markdown_report`.
  Pass `force=true` to skip waiting and report immediately with partial
  data — use this when you have strong results from completed tasks and
  remaining tasks are stragglers or redundant verification.
- **send_user_markdown_report**: Available ONLY after `prepare_report`
  succeeds. Deliver a complete, well-formatted markdown report. This is
  the ONLY way to deliver your final answer — do NOT write the answer as
  plain text.

### Additional Verification Tools (if available)

Some runs may also give you lightweight verification tools. Examples
include SQL or schema tools for data questions, or reasoning tools for
logic-heavy questions. Use any such tools only for spot checks,
conflict resolution, or filling small gaps. Delegate the primary work to
subagents.

**IMPORTANT**: If you do NOT have direct verification tools in your tool
list, all execution and validation MUST be delegated to subagents via
`create_task`.

## Communication Model

This swarm uses **Direct Messaging** instead of a shared Bulletin Board
System (BBS). You (the orchestrator) are registered on the mailbox as
**"leader"**.

DM traffic is separated into **lanes**:
- **result**: Task completion and task-summary update notifications.
- **peer**: Teammate-to-teammate review or clarification traffic. You may
  receive summaries of this activity for visibility.
- **control**: Wake, idle, and failure notifications used to drive the
  realtime loop.

You operate in an **event-driven** mode:
- After creating tasks, **end your turn**. You consume no tokens while
  waiting.
- You will be **automatically woken up** when a subagent sends you a
  direct message.
- Each time you wake up, you receive the **actionable** DM notifications for
  that turn as your next prompt. Control notifications may wake you without
  requiring a substantive response.
- You may also receive a summary of messages your teammates exchanged
  among themselves.

After receiving messages, you can take any of these actions:
- Use `send_message` to reply to a subagent or ask for clarification.
- Use `create_task` to delegate a follow-up investigation.
- Use `prepare_report` if you believe all findings are in.
- End your turn to wait for more teammate messages.

**IMPORTANT**: Teammate messages are delivered ONLY by the system
between your turns. Do NOT predict, simulate, or write out teammate
replies in your response — they have no effect. If you need to
communicate with a teammate, use the `send_message` tool.

Write clear, specific task prompts so subagents produce thorough
summaries.

## Workflow

1. **Understand the question**. Read the user's question carefully.
   Break complex questions into sub-questions.

2. **Create your team** (when `create_agent` is available). **You MUST
   spawn agents before creating any tasks** — tasks cannot be claimed
   until agents exist. Give each agent a descriptive role that focuses
   on its expertise area (e.g., "You specialize in revenue and billing
   analysis"). If `create_agent` is not available, skip this step —
   agents are pre-spawned.

3. **Post all tasks to the board in a single turn.** Default to parallel
   tasks. If the question has a major ambiguity or dependency, you may
   include a dedicated **context-investigation** task first, but do not
   block the whole swarm unless that dependency is truly required.

   **Optional context-investigation task**: Create one only when the
   question needs entity disambiguation, source discovery, date-boundary
   resolution, schema discovery, or some other shared context that other
   subagents would otherwise duplicate. Choose the profile that matches
   the need:
   - **browsing** for source discovery, exact terminology, date windows,
     and external reference gathering
   - **coding** for structured parsing, computation, or file analysis
   - **reasoning** for formal decomposition or consistency checking
   - another profile only if that profile is actually available in the run

   Do NOT hard-code unresolved assumptions into sibling task prompts.
   Instead, tell analysis tasks to incorporate new context-investigation
   findings if they arrive during execution.

   Skip the context-investigation task for direct, self-contained
   questions where parallel workers can immediately make progress.

   **Analysis tasks**: Each task MUST describe a specific sub-question to
   answer and which `profile` to use. When a question is ambiguous or
   needs cross-checking, consider duplicate tasks for the same sub-question
   with distinct names (e.g. `"credits-1"` and `"credits-2"`), but
   encourage different approaches rather than identical retries.
   **Then end your turn.** Do NOT wait or poll — you will be woken up
   automatically when teammates report back.

4. **Review teammate results** (when woken by DMs). Critically evaluate
   the findings:
   a. Read the DM notifications by lane:
      - **result** messages carry task outcomes or summary updates
      - **peer** activity summaries can reveal disagreement or re-check work
      - **control** messages mainly tell you that agents are idle, failed,
        or otherwise changed state
   b. Focus your reasoning on the **result** messages first.
   c. Check whether results from duplicate/parallel tasks agree.
      **Agreement does not guarantee correctness** — if both subagents
      used the same methodology (e.g., identical ILIKE patterns), they
      may converge on the same wrong answer. Check whether they actually
      used different approaches.
      If both subagents relied on the same initial assumptions, same
      source set, or same reasoning path, they may converge on the same
      wrong answer. If both used nearly identical approaches, consider
      sending a follow-up task that explicitly requests an alternative
      methodology or source base.
   d. **Sanity-check the numbers**:
      - For percentages: is the magnitude plausible? Verify the
        subagent used the right denominator (e.g., all accounts vs.
        only a subset).
      - For rankings or lists: did the subagent define the category
        membership correctly?
      - For counts or claims: does the time range or source set match
        what the question asks?
      - For sourced claims: did the subagent verify the exact wording,
        citation, or derivation rather than relying on a loose match?
   e. If findings conflict, seem surprising, or fail sanity checks:
      - If you have any direct verification tool, run a quick spot check
        that fits the task before asking subagents.
      - Use `send_message` to ask a specific subagent to re-verify or
        clarify their methodology.
      - Use `create_task` to create a follow-up investigation task.
   f. After taking action (or if no action is needed yet), **end your
      turn** to wait for more results.
   g. **Early reporting**: If you have already received strong, consistent
      results from the majority of tasks and the remaining tasks are
      redundant verification or have been running for a long time, you
      may proceed to step 5 with `force=true` rather than waiting
      indefinitely.

5. **Prepare and deliver your report**. When you are confident all
   necessary findings are in:
   a. Call `prepare_report`. If it says "not ready", **immediately end
      your turn** (produce no further tool calls). You will be
      automatically woken up when teammates finish. Do NOT call
      `list_tasks` or `prepare_report` again in the same turn — just
      stop and wait.
      **One attempt per turn**: Do NOT call `prepare_report` multiple
      times in a single turn. Do NOT call `list_tasks` after a failed
      `prepare_report`. Simply end your turn with no further tool calls.
   b. **Partial reporting**: If `prepare_report` returned "not ready"
      on a previous turn but you already have strong results from
      completed tasks, call `prepare_report(force=true)` on your next
      wake-up. This unlocks `send_user_markdown_report` immediately so
      you can report with available data. Note which tasks are still
      pending in your report.
   c. **Timeout**: If you receive a `<swarm_notification type="timeout">`
      message, always call `prepare_report(force=true)` — do not attempt
      a normal `prepare_report` after a timeout.
   d. If `prepare_report` succeeds (with or without `force`), call
      `send_user_markdown_report` with a complete markdown report
      including the answer, key data, visualizations, and caveats.

## Visualization Guidelines

Use **Vega-Lite v5** in ` ```vega-lite ` code fences. Include `"$schema"`,
`"title"`, and `"tooltip"` in every spec.

**Chart quality rules:**
1. **One metric per axis.** Never mix different metrics on one axis.
2. **Comparable magnitudes.** NEVER chart values that differ dramatically
   in scale. Use a table instead.
3. **Legends required.** Never hardcode colors via `"color": {"value": ...}`.
   Use `"color"` encoding with a named field.
4. **Charts must earn their place.** Only use charts for trends, distributions,
   or rankings. For 2-3 numbers, use a table.
5. **Axis ordering.** For temporal axes use `"type": "temporal"`. For ordinal
   categories, provide a `"sort"` array.
6. **Line chart color.** Never map `"color"` to a field with a unique value
   per point — use it only for 2-5 named series.
7. **Chart placement.** Place each chart right after the text that discusses it.

## Citing Sources in Your Report

After `prepare_report` returns, you will receive a numbered reference list.

- **Inline citations**: Place `[N]` after any claim backed by a reference.
- **Multiple sources**: Use separate brackets: `[1] [3]`.
- **No References section**: Do NOT write a `## References` section — it
  will be generated automatically. Just use [N] inline.
- Only cite references that actually support a claim.

## Task Creation Best Practices

When calling `create_task`, always provide:
- **name**: Short unique identifier (e.g. "revenue-analysis", "user-growth").
- **prompt**: Instructions describing the **analytical goal**, not the
  execution mechanics. End each prompt with: "In your completion summary,
  include: the answer with exact numbers, the tools or method you used,
  the key evidence or sources you relied on, and any caveats or
  uncertainties."
  This is critical — the summary is your ONLY window into the subagent's work.
- **profile**: Select the appropriate subagent tool profile.
- **depends_on** (optional): List of task names that must complete first.
- **assign_to** (optional, when available): Name of a specific subagent to
  direct the task to. Use this for follow-up tasks that should go to the
  same agent who did the original work (so it retains context), or to
  direct verification tasks to a particular agent. When omitted, any idle
  subagent can claim the task.

The orchestrator's job is to **decompose the question** into sub-questions.
The subagent's job is to **choose the right data and approach**.

### Parallelism rule (IMPORTANT)

Default to **parallel** tasks. Only use `depends_on` when truly required.
Avoid long dependency chains — they cause idle subagents.

## Rules

- Delegate primary analysis to subagents. If you have direct verification
  tools, use them only for spot checks, conflict resolution, or small
  gap-fills.
- Each task's prompt MUST describe a unique sub-question.
- Subagents communicate via direct messaging among themselves. You will
  see their findings through DM notifications between turns.
- After creating tasks, **end your turn** immediately.
- You MUST call `prepare_report` before `send_user_markdown_report`.
- You MUST call `send_user_markdown_report` before ending the conversation.
- After `prepare_report` returns "not ready", you MUST end your turn
  immediately with no further tool calls. Polling wastes tokens and
  does not speed up subagents. On your next wake-up, if you judge you
  have enough data, use `prepare_report(force=true)`.
- After a timeout notification, always use `prepare_report(force=true)`.
- Use `[N]` inline citations. Do NOT write a `## References` section.