swarm-engine 1.1.1 → 1.38.0

package/CLAUDE.md

@@ -54,7 +54,7 @@ src/
 ├── memory/                  # SQLite + FTS5 + Obsidian vault sync
 ├── hooks/                   # TypeScript hook handlers (universal ANSI)
 ├── plugin/                  # Claude Code plugin generator
-├── cli/                     # 21 CLI commands (15 visible + 6 hidden)
+├── cli/                     # 23 CLI commands (17 visible + 6 hidden)
 └── utils/                   # Logger, config, terminal, paths, redact, tokens, errors, env
 ```
 

package/README.md

@@ -1,37 +1,59 @@
 # Swarm Engine
 
+[![npm](https://img.shields.io/npm/v/swarm-engine)](https://www.npmjs.com/package/swarm-engine)
+[![Node](https://img.shields.io/node/v/swarm-engine)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://img.shields.io/badge/tests-1278%20passing-brightgreen)]()
+
 **Your agents. Orchestrated.**
 
-Coordinate multiple AI agents working on your code - researching, implementing, reviewing, testing - with an intelligent planner that learns from every run.
+The first self-aware AI orchestration engine. A 16-module ML pipeline -- built in pure TypeScript with zero external ML dependencies -- that predicts its own failures, explains them causally, and evolves its own rules. Underneath: 26 agents, 7 composable patterns, and a persistent knowledge graph that compounds intelligence across every run.
 
-Works with Claude Code, OpenAI Codex, and Google Gemini CLI. Mix models across agents in the same orchestration.
+Works with Claude Code, OpenAI Codex, Google Gemini CLI, and Vercel AI SDK. Mix models across agents in the same orchestration.
 
 ## What It Looks Like
 
 ```
-  Swarm Engine - hybrid pattern
+  ⚡ Swarm Engine — hybrid pattern
+
+  Phase: research ━━━━━━━━━━━━━━━━━━━━ done
+    ✓ researcher-code       sonnet-4-6     3.2K tok   14s
+    ✓ researcher-context    sonnet-4-6     1.8K tok    9s
 
-  Phase 1: research ━━━━━━━━━━━━━━━━━━━━ 100%  42s
-    ✓ researcher-code       sonnet   3.2K tokens
-    ✓ researcher-context    sonnet   1.8K tokens
+  Phase: implement ━━━━━━━━━━━━━━━━━━━ 1m 12s
+    ● implementer           opus-4-6       8.4K tok   1m 12s  src/auth/rate-limit.ts
 
-  Phase 2: implement ━━━━━━━━━━━━━━━━━━━  55%  1m 12s
-    ● implementer           opus     src/auth/rate-limit.ts...
+  Phase: review ────────────────────── pending
+    ○ reviewer-security     opus-4-6
+    ○ reviewer-perf         sonnet-4-6
+    ○ reviewer-convention   sonnet-4-6
 
-  Phase 3: review                         pending
-    ○ reviewer-correctness  ○ reviewer-security  ○ reviewer-convention
+  Timeline: ━━──── (1/3 phases)
 
-  $0.24 spent | 12.8K tokens | ~2m remaining
+  Recent findings:
+    ○ researcher-code: express-rate-limit already in package.json
+    ○ researcher-context: vault says rate limiter goes before auth middleware
+
+  12.8K tokens │ $0.24 │ 1m 36s  ~2m remaining
 ```
 
 ```
-  ┌─────────────────────────────────────────────────┐
-  │  ✓ Orchestration complete                       │
-  │  Pattern: hybrid (3 phases, 6 agents)           │
-  │  Duration: 3m 42s | Tokens: 47K | Cost: $0.38   │
-  │                                                 │
-  │  Save as template? deploy-lambda                │
-  └─────────────────────────────────────────────────┘
+  +---------------------------------------------------------+
+  |                                                         |
+  |  Orchestration complete                                 |
+  |                                                         |
+  |  Pattern:  hybrid (3 phases, 6 agents)                  |
+  |  Duration: 3m 42s                                       |
+  |  Tokens:   47.2K                                        |
+  |  Cost:     $0.3814                                      |
+  |  Tools:    142 calls                                    |
+  |                                                         |
+  |  Changes:                                               |
+  |    src/middleware/rate-limit.ts        48 +++           |
+  |    src/routes/users.ts                3 +-              |
+  |    tests/middleware/rate-limit.test.ts 62 +++           |
+  |                                                         |
+  +---------------------------------------------------------+
 ```
 
 ## Install
@@ -66,17 +88,34 @@ Requires Node.js 20+, jq, and at least one of Claude Code, Codex, or Gemini CLI.
 
 ## Quick Start
 
-```bash
-# From Claude Code (agents run in split panes)
+In Claude Code:
+```
 /swarm "add rate limiting to the API"
+```
+
+That's it. Agents spawn as teammates, research the codebase, implement the changes, and review the result. You see their work in split panes and get a summary when they're done.
 
