{"id":51951726,"url":"https://github.com/dubsopenhub/swarm-command","last_synced_at":"2026-07-29T06:01:29.036Z","repository":{"id":350072656,"uuid":"1205193002","full_name":"DUBSOpenHub/swarm-command","owner":"DUBSOpenHub","description":"🐝 Swarm Command — Multi-model consensus swarm orchestrator for Copilot CLI. Instantly launch up to 250 agents across 16 models with shadow scoring.","archived":false,"fork":false,"pushed_at":"2026-06-29T07:26:28.000Z","size":564,"stargazers_count":5,"open_issues_count":2,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-07T22:21:29.519Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DUBSOpenHub.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-08T18:16:17.000Z","updated_at":"2026-05-21T19:22:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/DUBSOpenHub/swarm-command","commit_stats":null,"previous_names":["dubsopenhub/swarm-command"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DUBSOpenHub/swarm-command","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DUBSOpenHub%2Fswarm-command","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DUBSOpenHub%2Fswarm-command/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DUBSOpenHub%2Fswarm-command/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DUBSOpenHub%2Fswarm-command/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DUBSOpenHub","download_url":"https://codeload.github.com/DUBSOpenHub/swarm-command/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DUBSOpenHub%2Fswarm-command/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36020486,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-29T02:00:04.910Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-29T06:01:27.447Z","updated_at":"2026-07-29T06:01:29.025Z","avatar_url":"https://github.com/DUBSOpenHub.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐝 Swarm Command\n\n**Multi-model consensus swarm orchestration for the Copilot CLI. Launch 50–250+ AI agents across 15 models with Shadow Score Spec L2 validation — from one command.**\n\n[![GitHub](https://img.shields.io/badge/GitHub-Copilot_CLI-blue?logo=github)](https://github.com/features/copilot)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Security Policy](https://img.shields.io/badge/Security-Policy-brightgreen?logo=github)](SECURITY.md)\n\n**Learn more and see the website here:** [dubsopenhub.github.io/swarm-command](https://dubsopenhub.github.io/swarm-command/)\n\n\u003e ### ⚡ One Command. That's It.\n\u003e\n\u003e **Never used the CLI before? No problem.**\n\u003e\n\u003e 1. Open your terminal\n\u003e 2. Paste this:\n\u003e    ```bash\n\u003e    curl -fsSL https://raw.githubusercontent.com/DUBSOpenHub/swarm-command/main/quickstart.sh | bash\n\u003e    ```\n\u003e 3. When Copilot opens, type: `swarm command`\n\u003e\n\u003e *Requires an active [Copilot subscription](https://github.com/features/copilot/plans).*\n\n---\n\n## 🚀 30-Second Overview\n\n**Swarm Command** is for tasks that are too big, risky, or cross-cutting for one model:\n\n- **Need one answer from many perspectives?** It fans your task out across a layered swarm.\n- **Need confidence, not vibes?** It uses cross-review + consensus scoring.\n- **Need hidden quality checks?** It validates bundles with sealed acceptance criteria.\n- **Need speed at scale?** Designed for parallel execution — agents work simultaneously, not sequentially.\n- **Need zero setup?** No servers, no API keys, no build step.\n\nIf your task spans **architecture + implementation + testing + docs + integration**, this is exactly what Swarm Command is built for.\n\n---\n\n## 🤔 What Is This?\n\n**Swarm Command** is a multi-model swarm orchestration skill for the [Copilot CLI](https://docs.github.com/copilot/concepts/agents/about-copilot-cli) that launches **50 to 250+ AI agents** across **15 different models** to solve complex tasks through hierarchical fan-out, cross-family review, and consensus-gated synthesis.\n\nGive it a task — architecture, refactoring, testing, docs, or integration — and it decomposes the mission into domains, dispatches Commanders, Squad Leads, and Workers, validates outputs against sealed acceptance criteria, and synthesizes a final answer from collective intelligence instead of single-model intuition.\n\n### 💬 The Problem\n\nOne model gives you **one perspective**.\n\nFor small tasks, that's perfect. For high-stakes tasks, it's fragile:\n\n- the model may miss cross-cutting risks,\n- the task may exceed one context window,\n- the output may sound confident without being complete,\n- and you have no independent check that the answer actually satisfies the mission.\n\nSwarm Command solves that by turning one request into a **structured swarm process**: split, parallelize, review, validate, converge.\n\n---\n\n## 🥊 Swarm Command vs. Stampede vs. Havoc\n\nThese systems are complementary — not competitors.\n\n| If you need to... | Use | Why |\n|---|---|---|\n| Solve **one complex task** with layered consensus inside your current Copilot CLI session | [**Swarm Command**](https://github.com/DUBSOpenHub/swarm-command) | Best when you want decomposition, cross-model review, shadow validation, and one synthesized answer |\n| Run **parallel coding workstreams** across terminals or branches | [**Stampede**](https://github.com/DUBSOpenHub/terminal-stampede) | Best when the goal is execution throughput across independent task lanes |\n| Run a **many-model tournament** to pressure-test ideas and rank options | [**Havoc Hackathon**](https://github.com/DUBSOpenHub/havoc-hackathon) | Best when you want competitive ideation, elimination rounds, and judged synthesis |\n\n**Rule of thumb:**\n- Choose [**Swarm Command**](https://github.com/DUBSOpenHub/swarm-command) for **consensus execution**.\n- Choose [**Stampede**](https://github.com/DUBSOpenHub/terminal-stampede) for **parallel implementation**.\n- Choose [**Havoc Hackathon**](https://github.com/DUBSOpenHub/havoc-hackathon) for **idea tournaments and comparative judging**.\n\n---\n\n## ⚡ What Makes It Different\n\n- 🐝 **True swarm** — 50 to 250+ agents, not 3–5\n- 🏗️ **5-layer hierarchy** — Nexus → Commander → Squad Lead → Worker → Reviewer\n- 🔀 **Cross-model diversity** — Claude + GPT families mixed within every pod\n- 🗳️ **Consensus scoring** — 4-stage gate-then-rank with CONSENSUS / MAJORITY / CONFLICT tiers\n- 👻 **Shadow Score** — [Shadow Score Spec](https://github.com/DUBSOpenHub/shadow-score-spec) L2 conformance. Sealed acceptance criteria generated before commanders execute, validated after, hardened on failure.\n- 🛡️ **Depth Guard** — 5 laws + 3-layer enforcement prevent runaway agent spawning\n- ⚡ **Circuit breaker** — 3-state FSM with 5-level recovery escalation\n- 📉 **Parallel by design** — agents execute concurrently with hierarchical fan-out and pipeline overlap\n- 💰 **Cost-controlled** — 1024:1 token compression, wave deployment, hard cost ceilings, and cheap workers\n- 📦 **Zero infrastructure** — no servers, no API keys, no build step\n\n---\n\n## 💰 Built for Cost Control\n\nRunning 250+ agents sounds expensive. It isn't — because every layer is engineered to minimize spend.\n\n### Token Compression (1024:1)\n\nContext shrinks at every layer. The Nexus holds 128K tokens; by the time instructions reach a worker, they're 128 tokens. Parents strip rationale, narrow file scope, and tighten constraints so children only receive the bytes they need.\n\n```text\nNexus       128K tokens ──► 4K task brief\nCommander    64K tokens ──► 2K context capsule\nSquad Lead   32K tokens ──► 512 shard\nWorker        8K tokens ──► 128 micro-brief\n```\n\n### Circuit Breakers\n\nA three-state FSM (CLOSED → OPEN → HALF-OPEN) monitors every layer. If too many agents fail (50–60% threshold), the breaker trips — no new agents spawn, costs stop climbing, and a recovery probe tests before the swarm resumes.\n\n**5-level recovery escalation:** Retry → Simplify → Model Swap → Scope Reduce → Graceful Degrade.\n\n### Wave Deployment (Canary → Probe → Remainder)\n\nAgents don't all launch at once. Each pod deploys in three waves with health gates between them:\n\n1. **Wave 1 (Canary)** — 1 agent verifies the task is feasible\n2. **Wave 2 (Probe)** — 3 agents test for rate limits and bulk viability\n3. **Wave 3 (Remainder)** — full pod only if gates pass\n\nIf the canary fails, the full pod never deploys. One cheap test prevents many expensive failures.\n\n### Six Resource Guards\n\n| Guard | What it does |\n|---|---|\n| **Timeout cascade** | 90s → 60s → 40s → 30s per layer — children always finish before parents |\n| **Token ceiling** | 128K / 64K / 32K / 8K per layer |\n| **Output size cap** | 4K / 1K / 512 / 256 tokens per layer |\n| **Retry budget** | Workers: 0 retries. Squad Leads: 1 retry. |\n| **Concurrent agent cap** | Max 50 agents launching simultaneously |\n| **Cost ceiling** | $5 / $10 / $20 hard cap — kills all agents if breached |\n\n### Cost by Scale\n\n| Scale | Agents | Typical Cost | Hard Cap | Wall-Clock |\n|---|---|---|---|---|\n| **SS-50** | ~36-52 | $2.50 | $5 | ~30s |\n| **SS-100** | ~89 | $5.50 | $10 | ~45s |\n| **SS-250** | ~316 | $10 | $20 | ~65–90s |\n\n### Why It's Cheap\n\n- **Workers are the cheapest models** — Haiku and GPT-Mini at L3, 10× cheaper than Opus\n- **Expensive reasoning stays at the top** — Opus and Sonnet only at Commander/Nexus level\n- **Context compresses monotonically** — each layer receives a fraction of its parent's tokens\n- **Failed work stops early** — circuit breakers and canary gates prevent runaway spend\n\n---\n\n## 🧠 30-Second Architecture\n\nBefore the full diagrams, here's the mental model:\n\n1. **Nexus** reads the mission and splits it into domains.\n2. **Commanders** own each domain and dispatch sub-work.\n3. **Workers** do tiny atomic tasks in parallel.\n4. **Reviewers + Shadow Score** decide what survives into the final answer.\n\n```text\nYou ask one question\n        ↓\nNexus decomposes the mission\n        ↓\nCommanders split by domain\n        ↓\nWorkers execute atomic tasks in parallel\n        ↓\nReviewers score + Shadow Score validates\n        ↓\nNexus emits one final bundle\n```\n\nIf you want the visual deep dive, jump to [docs/architecture.md](docs/architecture.md) or [docs/architecture-diagrams.md](docs/architecture-diagrams.md).\n\n---\n\n## 🏗️ How It Works\n\n```\n                          ┌─────────────────┐\n                    L0    │     NEXUS (1)    │  claude-opus-4.6\n                          │  128K ctx budget │  Task decomposition + final synthesis\n                          └────────┬────────┘\n                                   │\n              ┌────────────────────┼────────────────────┐\n              │                    │                     │\n        ┌─────┴─────┐      ┌─────┴─────┐        ┌─────┴─────┐\n  L1    │ CMD-ARCH   │      │ CMD-IMPL   │  ...   │ CMD-INTG   │  × 5 Commanders\n        │ 64K ctx    │      │ 64K ctx    │        │ 64K ctx    │  Domain specialists\n        └─────┬──────┘      └─────┬──────┘        └─────┬──────┘\n              │                    │                     │\n     ┌────────┼────────┐          │                     │\n     │        │        │          │                     │\n  ┌──┴──┐ ┌──┴──┐ ┌──┴──┐\n  L2  │SQ-1│ │SQ-2│ ... │SQ-10│   × 10 per Commander = 50 Squad Leads\n      │32K │ │32K │     │32K │    Micro-task decomposition + canary deploy\n      └──┬──┘ └──┬──┘   └──┬──┘\n         │        │          │\n      ┌──┴──┐ ┌──┴──┐   ┌──┴──┐\n  L3  │W×5  │ │W×5  │   │W×5  │  × 5 per Squad Lead = 250 Workers\n      │ 8K  │ │ 8K  │   │ 8K  │  Atomic execution (LEAF — no spawning)\n      └─────┘ └─────┘   └─────┘\n\n                    ┌──────────────┐\n              L4    │ REVIEWERS×10 │  Cross-review mesh (pipeline overlap)\n                    │    16K ctx   │  4-axis sealed scoring + consensus tiers\n                    └──────────────┘\n\n              + SHADOW SCORING (sealed acceptance criteria, Shadow Score Spec L2)\n```\n\n### Time-Flow Architecture\n\n```\nT+0s     T+2s       T+5s         T+12s       T+45s      T+65s    T+80s   T+90s\n  │        │          │             │           │          │        │       │\n  ▼        ▼          ▼             ▼           ▼          ▼        ▼       ▼\n┌────┐  ┌──────┐  ┌─────────┐  ┌──────────┐ ┌────────┐ ┌───────┐ ┌────┐ ┌────┐\n│NEXUS│→ │CMDs  │→ │SQUAD    │→ │WORKERS   │ │REVIEW  │ │MERGE  │ │VOTE│ │EMIT│\n│BOOT │  │SPAWN │  │LEADS    │  │EXECUTE   │ │MESH    │ │RESULTS│ │    │ │    │\n│     │  │      │  │+ CANARY │  │(parallel)│ │(overlap│ │       │ │    │ │    │\n│     │  │      │  │VERIFY   │  │          │ │start)  │ │       │ │    │ │    │\n└────┘  └──────┘  └─────────┘  └──────────┘ └────────┘ └───────┘ └────┘ └────┘\n  2s       3s         7s           33s          20s        15s      10s    5s\n```\n\n### Signal Flow — Token Compression\n\n```\n           CONTEXT DOWN (shrinking)              RESULTS UP (compressing)\n           ========================              ========================\n\n  L0  Full Task Brief    ─── 4K tokens ───►  Final Report     ◄── 4K tokens\n                 │                                    ▲\n  L1  Context Capsule    ─── 2K tokens ───►  Bundle           ◄── 1K tokens\n                 │                                    ▲\n  L2  Shard              ─── 512 tokens ──►  Atom Set         ◄── 512 tokens\n                 │                                    ▲\n  L3  Micro-Brief        ─── 128 tokens ──►  Atom             ◄── 256 tokens\n                 │                                    ▲\n  L4  Review Capsule     ─── 1K tokens ───►  Score Card       ◄── 512 tokens\n```\n\n---\n\n## 📊 Scaling Variants\n\n| Scale | Agents | Commanders | Workers | Reviewers | Best For | Wall-Clock |\n|---|---|---|---|---|---|---|\n| **SS-50** | ~36-52 | 2-3 | 30-45 | 3 | Fast bounded tasks | ~30s |\n| **SS-100** | ~89 | 5 | 75 | 8 | Multi-file features and reviews | ~45s |\n| **SS-250** | ~316 | 5 | 250 | 10 | Repo-wide or high-stakes work | ~65–90s |\n\n### 10-Second Decision Tree\n\n```text\nDo you need a fast second opinion on 1–2 files?\n→ SS-50\n\nDo you need a serious answer for a multi-file feature or subsystem?\n→ SS-100\n\nDo you need repo-wide coverage, compliance-grade review, or maximum consensus?\n→ SS-250\n```\n\nDefault is **SS-100**. Say `swarm command ss-250` for full deployment or `swarm command ss-50` for quick tasks.\n\nSee [docs/scaling.md](docs/scaling.md) for cost breakdowns, chooser guidance, and a deeper decision matrix.\n\n---\n\n## 🎯 Use Cases\n\nCurated highlights — see [docs/use-cases.md](docs/use-cases.md) for the full gallery.\n\n### SS-50 — Fast Expert Panels (~30s)\n\n**🔥 Stack Trace Whisperer**\n```text\nswarm command ss-50 \"Diagnose this error — 3 most likely root causes with fixes: [paste error]\"\n```\n\u003e Three fast expert panels race on runtime, dependency, and logic hypotheses. You get ranked diagnoses, not a single guess.\n\n**🔍 Explain Like I Own It**\n```text\nswarm command ss-50 \"I just inherited this codebase. Explain src/core/ — what does each piece do, where are the landmines?\"\n```\n\u003e Great for onboarding: architecture map, event flow, and hidden footguns in one brief.\n\n**⚡ Performance Profiler's Shortcut**\n```text\nswarm command ss-50 \"Find the performance bottlenecks in this file with optimized versions: [paste hot-path file]\"\n```\n\u003e Ideal when you need a prioritized hit list before opening a profiler.\n\n### SS-100 — Full Swarm, Default Scale (~45s)\n\n**🔐 Zero-Downtime Auth Rewrite**\n```text\nswarm command \"Migrate our session auth to JWT + refresh tokens across API, web app, DB, and tests\"\n```\n\u003e Architecture, implementation, testing, docs, and rollout risk all get separate ownership before synthesis.\n\n**🏗️ Legacy Service Extraction**\n```text\nswarm command \"Extract the billing module from our monolith into a service with minimal downtime\"\n```\n\u003e Produces migration phases, interface boundaries, contract tests, and rollback paths.\n\n**📱 Offline Sync Feature**\n```text\nswarm command \"Design offline-first sync for our field app: local cache, conflict resolution, API changes, UX, and tests\"\n```\n\u003e Covers data model, UX states, conflict semantics, and integration testing in parallel.\n\n### SS-250 — Maximum Intelligence (~65–90s)\n\n**🛡️ Zero-Day Security Sweep**\n```text\nswarm command ss-250 \"Full security audit: every file, every dependency, every injection surface — CVSS-scored vulnerability report\"\n```\n\u003e Best for broad-surface analysis where missing even one category matters.\n\n**⚖️ Compliance Fortress**\n```text\nswarm command ss-250 \"Audit for GDPR, HIPAA, SOC2, PCI-DSS compliance — every gap, every control, remediation tickets\"\n```\n\u003e Turns a giant policy problem into parallel control checks with one synthesized risk summary.\n\n**🗺️ Living Runbook Generator**\n```text\nswarm command ss-250 \"Read every service, every pipeline, every config — generate the complete operations manual\"\n```\n\u003e Excellent when tribal knowledge has to become documentation fast.\n\n### ❌ When NOT to Swarm\n\n- **\"What's the CLI flag for X?\"** → Ask a single agent\n- **Rename one variable** → Manual edit or single agent\n- **Prod is down and seconds matter** → Follow the human runbook first\n- **Writing a single-voice email** → One persona is better than a committee\n- **Step-through debugging** → Sequential work beats consensus here\n\n---\n\n## 📦 Install\n\n### Instant Install (no clone needed) ⚡\n\n```bash\nmkdir -p ~/.copilot/skills/swarm-command ~/.copilot/agents \u0026\u0026 \\\n  curl -sL https://raw.githubusercontent.com/DUBSOpenHub/swarm-command/main/skills/swarm-command/SKILL.md \\\n    -o ~/.copilot/skills/swarm-command/SKILL.md \u0026\u0026 \\\n  curl -sL https://raw.githubusercontent.com/DUBSOpenHub/swarm-command/main/agents/swarm-command.agent.md \\\n    -o ~/.copilot/agents/swarm-command.agent.md \u0026\u0026 \\\n  echo \"✅ Swarm Command installed — open Copilot CLI and type: swarm command\"\n```\n\n**Verify integrity (optional):**\n\n```bash\nshasum -a 256 ~/.copilot/skills/swarm-command/SKILL.md\nshasum -a 256 ~/.copilot/agents/swarm-command.agent.md\n```\n\n\u003e 💡 **Security note:** We recommend [inspecting quickstart.sh](https://github.com/DUBSOpenHub/swarm-command/blob/main/quickstart.sh) before piping to bash. You can also use the manual install above instead.\n\n### Clone \u0026 Explore\n\n```bash\ngit clone https://github.com/DUBSOpenHub/swarm-command.git\ncd swarm-command\nchmod +x quickstart.sh \u0026\u0026 ./quickstart.sh\n```\n\n---\n\n## 🧭 Reading Order / Learning Path\n\nIf you're new, read in this order:\n\n1. **This README** — what it is, when to use it, and how to run it\n2. [**docs/learning-path.md**](docs/learning-path.md) — beginner, operator, and architect reading tracks\n3. [**docs/architecture.md**](docs/architecture.md) — the conceptual system model\n4. [**docs/scaling.md**](docs/scaling.md) — which scale to choose and what it costs\n5. [**docs/use-cases.md**](docs/use-cases.md) — vivid prompts and expected outcomes\n6. [**docs/consensus.md**](docs/consensus.md) + [**docs/shadow-scoring.md**](docs/shadow-scoring.md) — the deep mechanics\n\n### Fast paths\n\n- **I just want to try it:** README → install → run `swarm command`\n- **I want to operate it well:** README → learning path → scaling → use cases\n- **I want to understand the design:** README → architecture → consensus → shadow scoring\n\n---\n\n## ❓ FAQ\n\n### Do I need API keys or infrastructure?\nNo. Swarm Command runs through your active Copilot subscription. No separate servers, queues, or key management required.\n\n### When should I use SS-50, SS-100, or SS-250?\nUse **SS-50** for bounded, fast tasks. Use **SS-100** for most real software work. Use **SS-250** when the task is repo-wide, high-stakes, or needs maximum coverage and consensus.\n\n### Personality Modes\n\nAppend a personality mode after the scale to adjust how the swarm operates:\n\n```bash\nswarm command ss-100 thorough \"audit auth module\"\nswarm command ss-250 fast \"quick scan of README\"\n```\n\n| Mode | Workers | Timeout | Models | Retry | Best For |\n|---|---|---|---|---|---|\n| `balanced` (default) | 5 per squad | 1.0× | mixed | 1 | Most tasks |\n| `thorough` | 5 per squad | 1.5× | opus/sonnet | 2 | High-stakes, complex analysis |\n| `fast` | 3 per squad | 0.6× | haiku only | 0 | Quick iteration, cost-sensitive |\n| `creative` | 4 per squad | 1.0× | max diversity | 1 | Brainstorming, novel problems |\n| `cautious` | 5 per squad | 1.2× | sonnet | 2 | Ambiguous tasks, high conflict risk |\n\n### Why mix Claude and GPT models?\nBecause diversity helps. Different model families catch different failure modes. Swarm Command intentionally mixes them so agreement means more than self-consistency.\n\n### What happens when agents disagree?\nDisagreement is preserved, scored, and escalated. Squad Leads and Commanders mark results as **CONSENSUS**, **MAJORITY**, **CONFLICT**, or **UNIQUE**, then Nexus arbitrates the unresolved pieces.\n\n### What is Shadow Score in one sentence?\nIt is a hidden acceptance test: criteria are generated before execution, kept sealed from the swarm, then used to validate outputs afterward.\n\n### Will this write code automatically?\nIt can produce plans, analyses, patches, documentation, tests, and rollout guidance depending on how you invoke it — but the point is not blind automation. The point is **reviewable, consensus-backed output**.\n\n### When should I avoid using it?\nAvoid it for tiny edits, urgent incident response where every second matters, or tasks that need one strong voice rather than many perspectives.\n\n---\n\n## 🛠️ How It Was Built\n\nSwarm Command came out of a simple question: **what if one Copilot CLI session could behave less like one assistant and more like a disciplined organization?**\n\nThe design evolved from **SwarmSpeed 250** experiments into a layered system with:\n\n- a single **Nexus** orchestrator,\n- domain-owning **Commanders**,\n- decomposing **Squad Leads**,\n- leaf-node **Workers**,\n- and independent **Reviewers**.\n\nThe turning point was a self-analysis run later documented in [docs/shadow-scoring.md](docs/shadow-scoring.md): sealed judges rated a design highly **even though it contained critical arithmetic errors**. That exposed a core truth of multi-agent systems: **review alone is not validation**.\n\nThat failure drove the big ideas that now define this repo:\n\n- **Shadow scoring** so hidden criteria can catch what the swarm forgot to optimize for\n- **Depth Guard** so recursion never turns into agent explosion\n- **Token compression** so higher-level intent survives while lower layers stay cheap\n- **Cross-family review** so agreement means more than “the same model said it twice”\n\nIn other words: Swarm Command is not just a big swarm. It is a swarm that learned from its own failure modes.\n\n---\n\n## 📋 Example Output\n\nSee what a completed swarm run looks like → **[Example Output](docs/example-output.md)**\n\n```\n🐝 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n   S W A R M   C O M P L E T E\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## Results Summary\n- Domains completed: 5/5\n- Consensus tier: CONSENSUS (4) · MAJORITY (1)\n- Overall confidence: 0.77\n- Agents deployed: 89\n- Wall-clock time: 72s\n- Shadow Score: 20.0% 🟡 Moderate (8 pass · 2 fail)\n```\n\n---\n\n## 👻 Shadow Scoring\n\nSwarm Command implements **[Shadow Score Spec](https://github.com/DUBSOpenHub/shadow-score-spec) L2 conformance** — sealed acceptance criteria generated before commanders execute, validated after, hardened on failure.\n\n**Formula:** `Shadow Score = (sealed_failures / sealed_total) × 100`\n\n| Shadow Score | Level | Action |\n|---|---|---|\n| 0% | ✅ Perfect | All sealed criteria passed |\n| 1–15% | 🟢 Minor | Proceed normally |\n| 16–30% | 🟡 Moderate | Attach Gap Report, warn |\n| 31–50% | 🟠 Significant | Quarantine bundle, hardening cycle |\n| \u003e 50% | 🔴 Critical | Reject bundle from synthesis |\n\n**Sealed-envelope protocol:**\n1. **Phase 1.5** — Nexus generates sealed acceptance criteria from the task\n2. **Phases 2–5** — Commanders execute without seeing those criteria\n3. **Phase 6** — Validate outputs, compute Shadow Score, produce Gap Report\n4. **Hardening** — If score \u003e 15%, share failure messages only for one fix cycle\n\nSee [docs/shadow-scoring.md](docs/shadow-scoring.md) for the full protocol.\n\n---\n\n## 🗳️ Consensus Algorithm\n\nA 4-stage consensus pipeline merges the best work from hundreds of agents:\n\n1. **Worker Self-Score** — Each worker emits confidence + self-score with its atom\n2. **Squad Lead Local Merge** — Groups atoms by sub-task, classifies as CONSENSUS / MAJORITY / CONFLICT\n3. **Commander Domain Merge** — Trimmed mean across squads, applies the consensus formula\n4. **Nexus Cross-Domain Synthesis** — Median-of-3 judging and final arbitration\n\n**Consensus formula:**\n```text\nscore = 0.40 × confidence + 0.30 × evidence + 0.15 × scope + 0.15 × coverage − min(0.30, conflict_rate × 0.30)\n```\n\n| Tier | Condition | Action |\n|---|---|---|\n| **CONSENSUS** | ≥ 70% agreement | Auto-accept |\n| **MAJORITY** | ≥ 50% agreement | Accept with dissent note |\n| **CONFLICT** | \u003c 50% agreement | Nexus arbitration |\n| **UNIQUE** | No overlap | Keep if evidence ≥ 7/10 |\n\nSee [docs/consensus.md](docs/consensus.md) for the full mechanics.\n\n---\n\n## ⚙️ Configuration\n\nAll tunables live in `config.yml`. Key settings:\n\n```yaml\nconsensus:\n  threshold_consensus: 0.70\n  threshold_majority: 0.50\n\ndepth_guard:\n  max_spawn_depth: 3\n  max_workers_per_squad_lead: 5\n\ncircuit_breaker:\n  timeout_cascade: [90, 60, 40, 30]\n\nshadow_scoring:\n  enabled: true\n  spec_version: \"1.0.0\"\n  conformance_level: \"L2\"\n  sealed_criteria_count: 10  # max; per-scale: SS-50=6, SS-100=8, SS-250=10\n  hardening:\n    enabled: true  # SS-50 overrides to disabled\n    threshold: 15\n```\n\nSee [docs/scaling.md](docs/scaling.md) for full scaling configuration and cost estimates.\n\n---\n\n## 🤖 Models Used\n\n| Role | Models |\n|---|---|\n| **Nexus** | claude-opus-4.6 |\n| **Commanders** (pool: 9) | claude-opus-4.6, claude-opus-4.5, claude-opus-4.6-1m, claude-sonnet-4.6, claude-sonnet-4.5, claude-sonnet-4, gpt-5.4, gpt-5.2, gpt-5.1 |\n| **Squad Leads** (SS-250 only) | claude-haiku-4.5, gpt-5.4-mini |\n| **Workers** (pool: 6) | claude-haiku-4.5, gpt-5.4-mini, gpt-5-mini, gpt-4.1, gpt-5.3-codex, gpt-5.2-codex |\n| **Reviewers** (7 pairs) | claude-opus-4.6↔gpt-5.4, claude-opus-4.5↔gpt-5.2, claude-opus-4.6-1m↔gpt-5.1, claude-sonnet-4.6↔gpt-5.3-codex, claude-sonnet-4.5↔gpt-5.2-codex, claude-sonnet-4↔gpt-5.4-mini, claude-haiku-4.5↔gpt-5-mini |\n\n---\n\n## 📁 Repository Structure\n\n```text\nswarm-command/\n├── README.md                           # Overview, install, comparison, FAQ\n├── AGENTS.md                           # Agent/skill descriptions\n├── CONTRIBUTING.md                     # Contribution guidelines\n├── catalog.yml                         # Skill metadata\n├── config.yml                          # All tunables\n├── LICENSE                             # MIT\n├── SECURITY.md                         # Security policy\n├── quickstart.sh                       # One-line installer\n├── .github/\n│   ├── copilot-instructions.md         # AI agent instructions for this repo\n│   ├── workflows/ci.yml               # CI: YAML lint + SKILL.md sync check\n│   └── skills/swarm-command/SKILL.md   # Skill discovery path\n├── agents/\n│   └── swarm-command.agent.md          # Standalone agent version\n├── skills/swarm-command/\n│   └── SKILL.md                        # Core skill\n├── templates/\n│   ├── commander.md                    # Commander prompt template\n│   ├── worker.md                       # Worker prompt template\n│   ├── reviewer.md                     # Cross-reviewer prompt template\n│   └── squad-lead.md                   # Squad Lead prompt template\n├── protocols/\n│   ├── depth-guard.md                  # 5 Laws + 3-layer enforcement\n│   ├── circuit-breaker.md              # 3-state FSM + 5-level recovery\n│   ├── context-capsule.md              # JSON schemas for data structures\n│   └── meta-reviewer.md               # Reviewer quality gate protocol\n└── docs/\n    ├── architecture.md                 # Architecture overview\n    ├── architecture-diagrams.md        # Mermaid diagrams\n    ├── consensus.md                    # Consensus algorithm deep dive\n    ├── example-output.md               # Sample completed swarm run output\n    ├── learning-path.md                # Recommended reading order\n    ├── scaling.md                      # Scale chooser + cost estimates\n    ├── shadow-scoring.md               # Shadow scoring protocol\n    └── use-cases.md                    # Expanded prompt gallery\n```\n\n---\n\n## 📄 License\n\n[MIT](LICENSE) — use it, fork it, build on it.\n\n---\n\n## 🛡️ Spec Conformance\n\nThis project implements **[Shadow Score Spec](https://github.com/DUBSOpenHub/shadow-score-spec) L2** — sealed acceptance criteria generated before execution, validated after, hardened on failure.\n\n---\n\n🐙 Created with 💜 by [@DUBSOpenHub](https://github.com/DUBSOpenHub) with the [GitHub Copilot CLI](https://docs.github.com/copilot).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdubsopenhub%2Fswarm-command","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdubsopenhub%2Fswarm-command","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdubsopenhub%2Fswarm-command/lists"}