swarm-engine 1.0.0

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

@@ -0,0 +1,43 @@
+# Chaos / Brownian Ratchet Pattern
+
+## Overview
+Multiple agents tackle overlapping tasks with ZERO coordination. Each works in an isolated worktree. CI (tests) is the one-way ratchet — anything that passes gets merged. Duplicated effort is fine. Progress is permanent.
+
+## When to Use
+- Test coverage improvement across a codebase
+- Refactoring campaigns (rename, extract, simplify)
+- Code cleanup and documentation
+- Any "make things better broadly" task without specific requirements
+
+## Architecture
+```
+                    ┌─── Agent 1 (worktree) ─── tests pass? ─── merge ──┐
+                    │                                                     │
+Broad Task ─→ Plan ─┼─── Agent 2 (worktree) ─── tests fail? ─── discard │─→ Net Result
+                    │                                                     │
+                    └─── Agent 3 (worktree) ─── tests pass? ─── merge ──┘
+```
+
+## Implementation
+```
+TeamCreate(team_name="chaos")
+
+# All agents get the same broad task, work independently
+Agent(name="chaos-1", isolation="worktree", run_in_background=True,
+      prompt="Improve: ...", model="opus")
+Agent(name="chaos-2", isolation="worktree", run_in_background=True,
+      prompt="Improve: ...", model="opus")
+Agent(name="chaos-3", isolation="worktree", run_in_background=True,
+      prompt="Improve: ...", model="opus")
+
+# Ratchet: merge only what passes tests
+for each branch:
+  if tests_pass(branch): merge(branch)
+  else: discard(branch)
+```
+
+## Pitfalls
+- **Not for specific features**: Chaos works for broad improvements, not targeted requirements.
+- **Merge conflicts**: Later merges may conflict with earlier ones. Auto-resolve or discard.
+- **Test quality matters**: If tests are weak, bad code passes the ratchet. Ensure good baseline test coverage.
+- **Cost**: N agents = N x token cost. Budget accordingly.

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

@@ -0,0 +1,84 @@
+# Competitive / Tournament Pattern
+
+## Overview
+Two or more agents solve the same problem independently using different approaches. A reviewer evaluates each solution. The user picks the winner. Useful when the optimal approach is uncertain.
+
+## When to Use
+- Design-uncertain features where multiple viable approaches exist
+- Performance-sensitive code where different algorithms should be compared
+- Architectural spikes before committing to an approach
+- Any "should we do X or Y?" question that's best answered by trying both
+
+## Architecture
+```
+                    ┌─── Implementer A (worktree) ───┐
+                    │                                 │
+User Task ─→ Plan ─┤                                 ├─→ Compare ─→ User Picks ─→ Apply
+                    │                                 │
+                    └─── Implementer B (worktree) ───┘
+                              ↓           ↓
+                         Reviewer A   Reviewer B
+```
+
+## Implementation
+
+```
+# Setup
+TeamCreate(team_name="competitive-team")
+TaskCreate(subject="Research approaches", description="...")
+TaskCreate(subject="Implement approach 1", description="...")
+TaskCreate(subject="Implement approach 2", description="...")
+TaskCreate(subject="Review approach 1", description="...")
+TaskCreate(subject="Review approach 2", description="...")
+
+# Phase 1: Research — identify two viable approaches
+research = Agent(name="researcher", team_name="competitive-team", run_in_background=True,
+                 prompt="Research approaches for: ...", model="sonnet")
+# Wait for research
+SendMessage(to="researcher", message="shutdown_request")
+
+# Phase 2: Implement — parallel, isolated worktrees
+Agent(name="impl-1", team_name="competitive-team", run_in_background=True,
+      prompt="Implement approach 1: ...", model="opus", isolation="worktree")
+Agent(name="impl-2", team_name="competitive-team", run_in_background=True,
+      prompt="Implement approach 2: ...", model="opus", isolation="worktree")
+# Wait for both implementations
+SendMessage(to="impl-1", message="shutdown_request")
+SendMessage(to="impl-2", message="shutdown_request")
+
+# Phase 3: Evaluate — parallel reviewers
+Agent(name="reviewer-1", team_name="competitive-team", run_in_background=True,
+      prompt="Review approach 1: ...", model="opus")
+Agent(name="reviewer-2", team_name="competitive-team", run_in_background=True,
+      prompt="Review approach 2: ...", model="opus")
+# Wait for both reviews
+SendMessage(to="reviewer-1", message="shutdown_request")
+SendMessage(to="reviewer-2", message="shutdown_request")
+
+# Phase 4: Select — present comparison, user decides
+# Apply winning worktree branch
+
+# Cleanup
+TeamDelete(team_name="competitive-team")
+```
+
+## Evaluation Criteria
+
+| Criteria | What to assess |
+|----------|---------------|
+| **Correctness** | Does it solve the full problem? Edge cases? |
+| **Complexity** | Lines of code, cyclomatic complexity, readability |
+| **Maintainability** | How easy to extend, modify, debug? |
+| **Performance** | Time/space complexity, benchmarks if applicable |
+| **Testability** | How easy to test? How much mocking needed? |
+
+## When NOT to Use
+- The approach is obvious — just implement it
+- The task is simple enough that two approaches would be nearly identical
+- Token budget is tight — this pattern costs 2x implementation tokens
+
+## Pitfalls
+- **Scope creep**: Agents may solve slightly different problems. Give them identical specs.
+- **Worktree cleanup**: If the user doesn't pick either approach, both worktrees should be cleaned up.
+- **Bias**: Present both approaches neutrally in the comparison. Don't lead the user.
+- **Incomplete comparison**: Each reviewer must assess ALL criteria, not just their strengths.

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

