Rename .ai-team/ to .squad/ with backward-compatible migration

The Nasty Thought

We named the team state directory .ai-team/ but we should have called it .squad/. It's our product name, it's shorter, and it's immediately clear what tool owns it.

Scope of Change

This is a breaking rename affecting ~745 occurrences across ~123 files in the source repo alone — plus every customer repo that has run squad init.

What references `.ai-team/`:

squad.agent.md — the coordinator prompt (paths in every spawn template, every file operation)
index.js — CLI creates/manages the directory
6 GitHub Actions workflows (guard, triage, issue-assign, heartbeat, preview, sync-labels)
9 template files
27 docs files
2 test files
.gitignore, .gitattributes, .npmignore
Every existing customer repo

Migration Strategy

Phase 1: Dual-path support (v0.5.0)

CLI checks for .squad/ first, falls back to .ai-team/
squad upgrade gains --migrate-directory flag that:
1. git mv .ai-team/ .squad/
2. Updates .gitattributes merge drivers
3. Updates .gitignore entries
4. Commits the rename
squad init creates .squad/ for new projects
squad.agent.md updated to resolve either path (team root detection)
Workflows detect both paths
Deprecation warning when .ai-team/ is detected: "⚠ .ai-team/ is deprecated. Run squad upgrade --migrate-directory to rename to .squad/."

Phase 2: Remove legacy support (v1.0.0)

Drop .ai-team/ fallback
CLI errors if .ai-team/ exists without .squad/
Clean removal of all dual-path logic

Why .squad/?

Branded — immediately identifies the tool
Shorter — 6 chars vs 8
Conventional — follows patterns like .github/, .vscode/, .husky/
No ambiguity — .ai-team could be any AI tool; .squad is ours

Acceptance Criteria

squad init creates .squad/ for new projects
squad upgrade --migrate-directory renames .ai-team/ to .squad/
CLI resolves either directory (backward compat in v0.5.0)
squad.agent.md team root detection checks both paths
All workflows handle both paths during transition
Deprecation warning shown when .ai-team/ detected
All source repo references updated (agent.md, templates, docs, tests, CI)
Migration tested on a repo with existing .ai-team/ state
.ai-team-templates/ also renamed to .squad-templates/ (or merged into .squad/templates/)

This is me personally speaking to all Squad team members and users - I'm so glad you're enjoying Squad, but this is a change we need to make now, while growth is still in its infancy, to make sure our files are obvious from now on. ai-team is so bland and generic. I'm shocked no one caught it earlier. We need to make sure it is obvious where "OUR" files are in users' repositories. We'll try to implement this in such a way that it impacts only new users, but this may be the first of what-I-hope-is-less-than-2-forever breaking changes we ever ship in Squad.

This change will come prior to 1.0. I'm going to try to get this into 0.5.0, but if I try it myself on a few existing projects and things hit the oscillator, I'll come up with a one-time workaround.

Sorry in advance if it comes to that!

docs(ai-team): agent history updates and decision inbox entries

Can we have a migration script included in the move to this version

Migration Plan for v0.5.0: .ai-team/ → .squad/

We've designed a migration strategy that balances automatic upgrade with user control. Before we implement this, we want your feedback. Does this approach work for your workflows? Any edge cases we're missing?

Three Migration Paths (All Scripted)

1. Auto-Migrate (Default)

When you run any Squad command after upgrading to v0.5.0, migration happens automatically:

npx github:bradygaster/squad init

🔄 Migrating .ai-team/ → .squad/...
   📦 Backed up to .ai-team.backup-20260216-143022/
   📁 Moved .ai-team/ → .squad/
   📝 Updated .gitignore and .gitattributes
   ✅ Changes committed. Push when ready: git push

What happens:

Pre-flight checks (repo clean, no conflicts)
Auto-backup to .ai-team.backup-{timestamp}/
Atomic git move via git mv
Config updates (.gitignore, .gitattributes)
Auto-commit with message
You just need to push

2. Defer Auto-Migrate (Scripted Workaround)

If you want control over timing:

# Skip auto-migration
export SQUAD_SKIP_AUTO_MIGRATE=true

npx github:bradygaster/squad init
# → Shows: "⚠️  .ai-team/ detected. Migrate when ready: squad upgrade --migrate-directory"

# When you're ready:
npx github:bradygaster/squad upgrade --migrate-directory
# → Runs same migration script, YOU commit and push

3. Rollback (Safety Valve)

Changed your mind? Rollback is one command:

squad upgrade --rollback-migration
# → Restores .ai-team/ from backup
# → You can downgrade: npx github:bradygaster/squad@v0.4.1