-# From any terminal
-swarm orchestrate "add rate limiting to the API"
+Other slash commands for specific patterns:
+```
+/research "how does the auth system work?"
+/tdd "add input validation to user endpoints"
+/red-team "harden the payment flow"
+/review-cycle "refactor the database layer"
+```
+
+### Standalone CLI
+
+You can also run orchestrations directly from any terminal, outside of Claude Code:
 
-# Preview what will happen before running
-swarm plan "add rate limiting" --dry-run
+```bash
+swarm orchestrate "add rate limiting"          # inline progress
+swarm orchestrate "add rate limiting" --panes  # tmux split panes
+swarm orchestrate "add rate limiting" --tui    # full-screen dashboard
+swarm plan "add rate limiting"                 # preview plan (free)
 ```
 
+The `--panes` flag uses tmux to show each agent in its own split pane. Install with `brew install tmux` (macOS) or `sudo apt install tmux` (Linux).
+
 ## VS Code and Cursor
 
 Swarm Engine ships with a VS Code extension that works in both VS Code and Cursor.
@@ -103,18 +142,84 @@ Then: `Cmd+Shift+P` > "Extensions: Install from VSIX" > select the `.vsix` file.
 @swarm status
 ```
 
+## Use as a Library
+
+Swarm Engine can be imported directly into Node.js applications:
+
+```bash
+npm install swarm-engine
+```
+
+```ts
+import { SwarmEngine } from 'swarm-engine';
+
+const engine = new SwarmEngine({ mock: true });
+const result = await engine.orchestrate({
+  task: 'Build a REST API',
+  pattern: 'hybrid',
+});
+console.log(result.status);
+```
+
+Key exports:
+
+```ts
+import {
+  SwarmEngine,       // Main orchestration engine
+  AgentRegistry,     // Load and manage agent definitions
+  EventBus,          // Typed event system for monitoring
+  PatternRegistry,   // Composable orchestration patterns
+  BackendRegistry,   // Multi-backend (Claude, Codex, Gemini, Vercel AI)
+  CostModel,         // Estimate token costs before running
+  ModelRouter,       // UCB1-based model selection
+  TemplateRegistry,  // Save and replay successful workflows
+} from 'swarm-engine';
+
+// Tier 1: Core Graph
+import {
+  ExecutionGraph,          // Persistent execution knowledge graph
+  GraphLearner,            // Cross-run pattern learning
+  GraphContextRouter,      // Relevance-scored context assembly
+  GraphAnalyzer,           // Topology analysis and failure prediction
+  ReviewFeedbackRecorder,  // Review findings into graph
+} from 'swarm-engine';
+
+// Tier 2: Advanced ML
+import {
+  CausalGraphEngine,              // Do-calculus causal inference
+  FailurePropagationPredictor,    // 3-layer GNN failure prediction
+  AdversarialEvolver,             // Thompson sampling red-team
+  MetaPatternSelector,            // TF-IDF + logistic pattern recommendation
+  PredictiveDropout,              // Active learning agent dropout
+} from 'swarm-engine';
+
+// Tier 3: Self-Aware Engine
+import {
+  PatternSynthesizer,     // Topology diff → novel patterns
+  TrajectoryPredictor,    // Mid-run success prediction
+  MetaAdversarialTester,  // Red-teams the engine's own ML
+  RuleEvolver,            // Self-evolving replanning rules
+  TaskDiscovery,          // Mines failure patterns for tasks
+  OrchestrationEmbedder,  // Topology embeddings for transfer learning
+} from 'swarm-engine';
+```
+
+See [src/index.ts](src/index.ts) for the full export surface.
+
 ## Why Swarm Engine
 
-AI coding agents work alone. You get one agent, one model, one approach. For complex tasks, that's not enough.
+Tools like Claude Code already let you spawn parallel agents with teams. That's powerful infrastructure. Swarm Engine builds on top of it with the parts you'd otherwise have to figure out yourself: which agents to run, in what order, with what prompts, on which models, and how to learn from the results.
 
-Swarm Engine orchestrates multiple agents in parallel. Each has a specialized role, the right model for the job, and shared knowledge from past runs.
+It gives you composable patterns, cost-aware planning, specialized agent definitions, and a memory system that improves with every run. Think of it as the orchestration layer that turns ad-hoc multi-agent work into repeatable workflows.
 
-- **7 composable patterns** - hybrid, TDD, red-team, spike, discover, review-cycle, research. Compose them: `--pattern "research | tdd | red-team"`
+- **Self-aware ML pipeline** - the engine predicts its own failures (GNN), explains them causally (do-calculus), and evolves its own replanning rules. All in pure TypeScript, zero external ML dependencies.
+- **16 graph modules across 3 tiers** - persistent knowledge graph, causal inference, GNN failure propagation, trajectory prediction, orchestration embeddings, and self-evolving rules.
+- **7 composable patterns** - hybrid, TDD, red-team, spike, discover, review-cycle, research. Compose them: `--pattern "tdd | red-team"`. Plus 12 slash commands including postmortem, diff-review, and fix-pr.
 - **Intelligent planner** - cost-based optimization, adaptive execution, learns from every run
 - **Mix any backend** - Claude for implementation, Codex for review, Gemini for research. Different model per agent.
 - **Reusable templates** - save successful workflows, run them again with different parameters
 - **26 specialized agents** - 16 core roles plus 10 focused reviewers (security, performance, data integrity, API contracts, testing, accessibility, dependencies, error handling, concurrency, documentation)
-- **871 tests** - 4 rounds of security review, clean on all adversarial attack vectors
+- **1,278 tests across 76 files** - 4 rounds of security review, clean on all adversarial attack vectors
 
 ## Templates
 
@@ -171,6 +276,8 @@ swarm plan "add auth middleware" --pattern hybrid
 | `/spike <problem>` | Two approaches compete, judge picks winner |
 | `/red-team <task>` | Adversarial build and break |
 | `/discover <problem>` | Hypothesize, experiment, implement winner |
+| `/dynamic <task>` | Planner decomposes into custom agent workflow |
+| `/postmortem <error>` | Root cause analysis, fix, and prevention |
 | `/fix-pr <PR#>` | Fix PR review comments |
 | `/resume` | Resume from checkpoint |
 
