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

[Copilot]

Copilot's findings

• Files reviewed: 36/36 changed files
• Comments generated: 1

[mnriem]

Please address Copilot feedback and resolve conflicts

[Copilot]

Copilot's findings

• Files reviewed: 39/39 changed files
• Comments generated: 1

[mnriem]

Please address Copilot feedback

[nike-17]

Copilot feedback is addressed: the latest Agy comment was resolved by confirming _inject_hook_command_note is inherited from SkillsIntegration, with tests/integrations/test_integration_agy.py covering that call path. All review threads are resolved and CI is green on the current SHA (5212a54). Could you please re-review when you have a chance?

[nike-17]

I pushed an explicit Agy compatibility shim in 10d7d39 so AgyIntegration._inject_hook_command_note(...) is defined directly and forwards to SkillsIntegration._inject_hook_command_note(...). This keeps behavior centralized while addressing the Copilot concern. Local verification: 2705 passed, 9 skipped; ruff passed.

[nike-17]

Agentic follow-up completed and pushed in b626ce0 after rebasing on latest main.

What changed after the prior update:

• Fixed the legacy init-options.json hook fallback so skills integrations without readable .specify/integration.json render native invocations for Agy/Trae/Devin, while preserving legacy non-skills Codex dotted slash behavior.
• Removed Agy's redundant second post-processing pass; it now relies on the shared SkillsIntegration path plus the explicit compatibility shim.
• Added regression coverage for persisted command prefixes, Agy $speckit-git-commit hook notes, strict/corrupt ai_skills handling, and legacy skills fallback rendering.

Verification on the rebased branch:

• uv run pytest tests/integrations tests/test_extensions.py tests/test_workflows.py tests/test_setup_tasks.py -q -> 2750 passed, 9 skipped
• uv run --with ruff ruff check src/specify_cli tests -> passed
• git diff --check -> passed

GitHub now reports the branch as mergeable and there are no unresolved review threads. The only remaining blocker I can see is the stale requested-changes review from the earlier Copilot feedback. Could you please re-review when available?