# How SwarmForge Uses the Layered Constitution System to Direct Agent Behavior

> SwarmForge directs AI agents with a layered constitution system. It combines baseline rules with pack-specific overrides for a single source of truth and localized customization.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: deep-dive
- Published: 2026-08-31

---

**SwarmForge directs every AI agent through a layered constitution system that composes shared baseline rules with pack-specific overrides, establishing a single source of truth for operational behavior while permitting localized customization.**

The `unclebob/swarm-forge` repository implements a sophisticated governance model where the layered constitution system acts as the authoritative source for agent behavior. This architecture ensures that every AI assistant follows consistent engineering standards, workflow protocols, and handoff procedures defined in the core articles, while individual projects inject specialized instructions through local overrides without forking the base rules.

## Understanding the Layered Constitution Architecture

The constitution system organizes agent instructions into three distinct layers that merge during pack initialization.

**The Entry Point** (`swarmforge/constitution.prompt`) serves as the root directive. This file contains a simple instruction: read every file in `swarmforge/constitution/articles/` and obey those instructions. This design pattern separates the bootstrap mechanism from the operational content, allowing the core message to remain stable while the specific rules evolve.

**Shared Articles** reside in `swarmforge/constitution/articles/` and establish global policies applicable to all packs. Key files include:

- `engineering.prompt` – Defines tool usage constraints and mutation policies
- `workflow.prompt` – Governs task progression and quality gates
- `handoffs.prompt` – Specifies protocols for transferring control between agents

**Local Overrides** follow the naming convention `local-*.prompt` and live within individual pack directories. When a pack instantiates, these files merge with the shared articles, allowing project-specific rules to override or extend baseline behavior without modifying the canonical source code.

## The Agent Execution Flow

When an agent initializes, it processes the layered constitution system through a strict four-phase pipeline:

1. **Read `swarmforge/constitution.prompt`** – The agent loads the entry point file, which directs it to discover all articles in the constitution directory.

2. **Iterate Shared Articles** – The agent sequentially loads each file from `swarmforge/constitution/articles/`, applying the embedded operational rules. These articles define immutable policies such as how to execute constitution tools, constraints for code mutations, and expectations for quality gates.

3. **Load Role-Specific Prompts** – The agent reads its designated role file from `swarmforge/roles/<role>.prompt`. This prompt explicitly references the shared constitution (e.g., "Read `swarmforge/constitution.prompt` or the constitution articles") and layers role-specific goals, constraints, or specialized instructions atop the baseline rules.

4. **Execute with Composed Guidance** – The agent operates using the merged instruction set, where shared articles provide the foundation and role prompts provide the specialization. Because the constitution is layered—shared articles first, then pack-specific `local-*.prompt` overrides—agents automatically inherit core disciplinary processes while adapting to local project requirements.

## Constitution Composition and Pack Integration

The `get-swarm-forge` utility orchestrates the assembly of the layered constitution during pack creation. This tool copies the shared articles from the repository's `main` branch into the pack's workspace, then scans for any `local-*.prompt` files within the pack directory. The resulting tree at `swarmforge/constitution/articles/` represents the **composed constitution** for that specific project.

According to the source implementation in `swarmforge/scripts/swarmforge.bb`, the startup sequence ensures constitution availability by copying the entire `swarmforge/constitution/` directory into every role's worktree. The script also modifies the agent's `PATH` environment variable to include the constitution directory, ensuring agents can reference constitutional tools and scripts regardless of their current working directory.

## Role-Specific Prompts and the Layered Stack

Role prompts function as the final layer in the constitution stack. Located at `swarmforge/roles/<role>.prompt`, these files explicitly acknowledge the layered constitution system by instructing the agent to first ingest the shared articles before executing role-specific logic.

This design enforces a **cascading authority** where:
- Base articles define universal constraints (e.g., "Never commit directly to main")
- Pack overrides adjust workflows (e.g., "Use `develop` branch instead of `main`")
- Role prompts specialize objectives (e.g., "As a Test Agent, focus on mutation testing")

