Skip to content

Coordinator should check for new Squad version on session start and offer to upgrade (with what's new digest) #1173

Closed

Description

@tamirdresher

Summary

Squad currently stamps its own version (Squad v0.9.6-insider.2) into the session greeting, but never checks if a newer version exists and never prompts the user to upgrade. Users only discover updates by manually checking GitHub or running npm view.

What's there today

  • .github/agents/squad.agent.md line 6: <!-- version: 0.9.6-insider.2 --> stamped at install/upgrade time
  • Line 13: instruction to include the version in the first response
  • "Restart guidance" rule: tells the user to restart after squad.agent.md changes (reactive, not proactive)

No check against the latest published version. No upgrade prompt. No "what's new".

Proposed behavior

On session start (in addition to existing git config user.name and team-root resolution):

  1. Cheap version check — fetch the latest published version of @bradygaster/squad-cli (or whichever package this install came from). Cache the result for ~24h in .squad/.cache/version-check.json so we don't hit npm on every session.
  2. Compare against the stamped version in squad.agent.md.
  3. If newer is available, surface a one-liner in the session greeting:
    🆕 Squad vX.Y.Z available (you're on v0.9.6-insider.2). Run `squad upgrade` — or say "upgrade squad" and I'll do it.
    
  4. On user confirm ("upgrade squad" / "yes upgrade"):
    • Run squad upgrade (preserving the configured stateBackend from .squad/config.json)
    • After upgrade, read the relevant CHANGELOG entry/entries between old and new version
    • Show a short "What's new" digest (3–6 bullets max) in the chat
    • Remind the user: "🔄 squad.agent.md updated. Restart your session to pick up the new coordinator." (existing self-development rule)

Constraints

  • Must not slow down session startup if network is unavailable / slow — fail silent, fall back to cached check
  • Must respect offline mode (kill switch like SQUAD_NO_VERSION_CHECK=1)
  • Must work across both worktree and orphan/git-notes state backends — upgrade must preserve user state
  • Cache must be invalidated correctly after a manual squad upgrade

Acceptance criteria

  • Version check runs at session start, cached for ~24h
  • User sees an unobtrusive notice when a newer version exists
  • User can trigger upgrade via chat
  • Upgrade preserves stateBackend and any user customization
  • "What's new" digest appears after upgrade (sourced from CHANGELOG.md between versions)
  • Restart prompt shown after squad.agent.md changes
  • Kill switch / offline behavior documented
  • No measurable slowdown when network is unreachable

Out of scope

  • Auto-upgrade without confirmation (always ask)
  • Major version migrations beyond what squad upgrade already handles
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions