[EPIC] v0.5.0 — .squad/ Migration & Architectural Cleanup #90

Overview

v0.5.0 is a breaking change release anchored on directory rename (.ai-team/ → .squad/). This affects 745 occurrences across 123 files and requires customer migration. This is the last breaking change before v1.0.

This release combines the migration with critical fixes and architectural cleanup that share the same code paths. Bundling these changes reduces total migration cost for users.

🎯 Anchor Issue

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

• Impact: 745 occurrences across 123 files (index.js, squad.agent.md, 6 workflows, 9 templates, 27 docs, tests, configs)
• Timeline: 3-4 weeks (audit → implementation → beta → ship)
• Migration UX: Auto-migrate by default via npx github:bradygaster/squad upgrade
• Safety: Automatic backup to .ai-team-backup-{timestamp}/, rollback available
• Rationale: Product identity alignment (Squad deserves .squad/, not generic .ai-team/), pre-1.0 house cleaning

🔧 Critical Fixes Bundled

#76 — squad.agent.md Exceeds GitHub Enterprise Limit (30K tokens)

Status: INTEGRATED INTO #69 (not separate work)

• Problem: squad.agent.md is 31,842 characters. GitHub Enterprise enforces 30K limit. GHE users blocked.
• Solution: Refactor squad.agent.md into lib/ structure while rewriting paths for Rename .ai-team/ to .squad/ with backward-compatible migration #69
  • Main file: 600 lines (coordinator core)
  • .github/agents/lib/spawning.md: 300 lines (spawn patterns)
  • .github/agents/lib/ceremonies.md: 200 lines (casting/init)
  • .github/agents/lib/operations.md: 385 lines (routing/plugins/GitHub)
• Result: 60% size reduction (1485 → 600 lines), GHE compatibility restored
• Why bundled: We're rewriting EVERY path in squad.agent.md for Rename .ai-team/ to .squad/ with backward-compatible migration #69 anyway. Touch once, not twice.

#86 — Squad Undid Uncommitted Changes (Data Loss Bug)

Status: HIGH SEVERITY - Week 1 investigation required

• Problem: User report of Squad silently discarding uncommitted work
• Impact: Trust-destroying if true. Cannot ship v0.5.0 with data loss bugs.
• Action: Investigate in Week 1. If migration-related, MUST fix before release. If elsewhere, still fix.

🧹 Cleanup & Hardening

#71 — Remove .ai-team/ Deprecation Banner

