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.template) is missing.
Root Causes (3 code paths)
1. Silent skip in upgrade.ts (version-current path)
File: packages/squad-cli/src/cli/core/upgrade.ts ~line 497-504
When 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:
if (storage.existsSync(agentSrc)) { // ← silently skips if missing!
storage.copySync(agentSrc, agentDest);
stampVersion(agentDest, cliVersion);
}
2. Silent skip in SDK init.ts
File: packages/squad-sdk/src/config/init.ts ~line 1032-1038
Same pattern — no else clause when template is missing:
if (templatesDir && storage.existsSync(join(templatesDir, 'squad.agent.md.template'))) {
// writes file
} // ← NO ELSE! File never created if template missing
3. No recovery from empty file state
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.
Expected Behavior
- If the template source is missing during upgrade/init, warn the user instead of silently skipping
- Post-upgrade validation should verify
squad.agent.md is non-empty
doctor should offer a recovery action, not just a warning
Steps to Reproduce
- Install squad-cli
- Run
squad init in a repo (creates .github/agents/squad.agent.md)
- Corrupt or remove the template source from the CLI's templates directory
- Run
squad upgrade
- Observe:
squad.agent.md is silently not refreshed (or remains empty)
Affected Files
packages/squad-cli/src/cli/core/upgrade.ts
packages/squad-sdk/src/config/init.ts
packages/squad-cli/src/cli/commands/doctor.ts
Bug
.github/agents/squad.agent.mdcan silently disappear or become empty after runningsquad upgradeorsquad init. This happens because multiple code paths skip file creation without warning when the template source (squad.agent.md.template) is missing.Root Causes (3 code paths)
1. Silent skip in upgrade.ts (version-current path)
File:
packages/squad-cli/src/cli/core/upgrade.ts~line 497-504When 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:2. Silent skip in SDK init.ts
File:
packages/squad-sdk/src/config/init.ts~line 1032-1038Same pattern — no
elseclause when template is missing:3. No recovery from empty file state
doctor.tsalready detects emptysquad.agent.md(test at line 271-280 confirms this is a known condition), but there's no automatic recovery path.Expected Behavior
squad.agent.mdis non-emptydoctorshould offer a recovery action, not just a warningSteps to Reproduce
squad initin a repo (creates.github/agents/squad.agent.md)squad upgradesquad.agent.mdis silently not refreshed (or remains empty)Affected Files
packages/squad-cli/src/cli/core/upgrade.tspackages/squad-sdk/src/config/init.tspackages/squad-cli/src/cli/commands/doctor.ts