Summary

• [Bug]: 0.4.2 removed "extension" command from specify #1982 — Adds a clear warning to `README.md` and `docs/installation.md` that the only official packages are published from `github/spec-kit`; any same-named PyPI packages are unaffiliated. Also adds `specify version` as a recommended post-install verification step.
• [Bug]: PR #1776 alias validation breaks all community extensions — alias pattern not documented #2017 — Instead of hard-failing when a community extension uses a legacy command/alias name, auto-correct it to the required pattern and emit a compatibility warning. Names that cannot be safely corrected still raise `ValidationError`.
• Bonus — Fixes a pre-existing flaky test (`TestPresetCatalog::test_search_with_cached_data`) that was making live network calls to the community catalog.

Changes

`docs/installation.md` / `README.md`

• Warning block clarifying GitHub is the only official source
• `specify version` verification step added after install instructions

`src/specify_cli/extensions.py`

• `ExtensionManifest._validate()`: auto-corrects legacy 2-part primary command names (`{ext_id}.cmd` or `speckit.cmd` → `speckit.{ext_id}.cmd`), emitting compatibility warnings; names that cannot be safely corrected still raise `ValidationError`
• Alias names follow the same correction path via `_try_correct_command_name()` — no separate alias helper
• Hook `command` refs are rewritten when they point at a renamed command; alias-form refs (`{ext_id}.cmd`) are also canonicalized to `speckit.{ext_id}.cmd`; a warning is emitted whenever any rewrite occurs
• Individual hook entries validated as dicts — non-mapping entries raise `ValidationError` instead of silently skipping (which would crash `HookExecutor.register_hooks()` later)
• SKILL output-name collision detection: a `seen_skill_names` dict is maintained across all commands and aliases (including auto-corrected aliases); any duplicate raises `ValidationError`
• `_try_correct_command_name()`: static helper covering both `speckit.cmd` and `{ext_id}.cmd` legacy forms for primary commands and aliases

`src/specify_cli/init.py`

• `extension_add`: prints compatibility warnings from `manifest.warnings` after successful install
• `extension_remove` confirmation: correct singular/plural (`1 command` vs `N commands`)

`src/specify_cli/agents.py`

• `CommandRegistrar.unregister_commands()`: removes empty skill parent directories after unlinking SKILL.md files, preventing orphaned `.claude/skills/speckit-*/` dirs

`tests/test_extensions.py`

• `TestExtensionManifest`: new tests covering primary/alias auto-correction, hook ref rewriting and canonicalization, collision detection, non-dict hook entry validation
• `TestCommandRegistrar`: `test_unregister_skill_removes_parent_directory` covering orphaned dir cleanup
• `TestExtensionRemoveCLI`: CLI tests covering singular/plural command count in removal confirmation

`tests/test_presets.py`

• `test_search_with_cached_data`: patched to use `unittest.mock.patch` on `get_active_catalogs` to isolate test from live community catalog network calls

Test plan

Unit tests

• 154 extension tests pass (pytest tests/test_extensions.py)
• Full suite passes

Live integration tests (real CLI, real filesystem, temp project dir)

All scenarios run against the workspace CLI with actual specify extension add/remove invocations:

Well-formed extension (foobar test extension):

✓ Extension installed successfully!
✓ .specify/extensions/foobar/ exists
✓ 11 command files created in .claude/commands/
✓ No compatibility warnings emitted

Legacy 2-part command name (foobar.hello → speckit.foobar.hello):

✓ Extension installed successfully!
⚠  Compatibility warning: Command name 'foobar.hello' does not follow the required
   pattern 'speckit.{extension}.{command}'. Registering as 'speckit.foobar.hello'.
   The extension author should update the manifest to use this name.
✓ Command file registered under canonical name

Hook with alias-form ref (foobar.hello → speckit.foobar.hello):

✓ Extension installed successfully!
⚠  Compatibility warning: Hook 'after_tasks' referenced command 'foobar.hello';
   updated to canonical form 'speckit.foobar.hello'. The extension author should
   update the manifest.

Non-dict hook entry (install must fail):

Validation Error: Hook 'after_tasks' must be a mapping, got str
✓ Extension not installed (install correctly aborted)

Remove — singular (1 command):

⚠  This will remove:
   • 1 command from AI agent

Remove — plural (2 commands):

⚠  This will remove:
   • 2 commands from AI agent

🤖 Generated with Claude Code