927f54feea
* feat(init)!: make git extension opt-in and remove --no-git at v0.10.0 - Remove --no-git parameter from specify init command - Remove git extension auto-installation from init flow - Git repository initialization (git init) still runs when git is available - Remove --no-git from all test invocations across the test suite - Update docs to reflect opt-in git extension behavior - Replace TestGitExtensionAutoInstall with TestGitExtensionOptIn tests BREAKING CHANGE: specify init no longer auto-installs the git extension. Use `specify extension add git` to install it explicitly. The --no-git flag has been removed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * refactor(scripts): remove git operations from core scripts Git functionality is now entirely managed by the git extension. Core scripts only handle directory-based feature creation and numbering. - Remove has_git(), check_feature_branch(), git branch creation from core - Simplify number detection to use only spec directory scanning - Remove HAS_GIT output from get_feature_paths() - Remove git remote fetching and branch querying - Keep BRANCH_NAME output key for backward compatibility Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * 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> * refactor(scripts): remove directory scanning and branch fallback from core Core scripts now resolve feature context exclusively from: 1. SPECIFY_FEATURE env var (set by git extension) 2. .specify/feature.json (persisted by specify command) Removed find_feature_dir_by_prefix() and directory scanning heuristics — these are the git extension's responsibility. Scripts error clearly when no feature context is available. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat: introduce feature_numbering, deprecate branch_numbering in init-options - specify command template now reads feature_numbering (preferred) with fallback to branch_numbering (deprecated) from init-options.json - Git extension reads git-config.yml > feature_numbering > branch_numbering - init now writes feature_numbering: sequential to init-options.json - Deprecation warning emitted when branch_numbering is used as fallback Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: remove trailing whitespace in common.ps1 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat(scripts): persist SPECIFY_FEATURE_DIRECTORY env var to feature.json When SPECIFY_FEATURE_DIRECTORY is set, get_feature_paths() now writes the value to .specify/feature.json so future sessions without the env var can still resolve the feature directory. The write is idempotent — it skips when the file already contains the same value. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: address review feedback — error messages and docs - Update error messages in common.sh and common.ps1 to reference SPECIFY_FEATURE_DIRECTORY instead of SPECIFY_FEATURE (which no longer resolves feature directories) - Fix get_current_branch comment (returns empty string, not error) - Update upgrade.md to reference SPECIFY_FEATURE_DIRECTORY with correct example paths - Update local-development.md troubleshooting: replace stale 'Git step skipped' row with actionable git extension guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(scripts): harden feature.json persistence - Use json_escape in printf fallback when jq is unavailable (common.sh) - Replace utf8NoBOM encoding with UTF8Encoding($false) for PowerShell 5.1 compatibility (common.ps1) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * refactor(scripts): remove dead feature_json_matches_feature_dir functions These guards are no longer needed since the branch-name validation they protected against has been removed from check-prerequisites. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * refactor(git-ext): rename create-new-feature to create-new-feature-branch The git extension's script only creates the git branch — rename it to reflect that responsibility. The core create-new-feature.sh/.ps1 handles feature directory creation and feature.json persistence. Also includes fixes from review feedback: - common.sh: _persist_feature_json uses json_escape fallback - common.ps1: Save-FeatureJson uses UTF8Encoding for PS 5.1 compat - common.ps1: case-sensitive path stripping on non-Windows - create-new-feature.sh/ps1: output both SPECIFY_FEATURE and SPECIFY_FEATURE_DIRECTORY - setup-tasks.sh: fix stale 'Validate branch' comment Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(tests): update references to renamed git extension scripts Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(tests): remove duplicate EXT_CREATE_FEATURE assignments Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Manfred Riem <mnriem@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
4.5 KiB
Installation Guide
Prerequisites
- Linux/macOS (or Windows; PowerShell scripts now supported without WSL)
- AI coding agent: Claude Code, GitHub Copilot, Codebuddy CLI, Gemini CLI, or Pi Coding Agent
- uv for package management (recommended) or pipx for persistent installation
- Python 3.11+
- Git (optional — required only when the git extension is enabled)
Installation
Important
The only official, maintained packages for Spec Kit come from the github/spec-kit GitHub repository. Any packages with the same name available on PyPI (e.g.
specify-clion pypi.org) are not affiliated with this project and are not maintained by the Spec Kit maintainers. For normal installs, use the GitHub-based commands shown below. For offline or air-gapped environments, locally built wheels created from this repository are also valid.
Persistent Installation (Recommended)
Install once and use everywhere. Replace vX.Y.Z with a tag from Releases:
Note
The command below requires uv. If you see
command not found: uv, install uv first.
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
Then initialize a project:
specify init <PROJECT_NAME> --integration copilot
One-time Usage
Run directly without installing — see the One-time usage (uvx) guide.
Alternative Package Managers
- pipx — see the pipx installation guide
- Enterprise / Air-Gapped — see the air-gapped installation guide
Specify Integration
Interactive terminals prompt you to choose a coding agent integration during initialization. Non-interactive sessions, such as CI or piped runs, default to GitHub Copilot unless you pass --integration.
You can proactively specify your coding agent integration during initialization:
specify init <project_name> --integration claude
specify init <project_name> --integration gemini
specify init <project_name> --integration copilot
specify init <project_name> --integration codebuddy
specify init <project_name> --integration pi
Specify Script Type (Shell vs PowerShell)
All automation scripts now have both Bash (.sh) and PowerShell (.ps1) variants.
Auto behavior:
- Windows default:
ps - Other OS default:
sh - Interactive mode: you'll be prompted unless you pass
--script
Force a specific script type:
specify init <project_name> --script sh
specify init <project_name> --script ps
Ignore Agent Tools Check
If you prefer to get the templates without checking for the right tools:
specify init <project_name> --integration claude --ignore-agent-tools
Verification
After installation, run the following command to confirm the correct version is installed:
specify version
This helps verify you are running the official Spec Kit build from GitHub, not an unrelated package with the same name.
Stay current: Run specify self check periodically to learn whether a newer release is available — it is read-only and never modifies your installation. When you are ready to upgrade, follow the Upgrade Guide.
After initialization, you should see the following commands available in your coding agent:
/speckit.specify- Create specifications/speckit.plan- Generate implementation plans/speckit.tasks- Break down into actionable tasks
Scripts are installed into a variant subdirectory matching the chosen script type:
.specify/scripts/bash/— contains.shscripts (default on Linux/macOS).specify/scripts/powershell/— contains.ps1scripts (default on Windows)
Troubleshooting
Enterprise / Air-Gapped Installation
If your environment blocks access to PyPI or GitHub, see the Enterprise / Air-Gapped Installation guide for step-by-step instructions on creating portable wheel bundles.
Git Credential Manager on Linux
If you're having issues with Git authentication on Linux, see the Air-Gapped Installation guide for Git Credential Manager setup instructions.