Title: fix: squad.agent.md silently disappears after upgrade when template source is missing · Issue #730 · github/squad · GitHub
Open Graph Title: fix: squad.agent.md silently disappears after upgrade when template source is missing · Issue #730 · github/squad
X Title: fix: squad.agent.md silently disappears after upgrade when template source is missing · Issue #730 · github/squad
Description: Bug .github/agents/squad.agent.md can silently disappear or become empty after running squad upgrade or squad init. This happens because multiple code paths skip file creation without warning when the template source (squad.agent.md.temp...
Open Graph Description: Bug .github/agents/squad.agent.md can silently disappear or become empty after running squad upgrade or squad init. This happens because multiple code paths skip file creation without warning when ...
X Description: Bug .github/agents/squad.agent.md can silently disappear or become empty after running squad upgrade or squad init. This happens because multiple code paths skip file creation without warning when ...
Opengraph URL: https://github.com/github/squad/issues/730
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"fix: squad.agent.md silently disappears after upgrade when template source is missing","articleBody":"## Bug\n\n`.github/agents/squad.agent.md` can silently disappear or become empty after running `squad upgrade` or `squad init`. This happens because multiple code paths skip file creation without warning when the template source (`squad.agent.md.template`) is missing.\n\n## Root Causes (3 code paths)\n\n### 1. Silent skip in upgrade.ts (version-current path)\n**File:** `packages/squad-cli/src/cli/core/upgrade.ts` ~line 497-504\n\nWhen the CLI version is already current, the upgrade refreshes `squad.agent.md` — but if the template source doesn't exist, it silently skips with no warning:\n```typescript\nif (storage.existsSync(agentSrc)) { // ← silently skips if missing!\n storage.copySync(agentSrc, agentDest);\n stampVersion(agentDest, cliVersion);\n}\n```\n\n### 2. Silent skip in SDK init.ts\n**File:** `packages/squad-sdk/src/config/init.ts` ~line 1032-1038\n\nSame pattern — no `else` clause when template is missing:\n```typescript\nif (templatesDir && storage.existsSync(join(templatesDir, 'squad.agent.md.template'))) {\n // writes file\n} // ← NO ELSE! File never created if template missing\n```\n\n### 3. No recovery from empty file state\n`doctor.ts` already detects empty `squad.agent.md` (test at line 271-280 confirms this is a known condition), but there's no automatic recovery path.\n\n## Expected Behavior\n\n- If the template source is missing during upgrade/init, **warn the user** instead of silently skipping\n- Post-upgrade validation should verify `squad.agent.md` is non-empty\n- `doctor` should offer a recovery action, not just a warning\n\n## Steps to Reproduce\n\n1. Install squad-cli\n2. Run `squad init` in a repo (creates `.github/agents/squad.agent.md`)\n3. Corrupt or remove the template source from the CLI's templates directory\n4. Run `squad upgrade`\n5. Observe: `squad.agent.md` is silently not refreshed (or remains empty)\n\n## Affected Files\n\n- `packages/squad-cli/src/cli/core/upgrade.ts`\n- `packages/squad-sdk/src/config/init.ts`\n- `packages/squad-cli/src/cli/commands/doctor.ts`","author":{"url":"https://github.com/diberry","@type":"Person","name":"diberry"},"datePublished":"2026-04-01T22:14:26Z","url":"https://github.com/github/squad/issues/730"}
| 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:e0031543-491a-1724-4791-f8554a60c736 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | C964:3A4875:1F33906:29864A3:6B017765 |
| html-safe-nonce | 3428ccadaecb81a177d9b929c9e61bd6600390d22b9c1a3bb2ceb157952a8bf2 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJDOTY0OjNBNDg3NToxRjMzOTA2OjI5ODY0QTM6NkIwMTc3NjUiLCJ2aXNpdG9yX2lkIjoiNDI1OTk1MDE1ODg0ODAzMDU2NSIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | 069a7bcd0471c3590f94b39f1346385cc774118a46367c6855b7d41ceb6c4286 |
| hovercard-subject-tag | issue:4190202284 |
| 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/730/issue_layout |
| twitter:image | https://opengraph.githubassets.com/9332e3ae191f2272a31e31d36bd3eac2b4ac0709150b60bebc91b82cc6da53a2/github/squad/issues/730 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/9332e3ae191f2272a31e31d36bd3eac2b4ac0709150b60bebc91b82cc6da53a2/github/squad/issues/730 |
| og:image:alt | Bug .github/agents/squad.agent.md can silently disappear or become empty after running squad upgrade or squad init. This happens because multiple code paths skip file creation without warning when ... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | diberry |
| 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