# How to Add a Completely New Role to an Existing SwarmForge Workflow

> Easily add a new role to your SwarmForge workflow by creating a prompt file and registering it in swarmforge.conf. Restart swarm to apply changes and enhance your development process.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: how-to-guide
- Published: 2026-08-08

---

**To add a completely new role to an existing SwarmForge workflow, create a prompt file at `swarmforge/roles/<role>.prompt` and register the role in [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf), then restart the swarm.**

SwarmForge orchestrates multi-agent workflows through a topology-driven architecture defined in the `unclebob/swarm-forge` repository. Adding a completely new role to an existing SwarmForge workflow requires modifying two specific files—a configuration entry and a prompt file—before the runtime validates and loads the new window automatically.

## Understanding the Two-Source Architecture

SwarmForge builds each workflow window from two distinct sources:

- **[`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf)** – The topology file that lists every role, the agent assigned to run it, and the **receive mode** (`task` or `batch`).
- **`swarmforge/roles/<role>.prompt`** – A plain-text instruction file that tells the chosen agent how to behave.

According to the validation logic in `swarmforge/scripts/swarmforge.bb`, the runtime strictly checks both items during startup.

### Validation Rules for New Roles

The `swarmforge.bb` script enforces three critical constraints when you add a completely new role:

1. **No underscores allowed** in the role name.
2. **Uniqueness required** – duplicate names trigger an error.
3. **Mandatory prompt file** – the file `<role>.prompt` must exist; otherwise SwarmForge aborts with "Missing role prompt".

## Step-by-Step Guide to Adding a New Role

Follow these steps to integrate a new role into any existing branch.

1. **Create the prompt file** at `swarmforge/roles/<new-role>.prompt`. This file contains the instructions the LLM agent follows.

```text

# swarmforge/roles/designer.prompt

designer
You are a UI/UX designer. Produce wireframes and visual mock-ups.
Refer to the project's style guide (swarmforge/constitution/articles/engineering.prompt).

```

2. **Add the configuration line** to [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) using the format:
   `<role> <display-name> <agent> <receive-mode>`

```text

# swarmforge/swarmforge.conf

designer Designer codex task

```

This entry tells SwarmForge to launch the `codex` agent, display the window title "Designer", and set the receive mode to `task`.

3. **Commit or copy the files** into your working branch. SwarmForge copies shared scripts and constitution articles on startup, so both files must be present in the branch you run.

4. **Restart the swarm** to load the new configuration:

```bash
./swarm

# or for a specific branch

./swarm my-feature-branch

```

The startup code parses [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf), validates the role, creates a tmux session, and loads the prompt via the `write-agent-instruction-file!` function.

## Optional Advanced Configuration

### Adding Role-Specific Constitution Articles

If your new role requires additional policy files, add role-specific articles under `swarmforge/constitution/articles/`. The top-level `constitution.prompt` can reference any article, or you can create a local override like `local-designer.prompt` that augments the shared `engineering.prompt`.

## Troubleshooting Common Errors

If validation fails, SwarmForge stops with explicit error messages:

- **"Duplicate role 'designer'"** – The role name already exists in [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf). Choose a unique name.
- **"Missing role prompt"** – The file `swarmforge/roles/<role>.prompt` is missing. Create the file and restart.
- **Underscore errors** – Rename the role to remove underscores.

## Summary

- SwarmForge requires **two files** to define a new role: the prompt file (`swarmforge/roles/<role>.prompt`) and the topology entry ([`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf)).
- The configuration format is `<role> <display-name> <agent> <receive-mode>` with strict **no-underscore** naming rules.
- Validation occurs in `swarmforge/scripts/swarmforge.bb`, which checks for unique names and existing prompt files.
- **Restart the swarm** after adding files to create the new tmux window automatically.
- Optional constitution articles can extend role capabilities without modifying core prompts.

## Frequently Asked Questions

### Can I use underscores in SwarmForge role names?

No. The validation logic in `swarmforge.bb` explicitly forbids underscores in role names. Use hyphens or camelCase instead.

### What is the difference between `task` and `batch` receive modes?

The `task` mode configures the role to receive single work items sequentially, while `batch` mode allows the agent to process multiple items at once. See [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) for detailed handoff semantics.

### Do I need to restart the swarm after adding a new role?

Yes. SwarmForge parses [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) and validates roles only during startup. Restart the swarm with `./swarm` or `./swarm <branch>` to create the new window.

### Where does the agent read its instructions from?

The agent reads the role-specific instructions from `swarmforge/roles/<role>.prompt` via the `write-agent-instruction-file!` function defined in `swarmforge/scripts/swarmforge.bb`. This file must exist before the swarm starts.