# How to Migrate Existing Projects to a Newer Version of SwarmForge

> Easily migrate existing projects to a newer SwarmForge version. Fetch the latest branch, use the swarm wrapper to auto-update scripts and articles, and commit your changes.

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

---

**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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) and any new role-prompt files.

```bash

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

```bash
./swarm

```

If the wrapper detects missing shared helper scripts ([`swarmforge/scripts/swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/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.

```bash
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.

```bash
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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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.