swarm-engine 1.0.0

package/skills/design-system/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: design-system
+description: |
+  Project design system for consistent, high-quality UI across all implementations.
+  TRIGGER when: building any frontend, UI, web page, component, dashboard, form, or
+  user-facing interface. Also triggers on: "style", "design", "layout", "theme",
+  "CSS", "component", "page", "responsive".
+  DO NOT TRIGGER for: backend code, scripts, CLI tools, documentation.
+---
+
+# Design System
+
+This is the project's visual identity. Follow it exactly. Do not deviate.
+
+## Aesthetic: Clean, Light, Spacious
+
+Inspired by Vercel and Stripe — precision engineering expressed visually. Every pixel is intentional. Nothing decorative. Nothing gratuitous.
+
+**The feel:** Calm authority. Like a well-designed instrument — everything exactly where it should be, nothing extra.
+
+## Typography
+
+**Font stack (in order of preference):**
+- Headings: `'Geist', 'Inter', -apple-system, BlinkMacSystemFont, sans-serif`
+- Body: `'Geist', 'Inter', -apple-system, BlinkMacSystemFont, sans-serif`
+- Code/monospace: `'Geist Mono', 'JetBrains Mono', 'SF Mono', 'Fira Code', monospace`
+
+**Scale:**
+```
+--text-xs:    0.75rem   / 12px
+--text-sm:    0.875rem  / 14px
+--text-base:  1rem      / 16px
+--text-lg:    1.125rem  / 18px
+--text-xl:    1.25rem   / 20px
+--text-2xl:   1.5rem    / 24px
+--text-3xl:   1.875rem  / 30px
+--text-4xl:   2.25rem   / 36px
+```
+
+**Rules:**
+- Body text: 16px, line-height 1.6, `--color-text-secondary` for most text
+- Headings: semibold (600), tight letter-spacing (-0.02em), `--color-text-primary`
+- Labels/captions: 12-14px, uppercase tracking (0.05em), `--color-text-tertiary`
+- Never bold body text. Use weight only for headings and emphasis.
+- Maximum line width: 65ch for prose, 80ch for code
+
+## Color
+
+**Light mode (default):**
+```
+--color-bg:              #ffffff
+--color-bg-subtle:       #fafafa
+--color-bg-muted:        #f4f4f5
+--color-bg-elevated:     #ffffff   (with shadow)
+
+--color-border:          #e4e4e7
+--color-border-subtle:   #f4f4f5
+
+--color-text-primary:    #09090b
+--color-text-secondary:  #3f3f46
+--color-text-tertiary:   #a1a1aa
+
+--color-accent:          #18181b   (near-black — the Vercel approach)
+--color-accent-hover:    #27272a
+
+--color-success:         #22c55e
+--color-warning:         #f59e0b
+--color-error:           #ef4444
+--color-info:            #3b82f6
+```
+
+**Dark mode:**
+```
+--color-bg:              #09090b
+--color-bg-subtle:       #18181b
+--color-bg-muted:        #27272a
+--color-bg-elevated:     #18181b   (with subtle border)
+
+--color-border:          #27272a
+--color-border-subtle:   #1c1c1e
+
+--color-text-primary:    #fafafa
+--color-text-secondary:  #a1a1aa
+--color-text-tertiary:   #71717a
+
+--color-accent:          #fafafa   (near-white)
+--color-accent-hover:    #e4e4e7
+```
+
+**Rules:**
+- No gradients unless they serve a specific purpose
+- No colored backgrounds for sections — use whitespace to separate
+- Accent color is near-black (light) or near-white (dark) — let the content be the color
+- Status colors (success/warning/error) used sparingly, only for actual status
+- Never use blue for links — use `--color-text-primary` with underline on hover
+
+## Spacing
+
+**Scale (8px base):**
+```
+--space-1:   0.25rem   / 4px
+--space-2:   0.5rem    / 8px
+--space-3:   0.75rem   / 12px
+--space-4:   1rem      / 16px
+--space-5:   1.25rem   / 20px
+--space-6:   1.5rem    / 24px
+--space-8:   2rem      / 32px
+--space-10:  2.5rem    / 40px
+--space-12:  3rem      / 48px
+--space-16:  4rem      / 64px
+--space-20:  5rem      / 80px
+--space-24:  6rem      / 96px
+```
+
+**Rules:**
+- Page padding: `--space-6` minimum on mobile, `--space-16` on desktop
+- Section spacing: `--space-16` to `--space-24` between major sections
+- Card padding: `--space-6` to `--space-8`
+- Generous whitespace always. When in doubt, add more space.
+- Consistent rhythm — pick a spacing value and repeat it. Don't use 7 different margins.
+
+## Layout
+
+**Grid:** 12-column on desktop, single column on mobile. Max content width: 1200px.
+
+**Rules:**
+- Left-aligned content, not centered (unless it's a hero/landing)
+- No card grids where a simple list would do
+- Navigation: top bar or left sidebar, never both
+- Content hierarchy through typography and spacing, not boxes and borders
+- Forms: single column, full-width inputs, clear labels above (not inline)
+- Tables: clean, minimal borders (top/bottom only or none), generous row padding
+
+## Components
+
+**Buttons:**
+- Primary: `--color-accent` bg, white text, no border, subtle hover darkening
+- Secondary: transparent bg, `--color-border` border, text color matches border
+- Size: 36px height default, 14px font, `--space-4` horizontal padding
+- Border-radius: 6px (not fully rounded — that's a fad)
+- No shadows on buttons. No gradients.
+
+**Inputs:**
+- Height: 40px
+- Border: 1px `--color-border`
+- Border-radius: 6px
+- Focus: 2px ring in `--color-accent` with 2px offset
+- Background: `--color-bg` (not gray)
+- Placeholder text: `--color-text-tertiary`
+
+**Cards:**
+- Background: `--color-bg-elevated`
+- Border: 1px `--color-border-subtle` OR shadow, never both
+- Shadow (if used): `0 1px 3px rgba(0,0,0,0.04), 0 1px 2px rgba(0,0,0,0.06)`
+- Border-radius: 8px
+- No colored headers. No icons in corners.
+
+**Tables:**
+- No zebra striping
+- Header: semibold, `--color-text-tertiary`, uppercase 12px with tracking
+- Rows: `--color-border-subtle` bottom border only
+- Cell padding: `--space-3` vertical, `--space-4` horizontal
+- Align numbers right, text left
+
+## Animations
+
+- Duration: 150ms for micro-interactions, 300ms for layout changes
+- Easing: `cubic-bezier(0.4, 0, 0.2, 1)` (Material standard)
+- What to animate: opacity, transform (translate/scale), color, border-color
+- What NOT to animate: width, height, margin, padding (causes layout thrash)
+- Page transitions: fade (opacity 0→1, 150ms)
+- No bouncing, no elastic, no spring physics unless it's a playful context
+
+## Anti-Patterns (NEVER do these)
+
+- Colored section backgrounds (the "alternating gray/white sections" pattern)
+- Hero sections with stock imagery or abstract gradients
+- Card grids with icons and 3 bullet points (the "SaaS features" pattern)
+- Rounded pill buttons on everything
+- Drop shadows on everything
+- "Glass morphism" / frosted glass on cards
+- Centering everything — left-align by default
+- Using 5+ font weights — stick to regular (400) and semibold (600)
+- Purple-to-blue gradients (the universal AI slop gradient)
+- Emoji as design elements in professional interfaces
+
+## Implementation
+
+When building a new page or component:
+1. Check if the project has an existing CSS/design system — use it
+2. If starting fresh, implement these tokens as CSS custom properties
+3. Use Tailwind if the project uses it — but follow THIS system's values, not Tailwind defaults
+4. Semantic HTML first, styling second
+5. Mobile-first responsive design
+6. Support both light and dark mode via `prefers-color-scheme`

package/skills/orchestration-patterns/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: orchestration-patterns
+description: |
+  Knowledge about swarm orchestration patterns for coordinating parallel sub-agents.
+  TRIGGER when: user mentions "orchestrate", "parallel agents", "fan-out", "swarm",
+  "dispatch agents", "agent coordination", "concurrent", "multi-agent", "batch migration",
+  "red-team", "debate", "chaos", "emergence", "adversarial", "brownian", "builder breaker",
+  "ambient", "background", "discover", "hypothesis", "experiment", "grounding",
+  "reality check", "human role",
+  or asks how to break a task into parallel work.
+  DO NOT TRIGGER for simple tasks that don't need orchestration.
+---
+
+# Swarm Orchestration Patterns
+
+## Quick Reference
+
+### When to Orchestrate
+Use orchestration when a task has **3+ independent work units** that can run concurrently.
+Do NOT orchestrate simple, linear tasks — the overhead isn't worth it.
+
+### Pattern Selection
+
+| Pattern | When to Use | Example |
+|---------|------------|---------|
+| **Fan-out/Fan-in** | N independent tasks, aggregate results | Research 5 different aspects of a system |
+| **Pipeline** | Sequential dependencies, each step feeds the next | Parse → Transform → Validate → Write |
+| **Hybrid** | Research first, then implement, then review | Most feature development |
+| **Review Cycle** | Implementation needs quality gates | Security-sensitive changes |
+| **Batch** | Same operation on many targets | Migrate 20 files to new format |
+| **Competitive** | Optimal approach is uncertain | Spike: try 2 approaches, pick best |
+| **Iterative** | Quality gate required before shipping | Security-sensitive changes, complex logic |
+| **Adversarial** | Need to verify robustness, security-critical code | /red-team: build + break simultaneously |
+| **Debate** | Uncertain code quality, need multi-perspective consensus | /debate: multi-round argumentation |
+| **Chaos** | Broad improvements with no specific requirements | /chaos: brownian ratchet, CI filters |
+| **Emergence** | Experimental — can agents self-organize? | /emergence: identical agents, no roles |
+
+### Model Routing
+
+| Task | Model | Rationale |
+|------|-------|-----------|
+| File search, listing, simple greps | haiku | Fast, cheap, sufficient for pattern matching |
+| Documentation writing | haiku | Straightforward content generation |
+| Codebase exploration, tracing flows | sonnet | Needs comprehension but not generation |
+| Convention review | sonnet | Pattern matching against existing style |
+| Code implementation | opus | Writing correct code requires deep reasoning |
+| Security review | opus | Must catch subtle vulnerabilities |
+| Correctness review | opus | Must reason about edge cases and logic |
+| Debugging | opus | Root cause analysis requires deep understanding |
+| Architecture decisions | opus | Complex trade-off reasoning |
+| Test writing (complex) | opus | Must understand code deeply to test it well |
+
+### Dispatch Checklist
+Before dispatching a sub-agent, verify your prompt includes:
+- [ ] Specific file paths and line numbers to focus on
+- [ ] Relevant context from prior phases
+- [ ] Clear success criteria
+- [ ] Project conventions (from CLAUDE.md if present)
+- [ ] Scope boundaries (what NOT to touch)
+- [ ] Scratchpad path included for cross-agent communication
+- [ ] Self-assessment fields (Confidence, Blockers, Files touched) requested in output
+- [ ] Agent spawned as team member (team_name, name, run_in_background: true)
+
+### Anti-Patterns to Avoid
+1. **Over-orchestration**: Don't use 5 agents for a 10-line change
+2. **Starving context**: Sub-agents can't ask questions — give them everything
+3. **File conflicts**: Two agents editing the same file = merge hell
+4. **Model waste**: Don't use opus for file search or documentation
+5. **Sequential disguised as parallel**: If B depends on A's output, don't pretend they're parallel
+
+### Cost Estimation Reference
+
+| Model | Typical per-agent cost | Use for |
+|-------|----------------------|---------|
+| haiku | ~$0.02 | File search, documentation, simple greps |
+| sonnet | ~$0.08 | Research, exploration, convention review |
+| opus | ~$0.40 | Implementation, security review, debugging, testing |
+
+Include estimated cost in every orchestration plan: sum of (agent count × per-model cost).
+
+For detailed pattern documentation, see the references/ directory.

package/skills/orchestration-patterns/examples/example-workflows.md

@@ -0,0 +1,290 @@
+# Example Orchestration Workflows
+
+## Example 1: Feature Development (Hybrid Pattern)
+
+**Task**: "Add WebSocket support to the notification system"
+
+```
+Phase 1: Research (parallel, 3 agents, sonnet)
+├── Researcher A: Current notification architecture (models, routes, services)
+├── Researcher B: Existing WebSocket patterns in codebase (if any)
+└── Researcher C: Test infrastructure and patterns for async code
+
+Phase 2: Architecture (sequential, 1 agent, opus)
+└── Orchestrator synthesizes research → proposes WebSocket architecture
+
+Phase 3: Implementation (parallel, 2 agents, opus)
+├── Implementer A: WebSocket server + connection manager
+└── Implementer B: Client notification handlers + event types
+
+Phase 4: Testing (parallel, 2 agents, opus)
+├── Tester A: Unit tests for WebSocket server
+└── Tester B: Integration tests for notification flow
+
+Phase 5: Review (parallel, 2 agents, opus)
+├── Reviewer A: Correctness + error handling review
+└── Reviewer B: Security review (auth, connection limits, data exposure)
+
+Result: 10 sub-agents, 5 phases, ~4 parallel dispatches
+```
+
+## Example 2: Bug Investigation (Pipeline + Fan-out)
+
+**Task**: "Users report intermittent 500 errors on /api/workflows"
+
+```
+Phase 1: Research (parallel, 3 agents, sonnet)
+├── Researcher A: Recent changes to workflow endpoints (git log)
+├── Researcher B: Error handling and logging in workflow routes
+└── Researcher C: Database queries and connection patterns in workflows
+
+Phase 2: Diagnosis (sequential, 1 agent, opus)
+└── Debugger: Synthesize research, form hypotheses, trace root cause
+
+Phase 3: Fix (sequential, 1 agent, opus)
+└── Implementer: Apply minimal fix based on diagnosis
+
+Phase 4: Verify (parallel, 2 agents, opus)
+├── Tester: Write regression test, run test suite
+└── Reviewer: Review fix for correctness and side effects
+
+Result: 7 sub-agents, 4 phases
+```
+
+## Example 3: Code Migration (Batch Pattern)
+
+**Task**: "Migrate all 15 connector plugins from sync to async"
+
+```
+Phase 1: Research (parallel, 2 agents, sonnet)
+├── Researcher A: Current sync connector interface and patterns
+└── Researcher B: Target async interface and migration requirements
+
+Phase 2: Template (sequential, 1 agent, opus)
+└── Create migration template based on research
+
+Phase 3: Batch Migration (parallel, 15 agents, opus, worktree isolation)
+├── Implementer 1: Migrate connector_s3.py
+├── Implementer 2: Migrate connector_gcs.py
+├── ...
+└── Implementer 15: Migrate connector_azure.py
+
+Phase 4: Integration (sequential, 1 agent, opus)
+└── Verify all connectors work together, run integration tests
+
+Result: 19 sub-agents, 4 phases, each migration gets its own PR
+```
+
+## Example 4: Multi-Angle Research (Fan-out/Fan-in)
+
+**Task**: "How does our auth system work end-to-end?"
+
+```
+Phase 1: Research (parallel, 4 agents, sonnet)
+├── Researcher A: Authentication entry points (login, OAuth, API keys)
+├── Researcher B: Token lifecycle (creation, refresh, revocation)
+├── Researcher C: Authorization middleware and permission checks
+└── Researcher D: Session management and storage
+
+Phase 2: Synthesis (sequential, orchestrator)
+└── Merge all findings into comprehensive auth system documentation
+
+Result: 4 sub-agents, 2 phases, produces architecture doc
+```
+
+## Example 5: PR Review (Fan-out/Fan-in)
+
+**Task**: "Review PR #142 thoroughly"
+
+```
+Phase 1: Context (parallel, 2 agents, sonnet)
+├── Researcher A: Understand PR scope from diff and commits
+└── Researcher B: Read related CLAUDE.md and project conventions
+
+Phase 2: Review (parallel, 3 agents, opus)
+├── Reviewer A: Correctness — bugs, logic errors, edge cases
+├── Reviewer B: Security — vulnerabilities, data exposure, auth
+└── Reviewer C: Quality — patterns, naming, complexity, tests
+
+Phase 3: Aggregate (sequential, orchestrator)
+└── Prioritize findings: Critical > Important > Suggestions > Strengths
+
+Result: 5 sub-agents, 3 phases
+```
+
+## Example 6: Design Spike (Competitive Pattern)
+
+**Task**: "Should we use WebSockets or Server-Sent Events for real-time updates?"
+
+```
+Phase 1: Research (parallel, 2 agents, sonnet)
+├── Researcher A: WebSocket patterns, complexity, browser support
+└── Researcher B: SSE patterns, complexity, browser support
+
+Phase 2: Implement (parallel, 2 agents, opus, worktree isolation)
+├── Implementer A: WebSocket implementation
+└── Implementer B: SSE implementation
+
+Phase 3: Evaluate (parallel, 2 agents, opus)
+├── Reviewer A: Review WebSocket approach
+└── Reviewer B: Review SSE approach
+
+Phase 4: Select (sequential)
+└── Present comparison table, user picks
+
+Result: 6 sub-agents, 4 phases, 2 working prototypes to compare
+```
+
+## Example 7: Iterative Quality Gate (Iterative Pattern)
+
+**Task**: "Implement the payment processing module — must pass security review"
+
+```
+Phase 1: Research (parallel, 2 agents, sonnet)
+├── Researcher A: Payment processing patterns in codebase
+└── Researcher B: Security requirements and compliance constraints
+
+Phase 2: Implement (sequential, 1 agent, opus)
+└── Implementer: Build payment module based on research
+
+Phase 3-4: Review-Fix Loop (max 3 iterations)
+├── Iteration 1:
+│   ├── Review: 2 critical (SQL injection, missing auth check)
+│   └── Fix: Parameterized queries, added auth middleware
+├── Iteration 2:
+│   ├── Review: 1 important (insufficient input validation)
+│   └── Fix: Added validation layer
+└── Iteration 3:
+    └── Review: PASS (0 critical, 0 important)
+
+Result: 7+ sub-agents, 4+ phases, guaranteed quality gate
+```
+
+## Example 8: Test-Driven Development (TDD Pattern)
+
+**Task**: "Add rate limiting to the API gateway"
+
+```
+Phase 1: Research (parallel, 2 agents, sonnet)
+├── Researcher A: Current API gateway middleware stack
+└── Researcher B: Test infrastructure and patterns
+
+Phase 2: Write Failing Tests (sequential, 1 agent, opus)
+└── Tester: Write rate limit tests (per-user, per-endpoint, burst)
+    Tests run: 5 new tests, all RED ✗
+
+Phase 3: Implement (sequential, 1 agent, opus)
+└── Implementer: Implement rate limiter to pass tests
+    Tests run: 5 new tests, all GREEN ✓
+
+Phase 4: Review (parallel, 2 agents)
+├── Reviewer A (opus): Correctness + edge cases
+└── Reviewer B (sonnet): Convention compliance
+
+Result: 6 sub-agents, 4 phases, test-first guarantee
+```
+
+## Example 9: Fix PR Review Comments (Fan-out Pattern)
+
+**Task**: "Fix the 8 review comments on PR #142"
+
+```
+Phase 1: Gather (sequential, orchestrator)
+└── Fetch PR comments via gh, group by file
+
+Phase 2: Fix (parallel, 3 agents, opus)
+├── Implementer A: Fix 3 comments in src/auth/ files
+├── Implementer B: Fix 3 comments in src/api/ files
+└── Implementer C: Fix 2 comments in src/models/ files
+
+Phase 3: Verify (parallel, 2 agents)
+├── Tester: Run test suite
+└── Reviewer: Verify each comment was properly addressed
+
+Result: 5 sub-agents, 3 phases, systematic comment resolution
+```
+
+## Example 10: Adversarial Red Team (Adversarial Pattern)
+
+**Task**: "Implement payment processing with security hardening"
+
+```
+Phase 1: Research (parallel, 2 agents, sonnet)
+├── Researcher A: Payment processing patterns
+└── Researcher B: Common payment security vulnerabilities
+
+Phase 2: Build (sequential, 1 agent, opus)
+└── Builder: Implement payment module
+
+Phase 3: Break (parallel, 3 agents, opus)
+├── Breaker A: Edge cases (null amounts, negative, overflow)
+├── Breaker B: Security attacks (injection, auth bypass)
+└── Breaker C: Mutation testing (flip conditions, remove checks)
+
+Phase 4: Harden (sequential, 1 agent, opus)
+└── Hardener: Fix all Critical findings from breakers
+
+Result: 7 sub-agents, 4 phases, adversarially-hardened code
+```
+
+## Example 11: Multi-Agent Debate (Debate Pattern)
+
+**Task**: "Review the new caching layer for production readiness"
+
+```
+Phase 1: Independent Review (parallel, 3 agents)
+├── Reviewer Alpha (opus): Correctness + logic
+├── Reviewer Beta (opus): Architecture + performance
+└── Reviewer Gamma (sonnet): Conventions + tests
+
+Phase 2: Debate Round (parallel, 3 agents)
+├── Debater Alpha: Responds to Beta+Gamma findings
+├── Debater Beta: Responds to Alpha+Gamma findings
+└── Debater Gamma: Responds to Alpha+Beta findings
+
+Phase 3: Verdict (sequential)
+└── Aggregate: consensus rules, confidence-weighted
+
+Result: 6 sub-agents, 3 phases, high-confidence verdict
+```
+
+## Example 12: Brownian Ratchet (Chaos Pattern)
+
+**Task**: "Improve test coverage across src/utils/"
+
+```
+Phase 1: Decompose (sequential)
+└── Break into 4 overlapping focus areas
+
+Phase 2: Swarm (parallel, 4 agents, opus, worktree isolation)
+├── Chaos 1: Focus on string utilities
+├── Chaos 2: Focus on date/time utilities
+├── Chaos 3: Focus on validation utilities
+└── Chaos 4: Focus on error handling utilities
+
+Phase 3: Ratchet (sequential)
+├── Chaos 1: tests pass → merge
+├── Chaos 2: tests pass → merge
+├── Chaos 3: tests fail → discard
+└── Chaos 4: tests pass → merge
+
+Result: 4 agents, 3 merged, 1 discarded, net +47 tests
+```
+
+## Example 13: Self-Organizing Agents (Emergence Pattern)
+
+**Task**: "Build a notification system"
+
+```
+Phase 1: Spawn (parallel, 5 identical general-purpose agents, opus)
+├── Agent 1 → emerged as: researcher (explored existing code)
+├── Agent 2 → emerged as: planner (wrote design doc)
+├── Agent 3 → emerged as: implementer (wrote notification service)
+├── Agent 4 → emerged as: tester (wrote test suite)
+└── Agent 5 → emerged as: reviewer (reviewed agent 3's code)
+
+Phase 2: Observe
+└── All agents self-organized via scratchpad coordination
+
+Result: 5 agents, no pre-assigned roles, emergent specialization
+```

package/skills/orchestration-patterns/references/adversarial.md

@@ -0,0 +1,51 @@
+# Adversarial / Red Team Pattern
+
+## Overview
+Builder and breaker agents work simultaneously. One implements, the other tries to destroy. The code that survives both is genuinely robust.
+
+## When to Use
+- Security-critical features (auth, payments, data handling)
+- Code that must handle adversarial inputs
+- Features where edge case coverage is critical
+- Any code where "it works in the happy path" isn't enough
+
+## Architecture
+```
+                    ┌─── Builder (implement) ───┐
+                    │                           │
+User Task ─→ Plan ─┤                           ├─→ Harden ─→ Result
+                    │                           │
+                    └─── Breakers (3 parallel) ──┘
+                         - Edge cases
+                         - Security attacks
+                         - Mutation testing
+```
+
+## Implementation
+```
+# Setup
+TeamCreate(team_name="red-team")
+
+# Phase 1: Build
+Agent(name="builder", team_name="red-team", run_in_background=True,
+      prompt="Implement: ...", model="opus")
+
+# Phase 2: Break (parallel)
+Agent(name="breaker-edges", team_name="red-team", run_in_background=True,
+      prompt="Find edge cases: ...", model="opus")
+Agent(name="breaker-security", team_name="red-team", run_in_background=True,
+      prompt="Attack security: ...", model="opus")
+Agent(name="breaker-mutations", team_name="red-team", run_in_background=True,
+      prompt="Mutation test: ...", model="opus")
+
+# Phase 3: Harden
+Agent(name="hardener", team_name="red-team", run_in_background=True,
+      prompt="Fix critical findings: ...", model="opus")
+
+# Shutdown all, TeamDelete
+```
+
+## Pitfalls
+- **Breakers too aggressive**: Finding 50 theoretical issues when 3 are real. Focus on Critical/Important only.
+- **Builder demoralized**: The builder's code gets torn apart. Frame it as strengthening, not criticism.
+- **False positives**: Breakers may flag things that aren't actually vulnerabilities. Harden only confirmed issues.

package/skills/orchestration-patterns/references/batch.md

@@ -0,0 +1,63 @@
+# Batch Pattern
+
+## Overview
+Apply the same operation to N independent targets simultaneously. Each agent gets the same instructions but different scope.
+
+## When to Use
+- Migrating many files to a new format
+- Applying the same refactor across multiple modules
+- Running the same analysis on multiple components
+- Any "for each X, do Y" task where X's are independent
+
+## Architecture
+```
+                    ┌─── Agent(target=file1.py) ───┐
+                    │                               │
+Template ─→ Plan ─→┼─── Agent(target=file2.py) ───┼─→ Summary
+                    │                               │
+                    └─── Agent(target=file3.py) ───┘
+```
+
+## Implementation
+
+```
+# Define the template once
+template = """
+Migrate {target} from v1 to v2 API format:
+1. Replace `client.get()` with `client.request(method="GET")`
+2. Add error handling wrapper
+3. Update imports
+4. Run tests for this module
+"""
+
+# Setup
+TeamCreate(team_name="batch-team")
+for target in targets:
+    TaskCreate(subject=f"Migrate {target}", description="...")
+
+# Dispatch one agent per target, all as teammates in parallel
+agents = []
+for i, target in enumerate(targets):
+    name = f"migrator-{i}"
+    agents.append(name)
+    Agent(name=name, team_name="batch-team", run_in_background=True,
+          prompt=template.format(target=target), model="sonnet", isolation="worktree")
+
+# After all complete, shutdown each teammate
+for name in agents:
+    SendMessage(to=name, message="shutdown_request")
+TeamDelete(team_name="batch-team")
+```
+
+## Worktree Isolation
+For batch operations that modify files, use `isolation: "worktree"` so each agent works on its own copy. This avoids merge conflicts and lets each agent's changes be reviewed independently (each opens a separate PR).
+
+## Sizing Guidelines
+- **Sweet spot**: 5-15 units per batch
+- **Too few** (< 3): Just do it sequentially, overhead isn't worth it
+- **Too many** (> 20): Token costs add up fast, consider batching in waves
+
+## Pitfalls
+- **Shared dependencies**: If targets import from a common module being changed, conflicts arise
+- **Template rigidity**: Some targets may need special handling — allow escape hatches
+- **Cost**: N agents = N × token cost. Budget accordingly.