[Feature]: Phase out first-party shell scripts while retaining extension script preferences

This is a multi-release deprecation plan, not a single change; no one should start by editing code. Read src/specify_cli/command_init.py (script choice handling), src/specify_cli/integrations/base.py (command variant selection) and src/specify_cli/shared_infra.py (which core scripts get installed), then docs/upgrade.md. Done means the design is agreed and the first sequenced PR (the execution-host contract) is scoped by a maintainer.

Problem Statement

Spec Kit maintains Bash (sh), PowerShell (ps), and Python (py) implementations of core scripts and scripts shipped with bundled extensions. Keeping these first-party implementations in parity adds maintenance, packaging, documentation, and testing work.

Specify CLI requires Python 3.11+, but installing the CLI does not guarantee Python is available where an agent later executes generated commands. Python-backed first-party commands require Python 3.11+ installed and invokable on the agent’s execution machine.

Existing projects contain generated commands and installed script copies. Updating the CLI must not silently rewrite or break those files. A project should move to Python-backed first-party commands when it is explicitly refreshed or rescaffolded, through a safe migration.

This proposal does not remove Bash or PowerShell support for external extensions. specify init --script sh|ps|py remains available; its saved value continues to signal the project’s preferred extension script variant.

Proposed Solution

Deprecate first-party sh and ps implementations across successive stable releases, then remove them in a later minor release. Keep generic extension variant selection. Track the work through these sequenced PRs, adding links and shipped versions to this issue as they land:

• PR 1 — Establish the execution-host contract. Document when Python 3.11+ is required where an agent executes first-party commands. Test interpreter resolution on Windows, macOS, and Linux, including relocated projects, isolated CLI installations, and changed or missing virtualenvs. Make failures actionable. The CLI must validate installed preset YAML and generate a small JSON representation of the template-resolution fields for project scripts to read with the Python standard library, so the agent execution environment does not need PyYAML. Preserve the behavior of unrefreshed projects. See the execution-host report.
• PR 2 — Complete first-party Python parity. Inventory all core and bundled-extension commands, including direct shell-script references. Close Python coverage gaps and test generated commands and packaged assets. Verify external extension behavior with each saved --script value.
• PR 3 — Announce deprecation. Publish scope, prerequisites, timing, and migration instructions. Warn when a choice causes a first-party shell implementation to be used—not merely because an external extension prefers one. Preserve current defaults and functionality. Ship as deprecation release A.
• PR 4 — Make Python the default for new first-party projects. Update init, bundle init, workflow init, and integration paths consistently. Continue supporting existing and explicitly selected first-party shell implementations during the notice period. Keep accepting and persisting --script sh|ps|py for extensions. Ship in a subsequent stable release B.
• PR 5 — Remove first-party shell implementations and migrate safely. Remove core and bundled-extension sh/ps scripts, template entries, and package assets from the distribution. New and refreshed projects must install and invoke their Python implementations regardless of the saved --script value. Leave unrefreshed projects’ installed commands and scripts usable. During refresh, install working Python scripts before replacing command invocations; do not delete an installed shell script while a remaining or customized command references it. Test successful, interrupted, and failed refreshes so a failure is reported without leaving broken command references. Retain shell support for external extensions and include release-critical migration documentation.
• PR 6 — Audit remaining documentation. After PR 5 merges, correct remaining first-party shell defaults, examples, and references across guides, reference pages, and bundled-extension docs. Preserve accurate documentation for external shell extensions. This focused audit does not defer documentation needed in PRs 1–5.

Release sequence: Ship PRs 5 and 6 in a later minor release C, after releases A and B. Keep this issue open until that release is complete.

Alternatives Considered

Maintaining three first-party variants indefinitely retains parity costs. Removing them immediately gives users no migration window. Removing sh and ps globally would break external extensions and is out of scope.

Component

Specify CLI (initialization, commands)

AI Agent (if applicable)

All agents

Use Cases

A team installs Python on a remote agent machine even though Specify CLI was installed locally. An existing project upgrades the CLI and continues using its installed shell-backed commands until the project is refreshed. A project selects --script ps for an external extension while its refreshed core commands use Python.

Acceptance Criteria

• Documentation distinguishes Python required to install the CLI from Python required on the agent execution machine, and explains which first-party commands need it during migration.
• New and explicitly refreshed projects resolve installed preset templates with Python 3.11+ even when that interpreter cannot import PyYAML. Preset installation and update generate the validated JSON projection; removal cleans it up. Missing or stale generated data produces actionable refresh guidance rather than silently using outdated data, without requiring a new YAML parser or installing packages into the project. Unrefreshed projects retain their existing behavior.
• Cross-platform tests cover new and upgraded projects, relocated projects, interpreter failures, and generated commands.
• Upgrading the CLI without refreshing a project does not rewrite or break that project’s installed commands and scripts.
• Existing first-party sh/ps projects remain functional throughout the deprecation releases and have a documented refresh path.
• After removal, new and refreshed projects install and invoke first-party Python scripts with each of --script sh, ps, and py.
• Refresh installs replacement scripts before switching command references, retains shell scripts still referenced by installed or customized commands, and reports failures without leaving commands pointing to missing scripts.
• specify init --script sh|ps|py remains available and persists the extension preference; external extensions, including shell-only ones, continue to work.
• Refresh preserves customized files unless the user explicitly chooses an overwriting option.
• docs/upgrade.md and release notes describe the minor-release migration accurately. Each PR updates documentation for its own behavior; the final audit leaves no outdated first-party shell instructions.
• Regression coverage is added without reducing total test collection.

Additional Context

src/specify_cli/command_init.py accepts and persists the script choice; src/specify_cli/integrations/base.py selects command variants; and src/specify_cli/shared_infra.py determines which core scripts are installed. Extension command and event paths use the saved preference. docs/installation.md documents current defaults, and docs/upgrade.md describes project upgrades.

AI Disclosure

Drafted with GitHub Copilot, powered by GPT-6 Sol, in an interactive human-supervised session (reasoning-effort setting not specified). Assistance covered repository inspection and issue drafting. No code was changed, and no PR was filed. A subsequent Copilot-assisted update incorporated the preset execution-host requirement and the reporter’s observation.