Skip to content

fix: squad.agent.md silently disappears after upgrade when template source is missing #730

@diberry

Description

@diberry

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

  1. Install squad-cli
  2. Run squad init in a repo (creates .github/agents/squad.agent.md)
  3. Corrupt or remove the template source from the CLI's templates directory
  4. Run squad upgrade
  5. 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions