feat(scripts): port create-new-feature, setup-plan and setup-tasks to Python by marcelsafin · Pull Request #3386 · github/spec-kit

marcelsafin · 2026-07-06T23:55:03Z

Description

Ports the three core workflow scripts to Python, per #3280. Follows the pattern established by the check-prerequisites PoC (#3302): additive port with parity tests that run the bash and Python versions side by side and compare output. Two small non-additive touches: templates/commands/plan.md and templates/commands/tasks.md gain a scripts.py entry, and resolve_skill_placeholders accepts py as a script variant (with interpreter prefixing and a fallback when a command's frontmatter lacks the configured variant).

Scope:

scripts/python/create_new_feature.py — port of create-new-feature.sh, including branch-name generation (stop words, acronym detection, word limits), feature numbering (specs scan + timestamp-dir handling), the 244-char ref-length truncation, --allow-existing-branch mode, and feature.json persistence (byte-identical to the jq output).
scripts/python/setup_plan.py — port of setup-plan.sh, including plan template resolution and the status messages that go to stderr in --json mode.
scripts/python/setup_tasks.py — port of setup-tasks.sh, including plan/spec validation and the tasks-template requirement.
scripts/python/common.py — adds resolve_template() (overrides → presets via registry → extensions → core), shared by the three scripts above.
src/specify_cli/integrations/base.py and shared_infra.py — add py template selection, interpreter prefixing, frontmatter-bounded script extraction, and Python-plus-platform-shell fallback installation.
Existing Bash/PowerShell create-feature twins — align Int64 validation, warnings/errors, and platform-appropriate persistence output with the Python port.
tests/parity_helpers.py — shared fixtures/helpers for parity tests, extracted from the pattern in test_check_prerequisites_python_parity.py.
Three-way parity tests cover JSON/text output, all flags, numeric boundaries, failure diagnostics, and non-dry persistence output.

Testing

Tested locally with uv run specify --help
Full suite with PowerShell: 4189 passed, 4 skipped
Create-feature parity/integration suites: 109 passed
Cross-script parity suites: 84 passed

AI Disclosure

I did not use AI assistance for this contribution
I did use AI assistance (describe below)

Ported and tested with GitHub Copilot CLI. I reviewed the diff and verified parity behavior manually.

Fixes #3280

… Python Ports the three core workflow scripts to Python as part of github#3280, following the check-prerequisites PoC pattern from github#3302. Adds resolve_template() to the shared common.py module and parity tests that run bash and Python side by side. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Ports three core Spec Kit workflow scripts (create-new-feature, setup-plan, setup-tasks) to Python while preserving the existing shell implementations, and adds parity tests to ensure the Python ports match Bash/PowerShell output and exit behavior.

Changes:

Added Python implementations for create-new-feature, setup-plan, and setup-tasks, plus shared resolve_template() logic in scripts/python/common.py.
Added shared parity-test utilities (tests/parity_helpers.py) to run Bash/PowerShell/Python twins in temporary repos with normalized output comparisons.
Added parity test suites for the three newly-ported scripts, including JSON/text output parity and PowerShell JSON parity where available.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_setup_tasks_python_parity.py	Adds Bash/Python + PowerShell/Python parity tests for `setup-tasks`.
tests/test_setup_plan_python_parity.py	Adds Bash/Python + PowerShell/Python parity tests for `setup-plan`.
tests/test_create_new_feature_python_parity.py	Adds parity tests for `create-new-feature` including numbering, truncation, errors, and persistence.
tests/parity_helpers.py	Introduces reusable helpers for parity tests (repo scaffolding, command builders, normalization, subprocess runner).
scripts/python/setup_tasks.py	Python port of `setup-tasks` including prereq checks + template resolution and JSON/text output.
scripts/python/setup_plan.py	Python port of `setup-plan` including template copy behavior and JSON-mode stderr status messages.
scripts/python/create_new_feature.py	Python port of `create-new-feature` including naming rules, numbering/timestamp modes, truncation, and feature.json persistence.
scripts/python/common.py	Adds `resolve_template()` and preset ordering helper to mirror Bash template resolution priority.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Review details

