How Constitution Articles Customize Agent Behavior in SwarmForge: A Layered Governance System

Constitution articles customize agent behavior in SwarmForge by acting as plain-text prompt files that are dynamically loaded into an agent's context, allowing shared defaults to be overridden or extended through a hierarchical file system in swarmforge/constitution/articles/.

SwarmForge implements a layered constitution architecture that governs every AI agent without requiring code changes. According to the unclebob/swarm-forge source code, the system relies on swarmforge/constitution.prompt as the entry point, which instructs each agent to consume every article file found under swarmforge/constitution/articles/. These articles encode concrete rules for workflow discipline, handoff mechanics, and engineering standards, enabling precise behavioral customization through simple file operations.

The Layered Constitution Architecture

The constitution system operates as a policy engine where plain-text prompts define agent governance. When an agent starts, orchestration scripts automatically place shared articles from the main branch onto the agent's PATH, then the agent consumes these articles in list order.

Shared Defaults vs. Local Overrides

The system distinguishes between shared articles (defaults from main) and local articles (branch-specific customizations):

• Shared articles (workflow.prompt, handoffs.prompt, engineering.prompt) provide baseline behavior for all swarms
• Local articles (prefixed with local-, e.g., local-workflow.prompt) extend shared rules without replacing them
• Overrides occur when a runnable branch contains a file with the exact same name as a shared article, causing the local version to supersede the default

This layering allows teams to inherit organization-wide standards while specializing behaviors for specific workflows or environments.

How Articles Shape Specific Behaviors

Each article controls a distinct operational domain. The following files represent the core governance layers in swarmforge/constitution/articles/:

Workflow Discipline (workflow.prompt)

The workflow.prompt article enforces work-tree discipline, commit message formats, and temporary-file locations. For example, it mandates: "Include your role byline in every git commit message in this form: By <role>." This ensures every agent leaves an auditable trail of its actions through standardized git history.

Handoff Mechanics (handoffs.prompt)

The handoffs.prompt article governs how agents send and receive work, defining allowed message types and validation steps. It restricts communications to specific protocols: "Only git_handoff and note are permitted message types; always forward a git_handoff to the next role in the pipeline." This prevents malformed inter-agent communications that could break pipeline continuity.

Engineering Standards (engineering.prompt)

The shared engineering.prompt establishes general coding conventions, test-driven development expectations, and code-review standards. When projects require divergent standards (e.g., mandating Python 3.12 or specific linting tools), teams can override this file entirely or supplement it with local-engineering.prompt.

The Bootstrap and Layering Mechanism

The constitution system initializes through a four-phase bootstrap process implemented in the ./swarm wrapper scripts.

1. Bootstrap Phase

When ./swarm starts, the wrapper copies missing shared articles from the main branch into the runnable branch's swarmforge/constitution/articles/ folder. This ensures baseline governance exists before agents initialize.

2. File Resolution

The system checks for filename collisions between shared and local articles. If a runnable branch contains engineering.prompt, the bootstrap skips copying the shared version, causing the agent to consume only the local rules. Files prefixed with local- avoid collisions, allowing additive customization.

3. Agent Consumption

Each agent's role prompt (located at swarmforge/roles/<role>.prompt) begins by invoking the constitution:

;; Example from coder.prompt
(read-file "swarmforge/constitution.prompt")
;; Agent-specific instructions follow...

The swarmforge/constitution.prompt file contains a shell loop that concatenates all articles:

for article in $(ls swarmforge/constitution/articles/*.prompt); do
  cat "$article"
done

This injects the full text of every article into the LLM's context window, effectively programming the agent's behavioral constraints through prompt engineering.

4. Dynamic Customization

Because articles are plain text, modifications require only git commits. Adding local-workflow.prompt to a branch immediately affects the next swarm launch without restarting services or recompiling code.

Practical Customization Examples

The following patterns demonstrate how to leverage the constitution layering system for specific use cases.

Extending Defaults with Local Articles

To add QA-specific handoff behavior for a "six-pack" workflow without replacing the standard workflow rules:

# In a runnable branch (e.g., six-pack)

mkdir -p swarmforge/constitution/articles
cat > swarmforge/constitution/articles/local-workflow.prompt <<'EOF'

# Local Workflow Customisation

## QA-Specific Handoff Rules

- When sending a handoff to the QA role, always set priority to 90.
- Include a `qa_review` tag in the task name.
EOF

Because the filename starts with local-, the default workflow.prompt loads first, followed by these additional constraints.

Overriding Shared Articles Completely

To replace the default engineering standards entirely:

# Replace the default engineering article

cat > swarmforge/constitution/articles/engineering.prompt <<'EOF'

# Project-Specific Engineering Rules

- Use only Python 3.12 for new modules.
- All new functions must be type-annotated.
- Run `black` and `ruff` as part of every commit.
EOF

The presence of a file named exactly engineering.prompt causes the bootstrap to skip the shared version, enforcing these exclusive rules.

Role-Level Constitution Invocation

Individual roles consume the constitution through explicit file reads. The coder role (swarmforge/roles/coder.prompt) loads governance before executing task-specific logic:

# In swarmforge/roles/coder.prompt

(read-file "swarmforge/constitution.prompt")
;; Coder-specific instructions follow...

This ensures the agent parses workflow.prompt, handoffs.prompt, and any local extensions before generating code or handling handoffs.

Summary

• Constitution articles are plain-text prompt files stored in swarmforge/constitution/articles/ that define agent behavior without code changes.
• Layered inheritance allows local-*.prompt files to extend shared defaults, while identical filenames override them completely.
• Bootstrap process copies shared articles from main to runnable branches, respecting local file precedence during initialization.
• Agent ingestion occurs through swarmforge/constitution.prompt, which concatenates all articles into the LLM context via shell loops invoked by role prompts.
• Key files include workflow.prompt (git discipline), handoffs.prompt (inter-agent messaging), and engineering.prompt (coding standards), all consumable by helper scripts like swarm_handoff.sh and ready_for_next.sh.

Frequently Asked Questions

How does SwarmForge handle conflicts between shared and local constitution articles?

SwarmForge resolves conflicts through filename matching during the bootstrap phase. If a runnable branch contains a file with the exact same name as a shared article (e.g., engineering.prompt), the local version overrides the shared default entirely. If the local file uses a local- prefix (e.g., local-workflow.prompt), it loads after the shared article, allowing the rules to extend rather than replace the baseline behavior.

Can constitution articles enforce specific git commit formats across all agents?

Yes, the workflow.prompt article explicitly controls git discipline and commit message formatting. By default, it requires agents to include role bylines in every commit message using the format By <role>. Teams can customize this by modifying workflow.prompt or adding local-workflow.prompt with additional git hooks or message templates, ensuring all agents in a swarm adhere to project-specific version control standards.

What is the execution order when multiple constitution articles are present?

Articles are consumed in the order returned by the shell command ls swarmforge/constitution/articles/*.prompt, which typically follows alphabetical sorting. Shared articles from main are copied first, then local modifications are either merged (if prefixed with local-) or substituted (if filenames match). The concatenated output is then injected into the agent's prompt context through the (read-file "swarmforge/constitution.prompt") invocation in each role's prompt file.

Are constitution changes immediate, or do they require a swarm restart?

Constitution changes take effect on the next swarm launch. Because ./swarm bootstrap scripts copy articles from main during initialization, modifying or adding files in swarmforge/constitution/articles/ and committing them to the branch ensures the next execution of ./swarm loads the updated governance. There is no hot-reload mechanism; agents read the constitution once at startup via the role prompt's read-file directive.

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