• Status: Cleanup (depends on Rename .ai-team/ to .squad/ with backward-compatible migration #69 shipping)
• Timeline: 2 hours, ships same day as Rename .ai-team/ to .squad/ with backward-compatible migration #69 or in v0.5.1 patch
• Rationale: Once .squad/ is the only supported path, the deprecation warning becomes noise

#84 — Standardize Timestamps to ISO 8601 UTC

• Status: Consistency improvement
• Timeline: 2 days, parallel to Rename .ai-team/ to .squad/ with backward-compatible migration #69
• Rationale: We're already auditing all files for Rename .ai-team/ to .squad/ with backward-compatible migration #69. Add timestamp format to the audit checklist. Minimal incremental cost.

#62 — Release & CI/CD Hardening Plan

• Status: Already assigned to Kobayashi
• Timeline: 1 week, parallel to Rename .ai-team/ to .squad/ with backward-compatible migration #69
• Rationale: v0.4.1 recovery established guardrails. More hardening needed before breaking change ships. The migration will stress-test the release pipeline.

✅ Success Criteria

All must be GREEN before v0.5.0 ships:

• Zero data loss: All users can migrate .ai-team/ → .squad/ with no lost casting, history, decisions, or skills
• GHE compatibility: squad.agent.md loads on GitHub Enterprise (<30K characters)
• Rollback safety: squad upgrade --rollback-migration works for 100% of beta testers
• Workflow compatibility: Guard/triage/heartbeat detect .squad/** correctly (not .ai-team/**)
• Migration success rate ≥90%: At most 1 in 10 migrations requires manual intervention
• Documentation accuracy: Zero stale .ai-team/ references in shipped docs
• Beta validation: 5-10 power users complete migration on real repos with no corruption

📅 Timeline (4 Weeks)

Target ship date: March 16, 2026 (70% confidence)
Fallback date: March 23, 2026 (if beta finds critical issues)

🔴 Top 3 Risks + Mitigations

Risk 1: State Corruption During Migration (CRITICAL)

Likelihood: 15-20% | Impact: Catastrophic

Mitigations:

• Pre-flight validation (refuse if uncommitted changes, if .squad/ exists, if mid-merge)
• Automatic backup before ANY changes: cp -r .ai-team/ .ai-team-backup-{timestamp}/
• Atomic commit (all changes in ONE commit, auto-rollback if commit fails)
• Rollback command: squad upgrade --rollback-migration
• Test coverage for ALL failure scenarios

Risk 2: Workflow Failures (HIGH)

Likelihood: 25-30% | Impact: High

Mitigations:

• Exhaustive audit: grep -r "\.ai-team" .github/workflows/ — every workflow file
• Guard workflow is HIGHEST priority (must block .squad/ from main/preview)
• Dual-path testing during beta (both .ai-team/ and .squad/ repos validated)
• Template sync enforcement via CI

Risk 3: GHE Prompt Size Still Broken After Refactor (MEDIUM)

Likelihood: 10-15% | Impact: High

Mitigations:

• Size budget: Main ≤18K chars, includes ≤10K chars total (leaves 2K buffer)
• GHE beta user validates BEFORE public release (GO/NO-GO gate)
• Fallback: Ship v0.5.0 with rename only, defer Squads in GitHub Enterprise Copilot- Invalid config "Prompt" exceeds max length 30000 #76 to v0.5.1

🚫 Deferred to v0.6.0 (Scope Control)

These issues are legitimate but NOT urgent enough to delay v0.5.0:

• Memory System Improvements — Feedback Welcome #63 — Memory System Improvements (assigned to Keaton, not foundational)
• Verify skills are preserved during export/import and document skill-agent associations #82 — Skills export/import verification (low user impact, code already works)
• Decision lifecycle management and archival system #85 — Decision lifecycle/archival (nice-to-have, not foundational)
• JetBrains + GitHub.com surface research (deferred to v0.5.0) #36 — JetBrains/GitHub.com research (already deferred per decomposition)
• Windsurf/Cursor/Etc. Support #79 — Windsurf/Cursor support (new surface, needs research spike first)
• squad- workflows seem to assume a particular project type? #87 — Workflows assume project type (needs investigation, not breaking)
• Notifications Discord quickstart instructions are out dated #88 — Notifications Discord doc outdated (minor docs fix)
• I Would Like Some Clarity on Ways of Working with squad (Branches) #75 — Branch clarity docs/UX (polish, not critical)

🧪 Beta Program (MANDATORY)

Cohort: 5-10 power users

• Squad's own repos (dogfooding)
• Community contributors: @spboyer, @londospark, @miketsui3a
• Volunteers via GitHub Discussions post

Exit Criteria (All Must Be GREEN):

1. ✅ Zero state corruption reports
2. ✅ Zero rollback failures
3. ✅ GHE compatibility confirmed (at least 1 GHE user)
4. ✅ Workflow compatibility (guard/triage/heartbeat work with .squad/)
5. ✅ Migration success rate ≥90%
6. ✅ Documentation accuracy (zero stale references)
7. ✅ Performance regression ≤5%

Red Flags That STOP Release:

• 2+ state corruption reports
• GHE user reports prompt still too large
• Workflows don't detect .squad/
• Rollback fails for any user
• Docs have >5 stale .ai-team/ references

📣 Communication Plan

Timing: Mid-March ship = MINIMUM breathing room (4 weeks post-v0.4.1). Late March is safer (6-8 weeks).

Key Message: "Your team is safe. Migration is automatic. Rollback is available. This is the last structural change before 1.0."

Channels:

• GitHub Discussion (2 weeks before release): Beta program + breaking change notice
• Blog post (release day): Why this change, what it fixes (Squads in GitHub Enterprise Copilot- Invalid config "Prompt" exceeds max length 30000 #76), migration walkthrough
• README callout (during beta): Warning that v0.5.0 beta is in progress
• Docs migration guide: Step-by-step upgrade, manual migration, rollback, troubleshooting

Release Headline: v0.5.0: .ai-team/ → .squad/
Subhead: Automatic migration, rollback available, last structural change before 1.0

Why This Change (3 Beats):

1. Product identity alignment: Squad deserves .squad/, not generic .ai-team/
2. GitHub Enterprise compatibility (Squads in GitHub Enterprise Copilot- Invalid config "Prompt" exceeds max length 30000 #76): Fixes prompt size bloat, unblocks GHE users
3. Pre-1.0 house cleaning: Last breaking structural change before v1.0

🔗 Related Issues

Included in v0.5.0:

• Rename .ai-team/ to .squad/ with backward-compatible migration #69 (anchor)
• Squads in GitHub Enterprise Copilot- Invalid config "Prompt" exceeds max length 30000 #76 (integrated into Rename .ai-team/ to .squad/ with backward-compatible migration #69)
• Squad undid its own uncommited changes from a previous session #86 (data loss investigation)
• Remove .ai-team/ deprecation banner (no longer needed after rename) #71 (cleanup)
• Standardize timestamps to ISO 8601 UTC across all logs and decisions #84 (timestamps)
• Release & CI/CD Hardening Plan for v0.5.0 #62 (CI/CD hardening)

Deferred to v0.6.0:

• Memory System Improvements — Feedback Welcome #63, Verify skills are preserved during export/import and document skill-agent associations #82, Decision lifecycle management and archival system #85, JetBrains + GitHub.com surface research (deferred to v0.5.0) #36, Windsurf/Cursor/Etc. Support #79, squad- workflows seem to assume a particular project type? #87, Notifications Discord quickstart instructions are out dated #88, I Would Like Some Clarity on Ways of Working with squad (Branches) #75

Closed as duplicate:

• Verify skills are preserved during export/import #83 (duplicate of Verify skills are preserved during export/import and document skill-agent associations #82)

📊 Work Breakdown

Total estimated effort: 242 squad-hours (30 calendar days with parallel work)

❓ Decision Points

For Brady:

1. ☑️ Squads in GitHub Enterprise Copilot- Invalid config "Prompt" exceeds max length 30000 #76 integration: Merge into Rename .ai-team/ to .squad/ with backward-compatible migration #69 (recommended by all three agents)
2. ☑️ Squad undid its own uncommited changes from a previous session #86 severity: Investigate in Week 1, blocks release if migration-related
3. ⏱️ Ship date: March 16 (aggressive) vs. March 23-30 (safer post-Fritz video)
4. ☑️ Beta mandatory: No exceptions. 7 exit criteria must pass.
5. ⏱️ Scope locked: No additions after Week 1 starts (protect timeline)

This epic represents Squad's last breaking change before v1.0. After v0.5.0, directory structure is stable.