# am-will/swarms architecture

> Architecture diagram of the GitHub repository am-will/swarms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/am-will/swarms
- Repository: https://github.com/am-will/swarms

## Overview

Swarms is a set of agent-orchestration skills for planning software work and executing it in dependency-aware parallel waves. The documented main workflow starts with a user request, proceeds through codebase research, clarification, planning and review, then hands the plan to an orchestrator that launches subagents, checks their work and advances through waves. README evidence supports this workflow and the Context7 integration; the other skill files are present in the tree but their behavior is not documented in the available excerpts.

Main entry points: [`skills/swarm-planner/SKILL.md`](https://github.com/am-will/swarms/blob/main/skills/swarm-planner/SKILL.md) (Swarm Planner), [`skills/parallel-task/SKILL.md`](https://github.com/am-will/swarms/blob/main/skills/parallel-task/SKILL.md) (Orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Planning"]
  node_planner["Swarm Planner<br/>[SKILL.md]"]
  node_research["Codebase Research<br/>[SKILL.md]"]
  node_clarification["Clarifications<br/>[SKILL.md]"]
  node_dependency_plan["Dependency Plan<br/>[SKILL.md]"]
  node_plan_review["Plan Review<br/>[SKILL.md]"]
end

subgraph group_execution["Execution"]
  node_parallel_task["Parallel Task<br/>[SKILL.md]"]
  node_orchestrator["Orchestrator<br/>[SKILL.md]"]
  node_subagents["Subagents<br/>[SKILL.md]"]
  node_wave_execution["Wave Execution<br/>[SKILL.md]"]
  node_work_verification["Work Verification<br/>[SKILL.md]"]
end

subgraph group_extensions["Other Skills"]
  node_co_design["Co-design<br/>[SKILL.md]"]
  node_spark_parallel["Spark Parallel<br/>[SKILL.md]"]
  node_tmux_parallel["Tmux Parallel<br/>[SKILL.md]"]
  node_super_swarm["Super Swarm<br/>[SKILL.md]"]
  node_spark_super_swarm["Spark Super Swarm<br/>[SKILL.md]"]
end

node_user(("User"))
node_context7["Context7 MCP"]

node_user -->|"requests planning"| node_planner
node_planner -->|"researches codebase"| node_research
node_planner -.->|"fetches docs"| node_context7
node_planner -->|"asks questions"| node_clarification
node_planner -->|"produces plan"| node_dependency_plan
node_planner -->|"spawns review"| node_plan_review
node_user -->|"requests execution"| node_parallel_task
node_parallel_task -->|"coordinates work"| node_orchestrator
node_orchestrator -->|"parses tasks"| node_dependency_plan
node_orchestrator -->|"launches parallel"| node_subagents
node_orchestrator -->|"advances waves"| node_wave_execution
node_subagents -->|"returns summaries"| node_work_verification
node_orchestrator -->|"verifies work"| node_work_verification

click node_planner "https://github.com/am-will/swarms/blob/main/skills/swarm-planner/SKILL.md"
click node_research "https://github.com/am-will/swarms/blob/main/skills/swarm-planner/SKILL.md"
click node_clarification "https://github.com/am-will/swarms/blob/main/skills/swarm-planner/SKILL.md"
click node_dependency_plan "https://github.com/am-will/swarms/blob/main/skills/swarm-planner/SKILL.md"
click node_plan_review "https://github.com/am-will/swarms/blob/main/skills/swarm-planner/SKILL.md"
click node_parallel_task "https://github.com/am-will/swarms/blob/main/skills/parallel-task/SKILL.md"
click node_orchestrator "https://github.com/am-will/swarms/blob/main/skills/parallel-task/SKILL.md"
click node_subagents "https://github.com/am-will/swarms/blob/main/skills/parallel-task/SKILL.md"
click node_wave_execution "https://github.com/am-will/swarms/blob/main/skills/parallel-task/SKILL.md"
click node_work_verification "https://github.com/am-will/swarms/blob/main/skills/parallel-task/SKILL.md"
click node_co_design "https://github.com/am-will/swarms/blob/main/skills/co-design/SKILL.md"
click node_spark_parallel "https://github.com/am-will/swarms/blob/main/skills/parallel-task-spark/SKILL.md"
click node_tmux_parallel "https://github.com/am-will/swarms/blob/main/skills/parallel-task-tmux/SKILL.md"
click node_super_swarm "https://github.com/am-will/swarms/blob/main/skills/super-swarm/SKILL.md"
click node_spark_super_swarm "https://github.com/am-will/swarms/blob/main/skills/super-swarm-spark/SKILL.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_planner,node_research,node_clarification,node_dependency_plan,node_plan_review,node_user toneBlue
class node_parallel_task,node_orchestrator,node_subagents,node_wave_execution,node_work_verification toneAmber
class node_co_design,node_spark_parallel,node_tmux_parallel,node_super_swarm,node_spark_super_swarm toneMint
class node_context7 toneIndigo
```

## Components

### Planning

- [Swarm Planner](https://github.com/am-will/swarms/blob/main/skills/swarm-planner/SKILL.md): `skills/swarm-planner/SKILL.md`
- [Codebase Research](https://github.com/am-will/swarms/blob/main/skills/swarm-planner/SKILL.md): `skills/swarm-planner/SKILL.md`
- [Clarifications](https://github.com/am-will/swarms/blob/main/skills/swarm-planner/SKILL.md): `skills/swarm-planner/SKILL.md`
- [Dependency Plan](https://github.com/am-will/swarms/blob/main/skills/swarm-planner/SKILL.md): `skills/swarm-planner/SKILL.md`
- [Plan Review](https://github.com/am-will/swarms/blob/main/skills/swarm-planner/SKILL.md): `skills/swarm-planner/SKILL.md`

### Execution

- [Parallel Task](https://github.com/am-will/swarms/blob/main/skills/parallel-task/SKILL.md): `skills/parallel-task/SKILL.md`
- [Orchestrator](https://github.com/am-will/swarms/blob/main/skills/parallel-task/SKILL.md): `skills/parallel-task/SKILL.md`
- [Subagents](https://github.com/am-will/swarms/blob/main/skills/parallel-task/SKILL.md): `skills/parallel-task/SKILL.md`
- [Wave Execution](https://github.com/am-will/swarms/blob/main/skills/parallel-task/SKILL.md): `skills/parallel-task/SKILL.md`
- [Work Verification](https://github.com/am-will/swarms/blob/main/skills/parallel-task/SKILL.md): `skills/parallel-task/SKILL.md`

### Other Skills

- [Co-design](https://github.com/am-will/swarms/blob/main/skills/co-design/SKILL.md): `skills/co-design/SKILL.md`
- [Spark Parallel](https://github.com/am-will/swarms/blob/main/skills/parallel-task-spark/SKILL.md): `skills/parallel-task-spark/SKILL.md`
- [Tmux Parallel](https://github.com/am-will/swarms/blob/main/skills/parallel-task-tmux/SKILL.md): `skills/parallel-task-tmux/SKILL.md`
- [Super Swarm](https://github.com/am-will/swarms/blob/main/skills/super-swarm/SKILL.md): `skills/super-swarm/SKILL.md`
- [Spark Super Swarm](https://github.com/am-will/swarms/blob/main/skills/super-swarm-spark/SKILL.md): `skills/super-swarm-spark/SKILL.md`

### Other components

- **User**
- **Context7 MCP**

## Connections

- User → Swarm Planner: requests planning (evidence: `README.md`)
- Swarm Planner → Codebase Research: researches codebase (evidence: `README.md`)
- Swarm Planner → Context7 MCP: fetches docs (evidence: `README.md`)
- Swarm Planner → Clarifications: asks questions (evidence: `README.md`)
- Swarm Planner → Dependency Plan: produces plan (evidence: `README.md`)
- Swarm Planner → Plan Review: spawns review (evidence: `README.md`)
- User → Parallel Task: requests execution (evidence: `README.md`)
- Parallel Task → Orchestrator: coordinates work (evidence: `README.md`)
- Orchestrator → Dependency Plan: parses tasks (evidence: `README.md`)
- Orchestrator → Subagents: launches parallel (evidence: `README.md`)
- Orchestrator → Wave Execution: advances waves (evidence: `README.md`)
- Subagents → Work Verification: returns summaries (evidence: `README.md`)
- Orchestrator → Work Verification: verifies work (evidence: `README.md`)
