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

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:

# 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: 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 that facilitate agent communication.
• 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.

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