swarm-engine 1.0.0

package/templates/agent-template.md

@@ -0,0 +1,73 @@
+---
+# Agent Template — copy and customize
+name: my-agent                  # Required: lowercase, hyphens, 3-50 chars
+description: |                  # Required: when to trigger + examples
+  One-line description of what this agent does.
+
+  <example>
+  <context>When this situation arises</context>
+  <user-request>User says something like this</user-request>
+  <assistant-response>Claude delegates to this agent</assistant-response>
+  <commentary>Why this agent is the right choice</commentary>
+  </example>
+
+model: inherit                  # Optional: sonnet | opus | haiku | inherit
+# tools: Read, Glob, Grep      # Optional: allowlist (inherits all if omitted)
+# disallowedTools: Write, Edit  # Optional: denylist
+# maxTurns: 20                  # Optional: limit agentic turns
+# background: true              # Optional: always run in background
+# isolation: worktree           # Optional: isolated git worktree
+# memory: user                  # Optional: user | project | local
+---
+
+You are a [Role] Agent. Your job is to [core responsibility].
+
+## Process
+1. **Step 1** — [what to do first]
+1b. **Check vault** — Read project context from the vault: `~/.claude/scripts/swarm-vault.sh repo "<repo-name>" overview`
+2. **Step 2** — [what to do next]
+3. **Step 3** — [final step]
+
+## Before You Act
+
+Before executing your process, reason through these questions internally (do not output this thinking):
+
+1. **What's the REAL problem?** Restate the task in your own words. If your restatement doesn't match the original request, you've already drifted.
+2. **What could go wrong?** Name 2-3 specific failure modes for THIS task — not hypothetical, concrete.
+3. **What's the blast radius?** If you make a mistake here, what else breaks? The answer determines how careful to be.
+4. **Am I the right agent for this?** If this task is better suited for a different agent type, say so immediately rather than producing mediocre output.
+
+## Output Format
+```
+## Summary
+[Brief answer/result]
+
+## Details
+[Structured findings with file:line references]
+
+## Recommendations
+[Next steps if applicable]
+```
+
+## Rules
+1. [Most important constraint]
+2. [Second constraint]
+3. [Third constraint]
+4. **Abstention** — If this task is outside your competence or you lack sufficient context to do it well, say so clearly in your output rather than producing low-quality work. Set Confidence to "low" and explain what's missing in Blockers.
+5. **Vault** — Check the vault for relevant context before starting: `~/.claude/scripts/swarm-vault.sh repo "<repo-name>" conventions`. Note non-obvious findings for the orchestrator to save.
+6. **Scratchpad** — If a scratchpad path is provided in your prompt, `Read` it before starting for context from sibling agents. Before completing, append your key findings under a `## Agent: <your-name>` heading.
+7. **Debt tagging** — Tag tech debt explicitly: DEBT:NEW (I introduced this), DEBT:EXISTING (I found this), DEBT:WORSENED (my change makes this worse). Include file, reason, and priority.
+
+## Self-Check (internal — do not output)
+Before finalizing your output:
+- Does my output actually answer what was asked? Re-read the original task.
+- Did I make assumptions I didn't flag? Each assumption is a potential failure point.
+- Is there anything I'm uncertain about that I presented as certain? Downgrade confidence.
+- What would a senior engineer critique about my output? Address that now.
+
+Always include at the end of your response:
+
+## Meta
+- **Confidence**: [high|medium|low] — how confident you are in your output
+- **Blockers**: [list of things that prevented full completion, or "none"]
+- **Files touched**: [list of file paths written/edited, or "none" for read-only agents]

package/templates/bug-fix.yml

@@ -0,0 +1,31 @@
+name: bug-fix
+description: "Reproduce, diagnose, fix, and verify a bug"
+parameters:
+  bug_description:
+    type: string
+    description: "Description of the bug"
+    required: true
+  reproduction_steps:
+    type: string
+    description: "Steps to reproduce"
+    required: false
+pattern: hybrid
+agents:
+  researcher:
+    extra_rules:
+      - "Reproduce the bug first"
+      - "Trace the root cause through the code"
+      - "Check git blame for recent changes to affected files"
+  implementer:
+    extra_rules:
+      - "Fix the root cause, not just the symptom"
+      - "Add a regression test"
+  reviewer:
+    extra_rules:
+      - "Verify the fix addresses the root cause"
+      - "Check for similar bugs in related code"
+success_criteria:
+  - "Bug is fixed"
+  - "Regression test added"
+  - "No side effects"
+tags: [bug, fix]

package/templates/explore.yml

@@ -0,0 +1,21 @@
+name: explore
+description: "Onboard to a new codebase — understand architecture, patterns, and conventions"
+parameters:
+  focus:
+    type: string
+    description: "Area to focus on (or 'full' for entire repo)"
+    default: full
+pattern: research
+agents:
+  researcher:
+    extra_rules:
+      - "Map the directory structure and key files"
+      - "Identify the tech stack, frameworks, and dependencies"
+      - "Find coding conventions and patterns"
+      - "Document the architecture and data flow"
+      - "Focus area: ${focus}"
+success_criteria:
+  - "Architecture documented"
+  - "Key files and patterns identified"
+  - "Conventions understood"
+tags: [research, onboarding]

package/templates/fix-pr.yml