@@ -0,0 +1,44 @@
+# Debate Pattern
+
+## Overview
+Multiple reviewers independently assess code, then debate their findings in a second round. Consensus = high confidence. Disagreement = flag for human.
+
+## When to Use
+- Code quality is uncertain and you want multiple perspectives
+- Complex logic where one reviewer might miss something
+- When you need a confidence-weighted verdict, not just pass/fail
+- Controversial design decisions that benefit from deliberation
+
+## Architecture
+```
+          ┌─── Reviewer A ───┐          ┌─── Debater A ───┐
+          │                  │          │                  │
+Code ───→ ├─── Reviewer B ───┼─→ Share → ├─── Debater B ───┼─→ Verdict
+          │                  │          │                  │
+          └─── Reviewer C ───┘          └─── Debater C ───┘
+          (independent)                 (respond to others)
+```
+
+## Implementation
+```
+# Round 1: Independent review
+TeamCreate(team_name="debate")
+Agent(name="reviewer-alpha", ..., prompt="Review independently: ...")
+Agent(name="reviewer-beta", ..., prompt="Review independently: ...")
+Agent(name="reviewer-gamma", ..., prompt="Review independently: ...")
+
+# Round 2: Debate (each sees others' reviews)
+Agent(name="debater-alpha", ..., prompt="Read beta+gamma reviews, respond: ...")
+Agent(name="debater-beta", ..., prompt="Read alpha+gamma reviews, respond: ...")
+Agent(name="debater-gamma", ..., prompt="Read alpha+beta reviews, respond: ...")
+
+# Verdict: consensus rules
+# All APPROVE → APPROVE
+# 2+ REQUEST_CHANGES → REQUEST_CHANGES
+# Disagreement → ESCALATE to human
+```
+
+## Pitfalls
+- **Groupthink**: Reviewers may converge on the first reviewer's opinion. Ensure independent Round 1.
+- **Debate fatigue**: Two rounds is usually enough. More rounds rarely change the verdict.
+- **Overweight consensus**: Unanimous agreement doesn't mean correctness. It means all agents have the same blind spots.

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

@@ -0,0 +1,50 @@
+# Emergence / Role-Free Pattern
+
+## Overview
+Identical agents with no pre-assigned roles self-organize to solve a task. Based on Dochkina 2026 (arXiv:2603.28990) which proved self-organizing agents outperform designed hierarchies by 14%.
+
+## When to Use
+- Experimental — testing whether self-organization produces better results
+- Tasks where the optimal role decomposition is unclear
+- Complex tasks that might benefit from unexpected agent behaviors
+- Research into multi-agent dynamics
+
+## Architecture
+```
+                    ┌─── Agent 1 (general) ──→ self-selects: researcher
+                    │
+                    ├─── Agent 2 (general) ──→ self-selects: implementer
+                    │
+Broad Task ─→ All ──┼─── Agent 3 (general) ──→ self-selects: tester
+                    │
+                    ├─── Agent 4 (general) ──→ self-selects: reviewer
+                    │
+                    └─── Agent 5 (general) ──→ self-selects: abstains
+```
+
+## Implementation
+```
+TeamCreate(team_name="emergence")
+
+# All agents are identical — no role assignment
+prompt = "You are Agent N in a team of 5. Decide what to do."
+
+Agent(name="agent-1", subagent_type="general-purpose", model="opus", ...)
+Agent(name="agent-2", subagent_type="general-purpose", model="opus", ...)
+Agent(name="agent-3", subagent_type="general-purpose", model="opus", ...)
+Agent(name="agent-4", subagent_type="general-purpose", model="opus", ...)
+Agent(name="agent-5", subagent_type="general-purpose", model="opus", ...)
+
+# Coordination via scratchpad only
+# Observe: what roles emerged? What overlapped? Quality assessment.
+```
+
+## Key Research
+- Dochkina 2026: 25,000 tasks, 5,006 emergent roles, 14% better than designed hierarchies
+- Only works with strong models (Opus-class). Weak models need pre-assigned roles.
+
+## Pitfalls
+- **Only for capable models**: Weak models won't self-organize effectively.
+- **Unpredictable**: You can't guarantee what roles will emerge. Some tasks may get neglected.
+- **Scratchpad critical**: Without the shared scratchpad, agents have no visibility into each other.
+- **Experimental**: Not yet proven for production coding tasks. Use for research and comparison.

package/skills/orchestration-patterns/references/fan-out-fan-in.md

@@ -0,0 +1,74 @@
+# Fan-Out / Fan-In Pattern
+
+## Overview
+Dispatch N independent agents simultaneously, collect all results, aggregate into a single output.
+
+## When to Use
+- Multiple independent research questions
+- Same analysis from different perspectives (e.g., 3 reviewers with different focus areas)
+- Batch operations on unrelated files
+- Parallel data gathering from multiple sources
+
+## Architecture
+```
+                    ┌─── Agent A ───┐
+                    │               │
+User Task ─→ Plan ─┼─── Agent B ───┼─→ Aggregate ─→ Result
+                    │               │
+                    └─── Agent C ───┘
+```
+
+## Implementation
+
+```
+# Setup
+TeamCreate(team_name="fan-out-team")
+TaskCreate(subject="Research angle A", description="...")
+TaskCreate(subject="Research angle B", description="...")
+TaskCreate(subject="Research angle C", description="...")
+
+# Dispatch all agents as teammates
+Agent(name="researcher-a", team_name="fan-out-team", run_in_background=True,
+      prompt="Research angle A: ...", model="haiku")
+Agent(name="researcher-b", team_name="fan-out-team", run_in_background=True,
+      prompt="Research angle B: ...", model="haiku")
+Agent(name="researcher-c", team_name="fan-out-team", run_in_background=True,
+      prompt="Research angle C: ...", model="haiku")
+
+# All three run concurrently and return results
+# Then synthesize all results into one coherent output
+
+# After completion, shutdown each teammate via SendMessage
+SendMessage(to="researcher-a", message="shutdown_request")
+SendMessage(to="researcher-b", message="shutdown_request")
+SendMessage(to="researcher-c", message="shutdown_request")
+TeamDelete(team_name="fan-out-team")
+```
+
+## Aggregation Strategies
+
+| Strategy | When | How |
+|----------|------|-----|
+| **Merge** | Complementary findings | Combine non-overlapping results |
+| **Vote** | Same question, multiple opinions | Majority rules, flag disagreements |
+| **Prioritize** | Mixed severity findings | Critical > Important > Suggestions |
+| **Synthesize** | Complex, overlapping findings | LLM summarizes all inputs |
+
+## Example: Multi-Angle Code Review
+
+```
+Phase: Review (parallel)
+├── Agent 1: Correctness review (sonnet) → bugs, logic errors
+├── Agent 2: Security review (sonnet) → vulnerabilities, data exposure
+└── Agent 3: Convention review (sonnet) → style, patterns, CLAUDE.md
+
+Aggregation: Prioritize
+├── Critical (any reviewer) → must fix
+├── Important (any reviewer) → should fix
+└── Suggestions (any reviewer) → optional
+```
+
+## Pitfalls
+- **Context explosion**: N agents returning detailed results can overwhelm the context window. Keep dispatch prompts focused and ask for concise outputs.
+- **Redundant work**: Agents may investigate overlapping areas. Define clear boundaries.
+- **All-or-nothing**: If one agent fails, you still need to handle partial results gracefully.

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

@@ -0,0 +1,99 @@
+# Iterative Refinement Pattern
+
+## Overview
+A loop of implement → review → gate check → fix until quality threshold is met or max iterations reached. Encodes quality as a hard gate rather than a suggestion.
+
+## When to Use
+- Security-sensitive changes that must pass review before shipping
+- Complex logic where first-pass implementation often has subtle bugs
+- Any task where "good enough on first try" is unlikely
+- When the cost of shipping a bug exceeds the cost of an extra review cycle
+
+## Architecture
+```
+                    ┌──────────────────────────────┐
+                    │                              │
+                    ↓                              │
+Implement ──→ Review (parallel) ──→ Gate Check ───┘ (if FAIL, iteration < max)
+                                        │
+                                        ↓ (if PASS or iteration == max)
+                                      Report
+```
+
+## Gate Criteria
+- **PASS**: 0 Critical findings AND 0 Important findings
+- **FAIL**: Any Critical or Important finding → fix and re-review
+- **MAX_ITERATIONS**: 3 (default) — if still failing after 3 iterations, report remaining issues to user
+
+## Implementation
+
+```
+# Setup
+TeamCreate(team_name="iterative-team")
+
+for iteration in 1..MAX_ITERATIONS:
+  # Create tasks for this iteration
+  TaskCreate(subject=f"Correctness review (iter {iteration})", description="...")
+  TaskCreate(subject=f"Security review (iter {iteration})", description="...")
+  TaskCreate(subject=f"Convention review (iter {iteration})", description="...")
+
+  # Review phase (parallel teammates)
+  Agent(name=f"correctness-{iteration}", team_name="iterative-team", run_in_background=True,
+        prompt="Review for correctness: ...", model="opus")
+  Agent(name=f"security-{iteration}", team_name="iterative-team", run_in_background=True,
+        prompt="Review for security: ...", model="opus")
+  Agent(name=f"convention-{iteration}", team_name="iterative-team", run_in_background=True,
+        prompt="Review conventions: ...", model="sonnet")
+
+  # Wait for all reviewers, then shutdown
+  SendMessage(to=f"correctness-{iteration}", message="shutdown_request")
+  SendMessage(to=f"security-{iteration}", message="shutdown_request")
+  SendMessage(to=f"convention-{iteration}", message="shutdown_request")
+
+  # Gate check
+  findings = parse_findings(correctness, security, convention)
+  critical = [f for f in findings if f.severity == "critical"]
+  important = [f for f in findings if f.severity == "important"]
+
+  if len(critical) == 0 and len(important) == 0:
+    TeamDelete(team_name="iterative-team")
+    return PASS  # Quality gate met
+
+  # Fix phase (sequential)
+  TaskCreate(subject=f"Fix issues (iter {iteration})", description="...")
+  Agent(name=f"fixer-{iteration}", team_name="iterative-team", run_in_background=True,
+        prompt=f"Fix these issues: {critical + important}", model="opus")
+  # Wait for fixer, then shutdown
+  SendMessage(to=f"fixer-{iteration}", message="shutdown_request")
+
+# Cleanup
+TeamDelete(team_name="iterative-team")
+return FAIL_WITH_REMAINING_ISSUES
+```
+
+## Context Accumulation
+Each iteration's fix agent gets: original spec, ALL prior review findings (not just current iteration), and what was already fixed. This prevents regression — the fix agent knows what was changed before and doesn't accidentally revert a prior fix.
+
+## Report Format
+
+```
+## Quality Gate: [PASS after N iterations | FAIL after 3 iterations]
+
+### Iteration 1
+- Findings: N critical, M important
+- Fixed: [list]
+
+### Iteration 2
+- Findings: N critical, M important
+- Fixed: [list]
+
+### Final State
+- Remaining issues: [list or "none"]
+- Suggestions (not blocking): [list]
+```
+
+## Pitfalls
+- **Infinite loops**: ALWAYS enforce max iterations. Without it, a reviewer that always finds something creates an endless cycle.
+- **Fix regression**: Fixing issue A can introduce issue B. Pass accumulated context so each fix is aware of prior changes.
+- **Diminishing returns**: If iteration 2 finds as many issues as iteration 1, something is fundamentally wrong with the implementation — escalate to user rather than looping.
+- **Over-fixing**: Only fix Critical and Important findings. Suggestions should NEVER trigger another iteration.

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

