How Agent Behavior Is Defined Using the SwarmForge Constitution System

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.

# 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 must have a matching swarmforge/roles/<role>.prompt file.

These role prompts inherit the global constitution but add tailored guidance:

# 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, ready_for_next.sh, 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.

# 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/<role>.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, ready_for_next.sh, 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.

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