swarm

Swarm Mode

Recommended model tier: smart (opus) - this skill requires complex reasoning

Launch parallel agents, each working on a story through SDLC stages.

NON-NEGOTIABLE REQUIREMENTS

1. SDLC Pipeline is MANDATORY - Every story MUST go through all 5 stages: DESIGN → TEST → DEV → VERIFY → DOCS
2. Git Worktrees are MANDATORY - Each story agent MUST work in an isolated worktree
3. VERIFY failures trigger BUILD-FIX loop - If VERIFY fails, invoke /aide:build-fix and re-verify until passing
4. Swarm MUST conclude with /aide:worktree-resolve - All story branches must be merged before completion

Activation

swarm 3                              → 3 story agents (SDLC mode)
swarm stories "Auth" "Payments"      → Named stories
swarm 2 --flat                       → Flat task mode (legacy)

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│  ORCHESTRATOR (you)                                                      │
│  1. Decompose work into stories                                          │
│  2. Create worktree per story                                           │
│  3. Spawn story agent per worktree (subagent_type: general-purpose)     │
│  4. Monitor progress via TaskList (DO NOT create tasks yourself!)       │
│  5. Call /aide:worktree-resolve when all stories complete               │
└─────────────────────────────────────────────────────────────────────────┘
                              │
       ┌──────────────────────┼──────────────────────┐
       ▼                      ▼                      ▼
┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐
│ Story A Agent   │   │ Story B Agent   │   │ Story C Agent   │
│ (worktree-a)    │   │ (worktree-b)    │   │ (worktree-c)    │
├─────────────────┤   ├─────────────────┤   ├─────────────────┤
│ SDLC Pipeline:  │   │ SDLC Pipeline:  │   │ SDLC Pipeline:  │
│ [DESIGN]        │   │ [DESIGN]        │   │ [DESIGN]        │
│ [TEST]          │   │ [TEST]          │   │ [TEST]          │
│ [DEV]           │   │ [DEV]           │   │ [DEV]           │
│ [VERIFY]        │   │ [VERIFY]        │   │ [VERIFY]        │
│ [DOCS]          │   │ [DOCS]          │   │ [DOCS]          │
└─────────────────┘   └─────────────────┘   └─────────────────┘
        │                     │                     │
        └─────────────────────┼─────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  SHARED NATIVE TASKS (Claude Code TaskList)                             │
│  All agents can see, create, and update tasks                           │
│  Dependencies via blockedBy auto-manage stage ordering                  │
└─────────────────────────────────────────────────────────────────────────┘

Workflow

1. Story Decomposition

First, check for an existing plan from /aide:plan-swarm:

mcp__plugin_aide_aide__decision_get with topic="swarm-plan"

If a plan exists, use its stories directly — skip ad-hoc decomposition. The plan has already been validated for independence and acceptance criteria.

If no plan exists, break the work into independent stories/features:

## Stories

1. **Auth Module** - User authentication with JWT
2. **Payment Processing** - Stripe integration for subscriptions
3. **User Dashboard** - Profile management UI

Each story should be:

• Independent (can be developed in parallel)
• Complete (has clear boundaries)
• Testable (has acceptance criteria)

2. Create Git Worktrees

Each story agent gets an isolated workspace. Create worktrees using git commands:

git worktree add .aide/worktrees/story-auth -b feat/story-auth
git worktree add .aide/worktrees/story-payments -b feat/story-payments
git worktree add .aide/worktrees/story-dashboard -b feat/story-dashboard

Automatic Integration:

• Worktrees in .aide/worktrees/ are auto-discovered by AIDE hooks
• When agents spawn, their worktree path is auto-injected into context
• When agents complete, worktrees are marked as "agent-complete" (ready for merge)
• Worktree state is tracked in .aide/state/worktrees.json

Naming Convention:

• Use story-<name> as worktree directory name
• Use matching agent-<name> as agent_id when spawning
• Example: story-auth worktree → spawn with agent_id containing "auth"

If worktree creation fails:

1. Check if branch exists: git branch -a | grep feat/story-auth
2. Remove stale worktree: git worktree remove .aide/worktrees/story-auth --force
3. Prune refs: git worktree prune
4. Retry creation

