feat(cli): warn when a newer spec-kit release is available (#1320)

CHANGELOG.md

@@ -2,308 +2,6 @@
 
 <!-- insert new changelog below this comment -->
 
-## [0.8.13] - 2026-05-21
-
-### Changed
-
-- fix: while/do-while loop condition reads stale iteration-0 step output (#2662)
-- docs: fix directory hierarchy in README examples (#2639)
-- fix(catalogs): reject boolean priority in extension and preset catalog readers (#2589)
-- Update Agent Governance extension to v1.2.0 (#2659)
-- Add agentic workflows for community catalog submissions (#2655)
-- feat: add self-check tip to check output (#2574)
-- fix(cli): clarify exception diagnostics (#2602)
-- ci: add diff whitespace check (#2572)
-- chore: release 0.8.12, begin 0.8.13.dev0 development (#2648)
-
-## [0.8.12] - 2026-05-20
-
-### Changed
-
-- fix(codex): inject dot-to-hyphen hook command note in Codex skills (#2503)
-- Update Squad Bridge extension to v1.3.0 (#2645)
-- Update Superpowers Implementation Bridge extension to v0.5.0 (#2644)
-- Add Team Assign extension to community catalog (#2642)
-- refactor: migrate extension catalog stack parsing to shared base (#2576)
-- Update Architecture Workflow extension to v1.1.0 (#2588)
--  fix(workflow): support integration: auto to follow project's initialized AI (#2421)
-- Add Superpowers Implementation Bridge extension to community catalog (#2586)
-- Add Interactive HTML Preview extension to community catalog (#2585)
-- chore: release 0.8.11, begin 0.8.12.dev0 development (#2584)
-- Update Agent Governance extension to v1.1.0 (#2583)
-
-## [0.8.11] - 2026-05-15
-
-### Changed
-
-- refactor: extract _version.py from __init__.py (PR-3/8) (#2550)
-- Add Time Machine extension to community catalog (#2580)
-- fix(powershell): ensure UTF-8 templates are written without BOM (#2280)
-- docs: document high-assurance spec workflow (#2518)
-- docs: fix script name in directory tree examples (#2555)
-- Fix preset skill description precedence (#2538)
-- fix(integration): clarify multi-install guidance (#2549)
-- feat: add version feature reporting (#2548)
-- Add Architecture Workflow extension to community catalog (#2565)
-- chore: release 0.8.10, begin 0.8.11.dev0 development (#2562)
-
-## [0.8.10] - 2026-05-14
-
-### Changed
-
-- docs: streamline install section and add community overview (#2561)
-- Move community extensions table from README to docs site (#2560)
-- Add Agent Governance extension to community catalog (#2559)
-- Add Reqnroll BDD extension to community catalog (#2545)
-- fix(cli): harden extension registration and discovery workflows (#2499)
-- refactor: extract _assets.py and _utils.py from __init__.py (PR-2/8) (#2543)
-- fix(opencode): use commands/ directory (plural) to match OpenCode docs (#2453)
-- refactor: extract _console.py from __init__.py (PR-1/8) (#2474)
-- Fix constitution reference in README (#2491)
-- chore: release 0.8.9, begin 0.8.10.dev0 development (#2532)
-
-## [0.8.9] - 2026-05-12
-
-### Changed
-
-- docs: revamp landing page with four-pillar card layout (#2531)
-- feat(extensions): update governance ecosystem extensions to latest versions (#2514)
-- Add changelog extension (#2177)
-- Add install directory to docfx.json file references (#2522)
-- feat(catalog): add BrownKit (brownkit) community extension (#2510) (#2520)
-- fix(kiro-cli): replace literal $ARGUMENTS with prose fallback (#2482)
-- Preset: Add game-narrative-writing  preset to community catalog (#2454)
-- docs: clarify CLI upgrade discovery (#2519)
-- fix: make template metadata line breaks markdownlint-safe (#2505)
-- refactor(catalogs): extract integration catalog config loading (#2497)
-- test(presets): silence expected UserWarnings in self-test composition… (#2373)
-- chore: release 0.8.8, begin 0.8.9.dev0 development (#2516)
-
-## [0.8.8] - 2026-05-11
-
-### Changed
-
-- chore(deps): bump actions/checkout from 4.3.1 to 6.0.2 (#2486)
-- feat(catalog): add Spec Kit Schedule (schedule) community extension (#2473)
-- fix(integration): refresh shared infra on `integration switch` (#2375)
-- Add MDE preset to community catalog (#2513)
-- Add MDE extension to community catalog (#2512)
-- chore: update community catalog with latest extension versions (#2490)
-- chore(deps): bump actions/setup-dotnet from 4.3.1 to 5.2.0 (#2489)
-- chore(deps): bump actions/github-script from 7 to 9 (#2488)
-- chore(deps): bump DavidAnson/markdownlint-cli2-action (#2487)
-- chore(deps): bump github/codeql-action from 4.35.3 to 4.35.4 (#2485)
-- feat(catalog): add API Evolve (api-evolve) community extension (#2479)
-- feat: Config-driven opt-in authentication registry with multi-platform support (#2393)
-- chore: release 0.8.7, begin 0.8.8.dev0 development (#2480)
-
-## [0.8.7] - 2026-05-07
-
-### Changed
-
-- feat: add agent-orchestrator to community extension catalog (#2236)
-- chore: update extension versions in community catalog (#2468)
-- fix(goose): Declare args parameter in generated recipes (#2402)
-- feat: Add lingma support (#2348)
-- docs: Add uv installation guide and inline callouts (#2465)
-- Add fx-to-dotnet to community extension catalog (#2471)
-- fix: default non-interactive init to copilot integration (#2414)
-- fix(forge): use hyphen notation for command refs in Forge integration (#2462)
-- feat(catalog): add Cost Tracker (cost) community extension (#2448)
-- chore: release 0.8.6, begin 0.8.7.dev0 development (#2463)
-
-## [0.8.6] - 2026-05-06
-
-### Changed
-
-- Load constitution context in `/speckit.implement` to enforce governance during implementation (#2460)
-- feat: improve catalog submission templates and CODEOWNERS (#2401)
-- fix: validate URL scheme in build_github_request (#2449)
-- Add Architecture Guard to community catalog (#2430)
-- Add multi-model-review extension to community catalog (#2446)
-- Update Ralph Loop to v1.0.2 (#2435)
-- Pin GitHub Actions by SHA (#2441)
-- fix(workflows): require project for catalog list (#2436)
-- Add agent-parity-governance to community catalog (#2382)
-- chore: release 0.8.5, begin 0.8.6.dev0 development (#2447)
-
-## [0.8.5] - 2026-05-04
-
-### Changed
-
-- feat(presets): add Spec2Cloud preset for Azure deployment workflow (#2413)
-- update security-review and memory-md extensions to latest versions (#2445)
-- fix: honor template overrides for tasks-template (#2278) (#2292)
-- Add token-analyzer to community catalog (#2433)
-- docs: add April 2026 newsletter (#2434)
-- feat: emit init-time notice for git extension default change (#2165) (#2432)
-- Update DyanGalih(Memory Hub and Security Review) community extensions (#2429)
-- Support controlled multi-install for safe AI agent integrations (#2389)
-- chore(integrations): clean up docs and project guard (#2428)
-- chore: release 0.8.4, begin 0.8.5.dev0 development (#2431)
-
-## [0.8.4] - 2026-05-01
-
-### Changed
-
-- fix(specify): correct self-referencing step number in validation flow (#2152)
-- chore(deps): bump DavidAnson/markdownlint-cli2-action (#2425)
-- Add security-governance to community catalog (#2386)
-- Add cross-platform-governance to community catalog (#2384)
-- Add architecture-governance to community catalog (#2383)
-- Add a11y-governance to community catalog (#2381)
-- feat(extensions): add Spec2Cloud extension for Azure deployment workflow (#2412)
-- fix: migrate extension commands on integration switch (#2404)
-- feat: add Squad Bridge extension to community catalog (#2417)
-- chore: release 0.8.3, begin 0.8.4.dev0 development (#2418)
-
-## [0.8.3] - 2026-04-29
-
-### Changed
-
-- Add Work IQ extension to community catalog (#2415)
-- feat(integrations): add Devin for Terminal skills-based integration (#2364)
-- fix: include --from git+... in upgrade hint to avoid PyPI squat package (#2411)
-- fix: dispatch opencode commands via run (#2410)
-- feat: add catalog discovery CLI commands (#2360)
-- update security review extension catalog to v1.3.0 (#2374)
-- chore(catalog): bump v-model extension to v0.6.0 (#2399)
-- feat: add threatmodel extension to community catalog (#2369)
-- Add isaqb-architecture-governance to community catalog (#2385)
-- chore: release 0.8.2, begin 0.8.3.dev0 development (#2397)
-
-## [0.8.2] - 2026-04-28
-
-### Changed
-
-- Add MarkItDown Document Converter extension to community catalog (#2390)
-- feat: Speckit preset fiction book v1.7 - Support for RAG (Chroma DB) offline semantic search (#2367)
-- fix(extensions): use explicit UTF-8 encoding when reading manifest YAML (#2370)
-- catalog: add m365 community extension
-- docs: replace deprecated --ai flag with --integration in all documentation (#2359)
-- feat(extensions,presets): authenticate GitHub-hosted catalog and download requests with GITHUB_TOKEN/GH_TOKEN (#2331)
-- Update extensify to v1.1.0 in community catalog (#2337)
-- feat(init): deprecate --no-git flag, gate deprecations at v0.10.0 (#2357)
-- Add Spec Orchestrator extension to community catalog (#2350)
-- chore: release 0.8.1, begin 0.8.2.dev0 development (#2356)
-
-## [0.8.1] - 2026-04-24
-
-### Changed
-
-- fix(plan): use .specify/feature.json to allow /speckit.plan on custom git branches (#2305) (#2349)
-- feat(vibe): migrate to SkillsIntegration from the old prompts-based MarkdownIntegration (#2336)
-- docs: move community presets table to docs site, add missing entries (#2341)
-- docs(presets): add lean preset README and enrich catalog metadata (#2340)
-- fix: resolve command references per integration type (dot vs hyphen) (#2354)
-- Update product-forge to v1.5.1 in community catalog (#2352)
-- chore(deps): bump astral-sh/setup-uv from 8.0.0 to 8.1.0 (#2345)
-- fix: replace xargs trim with sed to handle quotes in descriptions (#2351)
-- feat: register jira preset in community catalog (#2224)
-- feat: Preset screenwriting (#2332)
-- chore: release 0.8.0, begin 0.8.1.dev0 development (#2333)
-
-## [0.8.0] - 2026-04-23
-
-### Changed
-
-- feat(presets): Composition strategies (prepend, append, wrap) for templates, commands, and scripts (#2133)
-- feat(copilot): support `--integration-options="--skills"` for skills-based scaffolding (#2324)
-- docs(install): add pipx as alternative installation method (#2288)
-- Add Memory MD community extension (#2327)
-- Update version-guard to v1.2.0 (#2321)
-- fix: `--force` now overwrites shared infra files during init and upgrade (#2320)
-- chore: release 0.7.5, begin 0.7.6.dev0 development (#2322)
-
-## [0.7.5] - 2026-04-22
-
-### Changed
-
-- fix: resolve skill placeholders for all SKILL.md agents, not just codex/kimi (#2313)
-- feat(cli): add specify self check and self upgrade stub (#2316)
-- Update version-guard to v1.1.0 (#2318)
-- docs: move community presets from README to docs/community (#2314)
-- catalog: add wireframe extension (v0.1.1) (#2262)
-- Move community walkthroughs from README to docs/community (#2312)
-- docs(readme): list red-team in community-extensions table (#2311)
-- feat(catalog): add red-team extension to community catalog (#2306)
-- Add superpowers-bridge community extension (#2309)
-- feat: implement preset wrap strategy (#2189)
-- fix(agents): block directory traversal in command write paths (#2229) (#2296)
-- chore: release 0.7.4, begin 0.7.5.dev0 development (#2299)
-
-## [0.7.4] - 2026-04-21
-
-### Changed
-
-- fix(copilot): use --yolo to grant all permissions in non-interactive mode (#2298)
-- feat: add CITATION.cff and .zenodo.json for academic citation support (#2291)
-- Add spec-validate to community catalog (#2274)
-- feat: register Ripple in community catalog (#2272)
-- Add version-guard to community catalog (#2286)
-- Add spec-reference-loader to community catalog (#2285)
-- Add memory-loader to community catalog (#2284)
-- fix(integrations): strip UTF-8 BOM when reading agent context files (#2283)
-- Preset fiction book writing1.6 (#2270)
-- fix(integrations): migrate Antigravity (agy) layout to .agents/ and deprecate --skills (#2276)
-- chore: release 0.7.3, begin 0.7.4.dev0 development (#2263)
-
-## [0.7.3] - 2026-04-17
-
-### Changed
-
-- fix: replace shell-based context updates with marker-based upsert (#2259)
-- Add Community Friends page to docs site (#2261)
-- Add Spec Scope extension to community catalog (#2172)
-- docs: add Community-maintained plugin for Claude Code and GitHub Copilot CLI that installs Spec Kit skills via the plugin marketplace to README (#2250)
-- fix: suppress CRLF warnings in auto-commit.ps1 (#2258)
-- feat: register Blueprint in community catalog (#2252)
-- preset: Update preset-fiction-book-writing to community catalog -> v1.5.0 (#2256)
-- chore(deps): bump actions/upload-pages-artifact from 3 to 5 (#2251)
-- fix: add reference/*.md to docfx content glob (#2248)
-- chore: release 0.7.2, begin 0.7.3.dev0 development (#2247)
-
-## [0.7.2] - 2026-04-16
-
-### Changed
-
-- docs: add core commands reference and simplify README CLI section (#2245)
-- docs: add workflows reference, reorganize into docs/reference/, and add --version flag (#2244)
-- docs: add presets reference page and rename pack_id to preset_id (#2243)
-- docs: add extensions reference page and integrations FAQ (#2242)
-- docs: consolidate integration documentation into docs/integrations.md (#2241)
-- feat: update memorylint and superpowers-bridge versions to 1.3.0 with new download URLs (#2240)
-- feat: Integration catalog — discovery, versioning, and community distribution (#2130)
-- Add Catalog CI extension to community catalog (#2239)
-- Added issues extension (#2194)
-- chore: release 0.7.1, begin 0.7.2.dev0 development (#2235)
-
-## [0.7.1] - 2026-04-15
-
-### Changed
-
-- ci: add windows-latest to test matrix (#2233)
-- docs: remove deprecated --skip-tls references from local-development guide (#2231)
-- fix: allow Claude to chain skills for hook execution (#2227)
-- docs: merge TESTING.md into CONTRIBUTING.md, remove TESTING.md (#2228)
-- Add agent-assign extension to community catalog (#2030)
-- fix: unofficial PyPI warning (#1982) and legacy extension command name auto-correction (#2017) (#2027)
-- feat: register architect-preview in community catalog (#2214)
-- chore: deprecate --ai flag in favor of --integration on specify init (#2218)
-- chore: release 0.7.0, begin 0.7.1.dev0 development (#2217)
-
-## [0.7.0] - 2026-04-14
-
-### Changed
-
-- Add workflow engine with catalog system (#2158)
-- docs(catalog): add claude-ask-questions to community preset catalog (#2191)
-- Add SFSpeckit — Salesforce SDD Extension (#2208)
-- feat(scripts): optional single-segment branch prefix for gitflow (#2202)
-- chore: release 0.6.2, begin 0.6.3.dev0 development (#2205)
-- Add Worktrees extension to community catalog (#2207)
-- feat: Update catalog.community.json for preset-fiction-book-writing (#2199)
-
 ## [0.6.2] - 2026-04-13
 
 ### Changed

docs/installation.md

@@ -99,6 +99,23 @@ Scripts are installed into a variant subdirectory matching the chosen script typ
 - `.specify/scripts/bash/` — contains `.sh` scripts (default on Linux/macOS)
 - `.specify/scripts/powershell/` — contains `.ps1` scripts (default on Windows)
 
+### Update Notifications
+
+`specify` can check once per 24 hours whether a newer release is available on GitHub and print an upgrade hint. This is **opt-in**: the check is off by default because air-gapped and network-constrained environments cannot reach GitHub.
+
+To enable it, set:
+
+```bash
+export SPECIFY_ENABLE_UPDATE_CHECK=1   # or true / yes / on
+```
+
+Even when enabled, the check stays silent when:
+
+- stdout is not a TTY (piped output, redirected to a file, etc.)
+- the `CI` environment variable is set
+
+Network failures and rate-limit responses are swallowed — the check never fails the command you ran, though a cache miss may add a small startup delay (bounded by a 5-second fetch timeout) while contacting GitHub. Failures are also cached for the same 24h window, so a transient outage or block won't cause the CLI to retry on every invocation.
+
 ## Troubleshooting
 
 ### Enterprise / Air-Gapped Installation

src/specify_cli/__init__.py

@@ -97,6 +97,7 @@
     self_app as _self_app,
     self_check as self_check,
     self_upgrade as self_upgrade,
+    _check_for_updates,
 )
 
 def _build_agent_config() -> dict[str, dict[str, Any]]:
@@ -200,6 +201,16 @@ def callback(
         show_banner()
         console.print(Align.center("[dim]Run 'specify --help' for usage information[/dim]"))
         console.print()
+    # Addresses #1320: nudge users running outdated CLIs. The `version` subcommand
+    # already surfaces the version, so skip there to avoid double-printing; also
+    # skip help invocations. Runs on bare `specify` too so the banner launch
+    # benefits from the nudge when the user has opted in.
+    if (
+        ctx.invoked_subcommand not in {"version", "self"}
+        and "--help" not in sys.argv
+        and "-h" not in sys.argv
+    ):
+        _check_for_updates()
 
 def _refresh_shared_templates(
     project_path: Path,