Swarm Iosm

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. 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 (<5 min) meta-work (e.g., add entry to tracks.md), orchestrator MAY do it. But if it's real logic/code → delegate.

ORCHESTRATION WORKFLOW

Phase 0: Requirements Intake
    ↓
Phase 1: PRD Generation
    ↓
Phase 2: Decomposition & Planning (create plan.md)
    ↓
[NEW] Phase 2.5: Orchestration Planning ← AUTOMATIC
    ↓
Phase 3: Subagent Execution (CONTINUOUS DISPATCH) ← v1.1
    ↓
Phase 4: Integration & IOSM Gates
    ↓
Phase 5: Deployment Prep

CONTINUOUS DISPATCH LOOP (v1.1 — MANDATORY)

Ключевое изменение v1.1: Оркестратор работает в режиме continuous scheduling — как только задача становится READY, она запускается немедленно, без ожидания "конца волны".

Главный принцип

"Работай в режиме 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 (внутренний трекинг)

Правило: Если задача стала 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)
• Использовать относительные пути от корня проекта

Пример проверки конфликта:

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/<id>/scratch/
3. Использовать флаги --dry-run, --check где возможно

scratch_dir правило:

swarm/tracks/<track-id>/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:

## 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 формат: <primary_touch>|<intent_category>

• Используется для дедупликации одинаковых кандидатов от разных воркеров

Оркестратор обязан:

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 отслеживать:

## 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

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

(D) Anti-Loop Protection

## 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: Calculated from Effort field (S=5k, M=20k, L=50k, XL=100k tokens)
• Actual: Sum of tokens reported by subagent (if available) or estimate if not

Budget Control:

• Default limit: $10.00 per track
• Warn @ 80% ($8.00): Notify user
• Stop @ 100% ($10.00): Pause execution, ask user to increase budget or prune tasks

Gate-Driven Continuation

Оркестратор продолжает LOOP пока не достигнуты Gate targets:

Обновлять iosm_state.md после каждого батча:

# IOSM State — [Track ID]

**Updated:** 2026-01-17 15:30
**Status:** IN_PROGRESS

## Gate Targets (from plan.md)
- Gate-I: ≥0.75 (current: 0.68) ❌
- Gate-M: pass (current: pass) ✅
- Gate-O: tests pass (current: 3 failing) ❌
- Gate-S: N/A

## Auto-Spawn Queue
Based on gate gaps, auto-spawning:
- T15: "Improve naming clarity in core/calculator.py" (Gate-I gap)
- T16: "Fix 3 failing integration tests" (Gate-O gap)

## Blocking Questions (needs user)
- Q1: Should we fix test_natal_aspects.py or update expected values?

## Next Actions
Waiting for T15, T16 to complete. Then re-evaluate gates.

Правила продолжения:

• Если Gate-I ниже порога → auto-spawn "Improve clarity / reduce duplication"
• Если Gate-O не pass → auto-spawn "fix failing tests"
• Если Gate-M не pass → auto-spawn "remove circular import / clarify boundaries"
• Продолжать пока gates не достигнуты

Stop Conditions

Оркестратор ОБЯЗАН остановиться и спросить пользователя если:

1. Все remaining tasks = needs_user_input=true — нечего делать автономно
2. Противоречие — "fix code vs fix tests" без политики
3. High-risk — изменение бизнес-логики без источника/эталона
4. Scope creep — auto-spawn выходит за рамки PRD
5. Critical severity — SpawnCandidate с severity=critical

RETRY WORKFLOW (v1.2)

When user invokes /swarm-iosm retry <task-id>:

1. Load error diagnosis:

from parse_errors import parse_subagent_errors
report_path = Path(f"swarm/tracks/{track_id}/reports/{task_id}.md")
diagnoses = parse_subagent_errors(report_path, task_id)

2. Show diagnosis to user: Present each error with:

• Error type (e.g., "Permission Denied")
• Affected file
• Root reason
• Suggested fixes (from error diagnosis)

3. User chooses action: Use AskUserQuestion with options:

• "Apply suggested fix" (if automatic fix available)
• "Manual fix required" (user does it manually)
• "Skip and continue" (mark task as failed)

4. Regenerate brief: Create new brief with:

• All original brief content
• New "Previous Attempt" section:

## Previous Attempt (Failed)

This task was attempted before and failed with:

**Error:** Permission Denied
**File:** backend/migrations/001.sql
**Reason:** Database user lacks CREATE TABLE permission

**What was attempted:** Direct migration execution

**What to do differently:**
1. Grant permissions first, OR
2. Run as admin user, OR
3. Break into smaller steps

• New "Special Instructions" based on error type
• Error-specific context (files, commands, etc.)

5. Relaunch:

Task(
    subagent_type="iosm-engineering-agent",
    prompt=updated_brief,
    run_in_background=(not "--foreground" in user_command)
)

6. Update state:

• In iosm_state.md, mark task as RETRY_IN_PROGRESS
• Track retry_count in task metadata
• If retry_count >= 3, mark as PERMANENTLY_FAILED

Retry Limits

• Max 3 retries per task
• After 3rd failure: mark as PERMANENTLY_FAILED
• Requires manual intervention to proceed

Error-Specific Retry Strategies

Wave Checkpoints (не барьеры)

Waves остаются для отчётности и checkpoints, но НЕ для blocking:

Wave 1: [T01, T02] — checkpoint для Gate-I review
Wave 2: [T03, T04, T05] — checkpoint для Gate-M review
Wave 3: [T06, T07] — checkpoint для Gate-O review

Но: Если T03 завершился раньше T02, и T04 depends_on T03 — запускать T04 сразу, не ждать Wave 2 checkpoint.

PHASE 2.5: ORCHESTRATION PLANNING (AUTOMATIC)

Goal: Transform plan.md into executable orchestration_plan.md with waves, modes, conflict resolution.

When: After plan.md is created, before launching subagents.

Steps:

1. Validate plan.md has required fields:

   python .claude/skills/swarm-iosm/scripts/orchestration_planner.py swarm/tracks/<id>/plan.md --validate
   

   Check all tasks have:

   • Touches (files/folders)
   • Needs user input (true/false)
   • Effort (S/M/L/XL or minutes)

   If missing: Tasks without these fields CANNOT be auto-scheduled. Ask user to add them OR infer from context.

2. Generate orchestration plan:

   python .claude/skills/swarm-iosm/scripts/orchestration_planner.py swarm/tracks/<id>/plan.md --generate
   

   This creates swarm/tracks/<id>/orchestration_plan.md with:

   • Dependency graph
   • Critical path (longest path through dependencies)
   • Execution waves (parallel grouping)
   • File conflict matrix
   • Background readiness checklist
   • Time estimates (serial vs parallel)

3. Review with user: Show orchestration plan summary:

   Generated orchestration plan:
   - 5 waves (14 tasks total)
   - Wave 1: 1 task (Explorer, background)
   - Wave 2: 3 tasks parallel (Architects, foreground)
   - Wave 3: 3 tasks parallel (Implementers, background)
   - Wave 4: 3 tasks (Tests, background)
   - Wave 5: 3 tasks (Integration, mixed)
   
   Estimated time: 27-42h parallel (vs 60-80h serial)
   Speedup: ~1.8x
   
   Ready to execute? (yes/no)
   

4. Pre-resolve questions for background tasks: For each task marked needs_user_input: false but you suspect may need decisions:

   • Use AskUserQuestion NOW (before launching)
   • Document answers in subagent brief

   Example:

   Wave 3 has 3 background implementers.
   Before launching background tasks, let me clarify:
   
   [AskUserQuestion with 2-3 questions about API design, error handling, testing strategy]
   
   These answers will be included in subagent briefs so they can work autonomously.
   

Output: orchestration_plan.md ready, all questions resolved, ready for Phase 3 execution.

Phase 1: Requirements Intake (Universal)

When user invokes /swarm-iosm new-track or triggers this Skill:

1. Determine mode using AskUserQuestion:

   • Greenfield (new feature from scratch)
   • Brownfield (modify existing codebase)

2. If Brownfield: Suggest Plan mode first:

   "I recommend starting in Plan mode (read-only exploration) to safely analyze the codebase before making changes. Shall I proceed with Plan mode first?"
   

   • If yes: Use Task tool with Explore agent to map codebase
   • If no: Proceed with caution warnings

3. Gather requirements using AskUserQuestion for:

   • Priority: Speed / Quality / Cost
   • Change strictness: Safe (minimal changes) / Normal / Aggressive refactor
   • Test strategy: TDD (tests first) / Post-tests / Smoke only
   • Permissions: What tools/operations are allowed

4. Ask text questions for:

   • Goal: "What defines 'done' for this task? (1-2 sentences)"
   • Context: "Product/users/environment context?"
   • Constraints: "Tech stack, versions, deadlines, restrictions?"
   • Interfaces: "API/UI/CLI changes needed?"
   • Data: "Data sources, migrations, PII concerns?"
   • Risks: "What could go wrong?"
   • Definition of Done: "Tests? Docs? Deployment?"

5. Save intake to swarm/tracks/<track-id>/intake.md