@@ -228,9 +335,17 @@ swarm convert --to opencode   # OpenCode agents
 swarm convert --to windsurf   # Windsurf skills
 ```
 
-## Memory
+## Memory and Knowledge Graph Intelligence
+
+SQLite-backed knowledge base with full-text search, plus a 3-tier Execution Knowledge Graph that records every orchestration as a persistent, queryable topology. Syncs to Obsidian vault for cross-machine access.
+
+**Tier 1 -- Core Graph.** ExecutionGraph records orchestration topology. GraphLearner extracts cross-run patterns. GraphContextRouter replaces dump-everything context with relevance-scored assembly. GraphAnalyzer detects god nodes, bottlenecks, and topology risks.
+
+**Tier 2 -- Advanced ML.** CausalGraphEngine applies do-calculus to estimate treatment effects and suggest interventions. FailurePropagationPredictor uses a 3-layer GNN to predict which nodes are at risk before execution starts. MetaPatternSelector recommends orchestration patterns via TF-IDF + logistic regression. PredictiveDropout uses active learning to skip redundant agents.
+
+**Tier 3 -- Self-Aware Engine.** PatternSynthesizer generates novel orchestration patterns from topology diffs. TrajectoryPredictor forecasts orchestration success mid-run. RuleEvolver proposes and backtests its own replanning rules from historical failures. TaskDiscovery mines the graph for actionable tasks. OrchestrationEmbedder produces topology-based embeddings for similarity search and transfer learning. MetaAdversarialTester red-teams the engine's own ML subsystems.
 
-SQLite-backed knowledge base with full-text search. Syncs to Obsidian vault for cross-machine access. The engine learns from every run and compounds knowledge over time.
+All ML is implemented in pure TypeScript with zero external ML dependencies.
 
 ```bash
 swarm memory search "authentication"

