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

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.

;; 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

# 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

# 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.

# 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.

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