Repository navigation
[Bug]: PR #1776 alias validation breaks all community extensions — alias pattern not documented #2017
Description
Bug Description
Environment
- specify CLI version: 0.4.3
Problem
After the alias validation introduced in #1776, every community extension
that uses shorthand aliases fails to install:
specify extension add docguard
→ Validation Error: Invalid alias 'docguard.guard': must follow pattern 'speckit.{extension}.{command}'
specify extension add sync
→ Validation Error: Invalid alias 'speckit.drift': must follow pattern 'speckit.{extension}.{command}'
All community extensions fail. This is a regression introduced by #1776.
Impact
- All community extensions with aliases are broken
- No working workaround exists (local file paths rejected, localhost HTTP returns 400)
- Extension authors were not notified of the breaking change before it shipped
Expected behaviour
Either:
- Aliases should be validated with a looser rule (or not validated at all), OR
- Extension authors should have been notified before the breaking change shipped,
with a migration guide
Suggested fix
- Add alias validation rules to the Extension Publishing Guide / RFC so authors
know what is required - Notify community extension authors of the new requirements
- Consider a grace period or warning instead of hard failure for alias violations
Steps to Reproduce
specify extension add verify --from https://github.com/ismaelJimenez/spec-kit-verify/archive/refs/tags/v1.0.1.zipExpected Behavior
Extension installed
Actual Behavior
specify extension add verify --from https://github.com/ismaelJimenez/spec-kit-verify/archive/refs/tags/v1.0.1.zip
Warning: Installing from external URL.
Only install extensions from sources you trust.
Downloading from https://github.com/ismaelJimenez/spec-kit-verify/archive/refs/tags/v1.0.1.zip...
Validation Error: Invalid alias 'speckit.verify': must follow pattern 'speckit.{extension}.{command}'Specify CLI Version
0.4.3
AI Agent
Claude Code
Operating System
macOS 15.7.5
Python Version
Python 3.14.3
Error Logs
Additional Context
No response
Activity
mnriem commentedon Mar 30, 2026
@mbachorik Can you have a look? Probably should make it so aliases registration is:
Is that sufficient?
mnriem commentedon Mar 30, 2026
@c05m1x Please use 0.4.2 for now. We will get this addressed.
mbachorik commentedon Mar 30, 2026
IMO yes.
there's not better fix I can think off. w/o the check, the extension silently overwrites already registered commands (i've hit that) and that's imo much worse problem as it damages installation.
i'll check if i can do suggested fix quickly.
fix(extensions): auto-correct legacy command names instead of hard-fa…
fix(extensions): auto-correct legacy command names instead of hard-fa…
mbachorik commentedon Mar 30, 2026
nitpick: i believe the regression comes from #1994 and not from #1776.
mnriem commentedon Mar 30, 2026
@mbachorik Thank you for looking at it. I think the aliases should be allowed to use the 2 dotted variant to be honest. The only 2 dotted variant that should not be allowed is speckit.command. Thoughts?
fix(extensions): extend auto-correction to aliases (github#2017)
mbachorik commentedon Mar 30, 2026
my gut feeling is that extensions should use 3 part alias, and 2 part should be reserved for core speckit only (ie if maintainer/community decides to add a command to core framework, it might be already taken by extension).
i have built our system around speckit with extensions and 3-parts looks lean - you quickly know what's where.
my fix suggests to auto-correct 2-part alias from extension into 3-part alias, so it never overwrites core speckit command.
(or maybe i misunderstood, already after midnight here, srry)
mnriem commentedon Mar 30, 2026
No worries. I was thinking more along the lines of
Does that make sense?
c05m1x commentedon Mar 31, 2026
I've reverted to 0.4.0 when I realised that version is not affected (that's the version I'm using on my other laptop)
fix(extensions): address PR review feedback (github#2017)
mbachorik commentedon Mar 31, 2026
@mnriem your call. we could do this:
Format Role Example
speckit.command Core commands only speckit.plan, speckit.verify (future core)
speckit.myext.command Extension primary commands speckit.verify.run
myext.command Extension aliases verify.run, docguard.guard
Auto-correction for aliases:
speckit.verify -> verify.verify (strip speckit. prefix, warn)
docguard.guard -> already valid, pass through
speckit.verify.run used as an alias -> verify.run (strip speckit., warn)
mnriem commentedon Mar 31, 2026
@c05m1x Thoughts?
c05m1x commentedon Apr 2, 2026
@mnriem thank you for the update on the alias validation logic.
To ensure clear separation between the core framework and community contributions, my proposal is a standard for command alias patterns. I believe we should reserve one-dot command aliases (e.g., /speckit.verify) exclusively for the core framework.
For extensions, we should adopt one of the following patterns to prevent namespace collisions and maintain consistency:
Two-dot command aliases: /speckit.extension-name.command
Alternative one-dot aliases: /extension-name.command (if independent of the speckit namespace)
Adopting this structure would clarify which commands are part of the base Spec Kit and which are provided by the ecosystem, while also making documented patterns easier for community developers to follow.
I guess that was the gist of the above conversation, right? (admittedly, I did not read attentively)
4 remaining items
fix(extensions): extend auto-correction to aliases (github#2017)
fix(extensions): address PR review feedback (github#2017)
fix(tests): fix 4 failing tests and normalize null aliases in manifes…
fix(extensions): validate hooks is a dict and restrict alias 3-part c…
fix(extensions): canonicalize hook alias refs and fix docstrings (git…
fix(agents): remove empty skill parent dir on unregister (github#2017)
fix(cli): count aliases in removal confirmation command count (github…
test(cli): add isolated CLI tests for extension remove confirmation c…
fix(extensions): address final reviewer comments (github#2017)
fix(extensions): warn on alias hook canonicalization; fix pluralizati…
fix: unofficial PyPI warning (#1982) and legacy extension command nam…
c05m1x commentedon Apr 22, 2026
@mnriem I guess this issue can be closed? /cc @mbachorik
mnriem commentedon Apr 22, 2026
Yes, closing as fixed
fix: unofficial PyPI warning (github#1982) and legacy extension comma…