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.

marcelsafin · 2026-07-07T00:06:07Z

+def run(
+    cmd: list[str], repo: Path, env: dict[str, str] | None = None
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        cmd,
+        cwd=repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=env or clean_env(),
+    )


Fixed in 83a5dca: env if env is not None else clean_env().

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

marcelsafin · 2026-07-07T19:52:50Z

+def _sorted_preset_ids(presets_dir: Path) -> list[str]:
+    registry = presets_dir / ".registry"
+    if registry.is_file():
+        try:
+            data = json.loads(registry.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            data = None
+        if isinstance(data, dict):
+            presets = data.get("presets", {})
+            if isinstance(presets, dict):
+                return [
+                    pid
+                    for pid, meta in sorted(
+                        presets.items(),
+                        key=lambda kv: kv[1].get("priority", 10)
+                        if isinstance(kv[1], dict)
+                        else 10,
+                    )
+                    if isinstance(meta, dict) and meta.get("enabled", True) is not False
+                ]
+    try:
+        return sorted(p.name for p in presets_dir.iterdir() if p.is_dir())
+    except OSError:
+        return []


Fixed in d4e4c5e: the whole registry read/sort is now wrapped in a broad except that falls back to the directory scan, and the scan skips hidden dirs, matching the bash behavior. Added a parity test with an unorderable priority value plus a hidden preset dir.

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

marcelsafin · 2026-07-08T07:09:00Z

+def ps_cmd(repo: Path, script: str, *args: str) -> list[str]:
+    return [
+        POWERSHELL_EXE,
+        "-NoProfile",
+        "-File",
+        str(repo / ".specify" / "scripts" / "powershell" / f"{script}.ps1"),
+        *args,
+    ]


All ps_cmd call sites are guarded by HAS_POWERSHELL skips, but the failure mode was obscure. Added an assert with a clear message so a missing guard fails loudly.

marcelsafin · 2026-07-08T07:09:02Z

 scripts:
  sh: scripts/bash/setup-plan.sh --json
  ps: scripts/powershell/setup-plan.ps1 -Json
+  py: scripts/python/setup_plan.py --json


Good catch. resolve_skill_placeholders now accepts py and prefixes the resolved interpreter (quoted when the path contains spaces), matching process_template. Covered in tests/test_skill_placeholder_py.py.

marcelsafin · 2026-07-08T07:09:03Z

 scripts:
  sh: scripts/bash/setup-tasks.sh --json
  ps: scripts/powershell/setup-tasks.ps1 -Json
+  py: scripts/python/setup_tasks.py --json


Fixed together with the plan.md thread: the skills resolver handles py with interpreter prefixing now.

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.

marcelsafin · 2026-07-08T07:15:55Z

+@requires_bash
+@pytest.mark.parametrize(
+    "args",
+    [
+        (),
+        ("   ",),
+        ("--short-name",),
+        ("--number",),
+    ],
+    ids=["missing_description", "whitespace_description", "short_name_no_value", "number_no_value"],
+)
+def test_python_argument_errors_match_bash(repo: Path, args: tuple[str, ...]) -> None:
+    bash = run(bash_cmd(repo, SCRIPT, *args), repo)
+    py = run(py_cmd(repo, SCRIPT, *args), repo)
+
+    assert py.returncode == bash.returncode == 1
+    assert py.stdout == bash.stdout == ""
+    assert normalize_script_names(py.stderr, repo, SCRIPT) == normalize_script_names(
+        bash.stderr, repo, SCRIPT
+    )
+


Added test_python_invalid_number_fails_cleanly: exit code 1, empty stdout, and the exact error message are pinned, with a comment explaining the deliberate deviation from the bash arithmetic error.

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.

marcelsafin · 2026-07-08T07:22:10Z

 scripts:
  sh: scripts/bash/setup-plan.sh --json
  ps: scripts/powershell/setup-plan.ps1 -Json
+  py: scripts/python/setup_plan.py --json


The installer gap is fixed in #3403 (commit aa7e627): install_shared_infra maps py to the python variant dir and a test runs the installer with --script py and asserts the scripts land. Keeping that fix in one PR avoids conflicting duplicate patches; both PRs together complete the --script py flow.

marcelsafin · 2026-07-08T07:22:12Z

 scripts:
  sh: scripts/bash/setup-tasks.sh --json
  ps: scripts/powershell/setup-tasks.ps1 -Json
+  py: scripts/python/setup_tasks.py --json


Same as the plan.md thread: covered by the shared-infra fix in #3403.

Copilot

Review details

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

marcelsafin · 2026-07-08T19:08:14Z

+def _help_text(argv0: str) -> str:
+    return f"""{_usage(argv0)}
+
+Options:
+  --json              Output in JSON format
+  --dry-run           Compute feature name and paths without creating directories or files
+  --allow-existing-branch  Reuse an existing feature directory if it already exists
+  --short-name <name> Provide a custom short name (2-4 words) for the feature
+  --number N          Specify branch number manually (overrides auto-detection)
+  --timestamp         Use timestamp prefix (YYYYMMDD-HHMMSS) instead of sequential numbering
+  --help, -h          Show this help message


Right, --no-git does not exist in any variant. That was a description error on my part, not missing code: the flag list should have said --allow-existing-branch only. PR description fixed. The bash twin has no --no-git either, so implementing it here would break parity scope.

Copilot

Review details

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

marcelsafin · 2026-07-10T06:26:47Z

+        elif arg in {"--help", "-h"}:
+            sys.stdout.write(_help_text(sys.argv[0]))
+            return 0
+        # Other arguments are collected but unused, matching setup-plan.sh.


Reworded in 7408065. The comment now says the extra args are 'accepted and silently ignored', which matches what the loop and setup-plan.sh actually do.

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

marcelsafin · 2026-07-10T18:00:37Z

        script_variant = init_opts.get("script")
-        if script_variant not in {"sh", "ps"}:
+        if script_variant not in {"sh", "ps", "py"}:
            fallback_order = []


Fixed in 6e8f2e8. The fallback now also triggers when the configured variant is missing from the command's scripts mapping, not only when the variant name is unknown, so {SCRIPT} is never left unresolved. Regression test added: script=py with an sh/ps-only template resolves to the sh variant.

marcelsafin · 2026-07-10T18:00:40Z

 scripts:
  sh: scripts/bash/setup-plan.sh --json
  ps: scripts/powershell/setup-plan.ps1 -Json
+  py: scripts/python/setup_plan.py --json
 ---


Good catch, the description overstated it. Updated the PR body: the port is additive except for the scripts.py entries in plan.md/tasks.md and the py variant support in resolve_skill_placeholders.

…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"
            )

+        if branch_number:
+            try:
+                number = int(branch_number, 10)
+            except ValueError:
+                print(
+                    f"Error: --number must be an integer, got '{branch_number}'",
+                    file=sys.stderr,
+                )
+                return 1


…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

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

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

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

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

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

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

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

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

Comment on lines +204 to +212

if branch_number:

try:

number = int(branch_number, 10)

except ValueError:

print(

f"Error: --number must be an integer, got '{branch_number}'",

file=sys.stderr,

)

return 1

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!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Choose a reason for hiding this comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

marcelsafin commented Jul 6, 2026 •

edited

Loading