Upgrading Squad

Update Squad-owned files to the latest version without losing your team state.

1. Run the Upgrade

From your repo root:

squad upgrade

Squad detects your installed version, updates Squad-owned files, and runs any needed migrations:

✅ upgraded coordinator from 0.1.0 to 0.2.0
✅ upgraded .squad/templates/

Casting state validated — your team's identities and history are preserved

Squad is upgraded. (v0.2.0)

That’s it.

What Gets Upgraded

Squad-owned files (squad.agent.md and .ai-team-templates/) are replaced entirely. Don’t put custom changes in them — they’ll be lost on upgrade.

Updates retain each existing destination’s newline style, including CRLF on Windows, across the coordinator, generated capability block, templates, built-in skills, and workflows. A newline-only difference does not rewrite a managed template; real content updates still apply. New files use shipped template newlines. Upgrade does not change your repository’s line-ending policy.

Shared .mcp.json entries never contain a standalone installation’s absolute path. Packaged installs use squad.exe on Windows or squad on Unix from the MCP host’s PATH; npm installs retain their version-pinned npx entry.

Agent identities, charters, histories, decisions, session logs, and .squad/team.md are preserved byte-for-byte. Upgrade can install optional built-in charters, but it never adds those agents to the roster. Supported legacy casting state is migrated as described below; built-in skills may be refreshed as Squad-owned files.

Opting optional built-ins into the roster

Rai and Fact Checker remain opt-in for existing squads. Use the explicit roster command instead of upgrade:

# Preview the exact team.md diff without writing
squad roster add rai --dry-run

# Add one or both optional built-ins
squad roster add rai
squad roster add fact-checker
squad roster add all

# Remove only rows previously added by this command
squad roster remove rai

The first add writes and verifies .squad/team.md.roster-backup before changing team.md, then records row ownership in .squad/.roster-provenance.json. Repeated adds do not create duplicates, including when an equivalent or case-only row already exists. Removing the last tool-owned row restores the original bytes when the file has not otherwise changed.

Upgrading to Squad 2.0

What changes for existing Copilot-only users

Nothing changes unless you opt in:

• Running squad upgrade without --client keeps your repository Copilot-only, preserves your .squad/ team state, and does not generate files for Claude Code, Kiro, OpenCode, Cursor, Codex, or Antigravity.
• Plain squad init and squad upgrade only scaffold .squad/ runtime ignores (including .squad/backend/) in .gitignore; client-specific ignores such as .claude/worktrees/ are added only when --client claude (or --client all) is selected.

Adding multi-host client projections (--client)

Project your existing .squad/ team into any of the 7 supported hosts (copilot, claude, kiro, opencode, cursor, codex, antigravity, or all):

# Preview which host files would be created or updated
squad upgrade --dry-run --client claude,cursor,codex

# Apply and persist the selected hosts in .squad/config.json clients[]
squad upgrade --client claude,cursor,codex

Subsequent squad upgrade runs automatically refresh every client listed in .squad/config.json clients[] while preserving your existing MCP servers, formatting, and line endings in .mcp.json, .kiro/settings/mcp.json, opencode.json / opencode.jsonc, .cursor/mcp.json, and .codex/config.toml.

Handwritten casting registry repair and team.md backfill

If .squad/casting/registry.json was previously hand-edited by an agent or is empty after an older CLI init, squad upgrade (and squad upgrade --dry-run) automatically repairs it before upgrading managed files:

• Valid provenance records (including retired and inactive agents and extra fields) are kept verbatim and revision is incremented.
• Empty registries are backfilled from .squad/team.md when each specialist maps to a provable .squad/agents/<id>/charter.md folder.
• Pre-repair originals are archived at .squad/casting/handwritten-archive-<sha256>/.
• If an entry cannot be proven (for example, bare strings without a role/name object or a roster row with no matching charter folder), squad upgrade fails closed and prints the exact dropped entries and how to fix them (npx squad cast --name <Name> --role "<Role>").

