Title: [EPIC] v0.5.0 — .squad/ Migration & Architectural Cleanup · Issue #90 · github/squad · GitHub
Open Graph Title: [EPIC] v0.5.0 — .squad/ Migration & Architectural Cleanup · Issue #90 · github/squad
X Title: [EPIC] v0.5.0 — .squad/ Migration & Architectural Cleanup · Issue #90 · github/squad
Description: 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 co...
Open Graph Description: 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 brea...
X Description: 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 brea...
Opengraph URL: https://github.com/github/squad/issues/90
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"[EPIC] v0.5.0 — .squad/ Migration & Architectural Cleanup","articleBody":"## Overview\n\nv0.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.**\n\nThis 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.\n\n---\n\n## 🎯 Anchor Issue\n\n**#69** — Rename .ai-team/ to .squad/ with backward-compatible migration\n- **Impact:** 745 occurrences across 123 files (index.js, squad.agent.md, 6 workflows, 9 templates, 27 docs, tests, configs)\n- **Timeline:** 3-4 weeks (audit → implementation → beta → ship)\n- **Migration UX:** Auto-migrate by default via `npx github:bradygaster/squad upgrade`\n- **Safety:** Automatic backup to `.ai-team-backup-{timestamp}/`, rollback available\n- **Rationale:** Product identity alignment (Squad deserves .squad/, not generic .ai-team/), pre-1.0 house cleaning\n\n---\n\n## 🔧 Critical Fixes Bundled\n\n### #76 — squad.agent.md Exceeds GitHub Enterprise Limit (30K tokens)\n**Status:** INTEGRATED INTO #69 (not separate work)\n- **Problem:** squad.agent.md is 31,842 characters. GitHub Enterprise enforces 30K limit. GHE users blocked.\n- **Solution:** Refactor squad.agent.md into lib/ structure while rewriting paths for #69\n - Main file: 600 lines (coordinator core)\n - `.github/agents/lib/spawning.md`: 300 lines (spawn patterns)\n - `.github/agents/lib/ceremonies.md`: 200 lines (casting/init)\n - `.github/agents/lib/operations.md`: 385 lines (routing/plugins/GitHub)\n- **Result:** 60% size reduction (1485 → 600 lines), GHE compatibility restored\n- **Why bundled:** We're rewriting EVERY path in squad.agent.md for #69 anyway. Touch once, not twice.\n\n### #86 — Squad Undid Uncommitted Changes (Data Loss Bug)\n**Status:** HIGH SEVERITY - Week 1 investigation required\n- **Problem:** User report of Squad silently discarding uncommitted work\n- **Impact:** Trust-destroying if true. Cannot ship v0.5.0 with data loss bugs.\n- **Action:** Investigate in Week 1. If migration-related, MUST fix before release. If elsewhere, still fix.\n\n---\n\n## 🧹 Cleanup & Hardening\n\n### #71 — Remove .ai-team/ Deprecation Banner\n- **Status:** Cleanup (depends on #69 shipping)\n- **Timeline:** 2 hours, ships same day as #69 or in v0.5.1 patch\n- **Rationale:** Once .squad/ is the only supported path, the deprecation warning becomes noise\n\n### #84 — Standardize Timestamps to ISO 8601 UTC\n- **Status:** Consistency improvement\n- **Timeline:** 2 days, parallel to #69\n- **Rationale:** We're already auditing all files for #69. Add timestamp format to the audit checklist. Minimal incremental cost.\n\n### #62 — Release & CI/CD Hardening Plan\n- **Status:** Already assigned to Kobayashi\n- **Timeline:** 1 week, parallel to #69\n- **Rationale:** v0.4.1 recovery established guardrails. More hardening needed before breaking change ships. The migration will stress-test the release pipeline.\n\n---\n\n## ✅ Success Criteria\n\nAll must be GREEN before v0.5.0 ships:\n\n- [ ] **Zero data loss:** All users can migrate .ai-team/ → .squad/ with no lost casting, history, decisions, or skills\n- [ ] **GHE compatibility:** squad.agent.md loads on GitHub Enterprise (\u003c30K characters)\n- [ ] **Rollback safety:** `squad upgrade --rollback-migration` works for 100% of beta testers\n- [ ] **Workflow compatibility:** Guard/triage/heartbeat detect `.squad/**` correctly (not `.ai-team/**`)\n- [ ] **Migration success rate ≥90%:** At most 1 in 10 migrations requires manual intervention\n- [ ] **Documentation accuracy:** Zero stale `.ai-team/` references in shipped docs\n- [ ] **Beta validation:** 5-10 power users complete migration on real repos with no corruption\n\n---\n\n## 📅 Timeline (4 Weeks)\n\n| Week | Dates | Work |\n|------|-------|------|\n| **Week 1** | Feb 17-23 | Audit all 745 .ai-team/ references. Investigate #86 data loss bug. Design atomic migration logic. Kick off parallel work (#62, #84). |\n| **Week 2** | Feb 24-Mar 2 | Implementation: Fenster (rename paths), Verbal (refactor squad.agent.md). Update workflows. Recruit beta cohort via GitHub Discussion. |\n| **Week 3** | Mar 3-9 | **Beta program:** 5-10 users test migration on real repos. 7 exit criteria must pass. Fix any corruption bugs discovered. |\n| **Week 4** | Mar 10-16 | Final validation. Ship v0.5.0. Post-release monitoring. |\n\n**Target ship date:** March 16, 2026 (70% confidence) \n**Fallback date:** March 23, 2026 (if beta finds critical issues)\n\n---\n\n## 🔴 Top 3 Risks + Mitigations\n\n### Risk 1: State Corruption During Migration (CRITICAL)\n**Likelihood:** 15-20% | **Impact:** Catastrophic\n\n**Mitigations:**\n- Pre-flight validation (refuse if uncommitted changes, if .squad/ exists, if mid-merge)\n- Automatic backup before ANY changes: `cp -r .ai-team/ .ai-team-backup-{timestamp}/`\n- Atomic commit (all changes in ONE commit, auto-rollback if commit fails)\n- Rollback command: `squad upgrade --rollback-migration`\n- Test coverage for ALL failure scenarios\n\n### Risk 2: Workflow Failures (HIGH)\n**Likelihood:** 25-30% | **Impact:** High\n\n**Mitigations:**\n- Exhaustive audit: `grep -r \"\\.ai-team\" .github/workflows/` — every workflow file\n- Guard workflow is HIGHEST priority (must block .squad/ from main/preview)\n- Dual-path testing during beta (both .ai-team/ and .squad/ repos validated)\n- Template sync enforcement via CI\n\n### Risk 3: GHE Prompt Size Still Broken After Refactor (MEDIUM)\n**Likelihood:** 10-15% | **Impact:** High\n\n**Mitigations:**\n- Size budget: Main ≤18K chars, includes ≤10K chars total (leaves 2K buffer)\n- GHE beta user validates BEFORE public release (GO/NO-GO gate)\n- Fallback: Ship v0.5.0 with rename only, defer #76 to v0.5.1\n\n---\n\n## 🚫 Deferred to v0.6.0 (Scope Control)\n\nThese issues are legitimate but NOT urgent enough to delay v0.5.0:\n\n- **#63** — Memory System Improvements (assigned to Keaton, not foundational)\n- **#82** — Skills export/import verification (low user impact, code already works)\n- **#85** — Decision lifecycle/archival (nice-to-have, not foundational)\n- **#36** — JetBrains/GitHub.com research (already deferred per decomposition)\n- **#79** — Windsurf/Cursor support (new surface, needs research spike first)\n- **#87** — Workflows assume project type (needs investigation, not breaking)\n- **#88** — Notifications Discord doc outdated (minor docs fix)\n- **#75** — Branch clarity docs/UX (polish, not critical)\n\n---\n\n## 🧪 Beta Program (MANDATORY)\n\n**Cohort:** 5-10 power users\n- Squad's own repos (dogfooding)\n- Community contributors: @spboyer, @londospark, @miketsui3a\n- Volunteers via GitHub Discussions post\n\n**Exit Criteria (All Must Be GREEN):**\n1. ✅ Zero state corruption reports\n2. ✅ Zero rollback failures\n3. ✅ GHE compatibility confirmed (at least 1 GHE user)\n4. ✅ Workflow compatibility (guard/triage/heartbeat work with .squad/)\n5. ✅ Migration success rate ≥90%\n6. ✅ Documentation accuracy (zero stale references)\n7. ✅ Performance regression ≤5%\n\n**Red Flags That STOP Release:**\n- 2+ state corruption reports\n- GHE user reports prompt still too large\n- Workflows don't detect .squad/\n- Rollback fails for any user\n- Docs have >5 stale .ai-team/ references\n\n---\n\n## 📣 Communication Plan\n\n**Timing:** Mid-March ship = MINIMUM breathing room (4 weeks post-v0.4.1). Late March is safer (6-8 weeks).\n\n**Key Message:** \"Your team is safe. Migration is automatic. Rollback is available. This is the last structural change before 1.0.\"\n\n**Channels:**\n- **GitHub Discussion** (2 weeks before release): Beta program + breaking change notice\n- **Blog post** (release day): Why this change, what it fixes (#76), migration walkthrough\n- **README callout** (during beta): Warning that v0.5.0 beta is in progress\n- **Docs migration guide**: Step-by-step upgrade, manual migration, rollback, troubleshooting\n\n**Release Headline:** `v0.5.0: .ai-team/ → .squad/` \n**Subhead:** *Automatic migration, rollback available, last structural change before 1.0*\n\n**Why This Change (3 Beats):**\n1. **Product identity alignment:** Squad deserves .squad/, not generic .ai-team/\n2. **GitHub Enterprise compatibility (#76):** Fixes prompt size bloat, unblocks GHE users\n3. **Pre-1.0 house cleaning:** Last breaking structural change before v1.0\n\n---\n\n## 🔗 Related Issues\n\n**Included in v0.5.0:**\n- #69 (anchor)\n- #76 (integrated into #69)\n- #86 (data loss investigation)\n- #71 (cleanup)\n- #84 (timestamps)\n- #62 (CI/CD hardening)\n\n**Deferred to v0.6.0:**\n- #63, #82, #85, #36, #79, #87, #88, #75\n\n**Closed as duplicate:**\n- #83 (duplicate of #82)\n\n---\n\n## 📊 Work Breakdown\n\n**Total estimated effort:** 242 squad-hours (30 calendar days with parallel work)\n\n| Issue | Owner | Estimate | Dependency |\n|-------|-------|----------|------------|\n| #69 (rename) | Fenster | 80h (2 weeks) | NONE |\n| #76 (refactor) | Verbal | 24h (3 days) | Parallel to #69 |\n| #86 (data loss) | Fenster + Hockney | TBD (Week 1 investigation) | NONE |\n| #71 (banner) | Fenster | 2h | #69 complete |\n| #62 (CI/CD) | Kobayashi | 40h (1 week) | NONE |\n| #84 (timestamps) | Fenster | 16h (2 days) | NONE |\n\n---\n\n## ❓ Decision Points\n\n**For Brady:**\n1. ☑️ **#76 integration:** Merge into #69 (recommended by all three agents)\n2. ☑️ **#86 severity:** Investigate in Week 1, blocks release if migration-related\n3. ⏱️ **Ship date:** March 16 (aggressive) vs. March 23-30 (safer post-Fritz video)\n4. ☑️ **Beta mandatory:** No exceptions. 7 exit criteria must pass.\n5. ⏱️ **Scope locked:** No additions after Week 1 starts (protect timeline)\n\n---\n\n**This epic represents Squad's last breaking change before v1.0. After v0.5.0, directory structure is stable.**","author":{"url":"https://github.com/bradygaster","@type":"Person","name":"bradygaster"},"datePublished":"2026-02-17T01:19:52Z","url":"https://github.com/github/squad/issues/90"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:38f11393-937e-ad9e-f4ff-a63a0b113dd7 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | B8C4:1D41CD:8635F:B1BEA:6B015D5A |
| html-safe-nonce | 0cd30a48b71f65f5c454b6d18333cc0e680a3c4b931de0f03430e673b83668e5 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJCOEM0OjFENDFDRDo4NjM1RjpCMUJFQTo2QjAxNUQ1QSIsInZpc2l0b3JfaWQiOiI4MDY3ODQ1MDE3OTAyODY1NzU0IiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0= |
| visitor-hmac | 2e51310523941857442443344e3c886b359d18bb1b38dca2f8239bc342deb4c7 |
| hovercard-subject-tag | issue:3950244872 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/github/squad/90/issue_layout |
| twitter:image | https://opengraph.githubassets.com/d1e0a7238980e00948bedb5ad8dbdc6f508bc97c9e42a0d866d7fa52aed3dd48/github/squad/issues/90 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/d1e0a7238980e00948bedb5ad8dbdc6f508bc97c9e42a0d866d7fa52aed3dd48/github/squad/issues/90 |
| og:image:alt | 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 brea... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | bradygaster |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| turbo-cache-control | no-preview |
| go-import | github.com/github/squad git https://github.com/github/squad.git |
| octolytics-dimension-user_id | 9919 |
| octolytics-dimension-user_login | github |
| octolytics-dimension-repository_id | 1151205052 |
| octolytics-dimension-repository_nwo | github/squad |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 1151205052 |
| octolytics-dimension-repository_network_root_nwo | github/squad |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width