# How to Add a New Agent Role to SwarmForge: A Complete Guide > Learn how to add a new agent role to SwarmForge with this comprehensive guide. Discover the simple steps for creating prompts, registering roles, and launching agents efficiently. - Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge) - Tags: how-to-guide - Published: 2026-09-02 --- **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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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 `.prompt` when starting the agent. ```bash 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`](https://github.com/unclebob/swarm-forge/blob/main/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: ```bash 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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md). --- ## Step 3: Launch the Role to Create Its Worktree Run the launcher script with your new role name: ```bash ./swarmforge/scripts/swarmforge.sh designer ``` The [`swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/my-pack.conf)): ```ini [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`](https://github.com/unclebob/swarm-forge/blob/main/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: ```bash ./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: ```bash # 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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) | Protocol specification for hand-off format and validation | | [`swarmforge/scripts/swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.sh) | Role launcher that creates worktrees and tmux panes | | [`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.sh) | Daemon that routes files between role worktrees | | [`README.md`](https://github.com/unclebob/swarm-forge/blob/main/README.md) | Overview of the pack system and shared scripts | --- ## Summary - **Create** a prompt file in `swarmforge/constitution/articles/.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 ` 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 `.prompt` file in `swarmforge/constitution/articles/`. The [`swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/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//`. 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`](https://github.com/unclebob/swarm-forge/blob/main/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.