swarm-engine 1.1.1 → 1.3.0

package/commands/postmortem.md

@@ -0,0 +1,106 @@
+---
+description: "Root cause analysis — trace an error or incident back to its origin and produce a fix"
+argument-hint: "<error message, failing test, or incident description>"
+---
+
+You are running a postmortem analysis: systematically trace an error back to its root cause, understand how it happened, fix it, and prevent it from happening again.
+
+Follow the `swarm-output-style` skill for ALL output formatting.
+
+## Task
+$ARGUMENTS
+
+## Workflow
+
+### Step 0: Show Pre-flight Plan
+
+Before creating any team or spawning any agent, show the plan:
+
+Show the pre-flight plan (see swarm-output-style skill). Include:
+- All phases (Reproduce, Diagnose, Fix, Verify)
+- Agents per phase with model and focus
+- Estimated cost (~$0.12 reproduce, ~$0.15 diagnose, ~$0.19 fix, ~$0.23 verify/review)
+- Estimated time (~15-25 min total)
+
+Wait for user approval before proceeding.
+
+### Setup: Create Team
+1. Create a team with `TeamCreate` (name: `postmortem-<timestamp>`)
+2. Create tasks with `TaskCreate` for each work unit
+
+### Phase 1: Reproduce and Gather Evidence — parallel
+
+Show the phase banner with running total (see swarm-output-style skill).
+
+Spawn 3 researcher teammates (sonnet) simultaneously, each with `team_name`, `name`, and `run_in_background: true`:
+
+- **`researcher-reproduce`**: Reproduce the error. Find the exact steps, inputs, or conditions that trigger it. If a test fails, run it and capture the full output. If it's a runtime error, trace the call stack.
+- **`researcher-history`**: Check git history. When was this last working? What changed? Use `git log`, `git blame`, `git bisect` thinking to identify the commit or time window where the breakage was introduced.
+- **`researcher-context`**: Check memory and vault for related past incidents. Search for similar errors, known fragile areas, or prior decisions that constrained the implementation. Run `~/.claude/scripts/swarm-vault.sh search "<error keywords>"`.
+
+As each completes: show a one-line completion summary (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
+
+### Phase 2: Diagnose — sequential
+
+Show the phase banner with running total (see swarm-output-style skill).
+
+Spawn a debugger teammate (opus) with `team_name`, `name` (`diagnostician`), and `run_in_background: true`.
+
+Provide ALL evidence from Phase 1. The debugger should:
+1. Identify the root cause (not the symptom)
+2. Explain the chain of events: what triggered what
+3. Identify contributing factors (was there a missing test? a bad assumption? a race condition?)
+4. Classify the failure type: regression, design flaw, edge case, environment issue, dependency change
+5. Propose a fix
+
+As the teammate completes: show a one-line completion summary (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
+
+Present the diagnosis to the user. Proceed after approval.
+
+### Phase 3: Fix — sequential
+
+Show the phase banner with running total (see swarm-output-style skill).
+
+Spawn an implementer teammate (opus) with `team_name`, `name` (`fixer`), and `run_in_background: true`:
+
+- Fix the root cause, not just the symptom
+- Add a regression test that would have caught this
+- If the fix touches a fragile area, add defensive checks
+
+As the teammate completes: show a one-line completion summary (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
+
+### Phase 4: Verify — parallel
+
+Show the phase banner with running total (see swarm-output-style skill).
+
+Spawn 2 teammates simultaneously with `team_name`, `name`, and `run_in_background: true`:
+
+- **`verifier`** (tester, sonnet): Run the full test suite. Confirm the regression test passes. Confirm no other tests broke.
+- **`reviewer-fix`** (reviewer, opus): Review the fix for correctness. Check that it addresses the root cause, not a surface symptom. Look for similar patterns elsewhere in the codebase that might have the same vulnerability.
+
+As each completes: show a one-line completion summary (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
+
+### Phase 5: Report
+
+Show the full post-completion summary (see swarm-output-style skill). Include:
+- Status (PASS / NEEDS ATTENTION / FAILED)
+- Metrics (phases, agents, duration, tokens, cost)
+- Incident timeline (last working state → change introduced → discovered → fixed)
+- Root cause and contributing factors
+- Fix applied (files changed, regression test added)
+- Prevention checklist (actionable, not generic)
+- Verification results (test count, reviewer verdict)
+- Next steps
+
+### Cleanup
+1. Send `shutdown_request` via `SendMessage` to any remaining active teammates
+2. Call `TeamDelete` to clean up the team
+
+## Rules
+- All agents must be spawned as team members (TeamCreate → TaskCreate → Agent with team_name/name/run_in_background → SendMessage shutdown → TeamDelete)
+- Always find the ROOT cause, not the surface symptom. "X was null" is a symptom. "Input validation was missing because the API contract changed in v2 but the handler wasn't updated" is a root cause.
+- The regression test is mandatory. If the fix doesn't include a test that would have caught the original failure, the postmortem is incomplete.
+- Check for similar patterns elsewhere. If a bug exists in one place, the same mistake may exist in similar code.
+- The Prevention section should be actionable, not generic. "Write more tests" is useless. "Add null check tests for all handler parameters in src/api/handlers/" is actionable.
+- Follow the swarm-output-style skill for ALL output formatting
+- Show the plan first, spend tokens second

package/commands/red-team.md

@@ -5,30 +5,53 @@ argument-hint: "<feature or implementation to red-team>"
 
 You are running an adversarial red-team cycle where a builder implements and a breaker tries to destroy.
 
+Follow the `swarm-output-style` skill for ALL output formatting.
+
 ## Task
 $ARGUMENTS
 
 ## Workflow
 
+### Step 0: Show Pre-flight Plan
+
+Before creating any team or spawning any agent, show the plan:
+
+Show the pre-flight plan (see swarm-output-style skill). Include:
+- All phases (Research, Build, Break, Harden)
+- Agents per phase with model and focus
+- Estimated cost (~$0.08 research, ~$0.19 build, ~$0.45 break, ~$0.34 harden/verify)
+- Estimated time (~15-30 min total)
+
+Wait for user approval before proceeding.
+
 ### Setup: Create Team
 1. Create a team with `TeamCreate` (name: `red-team-<timestamp>`)
 2. Create tasks with `TaskCreate` for each work unit
 3. Create a scratchpad at `.claude/scratchpad/<team-name>.md` for cross-agent communication. Pass its path to all agent dispatches.
 
 ### Phase 1: Research (parallel)
+
+Show the phase banner with running total (see swarm-output-style skill).
+
 Spawn 2 researcher teammates (sonnet) with `team_name`, `name`, and `run_in_background: true`:
 - `researcher-code`: Understand the codebase area being worked on
 - `researcher-attack`: Research common vulnerabilities and failure modes for this type of feature
 
-As each completes, send `shutdown_request`.
+As each completes: show a one-line completion summary (see swarm-output-style skill), then send `shutdown_request`.
 
 ### Phase 2: Build (sequential)
+
+Show the phase banner with running total (see swarm-output-style skill).
+
 Spawn an implementer teammate (opus) with `team_name`, `name` (`builder`), and `run_in_background: true`.
 Include research findings as context. Implement the feature.
 
-As the teammate completes, send `shutdown_request`.
+As the teammate completes: show a one-line completion summary (see swarm-output-style skill), then send `shutdown_request`.
 
 ### Phase 3: Break (parallel)
+
+Show the phase banner with running total (see swarm-output-style skill).
+
 Spawn 3 breaker teammates simultaneously with `team_name`, `name`, and `run_in_background: true`:
 
 1. **`breaker-edge-cases`** (devils-advocate, opus) — Probe null inputs, empty collections, boundary conditions, concurrent access, network failures, resource exhaustion
@@ -37,39 +60,29 @@ Spawn 3 breaker teammates simultaneously with `team_name`, `name`, and `run_in_b
 
 Each breaker gets the full implementation from Phase 2.
 
-As each completes, send `shutdown_request`.
+As each completes: show a one-line completion summary (see swarm-output-style skill), then send `shutdown_request`.
 
 ### Phase 4: Harden (sequential)
+
+Show the phase banner with running total (see swarm-output-style skill).
+
 If breakers found vulnerabilities:
 1. Aggregate all findings by severity
 2. Spawn an implementer teammate (opus) with `team_name`, `name` (`hardener`), and `run_in_background: true` to fix Critical and Important findings
-3. As the hardener completes, send it a `shutdown_request`
+3. As the hardener completes: show a one-line completion summary (see swarm-output-style skill), then send it a `shutdown_request`
 4. Spawn a verifier teammate with `team_name`, `name` (e.g., `verifier-security`), and `run_in_background: true` to re-run the specific breaker's tests against the hardened code
-5. As the verifier completes, send it a `shutdown_request`
+5. As the verifier completes: show a one-line completion summary (see swarm-output-style skill), then send it a `shutdown_request`
 
 ### Phase 5: Report
-```markdown
-## Red Team Report
-
-### Built
-[What was implemented]
-
-### Attacked
-- Edge cases probed: [count]
-- Security attacks attempted: [count]
-- Mutations tested: [count]
-
-### Vulnerabilities Found
-| Severity | Finding | Status |
-|----------|---------|--------|
-| Critical | [finding] | Fixed / Open |
-
-### Hardening Applied
-[What was fixed]
 
-### Surviving Weaknesses
-[What couldn't be fixed or needs human decision]
-```
+Show the full post-completion summary (see swarm-output-style skill). Include:
+- Status (PASS / NEEDS ATTENTION / FAILED)
+- Metrics (phases, agents, duration, tokens, cost)
+- What was built and what was attacked
+- Vulnerability table (severity, finding, status)
+- Hardening applied
+- Surviving weaknesses requiring human decision
+- Next steps
 
 ### Cleanup
 1. Send `shutdown_request` to any remaining active teammates
@@ -80,3 +93,5 @@ If breakers found vulnerabilities:
 - Breakers should be genuinely adversarial — their goal is to BREAK the code
 - Only fix Critical and Important findings — Suggestions go in the report
 - If mutation tests reveal untested code paths, note them but don't block
+- Follow the swarm-output-style skill for ALL output formatting
+- Show the plan first, spend tokens second

package/commands/research.md

@@ -5,11 +5,25 @@ argument-hint: "<research question>"
 
 You are conducting parallel research to answer a complex question using multiple researcher agents simultaneously.
 
+Follow the `swarm-output-style` skill for ALL output formatting.
+
 ## Question
 $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:
+- The research question decomposed into 2-5 angles
+- One researcher per angle with model and focus (haiku for broad search, sonnet for deep analysis)
+- Estimated cost (~$0.04/researcher for haiku, ~$0.10/researcher for sonnet)
+- Estimated time (~2-3 min per haiku agent, ~3-5 min per sonnet agent)
+
+Wait for user approval before proceeding.
+
 ### Setup: Create Team
 1. Create a team with `TeamCreate` (name: `research-<timestamp>`, e.g., `research-1234`)
 2. Create tasks with `TaskCreate` for each research angle identified in the decomposition
@@ -21,12 +35,15 @@ Break the research question into 2-5 independent angles of investigation. Each a
 - Together provide a complete picture
 
 ### Step 2: Dispatch Researchers
+
+Show the phase banner with running total (see swarm-output-style skill).
+
 Spawn one researcher teammate per angle, ALL in parallel, each with `team_name`, `name` (e.g., `researcher-angle-1`), and `run_in_background: true`. Use:
 - `subagent_type`: Use the "Explore" type for pure search, or spawn a "researcher" agent for deeper analysis
 - `model`: "haiku" for broad searches, "sonnet" for deep analysis
 - Include the specific angle and any known context in each prompt
 
-As each teammate completes, send it a `shutdown_request` via `SendMessage` to close its split pane.
+As each completes: show a one-line completion summary (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
 
 ### Step 3: Synthesize
 Once all researchers return:
@@ -48,6 +65,8 @@ Once all researchers return:
 [Suggested next steps based on findings]
 ```
 
+Show the full post-completion summary (see swarm-output-style skill).
+
 ### Cleanup
 1. Send `shutdown_request` via `SendMessage` to any remaining active teammates
 2. Call `TeamDelete` to clean up the team
@@ -57,3 +76,5 @@ Once all researchers return:
 - Include full context in every researcher dispatch — they cannot ask follow-up questions
 - Use haiku for broad file search, sonnet for deep analysis
 - All findings must include file:line references
+- Follow the swarm-output-style skill for ALL output formatting
+- Show the plan first, spend tokens second

package/commands/review-cycle.md

@@ -5,33 +5,55 @@ argument-hint: "<implementation task>"
 
 You are running an implement-then-review cycle with parallel reviewers for quality assurance.
 
+Follow the `swarm-output-style` skill for ALL output formatting.
+
 ## Task
 $ARGUMENTS
 
 ## Workflow
 
+### Step 0: Show Pre-flight Plan
+
+Before creating any team or spawning any agent, show the plan:
+
+Show the pre-flight plan (see swarm-output-style skill). Include:
+- All phases (Research, Implement, Devil's Advocate, Review-Fix Loop)
+- Agents per phase with model and focus
+- Estimated cost (~$0.12 research, ~$0.19 implement, ~$0.10 devil's advocate, ~$0.29/review iteration)
+- Estimated time (~15-30 min depending on review iterations)
+
+Wait for user approval before proceeding.
+
 ### 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)
+
+Show the phase banner with running total (see swarm-output-style skill).
+
 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.
+As each completes: show a one-line completion summary (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
 
 Present the research findings and implementation plan to the user. Proceed after approval.
 
 ### Phase 2: Implement (sequential)
+
+Show the phase banner with running total (see swarm-output-style skill).
+
 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.
+As the teammate completes: show a one-line completion summary (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
 
 ### Phase 2b: Devil's Advocate (sequential)
 
+Show the phase banner with running total (see swarm-output-style skill).
+
 After implementation, spawn a devils-advocate teammate (opus) with `team_name`, `name` (e.g., `devils-advocate`), and `run_in_background: true`.
 
 Provide it with:
@@ -39,7 +61,7 @@ Provide it with:
 - 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.
+As the teammate completes: show a one-line completion summary (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
 
 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`
@@ -54,12 +76,15 @@ If only Important challenges or Questions were raised, include them as context f
 For each iteration (1 to 3):
 
 #### Review (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 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.
+As each completes: show a one-line verdict (PASS/FAIL + finding count) (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
 
 #### Gate Check
 Parse review results:
@@ -93,23 +118,14 @@ This block must be constructed from the actual reviewer findings and included ve
 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]
-```
+Show the full post-completion summary (see swarm-output-style skill). Include:
+- Status (PASS / NEEDS ATTENTION / FAILED)
+- Metrics (phases, agents, duration, tokens, cost)
+- What changed (files with git diff --stat if available)
+- Review gate result with per-reviewer table and per-iteration breakdown
+- Non-blocking suggestions
+- Next steps
 
 ### Cleanup
 1. Send `shutdown_request` via `SendMessage` to any remaining active teammates
@@ -121,3 +137,5 @@ As the fixer teammate completes, send it a `shutdown_request` via `SendMessage`
 - 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
+- Follow the swarm-output-style skill for ALL output formatting
+- Show the plan first, spend tokens second

package/commands/spike.md

@@ -0,0 +1,108 @@
+---
+description: "Two independent approaches to the same problem, evaluated side-by-side"
+argument-hint: "<problem to solve with competing approaches>"
+---
+
+You are running a competitive spike: two independent approaches to the same problem, evaluated side-by-side.
+
+Follow the `swarm-output-style` skill for ALL output formatting.
+
+## Task
+$ARGUMENTS
+
+## Workflow
+
+### Step 0: Show Pre-flight Plan
+
+Before creating any team or spawning any agent, show the plan:
+
+Show the pre-flight plan (see swarm-output-style skill). Include:
+- All phases (Research, Implement x2 in parallel worktrees, Evaluate x2, Select)
+- Agents per phase with model and focus
+- Estimated cost (~$0.08 research, ~$0.38 implement, ~$0.20 evaluate)
+- Estimated time (~20-35 min total)
+
+Wait for user approval before proceeding.
+
+### Setup: Create Team
+1. Create a team with `TeamCreate` (name: `spike-<timestamp>`, e.g., `spike-1234`)
+2. Create tasks with `TaskCreate` for each work unit (research, implementation, review)
+
+### Phase 1: Research — parallel
+
+Show the phase banner with running total (see swarm-output-style skill).
+
+Spawn 2 researcher teammates (sonnet) simultaneously, each with `team_name`, `name` (e.g., `researcher-a`, `researcher-b`), and `run_in_background: true` to explore the problem space. Each should:
+- Understand the constraints and requirements
+- Identify a viable approach
+- Describe the approach with tradeoffs
+
+As each completes: show a one-line completion summary (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
+
+Present the two approaches to the user before proceeding.
+
+### Phase 2: Implement — parallel (worktree isolation, depends on Phase 1)
+
+Show the phase banner with running total (see swarm-output-style skill).
+
+Spawn 2 implementer teammates (opus) simultaneously, each in an **isolated worktree**, with `team_name`, `name` (e.g., `implementer-a`, `implementer-b`), and `run_in_background: true`:
+- **Implementer A**: Approach 1 — full implementation in isolated worktree
+- **Implementer B**: Approach 2 — full implementation in isolated worktree
+
+Both receive the same spec and requirements but different suggested approaches.
+
+As each completes: show a one-line completion summary (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
+
+### Phase 3: Evaluate — parallel (depends on Phase 2)
+
+Show the phase banner with running total (see swarm-output-style skill).
+
+Spawn 2 reviewer teammates (opus) simultaneously, each with `team_name`, `name` (e.g., `reviewer-a`, `reviewer-b`), and `run_in_background: true`:
+- **Reviewer A**: Reviews Approach 1 — correctness, complexity, maintainability, testability
+- **Reviewer B**: Reviews Approach 2 — correctness, complexity, maintainability, testability
+
+As each completes: show a one-line verdict per approach (see swarm-output-style skill), then send `shutdown_request` via `SendMessage`.
+
+### Phase 4: Select — sequential (depends on Phase 3)
+Present a comparison table to the user:
+
+```
+## Spike Comparison
+
+| Criteria        | Approach 1           | Approach 2           |
+|-----------------|----------------------|----------------------|
+| Summary         | [brief description]  | [brief description]  |
+| Correctness     | [assessment]         | [assessment]         |
+| Complexity      | [lines/abstractions] | [lines/abstractions] |
+| Maintainability | [assessment]         | [assessment]         |
+| Performance     | [assessment]         | [assessment]         |
+| Testability     | [assessment]         | [assessment]         |
+| Reviewer Verdict| [recommendation]     | [recommendation]     |
+
+### Recommendation
+[Which approach and why]
+```
+
+The user picks the winner. Apply the winning approach: merge the winning worktree branch with `git merge <branch> --no-ff`, or if significantly diverged, cherry-pick the relevant commits.
+
+Show the full post-completion summary (see swarm-output-style skill). Include:
+- Status (PASS / NEEDS ATTENTION)
+- Metrics (phases, agents, duration, tokens, cost)
+- Spike comparison table summary
+- Which approach was selected and why
+- What was applied (merge/cherry-pick)
+- Next steps
+
+### Cleanup
+1. Send `shutdown_request` via `SendMessage` to any remaining active teammates
+2. Call `TeamDelete` to clean up the team
+
+## Rules
+- All agents must be spawned as team members (TeamCreate → TaskCreate → Agent with team_name/name/run_in_background → SendMessage shutdown → TeamDelete)
+- Both approaches must solve the FULL problem — no partial implementations
+- Use worktree isolation so approaches don't interfere with each other
+- Include clear tradeoff analysis in the comparison
+- The user always makes the final decision — never auto-select
+- If both approaches are flawed, recommend a third path informed by what was learned
+- Follow the swarm-output-style skill for ALL output formatting
+- Show the plan first, spend tokens second