feat(scripts): port create-new-feature, setup-plan and setup-tasks to Python (#3386)

* feat(scripts): port create-new-feature, setup-plan and setup-tasks to Python Ports the three core workflow scripts to Python as part of #3280, following the check-prerequisites PoC pattern from #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> * fix(tests): treat only None env as unset in parity run helper Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): fall back to directory scan on any registry error, skip hidden preset dirs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat(templates): add py: lines for setup_plan and setup_tasks Ships with the scripts they reference; the remaining templates got their py: lines in #3403. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: support py variant in skills placeholder resolver 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> * test: pin clean-error behavior for invalid --number Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(scripts): reword unused-arg comment to match implementation 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> * fix: fall back when configured script variant is missing from frontmatter Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): reject signed/whitespace --number values to match bash 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> * fix(scripts): complete Python port installation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(integrations): fall back for missing script variants Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * test: make Python script checks platform-aware Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix Windows Python command invocation parity Use PowerShell's call operator for spaced Python interpreter paths and align setup-tasks missing-template errors across script variants. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): preserve cross-platform Python parity Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: reject signed PowerShell feature numbers Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): align feature number range Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): reject exhausted feature numbers Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): complete create feature parity Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): align create feature outputs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): harden cross-platform parity Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): keep truncation JSON clean Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): align setup failure parity Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): close parity edge cases Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): propagate PowerShell setup errors Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): harden fallback resolution Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): stabilize PowerShell fallbacks Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): complete setup-plan parity Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(cli): require runnable script fallbacks Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(cli): preserve shell fallback without preference Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): restore help and symlink parity - setup-tasks.ps1: check -Help before unknown-argument validation so '-Help --bogus' exits 0 like the Bash/Python variants - common.py: strip the repo root prefix lexically in persist_feature_json instead of resolve(), so a symlinked specs/ still persists the relative 'specs/NNN-name' path the Bash/PowerShell helpers store Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): align persist-hint quoting with shlex.quote - create-new-feature.sh: replace printf %q with a shell_quote helper that emits shlex.quote-identical output, so the persistence hints stay byte-identical between the Bash and Python variants (printf %q output also varies between bash versions) - promote the negative --number test to an all-variants parity test now that Bash and PowerShell reject signed values consistently - add a spaced-repo-path parity test for the persistence hints Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-08-03 06:26:30 +08:00 · 2026-07-21 18:40:15 +02:00
parent 7873c447bd
commit 2a0ada9a6a
28 changed files with 2883 additions and 167 deletions
--- a/scripts/bash/create-new-feature.sh
+++ b/scripts/bash/create-new-feature.sh
@@ -90,6 +90,19 @@ if [ -z "$FEATURE_DESCRIPTION" ]; then
    exit 1
 fi

+MAX_FEATURE_NUMBER=9223372036854775807
+
+is_feature_number_in_range() {
+    local value="$1"
+    local normalized="${value#"${value%%[!0]*}"}"
+    [ -n "$normalized" ] || normalized=0
+    [ ${#normalized} -lt ${#MAX_FEATURE_NUMBER} ] && return 0
+    [ ${#normalized} -gt ${#MAX_FEATURE_NUMBER} ] && return 1
+    # Equal-length digit strings must be compared without arithmetic overflow.
+    # shellcheck disable=SC2071
+    [[ "$normalized" < "$MAX_FEATURE_NUMBER" || "$normalized" == "$MAX_FEATURE_NUMBER" ]]
+}
+
 # Function to get highest number from specs directory
 get_highest_from_specs() {
    local specs_dir="$1"
@@ -102,9 +115,11 @@ get_highest_from_specs() {
            # Match sequential prefixes (>=3 digits), but skip timestamp dirs.
            if echo "$dirname" | grep -Eq '^[0-9]{3,}-' && ! echo "$dirname" | grep -Eq '^[0-9]{8}-[0-9]{6}-'; then
                number=$(echo "$dirname" | grep -Eo '^[0-9]+')
-                number=$((10#$number))
-                if [ "$number" -gt "$highest" ]; then
-                    highest=$number
+                if is_feature_number_in_range "$number"; then
+                    number=$((10#$number))
+                    if [ "$number" -gt "$highest" ]; then
+                        highest=$number
+                    fi
                fi
            fi
        done
@@ -119,6 +134,19 @@ clean_branch_name() {
    echo "$name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//'
 }

+# Quote a value for POSIX shell reuse, byte-identical to Python's shlex.quote
+# so the persistence hints match the Python variant exactly (printf %q output
+# differs between bash versions and from shlex.quote for spaces/metachars).
+shell_quote() {
+    local value="$1" LC_ALL=C
+    if [[ "$value" =~ ^[A-Za-z0-9_@%+=:,./-]+$ ]]; then
+        printf '%s' "$value"
+    else
+        local q="'\"'\"'"
+        printf "'%s'" "${value//\'/$q}"
+    fi
+}
+
 # Resolve repository root using common.sh functions which prioritize .specify
 SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/common.sh"
@@ -202,9 +230,24 @@ if [ "$USE_TIMESTAMP" = true ]; then
    FEATURE_NUM=$(date +%Y%m%d-%H%M%S)
    BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
 else
+    if [ -n "$BRANCH_NUMBER" ] && [[ ! "$BRANCH_NUMBER" =~ ^[0-9]+$ ]]; then
+        echo "Error: --number must be an unsigned integer, got '$BRANCH_NUMBER'" >&2
+        exit 1
+    fi
+
+    # Bash arithmetic is signed 64-bit; reject digit strings that would wrap.
+    if [ -n "$BRANCH_NUMBER" ] && ! is_feature_number_in_range "$BRANCH_NUMBER"; then
+        echo "Error: --number must be between 0 and $MAX_FEATURE_NUMBER, got '$BRANCH_NUMBER'" >&2
+        exit 1
+    fi
+
    # Determine branch number from existing feature directories
    if [ -z "$BRANCH_NUMBER" ]; then
        HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
+        if [ "$HIGHEST" -eq "$MAX_FEATURE_NUMBER" ]; then
+            echo "Error: feature number must be between 0 and $MAX_FEATURE_NUMBER, got '9223372036854775808'" >&2
+            exit 1
+        fi
        BRANCH_NUMBER=$((HIGHEST + 1))
    fi

@@ -264,8 +307,8 @@ if [ "$DRY_RUN" != true ]; then
    _persist_feature_json "$REPO_ROOT" "$FEATURE_DIR"

    # Inform the user how to set feature state in their own shell
-    printf '# To persist: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME" >&2
-    printf '#              export SPECIFY_FEATURE_DIRECTORY=%q\n' "$FEATURE_DIR" >&2
+    printf '# To persist: export SPECIFY_FEATURE=%s\n' "$(shell_quote "$BRANCH_NAME")" >&2
+    printf '#              export SPECIFY_FEATURE_DIRECTORY=%s\n' "$(shell_quote "$FEATURE_DIR")" >&2
 fi

 if $JSON_MODE; then
@@ -295,7 +338,7 @@ else
    echo "SPEC_FILE: $SPEC_FILE"
    echo "FEATURE_NUM: $FEATURE_NUM"
    if [ "$DRY_RUN" != true ]; then
-        printf '# To persist in your shell: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME"
-        printf '#                           export SPECIFY_FEATURE_DIRECTORY=%q\n' "$FEATURE_DIR"
+        printf '# To persist in your shell: export SPECIFY_FEATURE=%s\n' "$(shell_quote "$BRANCH_NAME")"
+        printf '#                           export SPECIFY_FEATURE_DIRECTORY=%s\n' "$(shell_quote "$FEATURE_DIR")"
    fi
 fi
--- a/scripts/powershell/common.ps1
+++ b/scripts/powershell/common.ps1
@@ -29,13 +29,16 @@ function Find-SpecifyRoot {
 # command against a member project from a monorepo root without cd.
 #
 # Precondition: $env:SPECIFY_INIT_DIR is set. Returns the validated project root,
-# or writes an error and exits 1. Strict by design: the path must exist and
+# or writes an error and exits 1 unless -ReturnNullOnError is set. Strict by
+# design: the path must exist and
 # contain .specify/, with no silent fallback. (An empty string is falsy, so the
 # caller's `if ($env:SPECIFY_INIT_DIR)` guard treats empty as unset.)
 #
 # This is the single resolver: bundled extensions inherit it by sourcing core
 # (e.g. the git extension's create-new-feature-branch) rather than duplicating it.
 function Resolve-SpecifyInitDir {
+    param([switch]$ReturnNullOnError)
+
    $initDir = $env:SPECIFY_INIT_DIR
    # Normalize: relative paths resolve against the current directory.
    if (-not [System.IO.Path]::IsPathRooted($initDir)) {
@@ -47,6 +50,7 @@ function Resolve-SpecifyInitDir {
    # "not a Spec Kit project" error below.
    if (-not $resolved -or -not (Test-Path -LiteralPath $resolved.Path -PathType Container)) {
        [Console]::Error.WriteLine("ERROR: SPECIFY_INIT_DIR does not point to an existing directory: $($env:SPECIFY_INIT_DIR)")
+        if ($ReturnNullOnError) { return $null }
        exit 1
    }
    # Resolve-Path echoes back any trailing separator from the input; trim it so
@@ -56,6 +60,7 @@ function Resolve-SpecifyInitDir {
    $initRoot = [System.IO.Path]::TrimEndingDirectorySeparator($resolved.Path)
    if (-not (Test-Path -LiteralPath (Join-Path $initRoot '.specify') -PathType Container)) {
        [Console]::Error.WriteLine("ERROR: SPECIFY_INIT_DIR is not a Spec Kit project (no .specify/ directory): $initRoot")
+        if ($ReturnNullOnError) { return $null }
        exit 1
    }
    return $initRoot
@@ -64,9 +69,11 @@ function Resolve-SpecifyInitDir {
 # Get repository root, prioritizing .specify directory
 # This prevents using a parent repository when spec-kit is initialized in a subdirectory
 function Get-RepoRoot {
+    param([switch]$ReturnNullOnError)
+
    # Explicit project override wins (see Resolve-SpecifyInitDir).
    if ($env:SPECIFY_INIT_DIR) {
-        return (Resolve-SpecifyInitDir)
+        return (Resolve-SpecifyInitDir -ReturnNullOnError:$ReturnNullOnError)
    }

    # First, look for .specify directory (spec-kit's own marker)
@@ -147,10 +154,12 @@ function Get-FeaturePathsEnv {
    # so pure path resolution never writes .specify/feature.json, which would
    # dirty the working tree or overwrite a pinned value (issue #3025).
    param(
-        [switch]$NoPersist
+        [switch]$NoPersist,
+        [switch]$ReturnNullOnError
    )

-    $repoRoot = Get-RepoRoot
+    $repoRoot = Get-RepoRoot -ReturnNullOnError:$ReturnNullOnError
+    if (-not $repoRoot) { return $null }
    $currentBranch = Get-CurrentBranch

    # Resolve feature directory.  Priority:
@@ -174,7 +183,8 @@ function Get-FeaturePathsEnv {
        try {
            $featureConfig = $featureJsonRaw | ConvertFrom-Json
        } catch {
-            [Console]::Error.WriteLine("ERROR: Failed to parse .specify/feature.json: $_")
+            [Console]::Error.WriteLine("ERROR: Feature directory not found. Set SPECIFY_FEATURE_DIRECTORY or ensure .specify/feature.json contains feature_directory.")
+            if ($ReturnNullOnError) { return $null }
            exit 1
        }
        if ($featureConfig.feature_directory) {
@@ -185,10 +195,12 @@ function Get-FeaturePathsEnv {
            }
        } else {
            [Console]::Error.WriteLine("ERROR: Feature directory not found. Set SPECIFY_FEATURE_DIRECTORY or ensure .specify/feature.json contains feature_directory.")
+            if ($ReturnNullOnError) { return $null }
            exit 1
        }
    } else {
        [Console]::Error.WriteLine("ERROR: Feature directory not found. Set SPECIFY_FEATURE_DIRECTORY or run the specify command to create .specify/feature.json.")
+        if ($ReturnNullOnError) { return $null }
        exit 1
    }

@@ -334,30 +346,64 @@ function Resolve-Template {
    if (Test-Path $presetsDir) {
        $registryFile = Join-Path $presetsDir '.registry'
        $sortedPresets = @()
+        $registryParsed = $false
        if (Test-Path $registryFile) {
            try {
                $registryData = Get-Content $registryFile -Raw | ConvertFrom-Json
-                $presets = $registryData.presets
-                if ($presets) {
-                    $sortedPresets = $presets.PSObject.Properties |
+                if ($null -eq $registryData -or $registryData -isnot [PSCustomObject]) {
+                    throw 'Registry root must be an object'
+                }
+                $presetsProperty = $registryData.PSObject.Properties['presets']
+                if ($presetsProperty) {
+                    $presets = $presetsProperty.Value
+                    if ($null -eq $presets -or $presets -isnot [PSCustomObject]) {
+                        throw 'Registry presets must be an object'
+                    }
+                    $presetEntries = @($presets.PSObject.Properties)
+                    $priorityFor = {
+                        param($Entry)
+                        if ($Entry.Value -is [PSCustomObject]) {
+                            $priorityProperty = $Entry.Value.PSObject.Properties['priority']
+                            if ($priorityProperty) { return $priorityProperty.Value }
+                        }
+                        return 10
+                    }
+                    if ($presetEntries.Count -gt 1) {
+                        $allNumeric = $true
+                        $allStrings = $true
+                        foreach ($entry in $presetEntries) {
+                            $priority = & $priorityFor $entry
+                            if ($null -eq $priority -or $priority -isnot [ValueType]) {
+                                $allNumeric = $false
+                            }
+                            if ($null -eq $priority -or $priority -isnot [string]) {
+                                $allStrings = $false
+                            }
+                        }
+                        if (-not $allNumeric -and -not $allStrings) {
+                            throw 'Registry priorities are not mutually orderable'
+                        }
+                    }
+                    $sortedPresets = $presetEntries |
+                        Where-Object { $_.Value -is [PSCustomObject] } |
                        Where-Object { $null -eq $_.Value.enabled -or $_.Value.enabled -ne $false } |
-                        Sort-Object { if ($null -ne $_.Value.priority) { $_.Value.priority } else { 10 } } |
+                        Sort-Object { & $priorityFor $_ } |
                        ForEach-Object { $_.Name }
                }
+                $registryParsed = $true
            } catch {
-                # Fallback: alphabetical directory order
-                $sortedPresets = @()
+                $registryParsed = $false
            }
        }

-        if ($sortedPresets.Count -gt 0) {
+        if ($registryParsed) {
            foreach ($presetId in $sortedPresets) {
                $candidate = Join-Path $presetsDir "$presetId/templates/$TemplateName.md"
                if (Test-Path $candidate) { return $candidate }
            }
        } else {
            # Fallback: alphabetical directory order
-            foreach ($preset in Get-ChildItem -Path $presetsDir -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -notlike '.*' }) {
+            foreach ($preset in Get-ChildItem -Path $presetsDir -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -notlike '.*' } | Sort-Object Name) {
                $candidate = Join-Path $preset.FullName "templates/$TemplateName.md"
                if (Test-Path $candidate) { return $candidate }
            }
--- a/scripts/powershell/create-new-feature.ps1
+++ b/scripts/powershell/create-new-feature.ps1
@@ -7,7 +7,7 @@ param(
    [switch]$DryRun,
    [string]$ShortName,
    [Parameter()]
-    [long]$Number = 0,
+    [string]$Number = '',
    [switch]$Timestamp,
    [switch]$Help,
    [Parameter(Position = 0, ValueFromRemainingArguments = $true)]
@@ -142,12 +142,13 @@ if ($ShortName) {
    $branchSuffix = Get-BranchName -Description $featureDesc
 }

-# Warn if -Number and -Timestamp are both specified. Use ContainsKey (not
-# `-ne 0`) so an explicit `-Number 0` is also detected, matching the bash twin's
-# `[ -n "$BRANCH_NUMBER" ]` check.
-if ($Timestamp -and $PSBoundParameters.ContainsKey('Number')) {
-    Write-Warning "[specify] Warning: -Number is ignored when -Timestamp is used"
-    $Number = 0
+# Treat an explicit empty string as omitted, matching the bash and Python twins.
+$hasNumber = $PSBoundParameters.ContainsKey('Number') -and $Number -ne ''
+
+# Warn if -Number and -Timestamp are both specified.
+if ($Timestamp -and $hasNumber) {
+    [Console]::Error.WriteLine("[specify] Warning: -Number is ignored when -Timestamp is used")
+    $Number = ''
 }

 # Determine branch prefix
@@ -158,11 +159,23 @@ if ($Timestamp) {
    # Determine branch number from existing feature directories. Auto-detect only
    # when -Number was not supplied; an explicit value (including 0) is honored,
    # matching the bash twin's `[ -z "$BRANCH_NUMBER" ]` check.
-    if (-not $PSBoundParameters.ContainsKey('Number')) {
-        $Number = (Get-HighestNumberFromSpecs -SpecsDir $specsDir) + 1
+    [long]$resolvedNumber = 0
+    if (-not $hasNumber) {
+        $highestNumber = Get-HighestNumberFromSpecs -SpecsDir $specsDir
+        if ($highestNumber -eq [long]::MaxValue) {
+            Write-Error "Error: feature number must be between 0 and $([long]::MaxValue), got '9223372036854775808'"
+            exit 1
+        }
+        $resolvedNumber = $highestNumber + 1
+    } elseif ($Number -notmatch '^[0-9]+$') {
+        Write-Error "Error: -Number must be an unsigned integer, got '$Number'"
+        exit 1
+    } elseif (-not [long]::TryParse($Number, [ref]$resolvedNumber)) {
+        Write-Error "Error: -Number must be between 0 and $([long]::MaxValue), got '$Number'"
+        exit 1
    }

-    $featureNum = ('{0:000}' -f $Number)
+    $featureNum = ('{0:000}' -f $resolvedNumber)
    $branchName = "$featureNum-$branchSuffix"
 }

@@ -183,9 +196,9 @@ if ($branchName.Length -gt $maxBranchLength) {
    $originalBranchName = $branchName
    $branchName = "$featureNum-$truncatedSuffix"

-    Write-Warning "[specify] Branch name exceeded GitHub's 244-byte limit"
-    Write-Warning "[specify] Original: $originalBranchName ($($originalBranchName.Length) bytes)"
-    Write-Warning "[specify] Truncated to: $branchName ($($branchName.Length) bytes)"
+    [Console]::Error.WriteLine("[specify] Warning: Branch name exceeded GitHub's 244-byte limit")
+    [Console]::Error.WriteLine("[specify] Original: $originalBranchName ($($originalBranchName.Length) bytes)")
+    [Console]::Error.WriteLine("[specify] Truncated to: $branchName ($($branchName.Length) bytes)")
 }

 $featureDir = Join-Path $specsDir $branchName
@@ -225,6 +238,13 @@ if (-not $DryRun) {
    # Set environment variables for the current session
    $env:SPECIFY_FEATURE = $branchName
    $env:SPECIFY_FEATURE_DIRECTORY = $featureDir
+
+    $quotedBranchName = "'" + $branchName.Replace("'", "''") + "'"
+    $quotedFeatureDir = "'" + $featureDir.Replace("'", "''") + "'"
+    $featureAssignment = '$env:SPECIFY_FEATURE = ' + $quotedBranchName
+    $directoryAssignment = '$env:SPECIFY_FEATURE_DIRECTORY = ' + $quotedFeatureDir
+    [Console]::Error.WriteLine("# To persist: $featureAssignment")
+    [Console]::Error.WriteLine("#              $directoryAssignment")
 }

 if ($Json) {
@@ -242,7 +262,7 @@ if ($Json) {
    Write-Output "SPEC_FILE: $specFile"
    Write-Output "FEATURE_NUM: $featureNum"
    if (-not $DryRun) {
-        Write-Output "SPECIFY_FEATURE set to: $branchName"
-        Write-Output "SPECIFY_FEATURE_DIRECTORY set to: $featureDir"
+        Write-Output "# To persist in your shell: $featureAssignment"
+        Write-Output "#                           $directoryAssignment"
    }
 }
--- a/scripts/powershell/setup-plan.ps1
+++ b/scripts/powershell/setup-plan.ps1
@@ -4,7 +4,10 @@
 [CmdletBinding()]
 param(
    [switch]$Json,
-    [switch]$Help
+    [switch]$Help,
+    # Capture extra positional arguments to match Bash/Python behavior.
+    [Parameter(ValueFromRemainingArguments = $true)]
+    [string[]]$RemainingArgs
 )

 $ErrorActionPreference = 'Stop'
@@ -21,7 +24,11 @@ if ($Help) {
 . "$PSScriptRoot/common.ps1"

 # Get all paths and variables from common functions
-$paths = Get-FeaturePathsEnv
+$paths = Get-FeaturePathsEnv -ReturnNullOnError
+if (-not $paths) {
+    [Console]::Error.WriteLine("ERROR: Failed to resolve feature paths")
+    exit 1
+}

 # Ensure the feature directory exists
 New-Item -ItemType Directory -Path $paths.FEATURE_DIR -Force | Out-Null
--- a/scripts/powershell/setup-tasks.ps1
+++ b/scripts/powershell/setup-tasks.ps1
@@ -3,21 +3,34 @@
 [CmdletBinding()]
 param(
    [switch]$Json,
-    [switch]$Help
+    [switch]$Help,
+    [Parameter(ValueFromRemainingArguments = $true)]
+    [string[]]$RemainingArgs
 )

 $ErrorActionPreference = 'Stop'

+# Help wins over unknown-argument validation to match the Bash/Python
+# variants, which stop at --help and exit 0.
 if ($Help) {
    Write-Output "Usage: setup-tasks.ps1 [-Json] [-Help]"
    exit 0
 }

+if ($RemainingArgs.Count -gt 0) {
+    [Console]::Error.WriteLine("ERROR: Unknown option '$($RemainingArgs[0])'")
+    exit 1
+}
+
 # Source common functions
 . "$PSScriptRoot/common.ps1"

 # Get feature paths
-$paths = Get-FeaturePathsEnv
+$paths = Get-FeaturePathsEnv -ReturnNullOnError
+if (-not $paths) {
+    [Console]::Error.WriteLine("ERROR: Failed to resolve feature paths")
+    exit 1
+}

 if (-not (Test-Path $paths.IMPL_PLAN -PathType Leaf)) {
    [Console]::Error.WriteLine("ERROR: plan.md not found in $($paths.FEATURE_DIR)")
@@ -45,8 +58,8 @@ if (Test-Path $paths.QUICKSTART) { $docs += 'quickstart.md' }
 # Resolve tasks template through override stack
 $tasksTemplate = Resolve-Template -TemplateName 'tasks-template' -RepoRoot $paths.REPO_ROOT
 if (-not $tasksTemplate -or -not (Test-Path -LiteralPath $tasksTemplate -PathType Leaf)) {
-    $expectedCoreTemplate = Join-Path $paths.REPO_ROOT '.specify/templates/tasks-template.md'
-    [Console]::Error.WriteLine("ERROR: Tasks template not found for repository root: $($paths.REPO_ROOT)`nTemplate resolution order: overrides -> presets -> extensions -> core.`nExpected shared/core template location: $expectedCoreTemplate`nTo continue, verify whether 'tasks-template.md' is available in '.specify/templates/overrides/', preset templates, extension templates, or restore the shared/core templates (for example by re-running 'specify init') so that '.specify/templates/tasks-template.md' exists.")
+    [Console]::Error.WriteLine("ERROR: Could not resolve required tasks-template from the template override stack for $($paths.REPO_ROOT)")
+    [Console]::Error.WriteLine("Template 'tasks-template' was not found in any supported location (overrides, presets, extensions, or shared core). Add an override at .specify/templates/overrides/tasks-template.md, or run 'specify init' / reinstall shared infra to restore the core .specify/templates/tasks-template.md template.")
    exit 1
 }
 $tasksTemplate = (Resolve-Path -LiteralPath $tasksTemplate).Path
--- a/scripts/python/common.py
+++ b/scripts/python/common.py
@@ -84,7 +84,7 @@ def read_feature_json_feature_directory(repo_root: Path) -> str:
        return ""
    try:
        data = json.loads(feature_json.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+    except (OSError, UnicodeError, json.JSONDecodeError):
        return ""
    value = data.get("feature_directory") if isinstance(data, dict) else None
    return value if isinstance(value, str) else ""
@@ -95,16 +95,17 @@ def _json_dump(data: dict[str, str]) -> str:


 def persist_feature_json(repo_root: Path, feature_dir_value: str) -> None:
+    # Strip the repo root prefix lexically (no resolve()) to mirror the
+    # Bash/PowerShell helpers: with a symlinked <repo>/specs, resolve() would
+    # escape the repo and persist a machine-specific absolute path instead of
+    # the relative "specs/NNN-name" the other variants store.
    value = feature_dir_value
-    try:
-        relative = Path(value)
-        if relative.is_absolute():
-            try:
-                value = relative.resolve().relative_to(repo_root.resolve()).as_posix()
-            except ValueError:
-                value = str(relative)
-    except OSError:
-        pass
+    relative = Path(value)
+    if relative.is_absolute():
+        try:
+            value = relative.relative_to(repo_root).as_posix()
+        except ValueError:
+            value = str(relative)

    current = read_feature_json_feature_directory(repo_root)
    if current == value:
@@ -112,9 +113,8 @@ def persist_feature_json(repo_root: Path, feature_dir_value: str) -> None:

    specify_dir = repo_root / ".specify"
    specify_dir.mkdir(parents=True, exist_ok=True)
-    (specify_dir / "feature.json").write_text(
-        _json_dump({"feature_directory": value}),
-        encoding="utf-8",
+    (specify_dir / "feature.json").write_bytes(
+        _json_dump({"feature_directory": value}).encode("utf-8")
    )


@@ -182,6 +182,78 @@ def get_feature_paths(
    )


+def _sorted_preset_ids(presets_dir: Path) -> list[str]:
+    registry = presets_dir / ".registry"
+    if registry.is_file():
+        # Mirrors bash: any failure while reading or sorting the registry
+        # (invalid JSON, non-dict shapes, unorderable priority values) falls
+        # back to the directory scan below.
+        try:
+            data = json.loads(registry.read_text(encoding="utf-8"))
+            presets = data.get("presets", {})
+            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
+            ]
+        except Exception:
+            pass
+    try:
+        return sorted(
+            p.name
+            for p in presets_dir.iterdir()
+            if p.is_dir() and not p.name.startswith(".")
+        )
+    except OSError:
+        return []
+
+
+def resolve_template(template_name: str, repo_root: Path) -> Path | None:
+    """Resolve a template name to a file path using the priority stack.
+
+    Order (mirrors resolve_template in scripts/bash/common.sh):
+      1. .specify/templates/overrides/
+      2. .specify/presets/<preset-id>/templates/ (sorted by .registry priority)
+      3. .specify/extensions/<ext-id>/templates/ (hidden directories skipped)
+      4. .specify/templates/ (core)
+    """
+    base = repo_root / ".specify" / "templates"
+
+    override = base / "overrides" / f"{template_name}.md"
+    if override.is_file():
+        return override
+
+    presets_dir = repo_root / ".specify" / "presets"
+    if presets_dir.is_dir():
+        for preset_id in _sorted_preset_ids(presets_dir):
+            candidate = presets_dir / preset_id / "templates" / f"{template_name}.md"
+            if candidate.is_file():
+                return candidate
+
+    ext_dir = repo_root / ".specify" / "extensions"
+    if ext_dir.is_dir():
+        try:
+            extensions = sorted(p for p in ext_dir.iterdir() if p.is_dir())
+        except OSError:
+            extensions = []
+        for ext in extensions:
+            if ext.name.startswith("."):
+                continue
+            candidate = ext / "templates" / f"{template_name}.md"
+            if candidate.is_file():
+                return candidate
+
+    core = base / f"{template_name}.md"
+    if core.is_file():
+        return core
+    return None
+
+
 def get_invoke_separator(repo_root: Path) -> str:
    integration_json = repo_root / ".specify" / "integration.json"
    if not integration_json.is_file():
--- a/scripts/python/create_new_feature.py
+++ b/scripts/python/create_new_feature.py
@@ -0,0 +1,355 @@
+#!/usr/bin/env python3
+"""Create a new feature directory and spec file."""
+
+from __future__ import annotations
+
+import datetime
+import json
+import re
+import shlex
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+try:
+    from common import get_repo_root, persist_feature_json, resolve_template
+except ImportError:  # pragma: no cover - direct execution from unusual cwd
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    from common import get_repo_root, persist_feature_json, resolve_template
+
+
+def _json_line(payload: object) -> str:
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
+
+
+_STOP_WORDS = frozenset(
+    """
+    i a an the to for of in on at by with from is are was were be been being
+    have has had do does did will would should could can may might must shall
+    this that these those my your our their want need add get set
+    """.split()
+)
+
+_MAX_BRANCH_LENGTH = 244
+_MAX_FEATURE_NUMBER = 2**63 - 1
+
+
+def _int64_from_digits(value: str) -> int | None:
+    normalized = value.lstrip("0") or "0"
+    maximum = str(_MAX_FEATURE_NUMBER)
+    if len(normalized) > len(maximum) or (
+        len(normalized) == len(maximum) and normalized > maximum
+    ):
+        return None
+    return int(normalized, 10)
+
+
+def _persistence_assignments(
+    branch_name: str, feature_dir: str, *, powershell: bool
+) -> tuple[str, str]:
+    if powershell:
+        quoted_branch = "'" + branch_name.replace("'", "''") + "'"
+        quoted_dir = "'" + feature_dir.replace("'", "''") + "'"
+        return (
+            f"$env:SPECIFY_FEATURE = {quoted_branch}",
+            f"$env:SPECIFY_FEATURE_DIRECTORY = {quoted_dir}",
+        )
+    return (
+        f"export SPECIFY_FEATURE={shlex.quote(branch_name)}",
+        f"export SPECIFY_FEATURE_DIRECTORY={shlex.quote(feature_dir)}",
+    )
+
+
+def _usage(argv0: str) -> str:
+    return (
+        f"Usage: {argv0} [--json] [--dry-run] [--allow-existing-branch] "
+        "[--short-name <name>] [--number N] [--timestamp] <feature_description>"
+    )
+
+
+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
+
+Examples:
+  {argv0} 'Add user authentication system' --short-name 'user-auth'
+  {argv0} 'Implement OAuth2 integration for API' --number 5
+  {argv0} --timestamp --short-name 'user-auth' 'Add user authentication'
+"""
+
+
+@dataclass(frozen=True)
+class Args:
+    json_mode: bool = False
+    dry_run: bool = False
+    allow_existing: bool = False
+    short_name: str = ""
+    branch_number: str = ""
+    use_timestamp: bool = False
+    description: str = ""
+
+
+def _parse_args(argv: list[str], argv0: str) -> Args:
+    json_mode = False
+    dry_run = False
+    allow_existing = False
+    short_name = ""
+    branch_number = ""
+    use_timestamp = False
+    rest: list[str] = []
+
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg == "--json":
+            json_mode = True
+        elif arg == "--dry-run":
+            dry_run = True
+        elif arg == "--allow-existing-branch":
+            allow_existing = True
+        elif arg in {"--short-name", "--number"}:
+            if i + 1 >= len(argv) or argv[i + 1].startswith("--"):
+                print(f"Error: {arg} requires a value", file=sys.stderr)
+                raise SystemExit(1)
+            i += 1
+            if arg == "--short-name":
+                short_name = argv[i]
+            else:
+                branch_number = argv[i]
+        elif arg == "--timestamp":
+            use_timestamp = True
+        elif arg in {"--help", "-h"}:
+            sys.stdout.write(_help_text(argv0))
+            raise SystemExit(0)
+        else:
+            rest.append(arg)
+        i += 1
+
+    description = " ".join(rest).strip()
+    if not description:
+        if rest:
+            print(
+                "Error: Feature description cannot be empty or contain only whitespace",
+                file=sys.stderr,
+            )
+        else:
+            print(_usage(argv0), file=sys.stderr)
+        raise SystemExit(1)
+
+    return Args(
+        json_mode=json_mode,
+        dry_run=dry_run,
+        allow_existing=allow_existing,
+        short_name=short_name,
+        branch_number=branch_number,
+        use_timestamp=use_timestamp,
+        description=description,
+    )
+
+
+def _clean_branch_name(name: str) -> str:
+    cleaned = re.sub(r"[^a-z0-9]", "-", name.lower())
+    cleaned = re.sub(r"-+", "-", cleaned)
+    return cleaned.strip("-")
+
+
+def _generate_branch_name(description: str) -> str:
+    clean = re.sub(r"[^a-z0-9]", " ", description.lower())
+    meaningful: list[str] = []
+    for word in clean.split():
+        if word in _STOP_WORDS:
+            continue
+        if len(word) >= 3:
+            meaningful.append(word)
+        # Keep short words that appear as an uppercase acronym in the original,
+        # mirroring the bash twin's case-sensitive `grep -qw` check.
+        elif re.search(
+            rf"(?<![0-9A-Za-z_]){re.escape(word.upper())}(?![0-9A-Za-z_])",
+            description,
+        ):
+            meaningful.append(word)
+
+    if meaningful:
+        max_words = 4 if len(meaningful) == 4 else 3
+        return "-".join(meaningful[:max_words])
+
+    cleaned = _clean_branch_name(description)
+    return "-".join([part for part in cleaned.split("-") if part][:3])
+
+
+def _get_highest_from_specs(specs_dir: Path) -> int:
+    highest = 0
+    if not specs_dir.is_dir():
+        return highest
+    for entry in specs_dir.iterdir():
+        if not entry.is_dir():
+            continue
+        name = entry.name
+        # Match sequential prefixes (>=3 digits), but skip timestamp dirs.
+        if re.match(r"^[0-9]{3,}-", name) and not re.match(
+            r"^[0-9]{8}-[0-9]{6}-", name
+        ):
+            number = _int64_from_digits(re.match(r"^[0-9]+", name).group())
+            if number is not None:
+                highest = max(highest, number)
+    return highest
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv0 = sys.argv[0]
+    args = _parse_args(list(argv if argv is not None else sys.argv[1:]), argv0)
+
+    repo_root = get_repo_root(Path(__file__))
+    specs_dir = repo_root / "specs"
+    if not args.dry_run:
+        specs_dir.mkdir(parents=True, exist_ok=True)
+
+    if args.short_name:
+        branch_suffix = _clean_branch_name(args.short_name)
+    else:
+        branch_suffix = _generate_branch_name(args.description)
+
+    branch_number = args.branch_number
+    if args.use_timestamp and branch_number:
+        print(
+            "[specify] Warning: --number is ignored when --timestamp is used",
+            file=sys.stderr,
+        )
+        branch_number = ""
+
+    if args.use_timestamp:
+        feature_num = datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
+    else:
+        if branch_number:
+            # Mirrors bash: $((10#$BRANCH_NUMBER)) only accepts unsigned
+            # decimal digits, rejecting signs, whitespace, and other
+            # characters that int() would otherwise tolerate.
+            if not re.fullmatch(r"[0-9]+", branch_number):
+                print(
+                    "Error: --number must be an unsigned integer, "
+                    f"got '{branch_number}'",
+                    file=sys.stderr,
+                )
+                return 1
+            number = _int64_from_digits(branch_number)
+            if number is None:
+                print(
+                    "Error: --number must be between 0 and "
+                    f"{_MAX_FEATURE_NUMBER}, got '{branch_number}'",
+                    file=sys.stderr,
+                )
+                return 1
+        else:
+            number = _get_highest_from_specs(specs_dir) + 1
+        if number > _MAX_FEATURE_NUMBER:
+            rejected_number = branch_number or str(number)
+            number_label = "--number" if branch_number else "feature number"
+            print(
+                f"Error: {number_label} must be between 0 and "
+                f"{_MAX_FEATURE_NUMBER}, got '{rejected_number}'",
+                file=sys.stderr,
+            )
+            return 1
+        feature_num = f"{number:03d}"
+
+    max_suffix_length = _MAX_BRANCH_LENGTH - (len(feature_num) + 1)
+    if max_suffix_length <= 0:
+        print("Error: feature number is too long for a branch name", file=sys.stderr)
+        return 1
+
+    branch_name = f"{feature_num}-{branch_suffix}"
+
+    # GitHub enforces a 244-byte limit on branch names.
+    if len(branch_name) > _MAX_BRANCH_LENGTH:
+        truncated_suffix = re.sub(r"-$", "", branch_suffix[:max_suffix_length])
+        original_branch_name = branch_name
+        branch_name = f"{feature_num}-{truncated_suffix}"
+        print(
+            "[specify] Warning: Branch name exceeded GitHub's 244-byte limit",
+            file=sys.stderr,
+        )
+        print(
+            f"[specify] Original: {original_branch_name} "
+            f"({len(original_branch_name)} bytes)",
+            file=sys.stderr,
+        )
+        print(
+            f"[specify] Truncated to: {branch_name} ({len(branch_name)} bytes)",
+            file=sys.stderr,
+        )
+
+    feature_dir = specs_dir / branch_name
+    spec_file = feature_dir / "spec.md"
+
+    if not args.dry_run:
+        if feature_dir.is_dir() and not args.allow_existing:
+            if args.use_timestamp:
+                print(
+                    f"Error: Feature directory '{feature_dir}' already exists. "
+                    "Rerun to get a new timestamp or use a different --short-name.",
+                    file=sys.stderr,
+                )
+            else:
+                print(
+                    f"Error: Feature directory '{feature_dir}' already exists. "
+                    "Please use a different feature name or specify a different "
+                    "number with --number.",
+                    file=sys.stderr,
+                )
+            return 1
+
+        feature_dir.mkdir(parents=True, exist_ok=True)
+
+        if not spec_file.is_file():
+            template = resolve_template("spec-template", repo_root)
+            if template is not None and template.is_file():
+                shutil.copy(template, spec_file)
+            else:
+                print(
+                    "Warning: Spec template not found; created empty spec file",
+                    file=sys.stderr,
+                )
+                spec_file.touch()
+
+        # Persist to .specify/feature.json so downstream commands can find the feature.
+        persist_feature_json(repo_root, f"specs/{branch_name}")
+
+        # Inform the user how to set feature state in their own shell.
+        feature_assignment, directory_assignment = _persistence_assignments(
+            branch_name,
+            str(feature_dir),
+            powershell=sys.platform == "win32",
+        )
+        print(f"# To persist: {feature_assignment}", file=sys.stderr)
+        print(f"#              {directory_assignment}", file=sys.stderr)
+
+    if args.json_mode:
+        payload: dict[str, object] = {
+            "BRANCH_NAME": branch_name,
+            "SPEC_FILE": str(spec_file),
+            "FEATURE_NUM": feature_num,
+        }
+        if args.dry_run:
+            payload["DRY_RUN"] = True
+        sys.stdout.write(_json_line(payload))
+    else:
+        print(f"BRANCH_NAME: {branch_name}")
+        print(f"SPEC_FILE: {spec_file}")
+        print(f"FEATURE_NUM: {feature_num}")
+        if not args.dry_run:
+            print(f"# To persist in your shell: {feature_assignment}")
+            print(f"#                           {directory_assignment}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
--- a/scripts/python/setup_plan.py
+++ b/scripts/python/setup_plan.py
@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Setup implementation plan for a feature."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from pathlib import Path
+
+try:
+    from common import get_feature_paths, resolve_template
+except ImportError:  # pragma: no cover - direct execution from unusual cwd
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    from common import get_feature_paths, resolve_template
+
+
+def _json_line(payload: object) -> str:
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
+
+
+def _help_text(argv0: str) -> str:
+    return f"""Usage: {argv0} [--json]
+  --json    Output results in JSON format
+  --help    Show this help message
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(argv if argv is not None else sys.argv[1:])
+    json_mode = False
+    for arg in args:
+        if arg == "--json":
+            json_mode = True
+        elif arg in {"--help", "-h"}:
+            sys.stdout.write(_help_text(sys.argv[0]))
+            return 0
+        # Other arguments are accepted and silently ignored, matching setup-plan.sh.
+
+    try:
+        paths = get_feature_paths(script_file=Path(__file__))
+    except SystemExit as exc:
+        if exc.code == 0:
+            return 0
+        print("ERROR: Failed to resolve feature paths", file=sys.stderr)
+        return int(exc.code) if isinstance(exc.code, int) else 1
+
+    paths.feature_dir.mkdir(parents=True, exist_ok=True)
+
+    # Status messages go to stderr in JSON mode so stdout stays pure JSON.
+    status_stream = sys.stderr if json_mode else sys.stdout
+    if paths.impl_plan.is_file():
+        print(
+            f"Plan already exists at {paths.impl_plan}, skipping template copy",
+            file=status_stream,
+        )
+    else:
+        template = resolve_template("plan-template", paths.repo_root)
+        if template is not None and template.is_file():
+            shutil.copy(template, paths.impl_plan)
+            print(f"Copied plan template to {paths.impl_plan}", file=status_stream)
+        else:
+            print("Warning: Plan template not found", file=status_stream)
+            paths.impl_plan.touch()
+
+    if json_mode:
+        sys.stdout.write(
+            _json_line(
+                {
+                    "FEATURE_SPEC": str(paths.feature_spec),
+                    "IMPL_PLAN": str(paths.impl_plan),
+                    "SPECS_DIR": str(paths.feature_dir),
+                    "BRANCH": paths.current_branch,
+                }
+            )
+        )
+    else:
+        print(f"FEATURE_SPEC: {paths.feature_spec}")
+        print(f"IMPL_PLAN: {paths.impl_plan}")
+        print(f"SPECS_DIR: {paths.feature_dir}")
+        print(f"BRANCH: {paths.current_branch}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
--- a/scripts/python/setup_tasks.py
+++ b/scripts/python/setup_tasks.py
@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Check tasks prerequisites and resolve the tasks template."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+try:
+    from common import (
+        FeaturePaths,
+        format_speckit_command,
+        get_feature_paths,
+        resolve_template,
+    )
+except ImportError:  # pragma: no cover - direct execution from unusual cwd
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    from common import (
+        FeaturePaths,
+        format_speckit_command,
+        get_feature_paths,
+        resolve_template,
+    )
+
+
+def _json_line(payload: object) -> str:
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
+
+
+def _help_text(argv0: str) -> str:
+    return f"""Usage: {argv0} [--json]
+  --json    Output results in JSON format
+  --help    Show this help message
+"""
+
+
+def _dir_has_entries(path: Path) -> bool:
+    try:
+        return path.is_dir() and any(path.iterdir())
+    except OSError:
+        return False
+
+
+def _available_docs(paths: FeaturePaths) -> list[str]:
+    docs: list[str] = []
+    if paths.research.is_file():
+        docs.append("research.md")
+    if paths.data_model.is_file():
+        docs.append("data-model.md")
+    if _dir_has_entries(paths.contracts_dir):
+        docs.append("contracts/")
+    if paths.quickstart.is_file():
+        docs.append("quickstart.md")
+    return docs
+
+
+def _check_file(path: Path, description: str) -> None:
+    marker = "✓" if path.is_file() else "✗"
+    print(f"  {marker} {description}")
+
+
+def _check_dir(path: Path, description: str) -> None:
+    marker = "✓" if _dir_has_entries(path) else "✗"
+    print(f"  {marker} {description}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    json_mode = False
+    for arg in list(argv if argv is not None else sys.argv[1:]):
+        if arg == "--json":
+            json_mode = True
+        elif arg in {"--help", "-h"}:
+            sys.stdout.write(_help_text(sys.argv[0]))
+            return 0
+        else:
+            print(f"ERROR: Unknown option '{arg}'", file=sys.stderr)
+            return 1
+
+    try:
+        paths = get_feature_paths(script_file=Path(__file__))
+    except SystemExit as exc:
+        if exc.code == 0:
+            return 0
+        print("ERROR: Failed to resolve feature paths", file=sys.stderr)
+        return int(exc.code) if isinstance(exc.code, int) else 1
+
+    if not paths.impl_plan.is_file():
+        print(f"ERROR: plan.md not found in {paths.feature_dir}", file=sys.stderr)
+        print(
+            f"Run {format_speckit_command('plan', paths.repo_root)} first to create the implementation plan.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if not paths.feature_spec.is_file():
+        print(f"ERROR: spec.md not found in {paths.feature_dir}", file=sys.stderr)
+        print(
+            f"Run {format_speckit_command('specify', paths.repo_root)} first to create the feature structure.",
+            file=sys.stderr,
+        )
+        return 1
+
+    docs = _available_docs(paths)
+
+    tasks_template = resolve_template("tasks-template", paths.repo_root)
+    if tasks_template is None or not tasks_template.is_file():
+        print(
+            "ERROR: Could not resolve required tasks-template from the template "
+            f"override stack for {paths.repo_root}",
+            file=sys.stderr,
+        )
+        print(
+            "Template 'tasks-template' was not found in any supported location "
+            "(overrides, presets, extensions, or shared core). Add an override at "
+            ".specify/templates/overrides/tasks-template.md, or run 'specify init' "
+            "/ reinstall shared infra to restore the core "
+            ".specify/templates/tasks-template.md template.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if json_mode:
+        sys.stdout.write(
+            _json_line(
+                {
+                    "FEATURE_DIR": str(paths.feature_dir),
+                    "AVAILABLE_DOCS": docs,
+                    "TASKS_TEMPLATE": str(tasks_template),
+                }
+            )
+        )
+    else:
+        print(f"FEATURE_DIR: {paths.feature_dir}")
+        print(f"TASKS_TEMPLATE: {tasks_template}")
+        print("AVAILABLE_DOCS:")
+        _check_file(paths.research, "research.md")
+        _check_file(paths.data_model, "data-model.md")
+        _check_dir(paths.contracts_dir, "contracts/")
+        _check_file(paths.quickstart, "quickstart.md")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())