Files reviewed: 8/8 changed files
Comments generated: 1
Review effort level: Low

… hidden preset dirs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Ships with the scripts they reference; the remaining templates got their py: lines in github#3403. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

resolve_skill_placeholders only accepted sh/ps, so a py init option fell into the fallback path and {SCRIPT} rendered without an interpreter prefix. Accept py and prefix the resolved interpreter, matching process_template. Also guard ps_cmd against a missing PowerShell with a clear assert. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Copilot

Review details

Files reviewed: 12/12 changed files
Comments generated: 1
Review effort level: Low

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

marcelsafin · 2026-07-17T17:18:39Z

@copilot review

Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

src/specify_cli/agents.py:495

The fallback can select a variant that --script py did not install. For example, on Windows a command exposing only sh (a supported extension-command shape) reaches the secondary fallback here, but shared_infra.py:406-410 installs only python plus powershell; after path rewriting the generated command points to a missing .specify/scripts/bash/... file. Restrict fallback selection to variants guaranteed to be installed, or install whichever fallback is selected, and cover one-sided frontmatter on the opposite platform.

            default_variant = (
                "ps" if platform.system().lower().startswith("win") else "sh"
            )
            secondary_variant = "sh" if default_variant == "ps" else "ps"

            if default_variant in scripts:
                fallback_order.append(default_variant)
            if secondary_variant in scripts:
                fallback_order.append(secondary_variant)

            for key in scripts:
                if key not in fallback_order:
                    fallback_order.append(key)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

marcelsafin · 2026-07-17T17:32:07Z

@copilot review

Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

marcelsafin · 2026-07-17T17:45:35Z

@copilot review

Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

marcelsafin · 2026-07-17T17:58:37Z

@copilot review

Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

marcelsafin · 2026-07-17T18:08:26Z

@copilot review

Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

src/specify_cli/agents.py:486

Skills use the same opposite-shell fallback, so a Windows py project with only an sh entry receives a bare .sh invocation that PowerShell cannot execute merely because the file was installed. Limit fallback to a runnable platform variant or surface a clear unsupported-variant error.

            fallback_order = []
            default_variant = (
                "ps" if platform.system().lower().startswith("win") else "sh"
            )
            secondary_variant = "sh" if default_variant == "ps" else "ps"

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

marcelsafin · 2026-07-17T18:40:02Z

@copilot review

Copilot

Pull request overview

Copilot reviewed 27 out of 27 changed files in this pull request and generated no new comments.

marcelsafin · 2026-07-17T18:45:59Z

@mnriem Copilot’s current-head review on 158a773 generated no new comments, all review threads are resolved, and the full suite passes (4189 passed, 4 skipped). Ready for re-review.

Copilot

Review details

Files reviewed: 27/27 changed files
Comments generated: 0 new
Review effort level: Medium

mnriem · 2026-07-17T19:09:46Z

@marcelsafin Please address test & lint errors

marcelsafin requested a review from mnriem as a code owner July 6, 2026 23:55

Copilot AI review requested due to automatic review settings July 6, 2026 23:55

Copilot started reviewing on behalf of marcelsafin July 6, 2026 23:55 View session

Copilot AI reviewed Jul 6, 2026

View reviewed changes

Comment thread tests/parity_helpers.py

fix(tests): treat only None env as unset in parity run helper

83a5dca

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

mnriem requested a review from Copilot July 7, 2026 18:18

Copilot started reviewing on behalf of mnriem July 7, 2026 18:23 View session

Copilot AI reviewed Jul 7, 2026

View reviewed changes

Comment thread scripts/python/common.py

fix(scripts): fall back to directory scan on any registry error, skip…

d4e4c5e

… hidden preset dirs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

This was referenced Jul 7, 2026

Port git extension scripts to Python #3282

