Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

fix: unofficial PyPI warning (#1982) and legacy extension command name auto-correction (#2017) (#2027)

Michal Bachorik33a28ec8f7f8
diff --git a/README.md b/README.md
index a8a8d3a3e..54e245d63 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,8 @@ Spec-Driven Development **flips the script** on traditional software development
Choose your preferred installation method:
+> **Important:** The only official, maintained packages for Spec Kit are published from this GitHub repository. Any packages with the same name on PyPI are **not** affiliated with this project and are not maintained by the Spec Kit maintainers. Always install directly from GitHub as shown below.
+
#### Option 1: Persistent Installation (Recommended)
Install once and use everywhere. Pin a specific release tag for stability (check [Releases](https://github.com/github/spec-kit/releases) for the latest):
@@ -62,7 +64,13 @@ uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
```
-Then use the tool directly:
+Then verify the correct version is installed:
+
+```bash
+specify version
+```
+
+And use the tool directly:
```bash
# Create new project
diff --git a/docs/installation.md b/docs/installation.md
index 5d560b6e3..ed253902a 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -10,6 +10,8 @@
## 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):
@@ -69,6 +71,14 @@ uvx --from git+https://github.com/github/[email protected] specify init <proje
## 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
diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py
index eb4c306bf..b7b0c909a 100644
--- a/src/specify_cli/__init__.py
+++ b/src/specify_cli/__init__.py
@@ -3318,6 +3318,10 @@ def extension_add(
console.print("\n[green]βœ“[/green] Extension installed successfully!")
console.print(f"\n[bold]{manifest.name}[/bold] (v{manifest.version})")
console.print(f" {manifest.description}")
+
+ for warning in manifest.warnings:
+ console.print(f"\n[yellow]⚠ Compatibility warning:[/yellow] {warning}")
+
console.print("\n[bold cyan]Provided commands:[/bold cyan]")
for cmd in manifest.commands:
console.print(f" β€’ {cmd['name']} - {cmd.get('description', '')}")
@@ -3371,15 +3375,28 @@ def extension_remove(
# Get extension info for command and skill counts
ext_manifest = manager.get_extension(extension_id)
- cmd_count = len(ext_manifest.commands) if ext_manifest else 0
reg_meta = manager.registry.get(extension_id)
+ # Derive cmd_count from the registry's registered_commands (includes aliases)
+ # rather than from the manifest (primary commands only). Use max() across
+ # agents to get the per-agent count; sum() would double-count since users
+ # think in logical commands, not per-agent file counts.
+ # Use get() without a default so we can distinguish "key missing" (fall back
+ # to manifest) from "key present but empty dict" (zero commands registered).
+ registered_commands = reg_meta.get("registered_commands") if isinstance(reg_meta, dict) else None
+ if isinstance(registered_commands, dict):
+ cmd_count = max(
+ (len(v) for v in registered_commands.values() if isinstance(v, list)),
+ default=0,
+ )
+ else:
+ cmd_count = len(ext_manifest.commands) if ext_manifest else 0
raw_skills = reg_meta.get("registered_skills") if reg_meta else None
skill_count = len(raw_skills) if isinstance(raw_skills, list) else 0
# Confirm removal
if not force:
console.print("\n[yellow]⚠ This will remove:[/yellow]")
- console.print(f" β€’ {cmd_count} commands from AI agent")
+ console.print(f" β€’ {cmd_count} command{'s' if cmd_count != 1 else ''} per agent")
if skill_count:
console.print(f" β€’ {skill_count} agent skill(s)")
console.print(f" β€’ Extension directory: .specify/extensions/{extension_id}/")
diff --git a/src/specify_cli/agents.py b/src/specify_cli/agents.py
index e978d0136..c177e2a27 100644
--- a/src/specify_cli/agents.py
+++ b/src/specify_cli/agents.py
@@ -660,6 +660,15 @@ class CommandRegistrar:
cmd_file = commands_dir / f"{output_name}{agent_config['extension']}"
if cmd_file.exists():
cmd_file.unlink()
+ # For SKILL.md agents each command lives in its own subdirectory
+ # (e.g. .agents/skills/speckit-ext-cmd/SKILL.md). Remove the
+ # parent dir when it becomes empty to avoid orphaned directories.
+ parent = cmd_file.parent
+ if parent != commands_dir and parent.exists():
+ try:
+ parent.rmdir() # no-op if dir still has other files
+ except OSError:
+ pass
if agent_name == "copilot":
prompt_file = (
diff --git a/src/specify_cli/extensions.py b/src/specify_cli/extensions.py
index 8f45c425a..852699c39 100644
--- a/src/specify_cli/extensions.py
+++ b/src/specify_cli/extensions.py
@@ -132,6 +132,7 @@ class ExtensionManifest:
ValidationError: If manifest is invalid
"""
self.path = manifest_path
+ self.warnings: List[str] = []
self.data = self._load_yaml(manifest_path)
self._validate()
@@ -217,17 +218,98 @@ class ExtensionManifest:
f"Hook '{hook_name}' missing required 'command' field"
)
- # Validate commands (if present)
+ # Validate commands; track renames so hook references can be rewritten.
+ rename_map: Dict[str, str] = {}
for cmd in commands:
+ if not isinstance(cmd, dict):
+ raise ValidationError(
+ "Each command entry in 'provides.commands' must be a mapping"
+ )
if "name" not in cmd or "file" not in cmd:
raise ValidationError("Command missing 'name' or 'file'")
# Validate command name format
- if EXTENSION_COMMAND_NAME_PATTERN.match(cmd["name"]) is None:
+ if not EXTENSION_COMMAND_NAME_PATTERN.match(cmd["name"]):
+ corrected = self._try_correct_command_name(cmd["name"], ext["id"])
+ if corrected:
+ self.warnings.append(
+ f"Command name '{cmd['name']}' does not follow the required pattern "
+ f"'speckit.{{extension}}.{{command}}'. Registering as '{corrected}'. "
+ f"The extension author should update the manifest to use this name."
+ )
+ rename_map[cmd["name"]] = corrected
+ cmd["name"] = corrected
+ else:
+ raise ValidationError(
+ f"Invalid command name '{cmd['name']}': "
+ "must follow pattern 'speckit.{extension}.{command}'"
+ )
+
+ # Validate alias types; no pattern enforcement on aliases β€” they are
+ # intentionally free-form to preserve community extension compatibility
+ # (e.g. 'speckit.verify' short aliases used by existing extensions).
+ aliases = cmd.get("aliases")
+ if aliases is None:
+ cmd["aliases"] = []
+ aliases = []
+ if not isinstance(aliases, list):
raise ValidationError(
- f"Invalid command name '{cmd['name']}': "
- "must follow pattern 'speckit.{extension}.{command}'"
+ f"Aliases for command '{cmd['name']}' must be a list"
)
+ for alias in aliases:
+ if not isinstance(alias, str):
+ raise ValidationError(
+ f"Aliases for command '{cmd['name']}' must be strings"
+ )
+
+ # Rewrite any hook command references that pointed at a renamed command or
+ # an alias-form ref (ext.cmd β†’ speckit.ext.cmd). Always emit a warning when
+ # the reference is changed so extension authors know to update the manifest.
+ for hook_name, hook_data in self.data.get("hooks", {}).items():
+ if not isinstance(hook_data, dict):
+ raise ValidationError(
+ f"Hook '{hook_name}' must be a mapping, got {type(hook_data).__name__}"
+ )
+ command_ref = hook_data.get("command")
+ if not isinstance(command_ref, str):
+ continue
+ # Step 1: apply any rename from the auto-correction pass.
+ after_rename = rename_map.get(command_ref, command_ref)
+ # Step 2: lift alias-form '{ext_id}.cmd' to canonical 'speckit.{ext_id}.cmd'.
+ parts = after_rename.split(".")
+ if len(parts) == 2 and parts[0] == ext["id"]:
+ final_ref = f"speckit.{ext['id']}.{parts[1]}"
+ else:
+ final_ref = after_rename
+ if final_ref != command_ref:
+ hook_data["command"] = final_ref
+ self.warnings.append(
+ f"Hook '{hook_name}' referenced command '{command_ref}'; "
+ f"updated to canonical form '{final_ref}'. "
+ f"The extension author should update the manifest."
+ )
+
+ @staticmethod
+ def _try_correct_command_name(name: str, ext_id: str) -> Optional[str]:
+ """Try to auto-correct a non-conforming command name to the required pattern.
+
+ Handles the two legacy formats used by community extensions:
+ - 'speckit.command' β†’ 'speckit.{ext_id}.command'
+ - '{ext_id}.command' β†’ 'speckit.{ext_id}.command'
+
+ The 'X.Y' form is only corrected when X matches ext_id to ensure the
+ result passes the install-time namespace check. Any other prefix is
+ uncorrectable and will produce a ValidationError at the call site.
+
+ Returns the corrected name, or None if no safe correction is possible.
+ """
+ parts = name.split('.')
+ if len(parts) == 2:
+ if parts[0] == 'speckit' or parts[0] == ext_id:
+ candidate = f"speckit.{ext_id}.{parts[1]}"
+ if EXTENSION_COMMAND_NAME_PATTERN.match(candidate):
+ return candidate
+ return None
@property
def id(self) -> str:
diff --git a/tests/test_extensions.py b/tests/test_extensions.py
index a6ddff8e1..bec939702 100644
--- a/tests/test_extensions.py
+++ b/tests/test_extensions.py
@@ -243,7 +243,7 @@ class TestExtensionManifest:
ExtensionManifest(manifest_path)
def test_invalid_command_name(self, temp_dir, valid_manifest_data):
- """Test manifest with invalid command name format."""
+ """Test manifest with command name that cannot be auto-corrected raises ValidationError."""
import yaml
valid_manifest_data["provides"]["commands"][0]["name"] = "invalid-name"
@@ -255,6 +255,83 @@ class TestExtensionManifest:
with pytest.raises(ValidationError, match="Invalid command name"):
ExtensionManifest(manifest_path)
+ def test_command_name_autocorrect_speckit_prefix(self, temp_dir, valid_manifest_data):
+ """Test that 'speckit.command' is auto-corrected to 'speckit.{ext_id}.command'."""
+ import yaml
+
+ valid_manifest_data["provides"]["commands"][0]["name"] = "speckit.hello"
+
+ manifest_path = temp_dir / "extension.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_manifest_data, f)
+
+ manifest = ExtensionManifest(manifest_path)
+
+ assert manifest.commands[0]["name"] == "speckit.test-ext.hello"
+ assert len(manifest.warnings) == 1
+ assert "speckit.hello" in manifest.warnings[0]
+ assert "speckit.test-ext.hello" in manifest.warnings[0]
+
+ def test_command_name_autocorrect_matching_ext_id_prefix(self, temp_dir, valid_manifest_data):
+ """Test that '{ext_id}.command' is auto-corrected to 'speckit.{ext_id}.command'."""
+ import yaml
+
+ # Set ext_id to match the legacy namespace so correction is valid
+ valid_manifest_data["extension"]["id"] = "docguard"
+ valid_manifest_data["provides"]["commands"][0]["name"] = "docguard.guard"
+
+ manifest_path = temp_dir / "extension.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_manifest_data, f)
+
+ manifest = ExtensionManifest(manifest_path)
+
+ assert manifest.commands[0]["name"] == "speckit.docguard.guard"
+ assert len(manifest.warnings) == 1
+ assert "docguard.guard" in manifest.warnings[0]
+ assert "speckit.docguard.guard" in manifest.warnings[0]
+
+ def test_command_name_mismatched_namespace_not_corrected(self, temp_dir, valid_manifest_data):
+ """Test that 'X.command' is NOT corrected when X doesn't match ext_id."""
+ import yaml
+
+ # ext_id is "test-ext" but command uses a different namespace
+ valid_manifest_data["provides"]["commands"][0]["name"] = "docguard.guard"
+
+ manifest_path = temp_dir / "extension.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_manifest_data, f)
+
+ with pytest.raises(ValidationError, match="Invalid command name"):
+ ExtensionManifest(manifest_path)
+
+ def test_alias_free_form_accepted(self, temp_dir, valid_manifest_data):
+ """Aliases are free-form β€” a 'speckit.command' alias must be accepted unchanged."""
+ import yaml
+
+ valid_manifest_data["provides"]["commands"][0]["aliases"] = ["speckit.hello"]
+
+ manifest_path = temp_dir / "extension.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_manifest_data, f)
+
+ manifest = ExtensionManifest(manifest_path)
+
+ assert manifest.commands[0]["aliases"] == ["speckit.hello"]
+ assert manifest.warnings == []
+
+ def test_valid_command_name_has_no_warnings(self, temp_dir, valid_manifest_data):
+ """Test that a correctly-named command produces no warnings."""
+ import yaml
+
+ manifest_path = temp_dir / "extension.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_manifest_data, f)
+
+ manifest = ExtensionManifest(manifest_path)
+
+ assert manifest.warnings == []
+
def test_no_commands_no_hooks(self, temp_dir, valid_manifest_data):
"""Test manifest with no commands and no hooks provided."""
import yaml
@@ -317,6 +394,19 @@ class TestExtensionManifest:
with pytest.raises(ValidationError, match="Invalid hooks"):
ExtensionManifest(manifest_path)
+ def test_non_dict_hook_entry_raises_validation_error(self, temp_dir, valid_manifest_data):
+ """Non-mapping hook entries must raise ValidationError, not silently skip."""
+ import yaml
+
+ valid_manifest_data["hooks"]["after_tasks"] = "speckit.test-ext.hello"
+
+ manifest_path = temp_dir / "extension.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_manifest_data, f)
+
+ with pytest.raises(ValidationError, match="Invalid hook 'after_tasks'"):
+ ExtensionManifest(manifest_path)
+
def test_manifest_hash(self, extension_dir):
"""Test manifest hash calculation."""
manifest_path = extension_dir / "extension.yml"
@@ -686,8 +776,8 @@ class TestExtensionManager:
with pytest.raises(ValidationError, match="conflicts with core command namespace"):
manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
- def test_install_accepts_short_alias(self, temp_dir, project_dir):
- """Install should accept legacy short aliases for community extension compat."""
+ def test_install_accepts_free_form_alias(self, temp_dir, project_dir):
+ """Aliases are free-form β€” a short 'speckit.shortcut' alias must be preserved unchanged."""
import yaml
ext_dir = temp_dir / "alias-shortcut"
@@ -718,8 +808,10 @@ class TestExtensionManager:
(ext_dir / "commands" / "cmd.md").write_text("---\ndescription: Test\n---\n\nBody")
manager = ExtensionManager(project_dir)
- # Should not raise β€” short aliases are allowed
- manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+ manifest = manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+ assert manifest.commands[0]["aliases"] == ["speckit.shortcut"]
+ assert manifest.warnings == []
def test_install_rejects_namespace_squatting(self, temp_dir, project_dir):
"""Install should reject commands and aliases outside the extension namespace."""
@@ -1619,6 +1711,54 @@ Then {AGENT_SCRIPT}
prompts_dir = project_dir / ".github" / "prompts"
assert not prompts_dir.exists()
+ def test_unregister_skill_removes_parent_directory(self, project_dir, temp_dir):
+ """Unregistering a SKILL.md command should remove the empty parent subdirectory."""
+ import yaml
+
+ ext_dir = temp_dir / "cleanup-ext"
+ ext_dir.mkdir()
+ (ext_dir / "commands").mkdir()
+
+ manifest_data = {
+ "schema_version": "1.0",
+ "extension": {
+ "id": "cleanup-ext",
+ "name": "Cleanup Extension",
+ "version": "1.0.0",
+ "description": "Test",
+ },
+ "requires": {"speckit_version": ">=0.1.0"},
+ "provides": {
+ "commands": [
+ {
+ "name": "speckit.cleanup-ext.run",
+ "file": "commands/run.md",
+ "description": "Run",
+ }
+ ]
+ },
+ }
+ with open(ext_dir / "extension.yml", "w") as f:
+ yaml.dump(manifest_data, f)
+ (ext_dir / "commands" / "run.md").write_text("---\ndescription: Run\n---\n\nBody")
+
+ skills_dir = project_dir / ".agents" / "skills"
+ skills_dir.mkdir(parents=True)
+
+ registrar = CommandRegistrar()
+ from specify_cli.extensions import ExtensionManifest
+ manifest = ExtensionManifest(ext_dir / "extension.yml")
+ registered = registrar.register_commands_for_agent("codex", manifest, ext_dir, project_dir)
+
+ skill_subdir = skills_dir / "speckit-cleanup-ext-run"
+ assert skill_subdir.exists(), "Skill subdirectory should exist after registration"
+ assert (skill_subdir / "SKILL.md").exists()
+
+ registrar.unregister_commands({"codex": ["speckit.cleanup-ext.run"]}, project_dir)
+
+ assert not (skill_subdir / "SKILL.md").exists(), "SKILL.md should be removed"
+ assert not skill_subdir.exists(), "Empty parent subdirectory should be removed"
+
# ===== Utility Function Tests =====
@@ -3853,3 +3993,58 @@ class TestHookInvocationRendering:
assert "Executing: `/<missing command>`" in message
assert "EXECUTE_COMMAND: <missing command>" in message
assert "EXECUTE_COMMAND_INVOCATION: /<missing command>" in message
+
+
+class TestExtensionRemoveCLI:
+ """CLI tests for `specify extension remove` confirmation prompt wording."""
+
+ def _install_ext(self, project_dir, ext_dir):
+ """Install extension and return the manager."""
+ manager = ExtensionManager(project_dir)
+ manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+ return manager
+
+ def test_remove_confirmation_singular_command(self, tmp_path, extension_dir):
+ """Confirmation prompt should say '1 command' (singular) when one command registered."""
+ from typer.testing import CliRunner
+ from unittest.mock import patch
+ from specify_cli import app
+
+ project_dir = tmp_path / "project"
+ project_dir.mkdir()
+ (project_dir / ".specify").mkdir()
+
+ manager = self._install_ext(project_dir, extension_dir)
+ # Inject registered_commands with 1 entry so cmd_count == 1
+ manager.registry.update("test-ext", {"registered_commands": {"claude": ["speckit.test-ext.hello"]}})
+
+ runner = CliRunner()
+ with patch.object(Path, "cwd", return_value=project_dir):
+ result = runner.invoke(
+ app, ["extension", "remove", "test-ext"], input="n\n", catch_exceptions=False
+ )
+
+ assert "1 command" in result.output
+ assert "1 commands" not in result.output
+
+ def test_remove_confirmation_plural_commands(self, tmp_path, extension_dir):
+ """Confirmation prompt should say '2 commands' (plural) when two commands registered."""
+ from typer.testing import CliRunner
+ from unittest.mock import patch
+ from specify_cli import app
+
+ project_dir = tmp_path / "project"
+ project_dir.mkdir()
+ (project_dir / ".specify").mkdir()
+
+ manager = self._install_ext(project_dir, extension_dir)
+ # Inject registered_commands with 2 entries so cmd_count == 2
+ manager.registry.update("test-ext", {"registered_commands": {"claude": ["speckit.test-ext.hello", "speckit.test-ext.run"]}})
+
+ runner = CliRunner()
+ with patch.object(Path, "cwd", return_value=project_dir):
+ result = runner.invoke(
+ app, ["extension", "remove", "test-ext"], input="n\n", catch_exceptions=False
+ )
+
+ assert "2 commands" in result.output
diff --git a/tests/test_presets.py b/tests/test_presets.py
index 95af7a900..c7383a1f4 100644
--- a/tests/test_presets.py
+++ b/tests/test_presets.py
@@ -1175,8 +1175,7 @@ class TestPresetCatalog:
"""Test search with cached catalog data."""
from unittest.mock import patch
- # Only use the default catalog to prevent fetching the community catalog from the network
- monkeypatch.setenv("SPECKIT_PRESET_CATALOG_URL", PresetCatalog.DEFAULT_CATALOG_URL)
+ monkeypatch.delenv("SPECKIT_PRESET_CATALOG_URL", raising=False)
catalog = PresetCatalog(project_dir)
catalog.cache_dir.mkdir(parents=True, exist_ok=True)