How Constitution Layering Works with Prompt Files in Swarm Forge

Constitution layering in Swarm Forge works by stacking three tiers of prompt files—shared articles, project-specific overrides, and role-specific instructions—into a single hierarchical context that agents follow at runtime.

Swarm Forge implements a layered constitution system that assembles an agent's operating rules from multiple prompt files. This design, as implemented in unclebob/swarm-forge, separates universal policies from project customizations and individual role definitions, giving teams fine-grained control over agent behavior without duplication.

The Entry Point: swarmforge/constitution.prompt

Every agent starts from a single orchestration file. In swarmforge/constitution.prompt, the system defines the loading sequence:

# swarmforge/constitution.prompt

Read every file in swarmforge/constitution/articles/ and obey those
instructions. Then read swarmforge/roles for your role.

This two-step directive establishes the loading order: shared articles first, then role-specific instructions. The agent concatenates these prompts in sequence, with later content taking precedence where conflicts arise.

Layer 1: Base Constitution Articles

The foundation consists of standalone .prompt files in swarmforge/constitution/articles/. Each file encapsulates a functional domain.

Core articles in the repository include:

• engineering.prompt — coding standards and technical practices
• workflow.prompt — overall process expectations and state management
• handoffs.prompt — rules governing agent-to-agent transfers

The entry point iterates through all files in this directory alphabetically by filename, loading each into context. This creates the shared constitutional baseline applied to every agent regardless of role.

Creating a new constitutional rule:

# Create a security-focused article

cat > swarmforge/constitution/articles/security.prompt <<'EOF'
You must never disclose secrets, API keys, or passwords.
All communication should be logged for auditability.
EOF

# Stage and commit—the startup script auto-includes new articles

git add swarmforge/constitution/articles/security.prompt
git commit -m "Add security article to constitution"

Layer 2: Project-Specific Overrides

Packs (configuration bundles like two-pack or four-pack) can ship local-*.prompt files that supplement or override the base articles. These files are not name-matched against shared articles; they simply append additional rules.

The startup script copies the composed swarmforge/constitution/ tree into each role's working context, ensuring every agent sees identical base content plus any pack-provided extensions. This allows per-project customization without modifying the core repository.

Layer 3: Role-Specific Prompts

After constitution articles load, the agent reads its designated role prompt at swarmforge/roles/<role>.prompt. This final layer defines specialized responsibilities and can reference the constitution recursively.

Example from swarmforge/roles/lieutenant.prompt:

You are a Lieutenant. Follow the shared constitution first:
{{ read constitution.prompt }}

Additional duties:
- Coordinate engineering and workflow teams.
- When a handoff is required, follow the rules in handoffs.prompt.

The {{ read constitution.prompt }} syntax ensures agents re-load the latest constitutional rules dynamically—particularly useful after handoffs or context switches, as documented in swarmforge/handoff-protocol.md.

Deterministic Layer Ordering and Precedence

The concatenation sequence guarantees predictable behavior:

Order	Layer	Source Pattern	Override Capability
1	Shared articles	swarmforge/constitution/articles/*.prompt	Base definitions
2	Local extensions	local-*.prompt (pack-supplied)	Extend or specialize
3	Role prompt	swarmforge/roles/<role>.prompt	Final authority

Later layers override earlier definitions when conflicts occur. This hierarchy lets roles refine or specialize broad policies without rewriting shared files.

Runtime Assembly Example

The startup sequence (simplified):

# Load constitution layer: all articles concatenated

cat swarmforge/constitution/articles/*.prompt > /tmp/constitution.txt

# Append pack-specific local overrides if present

cat swarmforge/constitution/local-*.prompt >> /tmp/constitution.txt 2>/dev/null

# Append role-specific final layer

cat swarmforge/roles/lieutenant.prompt >> /tmp/constitution.txt

# Agent receives complete hierarchical prompt

Key Files and References

Path	Purpose
swarmforge/constitution.prompt	Orchestration entry point defining load order
swarmforge/constitution/articles/*.prompt	Shared functional domains (engineering, workflow, handoffs)
swarmforge/roles/<role>.prompt	Role-specific specializations and recursive constitution references
swarmforge/handoff-protocol.md	Documents re-reading patterns for dynamic constitution updates
README.md (Layered Constitution section)	Architectural overview of the three-tier system

Summary

• Constitution layering assembles agent context from three tiers: shared articles, project overrides, and role prompts
• swarmforge/constitution.prompt controls loading order with a simple two-step directive
• Files in swarmforge/constitution/articles/ establish universal policies loaded alphabetically
• Pack-provided local-*.prompt files enable project-specific customization
• swarmforge/roles/<role>.prompt delivers final role specialization with recursive constitution re-reading
• Later layers override earlier ones, creating clean hierarchical precedence

Frequently Asked Questions

How do I add a new rule that applies to all agents?

Create a .prompt file in swarmforge/constitution/articles/. The startup script automatically includes all files in this directory; alphabetical order determines loading sequence. Commit the file to propagate the rule across all roles.

Can one agent use different constitution articles than another?

All agents share identical base articles from swarmforge/constitution/articles/. Differentiation occurs at the role layer (swarmforge/roles/<role>.prompt) or through pack-specific local-*.prompt extensions. Roles cannot selectively exclude base articles—they receive the full set.

What happens when two articles define conflicting instructions?

Later layers override earlier ones. Within the article layer, alphabetical filename order determines precedence. For definitive control, place overriding rules in the role prompt (swarmforge/roles/<role>.prompt), which loads last and holds final authority.

Why do role prompts re-read the constitution with {{ read constitution.prompt }}?

This pattern ensures agents operate with current rules after context switches or handoffs. Since the constitution may evolve or agents may enter mid-workflow, the explicit re-read guarantees synchronization. The handoff-protocol.md file documents when this re-reading is required.

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