# How to Extend the Six‑Pack Workflow with Additional Roles in SwarmForge

> Extend SwarmForge's Six-Pack workflow with custom roles. Learn to create role prompts, update constitutions, add handoff templates, and modify pack scripts for enhanced team collaboration.

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

---

**Add new roles to SwarmForge's Six‑Pack workflow by creating a role prompt, updating the workflow constitution, adding handoff templates, and modifying the pack scripts and commit‑msg hook.**

The **Six‑Pack workflow** in SwarmForge defines a structured collaboration pattern of predefined roles—*coder*, *reviewer*, *tester*, *devops*, *product*, and *manager*—that hand off work in sequence. Extending this workflow with additional roles requires modifying several architectural layers, from prompt files to UI generation scripts.

This guide walks through the complete process of extending the Six‑Pack workflow with additional roles in SwarmForge, based on the source code structure found in `unclebob/swarm-forge`.

## Create the Role Prompt File

Every SwarmForge role is defined by a **prompt file** stored in `swarmforge/roles/`. Create a new `.prompt` file that specifies the role's purpose, scope, responsibilities, and tooling requirements.

Reference the existing `swarmforge/roles/lieutenant.prompt` as a template. A well‑structured role prompt includes:

- **Role identifier** — the canonical name used across the system
- **Description** — the role's primary purpose and domain
- **Responsibilities** — a clear list of duties and deliverables
- **Tooling** — any specialized tools or environments required

```clojure
;; swarmforge/roles/designer.prompt
{:role "designer"
 :description "Design UI/UX, create assets, ensure design consistency."
 :responsibilities ["Review mock‑ups submitted by the coder"
                    "Provide design specifications to the devops role"
                    "Document design decisions in the repository's README"]}

```

The prompt file serves as the **authoritative definition** that both human contributors and agent systems reference when invoking this role.

## Register the Role in the Workflow Constitution

The **Six‑Pack sequence** is defined in `swarmforge/constitution/articles/workflow.prompt`. This ordered list controls which role receives the next handoff.

Edit this file to insert your new role at the appropriate position in the sequence:

```markdown

## Six‑Pack Sequence

1. coder → 2. reviewer → 3. tester → 4. devops → 5. product → 6. manager → 7. designer

```

The **handoff protocol** uses this sequence to route work between roles. Position matters: placing *designer* after *manager* means design artifacts become a final validation step before delivery.

## Add Handoff Templates for Role Transitions

Every **inter‑role handoff** in SwarmForge is governed by templates in `swarmforge/constitution/articles/handoffs.prompt`. You must create explicit handoff templates for each transition involving your new role.

For example, when *devops* hands off to *designer*, define:

```clojure
;; swarmforge/constitution/articles/handoffs.prompt
;; devops → designer handoff template
{{#if (eq .from "devops")}}

## Design Asset Handoff

### Required Fields

- List of compiled assets (PNG, SVG, fonts, etc.)
- Design constraint documentation
- Asset provenance and licensing notes

### Verification Steps

- [ ] Assets render correctly in target environments
- [ ] File sizes meet performance budgets
- [ ] Naming conventions follow design system

Commit suffix: By devops.
{{/if}}

```

Each template must include:
- **Required fields** — data the receiving role needs
- **Verification steps** — checklist items for quality gates
- **Commit suffix** — the `By <role>.` signature enforced by the commit‑msg hook

## Update the Pack Scripts for UI Integration

SwarmForge generates dashboard UIs through **pack scripts** located in `swarmforge/scripts/`. The two primary scripts are `pack_web.bb` (web dashboard) and `pack_board.bb` (board view).

Extend the relevant script to recognize your new role, render its UI panel, and route handoff messages:

```clojure
;; swarmforge/scripts/pack_web.bb
;; Add designer role support

(def valid-roles ["coder" "reviewer" "tester" "devops" "product" "manager" "designer"])

(defn render-role-panel [role]
  (case role
    "designer" (render-designer-panel)
    ;; existing role handlers...
    (render-default-panel role)))

(defn render-designer-panel []
  [:div.panel.designer-panel
   [:h3 "Designer"]
   [:ul.asset-queue (map render-asset pending-assets)]
   [:button {:on-click #(trigger-handoff "designer" "manager")}
    "Hand off to Manager"]])

```

The pack scripts must:
- Include the new role in `valid-roles`
- Implement a role‑specific rendering function
- Wire up handoff triggers to the next role in the sequence

## Adjust the Commit‑Msg Hook

SwarmForge enforces **attribution discipline** through a commit‑msg hook in `swarmforge/scripts/commit_msg_hook.bb`. This hook automatically appends `By <role>.` to commit messages based on the active `ROLE` environment variable.

Add your new role to the hook's validation logic:

```bash

# swarmforge/scripts/commit_msg_hook.bb

#!/bin/bash

tmp_msg=$(cat "$1")
role_suffix=""

case "$ROLE" in
  coder)     role_suffix="By coder." ;;
  reviewer)  role_suffix="By reviewer." ;;
  tester)    role_suffix="By tester." ;;
  devops)    role_suffix="By devops." ;;
  product)   role_suffix="By product." ;;
  manager)   role_suffix="By manager." ;;
  designer)  role_suffix="By designer." ;;  # New role

  *)
    echo "Error: Unknown role '$ROLE'" >&2
    exit 1
    ;;
esac

echo "$tmp_msg" > "$1"
echo "$role_suffix" >> "$1"

```

The hook **rejects commits** from unrecognized roles, ensuring the Six‑Pack workflow remains intact.

## Refresh the Role‑Byline Registry

The master registry of valid roles lives in `swarmforge/constitution.prompt`. This file is loaded at **agent startup** to initialize the role discovery system.

Add your new role to the canonical list:

```clojure
;; swarmforge/constitution.prompt
{:swarm-forge/version "1.2.0"
 :roles [:coder :reviewer :tester :devops :product :manager :designer]
 :workflow {:type :six-pack
            :sequence [:coder :reviewer :tester :devops :product :manager :designer]}}

```

Without this registration, agents cannot discover or invoke the new role.

## Run and Extend the Test Suite

SwarmForge includes comprehensive tests in `test/swarmforge/` that verify the integrity of the Six‑Pack handoff cycle. After adding a role, create analogous tests and ensure full coverage.

Reference `test/swarmforge/pack_web_test.bb` for patterns. A new role test should verify:

- Role prompt parses correctly
- Workflow constitution includes the role in correct sequence
- Handoff templates exist for all adjacent transitions
- Pack script renders the role panel without errors
- Commit‑msg hook accepts the role suffix

```clojure
;; test/swarmforge/designer_role_test.bb
(ns swarmforge.designer-role-test
  (:require [clojure.test :refer :all]
            [swarmforge.roles :as roles]
            [swarmforge.workflow :as workflow]))

(deftest designer-role-exists
  (is (contains? (set (roles/list-roles)) "designer")))

(deftest designer-in-workflow-sequence
  (let [seq (workflow/six-pack-sequence)]
    (is (= "designer" (nth seq 6)))
    (is (= "manager" (nth seq 5)))))

(deftest devops-to-designer-handoff-template-exists
  (is (workflow/has-handoff-template? "devops" "designer")))

```

## Key Files for Extending the Six‑Pack Workflow

| File | Purpose |
|:---|:---|
| `swarmforge/roles/lieutenant.prompt` | Template for role prompt structure |
| `swarmforge/constitution/articles/workflow.prompt` | Defines the ordered Six‑Pack sequence |
| `swarmforge/constitution/articles/handoffs.prompt` | Contains inter‑role handoff templates |
| `swarmforge/scripts/pack_web.bb` | Web dashboard UI generation |
| `swarmforge/scripts/pack_board.bb` | Board view UI generation |
| `swarmforge/scripts/commit_msg_hook.bb` | Enforces `By <role>.` commit attribution |
| `swarmforge/constitution.prompt` | Master role registry for agent discovery |
| `test/swarmforge/pack_web_test.bb` | Test suite reference for new role tests |

## Summary

Extending the Six‑Pack workflow with additional roles in SwarmForge follows a **seven‑step architectural process**:

- **Create** a role prompt file in `swarmforge/roles/` that defines purpose, scope, and responsibilities
- **Register** the role in `swarmforge/constitution/articles/workflow.prompt` at the correct sequence position
- **Add** handoff templates in `swarmforge/constitution/articles/handoffs.prompt` for all adjacent role transitions
- **Update** `swarmforge/scripts/pack_web.bb` or `pack_board.bb` to render the new role's UI panel
- **Adjust** `swarmforge/scripts/commit_msg_hook.bb` to recognize and validate the new role's commit suffix
- **Refresh** `swarmforge/constitution.prompt` to include the role in the master registry
- **Test** thoroughly by adding role‑specific tests and running the full suite

This structure preserves SwarmForge's enforced workflow discipline while accommodating any number of additional roles.

## Frequently Asked Questions

### Can I add multiple roles at once to the Six‑Pack workflow?

Yes, but modify each architectural layer for every role sequentially. Add all role prompts first, then update the workflow constitution with the complete new sequence, followed by all handoff templates, pack script updates, hook modifications, and registry entries. Test comprehensively after batch changes to catch interaction issues between new roles.

### What happens if I forget to update the commit‑msg hook?

Commits made under the new role will fail validation with an "Unknown role" error. The hook in `swarmforge/scripts/commit_msg_hook.bb` explicitly rejects unrecognized roles to maintain attribution integrity. The Six‑Pack workflow depends on accurate bylines for tracking responsibility across handoffs.

### How do I position a new role between existing roles in the sequence?

Edit `swarmforge/constitution/articles/workflow.prompt` and insert the role name at your desired index in the ordered list. Then create handoff templates for both the incoming transition (previous role → new role) and outgoing transition (new role → next role). The pack scripts and tests must account for both new adjacencies.