Phase 2: PRD Generation

Using intake data, generate swarm/tracks/<track-id>/PRD.md following template:

# PRD: <Feature Name>
## 1. Problem
## 2. Goals / Non-goals
## 3. Users & Use-cases
## 4. Scope (MVP / Later)
## 5. Requirements
### Functional
### Non-functional
## 6. UX / API / Data
## 7. Risks & Mitigations
## 8. Acceptance Criteria
## 9. Rollout / Migration plan
## 10. IOSM Targets (Gates + expected index delta)

See templates/prd.md for detailed template.

Phase 3: Decomposition & Planning

From PRD, create spec.md and plan.md:

spec.md (Conductor-style):

• Context
• What / Why
• Constraints
• Out of scope
• Acceptance tests
• Artifacts to produce
• Rollback assumptions

plan.md (WBS with dependencies):

• Phases (0: Intake, 1: Design, 2: Implementation, 3: Verification, 4: Integration)
• Tasks with:
  • owner_role (Explorer/Architect/Implementer/TestRunner/etc)
  • depends_on (task IDs)
  • files_modules (scope)
  • acceptance criteria
  • artifacts (reports/T01.md, etc)
  • iosm_checks (which gates apply)
  • status (TODO/DOING/DONE/BLOCKED)

See templates/plan.md for structure.

Phase 3: Subagent Execution

Goal: Execute orchestration_plan.md using parallel waves of subagents.

CRITICAL: Launch subagents in PARALLEL WAVES, not one-by-one.

Standardized Subagent Roles

Use these predefined roles:

1. Explorer (brownfield analysis)

   • Tools: Read, Grep, Glob
   • Output: Architecture map, dependencies, test coverage, code style
   • When: Always for brownfield, before making changes

2. Architect (design decisions)

   • Tools: Read, Write (ADRs)
   • Output: ADR documents, interface contracts, API specs
   • When: Complex features, API changes, architectural decisions

3. Implementer-{A,B,C} (parallel implementation)

   • Tools: Read, Write, Edit, Bash (tests)
   • Output: Code changes, unit tests, implementation report
   • When: Independent modules that can be developed in parallel

4. TestRunner (verification)

   • Tools: Read, Bash, Write
   • Output: Test results, coverage report, failure analysis
   • When: After implementation, before integration

5. SecurityAuditor (security review)

   • Tools: Read, Grep, Bash (security scanners)
   • Output: Security findings, remediation suggestions
   • When: Auth/payment features, external APIs, data handling

6. PerfAnalyzer (performance review)

   • Tools: Read, Bash (profiling)
   • Output: Performance metrics, bottleneck analysis
   • When: Data processing, APIs, high-traffic features

7. DocsWriter (documentation)

   • Tools: Read, Write, Edit
   • Output: README updates, API docs, user guides
   • When: Public APIs, complex features, user-facing changes

Parallelization Rules:

✅ Parallel (can run simultaneously):

• Different modules/files with no shared state
• Independent research tasks (Explorer on different subsystems)
• Docs + Implementation (if API is stable)
• Multiple Implementers on separate components

❌ Sequential (must run in order):

• Tasks with dependencies (Architect → Implementer)
• Shared file modifications (two agents editing same file)
• Test → Fix → Re-test cycles

Background vs Foreground:

Use background (run_in_background: true in Task tool) when:

• Long-running operations (tests, builds, analysis)
• No user input needed (all questions resolved upfront)
• Permissions pre-approved
• Can tolerate "fire and forget" mode

Use foreground (default) when:

• Need user clarifications during execution
• Interactive debugging/problem-solving
• Permission escalations expected
• Results needed immediately for next step

IMPORTANT: Background subagents cannot use AskUserQuestion (tool call will fail). Resolve all questions BEFORE launching background tasks.

Background Limitations (CRITICAL)

Background subagents CANNOT reliably use:

Rule of thumb:

• Background = autonomous code/tests/read/local-only operations
• Foreground = MCP, external integrations, user decisions, risky operations

Pre-flight checklist for background tasks:

1. All questions pre-resolved in brief
2. No MCP tools required
3. No external API calls (or wrap with fallback)
4. No interactive permissions needed
5. Touches clearly defined (no surprises)

If task needs MCP or external calls → force foreground:

- **Needs user input:** true  ← even if technically "safe"
- **Note:** Requires MCP/external API, must run foreground

Step 1: Load Orchestration Plan

Read swarm/tracks/<id>/orchestration_plan.md to understand:

• How many waves
• Which tasks in each wave
• Which tasks are parallel vs sequential
• Which tasks are background vs foreground

