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

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

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

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

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

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

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

;; 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

;; 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.

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