team-adversarial-swarm

Team Adversarial Swarm

ACO Ant Colony Optimization + modular Workflow orchestration + adversarial decision-making.

Inherits team-swarm ant colony algorithm core (Python ACO script), uses 4 composable Workflow scripts to replace the team-worker architecture, and injects adversarial agent patterns at each decision node.

Architecture

SKILL.md (Coordinator — this file)
  │
  │  Phase 1: Config Generation (inline)
  │  Phase 2: ACO Init (Bash: aco.py init)
  │
  │  Phase 3: Iteration Loop ×K
  │  ┌──────────────────────────────────────────────────┐
  │  │ 3a. Bash: aco.py select → assignments            │
  │  │ 3b. Workflow(wf-swarm-explore)   ← 模块1         │
  │  │     N ants parallel → ant_results                │
  │  │ 3c. Workflow(wf-swarm-score)     ← 模块2         │
  │  │     3-vote adversarial scoring → verified_scores │
  │  │ 3d. Write scores → Bash: aco.py update           │
  │  │ 3e. Workflow(wf-swarm-converge)  ← 模块3         │
  │  │     prosecutor/defender/judge → converged?       │
  │  │ 3f. if converged: break                          │
  │  └──────────────────────────────────────────────────┘
  │
  │  Phase 4: Bash: aco.py report
  │  Workflow(wf-swarm-synthesize)      ← 模块4
  │  3-perspective analysis + arbitration → best-solution.md

Workflow Module Registry

Module	Script	Args Interface	Adversarial Pattern	Returns
Explore	`workflows/wf-swarm-explore.js`	`{ iteration, assignments[], objective, session, config }`	N ants parallel	`{ ant_results[] }`
Score	`workflows/wf-swarm-score.js`	`{ iteration, ant_results[], objective, rubric? }`	3-vote per ant (prosecutor/defender/judge)	`{ scores{}, calibration }`
Converge	`workflows/wf-swarm-converge.js`	`{ iteration, best, history[], config }`	prosecutor(continue)/defender(stop)/judge	`{ converged, reason, confidence }`
Synthesize	`workflows/wf-swarm-synthesize.js`	`{ best, top_k[], convergence_story, objective }`	3-perspective + arbitrator	`{ report, caveats }`

Each module is independently usable, and can also be composed and orchestrated by the Coordinator.

Shared Dependencies

All dependencies are internal to this skill, with no external references.

Python ACO script: <this-skill>/scripts/aco.py
- Runtime resolution: Glob(".claude/skills/team-adversarial-swarm/scripts/aco.py")
- Dependent modules: pheromone.py, scoring.py(same directory)
- Command: init / select / update / converged / report
- Protocol: specs/swarm-protocol.md
Workflow script: <this-skill>/workflows/wf-swarm-*.js
- Runtime resolution: Glob(".claude/skills/team-adversarial-swarm/workflows/wf-swarm-*.js")

Specs Reference

Spec	Purpose
specs/swarm-protocol.md	Coordinator ↔ Script ↔ Workflow tripartite protocol
specs/pheromone-schema.md	Pheromone matrix structure, update formula, evaporation rules
specs/ant-output-schema.md	Ant output JSON contract (three-tier scoring)
specs/convergence-criteria.md	Two-tier convergence: Python signals + adversarial debate
specs/swarm-config-template.json	User configuration template

Session Directory

.workflow/.team/TAS-<slug>-<date>/
├── swarm-config.json       # Phase 1 output
├── pheromone/              # ACO state (managed by aco.py)
│   ├── current.json
│   └── history/
├── trails/                 # Per-iteration trails (managed by aco.py)
├── scores/                 # Adversarial scoring results
│   └── iter-<k>-scores.json
├── artifacts/
│   ├── ant-<k>-<id>.json   # Ant outputs
│   └── best-solution.md    # Final synthesis
├── workflows/              # Workflow run artifacts
│   ├── explore-<k>.json    # Per-iteration explore results
│   ├── score-<k>.json      # Per-iteration score results
│   └── converge-<k>.json   # Per-iteration convergence decision
└── best.json               # Canonical best (managed by aco.py)

Coordinator Execution Flow

Phase 0: Resume Check

