refactor: remove all git operations from core

- Remove is_git_repo() and init_git_repo() dead code from _utils.py
- Remove --branch-numbering from init command
- Remove git from 'specify check' (now extension-only)
- Update docs: git is optional prerequisite, check command description
- Fix tests to reflect no-git-in-core reality (fallback to main)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mnriem

docs/installation.md

@@ -6,7 +6,7 @@
 - AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), [Codebuddy CLI](https://www.codebuddy.ai/cli), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [Pi Coding Agent](https://pi.dev)
 - [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pipx.pypa.io/) for persistent installation
 - [Python 3.11+](https://www.python.org/downloads/)
-- [Git](https://git-scm.com/downloads)
+- [Git](https://git-scm.com/downloads) _(optional — required only when the git extension is enabled)_
 
 ## Installation
 

docs/reference/core.md

@@ -17,12 +17,11 @@ specify init [<project_name>]
 | `--force`                | Force merge/overwrite when initializing in an existing directory         |
 | `--ignore-agent-tools`   | Skip checks for AI coding agent CLI tools                                |
 | `--preset <id>`          | Install a preset during initialization                                   |
-| `--branch-numbering`     | Branch numbering strategy: `sequential` (default) or `timestamp`         |
 
 Creates a new Spec Kit project with the necessary directory structure, templates, scripts, and AI coding agent integration files.
 
 > [!NOTE]
-> The git extension is opt-in during `specify init`. To add it after init, run `specify extension add git`.
+> Git repository initialization and branching are managed by the **git extension**, which is not installed by default. Run `specify extension add git` after init to enable git workflows.
 
 Use `<project_name>` to create a new directory, or `--here` (or `.`) to initialize in the current directory. If the directory already has files, use `--force` to merge without confirmation.
 
@@ -45,9 +44,6 @@ specify init my-project --integration copilot --script ps
 
 # Install a preset during initialization
 specify init my-project --integration copilot --preset compliance
-
-# Use timestamp-based branch numbering (useful for distributed teams)
-specify init my-project --integration copilot --branch-numbering timestamp
 ```
 
 ### Environment Variables
@@ -62,7 +58,7 @@ specify init my-project --integration copilot --branch-numbering timestamp
 specify check
 ```
 
-Checks that required tools are available on your system: `git` and any CLI-based AI coding agents. IDE-based agents are skipped since they don't require a CLI tool.
+Checks that CLI-based AI coding agents are available on your system. IDE-based agents are skipped since they don't require a CLI tool.
 
 This command stays offline. If a command behaves like an older Spec Kit version or an expected CLI feature is missing, run `specify self check` to check whether your local CLI is behind the latest release.
 

src/specify_cli/__init__.py

@@ -69,8 +69,6 @@
     _display_project_path,
     check_tool as check_tool,
     handle_vscode_settings as handle_vscode_settings,
-    init_git_repo as init_git_repo,
-    is_git_repo as is_git_repo,
     merge_json_files as merge_json_files,
     run_command as run_command,
 )
@@ -453,9 +451,6 @@ def check():
 
     tracker = StepTracker("Check Available Tools")
 
-    tracker.add("git", "Git version control")
-    git_ok = check_tool("git", tracker=tracker)
-
     agent_results = {}
     for agent_key, agent_config in AGENT_CONFIG.items():
         if agent_key == "generic":
@@ -483,9 +478,6 @@ def check():
 
     console.print("\n[bold green]Specify CLI is ready to use![/bold green]")
 
-    if not git_ok:
-        console.print("[dim]Tip: Install git for repository management[/dim]")
-
     if not any(agent_results.values()):
         console.print("[dim]Tip: Install a coding agent for the best experience[/dim]")
 

src/specify_cli/_utils.py

@@ -77,51 +77,6 @@ def check_tool(tool: str, tracker=None) -> bool:
     return found
 
 
-def is_git_repo(path: Path | None = None) -> bool:
-    """Check if the specified path is inside a git repository."""
-    if path is None:
-        path = Path.cwd()
-
-    if not path.is_dir():
-        return False
-
-    try:
-        subprocess.run(
-            ["git", "rev-parse", "--is-inside-work-tree"],
-            check=True,
-            capture_output=True,
-            cwd=path,
-        )
-        return True
-    except (subprocess.CalledProcessError, FileNotFoundError):
-        return False
-
-
-def init_git_repo(project_path: Path, quiet: bool = False) -> tuple[bool, str | None]:
-    """Initialize a git repository in the specified path."""
-    try:
-        original_cwd = Path.cwd()
-        os.chdir(project_path)
-        if not quiet:
-            console.print("[cyan]Initializing git repository...[/cyan]")
-        subprocess.run(["git", "init"], check=True, capture_output=True, text=True)
-        subprocess.run(["git", "add", "."], check=True, capture_output=True, text=True)
-        subprocess.run(["git", "commit", "-m", "Initial commit from Specify template"], check=True, capture_output=True, text=True)
-        if not quiet:
-            console.print("[green]✓[/green] Git repository initialized")
-        return True, None
-    except subprocess.CalledProcessError as e:
-        error_msg = f"Command: {' '.join(e.cmd)}\nExit code: {e.returncode}"
-        if e.stderr:
-            error_msg += f"\nError: {e.stderr.strip()}"
-        elif e.stdout:
-            error_msg += f"\nOutput: {e.stdout.strip()}"
-        if not quiet:
-            console.print(f"[red]Error initializing git repository:[/red] {e}")
-        return False, error_msg
-    finally:
-        os.chdir(original_cwd)
-
 
 def handle_vscode_settings(sub_item, dest_file, rel_path, verbose=False, tracker=None) -> None:
     """Handle merging or copying of .vscode/settings.json files.

src/specify_cli/commands/init.py

@@ -78,7 +78,6 @@ def init(
         github_token: str = typer.Option(None, "--github-token", help="Deprecated (no-op). Previously: GitHub token for API requests.", hidden=True),
         offline: bool = typer.Option(False, "--offline", help="Deprecated (no-op). All scaffolding now uses bundled assets.", hidden=True),
         preset: str = typer.Option(None, "--preset", help="Install a preset during initialization (by preset ID)"),
-        branch_numbering: str = typer.Option(None, "--branch-numbering", help="Branch numbering strategy: 'sequential' (001, 002, …, 1000, … — expands past 999 automatically) or 'timestamp' (YYYYMMDD-HHMMSS)"),
         integration: str = typer.Option(None, "--integration", help="AI coding agent integration to use (e.g. --integration copilot). See 'specify check' for available integrations."),
         integration_options: str = typer.Option(None, "--integration-options", help='Options for the integration (e.g. --integration-options="--commands-dir .myagent/cmds")'),
     ):
@@ -151,10 +150,7 @@ def init(
             console.print("[red]Error:[/red] Must specify either a project name, use '.' for current directory, or use --here flag")
             raise typer.Exit(1)
 
-        BRANCH_NUMBERING_CHOICES = {"sequential", "timestamp"}
-        if branch_numbering and branch_numbering not in BRANCH_NUMBERING_CHOICES:
-            console.print(f"[red]Error:[/red] Invalid --branch-numbering value '{branch_numbering}'. Choose from: {', '.join(sorted(BRANCH_NUMBERING_CHOICES))}")
-            raise typer.Exit(1)
+
 
         dir_existed_before = False
         if here:
@@ -383,7 +379,6 @@ def init(
                 init_opts = {
                     "ai": selected_ai,
                     "integration": resolved_integration.key,
-                    "branch_numbering": branch_numbering or "sequential",
                     "here": here,
                     "script": selected_script,
                     "speckit_version": get_speckit_version(),

tests/integrations/test_integration_base_toml.py

@@ -467,6 +467,7 @@ def test_init_options_includes_context_file(self, tmp_path):
             os.chdir(project)
             result = CliRunner().invoke(app, [
                 "init", "--here", "--integration", self.KEY, "--script", "sh",
+                "--ignore-agent-tools",
             ], catch_exceptions=False)
         finally:
             os.chdir(old_cwd)

tests/integrations/test_integration_base_yaml.py

@@ -346,6 +346,7 @@ def test_init_options_includes_context_file(self, tmp_path):
             os.chdir(project)
             result = CliRunner().invoke(app, [
                 "init", "--here", "--integration", self.KEY, "--script", "sh",
+                "--ignore-agent-tools",
             ], catch_exceptions=False)
         finally:
             os.chdir(old_cwd)

tests/integrations/test_integration_subcommand.py

@@ -960,7 +960,7 @@ def test_switch_does_not_register_disabled_extensions(self, tmp_path):
     def test_switch_refreshes_managed_shared_script_refs(self, tmp_path):
         """Switching refreshes managed shared scripts to the target command style."""
         project = _init_project(tmp_path, "claude")
-        shared_script = project / ".specify" / "scripts" / "bash" / "common.sh"
+        shared_script = project / ".specify" / "scripts" / "bash" / "setup-tasks.sh"
         assert shared_script.exists()
         shared_content = shared_script.read_text(encoding="utf-8")
         assert "/speckit-plan" in shared_content
@@ -986,7 +986,7 @@ def test_switch_refreshes_stale_managed_shared_infra(self, tmp_path):
         import hashlib
 
         project = _init_project(tmp_path, "claude")
-        shared_script = project / ".specify" / "scripts" / "bash" / "common.sh"
+        shared_script = project / ".specify" / "scripts" / "bash" / "setup-tasks.sh"
         assert "/speckit-plan" in shared_script.read_text(encoding="utf-8")
 
         # Simulate a stale vendored script: write truncated content as bytes
@@ -998,7 +998,7 @@ def test_switch_refreshes_stale_managed_shared_infra(self, tmp_path):
 
         manifest_path = project / ".specify" / "integrations" / "speckit.manifest.json"
         manifest_data = json.loads(manifest_path.read_text(encoding="utf-8"))
-        manifest_data["files"][".specify/scripts/bash/common.sh"] = (
+        manifest_data["files"][".specify/scripts/bash/setup-tasks.sh"] = (
             hashlib.sha256(stale_bytes).hexdigest()
         )
         manifest_path.write_text(json.dumps(manifest_data), encoding="utf-8")
@@ -1047,7 +1047,7 @@ def test_switch_preserves_user_customized_shared_infra(self, tmp_path):
     def test_switch_refresh_shared_infra_overwrites_customizations(self, tmp_path):
         """--refresh-shared-infra explicitly overwrites user customizations on switch."""
         project = _init_project(tmp_path, "claude")
-        shared_script = project / ".specify" / "scripts" / "bash" / "common.sh"
+        shared_script = project / ".specify" / "scripts" / "bash" / "setup-tasks.sh"
         assert "/speckit-plan" in shared_script.read_text(encoding="utf-8")
         rendered_bytes = shared_script.read_bytes()
 

tests/test_branch_numbering.py

@@ -1,74 +1,24 @@
 """
-Unit tests for branch numbering options (sequential vs timestamp).
+Unit tests verifying --branch-numbering removal (v0.10.0).
 
-Tests cover:
-- Persisting branch_numbering in init-options.json
-- Default value when branch_numbering is None
-- Validation of branch_numbering values
+Branch numbering is now managed entirely by the git extension's config.
+The --branch-numbering flag was removed from `specify init`.
 """
 
-import json
 from pathlib import Path
 
-from specify_cli import save_init_options
 
+class TestBranchNumberingFlagRemoved:
+    """--branch-numbering flag was removed in v0.10.0."""
 
-class TestSaveBranchNumbering:
-    """Tests for save_init_options with branch_numbering."""
-
-    def test_save_branch_numbering_timestamp(self, tmp_path: Path):
-        opts = {"branch_numbering": "timestamp", "ai": "claude"}
-        save_init_options(tmp_path, opts)
-
-        saved = json.loads((tmp_path / ".specify/init-options.json").read_text())
-        assert saved["branch_numbering"] == "timestamp"
-
-    def test_save_branch_numbering_sequential(self, tmp_path: Path):
-        opts = {"branch_numbering": "sequential", "ai": "claude"}
-        save_init_options(tmp_path, opts)
-
-        saved = json.loads((tmp_path / ".specify/init-options.json").read_text())
-        assert saved["branch_numbering"] == "sequential"
-
-    def test_branch_numbering_defaults_to_sequential(self, tmp_path: Path):
-        from typer.testing import CliRunner
-        from specify_cli import app
-
-        project_dir = tmp_path / "proj"
-        runner = CliRunner()
-        result = runner.invoke(app, ["init", str(project_dir), "--integration", "claude", "--ignore-agent-tools", "--script", "sh"])
-        assert result.exit_code == 0
-
-        saved = json.loads((project_dir / ".specify/init-options.json").read_text())
-        assert saved["branch_numbering"] == "sequential"
-
-
-class TestBranchNumberingValidation:
-    """Tests for branch_numbering CLI validation via CliRunner."""
-
-    def test_invalid_branch_numbering_rejected(self, tmp_path: Path):
-        from typer.testing import CliRunner
-        from specify_cli import app
-
-        runner = CliRunner()
-        result = runner.invoke(app, ["init", str(tmp_path / "proj"), "--integration", "claude", "--branch-numbering", "foobar", "--ignore-agent-tools"])
-        assert result.exit_code == 1
-        assert "Invalid --branch-numbering" in result.output
-
-    def test_valid_branch_numbering_sequential(self, tmp_path: Path):
-        from typer.testing import CliRunner
-        from specify_cli import app
-
-        runner = CliRunner()
-        result = runner.invoke(app, ["init", str(tmp_path / "proj"), "--integration", "claude", "--branch-numbering", "sequential", "--ignore-agent-tools", "--script", "sh"])
-        assert result.exit_code == 0
-        assert "Invalid --branch-numbering" not in (result.output or "")
-
-    def test_valid_branch_numbering_timestamp(self, tmp_path: Path):
+    def test_branch_numbering_flag_is_rejected(self, tmp_path: Path):
         from typer.testing import CliRunner
         from specify_cli import app
 
         runner = CliRunner()
-        result = runner.invoke(app, ["init", str(tmp_path / "proj"), "--integration", "claude", "--branch-numbering", "timestamp", "--ignore-agent-tools", "--script", "sh"])
-        assert result.exit_code == 0
-        assert "Invalid --branch-numbering" not in (result.output or "")
+        result = runner.invoke(app, [
+            "init", str(tmp_path / "proj"), "--integration", "claude",
+            "--branch-numbering", "sequential", "--ignore-agent-tools",
+        ])
+        assert result.exit_code != 0, "--branch-numbering should be rejected"
+        assert "No such option" in result.output or "no such option" in result.output.lower()

tests/test_check_prerequisites_paths_only.py

@@ -88,20 +88,17 @@ def test_paths_only_succeeds_on_non_spec_branch(prereq_repo: Path) -> None:
 
 @requires_bash
 def test_paths_only_succeeds_on_spec_branch(prereq_repo: Path) -> None:
-    """--paths-only must also work on a properly named spec branch."""
-    subprocess.run(
-        ["git", "checkout", "-q", "-b", "001-my-feature"],
-        cwd=prereq_repo,
-        check=True,
-    )
+    """--paths-only must also work when SPECIFY_FEATURE is set to a feature name."""
     script = prereq_repo / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
+    env = _clean_env()
+    env["SPECIFY_FEATURE"] = "001-my-feature"
     result = subprocess.run(
         ["bash", str(script), "--json", "--paths-only"],
         cwd=prereq_repo,
         capture_output=True,
         text=True,
         check=False,
-        env=_clean_env(),
+        env=env,
     )
     assert result.returncode == 0, result.stderr
     data = json.loads(result.stdout)
@@ -128,7 +125,7 @@ def test_paths_only_text_mode_on_non_spec_branch(prereq_repo: Path) -> None:
 
 @requires_bash
 def test_normal_mode_still_validates_branch(prereq_repo: Path) -> None:
-    """Without --paths-only, branch validation must still fail on main."""
+    """Without --paths-only, feature directory validation must still fail on main."""
     script = prereq_repo / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
     result = subprocess.run(
         ["bash", str(script), "--json"],
@@ -139,7 +136,7 @@ def test_normal_mode_still_validates_branch(prereq_repo: Path) -> None:
         env=_clean_env(),
     )
     assert result.returncode != 0
-    assert "Not on a feature branch" in result.stderr
+    assert "Feature directory not found" in result.stderr
 
 
 # ── PowerShell tests ──────────────────────────────────────────────────────
@@ -190,7 +187,7 @@ def test_ps_paths_only_succeeds_on_spec_branch(prereq_repo: Path) -> None:
 
 @pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
 def test_ps_normal_mode_still_validates_branch(prereq_repo: Path) -> None:
-    """Without -PathsOnly, branch validation must still fail on main."""
+    """Without -PathsOnly, feature directory validation must still fail on main."""
     script = prereq_repo / ".specify" / "scripts" / "powershell" / "check-prerequisites.ps1"
     exe = "pwsh" if HAS_PWSH else _POWERSHELL
     result = subprocess.run(
@@ -202,4 +199,5 @@ def test_ps_normal_mode_still_validates_branch(prereq_repo: Path) -> None:
         env=_clean_env(),
     )
     assert result.returncode != 0
-    assert "Not on a feature branch" in result.stderr
+    combined = result.stdout + result.stderr
+    assert "Feature directory not found" in combined