Swarm Pipeline

Pipeline / Task Graph Orchestration

Overview

This skill is invoked by the swarm dispatcher. You should already have the goal, target, and selected roles from the dispatcher. If invoked directly, start from step 1.

Orchestrate sequential stages with dependency edges. Handles two config shapes:

• pattern: pipeline with stages array — linear chain where each stage blocks the next. Stages support multiple roles.
• pattern: task-graph with nodes map — arbitrary DAG with depends_on edges supporting fan-in and fan-out. Each node has a single role (not a list).

Pipeline is a degenerate task-graph (linear topology). Both use the same blocks/blockedBy primitives for automatic stage transitions.

When to Use

• Multi-stage workflows where output feeds the next stage
• Implementation + review chains
• Database migrations with dependent steps
• Any workflow with sequential dependencies

When NOT to Use

• All tasks are independent (use fan-out or swarm)
• Tasks need structured merging with a dedicated reducer (use map-reduce)
• Competing approaches (use speculative)

Checklist

You MUST complete these steps in order:

1. Identify goal and target
2. Read config and determine topology
3. Build dependency graph
4. Check for existing team
5. Confirm with user
6. Create team and tasks
7. Spawn agents
8. Relay context between stages
9. Collect findings
10. Synthesize and present report
11. Await user instructions
12. Shutdown and cleanup

Step 1: Identify Goal and Target

Determine from the user's request (or dispatcher context):

• Goal: What is being done?
• Target: Which files, directories, or scope?

If unclear, ask the user. Do not guess scope.

Step 2: Read Config and Determine Topology

Read $CLAUDE_PLUGIN_ROOT/config/swarm-roles.yaml to get the preset config.

Determine the topology:

• If preset has stages array → pipeline (linear chain)
• If preset has nodes map → task-graph (arbitrary DAG)

Validation

The dispatcher has already validated config shape (role existence, required fields, subagent_type values). The checks below cover pipeline/task-graph-specific semantics.

• Non-empty topology: pipeline must have at least 1 stage; task graph must have at least 1 node. If empty, report the error and abort.
• Non-empty stage roles: each stages[].roles list must contain at least 1 entry. A stage with no roles would block the relay indefinitely. If empty, report the error and abort.
• Single-stage warning: if a pipeline has exactly 1 stage, warn the user that this degenerates to fan-out but uses pipeline hook semantics (requiring commit or SendMessage instead of just SendMessage). Offer to switch to fan-out for simpler gating.
• No cycles (task-graph): validate that depends_on references do not create cycles. If cycles found, report the error and abort.
• Valid depends_on (task-graph): all depends_on entries must reference existing node names.

Step 3: Build Dependency Graph

For Pipeline (stages)

Convert the linear stages array into a dependency chain:

stage[0] → stage[1] → stage[2] → ...

Each stage blocks the next. Stages with multiple roles create parallel tasks within the stage (fan-out within a stage, sequential between stages).

For Task Graph (nodes)

Read each node's depends_on list to build the DAG:

analyze → migrate-users ──→ validate
       → migrate-orders ──↗

All graph validation (cycles, dangling references) was completed in step 2. This step is construction only — do not re-validate here.

Step 4: Check for Existing Team

Only one team can exist per session. Before creating a new team, check if one already exists.

If a team exists:

• Active swarm: warn the user that a swarm is already running and offer to shut it down first (TeamDelete).
• Orphaned team (from a crashed session or /resume): agents from the previous session are gone but the team and task list persist. Offer the user two options:
  1. Delete and restart: TeamDelete the orphaned team, then proceed with a fresh swarm.
  2. Salvage completed work: check TaskList for completed tasks, synthesize any available findings from completed tasks, then TeamDelete and optionally re-run incomplete tasks.

Step 5: Confirm with User

Present the dispatch plan using AskUserQuestion:

I'll dispatch a {pipeline|task-graph} with these stages:

Stage 1: {name} — {roles}
  ↓
Stage 2: {name} — {roles} (blocked by: stage 1)
  ↓
Stage 3: {name} — {roles} (blocked by: stage 2)

Target: {files/scope}

Proceed?

For task-graph, show the DAG structure with dependency arrows.

Do NOT spawn anything until the user confirms.

Step 6: Create Team and Tasks

Team Naming

• Pipeline: swarm-pipeline-{goal-slug}-{timestamp}
• Task Graph: swarm-task-graph-{goal-slug}-{timestamp}

Generate the timestamp from the current date/time as a Unix epoch.

Create Team

TeamCreate with team_name: "swarm-{topology}-{goal-slug}-{ts}"

Create Tasks

One task per role per stage/node via TaskCreate:

• subject: imperative title including stage name
• description: detailed scope, target, stage context, reporting expectations
• activeForm: present-continuous spinner label

Set dependencies via TaskUpdate:

• For pipeline: each stage's tasks have addBlockedBy pointing to the previous stage's tasks
• For task-graph: each node's tasks have addBlockedBy matching the node's depends_on references

First stage / root nodes have no blockers — they start immediately.

Relay tasks — one per stage transition via TaskCreate:

• subject: "Relay stage {N} findings to stage {N+1}"
• description: "Collect findings from stage {N} agents, forward to stage {N+1} agents via SendMessage, wait for acknowledgment"
• activeForm: "Relaying stage {N} findings"
• addBlockedBy: all task IDs from stage N — relay auto-unblocks when the source stage completes
• Relay tasks for stage N+1 should be added to the addBlockedBy list of stage N+1's agent tasks (in addition to stage N's tasks)

This makes relay a visible, trackable step in the task list. The lead claims and completes relay tasks as part of step 8.

Step 7: Spawn Agents

For each role in each stage/node, spawn one agent via Agent with:

• team_name: the team name from step 6
• name: {stage-name}-{role-name} (e.g., implement-implementer)
• subagent_type: from the role config
• model: from the role config (if specified)
• isolation: from the role config (if specified — see isolation handling below)
• run_in_background: true
• prompt: composed from the parts below

Isolation Handling

Before spawning, check each role's isolation field:

• If isolation: worktree is set:
  • Override subagent_type to general-purpose
  • Print a note: Role {name}: using general-purpose (worktree isolation requires write access)
  • Pass isolation: "worktree" to the Agent tool call
• If isolation is absent: use the role's subagent_type as-is

Prompt Construction

Part 1: Identity and Stage Instructions

Your name is {name}. You are part of team {team_name}.

You are working on stage "{stage-name}" of a {pipeline|task-graph}.

Instructions:
- Claim your task from TaskList, mark it in_progress, then
  completed when done.
- Send your findings to the team lead via SendMessage when
  complete.
- Include a summary field in your message (5-10 words).

Your task may be blocked by earlier stages. When it unblocks, do
NOT claim it immediately. Wait for the team lead to send you a
"start" message via SendMessage containing upstream findings.
Only claim your task and begin work AFTER receiving the lead's
start message.

First-stage agents (no blockers): claim your task immediately.

Part 2: Role Prompt

The prompt field from swarm-roles.yaml for this role.

Part 3: Goal, Target, and Upstream Context

## Goal

{goal description from user}

## Target

{target files, scope, or context}

## Upstream Context

{forwarded findings from completed predecessor stages — empty for
first stage, populated by lead relay in step 8}

{any additional context the user provided}

Step 8: Relay Context Between Stages

This is the lead's core responsibility in pipeline orchestration.

When a stage completes (all its tasks are done and agents have sent findings):

1. Collect all findings from that stage's agents
2. Create a relay task via TaskCreate:
   • subject: "Relay stage {N} findings to stage {N+1}"
   • description: summary of what to forward
   • activeForm: "Relaying stage findings"
   • addBlockedBy: all task IDs from the completed stage
3. Forward the findings to the next stage's agents via SendMessage — include the stage name and a summary of what was done. End the message with: "You may now claim your task and begin work."
4. Wait for each downstream agent to acknowledge receipt via SendMessage before marking the relay task completed
5. Mark the relay task as completed

Do NOT proceed to the next relay until downstream agents have acknowledged. If an agent does not acknowledge, nudge it.

Context Passing Mechanisms

• SendMessage relay (default): lead forwards findings between stages as messages
• Worktree chain (when roles have isolation: worktree): each stage works on the branch from the previous stage. The lead includes the branch name in the forwarded context so the next stage can check it out.

Step 9: Collect Findings

As each stage completes, its agents send findings via SendMessage. The lead accumulates findings across all stages.

Normal flow: stages complete sequentially (or per the DAG). Each stage's agents go idle after sending.

Error handling:

• Stage agent idle without findings: send a message asking for status
• Blocked task not unblocking: check if predecessor is truly complete, intervene if stuck
• Stage failure: notify user, ask whether to continue with remaining stages or abort

Step 10: Synthesize and Present Report

Once all stages are complete:

Synthesize findings into a unified report that shows the progression through stages.

Report Structure

## Pipeline Analysis Report

**Goal:** {goal}
**Target:** {target}
**Topology:** {pipeline|task-graph}

### Stage: {stage-1-name}
{findings from stage 1}

### Stage: {stage-2-name}
{findings from stage 2, including how they built on stage 1}

...

### Summary
{brief overall assessment — how the pipeline progressed and
final outcome}

Step 11: Await User Instructions

After presenting the report:

• Do NOT fix issues agents found
• Do NOT shut down the team automatically
• Do NOT proceed past reporting without user input

Wait for the user to decide next steps.

Step 12: Shutdown and Cleanup

When the user indicates they're done:

1. Send shutdown_request to each agent via SendMessage (include the monitor agent if watchdog: true was active)
2. Wait for shutdown_response from each. If an agent does not respond after a reasonable wait, send one nudge message. If still unresponsive, proceed — the agent may have crashed or terminated.
3. Call TeamDelete to clean up. TeamDelete is the authoritative cleanup mechanism — it will fail if active agents remain. If it fails, retry after unresponsive agents have timed out.

Design Constraints

• Sequential execution: stages run in dependency order
• Parallel within stages: multiple roles in one stage run concurrently
• Lead relays context: the lead is responsible for forwarding findings between stages
• One team per session: check before creating
• User controls lifecycle: never auto-shutdown