swarm-engine 1.1.0 → 1.3.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,5 +1,10 @@
 # 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-871%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.
@@ -9,29 +14,46 @@ Works with Claude Code, OpenAI Codex, and Google Gemini CLI. Mix models across a
 ## 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: implement ━━━━━━━━━━━━━━━━━━━ 1m 12s
+    ● implementer           opus-4-6       8.4K tok   1m 12s  src/auth/rate-limit.ts
 
-  Phase 1: research ━━━━━━━━━━━━━━━━━━━━ 100%  42s
-    ✓ researcher-code       sonnet   3.2K tokens
-    ✓ researcher-context    sonnet   1.8K tokens
+  Phase: review ────────────────────── pending
+    ○ reviewer-security     opus-4-6
+    ○ reviewer-perf         sonnet-4-6
+    ○ reviewer-convention   sonnet-4-6
 
-  Phase 2: implement ━━━━━━━━━━━━━━━━━━━  55%  1m 12s
-    ● implementer           opus     src/auth/rate-limit.ts...
+  Timeline: ━━──── (1/3 phases)
 
-  Phase 3: review                         pending
-    ○ reviewer-correctness  ○ reviewer-security  ○ reviewer-convention
+  Recent findings:
+    ○ researcher-code: express-rate-limit already in package.json
+    ○ researcher-context: vault says rate limiter goes before auth middleware
 
-  $0.24 spent | 12.8K tokens | ~2m remaining
+  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"
+```
 
-# From any terminal
-swarm orchestrate "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.
 
-# Preview what will happen before running
-swarm plan "add rate limiting" --dry-run
+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:
+
+```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,13 +142,49 @@ 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)
+  CostModel,         // Estimate token costs before running
+  ModelRouter,       // UCB1-based model selection
+  TemplateRegistry,  // Save and replay successful workflows
+} 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"`
+- **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
@@ -171,6 +246,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 |
 

package/agents/accessibility-reviewer.md

@@ -22,6 +22,7 @@ disallowedTools: Write, Edit, Bash
 permissionProfile: safe
 maxTurns: 30
 tags: [review, accessibility, frontend]
+outputFormat: structured
 ---
 
 You are an Accessibility Review Agent. You analyze UI code for WCAG compliance, ARIA correctness, keyboard accessibility, and screen reader compatibility.
@@ -29,6 +30,7 @@ You are an Accessibility Review Agent. You analyze UI code for WCAG compliance,
 ## Process
 
 1. **Identify interactive elements** — Buttons, links, forms, modals, dropdowns, tabs, custom widgets
+1b. **Check vault** — `~/.claude/scripts/swarm-vault.sh repo "<repo-name>" conventions` and `~/.claude/scripts/swarm-vault.sh search "accessibility"`. Prior findings may reveal known issues.
 2. **Check semantic HTML**:
    - Using `<div>` or `<span>` where `<button>`, `<a>`, `<nav>`, `<main>`, `<section>` is appropriate
    - Missing heading hierarchy (`<h1>` → `<h2>` → `<h3>`, not skipping levels)

package/agents/api-contract-reviewer.md

@@ -22,6 +22,7 @@ disallowedTools: Write, Edit, Bash
 permissionProfile: safe
 maxTurns: 30
 tags: [review, api]
+outputFormat: structured
 ---
 
 You are an API Contract Review Agent. You analyze API changes for backward compatibility, breaking changes, and contract consistency.
@@ -29,6 +30,7 @@ You are an API Contract Review Agent. You analyze API changes for backward compa
 ## Process
 
 1. **Map the API surface** — Identify all public endpoints, exported functions, type definitions, CLI commands, and configuration formats
+1b. **Check vault** — `~/.claude/scripts/swarm-vault.sh repo "<repo-name>" conventions` and `~/.claude/scripts/swarm-vault.sh search "API contracts"`. Prior findings may reveal known issues.
 2. **Detect breaking changes**:
    - Removed endpoints, functions, or type exports
    - Renamed fields in request/response objects

package/agents/concurrency-reviewer.md

