Repository navigation
fix(integrations): use the agent's invocation prefix in hook blocks - #4958
shreyanshj10 wants to merge 2 commits into
Conversation
|
Before we can merge, please document this as a temporary compatibility fix, not a supported extension API. State that rewriting |
|
Makes sense, documented in both places a reader would hit it. Pushed in 861cd3a.
I also added a short note at the end of the "Hook Message Format" section of To confirm the intent: this is purely a compatibility measure so a generated Codex or Kimi skill does not tell the user to run an invocation their agent cannot parse. Extension authors should carry on writing the generic form. I have not added a rename or a deprecation path, since you asked for documentation. |
There was a problem hiding this comment.
🟢 Approval recommended
The implementation follows the centralized invocation mapping and includes focused regression and compatibility coverage.
0 open findings
What changed in this PR
Fixes #4954 by rendering hook invocations with each agent’s native prefix.
Changes:
- Adds prefix-aware hook placeholder rewriting.
- Applies rewriting to core and extension-generated skills.
- Adds regression and compatibility coverage.
| File | Description |
|---|---|
src/specify_cli/integrations/base.py |
Adds shared prefix resolution. |
src/specify_cli/agents.py |
Applies resolution during command registration. |
tests/integrations/test_base.py |
Tests prefix rewriting behavior. |
tests/integrations/test_integration_codex.py |
Covers generated Codex and slash-agent skills. |
extensions/EXTENSION-API-REFERENCE.md |
Documents generic hook syntax. |
Baseline red/green results were assessed from the provided evidence rather than independently rerun.
🧠 Review effort: Balanced
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
This pull request has been automatically marked as stale because it has had no activity for 30 days. It will be closed in 30 days unless there is a substantive update. If you intend to continue, please describe the current status, address or acknowledge outstanding feedback, and confirm whether the branch can be updated and the change remains ready for review. A comment that only states that the pull request is "still relevant" does not provide enough context for maintainers. |
The hook output blocks in the command templates and the bundled extension
commands hard-code a slash (`Command: `/{command}``, `To execute:
`/{command}``). Agents whose native skills invocation is not a bare slash
were told to emit an invocation they cannot run: Codex reported
`To execute: `/speckit-git-commit`` directly below the injected note
telling it to use `$speckit-git-commit`, and Kimi had the same problem
with `/skill:`.
Resolve the prefix at install time with the value get_invocation_prefix()
already returns for the agent, alongside the existing
__SPECKIT_COMMAND_*__ resolution. {command} stays a placeholder and
EXECUTE_COMMAND: {command}, which carries the raw hook id, is untouched.
Agents whose prefix is / render exactly as before.
Document resolve_hook_invocation_prefix as a temporary compatibility fix rather than a supported extension API, in the helper docstring and in the Hook Message Format section of the extension API reference, so extension authors keep writing the generic form in hook blocks.
861cd3a to
f39c461
Compare
Description
Fixes #4954.
The hook output blocks in
templates/commands/*.mdand in the bundled extensioncommands spell the invocation with a literal slash —
Command: `/{command}`,Executing: `/{command}`,To execute: `/{command}`. For agents whosenative skills invocation is not a bare slash that is wrong, and the generated
SKILL.mdends up contradicting itself: the injected dot-to-hyphen notecorrectly says
$speckit-git-commitfor Codex while the line right below itstill says
/{command}, so Codex reportsTo execute: `/speckit-git-commit`,which it cannot run. Kimi has the same problem with its
/skill:prefix.HookExecutor._render_hook_invocationis already prefix-aware at runtime, so thestatic templates were the only place still claiming a slash.
Rather than editing the 87 hard-coded occurrences across 14 template and
extension command files, I resolve the prefix at install time next to the
existing
__SPECKIT_COMMAND_*__resolution, using the prefixget_invocation_prefix()already returns for the agent.{command}stays aplaceholder for the agent to fill from
extensions.yml; only the prefix isresolved, and
EXECUTE_COMMAND: {command}, which carries the raw hook id ratherthan an invocation, is left alone. The placeholder route the issue suggests first
would also leave already-published third-party extension command files broken,
which is why I went this way — happy to switch if you prefer the placeholder.
New
IntegrationBase.resolve_hook_invocation_prefix(), called from the twoplaces that render skill content:
SkillsIntegration.post_process_skill_content()— core command templates,presets, and the extension skill path.
CommandRegistrar.register_commands()— this is what writes bundled extensionskills in practice, because
install_from_directory()registers commandsfirst and
_register_extension_skills()then skips the file it already wrote.Here the call sits beside the existing
resolve_command_refs()call, so it isa no-op for every command layout, where the prefix is
/anyway.Agents whose prefix is
/are untouched, which is all of them except Codex,ZCode, Command Code and Kimi.
One thing I left out deliberately, to keep this to the one defect: on the
registrar path the dot-to-hyphen note itself is never injected, so a bundled
extension skill gets the right prefix but still no note about the separator.
That is pre-existing and fixing it would change output for
/-prefix agentstoo, so it wants its own issue — I'm happy to open one.
Testing
tests/integrations/test_integration_codex.py::TestCodexHookInvocationPrefix— regression coverage through the real install paths:
CodexIntegration.setup()for a core skill, and
specify init --integration codexfollowed byExtensionManager.install_from_directory(extensions/bug)for a bundledextension skill. Both fail on
mainand pass with this change. The third testpins the no-regression case: a
/-prefix agent's skill keeps/{command}, andit passes on
maintoo.tests/integrations/test_base.py::TestResolveHookInvocationPrefix— the helperitself across
/,$and/skill:, that the bare{command}token is notrewritten, and that it is idempotent.
.venv/Scripts/python -m pytest tests/integrations tests/extensions -qanduvx ruff@0.15.0 check src tests. The remaining failures in that run arepre-existing on
mainon this machine — PowerShell parity, symlink privilegeand
MAX_PATH— and the failing set is identical with and without this change.Tested locally with
uv run specify --helpRan existing tests with
uv sync && uv run pytestTested with a sample project (if applicable)
Manual test results
Agent: Codex (skills mode,
--script py) | OS/Shell: Windows/bashPer the
src/specify_cli/*.pymapping rule this is a scaffolding change, so thecheck is that
specify initproduces aSKILL.mda Codex session can act on.specify init --integration codex.agents/skills/speckit-*/SKILL.mdhook block now readsTo execute: `${command}`, matching the$speckit-…note above it.specify extension install(bundledbug).agents/skills/speckit-bug-fix/SKILL.mdrenders`${command}`too, which is the file the issue names.$speckit-specify$-prefixed invocation itself is checked by inspection and by the tests above.specify init --integration claude`/{command}`.AI Disclosure
AI disclosure: Claude Code (model: Claude Opus 5, autonomous) produced this
change and its tests, including the diagnosis of the two skill-rendering paths
and the red/green runs against
main. Extent: code and tests, not just docs.