Support predictable branch name allocation and external branch creation

[rhuss]

Context

I maintain cc-sdd, a Claude Code plugin that adds trait overlays on top of spec-kit. It uses spec-kit's core workflow as-is (speckit.specify, speckit.plan, speckit.tasks, speckit.implement). The plugin adds quality gates, parallel implementation via agent teams, and git worktree isolation.

The worktrees trait creates a sibling git worktree after speckit.specify. This lets the user continue planning and implementing in an isolated directory without disrupting other Claude Code sessions on main.

Problem

create-new-feature.sh currently couples two concerns:

1. Branch name allocation (scanning branches + specs for the next NNN number, generating a clean suffix)
2. Branch creation (git checkout -b)

This coupling blocks a workflow where the worktree and branch get created before speckit.specify runs. Two specific issues:

• Standalone worktree creation: A user runs /sdd:worktree create "feature description" to set up branch + worktree upfront. They then run /speckit.specify inside the worktree. But create-new-feature.sh fails with "Branch already exists" because the branch was created externally.

• Branch name prediction: To create the worktree, we need the branch name before speckit.specify runs. The only way to get it today is calling create-new-feature.sh, which also creates the branch as a side effect.

Related Issues

This touches on a recurring theme in the spec-kit issue tracker:

• [Feature]: Support using existing branch (without auto branch creation) #1680 - Support using existing branch (without auto branch creation): same core ask, from teams whose CI/CD creates branches externally
• Native git worktree Support for Concurrent/Parallel Agent Execution #1476 - Native git worktree support for concurrent agent execution: the parallel agent isolation use case that our worktrees trait addresses
• Add ability to spawn worktree when creating new branch #61 - Add ability to spawn worktree when creating new branch: earliest request for worktree integration
• [Feature]: Make branch creation configurable #1921 - Make branch creation configurable: proposes branchStrategy: "auto" | "none" | "manual"
• Feature Request: Support disabling automatic branch creation via parameter #841 - Support disabling automatic branch creation via parameter: asks for --no-branch flag

Our proposal complements these requests. Rather than disabling branch creation entirely, we're asking for the ability to decouple name allocation from branch creation, which would also help resolve several of the issues above.

Proposal

Two small changes would enable these use cases:

1. Dry-run / name-only mode

A --dry-run or --name-only flag that runs the number allocation and name generation but skips branch creation and spec directory setup:

create-new-feature.sh --json --dry-run "Add user authentication"
# → {"BRANCH_NAME":"008-user-authentication","SPEC_FILE":"specs/008-user-authentication/spec.md","FEATURE_NUM":"008"}

External tools could then predict the branch name without side effects.

2. Tolerate pre-existing branches

When create-new-feature.sh detects that the target branch already exists and we're already on it, it should treat that as a no-op instead of failing. The script would still create the spec directory and template if they're missing.

# Currently fails:
git checkout -b 008-user-auth  # branch exists → error

# Proposed: detect and skip
if git rev-parse --verify "$BRANCH_NAME" >/dev/null 2>&1; then
    git checkout "$BRANCH_NAME"  # switch to it instead of creating
fi

This would let speckit.specify work correctly inside a worktree created externally with the right branch name.

Alternatives Considered

• Duplicating the numbering logic in our plugin. This works but creates drift risk as spec-kit's allocation algorithm changes.
• Calling create-new-feature.sh from the plugin, then restoring main. That's the current approach for the post-specify worktree flow. It works, but it forces a specific ordering (specify first, worktree second) that doesn't fit every workflow.

Impact

Both changes are backward-compatible and don't affect existing workflows. The --dry-run flag would also help other extensions that need to pre-allocate or preview branch names, such as CI integrations or project dashboards.

Happy to contribute a PR if the maintainers agree with the direction.

[mnriem]

PR #1941 is in flight to move the Git functionality wholesale to a new extension. This is to facilitate isolating Git related functionality to this extension so it does not touch core files and to make it possible for something to NOT use it altogether. Would that serve your purpose?

[rhuss]

Thanks for pointing to #1941, @mnriem. The direction makes sense. Isolating git operations into an extension is a cleaner foundation than scattering branch logic across core files.

That said, a full disable git switch is too coarse for what we need. Our worktrees trait wants spec-kit's numbering logic (the NNN-feature-name allocation) but needs to control the timing of branch creation. Disabling the extension entirely would force us to reimplement numbering, which creates drift risk as the algorithm evolves.

Two narrower capabilities would close the gap, and they'd fit naturally into the git extension:

1. Name-only / dry-run mode on the feature command, so external tools can query the next branch name without side effects
2. Tolerate pre-existing branches, so speckit.specify works correctly when run inside a worktree where the branch was created externally

Both are additive and backward-compatible. Happy to contribute them as a follow-up once #1941 lands, if that works for you.

[mnriem]

That is what presets are for. If you need a slight variation of any extension for your own organization you can overlay your own specific preset. See https://github.com/github/spec-kit/tree/main/presets Would that work for your scenario?