# How Local Prompt Naming Conventions Specialize Constitution Articles in Swarm-Forge

> Learn how Swarm-Forge uses local prompt naming conventions to specialize constitution articles by merging pack-specific rules without altering upstream files.

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

---

**Local prompt naming conventions in Swarm-Forge allow development packs to extend shared constitution articles by creating files prefixed with `local-`, which are automatically merged with base defaults during project initialization to add pack-specific rules without modifying upstream files.**

Swarm-Forge is a tmux-based orchestration platform that transforms AI agents into a disciplined software engineering team. The repository `unclebob/swarm-forge` maintains a shared constitution of default articles that define base behavior across all packs in the swarm. Understanding how local prompt naming conventions specialize constitution articles enables teams to safely customize agent workflows while preserving upstream compatibility and upgrade paths.

## The `local-*.prompt` Naming Convention Explained

### Shared Defaults in the Main Branch

Shared constitution articles reside in `swarmforge/constitution/articles/` on the main branch. These files—including `workflow.prompt`, `engineering.prompt`, and `handoffs.prompt`—establish the baseline behavioral contracts that every pack inherits by default. According to the source code, agents read these articles through the entry point `swarmforge/constitution.prompt`, which instructs them to obey every file in the constitution directory.

### The Local Specialization Pattern

When a pack requires modifications to a shared article, it creates a file following the `local-<article>.prompt` convention. For example:

- `local-workflow.prompt` specializes the shared `workflow.prompt`
- `local-engineering.prompt` specializes the shared `engineering.prompt`
- `local-handoffs.prompt` specializes the shared `handoffs.prompt`

This naming convention signals to the bootstrap scripts that these files should merge with rather than replace their shared counterparts. The pack adds the local file to its own repository, leaving the original shared article unchanged in the upstream `unclebob/swarm-forge` repository.

## Runtime Merge Process During Project Creation

During project initialization via the `get-swarm-forge` script, the system copies the shared article tree from `swarmforge/constitution/articles/` into the new project. Subsequently, it layers any detected `local-*.prompt` files on top of the base articles. 

Agents then read the entry point `swarmforge/constitution.prompt`, which instructs them to obey every file in the articles directory. Because the directory contains both shared defaults and local specializations, the final constitution represents a merged set of instructions where local rules augment base behavior.

## Advantages Over Direct File Overrides

**Safety**: The original shared articles remain untouched in the main branch, ensuring that upstream updates never overwrite pack-specific customizations during platform upgrades.

**Clarity**: The `local-` prefix explicitly documents which pack extends which article, simplifying code review and maintenance for engineering teams.

**Versioning**: Git history records only the delta—the additional local file—keeping diffs focused and preventing merge conflicts when pulling updates from the upstream repository.

## Implementing Pack-Specific Specializations

Consider a scenario where a pack must enforce that every task handoff includes a `priority` field. The shared `workflow.prompt` does not mandate this field, so the pack creates a specialization:

```text

# File: swarmforge/constitution/articles/local-workflow.prompt

# Extend the base workflow to require a priority line in every task handoff.

type: note
required-fields: priority

```

When `get-swarm-forge` instantiates the project, agents receive both the original workflow rules and the additional `required-fields` constraint. The agents will subsequently reject any handoff lacking a priority line, prompting immediate correction by the human operator.

## Critical Files in the Constitution Architecture

Understanding the complete file structure clarifies how local prompts integrate into the broader system:

- **`swarmforge/constitution.prompt`**: The entry point that directs agents to load all articles from the constitution directory.
- **`swarmforge/constitution/articles/workflow.prompt`**: Shared default defining base workflow requirements.
- **`swarmforge/constitution/articles/local-workflow.prompt`**: Pack-specific extension that specializes the base workflow (added by individual packs).
- **[`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf)**: Declares swarm topology, roles, and worktree configurations.
- **`swarmforge/roles/<role>.prompt`**: Role-specific behavioral definitions for individual agent types.
- **`swarmforge/scripts/`**: Contains helper scripts like [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) that facilitate agent communication.
- **[`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md)**: Formal specification of handoff file formats and lifecycles.

## Summary

- Local prompt naming conventions use the `local-<article>.prompt` pattern to extend shared constitution articles without modifying original files.
- Specializations reside in `swarmforge/constitution/articles/` alongside base articles provided by `unclebob/swarm-forge`.
- The `get-swarm-forge` bootstrap script automatically merges local prompts with shared defaults during project creation.
- This approach ensures safe upgrades, clear ownership of customizations, and focused version control diffs.
- Agents consume the merged constitution through `swarmforge/constitution.prompt`, applying both base rules and pack-specific extensions.

## Frequently Asked Questions

### What happens if a local prompt conflicts with a shared constitution article?

When both files define the same directive, the local prompt's specifications typically take precedence because the bootstrap process copies local files after the shared defaults, effectively overlaying pack-specific rules. The merged constitution visible to agents contains the union of both files, with local definitions superseding base values where explicitly contradictory.

### Can a pack create local specializations for any constitution article?

Yes, any file in `swarmforge/constitution/articles/` can be specialized by creating a corresponding `local-*.prompt` file with the matching suffix. The convention applies uniformly to `workflow.prompt`, `engineering.prompt`, `handoffs.prompt`, and any additional articles added to the shared constitution.

### How do agents know to read both the shared and local prompt files?

The `swarmforge/constitution.prompt` file serves as the entry point that instructs agents to process every file within `swarmforge/constitution/articles/`. Since the bootstrap scripts ensure both shared defaults and local specializations populate this directory before agent activation, the agents automatically apply the complete merged rule set without requiring explicit configuration changes.

### Do local prompts affect version control for the main Swarm-Forge repository?

No, local prompts remain within individual pack repositories and never modify the upstream `unclebob/swarm-forge` main branch. This separation ensures that packs can track their customizations independently while continuing to pull updates from the platform repository, maintaining a clean separation between shared infrastructure and pack-specific requirements.