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.
tests/parity_helpers.py — shared fixtures/helpers for parity tests, extracted from the pattern in test_check_prerequisites_python_parity.py.
25 parity tests across three files: exact JSON equality against bash, normalized text output, PowerShell JSON parity (skipped when pwsh is unavailable).

One deliberate deviation: --number abc produces a clean error message in Python where bash surfaces a raw arithmetic error (10#abc: value too great for base). The parity test asserts exit code and empty stdout for that case, not the stderr text.

Testing

Tested locally with uv run specify --help
Ran existing tests with uv sync && uv run pytest (3801 passed, 110 skipped)
Manual side-by-side runs of bash vs Python on a sample repo (23 cases: numbering, stop words, acronyms, truncation, collision handling, JSON/text modes)

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

Copilot

Review details

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

The loop accepts and silently ignores extra positional args (it doesn't build a collected list); match the wording to what the code and setup-plan.sh actually do. 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 no new comments.

Copilot

Review details

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

…tter 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.

Comments suppressed due to low confidence (1)

src/specify_cli/agents.py:418

When a Python-configured project encounters a command without a py entry, this fallback selects sh (or ps on Windows). Shared infra installs only the selected script variant, so a script=py project does not contain .specify/scripts/bash/powershell; commands such as clarify.md, which currently has only sh/ps, therefore resolve {SCRIPT} to a path that does not exist. Please ensure those commands provide/use their installed Python twin, or install the chosen fallback variant rather than merely replacing the placeholder.

        if script_variant not in {"sh", "ps", "py"} or script_variant not in scripts:
            fallback_order = []
            default_variant = (
                "ps" if platform.system().lower().startswith("win") else "sh"
            )

…10# parity The bash twin uses $((10#$BRANCH_NUMBER)), which rejects signed and whitespace-padded values. Python's int() accepted them (e.g. -1), producing a malformed -01-... prefix that sequential scans ignore. Restrict --number to unsigned decimal digits before conversion, and pin the parity with a bash-comparison test. 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 no new comments.

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

Open

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

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread scripts/python/setup_plan.py Outdated

Copilot AI review requested due to automatic review settings July 10, 2026 05:55

Copilot started reviewing on behalf of marcelsafin July 10, 2026 05:55 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

mnriem requested a review from Copilot July 10, 2026 14:10

Copilot started reviewing on behalf of mnriem July 10, 2026 14:11 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Comment thread src/specify_cli/agents.py

Comment thread templates/commands/plan.md

fix: fall back when configured script variant is missing from frontma…

6e8f2e8

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

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

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

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Comment thread scripts/python/create_new_feature.py

Copilot AI review requested due to automatic review settings July 10, 2026 20:21

Copilot started reviewing on behalf of marcelsafin July 10, 2026 20:21 View session

Copilot AI reviewed Jul 10, 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!

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

marcelsafin commented Jul 6, 2026 •

edited

Loading