@@ -0,0 +1,30 @@
+name: fix-pr
+description: "Fix PR review comments and push updates"
+parameters:
+  pr_number:
+    type: string
+    description: "Pull request number"
+    required: true
+    example: "42"
+  repo:
+    type: string
+    description: "Repository (owner/repo)"
+    required: false
+pattern: review-cycle
+agents:
+  researcher:
+    extra_rules:
+      - "Read the PR diff and all review comments"
+      - "Identify which comments require code changes vs discussion"
+  implementer:
+    extra_rules:
+      - "Address each review comment systematically"
+      - "Do not change code unrelated to the review"
+  reviewer:
+    extra_rules:
+      - "Verify each original review comment was addressed"
+success_criteria:
+  - "All review comments addressed"
+  - "Tests pass"
+  - "No unrelated changes"
+tags: [git, review]

package/templates/migration.yml

@@ -0,0 +1,36 @@
+name: migration
+description: "Database or schema migration with rollback plan"
+parameters:
+  from:
+    type: string
+    description: "Source schema/format"
+    required: true
+  to:
+    type: string
+    description: "Target schema/format"
+    required: true
+  rollback:
+    type: boolean
+    description: "Include rollback script?"
+    default: true
+pattern: tdd
+agents:
+  researcher:
+    extra_rules:
+      - "Understand the current schema: ${from}"
+      - "Map all code that depends on the schema"
+  tester:
+    extra_rules:
+      - "Write tests for the migration path"
+      - "Test rollback if rollback=true"
+  implementer:
+    extra_rules:
+      - "Migrate from ${from} to ${to}"
+      - "Write a rollback script if ${rollback}"
+      - "Ensure zero data loss"
+success_criteria:
+  - "Migration from ${from} to ${to} works"
+  - "All dependent code updated"
+  - "Rollback script included if requested"
+  - "No data loss"
+tags: [migration, database]

package/templates/refactor.yml

@@ -0,0 +1,35 @@
+name: refactor
+description: "Safe refactoring with verification at each step"
+parameters:
+  target:
+    type: string
+    description: "What to refactor (module, function, pattern)"
+    required: true
+  goal:
+    type: string
+    description: "What the refactoring achieves"
+    required: true
+  constraint:
+    type: string
+    description: "Constraints (e.g., no API changes, backward compatible)"
+    required: false
+    default: "No breaking changes to public API"
+pattern: review-cycle
+agents:
+  researcher:
+    extra_rules:
+      - "Map all callers and dependents of ${target}"
+      - "Identify the blast radius of changes"
+  implementer:
+    extra_rules:
+      - "Make changes incrementally, verify tests after each step"
+      - "Constraint: ${constraint}"
+  reviewer:
+    extra_rules:
+      - "Verify no behavioral changes beyond the stated goal"
+      - "Check that ${constraint} is respected"
+success_criteria:
+  - "Refactoring achieves: ${goal}"
+  - "All tests pass"
+  - "${constraint}"
+tags: [refactor, quality]

package/templates/security-audit.yml

@@ -0,0 +1,27 @@
+name: security-audit
+description: "OWASP-focused security review of a codebase or module"
+parameters:
+  scope:
+    type: string
+    description: "What to audit (full repo, module path, or file)"
+    required: true
+    example: "src/auth/"
+  depth:
+    type: string
+    description: "Audit depth"
+    enum: [quick, standard, thorough]
+    default: standard
+pattern: red-team
+agents:
+  implementer:
+    extra_rules:
+      - "Focus on ${scope}"
+      - "Check OWASP Top 10"
+  reviewer:
+    extra_rules:
+      - "Look for: injection, auth bypass, XSS, SSRF, path traversal"
+      - "Check dependency vulnerabilities"
+success_criteria:
+  - "All critical vulnerabilities identified"
+  - "Findings include severity, location, and fix recommendation"
+tags: [security, review]

package/templates/workflow-template.md

@@ -0,0 +1,63 @@
+---
+# Workflow (Command) Template — copy and customize
+description: "One-line description of this workflow"
+argument-hint: "<what the user should provide>"
+# allowed-tools: Read, Glob, Grep, Agent  # Optional: restrict tools
+---
+
+You are executing the [Workflow Name] workflow.
+
+## Task
+$ARGUMENTS
+
+## Workflow
+
+### Setup: Create Team
+1. Create a team with `TeamCreate` (name derived from workflow + timestamp)
+2. Create tasks with `TaskCreate` for each planned work unit
+3. Create a scratchpad at `.claude/scratchpad/<team-name>.md` for cross-agent communication:
+   ```bash
+   mkdir -p .claude/scratchpad && echo "# Scratchpad: <team-name>" > .claude/scratchpad/<team-name>.md
+   ```
+
+### Phase 1: [Name] — parallel
+# Include scratchpad path in each dispatch: "Scratchpad: .claude/scratchpad/{team-name}.md"
+Spawn N teammates with `team_name`, `name`, and `run_in_background: true`:
+- **Agent A** (researcher, haiku): [specific scope]
+- **Agent B** (researcher, haiku): [specific scope]
+
+### Phase 2: [Name] — sequential (depends on Phase 1)
+Synthesize Phase 1 results, then:
+- **Agent C** (implementer, sonnet): [specific scope with Phase 1 context]
+
+### Phase 3: [Name] — parallel (depends on Phase 2)
+Launch N review agents:
+- **Agent D** (reviewer, sonnet): [review focus area 1]
+- **Agent E** (reviewer, sonnet): [review focus area 2]
+
+### Phase 4: Report
+Aggregate all results:
+
+```
+## Summary
+[What was accomplished]
+
+## Key Findings/Changes
+[Structured results]
+
+## Issues
+[Any problems found]
+
+## Next Steps
+[Recommended follow-ups]
+```
+
+### Cleanup
+1. Send `shutdown_request` via `SendMessage` to each remaining active teammate to close their split pane
+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)
+- Present the plan before executing
+- Include full context in every agent dispatch
+- Use the cheapest model that can handle each task