mirror of
https://github.com/github/spec-kit.git
synced 2026-07-03 12:28:06 +08:00
33a28ec8f7
* docs: warn about unofficial PyPI packages and recommend version verification (#1982)
Clarify that only packages from github/spec-kit are official, and add
`specify version` as a post-install verification step to help users
catch accidental installation of an unrelated package with the same name.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(extensions): auto-correct legacy command names instead of hard-failing (#2017)
Community extensions that predate the strict naming requirement use two
common legacy formats ('speckit.command' and 'extension.command').
Instead of rejecting them outright, auto-correct to the required
'speckit.{extension}.{command}' pattern and emit a compatibility warning
so authors know they need to update their manifest. Names that cannot be
safely corrected (e.g. single-segment names) still raise ValidationError.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(tests): isolate preset catalog search test from community catalog network calls
test_search_with_cached_data asserted exactly 2 results but was getting 4
because _get_merged_packs() queries the full built-in catalog stack
(default + community). The community catalog had no local cache and hit
the network, returning real presets. Writing a project-level
preset-catalogs.yml that pins the test to the default URL only makes
the count assertions deterministic.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(extensions): extend auto-correction to aliases (#2017)
The upstream #1994 added alias validation in _collect_manifest_command_names,
which also rejected legacy 2-part alias names (e.g. 'speckit.verify').
Extend the same auto-correction logic from _validate() to cover aliases,
so both 'speckit.command' and 'extension.command' alias formats are
corrected to 'speckit.{ext_id}.{command}' with a compatibility warning
instead of hard-failing.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(extensions): address PR review feedback (#2017)
- _try_correct_command_name: only correct 'X.Y' to 'speckit.ext_id.Y'
when X matches ext_id, preventing misleading warnings followed by
install failure due to namespace mismatch
- _validate: add aliases type/string guards matching _collect_manifest
_command_names defensive checks
- _validate: track command renames and rewrite any hook.*.command
references that pointed at a renamed command, emitting a warning
- test: fix test_command_name_autocorrect_no_speckit_prefix to use
ext_id matching the legacy namespace; add namespace-mismatch test
- test: replace redundant preset-catalogs.yml isolation with
monkeypatch.delenv("SPECKIT_PRESET_CATALOG_URL") so the env var
cannot bypass catalog restriction in CI environments
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* Update docs/installation.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* fix(extensions): warn when hook command refs are silently canonicalized; fix grammar
- Hook rewrites (alias-form or rename-map) now always emit a warning so
extension authors know to update their manifests. Previously only
rename-map rewrites produced a warning; pure alias-form lifts were
silent.
- Pluralize "command/commands" in the uninstall confirmation message so
single-command extensions no longer print "1 commands".
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(extensions): raise ValidationError for non-dict hook entries
Silently skipping non-dict hook entries left them in manifest.hooks,
causing HookExecutor.register_hooks() to crash with AttributeError
when it called hook_config.get() on a non-mapping value.
Also updates PR description to accurately reflect the implementation
(no separate _try_correct_alias_name helper; aliases use the same
_try_correct_command_name path).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(extensions): derive remove cmd_count from registry, fix wording
Previously cmd_count used len(ext_manifest.commands) which only counted
primary commands and missed aliases. The registry's registered_commands
already tracks every command name (primaries + aliases) per agent, so
max(len(v) for v in registered_commands.values()) gives the correct
total.
Also changes "from AI agent" → "across AI agents" since remove()
unregisters commands from all detected agents.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(extensions): distinguish missing vs empty registered_commands in remove prompt
Using get() without a default lets us tell apart:
- key missing (legacy registry entry) → fall back to manifest count
- key present but empty dict (installed with no agent dirs) → show 0
Previously the truthiness check `if registered_commands and ...` treated
both cases the same, so an empty dict fell back to len(manifest.commands)
and overcounted commands that would actually be removed.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(extensions): clarify removal prompt wording to 'per agent'
'across AI agents' implied a total count, but cmd_count uses max()
across agents (per-agent count). Using sum() would double-count since
users think in logical commands, not per-agent files. 'per agent'
accurately describes what the number represents.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(extensions): clarify cmd_count comment — per-agent max, not total
The comment said 'covers all agents' implying a total, but cmd_count uses
max() across agents (per-agent count). Updated comment to explain the
max() choice and why sum() would double-count.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(extensions): add CLI tests for remove confirmation pluralization
Adds TestExtensionRemoveCLI with two CliRunner tests:
- singular: 1 registered command → '1 command per agent'
- plural: 2 registered commands → '2 commands per agent'
These prevent regressions on the cmd_count pluralization logic
and the 'per agent' wording introduced in this PR.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(agents): remove orphaned SKILL.md parent dirs on unregister
For SKILL.md-based agents (codex, kimi), each command lives in its own
subdirectory (e.g. .agents/skills/speckit-ext-cmd/SKILL.md). The previous
unregister_commands() only unlinked the file, leaving an empty parent dir.
Now attempts rmdir() on the parent when it differs from the agent commands
dir. OSError is silenced so non-empty dirs (e.g. user files) are safely left.
Adds test_unregister_skill_removes_parent_directory to cover this.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(extensions): drop alias pattern enforcement from _validate()
Aliases are intentionally free-form to preserve community extension
compatibility (e.g. 'speckit.verify' short aliases used by spec-kit-verify
and other existing extensions). This aligns _validate() with the intent of
upstream commit 4deb90f (fix: restore alias compatibility, #2110/#2125).
Only type and None-normalization checks remain for aliases. Pattern
enforcement continues for primary command names only.
Updated tests to verify free-form aliases pass through unchanged with
no warnings instead of being auto-corrected.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(extensions): guard against non-dict command entries in _validate()
If provides.commands contains a non-mapping entry (e.g. an int or string),
'name' not in cmd raises TypeError instead of a user-facing ValidationError.
Added isinstance(cmd, dict) check at the top of the loop.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: iamaeroplane <michal.bachorik@gmail.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
154 lines
6.5 KiB
Markdown
154 lines
6.5 KiB
Markdown
# Installation Guide
|
|
|
|
## Prerequisites
|
|
|
|
- **Linux/macOS** (or Windows; PowerShell scripts now supported without WSL)
|
|
- 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
|
|
- [Python 3.11+](https://www.python.org/downloads/)
|
|
- [Git](https://git-scm.com/downloads)
|
|
|
|
## Installation
|
|
|
|
> **Important:** The only official, maintained packages for Spec Kit come from the [github/spec-kit](https://github.com/github/spec-kit) GitHub repository. Any packages with the same name available on PyPI (e.g. `specify-cli` on 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.
|
|
|
|
### Initialize a New Project
|
|
|
|
The easiest way to get started is to initialize a new project. Pin a specific release tag for stability (check [Releases](https://github.com/github/spec-kit/releases) for the latest):
|
|
|
|
```bash
|
|
# Install from a specific stable release (recommended — replace vX.Y.Z with the latest tag)
|
|
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <PROJECT_NAME>
|
|
|
|
# Or install latest from main (may include unreleased changes)
|
|
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
|
|
```
|
|
|
|
Or initialize in the current directory:
|
|
|
|
```bash
|
|
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init .
|
|
# or use the --here flag
|
|
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here
|
|
```
|
|
|
|
### Specify AI Agent
|
|
|
|
You can proactively specify your AI agent during initialization:
|
|
|
|
```bash
|
|
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai claude
|
|
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai gemini
|
|
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai copilot
|
|
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai codebuddy
|
|
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai 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:
|
|
|
|
```bash
|
|
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --script sh
|
|
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --script ps
|
|
```
|
|
|
|
### Ignore Agent Tools Check
|
|
|
|
If you prefer to get the templates without checking for the right tools:
|
|
|
|
```bash
|
|
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai claude --ignore-agent-tools
|
|
```
|
|
|
|
## Verification
|
|
|
|
After installation, run the following command to confirm the correct version is installed:
|
|
|
|
```bash
|
|
specify version
|
|
```
|
|
|
|
This helps verify you are running the official Spec Kit build from GitHub, not an unrelated package with the same name.
|
|
|
|
After initialization, you should see the following commands available in your AI agent:
|
|
|
|
- `/speckit.specify` - Create specifications
|
|
- `/speckit.plan` - Generate implementation plans
|
|
- `/speckit.tasks` - Break down into actionable tasks
|
|
|
|
The `.specify/scripts` directory will contain both `.sh` and `.ps1` scripts.
|
|
|
|
## Troubleshooting
|
|
|
|
### Enterprise / Air-Gapped Installation
|
|
|
|
If your environment blocks access to PyPI (you see 403 errors when running `uv tool install` or `pip install`), you can create a portable wheel bundle on a connected machine and transfer it to the air-gapped target.
|
|
|
|
**Step 1: Build the wheel on a connected machine (same OS and Python version as the target)**
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/github/spec-kit.git
|
|
cd spec-kit
|
|
|
|
# Build the wheel
|
|
pip install build
|
|
python -m build --wheel --outdir dist/
|
|
|
|
# Download the wheel and all its runtime dependencies
|
|
pip download -d dist/ dist/specify_cli-*.whl
|
|
```
|
|
|
|
> **Important:** `pip download` resolves platform-specific wheels (e.g., PyYAML includes native extensions). You must run this step on a machine with the **same OS and Python version** as the air-gapped target. If you need to support multiple platforms, repeat this step on each target OS (Linux, macOS, Windows) and Python version.
|
|
|
|
**Step 2: Transfer the `dist/` directory to the air-gapped machine**
|
|
|
|
Copy the entire `dist/` directory (which contains the `specify-cli` wheel and all dependency wheels) to the target machine via USB, network share, or other approved transfer method.
|
|
|
|
**Step 3: Install on the air-gapped machine**
|
|
|
|
```bash
|
|
pip install --no-index --find-links=./dist specify-cli
|
|
```
|
|
|
|
**Step 4: Initialize a project (no network required)**
|
|
|
|
```bash
|
|
# Initialize a project — no GitHub access needed
|
|
specify init my-project --ai claude --offline
|
|
```
|
|
|
|
The `--offline` flag tells the CLI to use the templates, commands, and scripts bundled inside the wheel instead of downloading from GitHub.
|
|
|
|
> **Deprecation notice:** Starting with v0.6.0, `specify init` will use bundled assets by default and the `--offline` flag will be removed. The GitHub download path will be retired because bundled assets eliminate the need for network access, avoid proxy/firewall issues, and guarantee that templates always match the installed CLI version. No action will be needed — `specify init` will simply work without network access out of the box.
|
|
|
|
> **Note:** Python 3.11+ is required.
|
|
|
|
> **Windows note:** Offline scaffolding requires PowerShell 7+ (`pwsh`), not Windows PowerShell 5.x (`powershell.exe`). Install from https://aka.ms/powershell.
|
|
|
|
### Git Credential Manager on Linux
|
|
|
|
If you're having issues with Git authentication on Linux, you can install Git Credential Manager:
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
set -e
|
|
echo "Downloading Git Credential Manager v2.6.1..."
|
|
wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
|
|
echo "Installing Git Credential Manager..."
|
|
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
|
|
echo "Configuring Git to use GCM..."
|
|
git config --global credential.helper manager
|
|
echo "Cleaning up..."
|
|
rm gcm-linux_amd64.2.6.1.deb
|
|
```
|