Step 2: Execute Waves (ONE WAVE AT A TIME)

For each wave in the orchestration plan:

A. Prepare Subagent Briefs

For each task in the wave:

1. Generate brief using templates/subagent_brief.md

2. Fill in all sections:

   • Goal, Scope, Context
   • Dependencies (what previous tasks delivered)
   • Constraints (technical, performance, security)
   • Output contract (code + tests + report)
   • Verification steps
   • Acceptance criteria
   • Pre-resolved questions (for background tasks)
   • IOSM checks to pass

3. Include report template requirement:

   You MUST save report to: swarm/tracks/<id>/reports/<task-id>.md
   Use template: .claude/skills/swarm-iosm/templates/subagent_report.md
   

B. Launch Wave (CRITICAL: PARALLEL IN SINGLE MESSAGE)

For parallel tasks in wave:

Launch ALL tasks in wave SIMULTANEOUSLY using single message with multiple Task tool calls.

Example (Wave 3: 3 implementers):

I'm launching Wave 3 with 3 parallel implementers (all background):

[Single message with 3 Task tool calls]

Task 1 (T04 - Implementer-A):
- subagent_type: general-purpose
- description: Implement core business logic
- prompt: [Full brief for T04]
- run_in_background: true

Task 2 (T05 - Implementer-B):
- subagent_type: general-purpose
- description: Implement API endpoints
- prompt: [Full brief for T05]
- run_in_background: true

Task 3 (T06 - Implementer-C):
- subagent_type: general-purpose
- description: Implement data access layer
- prompt: [Full brief for T06]
- run_in_background: true

Monitoring: Use /bashes to track progress
Expected completion: 8-12 hours

NEVER launch tasks one-by-one if they can run parallel. ALWAYS use single message.

C. Monitor Progress

While wave is running:

1. Check background tasks periodically:

   /bashes
   

2. Check task output files (if provided):

   tail -n 50 /path/to/task/output/file
   

3. If task completes:

   • Verify report exists: swarm/tracks/<id>/reports/T##.md
   • Check acceptance criteria met
   • Mark status in plan.md: Status: DONE

4. If task blocks/fails:

   • Apply fallback strategy (see below)

D. Fallback Strategy (if subagent fails)

Scenario 1: Transient error (timeout, network)

• Action: Retry once automatically
• Command: Re-launch same brief

Scenario 2: Permission/question blocker

• Action: Resume in foreground
• How: Use TaskOutput to get task_id, then Task tool with resume parameter
• Example:

  Task blocked on permission for "run database migrations"
  → Resume in foreground, approve permission, continue
  

Scenario 3: Logic gap (unclear contract/spec)

• Action: Create recovery task
• Steps:
  1. Create new task for Architect: "Clarify [missing requirement]"
  2. Run Architect task (foreground)
  3. Update brief for blocked task
  4. Re-launch subagent

Scenario 4: Unrecoverable failure