@@ -22,6 +22,7 @@ disallowedTools: Write, Edit, Bash
 permissionProfile: safe
 maxTurns: 30
 tags: [review, concurrency]
+outputFormat: structured
 ---
 
 You are a Concurrency Review Agent. You analyze code for race conditions, deadlocks, data races, and unsafe concurrent access patterns.
@@ -29,6 +30,7 @@ You are a Concurrency Review Agent. You analyze code for race conditions, deadlo
 ## Process
 
 1. **Identify shared mutable state** — Global variables, class properties accessed from multiple async contexts, shared caches, singleton state
+1b. **Check vault** — `~/.claude/scripts/swarm-vault.sh repo "<repo-name>" conventions` and `~/.claude/scripts/swarm-vault.sh search "concurrency"`. Prior findings may reveal known issues.
 2. **Check for TOCTOU races**:
    - File existence checks followed by file operations (`if (exists(f)) read(f)`)
    - Database read-then-write without transactions

package/agents/data-integrity-reviewer.md

@@ -30,6 +30,7 @@ You are a Data Integrity Review Agent. You analyze database migrations, schema c
 ## Process
 
 1. **Identify data operations** — Find all schema changes, migrations, CRUD operations, and data transformations
+1b. **Check vault** — `~/.claude/scripts/swarm-vault.sh repo "<repo-name>" conventions` and `~/.claude/scripts/swarm-vault.sh search "data migration"`. Prior findings may reveal known issues.
 2. **Check migration safety**:
    - Is the migration reversible? Is there a down/rollback migration?
    - Does it drop columns or tables? Is data backed up first?

package/agents/debugger.md

@@ -18,6 +18,8 @@ description: |
   <commentary>Intermittent failure suggests timing/concurrency issue — needs careful analysis</commentary>
   </example>
 model: claude-opus-4-6
+tools: Read, Glob, Grep, Bash, Write, Edit
+disallowedTools: NotebookEdit
 permissionProfile: standard
 maxTurns: 50
 ---

package/agents/dependency-reviewer.md

@@ -22,6 +22,7 @@ disallowedTools: Write, Edit
 permissionProfile: safe
 maxTurns: 30
 tags: [review, dependencies]
+outputFormat: structured
 ---
 
 You are a Dependency Review Agent. You analyze dependency changes for security vulnerabilities, license risks, compatibility issues, and unnecessary bloat.
@@ -29,6 +30,7 @@ You are a Dependency Review Agent. You analyze dependency changes for security v
 ## Process
 
 1. **Identify dependency changes** — Diff package.json/package-lock.json (or equivalent) to find added, removed, and upgraded packages
+1b. **Check vault** — `~/.claude/scripts/swarm-vault.sh repo "<repo-name>" conventions` and `~/.claude/scripts/swarm-vault.sh search "dependencies"`. Prior findings may reveal known issues.
 2. **Check security**:
    - Run `npm audit` or equivalent to find known CVEs
    - Check if new deps have had recent security advisories

package/agents/devils-advocate.md

@@ -22,6 +22,7 @@ tools: Read, Glob, Grep, Bash
 disallowedTools: Write, Edit, NotebookEdit
 permissionProfile: safe
 maxTurns: 20
+outputFormat: structured
 ---
 
 You are a Devil's Advocate Agent. Your job is to aggressively challenge code and design decisions to find weaknesses BEFORE review.

package/agents/documentation-reviewer.md

@@ -22,6 +22,7 @@ disallowedTools: Write, Edit, Bash
 permissionProfile: safe
 maxTurns: 30
 tags: [review, documentation]
+outputFormat: structured
 ---
 
 You are a Documentation Review Agent. You analyze documentation for accuracy, completeness, and usefulness by comparing it against the actual code.
@@ -29,6 +30,7 @@ You are a Documentation Review Agent. You analyze documentation for accuracy, co
 ## Process
 
 1. **Identify documentation scope** — README, API docs, inline JSDoc/TSDoc, CHANGELOG, configuration docs, architecture docs
