Improve migration experience: fix shell init, add migrate command, update docs for all install methods

Summary

Users migrating from v0.5.4 to v0.8.x — particularly those who installed Squad via npx to a repo root rather than globally — encounter several friction points that make the migration feel broken even when following the guide.

What needs improving

1. Shell blocks `/init` when `.squad/` is missing (circular error)

When .squad/team.md doesn't exist, the interactive shell shows "Run /init to create your team first" and returns early — before the /init command can execute. The message is accurate but the fix requires /init to be runnable in the first place.

Fix: scaffold .squad/ with sdkInitSquad() when team.md is absent, then fall through to the existing handleInitCast path.

2. `scrub-emails` defaults to `.ai-team/` (stale default)

cli-entry.ts still defaults to .ai-team/ for the scrub-emails command help text and argument fallback — the directory was renamed to .squad/ in v0.8.

3. No automated migration command

There is currently no squad migrate command. Users must manually back up, delete, and reinitialise — and the steps are different depending on whether they installed globally, locally, or via npx.

New command: squad migrate [--dry-run] [--backup-dir <path>] that backs up .squad/, removes squad-owned scaffold files, runs a fresh sdkInitSquad(), and restores user-owned files (agents, decisions, routing, team.md, skills).

4. Docs reference the removed `npx github:bradygaster/squad` distribution

docs/scenarios/upgrading.md and docs/scenarios/troubleshooting.md still use the old GitHub-hosted install command throughout. The correct package is @bradygaster/squad-cli.

5. Node.js version inconsistency across docs

docs/get-started/migration.md says "Node.js 18 or later"
docs/scenarios/troubleshooting.md says "22.0.0"
Actual package.json engines field: >=20.0.0

6. Migration guide only covers global install

The migration guide (docs/get-started/migration.md) has no steps for local (npm install --save-dev) or npx users. Install commands are also pinned to @0.8.18.

Acceptance criteria

Shell /init "description" works even when .squad/ has been deleted
scrub-emails defaults to .squad/
squad migrate command exists, documented, and tested
docs/scenarios/upgrading.md uses @bradygaster/squad-cli only
docs/scenarios/troubleshooting.md corrected (commands + Node.js version)
docs/get-started/migration.md covers global, local, and npx install paths; uses @latest; documents squad migrate
All existing tests pass; new tests added for migrate command and updated shell behavior

How to test locally

No global install needed. Use the built CLI directly from your local clone.

1. Build the CLI

cd $(git rev-parse --show-toplevel)
npm run build

2. Set a shorthand (optional but convenient)

SQUAD="node $(git rev-parse --show-toplevel)/packages/squad-cli/dist/cli-entry.js"

3. Test `migrate` (dry run first)

In a repo with an existing .squad/ directory:

# Dry run — shows what would happen, no files changed
$SQUAD migrate --dry-run

# Live run
$SQUAD migrate

Expected: backup created at .squad-backup-{timestamp}/, scaffold files cleaned, fresh scaffold applied, user files (agents/, decisions.md, routing.md, team.md, skills/) restored.

4. Test the shell fix (missing `.squad/`)

rm -rf .squad
$SQUAD

Expected: shell scaffolds .squad/ automatically and prompts for init — does not show the circular "Run /init first" error.

5. Verify shell does NOT re-init after migrate

After running $SQUAD migrate, confirm .first-run is gone:

ls .squad/.first-run   # expected: No such file or directory

Then launch the shell and type any message:

$SQUAD
# Should go straight to normal chat, NOT prompt to cast a team

6. Test backup restoration

# Auto-detect and restore from the most recent backup
$SQUAD migrate --restore

# Or specify an explicit backup path
$SQUAD migrate --restore .squad-backup-{timestamp}

Expected: .squad/ is replaced with backup contents intact. When satisfied, clean up: rm -rf .squad-backup-{timestamp}.

7. Test `scrub-emails` default

$SQUAD scrub-emails --help

Expected: default directory shown as .squad/ (not .ai-team/).

8. Verify docs

docs/get-started/migration.md — Node >=20, @latest, all 3 install methods, squad migrate usage
docs/scenarios/upgrading.md — no npx github:bradygaster/squad references
docs/scenarios/troubleshooting.md — Node 20+, no SSH hang section

Implementation status — PR #199

All work is complete. Branch: williamhallatt/197-migration-experience → target: dev

New `squad migrate` command

