Squad Squad

Migration Guide

Upgrading from an older version of Squad? Find your scenario below.

Table of Contents

Quick Reference

BeforeAfter
npx github:bradygaster/squadnpx @bradygaster/squad-cli
@bradygaster/create-squad@bradygaster/squad-cli
.ai-team/ directory.squad/ directory
v0.5.4 (beta)v0.8.18

Scenario 1: Brand New User

Never used Squad before? Start here.

Prerequisites

  • Node.js 18 or later
  • npm 9 or later
  • A GitHub account with GitHub Copilot enabled
  • gh CLI authenticated (gh auth status should show you logged in)

Install

npm install -g @bradygaster/squad-cli

Or run without installing:

npx @bradygaster/squad-cli

Initialize a Project

cd your-project
squad init

This creates a .squad/ directory with your team roster, agent charters, and configuration files.

Verify

squad doctor

All checks should pass. You’re ready to go.

Scenario 2: Upgrading from v0.5.4 Beta

This is the biggest jump. The codebase was rewritten in TypeScript, the .squad/ directory format changed, and the command structure was reorganized.

What Changed

  • TypeScript rewrite: Entire codebase ported from JavaScript to TypeScript (strict mode).
  • .squad/ directory format: v0.5.4 format is incompatible with v0.8.18. You must reinitialize.
  • Command structure: Some commands were reorganized or renamed.
  • SDK API: The public API changed significantly if you were using Squad programmatically.
  • Distribution: npm-only. The npx github: install path is gone.

Step-by-Step

  1. Back up your existing .squad/ directory:

    cp -r .squad .squad-v054-backup

  2. Uninstall the old version (if globally installed):

    npm uninstall -g @bradygaster/create-squad

  3. Install v0.8.18:

    npm install -g @bradygaster/squad-cli@0.8.18

  4. Remove the old .squad/ directory:

    rm -rf .squad

  5. Reinitialize:

    squad init

  6. Manually migrate your customizations. Open .squad-v054-backup/ and copy over any custom agent charters, team roster entries, or decisions into the new .squad/ directory structure. The new format uses Markdown files (not JSON).

    Which files are safe to copy? Use this table as your guide:

    Directory/FileSafe to copy?Notes
    agents/✅ Yes — all of themIncluding scribe and ralph — their history is valuable context
    decisions.md✅ YesYour team’s decision ledger
    decisions/✅ YesIncluding inbox/
    routing.md✅ YesYour routing rules
    team.md✅ YesYour roster
    skills/✅ YesLearned patterns
    casting/❌ SkipRegenerated automatically on first run
    templates/❌ SkipOverwritten by squad upgrade
    log/🟡 OptionalDiagnostic archive — no harm copying, but not required
    orchestration-log/🟡 OptionalSame as log/

  7. Validate with squad doctor:

    squad doctor

    This runs 9 checks to ensure your .squad/ directory is healthy after migration. All checks should pass before you consider the upgrade complete.

Key Format Changes

v0.5.4v0.8.18
.squad/config.json.squad/team.md (Markdown with YAML front matter)
JSON decision log.squad/decisions.md (append-only Markdown)
Flat agent files.squad/agents/{name}/charter.md (directory per agent)

Scenario 3: Already on v0.8.x via npm

If you’re already on any v0.8.x release, this is a simple update.

npm install -g @bradygaster/squad-cli@latest

Verify the version:

squad --version

Expected output: 0.8.18 (or 0.8.18-preview.N).

Your .squad/ directory is compatible — no reinitialization needed.

Scenario 4: Was Using @bradygaster/create-squad

The @bradygaster/create-squad package is deprecated. It has been replaced by @bradygaster/squad-cli.

Switch

# Remove the old package
npm uninstall -g @bradygaster/create-squad

# Install the new package
npm install -g @bradygaster/squad-cli

The squad command works the same way. Your .squad/ directory does not need to change if you were already on v0.8.x.

Scenario 5: Was Using npx github: Distribution

The GitHub-native distribution (npx github:bradygaster/squad) has been removed. Squad is now distributed exclusively through npm.

Switch

Replace any usage of:

# OLD — no longer works
npx github:bradygaster/squad

With:

# NEW
npx @bradygaster/squad-cli

If you had this in scripts or CI/CD workflows, update every reference.

Scenario 6: My .squad/ Directory Broke After Upgrading

If squad doctor fails or commands error out after upgrading, follow these steps.

1. Back Up

cp -r .squad .squad-broken-backup

2. Reinitialize

rm -rf .squad
squad init

3. Restore Customizations

Manually copy custom agent charters, roster entries, and decisions from .squad-broken-backup/ into the new .squad/ structure.

4. Verify

squad doctor

If squad doctor still fails, see Troubleshooting below.

Scenario 7: I Have .ai-team/ from an Older Version

Very early versions of Squad used .ai-team/ instead of .squad/. This directory name is no longer recognized.

