Extract Git/Branching Operations into `extensions/git` Extension (Opt-Out, Auto-Enabled)

[mnriem]

Summary

Extract all Git-related operations (repository detection, branch creation, branch numbering, branch validation, remote fetching, SPECIFY_FEATURE env var management) from core into a self-contained Spec Kit extension at extensions/git/. The extension auto-enables by default during the migration period (opt-out) to preserve backward compatibility. Before the 1.0.0 release, the extension will transition to opt-in — users will explicitly install it via specify extension add git or a preset that includes it.

Scope note: The --no-git flag on specify init is out of scope for this issue and will be handled separately.

Problem

Git branching logic is deeply interwoven across ~815+ lines in 10+ files spanning 4 languages (Python, Bash, PowerShell, Markdown). Analysis of upstream issues reveals this coupling causes problems across five distinct categories — not just maintenance burden, but workflow lock-in, blocked extensibility, spec iteration friction, and contributor barriers. See the original problem analysis in the collapsed section below for the full breakdown.

Delivered Solution

The extraction was implemented incrementally via a hook-based architecture rather than the originally planned "rip and replace" approach. This preserves backward compatibility while cleanly separating git operations from core.

Stage 1 — PR #1941 (merged)

Created extensions/git/ with the extension manifest, commands, hooks, and scripts:

extensions/git/
    extension.yml
    git-config.yml                    # Branch numbering config
    commands/
        speckit.git.feature.md        # Branch creation
        speckit.git.validate.md       # Branch validation
        speckit.git.commit.md         # Auto-commit
        speckit.git.remote.md         # Remote URL detection
        speckit.git.initialize.md     # Git repo initialization
    scripts/
        bash/
            create-new-feature.sh     # Moved from scripts/bash/
            git-common.sh             # Git-specific subset of common.sh
            initialize-repo.sh
        powershell/
            create-new-feature.ps1    # Moved from scripts/powershell/
            git-common.ps1            # Git-specific subset of common.ps1
            initialize-repo.ps1

Key deliverables:

• Extension manifest with commands, hooks, and config.defaults
• speckit.git.feature creates branches with sequential or timestamp numbering
• speckit.git.validate validates feature branch naming conventions
• speckit.git.remote detects Git remote URL for GitHub integration
• speckit.git.commit auto-commits at hook points (optional)
• speckit.git.initialize initializes Git repos
• before_specify, before_constitution, and all other lifecycle hooks registered
• Auto-install during specify init (unless --no-git)
• Graceful degradation when git unavailable
• Cross-platform bash and PowerShell scripts
• Extension commands include explicit script paths (no {SCRIPT} placeholder reliance)
• Extension reads branch_numbering from its own config (.specify/extensions/git/git-config.yml)

Stage 2 — PR #2117 (open)

Enhanced the extension and CLI with:

• GIT_BRANCH_NAME env var override for exact branch naming (parallels SPECIFY_FEATURE_DIRECTORY)
• --force flag for specify init <dir> into existing directories
• Test coverage: TestGitExtensionAutoInstall (3 tests), TestFeatureDirectoryResolution (4 tests)
• All 1,195 tests passing, 0 failures

What Moved Out of Core

From Core	To Extension	Status
Branch creation logic	speckit.git.feature command + scripts	✅ Done
Branch validation	speckit.git.validate command	✅ Done
Remote URL detection	speckit.git.remote command	✅ Done
create-new-feature.sh	extensions/git/scripts/bash/	✅ Done
create-new-feature.ps1	extensions/git/scripts/powershell/	✅ Done
check_feature_branch()	Duplicated to git-common.sh	✅ Done (core copy retained for backward compat)
--branch-numbering config	git-config.yml in extension	✅ Done (CLI flag retained for backward compat)
Branch creation section of specify.md	Hook-based via before_specify	✅ Done

What Stays in Core (by design)

Component	Reason
--no-git flag	Out of scope; handled separately
get_current_branch() in common.sh/.ps1	Called by all downstream commands; not git-specific
SPECIFY_FEATURE env var check	Core feature detection, not git-specific
specs/ directory scanning fallback	Non-git feature detection
find_feature_dir_by_prefix()	Spec directory resolution (works without git)
check_feature_branch() in core common.sh	Called by setup-plan.sh and check-prerequisites.sh; removing would break scripts when git extension is disabled
--branch-numbering CLI flag	Backward compatibility; writes to init-options.json which the extension reads as fallback

Extension Enable/Disable Behavior

The specify extension disable git and specify extension enable git commands already exist and work correctly. When disabled:

• before_specify and other hooks don't fire (hook executor checks enabled status)
• Spec directories are still created (core behavior, independent of git)
• Identical to HAS_GIT=false behavior in scripts

Remaining Work (pre-1.0.0)

• Deprecate --branch-numbering CLI flag on init() with a warning pointing to .specify/extensions/git/git-config.yml (breaking change deferred to 1.0.0)
• Add explicit test for specify extension disable git → verify no branch operations occur
• Transition extension from auto-install (opt-out) to opt-in at 1.0.0 (remove auto-install code from init())

Acceptance Criteria