3. Spawn Story Agents

Launch agents using the Task tool with subagent_type: "general-purpose" (required for Edit/Write access).

IMPORTANT: Task Ownership

• The ORCHESTRATOR does NOT create SDLC tasks
• Each SUBAGENT creates and manages its OWN tasks
• Orchestrator only monitors via TaskList

Each agent manages its own SDLC pipeline.

Task({
  subagent_type: "general-purpose",
  prompt: `You are a story agent working on: Auth Module

Worktree: /path/to/.aide/worktrees/story-auth
Story ID: story-auth
Agent ID: agent-auth

## Your Mission
Implement the Auth Module through the full SDLC pipeline.

## SDLC Pipeline
You will create and execute these stages IN ORDER:

### Stage 1: DESIGN
Use the /aide:design skill (or follow its workflow).
Output: Technical design with interfaces, decisions, acceptance criteria.

### Stage 2: TEST
Use the /aide:test skill.
Write failing tests based on acceptance criteria from DESIGN.

### Stage 3: DEV
Use the /aide:implement skill.
Make all tests pass with minimal implementation.

### Stage 4: VERIFY
Use the /aide:verify skill.
Run full test suite, lint, type check. Must all pass.

**IF VERIFY FAILS:**
1. Invoke /aide:build-fix to address failures
2. Re-run /aide:verify
3. Repeat until VERIFY passes
4. Only then proceed to DOCS

### Stage 5: DOCS
Use the /aide:docs skill.
Update documentation to match implementation.

## Task Management
Use native Claude Code task tools to track your progress:

1. Create all stage tasks upfront:
   TaskCreate: "[story-auth][DESIGN] Design auth module"
   TaskCreate: "[story-auth][TEST] Write auth tests" (blockedBy: DESIGN task)
   TaskCreate: "[story-auth][DEV] Implement auth" (blockedBy: TEST task)
   TaskCreate: "[story-auth][VERIFY] Verify auth" (blockedBy: DEV task)
   TaskCreate: "[story-auth][DOCS] Document auth" (blockedBy: VERIFY task)

2. As you start each stage:
   TaskUpdate: taskId=X, status=in_progress, owner=agent-auth

3. As you complete each stage:
   TaskUpdate: taskId=X, status=completed

## Coordination

**Messaging (MCP tools):**
- Send status: \`message_send\` with from=agent-auth, type="status", content="[DESIGN] complete"
- Send blocker: \`message_send\` with from=agent-auth, type="blocker", content="Need API schema"
- Check inbox: \`message_list\` with agent_id=agent-auth
- Acknowledge: \`message_ack\` with message_id=N, agent_id=agent-auth

**At each stage transition:**
1. Check messages via \`message_list\`
2. Acknowledge and act on any requests
3. Send \`status\` message with new stage

**Shared state (MCP + CLI):**
- Check decisions: \`mcp__plugin_aide_aide__decision_get\` (MCP read)
- Record decisions: \`./.aide/bin/aide decision set <topic> "<decision>"\` (CLI write)
- Share discoveries: \`./.aide/bin/aide memory add --category=discovery --tags=project:<name>,session:\${AIDE_SESSION_ID},source:discovered "<finding>"\` (CLI write)

**Binary location:** The aide binary is at \`.aide/bin/aide\`. If it's on your \`$PATH\`, you can use \`aide\` directly.

## Completion
When all 5 stages are complete:
1. Verify all tasks show completed
2. Ensure all changes are committed
3. Send completion message: \`message_send\` with from=agent-auth, type="completion"
4. Report: "Story complete: Auth Module"
\`
});

Mid-flight control

Once stories are launched, you can intervene without killing/restarting agents. All control writes go through aide agent and reach the subagent on its next tool call (worst case ≈ duration of an in-flight Bash/Edit). The signal hook (src/hooks/agent-signals.ts) gates on a subagent's parent_session being set — orchestrator/solo sessions see zero overhead.

• Inspect: ./.aide/bin/aide agent list --parent=$(./.aide/bin/aide reflect current-session) --json
• Halt cleanly: ./.aide/bin/aide agent halt <agent-id> --reason="repeated rustdoc — see new instinct" Next tool call is blocked with the reason surfaced to the model.
• Pause / resume: ./.aide/bin/aide agent pause <agent-id> then ./.aide/bin/aide agent resume <agent-id>. Paused agents can only call message_send/message_list/message_ack/state_get.
• Mid-flight instruction: ./.aide/bin/aide message send --from=orchestrator --to=<agent-id> --priority=high "scope drifted — focus on auth.ts only". Surfaced as additionalContext on the subagent's next tool call.
• Soft deadline: ./.aide/bin/aide agent deadline <agent-id> 30m — warns at < 5min remaining; halts at 0.

When to intervene vs. let it run: prefer letting agents finish a stage and review at the next checkpoint. Use mid-flight halt only for clearly-wrong directions (infinite loops, scope drift, depleted budget with no progress).

Monitor Progress

Use TaskList to see all story progress:

TaskList

Example output:

#10 [completed] [story-auth][DESIGN] Design auth module (agent-auth)
#11 [completed] [story-auth][TEST] Write auth tests (agent-auth)
#12 [in_progress] [story-auth][DEV] Implement auth (agent-auth)
#13 [pending] [story-auth][VERIFY] Verify auth [blocked by #12]
#14 [pending] [story-auth][DOCS] Document auth [blocked by #13]
#20 [in_progress] [story-payments][DESIGN] Design payment module (agent-payments)

5. Merge Results

When all stories complete, use /aide:worktree-resolve:

# Verify all tasks complete
TaskList  # Should show all [completed]

# Check for blockers (use MCP tool)
mcp__plugin_aide_aide__memory_list with category=blocker

# Merge worktrees
/aide:worktree-resolve

SDLC Stage Reference

Stage	Skill	Creates	Depends On
DESIGN	/aide:design	Interfaces, decisions, acceptance criteria	-
TEST	/aide:test	Failing tests	DESIGN
DEV	/aide:implement	Passing implementation	TEST
VERIFY	/aide:verify	Quality validation	DEV
DOCS	/aide:docs	Updated documentation	VERIFY

VERIFY → BUILD-FIX Loop

                    ┌──────────────┐
                    │    VERIFY    │
                    └──────┬───────┘
                           │
              ┌────────────┴────────────┐
              │                         │
           PASS                       FAIL
              │                         │
              ▼                         ▼
         ┌────────┐              ┌──────────────┐
         │  DOCS  │              │  BUILD-FIX   │
         └────────┘              └──────┬───────┘
                                        │
                                        └──────► back to VERIFY

If VERIFY fails:

1. /aide:build-fix to fix issues
2. Re-run /aide:verify
3. Repeat until passing
4. Then proceed to DOCS

Story Agent Instructions Template

When spawning story agents, include:

You are story agent [AGENT-ID] working in worktree [PATH].

## Story

[Story name and description]

## SDLC Pipeline

Execute these stages in order. For each stage:

1. Create task with TaskCreate (set blockedBy for dependencies)
2. Claim task with TaskUpdate (owner=your-id, status=in_progress)
3. Execute stage using appropriate skill
4. Mark complete with TaskUpdate (status=completed)

### Stage Tasks to Create

TaskCreate({
subject: "[STORY-ID][DESIGN] Design [feature]",
description: "Technical design with interfaces and acceptance criteria",
activeForm: "Designing [feature]"
})

TaskCreate({
subject: "[STORY-ID][TEST] Write tests for [feature]",
description: "Failing tests based on acceptance criteria",
activeForm: "Writing tests"
})
// ... set blockedBy to DESIGN task ID

TaskCreate({
subject: "[STORY-ID][DEV] Implement [feature]",
description: "Make tests pass with minimal code",
activeForm: "Implementing [feature]"
})
// ... set blockedBy to TEST task ID

TaskCreate({
subject: "[STORY-ID][VERIFY] Verify [feature]",
description: "Full test suite, lint, type check",
activeForm: "Verifying [feature]"
})
// ... set blockedBy to DEV task ID

TaskCreate({
subject: "[STORY-ID][DOCS] Document [feature]",
description: "Update documentation",
activeForm: "Documenting [feature]"
})
// ... set blockedBy to VERIFY task ID

## Coordination

**Messaging (MCP tools):**

- Send status: `message_send` with from=[AGENT-ID], type="status", content="[STAGE] complete"
- Send blocker: `message_send` with from=[AGENT-ID], type="blocker", content="description"
- Check inbox: `message_list` with agent_id=[AGENT-ID]
- Acknowledge: `message_ack` with message_id=N, agent_id=[AGENT-ID]

**At each stage transition:**

1. Check messages via `message_list`
2. Acknowledge and act on any requests
3. Send `status` message with new stage name

**Shared state:**

- Check existing decisions: `mcp__plugin_aide_aide__decision_get` (MCP read)
- Record new decisions: `./.aide/bin/aide decision set <topic> "<decision>"` (CLI write)
- Share discoveries: `./.aide/bin/aide memory add --category=discovery --tags=project:<name>,session:${AIDE_SESSION_ID},source:discovered "<finding>"` (CLI write)

## VERIFY Failure Handling

If VERIFY stage fails:

1. DO NOT proceed to DOCS
2. Invoke /aide:build-fix to address failures
3. Re-run /aide:verify
4. Repeat until VERIFY passes
5. Only then proceed to DOCS

## Completion

All stages must complete. When done:

1. All 5 tasks show [completed]
2. VERIFY must have passed (not skipped)
3. All changes committed to your worktree branch
4. Send completion: `message_send` with from=[AGENT-ID], type="completion", content="Story [STORY-ID] complete"
5. Report: "Story [STORY-ID] complete - ready for merge"

Flat Mode (Legacy)

For non-code tasks or simple work, use --flat:

swarm 3 --flat

This uses the original task-grabbing model without SDLC stages.

Coordination via aide

Messages (MCP tools — primary coordination mechanism):

# Send status update (broadcast)
message_send: from="agent-auth", type="status", content="[DESIGN] complete, starting TEST"

# Send direct message
message_send: from="agent-auth", to="agent-payments", type="request", content="Need payment API schema"

# Check inbox
message_list: agent_id="agent-auth"

# Acknowledge after reading
message_ack: message_id=42, agent_id="agent-auth"

Decisions (shared across agents):

# Write (CLI)
./.aide/bin/aide decision set "auth-strategy" "JWT with refresh tokens"

# Read (MCP) - use mcp__plugin_aide_aide__decision_get with topic="auth-strategy"

Memory (shared discoveries):

./.aide/bin/aide memory add --category=discovery --tags=project:<name>,session:${AIDE_SESSION_ID},source:discovered "User model needs email validation"

Memory Hygiene

When any agent stores memories (discoveries, blockers, session summaries), always:

1. Include source: tag — Use source:discovered for findings, source:inferred for deductions
2. Include scope tags — Add project:<name>,session:<id> (get project name from git remote or directory; session ID from $AIDE_SESSION_ID or $CLAUDE_SESSION_ID)
3. Verify codebase claims before storing — If a memory references a file, function, or path, confirm it exists first. See the memorise skill for the full verification workflow.
4. Never use scope:global unless storing a user preference

This applies to all memory add commands in agent prompts, coordination examples, and the orchestrator memory section above.

OpenCode Mode

OpenCode has native todowrite/todoread for per-agent progress tracking, and a task tool for spawning subagents. However, OpenCode's todos are session-private — they are NOT shared across agents. For multi-agent coordination, use aide tasks (MCP tools) as the shared task system.

Task System Roles (OpenCode)

System	Role	Scope
aide tasks (MCP: task_create, task_list, task_claim, task_complete)	Shared coordination — all agents see the same board	Cross-session, persistent
todowrite (native)	Personal progress tracking within each agent	Session-private, per-agent
aide messages (MCP: message_send, message_list)	Real-time coordination, status broadcasts, blockers	Cross-session

Setup

1. Create worktrees as normal (one per story)
2. Launch separate OpenCode terminal sessions, one per story
3. Each session works in its assigned worktree directory

Orchestrator Workflow

The orchestrator (human or primary session):

1. Decompose stories (use /aide:plan-swarm first)
2. Create worktrees
3. Create aide tasks for all SDLC stages upfront:

   task_create: title="[story-auth][DESIGN] Design auth module"
   task_create: title="[story-auth][TEST] Write auth tests"
   task_create: title="[story-auth][DEV] Implement auth"
   task_create: title="[story-auth][VERIFY] Verify auth"
   task_create: title="[story-auth][DOCS] Document auth"
   

4. Launch terminal sessions with instructions (include agent ID and story assignment)
5. Monitor progress via task_list (MCP tool) or ./.aide/bin/aide task list (CLI)
6. When all tasks show done, run /aide:worktree-resolve

Story Agent Workflow (OpenCode)

Each story agent follows the same SDLC pipeline. Use aide tasks for shared tracking and native todowrite for personal step-by-step progress:

## Per SDLC Stage:

1. Claim the stage task:
   task_claim: task_id=<id>, agent_id=agent-auth

2. Use todowrite for personal tracking:
   todowrite: [{"content": "Design interfaces for auth", "status": "in_progress", "priority": "high"}]

3. Execute the stage (use appropriate /aide: skill)

4. Complete the aide task:
   task_complete: task_id=<id>, result="Designed JWT auth with refresh tokens"

5. Send status message:
   message_send: from="agent-auth", type="status", content="[DESIGN] complete"

6. Check for messages from other agents:
   message_list: agent_id="agent-auth"

Note: aide tasks do not have blockedBy dependency chaining like Claude Code native tasks. Stage ordering is enforced by the SDLC pipeline instructions — each agent processes stages sequentially (DESIGN → TEST → DEV → VERIFY → DOCS).

Coordination (OpenCode)

# Shared task board — all agents see the same tasks
task_list                                          # View all tasks
task_list: status="pending"                        # View unclaimed work

# Messages — real-time coordination
message_send: from="agent-auth", type="status", content="[DESIGN] complete, starting TEST"
message_send: from="agent-auth", to="agent-payments", type="request", content="Need payment API schema"
message_list: agent_id="agent-auth"
message_ack: message_id=42, agent_id="agent-auth"

# State — supplementary progress tracking
./.aide/bin/aide state set "agent-auth:stage" "TEST"

# Decisions and discoveries — shared knowledge
mcp__plugin_aide_aide__decision_get with topic="auth-strategy"
./.aide/bin/aide decision set "auth-strategy" "JWT with refresh tokens"
./.aide/bin/aide memory add --category=discovery --tags=project:<name>,session:${AIDE_SESSION_ID},source:discovered "User model needs email validation"

Completion (MANDATORY STEPS)

Swarm completion checklist - ALL REQUIRED:

Step 1: Verify All Stories Complete

# Claude Code:
TaskList  # All story tasks must show [completed]

# OpenCode:
task_list  # All aide tasks must show [done]

• Every story must have completed all 5 SDLC stages
• No tasks should be [pending] or [in_progress]

Step 2: Check for Blockers

Use mcp__plugin_aide_aide__memory_list with category=blocker

• If blockers exist, resolve them before proceeding
• Use /aide:build-fix for any remaining build/test issues

Step 3: Final Verification

Run verification on each worktree:

cd .aide/worktrees/story-X && npm test && npm run build

• If any fail, invoke /aide:build-fix and re-verify

Step 4: Merge Worktrees (MANDATORY)

YOU MUST invoke /aide:worktree-resolve - this is not optional.

/aide:worktree-resolve

This skill will:

• Merge each story branch into main
• Handle any merge conflicts
• Clean up worktrees

Step 5: Record Session

Only after successful merge, record the swarm session (see Orchestrator Memory below).

Orchestrator Memory

After swarm completes, record the session using the CLI:

./.aide/bin/aide memory add --category=session --tags=swarm,sdlc,project:<name>,session:${AIDE_SESSION_ID},source:discovered "## Swarm: [Brief Description]

### Stories Completed
- Story A: [outcome]
- Story B: [outcome]
- Story C: [outcome]

### Key Decisions Made
- [decision]: [rationale]

### Files Changed
- [summary of changes per story]

### Merge Status
- [branches merged successfully / any conflicts]"