The separation ensures that security-critical or workflow-essential rules in the base constitution cannot be accidentally omitted by role designers, while still granting flexibility for domain-specific instructions.

## Implementation Details and Source Code

The constitution loading mechanism relies on standard file system operations implemented in the startup scripts. The following Clojure excerpt from the initialization logic demonstrates how agents verify and load the constitutional framework:

```clojure
;; Simplified agent bootstrap from swarmforge/scripts/swarmforge.bb
(let [ctx {:constitution-file (fs/path worktree "swarmforge" "constitution.prompt")}]
  ;; Verify the constitution exists
  (when-not (fs/exists? (:constitution-file ctx))
    (throw (ex-info "Constitution prompt not found" ctx)))
  ;; Read the entry prompt
  (let [entry (slurp (:constitution-file ctx))]
    ;; Entry tells the agent to read every article
    (doseq [article (fs/list-dir (fs/path worktree "swarmforge" "constitution" "articles"))]
      (let [text (slurp article)]
        ;; Apply the article's instructions
        (process-article text)))))

```

Agents may also invoke shell helpers to ensure constitutional compliance. This pattern appears in role execution scripts that source the layered rules:

```bash

# Constitutional compliance helper

read-constitution() {
  # Load the entry point

  while read -r line; do
    [[ $line =~ ^Read\ every\ file\ in\ (.+) ]] && base="${BASH_REMATCH[1]}"
  done < swarmforge/constitution.prompt

  # Iterate over all article files

  for f in "$base"/*; do
    echo "Applying $(basename "$f")"
    source "$f"
  done
}

```

The unit tests in `test/swarmforge/script_test.clj` verify that the `get-swarm-forge` command correctly merges base articles with local overrides, ensuring the layered constitution system maintains integrity across different pack configurations.

## Summary

- The **layered constitution system** uses `swarmforge/constitution.prompt` as the universal entry point that directs agents to the articles directory.
- **Shared articles** in `swarmforge/constitution/articles/` establish non-negotiable operational rules for engineering, workflow, and handoffs.
- **Pack-specific overrides** via `local-*.prompt` files allow projects to customize behavior without modifying the canonical constitution.
- **Role prompts** in `swarmforge/roles/` specialize the base constitution for specific agent functions while maintaining dependency on core rules.
- The **startup script** (`swarmforge/scripts/swarmforge.bb`) ensures every agent worktree contains the complete composed constitution and appropriate environment configuration.

## Frequently Asked Questions

### What is the primary purpose of the constitution.prompt file in SwarmForge?

The `swarmforge/constitution.prompt` file serves as the universal bootstrap directive for every agent in the system. It contains the fundamental instruction to read and obey every file within `swarmforge/constitution/articles/`, establishing the entry point through which all constitutional rules flow. This separation of bootstrap logic from operational content allows the core invocation pattern to remain stable while the specific rules evolve.

### How does SwarmForge handle pack-specific customizations without modifying the base constitution?

SwarmForge implements a merge strategy through the `get-swarm-forge` utility, which copies shared articles from the `main` branch and then incorporates any `local-*.prompt` files found in the pack directory. These local files overlay or extend the base rules, creating a composed constitution specific to that project. This architecture ensures that common behavioral standards remain centralized while individual packs adapt workflows to their specific requirements.

### Where does the system verify that agents correctly load the layered constitution?

The verification logic resides in `test/swarmforge/script_test.clj`, which contains unit tests confirming that the constitution loading behavior works correctly across different pack configurations. Additionally, the startup script `swarmforge/scripts/swarmforge.bb` performs runtime validation by checking for the existence of `swarmforge/constitution.prompt` before copying the entire constitution tree into each role's worktree, ensuring agents cannot execute without access to the full rule set.

### How do role-specific prompts interact with the shared constitution layers?

Role prompts stored in `swarmforge/roles/<role>.prompt` explicitly reference the layered constitution system by instructing agents to first ingest the shared articles before executing role-specific tasks. This creates a dependency chain where the role cannot operate without the base constraints, ensuring that universal policies (such as handoff protocols or engineering standards) remain enforced even as agents pursue specialized objectives like testing, refactoring, or documentation generation.