Setup

Get your quarters ready

- - - - - - - - - - - - - - - - - - - - -

Prerequisites

Before you begin, make sure you have these installed:

Tool	Version	Purpose
`bash`	4.0+	Swarm is pure bash
`git`	2.20+	Worktrees, branches, commits
`gh`	2.0+	GitHub CLI for issues, PRs, labels
`claude`	latest	Claude Code CLI for agent execution
`python3`	3.6+	JSON handling and template rendering

Install Claude Code

npm install -g @anthropic-ai/claude-code

Install GitHub CLI

brew install gh
gh auth login

Installation

Step 1: Clone

Clone the repository that has Swarm set up, or add Swarm to your existing project.

git clone https://github.com/p4u1d34n0/Dromos.git
cd Dromos

Step 2: Initialise

Run the init command to set up the Swarm directory structure and configuration file.

bin/swarm init

This creates:

.swarm/prompts/ — agent prompt templates
.swarm/paradigms/ — coding standards files
swarm.json — project configuration

$ bin/swarm init

Initializing Swarm...

Repository: p4u1d34n0/Dromos (github)

Created swarm.json

Set up CI triggers? (Y/n):

CI Trigger Setup

CI triggers let Swarm run automatically when issues are assigned or labelled. This is optional for local use but essential for production automation.

bin/swarm setup-ci

The setup wizard will ask you to configure:

Setting	Default	Purpose
Assignee username	`swarm-bot`	Issues assigned to this user trigger Swarm
Trigger label	`swarm`	Issues with this label trigger Swarm
Mention keyword	`@swarm`	Comments containing this trigger Swarm
PR review triggers	Yes	Also trigger review agent on PR events

GitHub Actions

After running setup-ci, you'll need to configure these in your GitHub repository settings:

Repository Variables

Settings > Variables > Actions

SWARM_ASSIGNEE       = swarm-bot
SWARM_TRIGGER_LABEL  = swarm
SWARM_MENTION        = @swarm

Repository Secret

Settings > Secrets > Actions

ANTHROPIC_API_KEY = sk-ant-...

Commit the Workflow

git add .github/workflows/swarm.yml
git commit -m "Add Swarm CI workflow"
git push

Trigger It

Assign an issue to your swarm-bot user or add the swarm label to any issue.

Configuration

swarm.json

The main configuration file. Created by swarm init, updated by swarm setup-ci.

{
  "project": {
    "name": "Dromos",
    "repo": "p4u1d34n0/Dromos"
  },
  "agents": {
    "scope":  ".swarm/prompts/scope-agent.md",
    "dev":    ".swarm/prompts/dev-agent.md",
    "review": ".swarm/prompts/review-agent.md",
    "rework": ".swarm/prompts/rework-agent.md"
  },
  "paradigms": [
    ".swarm/paradigms/php-standards.md"
  ],
  "triggers": {
    "platform": "github",
    "assignee": "swarm-bot",
    "label": "swarm",
    "mention": "@swarm",
    "pr_review": true
  }
}

Agent Prompts

Each agent has a markdown prompt file in .swarm/prompts/. These define the agent's role, process, output format, and rules. Customise them to match your workflow.

Coding Paradigms

Files in .swarm/paradigms/ are appended to the system prompt for dev, review, and rework agents. Add one file per language or concern:

.swarm/paradigms/
  php-standards.md
  typescript-standards.md
  security-rules.md

Quick Start

Local Test Run

Try processing an issue locally before setting up CI:

# Preview what would happen
bin/swarm process 42 --dry

# Run it for real
bin/swarm process 42

# Check the worktrees
bin/swarm worktrees list

- - - - - - - - - - - - - - - - - - - - -

Start Playing

Game Over? Never.