Closed

Add py: lines to command templates' scripts: frontmatter #3283

Closed

feat(templates): add py: lines to command templates' scripts frontmatter #3403

Merged

feat(templates): add py: lines for setup_plan and setup_tasks

9817517

Ships with the scripts they reference; the remaining templates got their py: lines in github#3403. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 8, 2026 06:59

Copilot started reviewing on behalf of marcelsafin July 8, 2026 06:59 View session

Copilot AI reviewed Jul 8, 2026

View reviewed changes

Comment thread tests/parity_helpers.py

Comment thread templates/commands/plan.md

Comment thread templates/commands/tasks.md

Copilot AI review requested due to automatic review settings July 8, 2026 07:09

Copilot started reviewing on behalf of marcelsafin July 8, 2026 07:09 View session

Copilot AI reviewed Jul 8, 2026

View reviewed changes

Comment thread tests/test_create_new_feature_python_parity.py

test: pin clean-error behavior for invalid --number

e223c98

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 8, 2026 07:15

Copilot started reviewing on behalf of marcelsafin July 8, 2026 07:16 View session

Copilot AI reviewed Jul 8, 2026

View reviewed changes

Comment thread templates/commands/plan.md

Comment thread templates/commands/tasks.md

mnriem requested a review from Copilot July 8, 2026 14:43

Copilot started reviewing on behalf of mnriem July 8, 2026 14:44 View session

Copilot AI reviewed Jul 8, 2026

View reviewed changes

Comment thread scripts/python/create_new_feature.py

mnriem requested a review from Copilot July 9, 2026 18:04

Copilot started reviewing on behalf of mnriem July 9, 2026 18:04 View session

fix(scripts): close parity edge cases

0fdf575

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 17, 2026 17:18

Copilot started reviewing on behalf of marcelsafin July 17, 2026 17:18 View session

Copilot AI reviewed Jul 17, 2026

View reviewed changes

Comment thread scripts/powershell/common.ps1

Comment thread tests/test_setup_tasks_python_parity.py

fix(scripts): propagate PowerShell setup errors

26dc9e3

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 17, 2026 17:31

Copilot started reviewing on behalf of marcelsafin July 17, 2026 17:32 View session

Copilot AI reviewed Jul 17, 2026

View reviewed changes

Comment thread scripts/powershell/common.ps1

Comment thread tests/test_setup_plan_python_parity.py Outdated

fix(scripts): harden fallback resolution

21e252c

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 17, 2026 17:45

Copilot started reviewing on behalf of marcelsafin July 17, 2026 17:45 View session

Copilot AI reviewed Jul 17, 2026

View reviewed changes

Comment thread scripts/powershell/common.ps1 Outdated

Comment thread scripts/powershell/common.ps1

Comment thread tests/test_create_new_feature_python_parity.py Outdated

fix(scripts): stabilize PowerShell fallbacks

c6fb0c7

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 17, 2026 17:58

Copilot started reviewing on behalf of marcelsafin July 17, 2026 17:58 View session

Copilot AI reviewed Jul 17, 2026

View reviewed changes

Comment thread scripts/powershell/setup-plan.ps1

Comment thread src/specify_cli/__init__.py

fix(scripts): complete setup-plan parity

f9a96ea

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 17, 2026 18:08

Copilot AI reviewed Jul 17, 2026

View reviewed changes

Comment thread src/specify_cli/integrations/base.py Outdated

Comment thread src/specify_cli/__init__.py Outdated

fix(cli): require runnable script fallbacks

158a773

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI reviewed Jul 17, 2026

View reviewed changes

Uh oh!

Conversation

marcelsafin commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing

AI Disclosure

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Uh oh!

marcelsafin commented Jul 17, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

marcelsafin commented Jul 17, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

marcelsafin commented Jul 17, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marcelsafin commented Jul 17, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

marcelsafin commented Jul 17, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

marcelsafin commented Jul 6, 2026 •

edited

Loading