# Understanding project.prompt and local-*.prompt Files in Swarm-Forge's Constitution

> Learn how project.prompt and local-*.prompt files define Swarm-Forge AI agent behavior. Understand mission constraints and environment specifics within the constitution hierarchy.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: internals
- Published: 2026-08-10

---

**The `project.prompt` file defines the high-level mission and constraints of a Swarm-Forge repository, while `local-*.prompt` files capture environment-specific details like worktrees and branches; together they form the top of the constitution hierarchy that guides every AI agent's behavior.**

Swarm-Forge is a framework for coordinating multiple autonomous agents that collaboratively edit a codebase. At its core lies the **constitution** — a directory of `.prompt` files that inject behavioral rules directly into the language-model prompts powering each agent. Understanding how `project.prompt` and `local-*.prompt` files function within this system is essential for anyone configuring or extending Swarm-Forge deployments.

## What the Constitution Directory Contains

The Swarm-Forge runtime reads every text file ending with **`.prompt`** from the constitution directory at startup. The framework concatenates these files into a single prompt that establishes the operational context for the current agent.

According to the unclebob/swarm-forge source code, prompt files follow a strict hierarchy:

1. **`project.prompt`** — repository-wide mission and policies
2. **`local-*.prompt`** — dynamic, environment-specific context
3. **Role-specific articles** (`workflow.prompt`, `engineering.prompt`, `handoffs.prompt`, …) — specialized behavioral rules

This layered approach ensures agents operate **consistently** with project goals while respecting **local git discipline** and workspace constraints.

## The Role of project.prompt in Establishing Mission Context

The **`project.prompt`** file sits at the top of the constitution hierarchy. It defines the **high-level intent, scope, and constraints** that apply across all agents and workflows.

### What project.prompt Contains

A well-structured `project.prompt` typically includes:

- **Project purpose** — concise statement of what the repository aims to achieve
- **Global policies** — license requirements, security guardrails, performance targets
- **Target audience** — who will consume or maintain the output
- **Constitutional references** — pointers to role-specific rule files

### How project.prompt Is Used

When an agent launches, Swarm-Forge reads `swarmforge/constitution/project.prompt` and **prepends** its content to the full prompt assembly. This gives every downstream decision a consistent "big picture" anchor.

```clojure
;; Pseudocode from swarmforge/scripts/ launcher logic
(let [project-prompt   (slurp "swarmforge/constitution/project.prompt")
      local-prompt     (slurp "swarmforge/constitution/local-.prompt")
      role-prompt      (slurp "swarmforge/constitution/articles/workflow.prompt")
      full-prompt      (str project-prompt "\n\n"
                            local-prompt   "\n\n"
                            role-prompt)]
  (run-llm-with-prompt full-prompt))

```

### Example project.prompt Content

```text

# Project Overview

Swarm-Forge is a framework for coordinating multiple autonomous agents that collaboratively edit a codebase.  
All agents must respect the Constitution (see `workflow.prompt`, `engineering.prompt`, etc.) and never commit changes outside their assigned worktree.

```

Without a clear `project.prompt`, agents lack the **mission context** needed to evaluate tradeoffs or detect misaligned outputs.

## The Role of local-*.prompt in Capturing Execution Context

The **`local-*.prompt`** files (typically named `local-.prompt` or `local-{role}.prompt`) provide **environment-specific details** unique to the current checkout. Unlike the static `project.prompt`, these files are **generated dynamically** at runtime.

### What local-*.prompt Contains

A generated `local-.prompt` records:

- **Assigned worktree** — path to the agent's dedicated git worktree
- **Current branch** — which branch the agent should modify
- **Role assignment** — which constitutional role this agent fulfills
- **Temporary file conventions** — where transient data may be written

### How local-*.prompt Is Used

The framework appends `local-.prompt` **after** `project.prompt` but **before** role-specific articles. This positioning allows local constraints to **override** generic assumptions without corrupting the mission-level context.

### Example local-.prompt Output

