swarm-engine 1.0.0

package/commands/review-cycle.md

@@ -0,0 +1,123 @@
+---
+description: "Implement then review code in a parallel review cycle"
+argument-hint: "<implementation task>"
+---
+
+You are running an implement-then-review cycle with parallel reviewers for quality assurance.
+
+## Task
+$ARGUMENTS
+
+## Workflow
+
+### Setup: Create Team
+1. Create a team with `TeamCreate` (name: `review-cycle-<timestamp>`, e.g., `review-cycle-1234`)
+2. Create tasks with `TaskCreate` for each work unit identified in the plan
+
+### Phase 1: Research (parallel)
+Spawn 2-3 researcher teammates (sonnet) simultaneously, each with `team_name`, `name` (e.g., `researcher-arch`, `researcher-tests`, `researcher-deps`), and `run_in_background: true`:
+- One for architecture and patterns
+- One for related tests and test patterns
+- One for dependencies and integration points
+
+As each teammate completes, send it a `shutdown_request` via `SendMessage` to close its split pane.
+
+Present the research findings and implementation plan to the user. Proceed after approval.
+
+### Phase 2: Implement (sequential)
+Based on research findings, spawn an implementer teammate (opus) with `team_name`, `name` (e.g., `implementer`), and `run_in_background: true`.
+Include all research findings as context.
+
+As the teammate completes, send it a `shutdown_request` via `SendMessage` to close its split pane.
+
+### Phase 2b: Devil's Advocate (sequential)
+
+After implementation, spawn a devils-advocate teammate (opus) with `team_name`, `name` (e.g., `devils-advocate`), and `run_in_background: true`.
+
+Provide it with:
+- All files changed in Phase 2
+- The original task description
+- Research findings from Phase 1
+
+As the teammate completes, send it a `shutdown_request` via `SendMessage` to close its split pane.
+
+If the devil's advocate found **Critical** challenges:
+1. Spawn a new implementer teammate (opus, name: `implementer-hardened`) with `team_name` and `run_in_background: true`
+2. Include the devil's advocate's Critical challenges as requirements to address
+3. The implementer must address ALL Critical challenges before proceeding
+4. As the teammate completes, send `shutdown_request`
+
+If only Important challenges or Questions were raised, include them as context for the reviewers in Phase 3-4.
+
+### Phase 3-4: Review-Fix Loop (max 3 iterations)
+
+For each iteration (1 to 3):
+
+#### Review (parallel)
+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 a different focus:
+1. **Correctness reviewer** (opus) — Logic errors, edge cases, error handling, race conditions
+2. **Security reviewer** (opus) — Injection, auth bypass, data exposure, OWASP top 10
+3. **Convention reviewer** (sonnet) — Project patterns, naming, structure, CLAUDE.md compliance
+
+As each reviewer teammate completes, send it a `shutdown_request` via `SendMessage` to close its split pane.
+
+#### Gate Check
+Parse review results:
+- **PASS**: 0 Critical AND 0 Important findings → break loop, proceed to report
+- **FAIL**: Any Critical or Important finding → continue to Fix
+- **MAX ITERATIONS**: If iteration == 3 and still failing → report remaining issues to user
+
+#### Fix (sequential)
+If gate check failed:
+1. Aggregate all Critical + Important findings from all reviewers
+2. Present findings to user
+
+#### Reflexion (REQUIRED)
+The fixer's dispatch prompt MUST begin with this block — do not skip it:
+
+"## Previous Attempt Analysis
+The previous implementation failed review because:
+- [list each Critical/Important finding from reviewers]
+
+My approach to fix these issues:
+- [specific plan for each finding]
+
+I will avoid repeating:
+- [patterns from prior iterations that didn't work]"
+
+This block must be constructed from the actual reviewer findings and included verbatim at the start of the fixer's prompt. Without it, the fixer may repeat the same mistakes.
+
+3. Spawn an implementer teammate (opus) with `team_name`, `name` (e.g., `fixer-iter-N`), and `run_in_background: true` to fix Critical and Important issues only
+4. Do NOT fix Suggestions — they never trigger another iteration
+
+As the fixer teammate completes, send it a `shutdown_request` via `SendMessage` to close its split pane.
+
+### Phase 5: Report
+```markdown
+## Implementation Summary
+[What was built/changed]
+
+## Quality Gate: [PASS after N iterations | FAIL after 3 iterations]
+
+### Per-Iteration Results
+- **Iteration 1**: N critical, M important → [fixed / passed]
+- **Iteration 2**: N critical, M important → [fixed / passed]
+- **Iteration 3**: N critical, M important → [fixed / passed]
+
+## Remaining Concerns
+[Any Important/Suggestion findings from final iteration]
+
+## Suggestions (non-blocking)
+[Reviewer suggestions that did not trigger fixes]
+```
+
+### 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)
+- Only Critical and Important findings trigger a fix iteration — never Suggestions
+- Maximum 3 review-fix iterations before escalating to user
+- Present findings to user before each fix phase
+- Each fix phase must only address findings from the current iteration's review

package/commands/swarm-setup.md

@@ -0,0 +1,28 @@
+---
+description: "Interactive setup wizard — configure which AI backend each agent uses"
+argument-hint: ""
+---
+
+Run the Swarm Engine setup wizard to configure backends and models for your agents.
+
+## How to Execute
+
+Run this command in the terminal:
+
+```bash
+swarm setup
+```
+
+This walks you through 3 steps:
+
+1. **Default Backend** — Choose Claude, Codex, or Gemini as the default
+2. **Per-Agent Customization** — Same for all, or customize by role group (research, implementation, review)
+3. **Model Preferences** — Keep defaults or adjust (opus/sonnet/haiku)
+
+The wizard updates your agent `.md` files automatically. No manual editing needed.
+
+## If `swarm` is not on PATH
+
+```bash
+cd ~/dev/swarm-engine && npx tsx src/cli/index.ts configure
+```

package/commands/swarm.md

@@ -0,0 +1,126 @@
+---
+description: "Swarm Engine — orchestrate multi-agent development with composable patterns"
+argument-hint: "<task description> | setup | status | backends"
+---
+
+You are the Swarm Engine — a multi-agent orchestration system.
+
+If the user says "setup", run: `swarm setup` in the terminal to launch the interactive configuration wizard.
+If the user says "status", run: `swarm status` to show registered agents and backends.
+If the user says "backends", run: `swarm backends` to show available execution backends.
+
+Otherwise, orchestrate the task using formal patterns.
+
+## Task
+$ARGUMENTS
+
+## Workflow
+
+### Setup: Analyze and Select Pattern
+
+1. **Check memory** for relevant context:
+   ```bash
+   cd ~/dev/swarm-engine && npx tsx src/cli/index.ts memory search "<relevant keywords>"
+   ```
+
+2. **Assess the task** and select the best pattern:
+
+   | Task Type | Pattern | Why |
+   |-----------|---------|-----|
+   | General feature | `hybrid` | Research → Implement → Review (default) |
+   | Understanding code | `research` | Fan-out parallel exploration |
+   | Quality-critical code | `review-cycle` | Iterative review-fix loop |
+   | New feature with tests | `tdd` | Test-first guarantees coverage |
+   | Uncertain approach | `spike` | Two approaches compete, reviewer picks |
+   | Security-sensitive code | `red-team` | Build → Break → Harden |
+   | Complex/novel problem | `discover` | Hypothesize → Test → Implement winner |
+
+   If a dedicated command exists for the chosen pattern (e.g., `/review-cycle`, `/tdd`, `/spike`, `/red-team`, `/discover`, `/research`), **delegate to that command instead** of continuing here. Only continue with this command for `hybrid` or custom multi-phase orchestrations.
+
+3. **Create team**: `TeamCreate` (name: `orchestrate-<timestamp>`)
+4. **Create tasks**: `TaskCreate` for each planned phase
+
+### Phase 1: Research (parallel)
+
+Spawn 2-3 researcher teammates (sonnet) simultaneously, each with `team_name`, `name`, and `run_in_background: true`:
+- **researcher-code** — Explore the relevant codebase: architecture, entry points, existing patterns
+- **researcher-context** — Check memory and vault for past decisions, conventions, gotchas:
+  ```bash
+  ~/.claude/scripts/swarm-vault.sh repo "<repo-name>" conventions
+  ~/.claude/scripts/swarm-vault.sh repo "<repo-name>" gotchas
+  ```
+- **researcher-deps** (optional) — Map dependencies, integration points, downstream consumers
+
+As each teammate completes, send it a `shutdown_request` via `SendMessage` to close its split pane.
+
+Present the research findings and proposed implementation plan to the user. Proceed after approval.
+
+### Phase 2: Implement (parallel if independent, sequential if dependent)
+
+Based on research findings, spawn implementer teammates (opus) with `team_name`, `name`, and `run_in_background: true`.
+
+For each implementer, include:
+- All relevant research findings as context
+- Specific file assignments (no two implementers touch the same files)
+- Reference patterns from the codebase
+
+As each teammate completes, send it a `shutdown_request` via `SendMessage` to close its split pane.
+
+### Phase 3: Review (parallel)
+
+Spawn 2-3 reviewer teammates simultaneously, each with `team_name`, `name`, and `run_in_background: true`:
+1. **reviewer-correctness** (opus) — Logic errors, edge cases, error handling, race conditions
+2. **reviewer-security** (opus) — Injection, auth bypass, data exposure, OWASP top 10
+3. **reviewer-convention** (sonnet) — Project patterns, naming, structure compliance
+
+As each reviewer completes, send it a `shutdown_request` via `SendMessage` to close its split pane.
+
+#### Gate Check
+- **0 Critical AND 0 Important findings** → proceed to report
+- **Any Critical or Important finding** → spawn a fixer implementer (opus) to address them, then re-review (max 2 fix iterations)
+
+### Phase 4: Record Outcomes
+
+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>"
+```
+
+### Phase 5: Report
+
+```markdown
+## Orchestration Summary
+- **Pattern**: [hybrid / custom]
+- **Phases completed**: N of N
+
+## Changes Made
+[List of files changed with brief descriptions]
+
+## Research Findings
+[Key insights that informed the implementation]
+
+## Review Results
+- **Gate**: PASS / FAIL after N iterations
+- **Critical findings**: N (all resolved)
+- **Important findings**: N (resolved / remaining)
+
+## Suggestions (non-blocking)
+[Reviewer suggestions not addressed]
+
+## Knowledge Stored
+[What was saved to memory/vault for future use]
+```
+
+### 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)
+- Present the plan before executing — wait for user approval
+- If a dedicated command exists for the pattern, delegate to it
+- Include full context in every agent dispatch (agents don't share memory within a session)
+- Use the cheapest model that can handle each task (sonnet for research, opus for implementation/review)
+- Check engine memory before starting for relevant context
+- Record outcomes to engine memory after completion
+- Maximum 2 fix iterations before escalating remaining issues to the user

package/commands/tdd.md

@@ -0,0 +1,91 @@
+---
+description: "Test-driven development: write failing test, implement, verify green"
+argument-hint: "<feature description>"
+---
+
+You are running a strict TDD cycle: Red → Green → Review.
+
+## Task
+$ARGUMENTS
+
+## Workflow
+
+### Setup: Create Team
+1. Create a team with `TeamCreate` (name: `tdd-<timestamp>`, e.g., `tdd-1234`)
+2. Create tasks with `TaskCreate` for each phase of the TDD cycle
+
+### Phase 1: Research — parallel
+Spawn 2 researcher teammates simultaneously, each with `team_name`, `name`, and `run_in_background: true`:
+- **Researcher A** (`researcher-code`, sonnet): Existing code patterns, interfaces, and the module where the feature belongs
+- **Researcher B** (`researcher-tests`, sonnet): Test patterns, fixtures, test infrastructure, and how similar features are tested
+
+As each teammate completes, send it a `shutdown_request` via `SendMessage` to close its split pane.
+
+### Phase 2: Write Failing Test — sequential (depends on Phase 1)
+Spawn a tester teammate (opus) with `team_name`, `name` (e.g., `tester-red`), and `run_in_background: true`, with research context. The tester must:
+1. Write test(s) that describe the desired behavior
+2. Run the tests
+3. Verify they **fail** (red phase)
+
+If the tests pass, the feature already exists — report this and stop.
+
+As the teammate completes, send it a `shutdown_request` via `SendMessage` to close its split pane.
+
+Present the failing tests to the user. Proceed to implementation after approval.
+
+### Phase 3: Implement — sequential (depends on Phase 2)
+Spawn an implementer teammate (opus) with `team_name`, `name` (e.g., `implementer`), and `run_in_background: true`, with:
+- The failing test(s) as the specification
+- All research context from Phase 1
+- Goal: make the tests pass with **minimal code** — no extras
+
+As the teammate completes, send it a `shutdown_request` via `SendMessage` to close its split pane.
+
+### Phase 4: Verify — sequential (depends on Phase 3)
+Spawn a tester teammate (sonnet) with `team_name`, `name` (e.g., `tester-green`), and `run_in_background: true` to run the full test suite:
+- All tests must pass (green phase)
+- If **new** tests fail → send back to implementer with failure details
+- If **unrelated** tests fail → report regression and stop
+
+As the teammate completes, send it a `shutdown_request` via `SendMessage` to close its split pane.
+
+### Phase 5: Review — parallel (depends on Phase 4)
+Spawn 2 reviewer teammates simultaneously, each with `team_name`, `name`, and `run_in_background: true`, on the implementation (not the tests):
+1. **Correctness reviewer** (`reviewer-correctness`, opus) — Logic, edge cases, error handling
+2. **Convention reviewer** (`reviewer-convention`, sonnet) — Project patterns, naming, structure
+
+As each reviewer teammate completes, send it a `shutdown_request` via `SendMessage` to close its split pane.
+
+### Phase 6: Report
+
+```
+## TDD Report
+
+### Feature
+[What was built]
+
+### Tests Written
+- [test file:line — what each test covers]
+
+### Implementation
+- [file:line — what was added/changed]
+
+### Review Findings
+- Correctness: [PASS/FAIL — findings]
+- Conventions: [PASS/FAIL — findings]
+
+### Test Results
+[Full suite pass/fail summary]
+```
+
+### 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)
+- The test is the spec — implement only what the test demands
+- Never skip the red phase — tests MUST fail before implementation
+- Implement minimally — no gold-plating, no anticipatory code
+- If tests pass before implementation, the feature already exists — stop and report
+- Use opus for writing tests and implementation, sonnet for verification and convention review

package/dist/cli/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import './index.js';
+//# sourceMappingURL=bin.d.ts.map

package/dist/cli/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AACA,OAAO,YAAY,CAAC"}

package/dist/cli/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import './index.js';
+//# sourceMappingURL=bin.js.map

package/dist/cli/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AACA,OAAO,YAAY,CAAC"}

package/dist/cli/commands/acp.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare const acpCommand: Command;
+//# sourceMappingURL=acp.d.ts.map

package/dist/cli/commands/acp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/acp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,eAAO,MAAM,UAAU,SAoBnB,CAAC"}

package/dist/cli/commands/acp.js

@@ -0,0 +1,29 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { join } from 'path';
+import { homedir } from 'os';
+import { ACPServer } from '../../runtime/acp.js';
+import { AgentRegistry } from '../../core/registry.js';
+import { EventBus } from '../../core/event-bus.js';
+import { Logger } from '../../utils/logger.js';
+import { SwarmEngine } from '../../runtime/engine.js';
+export const acpCommand = new Command('acp')
+    .description('Start ACP server (wired to orchestration engine)')
+    .option('-p, --port <port>', 'Port', '3100')
+    .option('-h, --host <host>', 'Host', '127.0.0.1')
+    .option('--no-engine', 'Start without orchestration engine')
+    .action(async (options) => {
+    const bus = new EventBus(), logger = new Logger('acp', 'info'), registry = new AgentRegistry(bus);
+    registry.loadDirectory(join(homedir(), 'dev', 'swarm-engine', 'agents'));
+    let engine;
+    if (options.engine) {
+        engine = new SwarmEngine({ registry, bus, logger, mock: false, nonInteractive: true });
+    }
+    const server = new ACPServer({ port: parseInt(options.port, 10), host: options.host, registry, bus, logger, engine });
+    await server.start();
+    console.log(chalk.green(`ACP server on http://${options.host}:${options.port}`));
+    console.log(`  Engine: ${engine ? chalk.green('connected') : chalk.dim('disabled (--no-engine)')}`);
+    console.log(`  GET /health | GET /agents | POST /sessions | POST /sessions/:id/messages`);
+    process.on('SIGINT', async () => { await server.stop(); process.exit(0); });
+});
+//# sourceMappingURL=acp.js.map

