# How Constitution Layering Works with Prompt Files in Swarm Forge

> Learn how constitution layering in Swarm Forge works with prompt files. Stack shared articles, project overrides, and role instructions for a unified agent context.

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

---

**Constitution layering in Swarm Forge works by stacking three tiers of prompt files—shared articles, project-specific overrides, and role-specific instructions—into a single hierarchical context that agents follow at runtime.**

Swarm Forge implements a **layered constitution** system that assembles an agent's operating rules from multiple prompt files. This design, as implemented in `unclebob/swarm-forge`, separates universal policies from project customizations and individual role definitions, giving teams fine-grained control over agent behavior without duplication.

## The Entry Point: `swarmforge/constitution.prompt`

Every agent starts from a single orchestration file. In `swarmforge/constitution.prompt`, the system defines the loading sequence:

```text

# swarmforge/constitution.prompt

Read every file in swarmforge/constitution/articles/ and obey those
instructions. Then read swarmforge/roles for your role.

```

This two-step directive establishes the loading order: **shared articles first**, then **role-specific instructions**. The agent concatenates these prompts in sequence, with later content taking precedence where conflicts arise.

## Layer 1: Base Constitution Articles

The foundation consists of standalone `.prompt` files in `swarmforge/constitution/articles/`. Each file encapsulates a functional domain.

**Core articles in the repository include:**

- `engineering.prompt` — coding standards and technical practices
- `workflow.prompt` — overall process expectations and state management
- `handoffs.prompt` — rules governing agent-to-agent transfers

The entry point iterates through **all files in this directory alphabetically by filename**, loading each into context. This creates the *shared constitutional baseline* applied to every agent regardless of role.

**Creating a new constitutional rule:**

```bash

# Create a security-focused article

cat > swarmforge/constitution/articles/security.prompt <<'EOF'
You must never disclose secrets, API keys, or passwords.
All communication should be logged for auditability.
EOF

# Stage and commit—the startup script auto-includes new articles

git add swarmforge/constitution/articles/security.prompt
git commit -m "Add security article to constitution"

```

## Layer 2: Project-Specific Overrides

Packs (configuration bundles like `two-pack` or `four-pack`) can ship `local-*.prompt` files that supplement or override the base articles. These files are **not name-matched** against shared articles; they simply append additional rules.

The startup script copies the composed `swarmforge/constitution/` tree into each role's working context, ensuring every agent sees identical base content plus any pack-provided extensions. This allows per-project customization without modifying the core repository.

## Layer 3: Role-Specific Prompts

After constitution articles load, the agent reads its designated role prompt at `swarmforge/roles/<role>.prompt`. This final layer defines specialized responsibilities and can reference the constitution recursively.

**Example from `swarmforge/roles/lieutenant.prompt`:**

```prompt
You are a Lieutenant. Follow the shared constitution first:
{{ read constitution.prompt }}

Additional duties:
- Coordinate engineering and workflow teams.
- When a handoff is required, follow the rules in handoffs.prompt.

```

The `{{ read constitution.prompt }}` syntax ensures agents re-load the latest constitutional rules dynamically—particularly useful after handoffs or context switches, as documented in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md).

## Deterministic Layer Ordering and Precedence

The concatenation sequence guarantees predictable behavior:

| Order | Layer | Source Pattern | Override Capability |
|-------|-------|---------------|---------------------|
| 1 | Shared articles | `swarmforge/constitution/articles/*.prompt` | Base definitions |
| 2 | Local extensions | `local-*.prompt` (pack-supplied) | Extend or specialize |
| 3 | Role prompt | `swarmforge/roles/<role>.prompt` | Final authority |

Later layers **override** earlier definitions when conflicts occur. This hierarchy lets roles refine or specialize broad policies without rewriting shared files.

## Runtime Assembly Example

The startup sequence (simplified):

```bash

# Load constitution layer: all articles concatenated

cat swarmforge/constitution/articles/*.prompt > /tmp/constitution.txt

# Append pack-specific local overrides if present

cat swarmforge/constitution/local-*.prompt >> /tmp/constitution.txt 2>/dev/null

# Append role-specific final layer

cat swarmforge/roles/lieutenant.prompt >> /tmp/constitution.txt

# Agent receives complete hierarchical prompt

```

## Key Files and References

| Path | Purpose |
|------|---------|
| `swarmforge/constitution.prompt` | Orchestration entry point defining load order |
| `swarmforge/constitution/articles/*.prompt` | Shared functional domains (engineering, workflow, handoffs) |
| `swarmforge/roles/<role>.prompt` | Role-specific specializations and recursive constitution references |
| [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) | Documents re-reading patterns for dynamic constitution updates |
| [`README.md`](https://github.com/unclebob/swarm-forge/blob/main/README.md) (Layered Constitution section) | Architectural overview of the three-tier system |

## Summary

- **Constitution layering** assembles agent context from three tiers: shared articles, project overrides, and role prompts
- `swarmforge/constitution.prompt` controls loading order with a simple two-step directive
- Files in `swarmforge/constitution/articles/` establish universal policies loaded alphabetically
- Pack-provided `local-*.prompt` files enable project-specific customization
- `swarmforge/roles/<role>.prompt` delivers final role specialization with recursive constitution re-reading
- Later layers override earlier ones, creating clean hierarchical precedence

## Frequently Asked Questions

### How do I add a new rule that applies to all agents?

Create a `.prompt` file in `swarmforge/constitution/articles/`. The startup script automatically includes all files in this directory; alphabetical order determines loading sequence. Commit the file to propagate the rule across all roles.

### Can one agent use different constitution articles than another?

All agents share identical base articles from `swarmforge/constitution/articles/`. Differentiation occurs at the role layer (`swarmforge/roles/<role>.prompt`) or through pack-specific `local-*.prompt` extensions. Roles cannot selectively exclude base articles—they receive the full set.

### What happens when two articles define conflicting instructions?

Later layers override earlier ones. Within the article layer, alphabetical filename order determines precedence. For definitive control, place overriding rules in the role prompt (`swarmforge/roles/<role>.prompt`), which loads last and holds final authority.

### Why do role prompts re-read the constitution with `{{ read constitution.prompt }}`?

This pattern ensures agents operate with current rules after context switches or handoffs. Since the constitution may evolve or agents may enter mid-workflow, the explicit re-read guarantees synchronization. The [`handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/handoff-protocol.md) file documents when this re-reading is required.