parallel-fanout

name	parallel-fanout
description	Decompose a task into 2+ truly independent sub-tasks and dispatch them concurrently via separate `task()` calls. Pick whether to fan out explicitly, not by accident. USE WHEN: the user task is clearly decomposable into 2+ independent sub-tasks (independent files, independent probes, independent analyses), you would otherwise serialize work that has no real dependency, user said "in parallel" / "并行" / "fan out" / "spawn agents" / "同时跑". TRIGGER PHRASES: "in parallel", "parallel", "fan out", "spawn agents", "并行", "同时", "concurrent", "subagents", "multi-agent", "同时跑几个". SKIP WHEN: sub-tasks have a hard data dependency (output of A is input of B), the user explicitly said "sequential" / "one at a time", there is only one sub-task.
license	Apache-2.0
compatibility	Targets MiniMax Code 0.2.4 `task` tool. Verified against the bundled `cli.js` schema. Each sub-task is a separate `task()` call with its own `description` / `prompt` / `agent_name`. `agent_name` is canonical (`explore` / `worker` / `verifier`); `mavis` is the root agent, not a sub-agent.
metadata	{"author":"antianqi","version":"1.2.0","inspired-by":"https://github.com/openai/codex/blob/main/codex-rs/core/src/thread_manager.rs (design principle); the fan-out decision and wait-for-all aggregation are portable; on mcode each sub-task is a discrete `task()` call","changes-from-v1.1.0":"Replaced `subagent_type=` with the canonical mcode `agent_name=`. Replaced `brief=` with `prompt=`. Dropped `mavis` from the sub-agent list (mavis is the root). Dropped the Codex-harness pseudocode block; mcode 0.2.4 is the only shape shown. The 'concurrency cap' step now references mcode's own per-session buffer-unordered limit instead of a hypothetical host config."}

Parallel Fanout

When the user task is clearly decomposable into 2+ truly independent sub-tasks, the agent has two choices:

1. Serialize: do them one by one, holding the conversation hostage.
2. Fan out: dispatch them concurrently, aggregate the results.

This Skill is about knowing when to choose (2) and how to dispatch + aggregate cleanly so the user gets the parallel speedup without losing correctness.

mcode 0.2.4 surface

Each sub-task is a separate task() call:

task(
  description:    string,            // 3-5 word label, required
  prompt:         string,            // the brief, required
  agent_name:  "explore" | "worker" | "verifier",  // required
  run_in_background?: boolean        // optional; usually false for fan-out
)

The agent dispatches all the calls in a single response; mcode executes them concurrently subject to the host's per-session buffer-unordered limit (8 by default in 0.2.4; check the runtime config if unsure). The agent then waits for all to complete before aggregating.

agent_name is the canonical mcode spelling. agent_name= is accepted as a runtime alias but the Skills prefer canonical. mavis is the root agent not a sub-agent; do not pass it as agent_name.

When to use

Activate when any of these is true:

• The user task is clearly decomposable into 2+ independent sub-tasks.
• The sub-tasks touch independent files / directories / systems (so there is no shared state to corrupt).
• The user explicitly said "in parallel" / "并行" / "fan out" / "同时".
• You would otherwise serialize work that has no real dependency.

When NOT to use

• The sub-tasks have a hard data dependency (output of A is the input of B).
• The user explicitly said "sequential" / "one at a time" / "按顺序".
• There is only one sub-task (no fan-out to do).
• The sub-tasks would all touch the same file (race condition risk).

Process

1. Decompose explicitly. Write the list of sub-tasks in the brief header before dispatching anything. "Sub-tasks: A, B, C" is the single most important line.
2. For each sub-task, decide context size (see fork-context-decision Skill):
   • Self-contained sub-task? none (just the brief in prompt).
   • Needs prior context? N or all → inline the prior content into prompt.
3. Check mcode's per-session buffer-unordered limit. Default in 0.2.4 is 8 concurrent task calls. If you have more sub-tasks, the host will queue or fail — split the batch or use run_in_background: true and poll task_output later.
4. Dispatch the batch in a single response. mcode runs them concurrently subject to the buffer-unordered limit.
5. Wait for all to complete. The aggregator MUST verify each sub-task's output before declaring success (use completion-audit).
6. Surface the parallelism in the user-facing message. "I dispatched 3 sub-agents in parallel; here are their results." The user should know fan-out actually happened (vs serial).

Output contract

After activating this Skill, the agent's next message MUST include:

• The list of sub-tasks dispatched (one per task call).
• The chosen context level per sub-task.
• The aggregation result (per-sub-task outcome + overall verdict).
• A completion audit step (each sub-task verified).

Common pitfalls

• Fanning out for the sake of it — parallelism is a tool, not a goal. If two sub-tasks are easier to do serially, do them serially.
• Missing the data dependency — the most common bug. Always check: does sub-task B actually need sub-task A's output? If yes, serialize.
• Hitting mcode's buffer-unordered limit silently — the host will queue or fail. Check the limit first; if you have more than 8, run them in waves.
• Aggregating without verification — one sub-task may have silently failed. Always read each output.
• Using agent_name="mavis" — mavis is the root, not a sub-agent. Use explore / worker / verifier.
• Writing the sub-task brief in a separate brief= field — mcode 0.2.4 has no brief field. The brief goes in prompt.

Example

The example below is MiniMax Code 0.2.4 task tool syntax. The fan-out is 3 sub-tasks, all none context, all dispatched in one response, mcode runs them concurrently.

# Sub-tasks: A, B, C
# Concurrency cap: 8 (mcode 0.2.4 default)
# Context level: none (all sub-tasks are self-contained)
# Aggregation: read each output, run completion-audit, then summarize

> task(
    description="Look up X in repo 1",
    agent_name="explore",
    prompt="""
      Task name: lookup-X-repo1
      Task:     Find every file in <repo1> that imports `X`.
      Return:   List of <repo1>/<path> files, one per line.
    """
  )

> task(
    description="Look up Y in repo 2",
    agent_name="explore",
    prompt="""
      Task name: lookup-Y-repo2
      Task:     Find every file in <repo2> that imports `Y`.
      Return:   List of <repo2>/<path> files, one per line.
    """
  )

> task(
    description="Look up Z in repo 3",
    agent_name="explore",
    prompt="""
      Task name: lookup-Z-repo3
      Task:     Find every file in <repo3> that imports `Z`.
      Return:   List of <repo3>/<path> files, one per line.
    """
  )

# (Agent waits for all three.)
# Aggregator reads each output, audits per `completion-audit`.

The decision (3 sub-tasks, none context, wait-for-all) is the same; the call shape is what mcode 0.2.4 actually exposes.

Verification checklist

• Did you write the sub-task list in the brief header before dispatching?
• Did you stay under mcode's per-session buffer-unordered limit (default 8)?
• Did you choose the right context level per sub-task (via fork-context-decision)?
• Did you wait for all sub-tasks to complete before aggregating?
• Did you verify each sub-task's output (via completion-audit)?
• Did you use agent_name from {explore, worker, verifier} (not mavis)?
• Did you put the sub-task brief in the prompt field (not a separate brief)?