migrate — backs up .squad/, cleans scaffold files, runs sdkInitSquad(), restores user-owned files (agents/, config.json, decisions.md, routing.md, team.md, skills/)
migrate --dry-run — shows what would happen, no files changed
migrate --backup-dir <path> — custom backup location (constrained to cwd)
migrate --restore — auto-detects and restores the most recent .squad-backup-*/
migrate --restore <path> — restores from a specific backup path (constrained to cwd)
Auto-rollback on error: if anything in steps 2–4 throws, the backup is automatically restored before exit (gated on backupComplete flag — rollback only fires if backup succeeded)

Bug fixes

Shell re-init after migrate — after sdkInitSquad(), .first-run and .init-prompt are deleted so the shell does not treat a migrated install as brand-new
Casting registry missing after migrate — step 4b restores or synthesises casting/registry.json: Case A (v0.8.x): restore entire casting/ from backup; Case B (v0.5.x): scan restored agents/ and create a legacy registry
Cast overwrite guard — createTeam() guards charter.md and history.md, only writes if absent or empty
scrub-emails default path corrected from .ai-team/ to .squad/
config.json preserved — added to USER_OWNED so user Squad config survives migration
Path traversal guards — --restore and --backup-dir reject paths outside cwd

Docs updated

docs/get-started/migration.md — full rewrite: all 9 scenarios, squad migrate flow, restore/rollback instructions, squad init documented as internal
docs/scenarios/upgrading.md, troubleshooting.md — updated
docs/reference/cli.md — migrate command documented; fixed incorrect install entry
docs/scenarios/disaster-recovery.md, keep-my-squad.md, README.md — updated
docs/whatsnew.md — v0.8.21 section added
docs/blog/021-the-migration.md — squad migrate callout added

Tests (57 total, all passing)

File	Count	Covers
`test/migrate-command.test.ts`	23	`runMigrate`, `runRestore`, `findLatestBackup`, dry-run, auto-rollback, `.first-run` cleanup, casting state init
`test/cast-guard.test.ts`	11	`createTeam()` overwrite guard
`test/migrate-e2e.test.ts`	23	Full CLI E2E via `execFileSync`, restore (auto-detect + explicit path), shell reinit guard

fix(cli): fix migration experience for v0.5.x → v0.8.x upgrades

docs: add backup restoration steps to migration guide

docs: documentation sweep for migrate --restore

test: add unit, integration, and E2E tests for squad migrate and cast…

PR #199 opened — ready for review

PR: #199
Branch: williamhallatt/197-migration-experience → dev

What's in the PR

New command: squad migrate
Backs up, cleans, and reinitialises .squad/ in one step. Flags: --dry-run, --backup-dir, --restore [path]. Auto-rollback on failure.

Bug fixes

Shell re-init after migrate (stale .first-run/.init-prompt deleted post-reinit)
Casting registry.json missing after migrate (restored from backup or synthesised from agents/)
createTeam() overwrite guard (charter.md/history.md never overwritten)
scrub-emails default path (.ai-team/ → .squad/)

Tests: 57/57 passing

test/migrate-command.test.ts — 23 unit/integration tests
test/cast-guard.test.ts — 11 overwrite guard tests
test/migrate-e2e.test.ts — 23 E2E tests against built CLI binary

Docs
All migration entry points updated: migration.md, upgrading.md, troubleshooting.md, cli.md, disaster-recovery.md, keep-my-squad.md, README.md, whatsnew.md, 021-the-migration.md

Pre-PR team review summary

9 squad members reviewed the branch. All blockers were fixed before opening:

	Reviewer	Finding
✅	Keaton	`config.json` added to USER_OWNED
✅	Fenster	`backupComplete` flag gates rollback
✅	Edie	TypeScript clean; pre-existing `runInit` issue noted (out of scope)
✅	Hockney	57/57 pass; minor edge case gaps noted (non-blocking)
✅	McManus	`whatsnew.md` v0.8.21 added; `cli.md` install entry fixed
✅	Kujan	SDK integration correct; pre-existing `CastingRegistry` array/object mismatch noted (separate issue)
✅	Breedan	E2E suite passes; v0.5.x binary scenario noted as optional follow-up
✅	Baer	Path containment guards added for `--restore` and `--backup-dir`
✅	Marquez	UX styled; step completion markers added; dry-run output cleaned up