@@ -0,0 +1,72 @@
+# Pipeline Pattern
+
+## Overview
+Sequential chain of agents where each step's output feeds the next step's input.
+
+## When to Use
+- Data transformation workflows (parse → transform → validate → write)
+- Progressive refinement (draft → review → revise → finalize)
+- Tasks with strict ordering requirements
+- When each step fundamentally changes the context for the next
+
+## Architecture
+```
+User Task ─→ Agent A ─→ Agent B ─→ Agent C ─→ Result
+              (research)  (implement)  (review)
+```
+
+## Implementation
+
+```
+# Setup
+TeamCreate(team_name="pipeline-team")
+TaskCreate(subject="Research phase", description="...")
+TaskCreate(subject="Implementation phase", description="...")
+TaskCreate(subject="Review phase", description="...")
+
+# Sequential dispatch — each agent gets the prior agent's output
+result_a = Agent(name="researcher", team_name="pipeline-team", run_in_background=True,
+                 prompt="Research: ...", model="haiku")
+# Wait for result_a
+SendMessage(to="researcher", message="shutdown_request")
+
+result_b = Agent(name="implementer", team_name="pipeline-team", run_in_background=True,
+                 prompt="Implement based on research: {result_a}", model="sonnet")
+# Wait for result_b
+SendMessage(to="implementer", message="shutdown_request")
+
+result_c = Agent(name="reviewer", team_name="pipeline-team", run_in_background=True,
+                 prompt="Review implementation: {result_b}", model="sonnet")
+# Wait for result_c
+SendMessage(to="reviewer", message="shutdown_request")
+
+# Cleanup
+TeamDelete(team_name="pipeline-team")
+```
+
+## Hybrid Pipeline (with parallel phases)
+
+Most real workflows are hybrids — some phases are parallel within a sequential flow:
+
+```
+Phase 1 (parallel):  Research A + Research B + Research C
+                              ↓
+Phase 2 (sequential): Synthesize research → Implementation plan
+                              ↓
+Phase 3 (parallel):  Implement Module X + Implement Module Y
+                              ↓
+Phase 4 (parallel):  Review X + Review Y + Integration test
+                              ↓
+Phase 5 (sequential): Final aggregation → Report
+```
+
+## Context Passing
+The critical challenge in pipelines is passing sufficient context between stages:
+- **Summarize, don't dump**: Pass the conclusions from phase N, not the raw output
+- **Include original task**: Each agent should see the user's original request
+- **Accumulate decisions**: Keep a running list of decisions made in prior phases
+
+## Pitfalls
+- **Context loss**: Each agent starts fresh. Important details from early phases can get lost.
+- **Error propagation**: A mistake in phase 1 cascades through all subsequent phases.
+- **Unnecessary serialization**: Don't pipeline things that could be parallel.

