swarm-iosm

Swarm-IOSM

Parallel Orchestration Engine for Claude Code with Built-in Quality Gates

Features • Quick Start • Architecture • Documentation • Use Cases • Contributing

---

🎯 What is Swarm-IOSM?

Swarm-IOSM is an advanced orchestration engine for Claude Code that transforms complex development tasks into coordinated parallel work streams with enforced quality standards.

It implements the IOSM methodology (Improve → Optimize → Shrink → Modularize) as an executable system for parallel AI agent coordination, combining:

• 🤖 Intelligent Orchestration — Continuous dispatch scheduling with dependency analysis
• 🔒 File Conflict Detection — Lock management prevents parallel write conflicts
• 📋 PRD-Driven Planning — Structured requirements → decomposition → execution
• ✅ IOSM Quality Gates — Automated code quality, performance, and modularity checks
• 🔄 Auto-Spawn Protocol — Dynamic task discovery and creation during execution
• 📊 Cost Tracking — Budget guardrails with usage monitoring

Core Model: Touches → Locks → Gates → Done

A correctness model for parallel agent work: declare what files you touch, acquire locks to prevent conflicts, pass quality gates, ship.

Why Swarm-IOSM?

Traditional development workflows struggle with:

• Sequential bottlenecks — One task blocks the next, wasting time
• Context loss — Large features lack structured documentation
• Quality debt — No systematic enforcement of engineering standards
• Manual coordination — Developers spend time orchestrating instead of building

Swarm-IOSM solves these by:

• Parallelizing independent work streams (commonly 3–8x faster than sequential, depends on task independence)
• Enforcing IOSM quality gates before merge
• Automating task decomposition and subagent coordination
• Tracking all decisions and artifacts for full traceability

What Swarm-IOSM is NOT

To set clear expectations:

• ❌ Not a general-purpose workflow engine — Designed specifically for Claude Code agent orchestration
• ❌ Not a replacement for CI/CD — Complements your pipeline, doesn't replace Jenkins/GitHub Actions
• ❌ Not a code generator "autopilot" — Requires human oversight and decision-making
• ❌ Not safe to run unattended on production repos — Always review changes before merge

---

⚡ 60-Second Demo

# Install
git clone https://github.com/rokoss21/swarm-iosm.git .claude/skills/swarm-iosm

# In Claude Code
/swarm-iosm setup
/swarm-iosm new-track "Add JWT authentication"

What you get:

• swarm/tracks/<id>/PRD.md — Requirements document
• swarm/tracks/<id>/plan.md — Task breakdown with dependencies
• swarm/tracks/<id>/reports/ — Subagent execution reports (after /swarm-iosm implement)
• swarm/tracks/<id>/integration_report.md — Merge plan & results
• swarm/tracks/<id>/iosm_report.md — Quality gate evaluation

See complete example: examples/demo-track/ — Full track from PRD to merge (7 tasks, Redis caching feature)

---

🌟 Key Features

Core Capabilities

Feature	Description	Benefits
Continuous Dispatch Loop	Tasks launch immediately when dependencies are met	No artificial wave barriers, maximum parallelism
Parallel Subagent Execution	Up to 8 simultaneous background/foreground agents	Often 3-8x faster than sequential execution
IOSM Quality Gates	Automated checks for code quality, performance, complexity	Quality-gated before merge
File Lock Management	Hierarchical conflict detection (file/folder)	Safe parallel writes, prevents merge conflicts
Auto-Spawn from Discoveries	Subagents report new work → orchestrator schedules	Self-organizing workflow adaptation
Intelligent Error Recovery	Pattern-based diagnosis with suggested fixes	Auto-diagnosis with 3 retry limit
Cost & Budget Control	Token usage tracking with budget guardrails	Predictable API costs (default: $10 limit)
Checkpoint & Resume	Crash recovery from last known state	Fault-tolerant long-running tasks

Feature Status

Feature	Status	Command/Location
✅ Inter-Agent Communication	Available in v2.0+	shared_context.md auto-updated
✅ Task Dependency Visualization	Available in v2.0+	--graph flag in orchestration planner
✅ Anti-Pattern Detection	Available in v2.0+	Auto-warns during planning
✅ Template Customization	Available in v2.0+	Override in swarm/templates/
✅ Simulation Mode	Available in v1.3+	/swarm-iosm simulate
✅ Checkpoint & Resume	Available in v1.3+	/swarm-iosm resume
🧪 Live Monitoring	Experimental	/swarm-iosm watch (basic implementation)
🗺️ IDE Integration	Roadmap	VS Code extension planned
🗺️ CI/CD Templates	Roadmap	GitHub Actions / GitLab CI examples

---

🏗️ Architecture

System Overview

┌──────────────────────────────────────────────────────────────────────┐
│                    ORCHESTRATOR (Main Claude Agent)                  │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │              Continuous Dispatch Loop (v1.1+)                   │ │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐ │ │
│  │  │ Collect  │→ │ Classify │→ │ Conflict │→ │ Dispatch Batch   │ │ │
│  │  │  Ready   │  │  Modes   │  │  Check   │  │ (max 3-6 tasks)  │ │ │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────────────┘ │ │
│  │       ↑                                           │             │ │
│  │       │        ┌──────────┐  ┌──────────┐         ↓             │ │
│  │       └────────│  IOSM    │←─│ Auto-    │←────────┘             │ │
│  │                │  Gates