package/commands/diff-review.md

@@ -5,11 +5,25 @@ argument-hint: "[base-branch] (default: main)"
 
 You are reviewing the current branch's diff with parallel reviewers before creating a PR.
 
+Follow the `swarm-output-style` skill for ALL output formatting.
+
 ## Task
 $ARGUMENTS
 
 ## Workflow
 
+### Step 0: Show Pre-flight Plan
+
+Before creating any team or spawning any agent, show the plan:
+
+Show the pre-flight plan (see swarm-output-style skill). Include:
+- Base branch and diff summary (file count, approximate line count)
+- The 3 reviewers with model and focus area
+- Estimated cost (~$0.10 correctness, ~$0.10 security, ~$0.04 convention = ~$0.24 total)
+- Estimated time (~5-10 min)
+
+Wait for user approval before proceeding.
+
 ### Setup: Create Team
 1. Create a team with `TeamCreate` (name: `diff-review-<timestamp>`, e.g., `diff-review-1234`)
 2. Create tasks with `TaskCreate` for each reviewer focus area
@@ -21,13 +35,16 @@ Determine the base branch (default: `main` if no argument provided). Run:
 - Identify all changed files
 
 ### Step 2: Dispatch Reviewers (parallel)
+
+Show the phase banner with running total (see swarm-output-style skill).
+
 Spawn 3 reviewer teammates simultaneously, each with `team_name`, `name` (e.g., `reviewer-correctness`, `reviewer-security`, `reviewer-convention`), and `run_in_background: true`, each with the full diff, commit history, and project CLAUDE.md:
 
 1. **Correctness reviewer** (opus) — Logic errors, edge cases, off-by-ones, error handling, race conditions, resource leaks
 2. **Security reviewer** (opus) — OWASP top 10, auth issues, injection, data exposure, secrets in code
 3. **Convention reviewer** (sonnet) — Project patterns, naming, structure, CLAUDE.md compliance, test coverage
 
