/team-swarm

name: team-swarm
disable-model-invocation: true
description: Swarm intelligence team skill — ACO-driven multi-agent exploration with hybrid LLM coordinator + Python optimization controller. Coordinator generates swarm-config from user task, then runs K iterations of N parallel ants guided by pheromone state. Universal task space via config (nodes + scoring rule). Triggers on "team swarm", "swarm intelligence", "蚁群".
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__maestro__team_msg(*)
session-mode: run
contract:
  contract_version: 2.1
  consumes: []
  produces:
    - {path: outputs/best-solution.md, kind: swarm-best-solution, schema: swarm-best-solution/1.0, role: primary, required: true}
    - {path: outputs/swarm-report.json, kind: swarm-report, schema: swarm-report/1.0, role: attachment, required: true}
    - {path: 'outputs/ant-{iteration}-{ant_id}.json', kind: swarm-ant-result, schema: swarm-ant-result/1.0, role: evidence, required: false}
  gates: {entry: [], exit: []}

<required_reading> @~/.maestro/workflows/run-mode-lite.md </required_reading>

Team Swarm

Orchestrate ant-colony-style exploration over a user-defined task space. **Hybrid coordinator**: LLM handles task translation + worker spawning; Python script owns all numeric decisions (selection / pheromone update / convergence). Universal — task space and scoring rule come from `swarm-config.json`.

Architecture

Skill(skill="team-swarm", args="task description")
                    |
         SKILL.md (this file) = Router
                    |
     +--------------+--------------+
     |                             |
  no --role flag              --role <name>
     |                             |
  Coordinator                  Worker
  roles/coordinator/role.md    roles/<name>/role.md
     |
     +-- Phase 1: gen swarm-config
     +-- Phase 2: init  --> Bash: scripts/aco.py init
     +-- Phase 3: iterate (K rounds, each = spawn-and-stop)
     |   |
     |   +-- Bash: aco.py select --iter k  -> N assignments
     |   +-- Spawn N x team-worker(ant)
     |   +-- [callback when all ants done]
     |   +-- (optional) Spawn team-worker(scorer)
     |   +-- Bash: aco.py update --iter k
     |   +-- Bash: aco.py converged
     |   +-- branch: loop k+1 OR Phase 4
     |
     +-- Phase 4: converge --> Bash: aco.py report -> Spawn team-worker(analyst)
                                                    -> best-solution.md

Role Registry

| Role | Path | Prefix | Inner Loop | |------|------|--------|------------| | coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — | | ant | [roles/ant/role.md](roles/ant/role.md) | ANT-* | false | | scorer | [roles/scorer/role.md](roles/scorer/role.md) | SCORE-* | false | | analyst | [roles/analyst/role.md](roles/analyst/role.md) | ANALYST-* | false |

Role Router

Parse `$ARGUMENTS`:

• Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
• No `--role` -> `@roles/coordinator/role.md`, execute entry router

Shared Constants

• **Session prefix**: `TS`
• **Session path**: `{run_dir}/work/team/`
• **Team name**: `swarm`
• **Script root**: `<skill_root>/scripts/aco.py` (Python 3.10+)
• **Message bus**: `mcp__maestro__team_msg(session_id=<run-id>, ...)`

Worker Spawn Template

Coordinator spawns workers using this template:

Agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker",
  team_name: "swarm",
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: {run_dir}/work/team
session_id: <run-id>
run_dir: <exact run_dir from the birth packet or team-session.json.run.run_dir>
team_name: swarm
requirement: <task-description>
inner_loop: false

## Assignment (ant only)
<assignment JSON from aco.py select>

## Progress Milestones
session_id: <run-id>
Report progress via team_msg at natural phase boundaries.
Report blockers immediately via team_msg type="blocker".
Report completion via team_msg type="task_complete" after final SendMessage.

Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})

User Commands

| Command | Action | |---------|--------| | `check` / `status` | View iteration progress + convergence curve | | `resume` / `continue` | Resume interrupted iteration | | `feedback <text>` | Inject feedback into wisdom; applies at next iteration | | `revise <ITER>` | Re-run a specific iteration (rare) |

Specs Reference

| Spec | Purpose | |------|---------| | [specs/swarm-protocol.md](specs/swarm-protocol.md) | Master protocol: script <-> coordinator interface, data flow | | [specs/pheromone-schema.md](specs/pheromone-schema.md) | Pheromone JSON structure, update formula, evaporation | | [specs/ant-output-schema.md](specs/ant-output-schema.md) | Critical contract for ant JSON artifacts | | [specs/convergence-criteria.md](specs/convergence-criteria.md) | Stop conditions, multi-criterion logic | | [specs/swarm-config-template.json](specs/swarm-config-template.json) | User-facing config template with all knobs |

Scripts

| Script | Purpose | Invocation | |--------|---------|------------| | `scripts/aco.py` | Main CLI: init / select / update / converged / report | `python aco.py --session <path> <cmd>` | | `scripts/pheromone.py` | Pheromone matrix module (imported by aco.py) | — | | `scripts/scoring.py` | Pluggable scorer (script + fallback modes) | — |

Run Directory

{run_dir}/
├── outputs/                     # Formal deliverables (registered at Run completion)
│   ├── ant-<iter>-<id>.json
│   ├── swarm-report.json
│   └── best-solution.md
└── work/team/                   # Coordination state (not formal artifacts)