# Swarm Iosm

> Orchestrate complex development with AUTOMATIC parallel subagent execution, continuous dispatch scheduling, dependency analysis, file conflict detection, and IOSM quality gates. Analyzes task dependencies, builds critical path, launches parallel background workers with lock management, monitors progress, auto-spawns from discoveries. Use for multi-file features, parallel implementation streams, a…

- **Type:** Skill
- **Install:** `agentstack add skill-rokoss21-swarm-iosm-swarm-iosm`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [rokoss21](https://agentstack.voostack.com/s/rokoss21)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [rokoss21](https://github.com/rokoss21)
- **Source:** https://github.com/rokoss21/swarm-iosm
- **Website:** https://github.com/rokoss21/IOSM

## Install

```sh
agentstack add skill-rokoss21-swarm-iosm-swarm-iosm
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 ""`
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//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  [--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 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:**
```markdown
## Shared Context Updates
- [Error Handling]: Always wrap API calls in `try/except ApiError`.
```

### `/swarm-iosm integrate `
Collect subagent reports and create integration plan.

**What it does:**
1. Read all reports from `swarm/tracks//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 `
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:**
```bash
/swarm-iosm simulate --graph
```
Generates `dependency_graph.mermaid`.

### Anti-Pattern Detection
The planner automatically checks for:
- Monolithic tasks (XL + many touches)
- Low parallelism (` (Project-specific)
2. `.claude/skills/swarm-iosm/templates/` (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. **Integrate & Gate**
   - Collect all subagent reports
   - Resolve merge conflicts
   - Run IOSM quality gates
   - Generate `integration_report.md` and `iosm_report.md`

5. **Meta-work** (ONLY exception to "no implementation")
   - Update `plan.md` status
   - Fix metadata (`metadata.json`, `tracks.md`)
   - Resolve integration conflicts (merge reports)
   - Generate final reports/docs

#### ❌ ORCHESTRATOR NEVER DOES:

1. **Implementation work:**
   - ❌ Write application code (services, models, API, UI)
   - ❌ Write tests (unit, integration, performance)
   - ❌ Refactor existing code

2. **Analysis work:**
   - ❌ Explore codebase (that's Explorer's job)
   - ❌ Design architecture (that's Architect's job)
   - ❌ Run security scans (that's SecurityAuditor's job)

3. **Specialized work:**
   - ❌ Write documentation (that's DocsWriter's job)
   - ❌ Debug performance (that's PerfAnalyzer's job)

**Exception:** If a task is trivial ( **"Работай в режиме continuous scheduling: как только появляется READY задача без конфликтов touches и без needs_user_input — немедленно запускай её в background, даже если другие задачи ещё выполняются. После каждого батча собирай SpawnCandidates из отчётов и автоматически добавляй их в backlog. Продолжай цикл, пока не достигнуты заданные IOSM Gate targets."**   

### Continuous Orchestration Loop

```
LOOP (до достижения Gate targets):

  1. CollectReady()
     └─── Собрать задачи, у которых deps выполнены

  2. Classify()
     └─── Каждой задаче присвоить режим:
        - background: safe, no user input needed
        - foreground: needs user decision
        - blocked_user: needs_user_input=true, не можем авто-решить
        - blocked_conflict: touches пересекаются с running

  3. ConflictCheck()
     └─── Parallel launch ТОЛЬКО tasks без пересечения touches (для write)
     └─── Read-only tasks ВСЕГДА можно параллелить

  4. DispatchBatch()
     └─── Запустить READY tasks ОДНИМ СООБЩЕНИЕМ (max 3-6 per batch)
     └─── Приоритет: critical_path > high_severity_spawn > read-only_fillers
     └─── Каждый batch получает batch_id для трекинга
     └─── Не ждать "конца волны" — dispatch immediately

  5. Monitor()
     └─── Периодически читать outputs background tasks
     └─── Собирать SpawnCandidates из отчётов

  6. AutoSpawn()
     └─── Если найдены SpawnCandidates → создать новые tasks
     └─── Добавить в backlog и вернуться к шагу 1

  7. GateCheck()
     └─── Проверить условия Gate-I/M/O/S
     └─── Если достигнуты → остановиться + gate-report
     └─── Если нет → авто-spawn remediation tasks и продолжить

END LOOP
```

### Task States (внутренний трекинг)

| State | Описание |
|-------|----------|
| `backlog` | Все известные задачи |
| `ready` | Deps satisfied, можно запускать |
| `running` | Выполняется (background или foreground) |
| `blocked_user` | needs_user_input=true, ждёт решения |
| `blocked_conflict` | touches заняты другой running task |
| `done` | Завершена |

**Правило:** Если задача стала READY в момент, когда другие выполняются — **запускать сразу**, не ждать checkpoint.

### Touches Lock Manager

Для безопасного параллелизма оркестратор должен отслеживать "занятые" файлы:  

```
touches_lock: Set[path] = {}

При запуске task:
  1. Проверить: task.touches ∩ touches_lock == ∅ ?
  2. Если да → touches_lock.add(task.touches), запустить
  3. Если нет → blocked_conflict, ждать освобождения

При завершении task:
  1. touches_lock.remove(task.touches)
  2. Пересчитать ready_queue (кто разблокировался?)
```

**Правила конфликтов:**
- `read-only` задачи → **всегда параллельно** (не берут lock)
- `write-local` → параллельно если touches не пересекаются
- `write-shared` → строго последовательно

### Lock Granularity (v1.1.1)

**Иерархия конфликтов:**

```
Lock по ПАПКЕ (core/) конфликтует:
  ├── с любым lock внутри (core/a.py, core/b.py)
  └── с lock на саму папку (core/)

Lock по ФАЙЛУ (core/a.py) конфликтует:
  ├── только с тем же файлом
  └── с lock на родительскую папку (core/)
```

**Нормализация путей:**
- Всегда использовать `/` (forward slash)
- Убирать trailing slash (`core/` → `core`)
- Приводить к lowercase (для Windows)
- Использовать относительные пути от корня проекта

**Пример проверки конфликта:**
```python
def conflicts(lock_a: str, lock_b: str) -> bool:
    a, b = normalize(lock_a), normalize(lock_b)
    return a == b or a.startswith(b + '/') or b.startswith(a + '/')
```

### Read-Only Safety Rules

**Проблема:** "read-only" задачи могут случайно писать в cache, lockfiles, __pycache__.

**Решение:** read-only задачи ДОЛЖНЫ:
1. НЕ запускать команды, меняющие файлы (`npm install`, `pip install`)
2. Писать временные артефакты ТОЛЬКО в `swarm/tracks//scratch/`
3. Использовать флаги `--dry-run`, `--check` где возможно

**scratch_dir правило:**
```
swarm/tracks//scratch/   ← read-only tasks пишут сюда
  ├── T00_analysis.json
  ├── T03_coverage.xml
  └── ...
```

Эта папка НЕ требует lock и НЕ конфликтует ни с кем.

### Auto-Background Classification

Оркестратор автоматически классифицирует задачи:

**Auto-background** (safe, запускать без вопросов):
- Concurrency class = `read-only`
- Или `write-local` + `needs_user_input=false` + no policy conflicts
- effort >= M и нет choice points

**Auto-foreground** (нужен пользователь):
- Меняется API контракт/формат ответа
- Нужна "истина" (источники, бизнес-логика, астрология)
- Падают тесты и нужно решить "фиксить код или тест"
- High-risk изменения без тестов
- needs_user_input=true

### SpawnCandidates Protocol

Каждый субагент ОБЯЗАН писать в отчёте секцию `SpawnCandidates`:

```markdown
## SpawnCandidates

При работе обнаружены новые work items:

| ID | Subtask | Touches | Effort | User Input | Severity | Dedup Key | Accept Criteria |
|----|---------|---------|--------|------------|----------|-----------|-----------------|
| SC-01 | Fix missing type annotation in auth.py | `backend/auth.py` | S | false | medium | auth.py|type-annot | mypy passes |
| SC-02 | Clarify API contract for /natal/aspects | `docs/api_spec.yaml` | M | true | high | api_spec|contract | Contract approved |
```

**Dedup Key формат:** `|`
- Используется для дедупликации одинаковых кандидатов от разных воркеров

**Оркестратор обязан:**
1. После каждого task completion — читать SpawnCandidates
2. **Дедуплицировать** по dedup_key (первый wins)
3. Если `needs_user_input=false` и `severity != critical` → auto-spawn
4. Если `needs_user_input=true` → добавить в blocked_user queue
5. Прогнать новые tasks через планнер и dispatch

### Spawn Protection (v1.1.1)

**Защита от бесконечного размножения задач:**

#### (A) Spawn Budget

В `iosm_state.md` отслеживать:

```markdown
## Spawn Budget
- spawn_budget_total: 20
- spawn_budget_used: 7
- spawn_budget_remaining: 13
- spawn_budget_per_gate:
  - Gate-I: 5 (used: 2)
  - Gate-O: 8 (used: 3)
  - Gate-M: 4 (used: 2)
  - Gate-S: 3 (used: 0)
```

**Правила:**
- При исчерпании budget → STOP, спросить пользователя
- `severity=critical` игнорирует budget (всегда spawn)
- User может увеличить budget командой

#### (B) Dedup Rules

```python
def dedup_key(candidate) -> str:
    return f"{candidate.touches[0]}|{candidate.intent_category}"

# Оркестратор хранит:
seen_dedup_keys: Set[str] = set()

# При обработке SpawnCandidate:
if candidate.dedup_key in seen_dedup_keys:
    skip  # дубль
else:
    seen_dedup_keys.add(candidate.dedup_key)
    process(candidate)
```

#### (C) Severity Threshold

| Severity | Auto-spawn условие |
|----------|-------------------|
| `critical` | ВСЕГДА (даже если budget=0), STOP loop и alert |
| `high` | Если gate fail ИЛИ user запросил |
| `medium` | Если gate fail И budget > 0 |
| `low` | Только по явному запросу user |

#### (D) Anti-Loop Protection

```markdown
## Anti-Loop Metrics (in iosm_state.md)
- loops_without_progress: 0  # сбрасывается при любом task completion
- max_loops_without_progress: 3
- total_loop_iterations: 15
- max_total_iterations: 50
```

**Правило:** Если `loops_without_progress >= 3` → STOP, analyze why stuck

### Model Selection & Cost (v1.2)

**Model Selection Rules:**
- `haiku`: read-only tasks ($0.25/M tokens)
- `sonnet`: standard tasks, background automation ($3.00/M tokens)
- `opus`: security audits, critical architecture, user decisions ($15.00/M tokens)

**Cost Tracking:**
Orchestrator tracks cost in `iosm_state.md`:
- **Estimate:**

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [rokoss21](https://github.com/rokoss21)
- **Source:** [rokoss21/swarm-iosm](https://github.com/rokoss21/swarm-iosm)
- **License:** MIT
- **Homepage:** https://github.com/rokoss21/IOSM

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-rokoss21-swarm-iosm-swarm-iosm
- Seller: https://agentstack.voostack.com/s/rokoss21
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.