package/dist/cli/commands/acp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp.js","sourceRoot":"","sources":["../../../src/cli/commands/acp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC;KACzC,WAAW,CAAC,kDAAkD,CAAC;KAC/D,MAAM,CAAC,mBAAmB,EAAE,MAAM,EAAE,MAAM,CAAC;KAC3C,MAAM,CAAC,mBAAmB,EAAE,MAAM,EAAE,WAAW,CAAC;KAChD,MAAM,CAAC,aAAa,EAAE,oCAAoC,CAAC;KAC3D,MAAM,CAAC,KAAK,EAAE,OAAwD,EAAE,EAAE;IACzE,MAAM,GAAG,GAAG,IAAI,QAAQ,EAAE,EAAE,MAAM,GAAG,IAAI,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC;IAClG,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,QAAQ,CAAC,CAAC,CAAC;IAEzE,IAAI,MAA+B,CAAC;IACpC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,GAAG,IAAI,WAAW,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC;IACzF,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACtH,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACrB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,wBAAwB,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACjF,OAAO,CAAC,GAAG,CAAC,aAAa,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,wBAAwB,CAAC,EAAE,CAAC,CAAC;IACpG,OAAO,CAAC,GAAG,CAAC,4EAA4E,CAAC,CAAC;IAC1F,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9E,CAAC,CAAC,CAAC"}

package/dist/cli/commands/agents.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare const agentsCommand: Command;
+//# sourceMappingURL=agents.d.ts.map

package/dist/cli/commands/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/agents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,eAAO,MAAM,aAAa,SACgB,CAAC"}