# SwarmForge Layered Constitution System: How Constitution Articles Govern AI Agents > Explore SwarmForge's layered constitution system. Discover how plain-text articles govern AI agents with root entry points, shared defaults, and local overrides for deterministic behavior. - Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge) - Tags: deep-dive - Published: 2026-08-10 --- **SwarmForge uses a hierarchical layered constitution system where three distinct layers—root entry points, shared default articles, and local branch overrides—combine to provide AI agents with deterministic behavioral rules through plain-text constitution articles.** The `unclebob/swarm-forge` repository implements a sophisticated layered constitution system that governs how AI agents behave during software development workflows. This system organizes configuration into three hierarchical layers, allowing teams to enforce consistent engineering standards while maintaining workflow-specific flexibility through constitution articles stored as version-controlled prompt files. ## How the Layered Constitution System Works SwarmForge's constitution is not monolithic; it is deliberately stratified to balance consistency with customization. The architecture consists of three distinct elements that work together to form a complete behavioral framework. ### Root Entry Point The foundation begins with `swarmforge/constitution.prompt`, which serves as the bootstrap mechanism. According to the source code, this file instructs agents to ingest every rule file located in the `swarmforge/constitution/articles/` directory using a shell command that concatenates all `*.prompt` files: ```text # swarmforge/constitution.prompt # Tell agents to ingest all rule files under the articles directory $(find swarmforge/constitution/articles -type f -name '*.prompt' -print0 | xargs -0 cat) ``` ### Shared Default Articles Stored exclusively on the `main` branch, these baseline files provide universal policies inherited by all runnable branches. The repository includes three core shared articles that define engineering, handoff, and workflow standards: - **engineering.prompt** – Defines commit-message formats and temporary-file locations - **handoffs.prompt** – Specifies the handoff protocol between agents - **workflow.prompt** – Establishes work-tree discipline and failure-condition handling ### Local Overrides and Extensions Runnable branches—such as `two-pack`, `four-pack`, or `six-pack`—can specialize these rules by adding files to their local `swarmforge/constitution/articles/` directory. Files following the `local-*.prompt` naming convention extend the defaults, while files matching existing shared article names completely override the shared version for that branch. ## Article Inheritance and Override Logic When a swarm initializes, the startup script synchronizes articles from the `main` branch into the runnable branch's constitution directory. The merge logic follows a specific inheritance pattern: **missing** shared articles are copied automatically, but existing local files are **never overwritten**. This creates the layered effect where: 1. **Base layer** – Shared defaults provide a consistent foundation across all workflows 2. **Branch layer** – Each runnable branch can add `local-*.prompt` files to specialize the defaults 3. **Override layer** – Branches can commit files with identical names to shared articles (e.g., `workflow.prompt`) to replace the shared version completely ## Structure and Content of Constitution Articles **Constitution articles** are declarative prompt files containing behavioral rules that agents read at startup. These files specify concrete requirements such as commit-message formats, work-tree discipline, handoff validation protocols, and temporary-file locations. Because these files use plain text, they integrate with standard version control workflows, allowing code review and audit trails for policy changes. Agents enforce these rules while executing assigned tasks, creating a deterministic behavioral framework that can be modified through familiar git operations. ## Practical Configuration Examples ### Loading the Complete Constitution The root entry point uses shell expansion to concatenate all articles into a single configuration: ```text # swarmforge/constitution.prompt # Tell agents to ingest all rule files under the articles directory $(find swarmforge/constitution/articles -type f -name '*.prompt' -print0 | xargs -0 cat) ``` ### Adding Branch-Specific Extensions To add specialized rules without modifying shared defaults, create a `local-*.prompt` file: ```text # swarmforge/constitution/articles/local-engineering.prompt # Extra engineering rule for the four-pack workflow - Do not commit generated files that reside in the `target/` directory. ``` ### Overriding Shared Articles Completely When a branch requires fundamentally different rules, commit a file with the same name as the shared article: ```text # swarmforge/constitution/articles/workflow.prompt (branch-specific version) # New workflow rule set for the six-pack workflow - All handoffs must include a `type: git_handoff` entry. - Every commit message must contain a JIRA ticket ID like `ABC-123`. ``` ### Agent-Side Integration Role agents source the constitution at startup to access embedded functions and variables: ```bash # Example snippet that a role agent might run source "$SWARMFORGE_ROOT/swarmforge/constitution.prompt" # loads all rules # Now the agent can rely on variables/functions defined in the articles, # e.g., validate_commit_message, enforce_worktree_policy, etc. ``` ## Summary - The **layered constitution system** in `unclebob/swarm-forge` organizes AI governance into three hierarchical layers: root entry points, shared default articles, and local branch overrides. - **Shared articles** (`engineering.prompt`, `handoffs.prompt`, `workflow.prompt`) reside on the `main` branch and provide baseline policies for all workflows. - **Local overrides** using the `local-*.prompt` naming convention allow branches to extend defaults without modifying shared files. - **Complete overrides** occur when a branch commits a file matching a shared article name, which the startup script preserves instead of overwriting. - **Constitution articles** are plain-text prompt files that agents ingest at startup, enabling version-controlled, auditable behavioral policies. ## Frequently Asked Questions ### What happens if a runnable branch has a file with the same name as a shared constitution article? The startup script copies missing shared articles from the `main` branch but **does not overwrite** existing files. If your branch contains a local `workflow.prompt`, it will replace the shared version entirely for that branch, allowing complete customization of specific rule sets while inheriting other defaults. ### How do I add workflow-specific rules without modifying the shared defaults? Create a file following the `local-*.prompt` naming convention (for example, `local-engineering.prompt`) in your branch's `swarmforge/constitution/articles/` directory. These extension files are loaded alongside shared articles, adding specialized constraints without altering the baseline policies stored on `main`. ### Where are the baseline constitution articles stored in the repository? The shared default articles are located on the `main` branch within the `swarmforge/constitution/articles/` directory. Key files include `engineering.prompt` for commit standards, `handoffs.prompt` for agent communication protocols, and `workflow.prompt` for worktree discipline, all of which are copied to runnable branches during swarm initialization if not already present. ### Can constitution articles be version controlled and reviewed like code? Yes. Because constitution articles are plain text prompt files, they integrate directly with standard git workflows. Teams can commit changes, open pull requests for policy modifications, and maintain audit trails for behavioral rule updates, treating AI governance with the same rigor as source code.