Glob(".workflow/.team/TAS-*/swarm-config.json") → find active session
If one exists and has workflows/converge-*.json not marked converged → restore to the corresponding iteration
If no active session → Phase 1

Phase 1: Config Generation

Parse user intent, generate swarm-config.json。

If the intent is not clear enough, use AskUserQuestion to clarify:

What is the search space? (file glob / node list / abstract decision set)
What is the goal? (optimal solution / problem discovery / path optimization)
How to score? (test pass rate / lint / custom rules / LLM adversarial scoring)
Budget? (max iterations / ants per round / token budget)

Generate config fields:

{
  "task": { "objective": "...", "evidence_requirements": "..." },
  "swarm": { "n_ants": 5, "max_iterations": 5 },
  "aco": { "alpha": 1.0, "beta": 2.0, "rho": 0.1, "q": 1.0 },
  "task_space": { "nodes": [...], "auto_discover_from": "..." },
  "scoring": { "mode": "adversarial", "rubric": "..." },
  "convergence": { "patience": 2, "min_improvement": 0.01, "max_iterations": 5 }
}

Write to <session>/swarm-config.json。

Phase 2: ACO Init

Create session directory: TAS-<slug>-<date>
Resolve aco.py path (inherited from team-swarm skill)
Bash: python <aco.py> --session <session> init
Resolve output: { n_nodes, n_edges, pheromone_path }

Phase 3: Iteration Loop

for k in range(1, max_iterations + 1):
    # 3a. ACO selection
    assignments = Bash("python aco.py --session <session> select --iter k")
    
    # 3b. Parallel exploration (Workflow Module 1)
    explore_result = Workflow({
        scriptPath: "<skill>/workflows/wf-swarm-explore.js",
        args: { iteration: k, assignments, objective, session, config }
    })
    
    # 3c. Adversarial scoring (Workflow Module 2)
    score_result = Workflow({
        scriptPath: "<skill>/workflows/wf-swarm-score.js",
        args: { iteration: k, ant_results: explore_result.ant_results, objective, rubric }
    })
    
    # 3d. Write scores + pheromone update
    Write("<session>/scores/iter-k-scores.json", score_result)
    Bash("python aco.py --session <session> update --iter k")
    
    # 3e. Adversarial convergence check (Workflow Module 3)
    converge_result = Workflow({
        scriptPath: "<skill>/workflows/wf-swarm-converge.js",
        args: { iteration: k, best: aco_best, history: iter_history, config }
    })
    
    # 3f. Save + check
    Write("<session>/workflows/converge-k.json", converge_result)
    if converge_result.converged: break

Note: each Workflow call is independent; data is passed in via args and returned via return values. The Coordinator is responsible for data bridging between Workflows and for calling Python scripts.

Phase 4: Synthesis

Bash: python aco.py --session <session> report → get best + top_k + curve

Call Workflow Module 4:

Workflow({
  scriptPath: "<skill>/workflows/wf-swarm-synthesize.js",
  args: { best, top_k, convergence_story, objective }
})

Write the synthesis result to <session>/artifacts/best-solution.md
Display completion summary + AskUserQuestion (archive / keep / export / run another round)

Module Composition Patterns

Full pipeline (default)

explore → score → update → converge → [loop] → synthesize

Exploration only (skip scoring, use self_score)

explore → update(self_score) → converge → synthesize

Single-iteration debugging

explore(k=1) → score(k=1)  // 不循环，只看一轮

Standalone scoring (existing ant artifacts)

score(ant_results from files) → 输出 verified_scores

Standalone synthesis (existing best + trails)

synthesize(best, top_k) → best-solution.md

Error Handling

Scenario	Resolution
aco.py not found	Glob team-swarm skill path; prompt to install
Python < 3.10	Try python3; report dependencies
Workflow execution failed	Log the error, provide a --resume recovery point
All ants failed	Pause, AskUserQuestion (retry/terminate/adjust config)
Convergence never triggers	max_iterations safety net will always trigger
Hallucination cluster (>50% of ants downscored)	Pause, AskUserQuestion (continue/adjust scoring rules)

Completion

Display final results + interactive choices:

Archive: save session, display best-solution.md
Continue: keep session, additional iterations allowed
Export: Copy best-solution.md to the target location
Run again: Reset convergence and continue for K rounds