How to Configure Custom Roles and Worktrees in SwarmForge

You configure custom roles by creating prompt files in swarmforge/roles/ and registering them in the .swarmforge/roles.tsv state file using the swarmforge.sh role-add command, then optionally set custom worktree names with role-worktree-name.

SwarmForge does not use a traditional swarmforge.conf file. Instead, the unclebob/swarmforge repository implements a role-state architecture that tracks roles and their associated Git worktrees in a tab-separated registry. This design decouples role definitions from their execution environments, allowing you to configure multiple AI personas that operate on isolated worktrees.

Understanding the Role-State Architecture

Before modifying configuration, understand how SwarmForge stores role metadata. The system uses three coordinated components:

• Prompt files: Stored in swarmforge/roles/<role-name>.prompt, these define the role's behavior and instructions.
• Role-state registry: The .swarmforge/roles.tsv file in your repository root maintains a three-column mapping of role, mode (e.g., receive or send), and worktree name.
• Helper scripts: Located in swarmforge/scripts/, these provide the role-add, role-worktree-name, and role-known commands that manipulate the registry.

When you invoke a hand-off, the scripts query .swarmforge/roles.tsv to determine which worktree directory to enter before executing role-specific logic.

Step-by-Step Configuration

Create the Role Prompt File

First, define your custom role by adding a .prompt file to the roles directory. The filename (minus extension) becomes your role identifier.

echo "Senior Python Architect with expertise in refactoring" > swarmforge/roles/senior-architect.prompt

Register the Role in roles.tsv

Use the main SwarmForge script to add your role to the state file. This creates the entry in .swarmforge/roles.tsv with default values.

./swarmforge/scripts/swarmforge.sh role-add senior-architect

By default, this assigns:

• Mode: receive
• Worktree: senior-architect-ws

The resulting line in .swarmforge/roles.tsv appears as:

senior-architect    receive    senior-architect-ws

Customize the Worktree Name

To override the default worktree naming convention, use the role-worktree-name command. This updates the third column in the registry without recreating the role.

./swarmforge/scripts/swarmforge.sh role-worktree-name senior-architect legacy-refactor-ws

This modifies the entry to:

senior-architect    receive    legacy-refactor-ws

Verify Your Configuration

Confirm your role and worktree mapping using the role-known command:

./swarmforge/scripts/swarmforge.sh role-known

This outputs all registered roles with their current modes and associated worktrees, allowing you to audit your configuration before executing hand-offs.

Working with Configured Roles

Once configured, reference your custom role in hand-off scripts. The system automatically resolves the worktree from .swarmforge/roles.tsv and switches to that directory.

./swarmforge/scripts/handoff_lib.bb role-receive-mode senior-architect

In this example, the script reads the senior-architect entry, identifies legacy-refactor-ws as the target worktree, and executes the receive-mode logic within that Git worktree context.

Summary

• SwarmForge uses .swarmforge/roles.tsv rather than a traditional swarmforge.conf file to map roles to worktrees.
• Create role definitions as .prompt files in swarmforge/roles/ before registering them.
• Use ./swarmforge/scripts/swarmforge.sh role-add <role> to initialize role entries with default worktree names.
• Override worktree names using role-worktree-name to customize your development environment structure.
• The role-known command provides visibility into your current role-to-worktree mappings.

Frequently Asked Questions

What is the difference between swarmforge.conf and roles.tsv?

SwarmForge does not implement a swarmforge.conf file. Instead, configuration lives in .swarmforge/roles.tsv, a tab-separated file that tracks role names, operational modes, and Git worktree associations. This state-driven approach allows scripts to dynamically resolve execution contexts without parsing complex configuration syntax.

How do I change the mode for an existing role?

While modes like receive are stored in the second column of .swarmforge/roles.tsv, the helper scripts do not expose a dedicated role-set-mode command. You must manually edit .swarmforge/roles.tsv to change the mode value between receive and send, or remove and re-add the role using role-add if the script supports mode flags.

Can multiple roles share the same worktree?

Yes. Since .swarmforge/roles.tsv maps roles to arbitrary worktree name strings, you can assign identical worktree values to different roles. Both roles will operate within the same Git worktree context, though they will use different prompt files from swarmforge/roles/ for their respective behaviors.

Where are the role helper scripts located?

The role management commands are implemented in swarmforge/scripts/swarmforge.sh within the unclebob/swarmforge repository. This script provides the role-add, role-worktree-name, and role-known interfaces that read from and write to the .swarmforge/roles.tsv registry.

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