• extensions/git/extension.yml manifest with commands, hooks, and config.defaults
• speckit.git.feature command creates branches with sequential or timestamp numbering
• speckit.git.validate command validates feature branch naming conventions
• speckit.git.remote command detects Git remote URL for GitHub integration
• before_specify hook registered; specify.md template conditionally runs branching via hooks
• Extension commands include explicit script paths (no reliance on {SCRIPT} placeholder)
• Extension reads branch_numbering from its own config (.specify/extensions/git/git-config.yml)
• Extension degrades gracefully when git is not installed (warnings, no errors)
• specify extension disable git stops all branch operations without breaking spec creation
• specify extension enable git re-enables branch operations
• Auto-install logic added to specify init for bundled git extension
• All existing branching tests pass when run against the extension (1,195/1,195)
• Cross-platform: Bash and PowerShell scripts both in extension
• get_current_branch() remains intact in core common.sh/.ps1
• SPECIFY_FEATURE environment variable continues to work (stays in core)
• specify.md template conditionally includes branching based on hook system
• No regression in --no-git behavior
• GIT_BRANCH_NAME env var override for exact branch naming
• --branch-numbering CLI flag deprecated (pre-1.0.0)
• Auto-install transitions to opt-in (at 1.0.0)

Related Issues & PRs

#	Title	Status	Relevance	Signal
#841	Support disabling automatic branch creation via parameter	open	Resolved: specify extension disable git	25 👍
#1382	Custom namespacing and branch naming conventions	open	Unblocked: GIT_BRANCH_NAME env var + extension config	18 👍
#1066	Branch numbering repeats 001- prefix	open	Fix scope narrowed to extension	13 👍
#1921	Make branch creation configurable (branchStrategy)	open	Resolved by extension config	1 👍
#1901	Allow agent-namespaced branches (copilot/**)	open	Enabled via GIT_BRANCH_NAME	—
#1165	Different commands produce/expect different branch name syntax	open	Validation now in extension	—
#1191	Can't easily update or refine existing specs	open	Hook-based branching is optional	107 👍
#1941	PR: Git extension stage 1	merged	Phase 1+2 delivery	—
#2117	PR: Git extension stage 2	open	GIT_BRANCH_NAME, --force, tests	—

Original Problem Analysis

The scope of the coupling

File	Language	Git Lines	Operations
src/specify_cli/__init__.py	Python	~80	is_git_repo() (L634), init_git_repo() (L654), --branch-numbering validation (L1826), git init orchestration (L2100-2135), branch_numbering in init-options (L2146)
scripts/bash/create-new-feature.sh	Bash	~130	git branch -a, git fetch --all --prune, git checkout -b, git branch --list, branch number extraction, name generation, 244-byte validation
scripts/bash/common.sh	Bash	~95	get_repo_root(), get_current_branch(), has_git(), check_feature_branch(), find_feature_dir_by_prefix(), SPECIFY_FEATURE env var handling
scripts/powershell/create-new-feature.ps1	PowerShell	~120	PowerShell equivalents of all bash git operations
scripts/powershell/common.ps1	PowerShell	~75	PowerShell equivalents of all common.sh git operations
templates/commands/specify.md	Markdown	~35	Branch creation instructions, init-options.json reading for branch_numbering, script invocation with --timestamp/--short-name
templates/commands/implement.md	Markdown	1	git rev-parse --git-dir for .gitignore creation
templates/commands/taskstoissues.md	Markdown	5	git config --get remote.origin.url for GitHub issue creation
tests/test_branch_numbering.py	Python	69	6 tests for branch numbering persistence and validation
tests/test_timestamp_branches.py	Python	280	15 tests covering timestamp/sequential branching end-to-end

Impact of this coupling:

1. Workflow lock-in — users who don't want branching can't adopt spec-kit (Feature Request: Support disabling automatic branch creation via parameter #841, 25 reactions; [Feature]: Make branch creation configurable #1921)
2. Blocked extensibility — users who want different branching need core surgery ([Feature request] Custom namespacing and branch naming conventions #1382, 18 reactions; [Feature]: Allow agent-namespaced branches (claude/**, copilot/**, etc.) to bypass numeric prefix requirement #1901)
3. Spec iteration friction — mandatory branching makes spec refinement expensive (Spec-Driven Editing Flow: Can't Easily Update or Refine Existing Specs #1191, 107 reactions)
4. Maintenance burden — every branching enhancement touches 4+ files across 3 languages
5. Contributor barrier — PRs are large and complex because branching touches everything

[gabrielhmsantos]

Is there any intention to remove branch name validation from common.sh or to allow branch prefixes?

Currently, we have git as an extension and the branch-convention extension that adjusts the branch name, and when running scripts like check-prerequisites and setup-plan, it returns an error because the branch does not follow the NNN-feature-name pattern.

If it's okay, I can open a PR, a small correction to the Regex in common.sh in the check_feature_branch() function.

Something like:

if [[ "$branch" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*/(.+)$ ]]; then

branch="${BASH_REMATCH[1]}"

fi

Before the if check of is_sequential, to remove any prefix, and continue with the evaluation normally.

[mnriem]

The intent was to make all Git functionality flow through the Git extension so it can be disabled when so desired. So yea common.sh should not do that validation. But we'll have to check to make sure that we still have the equivalent. If you have time then yes please open a PR

[gabrielhmsantos]

I ran some tests on new repositories and I believe it was a poor initialization.

Everything went well, but I found some issues regarding how the cursor agent interacts with commands; I opened this issue for evaluation. #2149