Add integration-aware command hints

[nike-17]

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

• Tested locally with uv run specify --help
• Ran existing tests with uv sync && uv run pytest
• Tested with a sample project (if applicable)

Commands run:

uv run --extra test pytest tests/integrations tests/test_agent_config_consistency.py tests/test_workflows.py -q
uv run --extra test pytest tests/integrations/test_integration_codex.py tests/integrations/test_integration_base_skills.py -q
uv run --extra test pytest tests -k "codex and command" -q

Also initialized temporary Codex and Claude projects and verified Codex generated $speckit-plan / $speckit-git-commit without slash-form leaks, while Claude retained /speckit-plan.

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (describe below)

Implemented with Codex assistance in this repository workspace.

[Copilot]

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 extended resolve_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