Deprecated @bradygaster/squad-sdk/clients alias

If you import host adapter APIs programmatically, update @bradygaster/squad-sdk/clients to the canonical @bradygaster/squad-sdk/client subpath. The /clients subpath remains exported in 2.0 as a deprecated compatibility alias for the same symbols.

Experimental backend flag (--experimental-backend)

@bradygaster/squad-sdk/backend (BACKEND_CONTRACT_STAGE = 'experimental') is an opt-in preview surface (DurableSquad Phase 2 server-side integration for remote durable approvals and lease epochs is pending):

• In squad state-mcp, the 11 squad_backend_* MCP conversation tools are disabled by default. Pass --experimental-backend or set SQUAD_EXPERIMENTAL_BACKEND=1 to expose them (SQUAD_BACKEND_URL alone does not enable them).
• In SDK code, import createSquadBackend / DurableHttpSquadBackend from @bradygaster/squad-sdk/backend and pass an explicit https:// baseUrl (http:// only for localhost) and optional token.

Rolling back client projections (uninstallClients)

To remove generated host projections and restore shared files (CLAUDE.md, AGENTS.md, GEMINI.md, .gitignore, and shared MCP config files) byte-for-byte outside Squad’s managed sections:

import { uninstallClients } from '@bradygaster/squad-sdk/client';

uninstallClients(['claude', 'cursor', 'codex'], {
  root: process.cwd(),
  mcp: { command: 'squad', args: ['state-mcp'] },
});

Then remove the corresponding slug(s) from clients in .squad/config.json.

This is projection uninstall only. It does not change the installed CLI, your .squad/ team state, or the Squad version your repository is on, and it is not a way to return to an older Squad.

There is no supported downgrade

Never run an older Squad CLI (npx @bradygaster/squad-cli@<old>, an old standalone bundle, or a stale global install) against a repository that has been upgraded:

• Old CLIs have no newer-version guard; a real squad upgrade from them rewrites the coordinator, skills, workflows and templates back to the old version.
• 0.9.1’s squad upgrade --dry-run is not trustworthy: it performs the downgrade instead of previewing it. Later 0.13.x–1.1.0 CLIs honor --dry-run but still preview overwriting Squad-owned files.
• If an old CLI has already touched an upgraded repository, re-run squad upgrade with the current CLI to repair the Squad-owned files. Team state (team.md, decisions.md, agents’ charters and histories) is not changed by either direction.

The verified behavior of every old release is recorded under Tested upgrade paths below.

Removed in 2.0

Squad 2.0 removes some 1.x features outright; the single record of what was removed is the BREAKING row in What’s New → Breaking & Behavior Changes (v2.0.0). There is no migration tool for removed features. Squad now resolves a team only from the project .squad/ (current directory and parents): outside a project, squad status, squad doctor, squad cast and squad cost exit with No squad in this directory. Run "squad init" first.

squad upgrade removes an obsolete teamRoot setting that older versions could leave in .squad/config.json pointing outside the project (one line: Removed obsolete "teamRoot" setting from .squad/config.json.); a teamRoot that points at another repository (dual-root mode) is left alone. squad upgrade also no longer treats its own version stamps in squad.agent.md as a local customization, so an existing squad.agent.md.local-backup survives repeated upgrades.

Downgrading and old CLIs

Squad does not support downgrading in place. Older CLIs have no “newer workspace” guard — a 0.9.x or 1.x squad upgrade run against a 2.0 workspace will rewrite Squad-owned files to its own templates without warning, and on 0.9.1 squad upgrade --dry-run still writes. To go back, restore .github/agents/squad.agent.md, .github/workflows/squad-*.yml and .squad/ from version control, then install the older CLI. Keep the CLI version pinned per repository (npx @bradygaster/squad-cli@<version>) when several people work on the same workspace.

Tested upgrade paths

