Skip to content

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

Open
Open
[Feature]: Phase out first-party shell scripts while retaining extension script preferences#4884
Labels
feature-assessRun the Spec Kit idea-assessment pipeline on this feature requestfeature-goFeature assessment verdict: go — ready to hand off to /speckit.specifytriage-nice-to-haveVerdict: evidence-backed fix or greenlit feature — land after review

Description

@mnriem
mnriem
opened on Oct 8, 2026

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.

Activity

  1. mnriem
    added
    enhancement
    needs-triage
    feature-assessRun the Spec Kit idea-assessment pipeline on this feature request
    and removed
    enhancement
    needs-triage
    on Oct 8, 2026

  2. github-actions commented on Oct 8, 2026

    @github-actions
    github-actionsbot
    on Oct 8, 2026 – with GitHub Actions
    Contributor

    Feature assessment — phase-out-shell · Stage 1/5: Intake

    Idea Intake: Phase out first-party shell scripts

    Idea (as captured)

    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.

    The proposal is to deprecate first-party sh and ps implementations across successive stable releases, make Python the default for new and refreshed first-party projects, and remove first-party shell implementations in a later minor release. Existing projects should continue working until explicitly refreshed, with a safe migration that preserves customized or still-referenced shell scripts. Generic extension script selection must remain available so external extensions can continue using sh, ps, or py.

    The issue sequences six pull requests covering the execution-host contract, Python parity, deprecation, Python defaults, safe removal and migration, and documentation audit. It includes cross-platform testing, interpreter-failure handling, refresh interruption/failure behavior, preservation of customizations, and release documentation as acceptance criteria.

    Restated

    Spec Kit would consolidate first-party core and bundled-extension command implementations on Python over several releases while retaining shell variant selection for external extensions. The transition would preserve unrefreshed projects and provide an explicit, failure-safe refresh path before first-party shell implementations are removed.

    Origin & Context

    • Raised by: mnriem (issue author; collaborator)
    • Trigger: The issue identifies ongoing parity, packaging, documentation, and testing costs for maintaining three first-party script variants, and proposes a staged migration with a release window.

    First-Glance Unknowns

    • [NEEDS CLARIFICATION: Which first-party core and bundled-extension scripts and generated command paths are currently missing Python parity?]
    • [NEEDS CLARIFICATION: What exact project refresh command and compatibility boundary will govern migration of existing installations?]
    • [NEEDS CLARIFICATION: Which supported agent environments can guarantee Python 3.11+ at command execution time, and what support policy applies when it is unavailable?]
    • [NEEDS CLARIFICATION: How will customized files and installed commands be detected and preserved during refresh?]
    • [NEEDS CLARIFICATION: What release cadence and deprecation timeline define releases A, B, and C?]

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4884 · copilot · gpt52codex · 5.77 AIC · ⌖ 0.819 AIC · ⊞ 24.3K · ◷

  3. github-actions commented on Oct 8, 2026

    @github-actions
    github-actionsbot
    on Oct 8, 2026 – with GitHub Actions
    Contributor

    Feature assessment — phase-out-shell · Stage 2/5: Research

    Idea Research: Phase out first-party shell scripts

    • Slug: phase-out-shell
    • Created: 2026-10-08T14:43:41Z
    • Evidence confidence (overall): medium

    Users & Demand

    Prior Art

    • The repository already contains parallel core Bash, PowerShell, and Python script trees, with six files in each tree at inspection time — [source: scripts/bash, scripts/powershell, scripts/python] (confidence: high, cited).
    • The bundled Git extension also maintains four files in each of its Bash, PowerShell, and Python trees, and the repository has parity tests comparing variants — [source: extensions/git/scripts/*, tests/extensions/git/test_git_extension_python_parity.py] (confidence: high, cited).
    • Core parity coverage is explicit for prerequisite checking and template resolution, including composed content, missing templates, Unicode, and shell/Python output parity — [source: tests/test_check_prerequisites_python_parity.py, tests/test_resolve_template_python_parity.py] (confidence: high, cited).
    • The current integration contract accepts sh, ps, and py; tests exercise script selection and non-interactive initialization — [source: src/specify_cli/command_init.py, tests/integrations/test_cli.py, tests/integrations/test_integration_generic.py] (confidence: high, cited).
    • Upgrade documentation currently separates CLI upgrade from project-file refresh and says manifest-aware upgrades preserve source, specifications, and customized managed files unless forced — [source: docs/upgrade.md] (confidence: high, cited).

    Market & Context

    • Current user-facing documentation says Bash, PowerShell, and Python automation scripts are available; defaults are platform-dependent and --script can force a variant — [source: docs/installation.md] (confidence: high, cited).
    • The proposed change has a real compatibility cost because command files and extension commands refer to concrete shell paths today; examples in the Git extension documentation explicitly invoke Bash and PowerShell scripts — [source: extensions/git/commands/*.md, extensions/git/README.md] (confidence: high, cited).
    • The cost of doing nothing is asserted by the issue as continued parity maintenance, but no repository metric quantifies that cost — [source: [Feature]: Phase out first-party shell scripts while retaining extension script preferences #4884] (confidence: medium, cited; magnitude unverified).
    • External extensions are a distinct compatibility boundary: the issue explicitly keeps generic extension selection and external shell-only extensions in scope as preserved behavior — [source: [Feature]: Phase out first-party shell scripts while retaining extension script preferences #4884] (confidence: medium, cited).

    Data & Constraints

    • Specify CLI installation documents Python 3.11+ as a prerequisite, while the issue distinguishes local CLI installation from Python availability on the agent execution machine — [source: docs/installation.md, [Feature]: Phase out first-party shell scripts while retaining extension script preferences #4884] (confidence: high, cited).
    • Existing projects can contain installed command and script copies, and the upgrade guide uses manifests to detect modified files and avoid overwriting customized managed files unless forced — [source: docs/upgrade.md, src/specify_cli/shared_infra.py] (confidence: high, cited).
    • The acceptance criteria require cross-platform coverage, relocated projects, missing/changed virtual environments, interrupted or failed refreshes, and no remaining command references to deleted scripts — [source: [Feature]: Phase out first-party shell scripts while retaining extension script preferences #4884] (confidence: medium, cited).
    • The repository already has tests for path safety, shared infrastructure integrity, script parity, and generated-command behavior; the scope of coverage after a migration is not yet established — [source: tests/test_check_prerequisites_paths_only.py, tests/test_shared_infra_integrity.py, parity tests] (confidence: high, cited).

    Evidence Against the Idea

    • Removing first-party shell implementations can break existing or customized command references if refresh ordering and reference detection are incomplete — [source: current concrete shell-path documentation and [Feature]: Phase out first-party shell scripts while retaining extension script preferences #4884 acceptance criteria] (confidence: high, cited).
    • Python availability on the execution host is not guaranteed merely because the CLI was installed elsewhere, creating a reliability and support risk during migration — [source: [Feature]: Phase out first-party shell scripts while retaining extension script preferences #4884; docs/installation.md] (confidence: high, cited).
    • A large staged migration may impose release, documentation, and test burden that could outweigh parity savings if the current maintenance cost is smaller than asserted — [NEEDS CLARIFICATION: measured maintenance cost and migration adoption] (confidence: low, assumption).
    • The repository evidence shows Python parity is substantial but not proof of complete parity across every bundled command or extension path — [NEEDS CLARIFICATION: complete inventory and parity result] (confidence: medium, assumption).

    Gaps & Open Questions

    • [NEEDS CLARIFICATION: Complete inventory of first-party and bundled-extension scripts, commands, templates, package assets, and direct shell references.]
    • [NEEDS CLARIFICATION: Quantified maintenance cost, defect rate, and user impact of keeping three first-party variants.]
    • [NEEDS CLARIFICATION: Supported execution-host matrix and policy when Python 3.11+ is unavailable.]
    • [NEEDS CLARIFICATION: Exact refresh mechanism, customization detection rules, rollback guarantees, and release timeline.]
    • [NEEDS CLARIFICATION: Evidence from users or telemetry about shell variant usage, especially external extensions.]

    Sources

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4884 · copilot · gpt52codex · 5.77 AIC · ⌖ 0.819 AIC · ⊞ 24.3K · ◷

  4. github-actions commented on Oct 8, 2026

    @github-actions
    github-actionsbot
    on Oct 8, 2026 – with GitHub Actions
    Contributor

    Feature assessment — phase-out-shell · Stage 3/5: Problem

    Problem Definition: First-party script variant parity

    • Slug: phase-out-shell
    • Created: 2026-10-08T14:43:41Z
    • Inputs used: intake.md and research.md

    Problem Statement

    Spec Kit maintainers must keep first-party core and bundled-extension automation behavior aligned across Bash, PowerShell, and Python, while users run generated commands on execution machines whose Python availability may differ from the machine where the CLI was installed. This creates ongoing maintenance cost and a migration reliability risk for existing projects, especially when installed or customized commands refer to concrete script paths.

    Affected Users & Stakeholders

    Goals

    • Reduce the long-term first-party parity surface without breaking supported external extension variant selection.
    • Make the execution-host prerequisite for first-party commands explicit and actionable.
    • Preserve usability of existing projects through a documented, reliable transition.
    • Ensure project refreshes do not leave installed or customized commands pointing at missing scripts.
    • Establish measurable evidence that first-party behavior remains equivalent across supported environments during the transition.

    Non-Goals

    • Removing Bash or PowerShell support from external extensions.
    • Changing the meaning or availability of specify init --script sh|ps|py for extension selection.
    • Requiring an immediate migration of every existing project.
    • Redesigning unrelated CLI, integration, or extension behavior.

    Success Metrics

    • 100% of inventoried first-party core and bundled-extension command paths have a tested Python implementation before first-party shell removal (baseline: inventory and coverage are unknown).
    • 0 known generated-command references to removed first-party shell scripts after a successful refresh (baseline: current references exist in docs and command assets).
    • Existing projects that are not refreshed continue to execute their installed commands through the deprecation period (baseline: not yet measured).
    • Refresh failures and interruptions leave no command references to missing replacement scripts and report an actionable error (baseline: behavior not yet measured).
    • External extension tests pass for all three saved script preferences after each migration release (baseline: current selection is supported; complete extension coverage is unknown).
    • Documentation accurately distinguishes CLI installation Python requirements from execution-host requirements in the release sequence (baseline: installation documents Python 3.11+ but the proposed distinction is not yet fully documented).

    Cost of Inaction

    Without a change, maintainers continue updating and testing parallel first-party implementations and their packaging and documentation, while users remain exposed to platform-specific defaults and possible differences between CLI installation and command execution environments. The magnitude of maintenance cost, defect frequency, and user impact is not quantified, so the benefit of change remains uncertain.

    Open Questions

    • [NEEDS CLARIFICATION: What is the complete first-party and bundled-extension script/reference inventory, and what Python parity gaps remain?]
    • [NEEDS CLARIFICATION: Which execution hosts and Python discovery paths are supported, and what happens when Python 3.11+ is unavailable?]
    • [NEEDS CLARIFICATION: What exact refresh operation, customization detection, rollback behavior, and release timeline will be supported?]
    • [NEEDS CLARIFICATION: What observed usage or failure data validates the demand and prioritizes external-extension compatibility?]
    • [NEEDS CLARIFICATION: Which release or maintenance owners approve deprecation, default changes, and removal?]

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4884 · copilot · gpt52codex · 5.77 AIC · ⌖ 0.819 AIC · ⊞ 24.3K · ◷

  5. github-actions commented on Oct 8, 2026

    @github-actions
    github-actionsbot
    on Oct 8, 2026 – with GitHub Actions
    Contributor

    Feature assessment — phase-out-shell · Stage 4/5: Concept

    Concept: Phase out first-party shell scripts

    • Slug: phase-out-shell
    • Created: 2026-10-08T14:43:41Z
    • Recommended option: Staged Python transition with compatibility window

    Options

    Option A — Staged Python transition with compatibility window

    • Sketch: Establish and publish the execution-host contract, complete and verify Python parity, announce deprecation, make Python the default for new and refreshed first-party projects, then remove first-party shell assets only after a later release window. Existing projects remain usable until refresh, and refresh messaging makes the migration boundary explicit while preserving external extension preferences.
    • Appetite: large
    • Trade-offs: Best alignment with the issue's compatibility, migration, and external-extension goals; supports measurable parity and reference-safety gates. It requires several releases, broad inventory work, cross-platform testing, careful refresh behavior, and sustained documentation effort. The maintenance savings arrive later.
    • Rabbit holes: Incomplete shell-reference discovery, customized-file detection, interrupted refresh rollback, ambiguous Python discovery on remote hosts, and documentation drift across integrations and bundled extensions.

    Option B — Python-first for new projects, retain shell indefinitely for existing projects

    • Sketch: Use Python for new first-party projects and make the execution requirement clear, but keep shipping and supporting first-party Bash and PowerShell implementations for existing projects without a removal deadline. External extension selection remains unchanged.
    • Appetite: medium
    • Trade-offs: Reduces future shell usage and migration risk while avoiding destructive refresh behavior and preserving maximum backwards compatibility. It does not eliminate the three-way parity and packaging burden, and it leaves long-term maintenance cost largely intact.
    • Rabbit holes: Two support policies may diverge, “new” versus “existing” project detection may become confusing, and documentation may need to explain indefinite dual behavior.

    Option C — No first-party consolidation; invest only in parity and diagnostics

    • Sketch: Keep all three first-party variants and focus on automated parity checks, clearer interpreter diagnostics, and documentation of current defaults and requirements. Do not change the release or refresh compatibility model.
    • Appetite: small
    • Trade-offs: Lowest migration risk and fastest improvement to current reliability signals. It preserves the current maintenance surface and does not address the stated strategic goal of reducing first-party parity work.
    • Rabbit holes: Better diagnostics may expose more environment-specific cases without reducing the number of implementations, and parity tests may become a substitute for deciding whether the maintenance model is sustainable.

    Recommendation

    Recommend Option A only if specification work first confirms the complete script/reference inventory, execution-host support policy, and a safe refresh/rollback boundary. It is the only option that directly targets the stated parity cost while honoring the acceptance criteria for unrefreshed projects and external extensions. Because demand and maintenance savings are not quantified, the recommendation is conditional rather than evidence of a ready-to-implement commitment; Option B is the safer fallback if migration safety or usage data cannot be established.

    Out of Scope (for the recommended option)

    • Removing Bash or PowerShell support from external extensions.
    • Changing the meaning or availability of specify init --script sh|ps|py for extension selection.
    • Immediate forced migration of all existing projects.
    • Detailed architecture, command/API design, data models, implementation tasks, or unrelated CLI redesign.
    • Proceeding to shell removal without complete parity evidence, reference-safety checks, and an actionable Python execution-host policy.

    Assumptions to Validate

    • Python implementations can reach behavioral parity for every first-party core and bundled-extension command that will survive the transition.
    • Supported execution hosts can provide or reliably locate Python 3.11+, or the project can define a supported failure path.
    • Existing-project refresh can distinguish managed files from customized or still-referenced files without silently breaking commands.
    • A staged release window is acceptable to maintainers and users, and documentation can reach affected projects.
    • External extensions can retain their saved script preference independently of first-party defaults.
    • The maintenance cost and defect risk are material enough to justify a large, multi-release migration.

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4884 · copilot · gpt52codex · 5.77 AIC · ⌖ 0.819 AIC · ⊞ 24.3K · ◷

  6. github-actions commented on Oct 8, 2026

    @github-actions
    github-actionsbot
    on Oct 8, 2026 – with GitHub Actions
    Contributor

    Feature assessment — phase-out-shell · Stage 5/5: Decision — verdict needs-clarification

    Decision: Phase out first-party shell scripts

    • Slug: phase-out-shell
    • Decided: 2026-10-08T14:43:41Z
    • Verdict: needs-clarification
    • Artifacts reviewed: intake.md, research.md, problem.md, concept.md

    Scorecard

    Criterion Rating Justification
    Problem validity adequate The repository clearly contains parallel core and extension variants and parity tests, and the issue identifies a concrete maintenance and execution-host problem; the user impact and defect frequency are not quantified.
    Evidence strength weak Repository structure and documentation support the existence of the parity surface, but there is no measured maintenance cost, usage data, failure data, complete parity inventory, or external user signal beyond the issue's stated use cases.
    Value vs. inaction adequate Consolidation could reduce long-term parity work and clarify execution requirements, while inaction preserves known maintenance burden; the relative value is uncertain without cost and usage measurements.
    Feasibility / appetite adequate A staged multi-release option is conceptually credible and a smaller fallback exists, but refresh safety, rollback, interpreter discovery, and reference detection remain unvalidated.
    Strategic fit adequate The proposal aligns with reducing first-party duplication while explicitly preserving external extension compatibility, consistent with the issue and current CLI surfaces; formal project-goal evidence was not identified.
    Risk posture weak The major compatibility risks are identified, but no evidence yet shows that customized references, interrupted refreshes, missing Python, or all bundled paths can be handled safely.

    Verdict & Rationale

    Needs clarification. The problem is plausible and a staged concept is shaped, but the evidence threshold for a go verdict is not met: evidence strength is weak, and the highest-impact migration risks are unvalidated. The request should return to research and then shape/define once the complete script/reference inventory, observed usage and maintenance impact, execution-host policy, and refresh safety guarantees are established. This is preferable to committing to a large multi-release migration on maintainer assertion alone.

    If needs-clarification

    • Blocking questions:
      • [NEEDS CLARIFICATION: What is the complete inventory of first-party core and bundled-extension scripts, generated command references, package assets, and direct shell invocations, and where are Python parity gaps?]
      • [NEEDS CLARIFICATION: What observed usage, support incidents, or telemetry demonstrate the demand and quantify shell-variant impact?]
      • [NEEDS CLARIFICATION: What maintenance cost, defect rate, and expected savings justify a large multi-release migration?]
      • [NEEDS CLARIFICATION: Which execution hosts and Python discovery rules are supported, and what is the user-facing failure policy when Python 3.11+ is unavailable?]
      • [NEEDS CLARIFICATION: What exact refresh operation detects customizations and remaining references, installs replacements safely, rolls back or reports interruption/failure, and preserves unrefreshed projects?]
      • [NEEDS CLARIFICATION: What release owners and timeline govern deprecation, default changes, and removal?]
        +- Revisit stage: research, then define and shape if the new evidence changes the problem boundary or viable option.

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4884 · copilot · gpt52codex · 5.77 AIC · ⌖ 0.819 AIC · ⊞ 24.3K · ◷

  7. github-actions
    added
    feature-needs-clarificationFeature assessment verdict: needs clarification
    on Oct 8, 2026
  8. mnriem
    added
    feature-goFeature assessment verdict: go — ready to hand off to /speckit.specify
    and removed
    feature-needs-clarificationFeature assessment verdict: needs clarification
    on Oct 8, 2026

  9. mnriem commented on Oct 8, 2026

    @mnriem
    mnriem
    on Oct 8, 2026
    CollaboratorAuthor

    As we want to lower the maintenance burden we are going ahead with this

  10. mnriem
    added
    triage-nice-to-haveVerdict: evidence-backed fix or greenlit feature — land after review
    on Oct 8, 2026

  11. cacl-dis commented on Oct 8, 2026

    @cacl-dis
    cacl-dis
    on Oct 8, 2026

    A data point for PR 1 (execution-host contract)

    With a preset installed, template resolution parses preset.yml with whatever Python the command runs on. That is true in all three variants (common.sh, Get-Python3Command in common.ps1, and scripts/python/common.py). If that Python cannot import yaml, every resolving command fails with:

    PyYAML is required to resolve preset template composition

    specify-cli declares pyyaml>=6.0, so the CLI's own environment always has it. The Python on PATH may or may not. On macOS with Homebrew Python 3.14 and uv tool install specify-cli (1.0.10):

    ~/.local/share/uv/tools/specify-cli/bin/python3 -c "import yaml" succeeds (6.0.3).
    /opt/homebrew/bin/python3 -c "import yaml" fails.

    The workarounds people reach for are all fragile:

    • pip install --user hits PEP 668 (externally-managed-environment) on Homebrew and Debian, and the common next step is --break-system-packages.
    • A user-site install is tied to one Python minor version, so the next Python upgrade removes it and the error comes back.
    • Activating a venv does not help, because the agent's shell (desktop app, IDE) never sees the activation.

    We currently work around it with a dedicated uv venv, put first on PATH in .zshrc and .bashrc to accommodate different agent and user preferences.

    Two suggestions for PR 1:

    1. Interpreter resolution prefers the CLI's own interpreter when it is on the same machine, and falls back to PATH only when it is not. This keeps the remote-agent case from this issue working, and it removes the problem for the common local case. One option is to record sys.executable at specify init / preset add time.
    2. Either list PyYAML in the execution-host contract or remove the need for it. For example, specify preset add could write a JSON copy of the resolved manifest that the scripts read with the standard library. That would make "Python 3.11+" the whole requirement, as the issue currently states it.
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

    feature-assessRun the Spec Kit idea-assessment pipeline on this feature requestfeature-goFeature assessment verdict: go — ready to hand off to /speckit.specifytriage-nice-to-haveVerdict: evidence-backed fix or greenlit feature — land after review

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions