SwarmForge Layered Constitution System: How Constitution Articles Govern AI Agents

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:

# 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:

# 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:

# 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:

# 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:

# 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}