Migrate

  1. Back up:

    mv .ai-team .ai-team-backup

  2. Initialize the new directory:

    squad init

  3. Manually migrate any custom configuration from .ai-team-backup/ into .squad/.

  4. Update .gitignore if it references .ai-team/:

    # Remove .ai-team references, add .squad if needed

  5. Verify:

    squad doctor

Scenario 8: Using Squad in CI/CD

If you run Squad in GitHub Actions or another CI/CD system, update your workflow files.

Before (old distribution)

- name: Run Squad
  run: npx github:bradygaster/squad

After (v0.8.18)

- uses: actions/setup-node@v4
  with:
    node-version: '18'

- name: Install Squad
  run: npm install -g @bradygaster/squad-cli@0.8.18

- name: Run Squad
  run: squad doctor && squad status
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Key CI/CD Notes

  • Set GITHUB_TOKEN as an environment variable. Squad requires it for GitHub Copilot operations.
  • Pin to a specific version (@0.8.18) in CI to avoid surprise upgrades.
  • If you use npx, use npx @bradygaster/squad-cli@0.8.18 with a pinned version.
  • Node.js 18+ is required. Update your workflow’s setup-node action if needed.

Scenario 9: Using Squad SDK Programmatically

If you import Squad as a library, the package name and API have changed.

Package Change

# OLD
npm install @bradygaster/squad

# NEW
npm install @bradygaster/squad-sdk

Import Change

// OLD
import { Squad } from '@bradygaster/squad';

// NEW
import { Squad } from '@bradygaster/squad-sdk';

API Notes

  • The SDK is now fully typed (TypeScript strict mode).
  • Some methods were renamed or reorganized. Check the SDK documentation for the current API surface.
  • If you were relying on internal/undocumented APIs, those have changed. Stick to the documented public API.

Troubleshooting

command not found: squad

Squad isn’t on your PATH. Either install globally or use npx:

npm install -g @bradygaster/squad-cli
# or
npx @bradygaster/squad-cli doctor

npm 404 error when installing

You may be using the old package name. Use the correct name:

npm install -g @bradygaster/squad-cli

If the package genuinely isn’t published yet, check the npm page or the GitHub repo for release status.

Permission denied during install

Use one of these approaches (do not use sudo npm):

# Option 1: Fix npm prefix (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# Option 2: Use npx instead
npx @bradygaster/squad-cli

Old format not recognized

Your .squad/ directory is from an older version. Back it up and reinitialize:

cp -r .squad .squad-old-backup
rm -rf .squad
squad init

GITHUB_TOKEN issues

Squad needs a valid GitHub token for Copilot operations. Verify:

echo $GITHUB_TOKEN

If empty, authenticate via the GitHub CLI:

gh auth login
export GITHUB_TOKEN=$(gh auth token)

gh auth issues

Make sure the GitHub CLI is installed and authenticated:

gh auth status

If not authenticated:

gh auth login

npx cache serving a stale version

Clear the npx cache and retry:

npx clear-npx-cache
npx @bradygaster/squad-cli@0.8.18

Or install globally to bypass npx caching entirely:

npm install -g @bradygaster/squad-cli@0.8.18

Wrong version installed

Check your installed version:

squad --version

If it shows an old version:

npm uninstall -g @bradygaster/squad-cli
npm install -g @bradygaster/squad-cli@0.8.18

Team roster gone after upgrade

Your .squad/team.md may not have survived the upgrade. Reinitialize and restore from backup:

squad init
# Then manually restore roster entries from your backup

squad doctor fails

Run it to see which checks fail:

squad doctor

Common causes:

  • Missing .squad/ directory — run squad init.
  • Missing GITHUB_TOKEN — see GITHUB_TOKEN issues above.
  • Node.js too old — upgrade to Node.js 18+.
  • Corrupted .squad/ files — back up, remove, and reinitialize.

Node.js version too old

Squad requires Node.js 18 or later. Check your version:

node --version

If below 18, upgrade via nodejs.org or your preferred version manager:

# nvm
nvm install 18
nvm use 18

# fnm
fnm install 18
fnm use 18

Rolling Back

If you need to downgrade from v0.8.18:

npm install -g @bradygaster/squad-cli@0.8.17

Warnings

  • The GitHub-native distribution (npx github:bradygaster/squad) is permanently removed. You cannot roll back to that install method.
  • .squad/ directory format changed between v0.5.4 and v0.8.x. If you roll back to v0.5.4, your current .squad/ directory will not be compatible. Keep backups.
  • Rolling back within the v0.8.x line (e.g., 0.8.18 to 0.8.17) should be safe — the .squad/ format is stable across v0.8.x releases.

What’s New in v0.8.18

  • Remote Squad Mode: squad link, squad init --mode remote, and dual-root path resolution for team identity directories.
  • squad doctor: 9-check setup validation with clear pass/fail output.
  • npm-only distribution: Simpler install, semantic versioning, stable and insider channels.
  • TypeScript strict mode: Full type safety across the SDK and CLI.
  • Semver fix: Version format now follows the semver spec (0.8.18-preview.N instead of 0.8.18.N-preview).

For the full list of changes, see the CHANGELOG.

Questions or issues? Open an issue at github.com/bradygaster/squad.