Every row below is a pinned, published artifact of an older Squad release driven through squad init under a given project state shape, then upgraded with the CLI packed from the tree under test (npm pack of @bradygaster/squad-sdk + @bradygaster/squad-cli) by test/squad-20-upgrade-matrix.test.ts. A row passes only when every non-xfail assertion passed; a row that carries a pinned finding is reported as pass WITH known … failure (F), never as a bare pass; fail names the failing checks; not applicable cells are each explained individually below (none means “not run”). Machine-readable source: test-fixtures/spec/suite-v0.2/upgrade-matrix.json (protocol upgrade-matrix/v1).

Three different things

⚠️ Never run an older Squad CLI against an upgraded repository. There is no supported downgrade. The downgrade-probe rows record what each old CLI does: 0.9.1 squad upgrade --dry-run is not trustworthy — it rewrites the coordinator, skills, workflows and templates in place (F3); 0.13.1–1.1.0 preview overwriting them. If an old CLI has already touched an upgraded repository, re-run squad upgrade with the current CLI to repair the Squad-owned files; your .squad/ team state is not changed by either direction. uninstallClients() removes host projections only — it is not a way back to an older Squad.

Runs

All recorded runs executed against one tree, commit 9da01a2e41ba15794d31b0b8251ddaa3abd34ba8, with harness hash bca27c39dc2dcbff… (sha256 over the suite, renderer, workflow, fs hook and this fixture minus runs; the integrity test refuses a recorded run whose harness differs from the committed one, so folding results may change nothing but the runs data).

Producers (pinned, immutable provenance)

npm tarballs are fetched by exact version through the registry npm is configured for and verified against the recorded sha1 + sha512 before use; GitHub Release bundles are downloaded by immutable asset id and verified against the recorded sha256. A verification mismatch fails the producer’s rows (it is never a skip); only an unreachable registry/release yields a skip, and that skip carries the reason.

State shapes

Results (version × shape × OS)

Not-applicable cells, each explained

These 7 cells are structurally impossible to exercise — the old producer cannot create that project shape — so they are not “not run”; the suite asserts the recorded skipped rows are exactly this list.

Expected failures (pinned)

Each pin names an open finding; the suite reports the check as xfail and fails the moment it starts passing (xpass), so a pin cannot outlive its bug.

Checks

Paths a plain squad upgrade may create or rewrite (the only changes user-state-preserved accepts):

• ^\.github/agents/squad\.agent\.md(\.local-backup)?$
• ^\.github/copilot-instructions\.md$
• ^\.github/skills/
• ^\.copilot/skills/
• ^\.github/workflows/(squad-[\w-]+|sync-squad-labels)\.yml(\.local-backup)?$
• ^\.squad/\.first-run$
• ^\.squad/config\.json$
• ^\.squad/casting/
• ^\.squad/templates/
• ^\.squad/casting-(history|policy|registry)\.json$
• ^\.squad/agents/(rai|Rai|fact-checker|ralph|scribe)/
• ^\.squad/(rai|fact-checker|identity|memory)/
• ^\.squad/(ceremonies|ralph-instructions)\.md$
• ^\.gitignore$
• ^\.gitattributes$
• ^\.mcp\.json$
• ^\.copilot/mcp-config\.json$
• ^\.vscode/

Findings

Real upgrade defects observed by the suite. An open finding is pinned as an expected failure until fixed (the fix lands in the layer named, not in this test-only layer); a resolved finding keeps its repro here so the matrix row that used to carry it documents the regression guard.

F1 — Stale teamRoot written by 0.13.x–1.x init survives squad upgrade; the upgraded project resolves in remote mode against the removed profile squad

Severity: high · Owner: C — user-profile squad removal (runUpgrade / resolveSquadPaths) · Status: ✅ resolved

Repro:

1. Seed a 1.x profile tree under the platform config dir: the user-profile roster directory and .squad/ under <config>/squad/ (APPDATA on Windows, XDG_CONFIG_HOME on Linux).
2. squad init with @bradygaster/squad-cli 0.13.1 or 1.0.0 (npm) or the 1.0.1 / 1.1.0 standalone bundle: it prints its profile-detected notice and writes .squad/config.json → { "version": 1, "teamRoot": "<config>\\squad" }.
3. Upgrade with the 2.0 CLI packed from this tree: squad upgrade (exit 0, no warning about teamRoot).
4. cat .squad/config.json still contains teamRoot: <config>/squad; squad doctor reports Mode: remote and ❌ routing.md, casting/registry.json, decisions.md not found — it is reading <config>/squad/.squad/, not the project.

Observed: team-root-absent fails (teamRoot=<config-home>/squad) and doctor fails for the profile shape on every 0.13.1+ producer. The profile tree itself stays sha256-identical (profile-untouched passes), so this is a resolution defect, not a write: Squad 2.0 keeps honouring a link to a directory it no longer supports. Expected: squad upgrade drops (or refuses with guidance) a teamRoot that points at the platform config dir, and the project resolves in local mode.

Resolved: Fixed on squad2-c @ 21ecca77 (PR #2279): squad upgrade removes a teamRoot that resolves to the platform config dir / ~/.squad / SQUAD_HOME (isRetiredProfileTeamRoot() in @bradygaster/squad-sdk/resolution) and prints Removed stale teamRoot pointing to <path>; project state is now local; --dry-run previews it; resolveSquadPaths treats such a teamRoot as local mode. Dual-root targets are untouched. Verified by this matrix: team-root-absent and doctor now pass for every 0.13.1+ producer × profile on both OSes (the former pins produced xpass before removal).

F2 — squad upgrade never recognizes its own stamped coordinator: every run reports “local customizations” and overwrites squad.agent.md.local-backup

Severity: medium · Owner: CLI core — packages/squad-cli/src/cli/core/upgrade.ts writeAgentTemplate · Status: ✅ resolved

Repro:

1. squad init (any producer, including the 2.0 CLI itself), then squad upgrade once — a genuine pre-upgrade coordinator is saved to .github/agents/squad.agent.md.local-backup.
2. Run squad upgrade again with nothing changed.
3. Output again says ⚠️ squad.agent.md has local customizations — backed up to squad.agent.md.local-backup; the backup is overwritten with the pristine current coordinator, so the user’s real pre-upgrade copy is gone. The only file whose sha256 changes between run 1 and run 2 is .github/agents/squad.agent.md.local-backup.

Observed: idempotent-second-upgrade fails with exactly .github/agents/squad.agent.md.local-backup for every old producer × shape × platform. On a project initialized by the 2.0 CLI itself the warning is printed on every run too (Already up to date + ⚠️ … local customizations), but the overwritten backup is byte-identical, so the HEAD rows are not pinned. Cause: writeAgentTemplate strips <!-- squad-cli vX --> before comparing, but stampVersion writes <!-- version: X -->, - **Version:** X and Squad vX, so a stamped coordinator never equals the template. Expected: a second squad upgrade is a byte-for-byte no-op, prints no customization warning, and never touches an existing .local-backup.

Resolved: Fixed on squad2-c @ 21ecca77 (PR #2279): stripAgentStamps() (@bradygaster/squad-cli/core/upgrade) normalizes <!-- version: X -->, the - **Version:** token, `Squad vX`, @bradygaster/squad-cli@X and the legacy <!-- squad-cli vX --> before the customization compare, and an identical .local-backup is not rewritten. Verified by this matrix: idempotent-second-upgrade now passes for every producer × shape on both OSes.

F3 — Squad 0.9.1 squad upgrade --dry-run is not dry: pointed at a 2.0 project it silently downgrades the coordinator, skills, workflows and templates in place

Severity: info (historical producer defect — not fixable in 2.0; recorded for the downgrade story) · Owner: none — behavior of the published 0.9.1 CLI · Status: 🔴 open

Repro:

1. Scaffold with 0.9.1 (npm install @bradygaster/squad-cli@0.9.1), upgrade with the 2.0 CLI, copy the project.
2. In the copy run the 0.9.1 CLI: squad upgrade --dry-run.
3. It exits 0, prints the normal upgrade summary (Upgrade complete: v1.2.0-preview.1 → v0.9.1 … Preserves user state: …) and rewrites ~44 files with the pinned 0.9.1 SDK (~83 when 0.9.1’s >=0.9.0 SDK range floats to 1.0.1): .github/agents/squad.agent.md (back to 0.9.1), .copilot/skills/*, .github/workflows/squad-*.yml, .squad/templates/*, plus stray .squad/charter.md, .squad/roster.md, .squad/history.md … at the state root.

Observed: downgrade-probe fails for every 0.9.1 row because the dry-run modified files (destructive: it IS the downgrade) and printed Upgrade complete: v1.2.0-preview.1 → v0.9.1; 0.13.1, 1.0.0, 1.0.1 and 1.1.0 honor --dry-run (Run without --dry-run to apply., nothing modified) but their preview lists overwrite .github/workflows/squad-*.yml etc. — none of the old CLIs has a newer-version guard, so running any of them for real against a 2.0 project downgrades the Squad-owned files. Guidance for users: never run an older CLI against an upgraded repository; re-run squad upgrade with the 2.0 CLI to repair a downgraded coordinator (team state is not touched by the downgrade).

Pinned checks: downgrade-probe (0.9.1 × all shapes × all platforms).

F4 — First squad upgrade of a 0.9.x project (empty .squad/casting/) does not converge: the coordinator’s team-capabilities block is only rendered by the second upgrade

Severity: medium · Owner: CLI core — packages/squad-cli/src/cli/core/upgrade.ts (coordinator write + syncTeamCapabilities run before the casting pair is scaffolded) · Status: ✅ resolved

Repro:

1. npx @bradygaster/squad-cli@0.9.1 init with @bradygaster/squad-sdk@0.9.1 pinned (the faithful 0.9.1 layout): .squad/casting/ exists but contains no registry.json/history.json.
2. Run the 2.0 CLI squad upgrade: it prints ⚠️ Could not refresh squad.agent.md team capabilities: Cannot read a consistent casting registry/history pair: both files are required, then creates the casting pair later in the same run.
3. Run squad upgrade again: ✓ upgraded squad.agent.md — the coordinator gains the 17-line <!-- squad:capabilities … --> block that run 1 could not render. Nothing else changes.

Observed: idempotent-second-upgrade fails with exactly .github/agents/squad.agent.md for 0.9.1 × default/profile/ai-team on both OSes. 0.9.1 × legacy-casting is unaffected because the hand-written registry is repaired in the preflight, so the pair exists before the coordinator is written. The project is correct after the second run; the defect is ordering — the capabilities sync should run after the casting pair is ensured (or the pair should be ensured in the preflight).

Resolved: Fixed on squad2-c @ 50afa91a (PR #2279): runUpgrade runs preflightCastingPair() (ensureCastingDefaults) before writeAgentTemplate in both the already-current and the normal path, so a 0.9.x project with an empty .squad/casting/ gets the <!-- squad:capabilities --> block on the first upgrade and the second upgrade is byte-identical (C test: test/upgrade-profile-teamroot.test.ts › “F4: a 0.9.x project (empty casting/) upgrades in ONE pass”). Verified by this matrix: with the pin still in place, idempotent-second-upgrade produced xpass on exactly 0.9.1 × default/profile/ai-team; the pin is removed.

Unsupported downgrade — what each old CLI does to an upgraded repository

Recorded by the downgrade-probe check (dry-run on a copy; the only assertion is “modified nothing”). This is not a supported path — see the warning at the top of this section.

Migrations

Some upgrades require additive changes to your team state directory — like creating a new subdirectory that didn’t exist in older versions.

Migrations are:

• Preserving — directory migrations are additive; casting schema migrations preserve original files in a non-overwriting archive
• Idempotent — safe to re-run; if the change already exists, it’s skipped

Example: upgrading to v0.2.0 creates .ai-team/skills/ if it doesn’t already exist.

Legacy casting state (upgrades to 1.x)

squad upgrade attempts casting migration before replacing the coordinator, skills, workflows, or other upgrade-managed files, even when the installed coordinator already matches the CLI version. A casting-only failure leaves both live casting files unchanged, but no longer blocks unrelated upgrade work.

Supported unversioned registries have an agents object with persistent names, universes, statuses, and creation dates. Roles default to the agent ID only when absent; display names and update dates default to the persistent name and creation date only when absent. Supported history contains assignment snapshots using members[].folder, agent ID arrays, or role-ID-to-persistent-name maps, with matching universe usage records using created_at or used_at. Snapshots and usage records also accept the historical assigned_at timestamp. If multiple recognized timestamp fields are present, each must be valid and denote the same instant. The original timestamp string, including its timezone offset, is retained; migration never substitutes an agent creation date for an assignment date.

The historical entries[] / assignments[] and agents[] / assignments[] variants emitted by 0.9.x coordinators are also supported when each registry entry’s persistent name matches exactly one canonical folder’s charter.md under the team’s agents/ directory. The charter must contain an ## Identity section with - **Name:**; its optional - **Role:** supplies the role, otherwise the canonical folder ID is used. Missing, duplicated, malformed, or conflicting identities stop migration; names are never slugified into IDs. Keep the original producer’s charters with the state when testing this variant. Each assignment’s explicit persistent-name list or { name, role } member list supplies only that historical membership, not today’s roster. Member roles must agree with the authoritative charter. Its recorded universe and timestamp, created_at, used_at, or assigned_at value supplies the corresponding usage event. Missing universe or date evidence is never filled from the current naming policy or agent creation dates.

Migration preserves agent IDs, names, original dates (including timezone offsets), assignment keys, and snapshot dates. Revision 1 and generated_at establish a new managed migration baseline, not a reconstructed historical generation. An agent created after an older assignment keeps its later creation date.

The byte-exact originals, including repository paths and metadata not represented by the current runtime schema, are retained at casting/legacy-archive-<content-hash>/registry.json and history.json. Archives are never overwritten. Treat them as private state: inspect them before sharing or committing. Publication uses the shared writer lock and recoverable registry/history commit transaction. Repeating migration preserves managed bytes.

squad upgrade --dry-run validates and previews migration without creating locks, archives, or transaction files. Unknown schemas, damaged files, missing pair members, mismatched assignment evidence, or inconsistent managed transactions leave the casting pair byte-exact and produce an actionable warning. The rest of the upgrade continues, including client templates and the squad_state bridge, then repeats the casting warning in the completion summary. Back up the state and seek recovery help; do not manually add revision, delete casting files, or rewrite dates.

Incomplete legacy provenance

Automatic migration refuses agents without a nonempty universe, snapshots with a missing or null universe, and snapshots without matching historical usage. Descriptive names alone do not prove a universe. A current coordinator’s naming policy does not prove the policy of an older assignment. Migration will not invent a universe, usage entry, or historical membership.

The historical entries[] / assignments[] and agents[] / assignments[] pairs require recovery when original folder/charter identities are missing or ambiguous. The diagnostic names the unmapped persistent name and the number of matching folders. Persistent names are not canonical folder IDs. Today’s team roster is not evidence of which agents belonged to an older assignment. Restore the original authoritative charter.md files alongside the original casting pair; do not create charters from guessed name-to-folder mappings.

If either policy stops your upgrade:

1. Keep the installed coordinator and both original casting files intact. Make a private backup of the entire team state directory and coordinator before attempting recovery.
2. Retrieve the original assignment records and producing coordinator from version control or backups. For identity recovery, include original folder IDs and each historical assignment’s membership, not just today’s roster. For universe recovery, include recorded universe and usage evidence for each assignment. Do not fill fields from guesses or create synthetic usage.
3. Request migration/recovery support with the producer version, schema shape, and anonymized evidence. Do not publish private paths, state archives, or team knowledge. If evidence is unavailable, keep using the installed version; this refusal is not a completed migration.
4. After an evidence-backed recovery is available, test it on a disposable backup using squad upgrade --dry-run, then upgrade and verify identities, historical membership, dates, and byte-exact original archives before applying it to the live team.

Migrating .ai-team/ → .squad/ (v0.5.0+)

In Squad v0.5.0, the team state directory was renamed from .ai-team/ to .squad/. Existing repos continue to work — Squad detects both. If you’re still on .ai-team/, you’ll see a deprecation warning.

To migrate your repo:

# Step 1: Upgrade to get the latest migration tooling
squad upgrade

# Step 2: Rename the directory
squad upgrade --migrate-directory

Then commit:

git add -A
git commit -m "chore: migrate .ai-team/ → .squad/"

What the migration does:

• Renames .ai-team/ → .squad/
• Updates .gitignore and .gitattributes references
• Scrubs email addresses from migrated files (PII cleanup)

Timeline: .ai-team/ support continues through v0.6.0. Migration becomes required in v1.0.0.

Full details: See the Migration Guide.

Version Stamping

squad.agent.md is version-stamped on install and upgrade. The version appears in two places:

1. Agent Name (Visible in UI)

The version is displayed in the agent picker across all Copilot hosts (VS Code, CLI, Visual Studio):

name: Squad (vX.Y.Z)

When you select agents in Copilot, you’ll see “Squad (vX.Y.Z)” in the dropdown — making it immediately clear which version you’re running.

2. Version Field (For Reference)

The frontmatter also includes a standalone version field:

version: "X.Y.Z"

3. CLI Check

You can also check your installed version from the command line:

squad --version

The output will show your installed version (e.g., X.Y.Z).

Already Up to Date

If you’re already on the latest version:

squad upgrade

✅ Already up to date (v0.2.0)

Squad still runs any missing migrations in case a prior upgrade was interrupted.

2. Commit the Upgrade

git add .github/agents/squad.agent.md .ai-team-templates/
git commit -m "Upgrade Squad to v0.2.0"

Review the upgrade diff, including any casting migration and original-file archives, before committing. Do not share archives containing private metadata.

Tips

• Upgrade preserves your team. It refreshes Squad-owned files and safely migrates supported casting state with original-file archives.
• Don’t customize squad.agent.md. Any changes you make will be overwritten on the next upgrade. If you need custom behavior, use directives in decisions.md instead.
• Re-running upgrade is harmless. If you’re not sure whether an upgrade completed, run it again. It’s idempotent.

After upgrading to two-layer or orphan

After running squad upgrade --state-backend two-layer (or --state-backend orphan), verify the migration completed cleanly:

1. Working tree is clean

git status

You should see no changes. The migration removes the working-tree state files after copying them to the orphan branch — if .squad/decisions.md or any history.md files still appear as untracked or modified, rerun the migration.

2. Orphan branch contains your state

git ls-tree --name-only -r squad-state

You should see your state files listed (e.g. decisions.md, agents/scribe/history.md). If the branch is missing or empty, the migration may not have completed.

3. Push the orphan branch and notes once

The orphan branch and any git notes need to be pushed to the remote so collaborators can access them:

git push origin squad-state
git push origin 'refs/notes/squad*:refs/notes/squad*'

After this, the post-commit hook keeps both in sync automatically on every commit.

If state files reappear later

If .squad/decisions.md or history.md files reappear in the working tree and a git commit is blocked with ⚠ squad pre-commit: refusing to commit two-layer state into the working tree, see the pre-commit troubleshooting entry for the recovery flow.