package/skills/swarm-output-style/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: swarm-output-style
+description: |
+  Professional output formatting for swarm agent orchestrations.
+  TRIGGER when: orchestrating tasks, presenting plans, reporting results,
+  showing agent status, displaying review findings, or any multi-agent output.
+  DO NOT TRIGGER for simple single-file edits or conversational responses.
+---
+
+# Swarm Output Style Guide
+
+## Plan Presentation
+
+When presenting an orchestration plan, use this format:
+
+```
+## Orchestration Plan
+
+**Task**: [1-line description]
+**Pattern**: [pattern name]
+**Agents**: [count] | **Phases**: [count] | **Est. cost**: ~$[amount]
+
+### Phase 1: [Name] — parallel
+| Agent | Role | Model | Focus |
+|-------|------|-------|-------|
+| `name` | type | model | what they do |
+
+### Phase 2: [Name] — sequential (depends on Phase 1)
+| Agent | Role | Model | Focus |
+|-------|------|-------|-------|
+| `name` | type | model | what they do |
+```
+
+## Progress Updates
+
+Keep compact. One line per agent with status:
+```
+agent-name    [working]  current action
+agent-name    [done]     completed in 12s
+agent-name    [idle]     waiting for Phase 2
+```
+
+Do NOT dump raw agent output into progress updates. Summarize.
+
+## Agent Reports
+
+Each agent includes a Meta block. When aggregating:
+- Lead with the overall result (pass/fail/concerns)
+- Group findings by severity (critical > important > suggestion)
+- Include file:line references
+- Keep it scannable — bullet points, not paragraphs
+
+## Final Summary
+
+```
+## Summary
+
+**Status**: [COMPLETE / NEEDS CHANGES / FAILED]
+
+### What was done
+- [bullet points]
+
+### Key decisions
+- [bullet points]
+
+### Metrics
+Agents: [N] | Phases: [N] | Duration: [time] | Est. cost: ~$[amount]
+```
+
+## Anti-Patterns (DO NOT)
+
+- Do NOT dump raw agent transcripts into the summary
+- Do NOT use emoji in structured output (alignment issues in terminals)
+- Do NOT repeat the original task description in every status update
+- Do NOT show agent Meta blocks to the user — synthesize them
+- Do NOT use vague language ("various improvements") — be specific
+- Do NOT include timestamps in every line — only in the activity feed
+
+## Color Conventions (for terminal output)
+
+When outputting to terminal:
+- **Bold** for section headers
+- Agent names in their role color (blue=researcher, green=implementer, yellow=reviewer)
+- Status badges: `[working]` `[done]` `[idle]` `[error]`
+- Keep lines under 80 characters for terminal compatibility

package/templates/add-endpoint.yml

@@ -0,0 +1,44 @@
+name: add-endpoint
+description: "Add a REST API endpoint with validation, tests, and documentation"
+parameters:
+  route:
+    type: string
+    description: "API route path"
+    required: true
+    example: "/api/users/:id"
+  method:
+    type: string
+    description: "HTTP method"
+    enum: [GET, POST, PUT, PATCH, DELETE]
+    required: true
+  auth:
+    type: boolean
+    description: "Requires authentication?"
+    default: true
+  description:
+    type: string
+    description: "What the endpoint does"
+    required: true
+pattern: review-cycle
+context_files:
+  - "src/routes/**/*.ts"
+  - "src/middleware/*.ts"
+agents:
+  researcher:
+    extra_rules:
+      - "Find existing endpoint patterns and conventions"
+      - "Identify the validation and auth middleware used"
+  implementer:
+    extra_rules:
+      - "Follow the existing route file naming convention"
+      - "Include request/response type definitions"
+  tester:
+    extra_rules:
+      - "Test authenticated and unauthenticated requests"
+      - "Test validation errors with 400 responses"
+success_criteria:
+  - "Endpoint responds to ${method} ${route}"
+  - "Auth middleware applied if auth=true"
+  - "Input validation with error responses"
+  - "At least 3 test cases"
+tags: [api, backend]

package/templates/add-feature.yml

@@ -0,0 +1,30 @@
+name: add-feature
+description: "Add a new feature with tests and documentation"
+parameters:
+  feature:
+    type: string
+    description: "Feature description"
+    required: true
+  test_framework:
+    type: string
+    description: "Test framework to use"
+    default: "jest"
+pattern: hybrid
+agents:
+  researcher:
+    extra_rules:
+      - "Understand how similar features are implemented in the codebase"
+      - "Identify affected modules and potential side effects"
+  implementer:
+    extra_rules:
+      - "Follow existing code patterns and conventions"
+      - "Write tests using ${test_framework}"
+  reviewer:
+    extra_rules:
+      - "Check for edge cases and error handling"
+      - "Verify test coverage"
+success_criteria:
+  - "Feature works as described"
+  - "Tests pass with good coverage"
+  - "No regressions"
+tags: [feature, implementation]