• Action: Mark BLOCKED and continue
• Steps:
  1. Update plan.md: Status: BLOCKED(reason: ...)
  2. Save partial work in reports/T##-partial.md
  3. Add to integration report: "T## blocked, manual resolution needed"
  4. Continue with other waves (don't block entire workflow)

Step 3: Wave Completion Check

Before proceeding to next wave:

• All tasks in wave completed OR marked BLOCKED
• All reports saved to reports/
• No merge conflicts detected (if parallel edits)
• All acceptance criteria met (or exceptions documented)

If wave has blockers:

• Document in orchestration_plan.md (update Progress section)
• Decide: resolve now OR defer to integration phase

Step 4: Proceed to Next Wave

Repeat Step 2 for next wave.

Important:

• Respect dependencies: Wave N can only start when all Wave N-1 tasks are DONE or BLOCKED
• Update orchestration_plan.md with actual completion times (for future estimation)

Step 5: All Waves Complete

When all waves finished:

• Update plan.md: Status: Integration
• Proceed to Phase 4 (Integration & IOSM Gates)

PARALLEL LAUNCH EXAMPLES

Example 1: Wave 2 (3 foreground tasks)

Launching Wave 2 (Design phase) with 3 tasks:

[Single message with 3 Task calls, all foreground]

These tasks will run interactively (you'll see their prompts).
Expected: ~4-6 hours for slowest task (T01)

Example 2: Wave 3 (3 background tasks)

Launching Wave 3 (Implementation) with 3 background tasks:

[Single message with 3 Task calls, all run_in_background: true]

Monitor with: /bashes
Check outputs in: swarm/tracks/2026-01-17-001/reports/

Example 3: Mixed wave (2 parallel + 1 sequential)

Wave 4a: Launching 2 parallel tasks (T08, T10):

[Single message with 2 Task calls, background]

When T08 completes, I'll launch Wave 4b (T09 depends on T08).

Phase 4: Integration & IOSM Gates

After subagents complete:

1. Read all reports from swarm/tracks/<id>/reports/
2. Validate each report has required sections (see templates/subagent_report.md)
3. Identify conflicts:
   • File modification overlaps
   • Contradictory decisions
   • Dependency mismatches
4. Generate integration_report.md with:
   • What changed (by task)
   • Conflict resolutions
   • Merge order (respecting dependencies)
   • Final verification checklist
   • Rollback guide

See templates/integration_report.md.

IOSM Quality Gates Evaluation

After integration_report.md is complete, run IOSM gates on integrated result:

Gate-I (Improve):

• Semantic clarity ≥0.95 (clear naming, no magic numbers)
• Code duplication ≤5%
• Invariants documented
• All TODOs tracked

Gate-O (Optimize):

• P50/P95/P99 latency measured
• Error budget defined
• Basic chaos/resilience tests passing
• No obvious N+1 queries or memory leaks

Gate-S (Shrink):

• API surface reduced ≥20% (or justified growth)
• Dependency count stable or reduced
• Onboarding time ≤15min for new contributor

Gate-M (Modularize):

• Clear module contracts
• Change surface ≤20% (localized impact)
• Coupling/cohesion metrics acceptable
• No circular dependencies

Calculate IOSM-Index:

IOSM-Index = (Gate-I + Gate-O + Gate-S + Gate-M) / 4

Target: ≥0.80 for production merge.

Generate swarm/tracks/<id>/iosm_report.md with gate results.

See templates/iosm_gates.md for detailed criteria.

File Structure

The Skill creates this structure:

.claude/skills/swarm-iosm/     # Skill definition
  SKILL.md                      # This file
  templates/                    # Progressive disclosure templates
  scripts/                      # Validation/analysis scripts

swarm/                          # Project workflow data
  context/                      # Project-wide context
    product.md
    tech-stack.md
    workflow.md
  tracks/                       # Feature/task tracks
    <YYYY-MM-DD-NNN>/          # Track directory
      intake.md                 # Requirements intake
      PRD.md                    # Product requirements
      spec.md                   # Technical spec
      plan.md                   # Implementation plan
      metadata.json             # Track metadata
      reports/                  # Subagent reports
        T01.md
        T02.md
        ...
      integration_report.md     # Integration plan
      iosm_report.md           # Quality gate results
      rollback_guide.md        # Revert instructions (if needed)
  tracks.md                     # Track registry/index

Best Practices

1. Always resolve questions upfront - Background subagents can't ask questions
2. Use Plan mode for brownfield - Safe exploration before changes
3. Parallelize research, sequence implementation - Avoid file conflicts
4. Demand structured reports - Traceability and integration depend on it
5. Run IOSM gates before merge - Quality enforcement
6. Create rollback plans - Safety net for production changes
7. Use TodoWrite - Track overall Swarm workflow progress
8. Monitor background tasks - Use /bashes command

Common Patterns

Pattern 1: Greenfield Feature

/swarm-iosm new-track "Add email notification system"
→ Intake (quick, no repo analysis)
→ PRD + Plan generation
→ Parallel: Architect (API design) + DocsWriter (email templates)
→ Sequential: Implementer (core) → TestRunner → Integration

Pattern 2: Brownfield Refactor

/swarm-iosm setup
/swarm-iosm new-track "Refactor payment processing"
→ Plan mode: Explorer analyzes payment module
→ Architect creates migration plan
→ Parallel: Implementer-A (new code) + TestRunner (regression tests)
→ Integration with rollback guide

Pattern 3: Large Feature with Many Tasks

/swarm-iosm new-track "Multi-tenant architecture"
→ Generate plan with 15+ tasks
→ Phase 1: Sequential design (Architect → review)
→ Phase 2: Parallel implementation (3x Implementer background)
→ Phase 3: Sequential integration (merge → test → gates)

Troubleshooting

Background subagent fails with permission error:

• Resume in foreground: Find task in /bashes, get task ID, resume
• Pre-approve permissions: Use AskUserQuestion before launching

Reports missing or incomplete:

• Subagent brief must explicitly require report template
• Validate reports using scripts/summarize_reports.py

File conflicts during integration:

• Plan should minimize shared file edits
• Use git branches per subagent (advanced)
• Integration report must resolve conflicts manually

IOSM gates failing:

• Review gate criteria in templates/iosm_gates.md
• Some gates may be aspirational (document exceptions

…(truncated)