fix(cli): fix migration experience for v0.5.x → v0.8.x upgrades

docs: add backup restoration steps to migration guide

docs: documentation sweep for migrate --restore

test: add unit, integration, and E2E tests for squad migrate and cast…

feat: scaffold monorepo with npm workspaces

docs(ai-team): Merge next-wave triage decisions, update agent history

fix: wire missing CLI commands into cli-entry.ts (#244)

📋 Assigned to PAO (DevRel)

Issue: #197 — Improve migration experience: fix shell init, add migrate command, update docs for all install methods

PAO will pick this up in the next Copilot session.

For Copilot coding agent: If enabled, this issue will be worked automatically.
Otherwise, start a Copilot session and say:
PAO, work on issue #197

📋 Assigned to EECOM (Core Dev)

Issue: #197 — Improve migration experience: fix shell init, add migrate command, update docs for all install methods

EECOM will pick this up in the next Copilot session.

For Copilot coding agent: If enabled, this issue will be worked automatically.
Otherwise, start a Copilot session and say:
EECOM, work on issue #197

Thanks for filing this — it's on our sprint board now. The team will be picking this up in the next session to improve the migration experience across all install paths and platforms. 🚀

chore: update now.md with session state — dev stabilized, 4113 tests,…

docs: add local and npx install paths to migration guide

docs: consolidated docs quality, reduction, and dedup

🔄 Ralph status: Feature — migration experience improvements. No PR. Backlog.

@williamhallatt

@williamhallatt any of these still remaining after your pull requests and other contributions? if so, please re-open but closing for now since i think we got all of these.

Navigation Menu

Repository navigation

Improve migration experience: fix shell init, add migrate command, update docs for all install methods #197

Summary

What needs improving

1. Shell blocks `/init` when `.squad/` is missing (circular error)

2. `scrub-emails` defaults to `.ai-team/` (stale default)

3. No automated migration command

4. Docs reference the removed `npx github:bradygaster/squad` distribution

5. Node.js version inconsistency across docs

6. Migration guide only covers global install

Acceptance criteria

How to test locally

1. Build the CLI

2. Set a shorthand (optional but convenient)

3. Test `migrate` (dry run first)

4. Test the shell fix (missing `.squad/`)

5. Verify shell does NOT re-init after migrate

6. Test backup restoration

7. Test `scrub-emails` default

8. Verify docs

Implementation status — PR #199

New `squad migrate` command

Bug fixes

Docs updated

Tests (57 total, all passing)

PR #199 opened — ready for review

What's in the PR

Pre-PR team review summary

29 remaining items

📋 Assigned to PAO (DevRel)

📋 Assigned to EECOM (Core Dev)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Improve migration experience: fix shell init, add migrate command, update docs for all install methods #197

Description

Summary

What needs improving

1. Shell blocks /init when .squad/ is missing (circular error)

2. scrub-emails defaults to .ai-team/ (stale default)

3. No automated migration command

4. Docs reference the removed npx github:bradygaster/squad distribution

5. Node.js version inconsistency across docs

6. Migration guide only covers global install

Acceptance criteria

Activity

williamhallatt commented on Mar 5, 2026

How to test locally

1. Build the CLI

2. Set a shorthand (optional but convenient)

3. Test migrate (dry run first)

4. Test the shell fix (missing .squad/)

5. Verify shell does NOT re-init after migrate

6. Test backup restoration

7. Test scrub-emails default

8. Verify docs

williamhallatt commented on Mar 5, 2026

Implementation status — PR #199

New squad migrate command

Bug fixes

Docs updated

Tests (57 total, all passing)

williamhallatt commented on Mar 5, 2026

PR #199 opened — ready for review

What's in the PR

Pre-PR team review summary

29 remaining items

github-actions commented on Mar 15, 2026

📋 Assigned to PAO (DevRel)

github-actions commented on Mar 15, 2026

📋 Assigned to EECOM (Core Dev)

bradygaster commented on Mar 15, 2026

diberry commented on Mar 31, 2026

bradygaster commented on May 18, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

1. Shell blocks `/init` when `.squad/` is missing (circular error)

2. `scrub-emails` defaults to `.ai-team/` (stale default)

4. Docs reference the removed `npx github:bradygaster/squad` distribution

3. Test `migrate` (dry run first)

4. Test the shell fix (missing `.squad/`)

7. Test `scrub-emails` default

New `squad migrate` command