How to Migrate Existing Projects to a Newer Version of SwarmForge

To migrate an existing SwarmForge project, fetch the latest runnable branch, run the ./swarm wrapper to auto-update shared scripts and constitution articles from the main branch, then commit the changes.

SwarmForge stores all version-specific data inside the project directory, making migration straightforward without external dependencies. The unclebob/swarm-forge repository separates the stable core system in the main branch from runnable workflow branches like two-pack, four-pack, and six-pack. When you migrate an existing project to a newer version of SwarmForge, you update both the workflow configuration and the shared helper infrastructure that powers the multi-agent swarm.

Understanding SwarmForge's Version Architecture

SwarmForge uses a dual-branch architecture that separates workflow-specific logic from shared infrastructure.

The main branch contains the universal helper scripts, constitution articles, and bug fixes that apply to all projects. The runnable branches (e.g., four-pack, six-pack) contain the swarmforge/swarmforge.conf configuration and role-specific prompt files that define a particular swarm topology.

When the ./swarm wrapper executes, it acts as the synchronization engine. It checks the local .swarmforge/ directory and compares it against the current main branch. If swarmforge/scripts/ or swarmforge/constitution/articles/ files are missing, the wrapper automatically downloads the latest main branch archive and copies only the missing components, preserving your existing customizations.

Step-by-Step SwarmForge Migration Process

Follow these steps to bring an existing project up-to-date while preserving your local configurations.

Fetch the Latest Runnable Branch

First, update your workflow-specific files by pulling the latest version of your current branch. This gives you the updated swarmforge/swarmforge.conf and any new role-prompt files.

# Example: keep using the "four-pack" workflow

BRANCH=four-pack
curl -L "https://github.com/unclebob/swarm-forge/archive/refs/heads/${BRANCH}.tar.gz" \
    | tar -xz --strip-components=1

This command downloads the branch archive and extracts it directly into your project root, overwriting the runnable workflow configuration while leaving your project-specific files intact.

Run the Wrapper to Sync Shared Files

Execute the ./swarm wrapper to trigger the automatic update mechanism. On first run after pulling new files, the wrapper examines the swarmforge/scripts/ and swarmforge/constitution/articles/ directories.

./swarm

If the wrapper detects missing shared helper scripts (swarmforge/scripts/swarmforge.sh) or constitution articles (swarmforge/constitution/articles/), it downloads the current main branch archive, copies the missing files into place, and then launches the swarm. This ensures your project always uses the latest backend defaults and hand-off protocols without manual file management.

Force Refresh When Needed (Optional)

To guarantee that every shared script and article is the newest version—even if a local copy already exists—delete the local copies before running the wrapper.

rm -rf swarmforge/scripts
rm -rf swarmforge/constitution/articles
./swarm

This forces the wrapper to repopulate both directories with fresh copies from the main branch. Use this approach when changelog documentation indicates critical updates to the constitution or helper libraries that might not trigger the standard "missing file" detection.

Commit and Verify the Upgrade

After the wrapper completes, commit the updated files to ensure future collaborators receive the upgraded version.

git add swarmforge/scripts swarmforge/constitution/articles
git commit -m "Upgrade SwarmForge to latest release"

Start the swarm and monitor the tmux windows to verify all agents launch correctly with the new backend defaults. If a specific role fails to initialize, inspect its swarmforge/roles/<role>.prompt file for outdated references that may conflict with the updated hand-off protocol.

Key Files Involved in Migration

Understanding these critical files helps diagnose migration issues and ensures smooth version transitions.

• swarmforge/swarmforge.conf – Defines the swarm topology and is pulled directly from your chosen runnable branch.
• swarmforge/roles/<role>.prompt – Contains role-specific instructions that may require manual updates when prompt schemas change between versions.
• swarmforge/constitution/articles/*.prompt – Shared constitution files maintained in the main branch; the wrapper copies or updates these automatically.
• swarmforge/scripts/swarmforge.sh – The core wrapper script executed by ./swarm that handles worktree creation, file synchronization, and tmux session management.
• .worktrees/<role> – Runtime directories that are re-initialized automatically if the underlying repository changes, ensuring each agent sees the newest scripts on its $PATH.

Summary

• SwarmForge separates workflow configuration (runnable branches) from shared infrastructure (main branch), allowing granular updates.
• The ./swarm wrapper automatically downloads missing helper scripts and constitution articles from the main branch on first execution.
• Delete swarmforge/scripts and swarmforge/constitution/articles before running ./swarm to force a complete refresh of shared components.
• Always commit migrated files after verification to distribute updates to collaborators.
• Role-specific prompts in swarmforge/roles/ may require manual adjustment if hand-off protocols change between versions.

Frequently Asked Questions

What happens if I don't delete the old scripts before running ./swarm?

The wrapper only copies files that are missing from your local swarmforge/scripts and swarmforge/constitution/articles directories. If a script already exists locally—even if it's outdated—the wrapper will skip it to preserve your customizations. This means you might continue running older helper code unless you manually remove the directories to trigger a full refresh.

Can I stay on an older workflow branch while upgrading shared components?

Yes. You can remain on any runnable branch (such as two-pack or four-pack) indefinitely while still receiving updates to the shared scripts and constitution articles from the main branch. The wrapper synchronizes with main independently of your workflow branch choice, allowing you to maintain stable swarm topologies while benefiting from bug fixes and protocol improvements.

How do I know if a role prompt needs manual updating?

Inspect the tmux output when starting the swarm after migration. If a specific agent fails to initialize or produces errors about unrecognized instructions, check the corresponding swarmforge/roles/<role>.prompt file. Compare it against the new version's template in the runnable branch archive. Updated role prompts typically reflect changes to the hand-off protocol or backend tool availability that the automatic sync cannot patch dynamically.

Will I lose my project-specific customizations during migration?

No. The migration process preserves all files that exist locally. Since the wrapper only adds missing files rather than overwriting existing ones, your custom constitution overrides, modified role prompts, and project-specific scripts remain untouched. To ensure you receive updated shared files while keeping customizations, delete only the swarmforge/scripts and swarmforge/constitution/articles directories, not your root configuration or role-specific files.

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