# How Constitution Articles Layer with Pack-Specific Prompts in Swarm Forge

> Discover how Swarm Forge's Constitution articles layer with pack-specific prompts. Learn about global baseline policies and specialized overrides for advanced control.

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

---

**Constitution articles form a three-layer stack in Swarm Forge: the global constitution file pulls in shared articles as a baseline policy, and pack-specific prompts are appended last to allow specialized overrides.**

Swarm Forge manages **agent system prompts through a hierarchical layering system** where constitution articles establish universal governance rules, and pack-specific prompts provide final customization. Understanding how constitution articles layer with pack-specific prompts is essential for controlling agent behavior across different packs and roles.

## The Three-Layer Prompt Architecture

Swarm Forge constructs every agent's complete instruction set through three distinct layers processed in strict order.

### Layer 1: Global Constitution Entry Point

The foundation begins with `swarmforge/constitution.prompt`. This single-line file contains a directive instructing the agent to **read every file in `swarmforge/constitution/articles/` and obey those instructions recursively**.

Because this file uses recursive language, it automatically discovers and incorporates all article files without explicit enumeration in the agent instruction generator.

### Layer 2: Constitution Articles

The **shared articles** live in `swarmforge/constitution/articles/` and are defined in `swarmforge/scripts/forge.bb`:

| Article File | Purpose |
|-------------|---------|
| `engineering.prompt` | Software engineering standards and practices |
| `workflow.prompt` | Process and collaboration workflows |
| `handoffs.prompt` | Agent-to-agent communication protocols |

These files are declared as **shared-articles** in the build configuration:

```clojure
;; swarmforge/scripts/forge.bb
(def shared-articles ["engineering.prompt"
                      "workflow.prompt"
                      "handoffs.prompt"])

```

When a pack is loaded, these articles are **copied into the pack's state directory** alongside the constitution file. The recursive loading mechanism in `constitution.prompt` ensures all three articles become active policy for every agent.

### Layer 3: Pack-Specific and Role Prompts

The final layer comes from **role-specific prompt files** stored in `swarmforge/roles/` (e.g., `lieutenant.prompt`, `coder.prompt`). The function `write-agent-instruction-file!` in `swarmforge/scripts/swarmforge.bb` assembles the complete instruction set:

```clojure
;; swarmforge/scripts/swarmforge.bb (lines 450-457)
(defn write-agent-instruction-file!
  [ctx role prompt-file last-role?]
  ;; ... file setup ...
  (spit (str prompt-file)
        (str "Read swarmforge/constitution.prompt, then read every file it refers to recursively, and obey all of those instructions.\n"
             "Read swarmforge/roles/" role ".prompt, then read every file it refers to recursively, and follow all of those instructions.\n")))

```

The **explicit ordering in this function** determines precedence: constitution articles are loaded first as baseline policy, and the role-specific prompt follows. If a pack provides its own `.prompt` file, it is concatenated after the role prompt, making it the **final behavioral authority**.

## Final Prompt Order and Precedence

The complete instruction stack resolves to this execution order:

```

1. constitution.prompt (entry point)
   ├── engineering.prompt (shared article)
   ├── workflow.prompt (shared article)
   └── handoffs.prompt (shared article)
2. <role>.prompt (e.g., lieutenant.prompt, coder.prompt)
3. [optional] pack-specific .prompt file

```

This structure ensures that **pack-specific prompts can extend or override** constitution articles without breaking shared governance. The articles act as guardrails; pack-specific content provides specialization.

## Key Files in the Layering System

| File Path | Function | Relevant Reference |
|-----------|----------|------------------------|
| `swarmforge/constitution.prompt` | Entry point for recursive article loading | Constitution directive |
| `swarmforge/constitution/articles/*.prompt` | Global policy articles (engineering, workflow, handoffs) | Shared articles |
| `swarmforge/scripts/forge.bb` | Declares shared-articles list and copies constitution to pack state | Line 9 |
| `swarmforge/scripts/swarmforge.bb` | Generates final instruction file with explicit layer ordering | Lines 450-457 (`write-agent-instruction-file!`) |
| `swarmforge/roles/*.prompt` | Role-specific behavioral templates | Role prompt directory |

## How Pack Overrides Work in Practice

When you need a pack to behave differently from the global constitution, **place custom directives in the pack's `.prompt` file or modify the role prompt**. Because these load last, they take precedence in the agent's instruction context according to the `write-agent-instruction-file!` implementation.

For example, if `engineering.prompt` specifies "use test-driven development," but a particular pack's prompt states "prototyping mode—tests optional," the agent receives both instructions but the **pack-specific directive appears last and carries final weight** in typical LLM system prompt interpretation.

## Summary

- **Constitution articles** in `swarmforge/constitution/articles/` provide universal baseline policy through recursive loading.
- **`write-agent-instruction-file!`** explicitly orders layers: constitution first, role prompt second, pack-specific content last.
- **Pack-specific prompts** are appended at the end of the instruction file, enabling behavioral specialization without forking shared governance rules.
- The `shared-articles` list in `forge.bb` controls which article files are distributed to every pack's state directory.

## Frequently Asked Questions

### What happens if a constitution article conflicts with a pack-specific prompt?

Pack-specific prompts take precedence because they appear last in the instruction file generated by `write-agent-instruction-file!`. The LLM typically weighs later instructions more heavily. For strict enforcement of constitution rules, ensure articles use imperative language that pack prompts cannot easily override.

### Where do I add a new global policy that all packs must follow?

Create a new `.prompt` file in `swarmforge/constitution/articles/`, then add its filename to the `shared-articles` vector in `swarmforge/scripts/forge.bb`. The recursive loading mechanism in `constitution.prompt` will automatically include it for all agents.

### Can a pack opt out of specific constitution articles?

No direct opt-out mechanism exists. All `shared-articles` are copied to every pack's state and loaded via the constitution entry point. To create pack-specific exceptions, **override the unwanted behavior** in the pack's or role's prompt file rather than excluding the article.

### How does `write-agent-instruction-file!` handle multiple roles in a pack?

The function generates separate instruction files per role. Each file contains the same constitution-article preamble, followed by that specific role's prompt from `swarmforge/roles/<role>.prompt`. This ensures **consistent baseline governance** across all roles in a pack while allowing role-specific specialization.