Potential bug with the create-new-feature.ps1 script that ignores existing feature branches when determining next feature number

[fgalarraga]

Description

The PowerShell script .specify/scripts/powershell/create-new-feature.ps1 only checks the specs/ directory on the current branch to determine the next feature number, but does not check existing branch names. This causes numbering conflicts when working with multiple feature branches that haven't been merged to main.

Expected Behavior

When running the script from main, it should:

1. Check the specs/ directory for existing spec folders with pattern \d{3}-*
2. Also check git branch output for existing branches with pattern \d{3}-*
3. Use the highest number found from either source
4. Increment by 1 to determine the next feature number

Current Behavior

The script only checks step 1 (specs directory on current branch). If feature branches exist but haven't been merged to main, the script will reuse feature numbers, creating conflicts.

Reproduction Steps

1. Initialize a new spec-kit project
2. From main branch, run the script to create feature 001:

   .\.specify\scripts\powershell\create-new-feature.ps1 -ShortName "first-feature"

   • Creates branch 001-first-feature
   • Creates specs/001-first-feature/ directory
3. Push branch 001-first-feature to remote (do NOT merge to main)
4. Checkout main again
5. Run the script to create feature 002:

   .\.specify\scripts\powershell\create-new-feature.ps1 -ShortName "second-feature"

Expected: Creates branch 002-second-feature
Actual: Creates branch 001-second-feature (reuses 001)

Root Cause

Looking at lines 82-92 of create-new-feature.ps1:

$existingSpecs = Get-ChildItem -Path $specsDir -Directory -ErrorAction SilentlyContinue |
    Where-Object { $_.Name -match '^\d{3}' } |
    ForEach-Object {
        if ($_.Name -match '^(\d{3})') {
            [int]$matches[1]
        }
    } |
    Sort-Object -Descending |
    Select-Object -First 1

The script only checks directories in $specsDir, not branch names via git branch.

Suggested Fix

Add branch checking logic before determining feature number:

# Get highest number from specs directory
$existingSpecs = Get-ChildItem -Path $specsDir -Directory -ErrorAction SilentlyContinue |
    Where-Object { $_.Name -match '^\d{3}' } |
    ForEach-Object {
        if ($_.Name -match '^(\d{3})') {
            [int]$matches[1]
        }
    } |
    Sort-Object -Descending |
    Select-Object -First 1

# Get highest number from branch names
$existingBranches = git branch -a | 
    ForEach-Object { $_.Trim() -replace '^\*?\s+', '' -replace '^remotes/origin/', '' } |
    Where-Object { $_ -match '^\d{3}-' } |
    ForEach-Object {
        if ($_ -match '^(\d{3})') {
            [int]$matches[1]
        }
    } |
    Sort-Object -Descending |
    Select-Object -First 1

# Use the highest number from either source
$highestExisting = [Math]::Max(
    $(if ($existingSpecs) { $existingSpecs } else { 0 }),
    $(if ($existingBranches) { $existingBranches } else { 0 })
)

$featureNumber = $highestExisting + 1

Workaround

Until fixed, merge spec directories to main after creating each feature branch, so the next run can see the previous feature number in the specs directory.

Environment

• OS: Windows 11
• PowerShell Version: 7.5.4
• spec-kit: v0.0.20

[fgalarraga]

✅ Fix Verified and Tested

I can confirm the proposed fix works correctly! Here are the test results:

Test Setup

1. Applied the suggested fix to create-new-feature.ps1 (checking both specs/ directory AND git branches)
2. Committed the fix to a fix/branch-numbering-detection branch
3. Merged the fix to main branch
4. Ran sequential feature creation tests

Test Results

Test 1 - Create First Feature:

# From main branch
/speckit.specify -ShortName "first-feature" Create a test feature to verify branch numbering

• ✅ Created branch: 001-first-feature
• ✅ Committed and pushed to remote
• ✅ Returned to main branch

Test 2 - Create Second Feature (The Critical Test):

# From main branch (001-first-feature exists ONLY on remote, not merged to main)
/speckit.specify -ShortName "second-feature" Create another test feature to verify incremental numbering

• ✅ Created branch: 002-second-feature (NOT 001-second-feature)
• ✅ Correctly detected the existing 001-first-feature branch on remote
• ✅ Incremented to 002 as expected

Fix Confirmation

The fix successfully:

• ✅ Detects existing feature branches from remote repository
• ✅ Prevents duplicate branch numbers
• ✅ Works correctly even when feature branches haven't been merged to main
• ✅ Checks both specs/ directory AND branch names
• ✅ Uses the highest number from either source

Implementation Details

The fix adds branch detection logic that:

1. Scans all branches (local and remote) using git branch -a
2. Strips remote prefixes (remotes/origin/)
3. Extracts numeric prefixes matching ^\d{3}- pattern
4. Compares highest number from branches vs. specs/ directory
5. Uses [Math]::Max() to determine the starting point
6. Increments by 1

Code Added

# Get highest number from branch names
$existingBranches = git branch -a | 
    ForEach-Object { $_.Trim() -replace '^\*?\s+', '' -replace '^remotes/origin/', '' } |
    Where-Object { $_ -match '^\d{3}-' } |
    ForEach-Object {
        if ($_ -match '^(\d{3})') {
            [int]$matches[1]
        }
    } |
    Sort-Object -Descending |
    Select-Object -First 1

# Use the highest number from either source
$highestExisting = [Math]::Max(
    $(if ($existingSpecs) { $existingSpecs } else { 0 }),
    $(if ($existingBranches) { $existingBranches } else { 0 })
)

$featureNumber = $highestExisting + 1

This fix resolves the issue completely and enables the proper workflow of creating multiple feature branches in parallel without requiring merges to main for correct numbering.

[maxmeyer3141]

HI there, i think this won't completly fix the problem with the branch numbering when using coding agents because the speckit.specify command prompt template instructs the agent to call the script with the Number parameter which bypasses this solution.
I suggest to update the git commands in https://github.com/github/spec-kit/blob/main/templates/commands/specify.md aswell.

Template (Source)

b. Find the highest feature number across all sources for the short-name:
- Remote branches: git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'
- Local branches: git branch | grep -E '^[* ]*[0-9]+-<short-name>$'
- Specs directories: Check for directories matching `specs/[0-9]+-``

Template (fix)

b. Find the highest feature number across all sources for the short-name:
- Remote branches: git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-$'
- Local branches: git branch | grep -E '^[* ]*[0-9]+-$'
- Specs directories: Check for directories matching specs/[0-9]+-

Am i correct?

[MisinformedDNA]

Yep, still an issue with Github Copilot.