Add integration-aware command hints#2776
Open
nike-17 wants to merge 1 commit into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR makes user-facing Spec Kit command hints “integration-aware” by introducing an integration-owned display invocation API (prefix + separator) and routing template/script placeholder rendering and init guidance through it (notably enabling Codex-style $speckit-… hints while preserving existing slash-command behaviors).
Changes:
- Added
user_command_prefix+build_user_command_invocation()to integrations, and extendedresolve_command_refs()/process_template()to render integration-specific command hints. - Updated shared infra installation/refresh and presets/template processing to pass the active integration’s prefix/separator and safely escape
$speckit…in generated scripts. - Expanded test coverage across init output, template/script rendering, and Codex/Copilot behaviors.
Show a summary per file
| File | Description |
|---|---|
| tests/test_init_command_invocations.py | New regression tests asserting init “next steps” use the correct invocation syntax per integration. |
| tests/integrations/test_integration_subcommand.py | Updates expectations for Codex-switched template content to use $speckit-…. |
| tests/integrations/test_integration_state.py | Adds coverage for persisted command_prefix normalization and runtime invocation helpers. |
| tests/integrations/test_integration_codex.py | Verifies Codex display invocations and generated skills use $speckit-… consistently. |
| tests/integrations/test_integration_base_skills.py | Ensures skills integrations’ user-facing invocations remain consistent and hook-note logic aligns with new syntax. |
| tests/integrations/test_integration_base_markdown.py | Adds coverage that markdown integrations keep /speckit.<name> display hints. |
| tests/integrations/test_cli.py | Adds infra-level tests for custom prefix rendering/escaping in templates and scripts, plus end-to-end init coverage for Codex. |
| tests/integrations/test_base.py | Adds unit coverage for build_user_command_invocation() and new resolve_command_refs() capabilities. |
| templates/commands/*.md | Switches hook output examples to {command_invocation} and adds guidance for dot→hyphen conversion when needed. |
| src/specify_cli/shared_infra.py | Passes command_prefix through placeholder resolution and escapes $speckit in generated scripts. |
| src/specify_cli/presets.py | Resolves command refs using both invoke separator and command prefix from agent configs. |
| src/specify_cli/integrations/*/init.py | Sets integration-specific user_command_prefix and passes effective prefix/separator into template processing. |
| src/specify_cli/integrations/base.py | Introduces display invocation API (user_command_prefix, formatter, and command-ref rendering updates). |
| src/specify_cli/integration_state.py | Normalizes command_prefix in integration settings. |
| src/specify_cli/integration_runtime.py | Persists command_prefix and introduces helpers for resolving prefix/invocations from stored state. |
| src/specify_cli/extensions.py | Renders hook command invocations using integration-aware helpers when possible. |
| src/specify_cli/commands/init.py | Uses integration-owned display invocation for init “next steps” hints. |
| src/specify_cli/agents.py | Adds command_prefix to agent configs and uses it when resolving __SPECKIT_COMMAND_*__ in command bodies. |
| src/specify_cli/init.py | Threads command_prefix into shared infra install/refresh across install/switch/upgrade flows. |
| AGENTS.md | Documents user_command_prefix and notes build_user_command_invocation() behavior for skills mode. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 35/35 changed files
- Comments generated: 3
Comment on lines
+116
to
+136
| def user_command_invocation_for_integration( | ||
| integration: Any, | ||
| state: dict[str, Any], | ||
| key: str, | ||
| command_name: str, | ||
| args: str = "", | ||
| parsed_options: dict[str, Any] | None = None, | ||
| ) -> str: | ||
| """Build a copy-pasteable command invocation for integration guidance.""" | ||
| options = parsed_options | ||
| if options is None: | ||
| setting = integration_setting(state, key) | ||
| stored_parsed = setting.get("parsed_options") | ||
| if isinstance(stored_parsed, dict): | ||
| options = stored_parsed | ||
|
|
||
| return integration.build_user_command_invocation( | ||
| command_name, | ||
| args, | ||
| parsed_options=options, | ||
| ) |
Comment on lines
+2427
to
+2428
| except Exception: | ||
| pass |
Comment on lines
17
to
25
| # Note injected into hook sections so agy maps dot-notation command | ||
| # names (from extensions.yml) to the hyphenated skill names it uses. | ||
| # Without this, agy emits ``/speckit.git.commit`` (which does not | ||
| # resolve) instead of ``/speckit-git-commit``. | ||
| # Without this, agy may emit ``/speckit.git.commit`` (which does not | ||
| # resolve) instead of ``$speckit-git-commit``. | ||
| _HOOK_COMMAND_NOTE = ( | ||
| "- When constructing slash commands from hook command names, " | ||
| "- When constructing command invocations from hook command names, " | ||
| "replace dots (`.`) with hyphens (`-`). " | ||
| "For example, `speckit.git.commit` → `/speckit-git-commit`.\n" | ||
| "For example, `speckit.git.commit` → `$speckit-git-commit`.\n" | ||
| ) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds integration-aware user-facing command invocation rendering so generated Spec Kit hints use the active agent syntax. Codex now renders
$speckit-...hints, standard slash-command integrations keep their existing behavior, and shared templates/scripts, extension hooks, presets, and init next steps all route through the integration-owned display invocation API.Testing
uv run specify --helpuv sync && uv run pytestCommands run:
Also initialized temporary Codex and Claude projects and verified Codex generated
$speckit-plan/$speckit-git-commitwithout slash-form leaks, while Claude retained/speckit-plan.AI Disclosure
Implemented with Codex assistance in this repository workspace.