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

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, 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 – 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.

# 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 using the format: <role> <display-name> <agent> <receive-mode>

# 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:

./swarm

# or for a specific branch

./swarm my-feature-branch

The startup code parses 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. 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).
• 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 for detailed handoff semantics.

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

Yes. SwarmForge parses 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.

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