-As each reviewer teammate completes, send it a `shutdown_request` via `SendMessage` to close its split pane.
+As each completes: show a one-line verdict (PASS/FAIL + finding count) (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
 
 ### Step 3: Aggregate
 Merge all findings and categorize by priority:
@@ -36,21 +53,14 @@ Merge all findings and categorize by priority:
 - **Suggestion** — note in PR description (style, optional improvements)
 
 ### Step 4: Recommend
-Based on findings, give one recommendation:
-
-```
-## Diff Review Results
-
-### Findings
-| Priority | File | Line | Finding | Reviewer |
-|----------|------|------|---------|----------|
-| Critical | ...  | ...  | ...     | ...      |
 
-### Verdict
-- **Critical issues found** → "Fix these before creating a PR"
-- **Only Important/Suggestions** → "Ready for PR — consider addressing these"
-- **Clean** → "LGTM — ready for PR"
-```
+Show the full post-completion summary (see swarm-output-style skill). Include:
+- Status (PASS / NEEDS ATTENTION / FAILED)
+- Metrics (agents, duration, tokens, cost)
+- Review gate result with per-reviewer table (findings by severity)
+- Consolidated findings table (Priority | File | Line | Finding | Reviewer)
+- Verdict: "Fix these before creating a PR" / "Ready for PR — consider addressing these" / "LGTM — ready for PR"
+- Next steps (git push, gh pr create, or fix commands)
 
 ### Cleanup
 1. Send `shutdown_request` via `SendMessage` to any remaining active teammates
@@ -62,3 +72,5 @@ Based on findings, give one recommendation:
 - Include full diff context for each reviewer — they cannot access git
 - This workflow is read-only — report findings, never fix anything
 - Include file:line references for every finding
+- Follow the swarm-output-style skill for ALL output formatting
+- Show the plan first, spend tokens second

package/commands/discover.md

@@ -0,0 +1,102 @@
+---
+description: "Hypothesis-driven development — form theories, test cheaply, build the winner"
+argument-hint: "<complex problem where the right approach is unclear>"
+---
+
+You are running a discovery cycle: form hypotheses, test them cheaply, then implement the winner.
+
+Follow the `swarm-output-style` skill for ALL output formatting.
+
+## Task
+$ARGUMENTS
+
+## Workflow
+
+### Step 0: Show Pre-flight Plan
+
+Before creating any team or spawning any agent, show the plan:
+
+Show the pre-flight plan (see swarm-output-style skill). Include:
+- All phases (Hypothesize, Experiment, Implement, Review)
+- Agents per phase with model and focus
+- Estimated cost (~$0.12 hypothesize, ~$0.12 experiment at sonnet rates, ~$0.19 implement, ~$0.20 review)
+- Estimated time (~20-40 min total)
+
+Wait for user approval before proceeding.
+
+### Setup: Create Team
+1. Create a team with `TeamCreate` (name: `discover-<timestamp>`)
+2. Create tasks with `TaskCreate` for each work unit
+
+### Phase 1: Hypothesize — parallel
+
+Show the phase banner with running total (see swarm-output-style skill).
+
+Spawn 2-3 researcher teammates (sonnet) simultaneously, each with `team_name`, `name`, and `run_in_background: true`:
+- Each researcher explores a different angle of the problem
+- Each proposes a hypothesis: "I think the best approach is X because Y"
+- Each identifies what evidence would prove or disprove the hypothesis
+
+As each completes: show a one-line completion summary (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
+
+Present the hypotheses to the user. Select 2-3 to test.
+
+### Phase 2: Experiment — parallel (cheap, fast)
+
+Show the phase banner with running total (see swarm-output-style skill).
+
+Spawn 2-3 implementer teammates (sonnet, not opus — keep it cheap) simultaneously, each with `team_name`, `name`, and `run_in_background: true`:
+- Each builds a minimal proof-of-concept for one hypothesis
+- NOT a full implementation — just enough to validate or invalidate
+- Time-box: keep experiments under 5 minutes each
+- Each reports: hypothesis confirmed or rejected, with evidence
+
+As each completes: show a one-line completion summary (confirmed/rejected + key evidence) (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
+
+Present the experiment results. Identify the winning hypothesis.
+
+### Phase 3: Implement — sequential (depends on Phase 2)
+
+Show the phase banner with running total (see swarm-output-style skill).
+
+Spawn an implementer teammate (opus) with `team_name`, `name`, and `run_in_background: true`:
+- Full implementation of the winning approach
+- Informed by what was learned from ALL experiments (including failed ones)
+- Include tests
+
+As the teammate completes: show a one-line completion summary (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
+
+### Phase 4: Review — parallel (depends on Phase 3)
+
+Show the phase banner with running total (see swarm-output-style skill).
+
+Spawn 2 reviewer teammates (opus) simultaneously with `team_name`, `name`, and `run_in_background: true`:
+- **reviewer-correctness**: Logic, edge cases, error handling
+- **reviewer-convention**: Project patterns, code style
+
+As each completes: show a one-line verdict (PASS/FAIL + finding count) (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
+
+### Phase 5: Report
+
+Show the full post-completion summary (see swarm-output-style skill). Include:
+- Status (PASS / NEEDS ATTENTION / FAILED)
+- Metrics (phases, agents, duration, tokens, cost)
+- Hypotheses tested (table with confirmed/rejected)
+- Winner and rationale
+- What was learned from rejected hypotheses
+- What changed (files)
+- Review gate result
+- Next steps
+
+### Cleanup
+1. Send `shutdown_request` via `SendMessage` to any remaining active teammates
+2. Call `TeamDelete` to clean up the team
+
+## Rules
+- All agents must be spawned as team members (TeamCreate → TaskCreate → Agent with team_name/name/run_in_background → SendMessage shutdown → TeamDelete)
+- Experiments must be CHEAP — use sonnet, keep scope minimal, time-box to 5 minutes
+- Failed experiments are valuable — include their learnings in the final implementation context
+- The user approves the winning hypothesis before full implementation begins
+- If no hypothesis is clearly better, recommend combining the best elements from multiple experiments
+- Follow the swarm-output-style skill for ALL output formatting
+- Show the plan first, spend tokens second

package/commands/dynamic.md

@@ -0,0 +1,136 @@
+---
+description: "Let the planner decompose your task into a custom agent workflow -- no pattern selection needed"
+argument-hint: "<any task -- the planner figures out the approach>"
+---
+
+You are running a dynamic orchestration: instead of following a predefined pattern, the planner analyzes the task and builds a custom workflow.
+
+Follow the `swarm-output-style` skill for ALL output formatting.
+
+## Task
+$ARGUMENTS
+
+## Workflow
+
+### Step 0: Check Memory
+
+Search for relevant context:
+```bash
+cd ~/dev/swarm-engine && npx tsx src/cli/index.ts memory search "<relevant keywords>"
+```
+
+### Step 1: Analyze and Decompose
+
+You ARE the planner. Analyze the task and decompose it into subtasks. For each subtask, decide:
+
+1. **What agent type** should handle it (researcher, implementer, reviewer, tester, debugger, refactorer, etc.)
+2. **What model** it needs (expensive tasks like security review get claude-opus-4-6, simple tasks like scanning get claude-sonnet-4-6)
+3. **What dependencies** it has (which subtasks must complete before this one can start)
+4. **What files** it will touch (no two agents should modify the same files)
+
+Group subtasks into waves based on dependencies:
+- **Wave 1**: Independent tasks that can run in parallel (typically research)
+- **Wave 2**: Tasks that depend on Wave 1 results (typically implementation)
+- **Wave 3**: Tasks that depend on Wave 2 (typically review, testing)
+- Add more waves as needed
+
+### Step 2: Show Pre-flight Plan
+
+Present the decomposition as a pre-flight plan:
+
+```
+## Dynamic Orchestration Plan
+
+**Task**: [task description]
+**Waves**: [N] | **Agents**: [N] | **Est. cost**: ~$[amount] | **Est. time**: ~[duration]
+
+### Wave 1 -- parallel (~[time], ~$[cost])
+| Agent | Type | Model | Focus | Dependencies |
+|-------|------|-------|-------|-------------|
+| `name` | [type] | [model] | [what it does] | none |
+
+### Wave 2 -- parallel (~[time], ~$[cost])
+| Agent | Type | Model | Focus | Dependencies |
+|-------|------|-------|-------|-------------|
+| `name` | [type] | [model] | [what it does] | Wave 1 |
+
+[repeat for all waves]
+
+**File ownership:**
+| Agent | Files |
+|-------|-------|
+| `name` | [files this agent will touch] |
+
+Proceed?
+```
+
+Wait for user approval before proceeding.
+
+### Step 3: Create Team and Execute
+
+1. `TeamCreate` (name: `dynamic-<timestamp>`)
+2. `TaskCreate` for each wave
+
+Execute each wave in order:
+
+For each wave:
+1. Show the phase banner with running total
+2. Spawn all agents in this wave in parallel, each with `team_name`, `name`, and `run_in_background: true`
+3. Include context from all completed previous waves
+4. As each completes: show a one-line completion summary, then send `shutdown_request`
+5. After all agents in the wave complete: show wave summary
+
+**Between waves**: If any agent failed or returned low confidence, show error recovery options before proceeding to the next wave.
+
+### Step 4: Quality Gate
+
+After the final wave, assess the combined output:
+- Did all agents succeed?
+- Are there file conflicts or inconsistencies between agent outputs?
+- Do the changes compile/pass linting?
+
+If issues found, spawn a fixer agent to resolve them.
+
+### Step 5: Record and Report
+
+Store results in engine memory:
+```bash
+echo "<outcome summary>" | cd ~/dev/swarm-engine && npx tsx src/cli/index.ts memory store outcome "<title>" --repo "<repo>"
+```
+
+Show the full post-completion summary (see swarm-output-style skill). Include:
+- Status
+- Wave breakdown (which agents ran in each wave)
+- Metrics (waves, agents, duration, tokens, cost)
+- What changed (files with git diff --stat)
+- Quality gate result
+- Next steps
+
+### Cleanup
+1. Send `shutdown_request` to any remaining active teammates
+2. Call `TeamDelete` to clean up the team
+
+## Decomposition Guidelines
+
+When deciding how to break down a task:
+
+**Research first**: Always start with at least one researcher to understand the codebase before modifying it.
+
+**Parallelize aggressively**: If two subtasks touch different files and don't depend on each other, run them in parallel.
+
+**Right-size agents**: Use the cheapest model that can handle the task. Research and scanning with sonnet. Implementation and review with opus.
+
+**File ownership**: Each file should be owned by exactly one agent. If two agents need the same file, make one depend on the other.
+
+**Review everything**: The final wave should always include at least one reviewer checking the combined output.
+
+**Keep it simple**: Most tasks need 2-4 waves and 3-8 agents. Don't over-decompose a task that one agent could handle. If the task is simple, use 1 wave with 1-2 agents.
+
+## Rules
+- Show the plan first, spend tokens second
+- All agents must use team protocol (TeamCreate, Agent with team_name/name/run_in_background, SendMessage shutdown, TeamDelete)
+- No two agents modify the same files in the same wave
+- Every agent dispatch includes full context from previous waves
+- Always include a review step in the final wave
+- Follow the swarm-output-style skill for ALL output formatting
+- Maximum 6 waves -- if you need more, the task should be split into separate orchestrations

package/commands/fix-pr.md

@@ -5,6 +5,8 @@ argument-hint: "<PR number or URL>"
 
 You are fixing PR review comments by dispatching parallel implementers grouped by file.
 
+Follow the `swarm-output-style` skill for ALL output formatting.
+
 ## Task
 $ARGUMENTS
 
@@ -25,46 +27,48 @@ For each file group, classify every comment:
 - **Nit/style fix** → assign to implementer (sonnet)
 - **Question/discussion** → skip, include in report
 
-### Step 3: Present Plan
-Show the user the dispatch plan:
+### Step 3: Show Pre-flight Plan
+
+Show the pre-flight plan (see swarm-output-style skill). Use the dispatch plan format:
 
 ```
-## Fix Plan
+## Orchestration Plan
+
+**Task**: Fix [N] review comments across [M] file groups for PR #[number]
+**Pattern**: parallel-fix | **Phases**: 1 | **Agents**: [N] | **Est. cost**: ~$[amount] | **Est. time**: ~[duration]
 
-| File Group | Comments | Agent | Model | Summary |
-|------------|----------|-------|-------|---------|
-| src/foo.py | 3        | implementer | opus   | [what to fix] |
-| src/bar.py | 1        | implementer | sonnet | [style nit] |
-| src/baz.py | 2        | — (skipped) | —      | [questions only] |
+### Phase 1: Fix -- parallel (~[time], ~$[cost])
+| Agent | Model | Focus |
+|-------|-------|-------|
+| `fixer-foo` | opus   | src/foo.py — [what to fix] |
+| `fixer-bar` | sonnet | src/bar.py — [style nit] |
+| `fixer-baz` | —      | src/baz.py — SKIPPED (questions only) |
+
+Proceed?
 ```
 
-Ask the user to approve before proceeding.
+Wait for user approval before proceeding.
 
 ### Step 4: Dispatch Implementers
+
+Show the phase banner with running total (see swarm-output-style skill).
+
 Spawn one implementer teammate per file group, ALL in parallel, each with `team_name`, `name` (e.g., `fixer-foo`, `fixer-bar`), and `run_in_background: true`. Each dispatch includes:
 - The exact comment text for their file(s)
 - The full PR diff for context
 - The original PR description
 - Clear instructions on what to change
 
-As each teammate completes, send it a `shutdown_request` via `SendMessage` to close its split pane.
+As each completes: show a one-line completion summary (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
 
 ### Step 5: Report
-Once all implementers complete, produce a summary:
 
-```
-## PR Fix Report
-
-### Comments Addressed
-- [file:line — what was fixed, which comment]
-
-### Comments Skipped
-- [file:line — why (question/discussion)]
-
-### Next Steps
-- Push changes: `git push`
-- Re-request review: `gh pr edit <the PR> --add-reviewer [reviewer]`
-```
+Show the full post-completion summary (see swarm-output-style skill). Include:
+- Status (PASS / NEEDS ATTENTION)
+- Metrics (agents, duration, tokens, cost)
+- Comments addressed (file:line — what was fixed, which comment)
+- Comments skipped (file:line — why)
+- Next steps (git push, re-request review)
 
 ### Cleanup
 1. Send `shutdown_request` via `SendMessage` to any remaining active teammates
@@ -76,3 +80,5 @@ Once all implementers complete, produce a summary:
 - Group by file to avoid merge conflicts between parallel implementers
 - Include the exact comment text in each implementer dispatch
 - Use opus for logic/behavior changes, sonnet for style/nit fixes
+- Follow the swarm-output-style skill for ALL output formatting
+- Show the plan first, spend tokens second