Key Points

✅ Automatic by default - Zero friction for 95% of users
✅ Fully scripted workaround - Defer with env var, migrate when ready
✅ Safe - Auto-backup, pre-flight checks, rollback available
✅ No dual-path maintenance - v0.5.0 only reads .squad/
✅ Forward-only - Users upgrade linearly (v0.4.1 → v0.5.0)

Timeline

Week 1 (Feb 17-23): Audit all 745 .ai-team/ references, implement migration
Week 2 (Feb 24-Mar 2): Testing, edge cases, docs updates
Week 3 (Mar 3-9): Beta program (5-10 users with real repos)
Week 4 (Mar 10-16): Ship v0.5.0

What We Need From You

Would this migration approach work for your workflow?

Does auto-migrate feel safe, or would you prefer opt-in?
Is the \SQUAD_SKIP_AUTO_MIGRATE\ escape hatch sufficient?
Any edge cases we're missing? (monorepos, submodules, exotic git setups, etc.)
Concerns about the 3-week timeline?

Feedback welcome here or in Discussions. We want to get this right before we start coding.

Note - these dates aren't accurate. We'll have it out by EOW.

feat: dual-path support for .squad/ and .ai-team/ directories

Merge feature/dual-path-squad-support into develop

Updated Scope: Single .squad/ Folder

Brady directive (Feb 18): Everything goes inside .squad/ — no separate templates directory.

Impact on your audit:

.ai-team-templates/ → .squad/templates/ (nested inside .squad/)
Reference count increases from 1,572 to ~1,672 (+100 template refs)
Estimate increases from 15-20h to ~17-22h (+2h for nested directory handling)

Your 3-PR plan still works:

PR feat: worktree awareness, Scribe auto-commit, and decision consolidation #1: CLI foundation (now handles nested templates dir)
PR feat: GitHub Issues intake, PRD mode, and human team members #2: Documentation (~120 files → ~130 files)
PR [TEST] API capability test — will be deleted #3: Workflows (no change)

Migration logic addition:

Create .squad/templates/ subdirectory structure
Preserve template organization (casting/, workflows/, skills/)
Update index.js to look for templates at .squad/templates/ first, fall back to .ai-team-templates/

Full directive captured in .ai-team/decisions/inbox/copilot-directive-single-squad-folder.md

v0.5.0 Consolidation Directive — Clarified

From: Today's session with Brady, Keaton, Fenster

This comment clarifies the consolidation scope for the .ai-team/ → .squad/ migration in v0.5.0.

Brady's Directive (Consolidated)

In v0.5.0, consolidate everything under .squad/ except:

index.js — CLI entry point (root required for npx)
package.json — Package manifest (root required for npx)
emplates/ — Init boilerplate (root required for npx to copy during create-squad)

Rationale: Eliminate the naming sprawl. One branded folder (.squad/) for all team artifacts; npx-critical files stay at root.

Directory Migration Plan

.ai-team/ → .squad/
.ai-team-templates/ → .squad/templates/ (merged under .squad)
templates/ → templates/ (stays at root)

Guard Workflow Policy

Block .squad/ entirely from protected branches** (main/preview/insider).

Why simple, no carve-outs:

.squad/ = team runtime state (never ships)
emplates/ at root = public boilerplate (ships in npm tarball)
Separation is semantic AND technical

Guard workflow updated Feb 20 to also block docs/proposals/ (internal design work).

Affected Scopes

CLI (index.js): Dual-path support — check .squad/ first, fall back to .ai-team/
squad.agent.md: ~745 occurrences across ~123 files. Team root detection checks both paths.
Workflows (6+): All handle both paths during v0.5.0
Templates: .ai-team-templates/ merges into .squad/templates/
Documentation & Tests: 27 docs + 2 test files updated

Branch Content Policy (Formalized Feb 20)

✅ ALLOWED on main/preview/insider: index.js, package.json, templates/, .github/, docs/ (except proposals), test/

❌ FORBIDDEN on main/preview/insider: .squad/, .ai-team/, .ai-team-templates/, team-docs/, docs/proposals/

See .ai-team/decisions/inbox/copilot-branch-content-policy.md for full policy.

Status: Epic updated with consolidated directive from today's session.

docs(ai-team): session log, orchestration entries, decision merge

Scope Update: Identity Layer added to v0.5.0

Per Brady's directive (2026-02-20): wisdom.md and now.md are now part of v0.5.0 instead of deferred to v0.6.0. Rationale: we're already touching every path during the rename — adding two files under .squad/identity/ is near-zero marginal effort.

New sub-issue: #107 — Add identity layer (wisdom.md + now.md) to .squad/ structure