```text

# Local Execution Context

## Assigned Worktree

- Role: coder
- Worktree: ./worktrees/coder
- Current branch: feature/awesome-thing

## Temporary Files

- Use `./tmp/` inside the assigned worktree for any transient data.

```

The *Worktree Discipline* and *Temporary Files* sections referenced here are defined in `swarmforge/constitution/articles/workflow.prompt`, but `local-.prompt` **instantiates** them for the current session.

## The Constitution Hierarchy in Practice

The relationship between these prompt files creates a **cascading Override model**:

| Position | File | Purpose | Mutability |
|----------|------|---------|------------|
| 1 | `project.prompt` | Mission and global policies | Static, version-controlled |
| 2 | `local-*.prompt` | Workspace and branch context | Generated at runtime |
| 3 | `articles/*.prompt` | Role-specific behaviors | Static, version-controlled |

This structure appears throughout the unclebob/swarm-forge implementation. For example, `swarmforge/constitution/articles/workflow.prompt` defines worktree discipline in the abstract; `local-.prompt` makes it concrete for the current session.

### Key Article Files in the Constitution

- **`swarmforge/constitution/articles/workflow.prompt`** — worktree discipline, commit bylines, temporary-file conventions
- **`swarmforge/constitution/articles/engineering.prompt`** — language-tool defaults, testing rules, verification guardrails
- **`swarmforge/constitution/articles/handoffs.prompt`** — protocol for transferring state between agents

## Configuring Prompt Files for Your Deployment

### Creating an Effective project.prompt

Write `project.prompt` for **clarity and constraint**. Avoid operational details that change per environment — those belong in `local-*.prompt`.

```text

# Project: DataPipeline Automation

## Mission

Transform raw telemetry into analytics-ready schemas with zero-downtime migrations.

## Global Constraints

- All database changes must be reversible (rollback scripts required)
- Python 3.11+ with type hints on all public interfaces
- Apache 2.0 license; no GPL dependencies

```

### Ensuring local-*.prompt Generation

The Swarm-Forge runtime typically generates `local-.prompt` via launcher scripts in `swarmforge/scripts/`. Verify your deployment populates:

- **Worktree path** — absolute or repo-relative path
- **Branch name** — validated against protected branch rules
- **Temporary directory** — must exist and be writable

Missing or stale `local-.prompt` content causes agents to operate on **wrong branches** or write files to **incorrect locations**.

## Summary

- **`project.prompt`** provides the **static, mission-level context** that all agents share — define repository purpose, global policies, and constitutional structure here.
- **`local-*.prompt`** supplies **dynamic, environment-specific constraints** — worktrees, branches, and temporary directories that vary per execution.
- Together they form the **top two layers** of the Swarm-Forge constitution hierarchy, ensuring agents work consistently with project goals while respecting local git discipline.
- The framework concatenates prompts in order: `project.prompt` → `local-*.prompt` → role-specific articles, then feeds the result to the language model.

## Frequently Asked Questions

### What happens if project.prompt is missing?

The Swarm-Forge runtime will still launch agents, but they will lack mission-level context. Decisions may drift from repository goals, and agents cannot resolve conflicts between role-specific rules because no "big picture" anchor exists. Always include a `project.prompt` in production deployments.

### Can I use multiple local-*.prompt files?

Yes. The framework supports role-specific variants like `local-coder.prompt` or `local-reviewer.prompt`. These override the generic `local-.prompt` when an agent assumes a specialized role. The launcher script in `swarmforge/scripts/` selects the appropriate file based on the `--role` parameter.

### Should local-*.prompt be committed to version control?

No. `local-*.prompt` contains **transient, machine-specific paths** that will break on other checkouts. Add it to `.gitignore`. Let the runtime generate it fresh, or provide a `local-.prompt.template` file if your deployment requires custom generation logic.

### How do project.prompt and local-*.prompt interact with role-specific articles?

Role-specific articles in `swarmforge/constitution/articles/` refine behavior for particular tasks. `project.prompt` and `local-*.prompt` **constrain** these refinements — for example, `engineering.prompt` may recommend inline tests, but `local-.prompt` can redirect temporary test artifacts to the assigned worktree's `./tmp/` directory.