create-new-feature.ps1 missing git branch creation

[AhmedEssa1]

Bug Description

The /specify command (via create-new-feature.ps1) generates a branch name and creates the feature directory structure, but does not create the actual git branch.

Expected Behavior

When running /specify add user authentication, the script should:

1. ✅ Generate branch name (e.g., 001-user-authentication)
2. ✅ Create specs/001-user-authentication/ directory
3. ✅ Create specs/001-user-authentication/spec.md
4. ✅ Save to .specify/feature.json
5. ❌ MISSING: Create and checkout git branch with git checkout -b 001-user-authentication

Actual Behavior

Only steps 1-4 happen. The git branch is never created. Users remain on their current branch (e.g., master or main).

Environment

• Spec Kit version: 0.11.0
• OS: Windows 11
• Script: .specify/scripts/powershell/create-new-feature.ps1

Root Cause

In create-new-feature.ps1 (line 212), after Save-FeatureJson is called, there is no git checkout -b invocation. The Get-CurrentBranch function in common.ps1 only reads from environment variables or .specify/feature.json — it's a virtual branch, not a real git branch.

Suggested Fix

Add after Save-FeatureJson call (around line 212):

# Create git branch for the new feature
try {
    $existingBranches = & git branch --list $branchName 2>$null
    if ($existingBranches) {
        Write-Warning "[specify] Git branch '$branchName' already exists. Checking it out..."
        & git checkout $branchName 2>$null | Out-Null
    } else {
        & git checkout -b $branchName 2>$null | Out-Null
        Write-Output "[specify] Created and checked out git branch: $branchName"
    }
} catch {
    Write-Warning "[specify] Failed to create git branch: $_"
}

This handles:

• New branch creation
• Existing branch checkout (idempotent)
• Error handling if git is unavailable

Impact

Users following Spec-Driven Development workflows expect each feature to be isolated in its own git branch. Without automatic branch creation, users must manually run git checkout -b <branch-name> after every /specify command, which is error-prone and breaks the expected workflow.

[github-actions]

Bug assessment — create-feature-no-branch: Invalid · severity N/A (behavior is by design; see note on documentation gap below)

---

Bug Assessment: create-new-feature.ps1 missing git branch creation

• Slug: create-feature-no-branch
• Created: 2026-06-18
• Source: issue create-new-feature.ps1 missing git branch creation #3050
• Verdict: invalid
• Severity: N/A — not a defect in the code; git branch creation is intentionally delegated to an optional extension

Report (summarized)

Reporter (@AhmedEssa1) observes that running /specify add user authentication on Spec Kit 0.11.0 (Windows 11, PowerShell) creates the spec directory structure and saves .specify/feature.json, but never creates or checks out a git branch. They point to create-new-feature.ps1 line ~212 as the missing call site, and propose adding a git checkout -b block there.

Symptom

After running the /specify command, the script outputs BRANCH_NAME: 001-user-authentication and creates specs/001-user-authentication/spec.md, but no corresponding git branch is created or checked out. Users must manually run git checkout -b <name> after every invocation.

Reproduction

1. Install Spec Kit 0.11.0 on Windows 11 (no git extension installed).
2. Open a repo in an agent that uses the standard specify.md command template.
3. Run /specify add user authentication.
4. Observe: specs/001-user-authentication/spec.md is created, feature.json is written, environment variables are set.
5. Run git branch — no new branch is listed.

[NEEDS CLARIFICATION: Whether the git extension (specify extension add git) was installed and enabled at time of testing.]

Suspected Code Paths

• scripts/powershell/create-new-feature.ps1:197–217 — core spec-directory creation; intentionally omits any git call; sets SPECIFY_FEATURE env var but does not run git checkout -b.
• scripts/bash/create-new-feature.sh:239–267 — bash equivalent; same design.
• extensions/git/scripts/powershell/create-new-feature-branch.ps1:328–384 — the script that does run git checkout -q -b $branchName; only invoked when the git extension is active.
• extensions/git/scripts/bash/create-new-feature-branch.sh:381–416 — bash equivalent; same.
• extensions/git/extension.yml:48–50 — declares before_specify hook (speckit.git.feature, optional: false) that drives branch creation.
• templates/commands/specify.md:22–53 — the core /specify command template; checks for and runs before_specify hooks before creating the spec directory.

Root Cause Hypothesis

There is no bug in the scripts. Git branch creation is intentionally separated into the optional git extension (extensions/git/). The architecture is:

• create-new-feature.ps1 / create-new-feature.sh (core): creates spec directory, spec.md, feature.json, and env vars only.
• create-new-feature-branch.ps1 / create-new-feature-branch.sh (git extension): creates the actual git branch via git checkout -b.
• The git extension registers a mandatory before_specify hook that fires the branch script before the core spec-directory step when the extension is enabled.

If a user does not have the git extension installed (specify extension add git), no branch is created — this is expected and documented behavior. The core command template (templates/commands/specify.md) explicitly notes: "The spec directory name and the git branch name are independent."

Confidence: high — confirmed by reading all four script files and extension.yml.

Proposed Remediation

Preferred — No code change needed; close as invalid with guidance:
The reporter should install the bundled git extension:

specify extension add git

Once installed and enabled, the before_specify hook fires automatically on every /specify invocation, creates the git branch, and the core script then creates the spec directory. The extension handles edge cases (existing branches, graceful degradation when git is absent, idempotency via --allow-existing-branch).

Alternatives:

• If the user intentionally does not want the git extension (e.g., they manage branches themselves), the current behavior is correct and the output BRANCH_NAME gives them the name to use manually.
• If a future design decision was made to always create branches in the core script, that would couple git into a currently git-free script and remove the ability to use Spec Kit without git. This is not recommended.

Files likely to change: None (no code fix warranted).

Tests to add or update: None required for this report; existing test coverage for create-new-feature-branch.ps1 / .sh already validates branch creation in the git extension.

---

Secondary observation — scaffold preset wording:
presets/scaffold/commands/speckit.specify.md (step 1) says "Create the feature branch by running the script" and references create-new-feature.sh / create-new-feature.ps1, which do not create git branches. The word "branch" here refers loosely to the feature directory, but this wording could mislead users (and likely contributed to this report). A clarifying rename of that label to "Create the feature directory" would remove ambiguity. This is a documentation issue, not a code bug, and is low priority given the scaffold preset is a template for building custom presets rather than a user-facing preset.

Risks & Considerations

• Adding git checkout -b to the core scripts (as the reporter suggests) would break projects that use Spec Kit without git, or that manage branches via a different tool — contrary to the design principle of graceful degradation.
• The git extension already handles all the edge cases the reporter's proposed fix attempts to cover (idempotency, error handling, no-git warning).

Open Questions

• [NEEDS CLARIFICATION: Was specify extension add git ever run in this project? If so, is the extension enabled (specify extension list)?]
• [NEEDS CLARIFICATION: Is the user using a custom preset that overrides the /specify command, e.g., the scaffold preset? That preset calls create-new-feature.ps1 directly without hook awareness.]

Generated by 🐛 Assess Bug from Labeled Issue for issue #3050 · 262.1 AIC · ⌖ 13.5 AIC · ⊞ 31.2K · ◷

[mnriem]

Please add the Git extension to your project using:

specify extension add git