How Constitution Articles Layer with Pack-Specific Prompts in Swarm Forge

Constitution articles form a three-layer stack in Swarm Forge: the global constitution file pulls in shared articles as a baseline policy, and pack-specific prompts are appended last to allow specialized overrides.

Swarm Forge manages agent system prompts through a hierarchical layering system where constitution articles establish universal governance rules, and pack-specific prompts provide final customization. Understanding how constitution articles layer with pack-specific prompts is essential for controlling agent behavior across different packs and roles.

The Three-Layer Prompt Architecture

Swarm Forge constructs every agent's complete instruction set through three distinct layers processed in strict order.

Layer 1: Global Constitution Entry Point

The foundation begins with swarmforge/constitution.prompt. This single-line file contains a directive instructing the agent to read every file in swarmforge/constitution/articles/ and obey those instructions recursively.

Because this file uses recursive language, it automatically discovers and incorporates all article files without explicit enumeration in the agent instruction generator.

Layer 2: Constitution Articles

The shared articles live in swarmforge/constitution/articles/ and are defined in swarmforge/scripts/forge.bb:

Article File	Purpose
engineering.prompt	Software engineering standards and practices
workflow.prompt	Process and collaboration workflows
handoffs.prompt	Agent-to-agent communication protocols

These files are declared as shared-articles in the build configuration:

;; swarmforge/scripts/forge.bb
(def shared-articles ["engineering.prompt"
                      "workflow.prompt"
                      "handoffs.prompt"])

When a pack is loaded, these articles are copied into the pack's state directory alongside the constitution file. The recursive loading mechanism in constitution.prompt ensures all three articles become active policy for every agent.

Layer 3: Pack-Specific and Role Prompts

The final layer comes from role-specific prompt files stored in swarmforge/roles/ (e.g., lieutenant.prompt, coder.prompt). The function write-agent-instruction-file! in swarmforge/scripts/swarmforge.bb assembles the complete instruction set:

;; swarmforge/scripts/swarmforge.bb (lines 450-457)
(defn write-agent-instruction-file!
  [ctx role prompt-file last-role?]
  ;; ... file setup ...
  (spit (str prompt-file)
        (str "Read swarmforge/constitution.prompt, then read every file it refers to recursively, and obey all of those instructions.\n"
             "Read swarmforge/roles/" role ".prompt, then read every file it refers to recursively, and follow all of those instructions.\n")))

The explicit ordering in this function determines precedence: constitution articles are loaded first as baseline policy, and the role-specific prompt follows. If a pack provides its own .prompt file, it is concatenated after the role prompt, making it the final behavioral authority.

Final Prompt Order and Precedence

The complete instruction stack resolves to this execution order:

1. constitution.prompt (entry point)
   ├── engineering.prompt (shared article)
   ├── workflow.prompt (shared article)
   └── handoffs.prompt (shared article)
2. <role>.prompt (e.g., lieutenant.prompt, coder.prompt)
3. [optional] pack-specific .prompt file

This structure ensures that pack-specific prompts can extend or override constitution articles without breaking shared governance. The articles act as guardrails; pack-specific content provides specialization.

Key Files in the Layering System

File Path	Function	Relevant Reference
swarmforge/constitution.prompt	Entry point for recursive article loading	Constitution directive
swarmforge/constitution/articles/*.prompt	Global policy articles (engineering, workflow, handoffs)	Shared articles
swarmforge/scripts/forge.bb	Declares shared-articles list and copies constitution to pack state	Line 9
swarmforge/scripts/swarmforge.bb	Generates final instruction file with explicit layer ordering	Lines 450-457 (write-agent-instruction-file!)
swarmforge/roles/*.prompt	Role-specific behavioral templates	Role prompt directory

How Pack Overrides Work in Practice

When you need a pack to behave differently from the global constitution, place custom directives in the pack's .prompt file or modify the role prompt. Because these load last, they take precedence in the agent's instruction context according to the write-agent-instruction-file! implementation.

For example, if engineering.prompt specifies "use test-driven development," but a particular pack's prompt states "prototyping mode—tests optional," the agent receives both instructions but the pack-specific directive appears last and carries final weight in typical LLM system prompt interpretation.

Summary

• Constitution articles in swarmforge/constitution/articles/ provide universal baseline policy through recursive loading.
• write-agent-instruction-file! explicitly orders layers: constitution first, role prompt second, pack-specific content last.
• Pack-specific prompts are appended at the end of the instruction file, enabling behavioral specialization without forking shared governance rules.
• The shared-articles list in forge.bb controls which article files are distributed to every pack's state directory.

Frequently Asked Questions

What happens if a constitution article conflicts with a pack-specific prompt?

Pack-specific prompts take precedence because they appear last in the instruction file generated by write-agent-instruction-file!. The LLM typically weighs later instructions more heavily. For strict enforcement of constitution rules, ensure articles use imperative language that pack prompts cannot easily override.

Where do I add a new global policy that all packs must follow?

Create a new .prompt file in swarmforge/constitution/articles/, then add its filename to the shared-articles vector in swarmforge/scripts/forge.bb. The recursive loading mechanism in constitution.prompt will automatically include it for all agents.

Can a pack opt out of specific constitution articles?

No direct opt-out mechanism exists. All shared-articles are copied to every pack's state and loaded via the constitution entry point. To create pack-specific exceptions, override the unwanted behavior in the pack's or role's prompt file rather than excluding the article.

How does write-agent-instruction-file! handle multiple roles in a pack?

The function generates separate instruction files per role. Each file contains the same constitution-article preamble, followed by that specific role's prompt from swarmforge/roles/<role>.prompt. This ensures consistent baseline governance across all roles in a pack while allowing role-specific specialization.

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