# How to Configure Custom Roles and Worktrees in SwarmForge > Learn to configure custom roles and worktrees in SwarmForge by creating prompt files, registering them with role-add, and setting worktree names in swarmforge.conf. - Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge) - Tags: how-to-guide - Published: 2026-08-08 --- **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`](https://github.com/unclebob/swarm-forge/blob/main/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/.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. ```bash 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. ```bash ./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. ```bash ./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: ```bash ./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. ```bash ./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`](https://github.com/unclebob/swarm-forge/blob/main/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 ` 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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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.