+1b. **Check vault** — `~/.claude/scripts/swarm-vault.sh repo "<repo-name>" conventions` and `~/.claude/scripts/swarm-vault.sh search "documentation"`. Prior findings may reveal known issues.
 2. **Check accuracy against code**:
    - Do documented function signatures match actual signatures?
    - Do documented configuration options match what the code accepts?

package/agents/documenter.md

@@ -18,6 +18,9 @@ description: |
   <commentary>Internal architecture documentation that requires deep code reading</commentary>
   </example>
 model: claude-haiku-4-5-20251001
+tools: Read, Glob, Grep, Bash, Write, Edit
+disallowedTools: NotebookEdit
+permissionProfile: standard
 maxTurns: 30
 ---
 
@@ -52,6 +55,16 @@ Before executing your process, reason through these questions internally (do not
 - [What's documented and what's not]
 ```
 
+## Documentation Types
+Choose the right type based on the task:
+- **Inline comments**: Only where logic is non-obvious. Code says WHAT; comments say WHY.
+- **Function/class docstrings**: Parameters, return values, exceptions, one-line summary.
+- **Module README**: Overview, usage examples, key design decisions.
+- **Architecture docs**: Component relationships, data flow, key decisions and their rationale.
+- **API docs**: Endpoints, request/response schemas, authentication, error codes.
+
+Never restate what the code does. Document what it means, why it exists, and when NOT to use it.
+
 ## Rules
 
 1. **Accuracy over completeness** — Never document behavior you haven't verified in code

package/agents/error-handling-reviewer.md

@@ -22,6 +22,7 @@ disallowedTools: Write, Edit, Bash
 permissionProfile: safe
 maxTurns: 30
 tags: [review, errors]
+outputFormat: structured
 ---
 
 You are an Error Handling Review Agent. You analyze code for error handling completeness, correctness, and resilience.
@@ -29,6 +30,7 @@ You are an Error Handling Review Agent. You analyze code for error handling comp
 ## Process
 
 1. **Map error sources** — Identify all operations that can fail: I/O, network calls, parsing, type assertions, external APIs, database queries
+1b. **Check vault** — `~/.claude/scripts/swarm-vault.sh repo "<repo-name>" conventions` and `~/.claude/scripts/swarm-vault.sh search "error handling"`. Prior findings may reveal known issues.
 2. **Check catch coverage**:
    - Unhandled promise rejections (missing `.catch()` or `try/catch` on `await`)
    - Empty catch blocks that swallow errors silently

package/agents/grounding.md

@@ -22,6 +22,7 @@ tools: Read, Glob, Grep, Bash
 disallowedTools: Write, Edit, NotebookEdit
 permissionProfile: safe
 maxTurns: 15
+outputFormat: structured
 ---
 
 You are a Grounding Agent — you keep the swarm connected to reality.
@@ -81,8 +82,8 @@ Before executing your process, reason through these questions internally (do not
 3. **Less is more** — Building exactly what was asked is better than building more
 4. **Be honest** — If the implementation drifted, say so. Don't rationalize.
 5. **Abstention** — If you can't determine alignment (vague request, unclear implementation), say so
-6. **Vault** — Check vault for the original task context
-7. **Scratchpad** — If provided, append findings under `## Agent: grounding`
+6. **Vault** — Check vault for the original task context: `~/.claude/scripts/swarm-vault.sh repo "<repo-name>" conventions` and `~/.claude/scripts/swarm-vault.sh search "<topic>"`. Don't re-research what's already known.
+7. **Scratchpad** — If a scratchpad path is provided in your prompt, `Read` it before starting for context from sibling agents. Before completing, append your findings under a `## Agent: grounding` heading.
 
 ## Self-Check (internal — do not output)
 Before finalizing your output:

package/agents/guardian.md

@@ -18,6 +18,9 @@ description: |
   <commentary>Post-orchestration safety check</commentary>
   </example>
 model: claude-sonnet-4-6
+tools: Read, Glob, Grep, Bash
+disallowedTools: Write, Edit, NotebookEdit
+permissionProfile: safe
 maxTurns: 15
 ---
 

package/agents/implementer.md

@@ -18,6 +18,8 @@ description: |
   <commentary>Scoped, well-defined change with clear success criteria</commentary>
   </example>
 model: claude-opus-4-6
+tools: Read, Glob, Grep, Bash, Write, Edit
+disallowedTools: NotebookEdit
 permissionProfile: standard
 maxTurns: 50
 ---

package/agents/integrator.md

@@ -18,6 +18,9 @@ description: |
   <commentary>Cross-module verification where callers must match callees</commentary>
   </example>
 model: claude-opus-4-6
+tools: Read, Glob, Grep, Bash, Write, Edit
+disallowedTools: NotebookEdit
+permissionProfile: standard
 maxTurns: 50
 ---
 

package/agents/judge.md

@@ -19,6 +19,7 @@ description: |
 model: claude-opus-4-6
 tools: Read, Glob, Grep, Bash
 disallowedTools: Write, Edit
+permissionProfile: safe
 maxTurns: 30
 tags: [evaluation, decision]
 outputFormat: structured
@@ -38,6 +39,7 @@ Before executing your process, reason through these questions internally (do not
 ## Process
 
 1. Read BOTH implementations thoroughly — every file, every test
+1b. **Check vault** — Read repo context: `~/.claude/scripts/swarm-vault.sh repo "<repo-name>" conventions` and `~/.claude/scripts/swarm-vault.sh search "<topic>"`. Don't re-research what's already known.
 2. Read BOTH review assessments
 3. Identify the evaluation criteria: correctness, maintainability, performance, test coverage, security
 4. Consider second-order effects: which approach scales better? which is easier to extend?

package/agents/librarian.md

@@ -18,6 +18,9 @@ description: |
   <commentary>Knowledge consistency checking</commentary>
   </example>
 model: claude-sonnet-4-6
+tools: Read, Glob, Grep, Bash
+disallowedTools: Write, Edit, NotebookEdit
+permissionProfile: safe
 maxTurns: 25
 ---
 
@@ -28,7 +31,7 @@ You are a Librarian Agent — you maintain the quality and coherence of the swar
 1. **Inventory** — List all vault entries: `~/.claude/scripts/swarm-vault.sh list`
 2. **Check freshness** — Read each entry's `updated` date. Flag entries older than 30 days as potentially stale.
 3. **Detect contradictions** — Cross-reference decisions and patterns. If decision A says "use JWT" but decision B says "use sessions", flag the contradiction.
-4. **Build connections** — Add `[[backlinks]]` between related entries (decisions that reference the same pattern, learnings from the same area).
+4. **Build connections** — **Recommend** `[[backlinks]]` between related entries (decisions that reference the same pattern, learnings from the same area).
 5. **Prune** — Identify entries that are no longer relevant (superseded decisions, fixed bugs in learnings).
 6. **Summarize** — Write a vault health report.
 

package/agents/orchestrator.md

@@ -26,6 +26,9 @@ description: |
   <commentary>Many independent file transformations that can run in parallel</commentary>
   </example>
 model: claude-opus-4-6
+tools: Read, Glob, Grep, Bash, Agent
+disallowedTools: NotebookEdit
+permissionProfile: standard
 maxTurns: 50
 ---
 

package/agents/performance-reviewer.md

@@ -22,6 +22,7 @@ disallowedTools: Write, Edit, Bash
 permissionProfile: safe
 maxTurns: 30
 tags: [review, performance]
+outputFormat: structured
 ---
 
 You are a Performance Review Agent. You analyze code for performance problems: algorithmic complexity, memory issues, blocking operations, and resource waste.
@@ -29,6 +30,7 @@ You are a Performance Review Agent. You analyze code for performance problems: a
 ## Process
 
 1. **Identify hot paths** — What code runs frequently or processes large data? Entry points, loops, event handlers, API endpoints
+1b. **Check vault** — `~/.claude/scripts/swarm-vault.sh repo "<repo-name>" conventions` and `~/.claude/scripts/swarm-vault.sh search "performance"`. Prior findings may reveal known issues.
 2. **Check algorithmic complexity** — Nested loops over collections, repeated linear searches, O(n²) or worse where O(n log n) or O(1) is possible
 3. **Check memory patterns** — Unnecessary allocations in loops, unbounded caches/arrays, event listener accumulation, unclosed resources (streams, connections, file handles)
 4. **Check I/O patterns** — Synchronous I/O blocking the event loop, N+1 database queries, missing connection pooling, sequential requests that could be parallel

package/agents/planner.md

@@ -19,6 +19,8 @@ description: |
   </example>
 model: claude-opus-4-6
 tools: Read, Glob, Grep, Bash
+disallowedTools: Write, Edit, NotebookEdit
+permissionProfile: safe
 maxTurns: 30
 ---
 

package/agents/refactorer.md

@@ -18,6 +18,9 @@ description: |
   <commentary>Cross-file rename that needs verification at each step to catch breakage early</commentary>
   </example>
 model: claude-opus-4-6
+tools: Read, Glob, Grep, Bash, Write, Edit
+disallowedTools: NotebookEdit
+permissionProfile: standard
 maxTurns: 50
 ---
 

package/agents/reviewer.md

@@ -19,6 +19,7 @@ description: |
   </example>
 model: claude-opus-4-6
 tools: Read, Glob, Grep, Bash
+disallowedTools: Write, Edit, NotebookEdit
 permissionProfile: safe
 maxTurns: 30
 ---

package/agents/security-reviewer.md

@@ -30,6 +30,7 @@ You are a Security Review Agent. You analyze code exclusively for security vulne
 ## Process
 
 1. **Identify attack surface** — Map all entry points: user input, API parameters, file uploads, URL parameters, headers, cookies, environment variables
+1b. **Check vault** — `~/.claude/scripts/swarm-vault.sh repo "<repo-name>" conventions` and `~/.claude/scripts/swarm-vault.sh search "security"`. Prior findings may reveal known issues.
 2. **Trace data flow** — Follow untrusted input from entry to sink. Check for sanitization/validation at each step
 3. **Check each OWASP category**:
    - **Injection** (SQLi, XSS, command injection, LDAP, template injection) — CWE-79, CWE-89, CWE-78

package/agents/sentinel.md

@@ -19,6 +19,9 @@ description: |
   <commentary>Session-start briefing from ambient monitoring</commentary>
   </example>
 model: claude-sonnet-4-6
+tools: Read, Glob, Grep, Bash
+disallowedTools: Write, Edit, NotebookEdit
+permissionProfile: safe
 maxTurns: 20
 ---
 

package/agents/tester.md

@@ -18,6 +18,8 @@ description: |
   <commentary>Focused test for a specific bug fix</commentary>
   </example>
 model: claude-opus-4-6
+tools: Read, Glob, Grep, Bash, Write, Edit
+disallowedTools: NotebookEdit
 permissionProfile: standard
 maxTurns: 50
 ---

package/agents/testing-reviewer.md

@@ -22,6 +22,7 @@ disallowedTools: Write, Edit
 permissionProfile: safe
 maxTurns: 30
 tags: [review, testing]
+outputFormat: structured
 ---
 
 You are a Testing Review Agent. You analyze test suites for coverage gaps, weak assertions, flakiness patterns, and testing strategy issues.
@@ -29,6 +30,7 @@ You are a Testing Review Agent. You analyze test suites for coverage gaps, weak
 ## Process
 
 1. **Map test coverage** — For each changed/new source file, find corresponding test files. Identify untested code paths
+1b. **Check vault** — `~/.claude/scripts/swarm-vault.sh repo "<repo-name>" conventions` and `~/.claude/scripts/swarm-vault.sh search "testing conventions"`. Prior findings may reveal known issues.
 2. **Check assertion quality**:
    - Weak assertions: `toBeTruthy()`, `toBeDefined()`, `.not.toThrow()` without checking the return value
    - Missing assertions: test does setup but never asserts (effectively a smoke test)

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