# How Constitution Articles Customize Agent Behavior in SwarmForge: A Layered Governance System

> Discover how SwarmForge constitution articles customize agent behavior using plain-text prompt files. Learn about layered governance and dynamic context loading for flexible agent control.

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

---

**Constitution articles customize agent behavior in SwarmForge by acting as plain-text prompt files that are dynamically loaded into an agent's context, allowing shared defaults to be overridden or extended through a hierarchical file system in `swarmforge/constitution/articles/`.**

SwarmForge implements a *layered constitution* architecture that governs every AI agent without requiring code changes. According to the `unclebob/swarm-forge` source code, the system relies on `swarmforge/constitution.prompt` as the entry point, which instructs each agent to consume every article file found under `swarmforge/constitution/articles/`. These articles encode concrete rules for workflow discipline, handoff mechanics, and engineering standards, enabling precise behavioral customization through simple file operations.

## The Layered Constitution Architecture

The constitution system operates as a policy engine where plain-text prompts define agent governance. When an agent starts, orchestration scripts automatically place shared articles from the `main` branch onto the agent's `PATH`, then the agent consumes these articles in list order.

### Shared Defaults vs. Local Overrides

The system distinguishes between **shared articles** (defaults from `main`) and **local articles** (branch-specific customizations):

- **Shared articles** (`workflow.prompt`, `handoffs.prompt`, `engineering.prompt`) provide baseline behavior for all swarms
- **Local articles** (prefixed with `local-`, e.g., `local-workflow.prompt`) extend shared rules without replacing them
- **Overrides** occur when a runnable branch contains a file with the exact same name as a shared article, causing the local version to supersede the default

This layering allows teams to inherit organization-wide standards while specializing behaviors for specific workflows or environments.

## How Articles Shape Specific Behaviors

Each article controls a distinct operational domain. The following files represent the core governance layers in `swarmforge/constitution/articles/`:

### Workflow Discipline (`workflow.prompt`)

The `workflow.prompt` article enforces work-tree discipline, commit message formats, and temporary-file locations. For example, it mandates: *"Include your role byline in every git commit message in this form: `By <role>.`"* This ensures every agent leaves an auditable trail of its actions through standardized git history.

### Handoff Mechanics (`handoffs.prompt`)

The `handoffs.prompt` article governs how agents send and receive work, defining allowed message types and validation steps. It restricts communications to specific protocols: *"Only `git_handoff` and `note` are permitted message types; always forward a `git_handoff` to the next role in the pipeline."* This prevents malformed inter-agent communications that could break pipeline continuity.

### Engineering Standards (`engineering.prompt`)

The shared `engineering.prompt` establishes general coding conventions, test-driven development expectations, and code-review standards. When projects require divergent standards (e.g., mandating Python 3.12 or specific linting tools), teams can override this file entirely or supplement it with `local-engineering.prompt`.

## The Bootstrap and Layering Mechanism

The constitution system initializes through a four-phase bootstrap process implemented in the `./swarm` wrapper scripts.

**1. Bootstrap Phase**

When `./swarm` starts, the wrapper copies missing shared articles from the `main` branch into the runnable branch's `swarmforge/constitution/articles/` folder. This ensures baseline governance exists before agents initialize.

**2. File Resolution**

The system checks for filename collisions between shared and local articles. If a runnable branch contains `engineering.prompt`, the bootstrap skips copying the shared version, causing the agent to consume only the local rules. Files prefixed with `local-` avoid collisions, allowing additive customization.

**3. Agent Consumption**

Each agent's role prompt (located at `swarmforge/roles/<role>.prompt`) begins by invoking the constitution:

```clj
;; Example from coder.prompt
(read-file "swarmforge/constitution.prompt")
;; Agent-specific instructions follow...

```

The `swarmforge/constitution.prompt` file contains a shell loop that concatenates all articles:

```sh
for article in $(ls swarmforge/constitution/articles/*.prompt); do
  cat "$article"
done

```

This injects the full text of every article into the LLM's context window, effectively programming the agent's behavioral constraints through prompt engineering.

**4. Dynamic Customization**

Because articles are plain text, modifications require only git commits. Adding `local-workflow.prompt` to a branch immediately affects the next swarm launch without restarting services or recompiling code.

## Practical Customization Examples

The following patterns demonstrate how to leverage the constitution layering system for specific use cases.

### Extending Defaults with Local Articles

To add QA-specific handoff behavior for a "six-pack" workflow without replacing the standard workflow rules:

```sh

# In a runnable branch (e.g., six-pack)

mkdir -p swarmforge/constitution/articles
cat > swarmforge/constitution/articles/local-workflow.prompt <<'EOF'

# Local Workflow Customisation

## QA-Specific Handoff Rules

- When sending a handoff to the QA role, always set priority to 90.
- Include a `qa_review` tag in the task name.
EOF

```

Because the filename starts with `local-`, the default `workflow.prompt` loads first, followed by these additional constraints.

### Overriding Shared Articles Completely

To replace the default engineering standards entirely:

```sh

# Replace the default engineering article

cat > swarmforge/constitution/articles/engineering.prompt <<'EOF'

# Project-Specific Engineering Rules

- Use only Python 3.12 for new modules.
- All new functions must be type-annotated.
- Run `black` and `ruff` as part of every commit.
EOF

```

The presence of a file named exactly `engineering.prompt` causes the bootstrap to skip the shared version, enforcing these exclusive rules.

### Role-Level Constitution Invocation

Individual roles consume the constitution through explicit file reads. The `coder` role (`swarmforge/roles/coder.prompt`) loads governance before executing task-specific logic:

```text

# In swarmforge/roles/coder.prompt

(read-file "swarmforge/constitution.prompt")
;; Coder-specific instructions follow...

```

This ensures the agent parses `workflow.prompt`, `handoffs.prompt`, and any local extensions before generating code or handling handoffs.

## Summary

- **Constitution articles** are plain-text prompt files stored in `swarmforge/constitution/articles/` that define agent behavior without code changes.
- **Layered inheritance** allows `local-*.prompt` files to extend shared defaults, while identical filenames override them completely.
- **Bootstrap process** copies shared articles from `main` to runnable branches, respecting local file precedence during initialization.
- **Agent ingestion** occurs through `swarmforge/constitution.prompt`, which concatenates all articles into the LLM context via shell loops invoked by role prompts.
- **Key files** include `workflow.prompt` (git discipline), `handoffs.prompt` (inter-agent messaging), and `engineering.prompt` (coding standards), all consumable by helper scripts like [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) and [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh).

## Frequently Asked Questions

### How does SwarmForge handle conflicts between shared and local constitution articles?

SwarmForge resolves conflicts through filename matching during the bootstrap phase. If a runnable branch contains a file with the exact same name as a shared article (e.g., `engineering.prompt`), the local version overrides the shared default entirely. If the local file uses a `local-` prefix (e.g., `local-workflow.prompt`), it loads after the shared article, allowing the rules to extend rather than replace the baseline behavior.

### Can constitution articles enforce specific git commit formats across all agents?

Yes, the `workflow.prompt` article explicitly controls git discipline and commit message formatting. By default, it requires agents to include role bylines in every commit message using the format `By <role>.` Teams can customize this by modifying `workflow.prompt` or adding `local-workflow.prompt` with additional git hooks or message templates, ensuring all agents in a swarm adhere to project-specific version control standards.

### What is the execution order when multiple constitution articles are present?

Articles are consumed in the order returned by the shell command `ls swarmforge/constitution/articles/*.prompt`, which typically follows alphabetical sorting. Shared articles from `main` are copied first, then local modifications are either merged (if prefixed with `local-`) or substituted (if filenames match). The concatenated output is then injected into the agent's prompt context through the `(read-file "swarmforge/constitution.prompt")` invocation in each role's prompt file.

### Are constitution changes immediate, or do they require a swarm restart?

Constitution changes take effect on the next swarm launch. Because `./swarm` bootstrap scripts copy articles from `main` during initialization, modifying or adding files in `swarmforge/constitution/articles/` and committing them to the branch ensures the next execution of `./swarm` loads the updated governance. There is no hot-reload mechanism; agents read the constitution once at startup via the role prompt's `read-file` directive.