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

> Learn how agent prompts are defined in SwarmForge using plain-text .prompt files. Understand the .prompt file system and how it works with the core swarmforge.bb script.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: deep-dive
- Published: 2026-09-02

---

**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:

```clojure
;; 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:

```text

# 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`](https://github.com/unclebob/swarm-forge/blob/main/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:

```text
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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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.