Swarm Workflow (IOSM)

A structured workflow for complex development tasks that combines PRD-driven planning, parallel subagent execution, and IOSM (Improve→Optimize→Shrink→Modularize) quality gates.

Quick Start

For new features/projects (Greenfield):

/swarm-iosm new-track "Add user authentication with JWT"

For existing codebases (Brownfield):

/swarm-iosm setup
/swarm-iosm new-track "Refactor payment processing module"

Check progress:

/swarm-iosm status

When to Use This Skill

Use Swarm Workflow when:

• Task requires multiple parallel work streams (exploration, implementation, testing, docs)
• Need formal PRD and decomposition for complex features
• Want structured reports and traceability ("who did what and why")
• Brownfield refactoring that needs careful planning and rollback strategy
• Team collaboration requiring artifact-based handoffs
• Quality gates (IOSM) are needed for acceptance

Don't use for:

• Simple single-file changes
• Quick bug fixes
• Exploratory tasks without implementation

Core Commands

/swarm-iosm setup

Initialize project context for Swarm workflow.

What it does:

1. Creates swarm/ directory structure
2. Generates project context files (product.md, tech-stack.md, workflow.md)
3. Initializes tracks.md registry

When to use: First time in a project, or when project context has significantly changed.

/swarm-iosm new-track "<description>"

Create a new feature/task track with PRD and implementation plan.

What it does:

1. Requirements gathering (AskUserQuestion for mode/priorities/constraints)
2. Generate PRD (swarm/tracks/<id>/PRD.md)
3. Create spec (spec.md) and plan (plan.md) with phases/tasks/dependencies
4. Identify subagent roles needed
5. Create metadata.json with track info

Arguments: Brief description of the feature/task (e.g., "Add OAuth2 authentication")

/swarm-iosm implement [track-id]

Execute the implementation plan using parallel subagents.

What it does:

1. Load plan from track
2. Identify parallelizable tasks vs. sequential chains
3. Launch subagents (suggests background for long-running, foreground for interactive)
4. Each subagent produces structured report in reports/
5. Monitor progress and collect outputs

Arguments: Optional track-id (defaults to most recent track)

/swarm-iosm status [track-id]

Show progress summary for a track.

What it does:

1. Parse plan.md for task statuses
2. List completed reports
3. Show blockers and open questions
4. Display dependency chain status

/swarm-iosm watch [track-id]

Open a live monitoring dashboard for a track. (v1.3)

What it does:

1. Calculates real-time metrics (velocity, ETA, progress %)
2. Renders an ASCII progress bar
3. Shows status of all tasks in the track
4. Refreshes data from reports and checkpoints

Example usage:

/swarm-iosm watch

/swarm-iosm simulate [track-id]

Run a dry-run simulation of the implementation plan. (v1.3)

What it does:

1. Loads implementation plan and resource constraints
2. Simulates dispatch loop with virtual time
3. Identifies bottlenecks and potential conflicts
4. Generates ASCII timeline and simulation report
5. Estimates total parallel execution time vs serial

Example usage:

/swarm-iosm simulate
/swarm-iosm simulate 2026-01-17-001

/swarm-iosm resume [track-id]

Resume an interrupted implementation from the latest checkpoint. (v1.3)

What it does:

1. Loads latest checkpoint from checkpoints/latest.json
2. Reconciles state by reading all report files in reports/
3. Identifies completed vs pending tasks
4. Recalculates the ready queue
5. Shows a summary of progress and next steps

Example usage:

/swarm-iosm resume
/swarm-iosm resume 2026-01-17-001

/swarm-iosm retry <task-id> [--foreground] [--reset-brief]

Retry a failed task with optional mode changes. (v1.2)

What it does:

1. Reads error diagnosis from task report using parse_errors.py
2. Shows error diagnosis to user with suggested fixes
3. Asks user to choose: apply fix, manual fix, or skip
4. Regenerates subagent brief with error context
5. Relaunches task using Task tool
6. Tracks retry count (max 3 per task)

Arguments:

• <task-id>: Task to retry (e.g., T04)
• --foreground: Force foreground execution (for interactive debugging)
• --reset-brief: Regenerate brief from scratch (vs. reuse existing)

Error-specific behaviors:

• Permission Denied: Always suggest --foreground
• MCP Tool Unavailable: Force foreground mode
• Import Error: Suggest pip install before retry
• Test Failed: Ask user: "Fix code or update tests?"

Example usage:

/swarm-iosm retry T04
/swarm-iosm retry T04 --foreground
/swarm-iosm retry T04 --reset-brief

Inter-Agent Communication (v2.0)

Subagents can share knowledge via shared_context.md.

Protocol:

1. Subagent discovers a pattern (e.g., "Use schemas.py for all models").
2. Subagent writes to "Shared Context Updates" in their report.
3. Orchestrator runs merge_context.py to update shared_context.md.
4. Subsequent subagents read shared_context.md in their brief.

Example Report Update:

## Shared Context Updates
- [Error Handling]: Always wrap API calls in `try/except ApiError`.

/swarm-iosm integrate <track-id>

Collect subagent reports and create integration plan.

What it does:

1. Read all reports from swarm/tracks/<id>/reports/
2. Identify conflicts and resolution strategy
3. Generate integration_report.md with merge order
4. Run IOSM quality gates
5. Create iosm_report.md with gate results and IOSM-Index

/swarm-iosm revert-plan <track-id>

Generate rollback guide for a track (does not execute git revert).

What it does:

1. Analyze files touched (from reports)
2. Identify commits/changes to revert
3. Suggest checkpoint/branch strategy
4. Create rollback_guide.md with manual steps

Advanced Features (v2.0)

Task Dependencies Visualization (--graph)

Generate a Mermaid diagram of the task dependency graph.

Usage:

/swarm-iosm simulate --graph

Generates dependency_graph.mermaid.

Anti-Pattern Detection

The planner automatically checks for:

• Monolithic tasks (XL + many touches)
• Low parallelism (<1.2x speedup)
• Missing quality gates
• Circular dependencies

Warnings appear in simulate and validate output.

Template Customization

You can override standard templates by placing files in swarm/templates/.

Resolution Order:

1. swarm/templates/<name> (Project-specific)
2. .claude/skills/swarm-iosm/templates/<name> (Skill defaults)

Supported Templates:

• prd.md, plan.md, subagent_brief.md, subagent_report.md

Resource Constraints & Cost Control

Define limits in plan.md or metadata to prevent overload.

Defaults:

• Max Parallel Background: 6
• Max Parallel Foreground: 2
• Max Total: 8
• Cost Limit: $10.00

Model Selection:

• Auto-select: Haiku (read-only), Sonnet (standard), Opus (security/arch).

Instructions for Claude

ORCHESTRATOR RESPONSIBILITIES

CRITICAL: The main agent (Claude) acts as ORCHESTRATOR ONLY. You coordinate subagents but DO NOT do implementation work yourself.

MANDATORY RULES

✅ ORCHESTRATOR DOES:

1. Analyze & Plan

   • Parse plan.md and build dependency graph
   • Generate orchestration_plan.md with waves/critical path
   • Detect file conflicts and resolve scheduling

2. Launch Subagents

   • Create detailed briefs for each subagent (using templates)
   • Launch parallel waves in single message (multiple Task tool calls)
   • Default to background mode (unless interactive)
   • Pre-resolve all questions for background tasks

3. Monitor & Handle Blockers

   • Use /bashes to track background tasks
   • Resume stuck tasks in foreground if needed
   • Apply fallback strategy (retry → resume → recovery task)

4. **Integra