How to Add a New Agent Role to SwarmForge: A Complete Guide

SwarmForge adds new agent roles by creating a prompt file in swarmforge/constitution/articles/, registering the role in .swarmforge/roles.tsv, and launching it via swarmforge.sh to auto-generate a dedicated Git worktree and tmux pane.

SwarmForge is an open-source multi-agent orchestration framework where every pipeline participant is defined as a role. Each role operates in its own isolated Git worktree with a dedicated LLM prompt and hand-off routing rules. This guide walks you through the exact steps to add a custom role like designer or architect to your SwarmForge pipeline, based on the source code in unclebob/swarm-forge.

---

What Defines a Role in SwarmForge?

A SwForge role consists of three core components tracked by the orchestration system:

1. Role name — the identifier used via the SWARMFORGE_ROLE environment variable
2. Role prompt — the system prompt that defines the LLM's responsibilities
3. Role worktree — an isolated Git worktree where the agent writes changes

The hand-off daemon coordinates between roles by reading the central registry at .swarmforge/roles.tsv, as documented in swarmforge/handoff-protocol.md.

---

Step 1: Create the Role Prompt File

Every role needs a constitution prompt stored in swarmforge/constitution/articles/. The launcher script automatically loads <role>.prompt when starting the agent.

cat > swarmforge/constitution/articles/designer.prompt <<'EOF'
You are a UI/UX designer. Generate wireframes, design specs,
and justify UI decisions with user-centered reasoning.
EOF

The swarmforge.sh script reads this file at startup and passes it to the LLM backend as the system prompt.

---

Step 2: Register the Role in roles.tsv

Add your role to the hand-off protocol's registry. Edit .swarmforge/roles.tsv and append a tab-delimited line:

printf "designer\tbatch\n" >> .swarmforge/roles.tsv

The columns are:

• Role name — matches your prompt filename
• Receive mode — either batch (processes all pending hand-offs) or task (processes one at a time)

The hand-off daemon uses this table to route git_handoff files to the correct worktree, as specified in swarmforge/handoff-protocol.md.

---

Step 3: Launch the Role to Create Its Worktree

Run the launcher script with your new role name:

./swarmforge/scripts/swarmforge.sh designer

The swarmforge.sh script performs three critical operations:

1. Sets SWARMFORGE_ROLE=designer in the process environment
2. Initializes a Git worktree at .swarmforge/worktrees/designer
3. Opens a dedicated tmux pane running the LLM backend with your prompt

Each role's worktree isolation prevents file conflicts and enables clean hand-offs between agents.

---

Step 4: Define Hand-Off Routing Rules

Configure where your new role sends work when finished. Add a [handoff] section to your pack's configuration file (e.g., my-pack.conf):

[handoff]
designer = coder, architect

This tells the hand-off daemon that when designer completes its task, the resulting changes should be forwarded to both coder and architect roles. The daemon reads these mappings from swarmforge.conf or project-local config files to build the pipeline graph.

---

Step 5: Restart the Swarm

Apply your changes by restarting the orchestration dashboard:

./swarm

The dashboard will now display a designer pane alongside existing roles, and the hand-off daemon will include it in the pipeline workflow.

---

Complete Example: Adding a Designer Role

Here's the full sequence condensed into copy-paste commands:

# Write the constitution prompt

cat > swarmforge/constitution/articles/designer.prompt <<'EOF'
You are a UI/UX designer. Generate wireframes, design specs,
and justify UI decisions with user-centered reasoning.
EOF

# Register with batch receive mode

printf "designer\tbatch\n" >> .swarmforge/roles.tsv

# Launch to create worktree and tmux pane

./swarmforge/scripts/swarmforge.sh designer

# Add hand-off routing in your pack config:

# [handoff]

# designer = coder, architect

# Restart to activate

./swarm

---

Key Files for Role Management

File	Purpose
swarmforge/constitution/articles/*.prompt	Per-role LLM system prompts
.swarmforge/roles.tsv	Runtime registry of all roles and receive modes
swarmforge/handoff-protocol.md	Protocol specification for hand-off format and validation
swarmforge/scripts/swarmforge.sh	Role launcher that creates worktrees and tmux panes
swarmforge/scripts/swarm_handoff.sh	Daemon that routes files between role worktrees
README.md	Overview of the pack system and shared scripts

---

Summary

• Create a prompt file in swarmforge/constitution/articles/<role>.prompt to define the LLM's behavior
• Register the role in .swarmforge/roles.tsv with its receive mode (batch or task)
• Launch via swarmforge/scripts/swarmforge.sh <role> to auto-provision worktree and tmux pane
• Route hand-offs by adding [handoff] entries in your pack configuration
• Restart with ./swarm to activate the new role in the dashboard

With these five steps, you can extend SwarmForge pipelines with any specialized agent role.

---

Frequently Asked Questions

What is the difference between batch and task receive modes?

The batch mode processes all pending hand-off files in the role's inbox before completing, while task mode handles one hand-off at a time. Use batch for roles that need full context of all upstream changes, and task for sequential processing workflows. The hand-off daemon reads this setting from .swarmforge/roles.tsv to determine polling behavior.

Can multiple roles share the same prompt file?

No. Each role requires its own <role>.prompt file in swarmforge/constitution/articles/. The swarmforge.sh launcher constructs the prompt path dynamically from the SWARMFORGE_ROLE value. However, you can use shell scripts or templating to generate similar prompts for related roles.

Where does the role store its output files?

Each role writes to its isolated Git worktree under .swarmforge/worktrees/<role>/. The hand-off daemon copies completed work to downstream role worktrees based on the [handoff] routing rules. This worktree isolation is enforced by the launcher—roles never write directly to the main repository or each other's directories.

Do I need to manually create the worktree directory?

No. The swarmforge/scripts/swarmforge.sh script automatically initializes the Git worktree when you first launch a role. Manual creation would interfere with the launcher's internal bookkeeping. If you need to reset a role, delete its entry from .swarmforge/worktrees/ and relaunch rather than creating directories by hand.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}