fix(integrations): preserve native skill invocation prefixes

[BenBtg]

Summary

Preserve each integration's native skill invocation syntax when rendering command references:

• render Codex and ZCode skill invocations as $speckit-<name>
• retain /speckit-<name> for other skills integrations and /speckit.<name> for command integrations
• propagate the selected prefix through init, install, switch, upgrade, refresh, extension registration, preset restoration, and shared Bash/PowerShell/Python helpers
• keep literal documentation examples unchanged while resolving explicit command-reference tokens
• centralize integration prefix selection to avoid duplicated branching across lifecycle paths

This extracts the invocation-prefix work from #3616 so that PR remains focused on the constitution command guardrail. No constitution template or guardrail test changes are included here.

Validation

• .venv/bin/python -m pytest tests/integrations/test_base.py tests/integrations/test_cli.py tests/integrations/test_integration_codex.py tests/integrations/test_integration_zcode.py tests/integrations/test_integration_subcommand.py tests/test_extensions.py tests/test_presets.py tests/test_setup_tasks.py -q — 1151 passed
• uvx ruff check src/specify_cli tests/integrations/test_integration_codex.py tests/integrations/test_integration_zcode.py --quiet
• git diff --check

Authored autonomously by GitHub Copilot (model: GPT-5.6 Sol) on behalf of @BenBtg.

[Copilot]

Pull request overview

Preserves native $speckit-* invocation syntax for Codex and ZCode across integration rendering and lifecycle operations.

Changes:

• Centralizes native prefix resolution.
• Propagates prefixes through shared infrastructure, extensions, presets, and integration lifecycle flows.
• Adds coverage for dollar-prefixed rendering across Bash, PowerShell, and Python.

Show a summary per file

File	Description
src/specify_cli/__init__.py	Forwards invocation prefixes to shared infrastructure.
src/specify_cli/agents.py	Applies native prefixes during command registration.
src/specify_cli/commands/init.py	Supplies the selected prefix during initialization.
src/specify_cli/integration_runtime.py	Resolves prefixes by integration mode.
src/specify_cli/integrations/_helpers.py	Preserves prefixes when changing defaults.
src/specify_cli/integrations/_install_commands.py	Handles prefixes during installation.
src/specify_cli/integrations/_migrate_commands.py	Handles prefixes during switch and upgrade.
src/specify_cli/integrations/base.py	Renders native skill invocations and hook guidance.
src/specify_cli/presets/__init__.py	Preserves prefixes during preset restoration.
src/specify_cli/shared_infra.py	Renders prefixes in templates and scripts.
tests/integrations/test_base.py	Tests core invocation rendering.
tests/integrations/test_cli.py	Tests shared template and script output.
tests/integrations/test_integration_base_skills.py	Updates hook-guidance expectations.
tests/integrations/test_integration_codex.py	Verifies Codex guidance wording.
tests/integrations/test_integration_subcommand.py	Tests install and switch behavior.
tests/integrations/test_integration_zcode.py	Cleans up ZCode test formatting.
tests/test_extensions.py	Tests Codex extension references.
tests/test_presets.py	Tests dollar-prefixed preset restoration.
tests/test_setup_tasks.py	Tests Bash and PowerShell formatters.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 19/19 changed files
• Comments generated: 2
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 19/19 changed files
• Comments generated: 2
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 20/20 changed files
• Comments generated: 1
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 20/20 changed files
• Comments generated: 0 new
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 20/20 changed files
• Comments generated: 1
• Review effort level: Medium

[Copilot]

Review details

Comments suppressed due to low confidence (1)

src/specify_cli/integrations/base.py:854

• This still special-cases only dollar-style skills instead of using the new native-prefix resolver. For Kimi, the token is first rendered as /speckit-*, so KimiIntegration.post_process_skill_content() must broadly replace every /speckit-*; that also rewrites literal documentation examples, contrary to the PR’s stated token-only behavior. Resolve the token with get_invocation_prefix() here and narrow/remove Kimi’s broad replacement.

        invocation_prefix = (
            "$"
            if is_dollar_skills_agent(agent_name, invoke_separator == "-")
            else "/"
        )

• Files reviewed: 20/20 changed files
• Comments generated: 2
• Review effort level: Medium

[Copilot]

Review details

Comments suppressed due to low confidence (1)

src/specify_cli/integrations/base.py:854

• This path still only recognizes dollar-style skills, so Kimi command tokens are first rendered as /speckit-* and are then corrected by KimiIntegration.post_process_skill_content()'s whole-body replacement (integrations/kimi/__init__.py:60-63). That replacement also changes literal /speckit-* documentation examples, contradicting this PR's stated token-only behavior; the same happens for extension/preset skill bodies that call the Kimi post-processor. Resolve the prefix here with get_invocation_prefix(agent_name, invoke_separator == "-"), and narrow/remove Kimi's broad replacement now that explicit tokens and hook notes can be rendered natively.

        invocation_prefix = (
            "$"
            if is_dollar_skills_agent(agent_name, invoke_separator == "-")
            else "/"
        )

• Files reviewed: 20/20 changed files
• Comments generated: 1
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 20/20 changed files
• Comments generated: 1
• Review effort level: Medium

[Copilot]

Review details

Comments suppressed due to low confidence (1)

src/specify_cli/integrations/base.py:853

• Use the centralized prefix resolver here as well. For Kimi this currently renders explicit tokens as /speckit-* and relies on KimiIntegration.post_process_skill_content()'s whole-body replacement to obtain /skill:speckit-*; that replacement also changes literal /speckit-* documentation, contradicting the PR's token-only behavior. Resolve the token directly with get_invocation_prefix(agent_name, invoke_separator == "-") and remove/narrow Kimi's broad replacement.

        invocation_prefix = (
            "$"
            if is_dollar_skills_agent(agent_name, invoke_separator == "-")
            else "/"

• Files reviewed: 20/20 changed files
• Comments generated: 0 new
• Review effort level: Medium