# How Agent Behavior Is Defined Using the SwarmForge Constitution System > Discover how SwarmForge constitution defines AI agent behavior using a layered, file-based ruleset. Learn to enforce project-wide discipline with custom prompts. - Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge) - Tags: how-to-guide - Published: 2026-08-09 --- **The SwarmForge constitution system drives AI agent behavior through a layered, file-based ruleset where a root `constitution.prompt` file recursively loads articles from `swarmforge/constitution/articles/` and combines them with role-specific prompts to enforce project-wide discipline.** The `unclebob/swarm-forge` repository implements a declarative governance model for AI swarms. At its core, the SwarmForge constitution system uses plain-text prompt files to encode everything from engineering standards to workflow protocols, ensuring every agent operates within strict, version-controlled boundaries. ## Constitution Entry Point and Architecture Every swarm begins with a single entry point: **`swarmforge/constitution.prompt`**. This file contains a meta-instruction that tells the launcher to recursively read every article it references. ```text # swarmforge/constitution.prompt Read swarmforge/constitution.prompt, then read every file it refers to recursively, and obey all of those instructions. ``` When the swarm starts, the launcher script (`swarmforge/scripts/swarmforge.bb`) loads this file and walks the references it contains. The prompt itself is minimal—its power comes from the *articles* it points to. ### Default Articles Governing Agent Behavior The constitution delegates specific rule domains to individual article files stored in **`swarmforge/constitution/articles/`**. The three default articles shipped on the `main` branch are: - **`engineering.prompt`** — Defines required tooling, language defaults, design guidelines (CRAP, DRY), and verification pipelines. - **`workflow.prompt`** — Enforces work-tree discipline, commit-message format, temporary-file locations, and failure handling. - **`handoffs.prompt`** — Describes the hand-off protocol (git-hand-off vs. note messages) and the runtime layout under `.swarmforge/handoffs/`. Each article is a plain-text `.prompt` file that agents read and apply to their decision-making process. ## Role-Specific Behavior Definition While articles define global rules, individual roles require specialized instructions. Every role listed in [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) must have a matching **`swarmforge/roles/.prompt`** file. These role prompts inherit the global constitution but add tailored guidance: ```text # swarmforge/roles/coder.prompt You are the *coder* role. Implement the requested behavior using TDD and unit tests. Follow the Engineering Rules from engineering.prompt and the Worktree Discipline from workflow.prompt. ``` By explicitly referencing shared articles, the role prompt guarantees that all agents obey the same project-wide policies while still receiving context-specific instructions. For example, an `architect` role might emphasize module boundaries and dependency direction, while a `tester` role focuses on mutation testing and acceptance criteria. ## Runtime Enforcement Mechanisms The SwarmForge constitution system is not merely documentation—it is actively enforced at runtime through three distinct phases: 1. **Article Synchronization** — At startup, the launcher copies missing shared articles into the runnable branch’s `swarmforge/constitution/articles/` directory, skipping any file that already exists. This ensures base rules are present without overwriting local customizations. 2. **Work-Tree Preparation** — The launcher syncs constitution files into each role’s dedicated work-tree, ensuring the agent’s environment contains both the helper scripts and the constitutional rules. 3. **Hand-Off Validation** — Throughout the agent lifecycle, entry scripts ([`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh), [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh), [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh)) read the constitution and enforce its rules during the hand-off cycle. If an agent deviates—such as working on the wrong branch, omitting the required commit-byline, or invoking a stale tool—the constitution’s rules cause the agent to **stop and report** rather than silently proceed. ## Extending the Constitution with Local Articles Runnable branches can extend the base behavior by adding *local* articles (e.g., `local-workflow.prompt`) to their `swarmforge/constitution/articles/` directory. These local files narrow or extend the shared rules without replacing them, preserving a single source of truth for base behavior while allowing project-specific customization. ```bash # Example: Creating a local constitution extension cat > swarmforge/constitution/articles/local-engineering.prompt <<'EOF' In addition to the Engineering Rules, you must run property-based tests before marking any task complete. EOF ``` ## Summary - The SwarmForge constitution system uses a recursive file structure starting at `swarmforge/constitution.prompt` to load behavioral rules. - **Articles** (`engineering.prompt`, `workflow.prompt`, `handoffs.prompt`) encode global standards for tooling, discipline, and communication. - **Role prompts** (`swarmforge/roles/.prompt`) inherit the constitution and add specialized instructions for specific swarm members. - The launcher (`swarmforge/scripts/swarmforge.bb`) synchronizes these files into agent work-trees at startup. - Runtime enforcement occurs through hand-off scripts that validate compliance before allowing agents to proceed. ## Frequently Asked Questions ### What is the difference between a constitution article and a role prompt? A **constitution article** defines project-wide rules that apply to every agent in the swarm, such as commit formats or allowed tools. A **role prompt** defines behavior specific to a single role (e.g., `coder` or `architect`) and explicitly references the shared articles to ensure it operates within the global constraints. ### Can I override a default article without modifying the SwarmForge repository? Yes. You can add a *local* article to your runnable branch’s `swarmforge/constitution/articles/` directory. The launcher copies missing shared articles first, then respects your local files, allowing you to extend or narrow rules without altering the base `main` branch files. ### How does the constitution enforce rules if an agent tries to deviate? The hand-off scripts ([`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh), [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh), [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh)) parse the constitution at each state transition. If an agent produces an invalid commit hash, works on an incorrect branch, or violates workflow discipline, the validation logic triggers a failure that halts progress and reports the specific constitutional violation. ### Where is the constitution actually loaded during agent startup? The launcher script `swarmforge/scripts/swarmforge.bb` (specifically around lines 303-472) reads the root `constitution.prompt`, resolves all recursive article references, and copies the resulting rule set into the agent’s work-tree before the agent process begins execution.