How Agent Prompts Are Defined in Swarm Forge: The .prompt File System Explained

Swarm Forge defines agent prompts using plain-text .prompt files stored in swarmforge/roles/, loaded by the core swarmforge.bb script alongside a shared constitution.

Swarm Forge is an open-source multi-agent orchestration framework by Robert C. Martin. Unlike hardcoded prompt strings, the system externalizes agent behavior into editable text files. This design lets operators modify agent personalities, constraints, and capabilities without recompiling code.

The Prompt File Architecture

Swarm Forge uses a two-layer prompt system: a shared constitution that applies to all agents, and role-specific prompts that define individual agent behavior.

Layer 1: The Shared Constitution

The entry point swarmforge/scripts/swarmforge.bb first loads swarmforge/constitution.prompt. This file instructs the system to recursively read every article under swarmforge/constitution/articles/:

• engineering.prompt — engineering discipline rules
• workflow.prompt — worktree and temporary file conventions
• handoffs.prompt — inter-agent communication protocols

These articles establish baseline constraints that every agent must follow. According to the source at line 352 of swarmforge.bb, the constitution is the foundation of all agent contexts.

Layer 2: Role-Specific Prompts

After loading the constitution, the script resolves the requested role and validates that its prompt file exists:

;; From swarmforge/scripts/swarmforge.bb
(reject-if (not (fs/exists? (fs/path (:roles-dir ctx) (str role ".prompt"))))
           (str "Missing role prompt " (fs/path (:roles-dir ctx) (str role ".prompt"))))

If validation passes, the system reads swarmforge/roles/{role}.prompt. For example, the lieutenant role uses swarmforge/roles/lieutenant.prompt.

Prompt File Format and Content

Prompt files are markdown-compatible plain text. They contain:

• A role header (e.g., # Lieutenant)

• Behavioral directives in natural language

• References to helper scripts for agent actions

• Follow-up handling protocols

Here is the actual lieutenant prompt structure:

# Lieutenant

You oversee the forge: `projects/`, the dashboard, and the operator's chat.
…
- Follow‑ups arrive as `[id] text`. Answer with
  `pack_dashboard_request.sh answer <id> ./tmp/answer.txt`.
- Ask with `pack_dashboard_request.sh clarify ./tmp/question.txt`.

The prompt references pack_dashboard_request.sh (located in swarmforge/scripts/) for dashboard interactions. This separation keeps orchestration logic in scripts while behavior lives in prompts.

How Prompts Are Loaded at Runtime

The swarmforge.bb script orchestrates prompt loading in four steps:

1. Read constitution — Load base rules from swarmforge/constitution.prompt
2. Resolve role file — Construct path swarmforge/roles/{role}.prompt
3. Validate existence — Abort with error if the role prompt is missing (line 180)
4. Copy for lieutenant — When spawning a supervisor, copy lieutenant.prompt into the worktree (lines 452–456)

The final context string assembled for the agent reads:

Read swarmforge/constitution.prompt, then read every file it refers to recursively, and obey all of those instructions.
Read swarmforge/roles/{role}.prompt, then read every file it refers to recursively, and follow all of those instructions.

Helper Scripts Referenced in Prompts

Prompt files delegate technical operations to companion shell scripts:

Script	Purpose
pack_dashboard_request.sh	Package agent answers and clarification requests
pack_dashboard_request.sh answer <id> <file>	Submit a follow-up answer
pack_dashboard_request.sh clarify <file>	Request operator clarification

This pattern keeps prompts declarative while implementation details remain testable shell code.

Prompt Customization Workflow

To modify an agent's behavior in Swarm Forge:

1. Locate the role file: swarmforge/roles/{agent}.prompt
2. Edit directives, tool references, or response formats
3. Optionally update shared articles in swarmforge/constitution/articles/ for system-wide changes
4. Restart the swarm — no recompilation required

The .prompt extension and flat file structure enable version control, diff review, and rapid iteration on agent behavior.

Summary

• .prompt files in swarmforge/roles/ define individual agent behavior
• swarmforge/constitution.prompt and its articles provide shared constraints
• swarmforge/scripts/swarmforge.bb orchestrates prompt loading and validation
• Prompts reference helper scripts like pack_dashboard_request.sh for concrete operations
• The architecture separates behavior (text) from mechanism (code), enabling runtime customization

Frequently Asked Questions

What file extension do Swarm Forge prompts use?

Swarm Forge prompts use the .prompt extension. All role files live in swarmforge/roles/ with names like lieutenant.prompt, coder.prompt, or cleaner.prompt. The core script explicitly looks for files matching this pattern when resolving agent roles.

Can I create custom agent roles in Swarm Forge?

Yes. Create a new .prompt file in swarmforge/roles/ with your desired role name. The swarmforge.bb script dynamically resolves roles by filename, so any valid file in this directory becomes available. Ensure your prompt references appropriate helper scripts for agent actions.

What happens if a role prompt file is missing?

The system aborts with an error during role resolution. At line 180 of swarmforge.bb, the script checks fs/exists? for {role}.prompt and rejects the operation with a descriptive path if the file is not found. This prevents silent fallback to default behaviors.

How do agents know which scripts to use for actions?

Prompt files explicitly name helper scripts in their directives. For example, the lieutenant prompt instructs: "pack_dashboard_request.sh answer <id> ./tmp/answer.txt". The agent receives this as natural language context and generates calls to these scripts, which the orchestration layer then executes.

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