[Bug]: __SPECKIT_COMMAND_<NAME>__ still can't represent hyphenated command names — #4204 stalled after review

[minzzang144]

Bug Description

__SPECKIT_COMMAND_<NAME>__ still can't represent command names containing a hyphen (e.g. the bundled speckit.agent-context.update), because the token's character class doesn't allow -:

# src/specify_cli/integrations/base.py
r"__SPECKIT_COMMAND_([A-Z][A-Z0-9_]*)__"

This was reported in #4198. A fix landed in #4204 by adding a second token form, __SPECKIT_COMMAND(...)__, carrying the command id verbatim. During review, a simpler alternative was proposed instead: keep the single existing token form and just widen its character class to allow the literal hyphen. The maintainer (@mnriem) requested this direction explicitly ("Please go for option 2", CHANGES_REQUESTED, 2026-08-21), but #4204 has seen no further activity since. Filing this so the agreed direction doesn't get lost.

Suggested fix

Widen the character class in both resolve_command_refs() (src/specify_cli/integrations/base.py) and the extension-skills resolver (src/specify_cli/extensions/__init__.py):

# before
r"__SPECKIT_COMMAND_([A-Z][A-Z0-9_]*)__"
# after
r"__SPECKIT_COMMAND_([A-Z][A-Z0-9_-]*)__"

No decode-logic change is needed — .replace("_", separator) already leaves a literal - untouched, so e.g. __SPECKIT_COMMAND_AGENT-CONTEXT_UPDATE__ resolves to /speckit.agent-context.update. This works for any number of segments and any number of hyphens per segment. A tested reference implementation (including test coverage and a docs update) is available at:
main...minzzang144:spec-kit:fix/4198-command-ref-token-hyphen

Steps to Reproduce

from specify_cli.integrations.base import IntegrationBase as I

# actual bundled command: speckit.agent-context.update
I.resolve_command_refs("__SPECKIT_COMMAND_AGENT_CONTEXT_UPDATE__", ".")

Expected Behavior

The token resolves to the command id that is actually installed: /speckit.agent-context.update.

Actual Behavior

The hyphen is interpreted as a segment separator, so a three-segment command renders as four segments, with no warning:

__SPECKIT_COMMAND_AGENT_CONTEXT_UPDATE__ → /speckit.agent.context.update   ← no such command

Same symptom as #4198, still unresolved on main.

Specify CLI Version

0.16.0

AI Agent

Claude Code

Operating System

macOS 15.3.1

Python Version

3.13.9

Error Logs

Additional Context

See #4198 (original report) and #4204 (prior attempt + review discussion) for full history.

After @mnriem requested Option 2 on #4204, I wasn't sure how to act on it — that PR's branch lives directly in this repo rather than a fork, so I don't have push access to it. I asked about the right process in a comment there, but it's been a few days without a response, so I opened this issue instead with a working reference implementation, hoping that's a more actionable path. That said, this is my first time contributing to this repo, so I'm genuinely unsure if this is the right way to proceed — please let me know if you'd prefer a different approach (e.g. continuing directly on #4204, or something else), and I'm happy to adjust.

(+ I reviewed the diff and ran the test suite myself before filing.)