Add integration-aware command hints by nike-17 · Pull Request #2776 · github/spec-kit

nike-17 · 2026-05-30T19:34:41Z

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 · 2026-06-03T12:22:09Z

Please address Copilot feedback and resolve conflicts

Copilot

Copilot's findings

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

    }
    context_file = "AGENTS.md"
-
-    @staticmethod
-    def _inject_hook_command_note(content: str) -> str:
-        """Insert a dot-to-hyphen note before each hook output instruction.
-
-        Targets the line ``- For each executable hook, output the following``
-        and inserts the note on the line before it, matching its indentation.
-        Skips if the note is already present.
-        """
-        if "replace dots" in content:
-            return content
-
-        def repl(m: re.Match[str]) -> str:
-            indent = m.group(1)
-            instruction = m.group(2)
-            # ``eol`` is empty when the regex matched via ``$`` because the
-            # instruction was the final line of a file with no trailing
-            # newline. Default to ``\n`` so the note never collapses onto
-            # the same line as the instruction.
-            eol = m.group(3) or "\n"
-            return (
-                indent
-                + _HOOK_COMMAND_NOTE.rstrip("\n")
-                + eol
-                + indent
-                + instruction
-                + eol
-            )
-
-        return re.sub(
-            r"(?m)^(\s*)(- For each executable hook, output the following[^\r\n]*)(\r\n|\n|$)",
-            repl,
-            content,
-        )
-
-    def post_process_skill_content(self, content: str) -> str:
-        """Inject the dot-to-hyphen hook command note."""
-        return self._inject_hook_command_note(content)
+    user_command_prefix = "$"



mnriem

Please address Copilot feedback

nike-17 requested a review from mnriem as a code owner May 30, 2026 19:34

mnriem requested a review from Copilot June 1, 2026 16:17

Copilot started reviewing on behalf of mnriem June 1, 2026 16:17 View session

Copilot AI reviewed Jun 1, 2026

View reviewed changes

Comment thread src/specify_cli/integration_runtime.py

Comment thread src/specify_cli/extensions.py

Comment thread src/specify_cli/integrations/agy/__init__.py Outdated

mnriem requested a review from Copilot June 2, 2026 16:49

Copilot started reviewing on behalf of mnriem June 2, 2026 16:50 View session

Copilot AI reviewed Jun 2, 2026

View reviewed changes

Comment thread src/specify_cli/integrations/agy/__init__.py Outdated

nike-17 added 4 commits June 3, 2026 17:37

Add integration-aware command hints

7b9a946

Address integration command hint review

de66f6b

Deduplicate Agy hook note injection

6720636

Align command hint tests after rebase

5212a54

nike-17 force-pushed the feat/integration-command-prefixes branch from 7872734 to 5212a54 Compare June 4, 2026 03:45

mnriem requested a review from Copilot June 4, 2026 12:50

Copilot started reviewing on behalf of mnriem June 4, 2026 12:51 View session

Copilot AI reviewed Jun 4, 2026

View reviewed changes

mnriem requested changes Jun 4, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add integration-aware command hints#2776

Add integration-aware command hints#2776
nike-17 wants to merge 4 commits into
github:mainfrom
nike-17:feat/integration-command-prefixes

nike-17 commented May 30, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

mnriem commented Jun 3, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

mnriem left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

nike-17 commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing

AI Disclosure

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

mnriem commented Jun 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nike-17 commented May 30, 2026 •

edited

Loading