Updated sub-issue list:

CLI dual-path support for .squad/ migration #101 — CLI dual-path support
squad.agent.md path migration - 745 references #102 — squad.agent.md path updates
Workflow dual-path support for .squad/ migration #103 — Workflow dual-path support
Merge .ai-team-templates/ into .squad/templates/ #104 — Merge .ai-team-templates/ into .squad/
Documentation and test updates for .squad/ paths #105 — Docs and tests updates
Guard workflow enforcement - verify .squad/ blocking #106 — Guard workflow verification
Add identity layer (wisdom.md + now.md) to .squad/ structure #107 — Identity layer (wisdom.md + now.md) NEW

docs(ai-team): Capture identity layer scope change to v0.5.0

Privacy: Email scrub added to migration scope

New sub-issue: #108 — Scrub email addresses from .squad/ files during migration

The squad upgrade --migrate-directory tool must also scrub user email addresses that were written to .ai-team/ files by earlier versions. This is now part of the auto-migration checklist.

Updated sub-issue list:

CLI dual-path support for .squad/ migration #101 — CLI dual-path support
squad.agent.md path migration - 745 references #102 — squad.agent.md path updates
Workflow dual-path support for .squad/ migration #103 — Workflow dual-path support
Merge .ai-team-templates/ into .squad/templates/ #104 — Merge .ai-team-templates/ into .squad/
Documentation and test updates for .squad/ paths #105 — Docs and tests updates
Guard workflow enforcement - verify .squad/ blocking #106 — Guard workflow verification
Add identity layer (wisdom.md + now.md) to .squad/ structure #107 — Identity layer (wisdom.md + now.md)
Privacy: Scrub email addresses from .squad/ files during migration #108 — Privacy: email scrub during migration NEW

Complete. .ai-team/ → .squad/ migration shipped via PRs #109–#113: CLI dual-path (#111), workflow dual-path (#109), .ai-team-templates/ move (#112), docs/test updates (#113), email scrubbing (#110). Backward-compatible migration via 'squad upgrade'.

Merge pull request github#69 from jbenami_microsoft/squad/64-watchdog…

Navigation Menu

Repository navigation

Rename .ai-team/ to .squad/ with backward-compatible migration #69

The Nasty Thought

Scope of Change

What references `.ai-team/`:

Migration Strategy

Phase 1: Dual-path support (v0.5.0)

Phase 2: Remove legacy support (v1.0.0)

Why .squad/?

Acceptance Criteria

Migration Plan for v0.5.0: .ai-team/ → .squad/

Three Migration Paths (All Scripted)

1. Auto-Migrate (Default)

2. Defer Auto-Migrate (Scripted Workaround)

3. Rollback (Safety Valve)

Key Points

Timeline

What We Need From You

Updated Scope: Single .squad/ Folder

v0.5.0 Consolidation Directive — Clarified

Brady's Directive (Consolidated)

Directory Migration Plan

Guard Workflow Policy

Affected Scopes

Branch Content Policy (Formalized Feb 20)

Scope Update: Identity Layer added to v0.5.0

Updated sub-issue list:

Privacy: Email scrub added to migration scope

Updated sub-issue list:

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Rename .ai-team/ to .squad/ with backward-compatible migration #69

Description

The Nasty Thought

Scope of Change

What references .ai-team/:

Migration Strategy

Phase 1: Dual-path support (v0.5.0)

Phase 2: Remove legacy support (v1.0.0)

Why .squad/?

Acceptance Criteria

Activity

bradygaster commented on Feb 15, 2026

spboyer commented on Feb 16, 2026

bradygaster commented on Feb 16, 2026

Migration Plan for v0.5.0: .ai-team/ → .squad/

Three Migration Paths (All Scripted)

1. Auto-Migrate (Default)

2. Defer Auto-Migrate (Scripted Workaround)

3. Rollback (Safety Valve)

Key Points

Timeline

What We Need From You

bradygaster commented on Feb 16, 2026

bradygaster commented on Feb 18, 2026

Updated Scope: Single .squad/ Folder

bradygaster commented on Feb 20, 2026

v0.5.0 Consolidation Directive — Clarified

Brady's Directive (Consolidated)

Directory Migration Plan

Guard Workflow Policy

Affected Scopes

Branch Content Policy (Formalized Feb 20)

bradygaster commented on Feb 20, 2026

Scope Update: Identity Layer added to v0.5.0

Updated sub-issue list:

bradygaster commented on Feb 20, 2026

Privacy: Email scrub added to migration scope

Updated sub-issue list:

bradygaster commented on Feb 20, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

What references `.ai-team/`: