feat: support SPECKIT_INTEGRATION_<KEY>_EXECUTABLE env var (#2743)

* Initial plan

* feat: support SPECKIT_INTEGRATION_<KEY>_EXECUTABLE env var override

Adds `IntegrationBase._resolve_executable()` which reads
`SPECKIT_INTEGRATION_<KEY>_EXECUTABLE` (hyphens→underscores, uppercased)
and falls back to `self.key` when unset or whitespace-only.

All concrete `build_exec_args()` implementations now call
`self._resolve_executable()` instead of hard-coding `self.key` or
`"agy"` as the first argv token:
- MarkdownIntegration, TomlIntegration, SkillsIntegration (base classes)
- CodexIntegration, DevinIntegration, OpencodeIntegration, HermesIntegration, AgyIntegration
- CopilotIntegration (overrides `_resolve_executable()` to fall back to
  the platform-specific `_copilot_executable()` default; also updates
  `dispatch_command()` to use `_resolve_executable()`)

Tests added to tests/integrations/test_extra_args.py covering:
- default (unset) falls back to key
- env var replaces first argv token
- whitespace-only env var is a no-op
- key hyphen→underscore normalisation
- cross-integration scoping (wrong key ignored)
- all override integrations (Codex, Devin, Opencode, Copilot)
- Copilot dispatch_command path
- EXECUTABLE and EXTRA_ARGS can be set simultaneously

See issue #2596."

* fix: complete docstring sentence in _resolve_executable

* test: generalize extra-args test comments for override coverage

* Fix stale Codex executable comment

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

src/specify_cli/integrations/agy/__init__.py

@@ -90,7 +90,7 @@ class AgyIntegration(SkillsIntegration):
         output_json: bool = True,
     ) -> list[str] | None:
         # agy does not support --model or JSON output; both params are ignored
-        return ["agy", "--print", prompt]
+        return [self._resolve_executable(), "--print", prompt]
 
     def setup(
         self,

src/specify_cli/integrations/base.py

@@ -146,6 +146,28 @@ class IntegrationBase(ABC):
         """
         return None
 
+    def _resolve_executable(self) -> str:
+        """Return the executable for this integration's CLI tool.
+
+        Checks ``SPECKIT_INTEGRATION_<KEY>_EXECUTABLE`` first, allowing
+        operators to override the binary path without modifying the
+        integration configuration — useful when the tool is installed in
+        a non-standard location or a specific version must be pinned.
+        Hyphens in the integration key are replaced with underscores and
+        the key is uppercased so that, for example, ``kiro-cli`` maps to
+        ``SPECKIT_INTEGRATION_KIRO_CLI_EXECUTABLE``.
+
+        Falls back to ``self.key`` when the env var is unset or
+        whitespace-only so existing behaviour is unchanged.
+
+        See issue #2596.
+        """
+        env_name = (
+            f"SPECKIT_INTEGRATION_{self.key.upper().replace('-', '_')}_EXECUTABLE"
+        )
+        override = os.environ.get(env_name, "").strip()
+        return override if override else self.key
+
     def _apply_extra_args_env_var(self, args: list[str]) -> None:
         """Append `SPECKIT_INTEGRATION_<KEY>_EXTRA_ARGS` env-var value to *args*.
 
@@ -895,7 +917,7 @@ class MarkdownIntegration(IntegrationBase):
     ) -> list[str] | None:
         if not self.config or not self.config.get("requires_cli"):
             return None
-        args = [self.key, "-p", prompt]
+        args = [self._resolve_executable(), "-p", prompt]
         self._apply_extra_args_env_var(args)
         if model:
             args.extend(["--model", model])
@@ -983,7 +1005,7 @@ class TomlIntegration(IntegrationBase):
     ) -> list[str] | None:
         if not self.config or not self.config.get("requires_cli"):
             return None
-        args = [self.key, "-p", prompt]
+        args = [self._resolve_executable(), "-p", prompt]
         self._apply_extra_args_env_var(args)
         if model:
             args.extend(["-m", model])
@@ -1402,7 +1424,7 @@ class SkillsIntegration(IntegrationBase):
     ) -> list[str] | None:
         if not self.config or not self.config.get("requires_cli"):
             return None
-        args = [self.key, "-p", prompt]
+        args = [self._resolve_executable(), "-p", prompt]
         self._apply_extra_args_env_var(args)
         if model:
             args.extend(["--model", model])

src/specify_cli/integrations/codex/__init__.py

@@ -37,11 +37,9 @@ class CodexIntegration(SkillsIntegration):
         output_json: bool = True,
     ) -> list[str] | None:
         # Codex uses ``codex exec "prompt"`` for non-interactive mode.
-        # Use ``self.key`` so the executable name stays coupled to the
-        # env-var lookup (which also derives from ``self.key``), matching
-        # the pattern in Devin/Opencode and avoiding drift if the key
-        # ever changes.
-        args: list[str] = [self.key, "exec", prompt]
+        # Resolve argv[0] via the shared executable resolver so operators can
+        # override the binary with SPECKIT_INTEGRATION_CODEX_EXECUTABLE.
+        args: list[str] = [self._resolve_executable(), "exec", prompt]
         self._apply_extra_args_env_var(args)
         if model:
             args.extend(["--model", model])

src/specify_cli/integrations/copilot/__init__.py

@@ -134,6 +134,18 @@ class CopilotIntegration(IntegrationBase):
             ),
         ]
 
+    def _resolve_executable(self) -> str:
+        """Return the Copilot CLI executable, respecting the env-var override.
+
+        Checks ``SPECKIT_INTEGRATION_COPILOT_EXECUTABLE`` first.  Falls
+        back to the platform-specific default from ``_copilot_executable()``
+        (``copilot.cmd`` on Windows, ``copilot`` elsewhere) so that
+        existing behaviour is preserved when the env var is unset.
+        """
+        env_name = "SPECKIT_INTEGRATION_COPILOT_EXECUTABLE"
+        override = os.environ.get(env_name, "").strip()
+        return override if override else _copilot_executable()
+
     def build_exec_args(
         self,
         prompt: str,
@@ -148,7 +160,7 @@ class CopilotIntegration(IntegrationBase):
         # Controlled by SPECKIT_COPILOT_ALLOW_ALL_TOOLS env var
         # (default: enabled).  The deprecated SPECKIT_ALLOW_ALL_TOOLS
         # is also honoured as a fallback.
-        args = [_copilot_executable(), "-p", prompt]
+        args = [self._resolve_executable(), "-p", prompt]
         self._apply_extra_args_env_var(args)
         if _allow_all():
             args.append("--yolo")
@@ -217,7 +229,7 @@ class CopilotIntegration(IntegrationBase):
             agent_name = f"speckit.{stem}"
             prompt = args or ""
 
-        cli_args = [_copilot_executable(), "-p", prompt]
+        cli_args = [self._resolve_executable(), "-p", prompt]
         # Honour SPECKIT_INTEGRATION_COPILOT_EXTRA_ARGS for real workflow
         # runs.  `dispatch_command` builds cli_args inline rather than
         # going through `build_exec_args`, so the hook must be invoked

src/specify_cli/integrations/devin/__init__.py

@@ -48,7 +48,7 @@ class DevinIntegration(SkillsIntegration):
         stdout instead of structured JSON. ``requires_cli=True`` is
         kept on the integration for tool detection.
         """
-        args = [self.key, "-p", prompt]
+        args = [self._resolve_executable(), "-p", prompt]
         self._apply_extra_args_env_var(args)
         if model:
             args.extend(["--model", model])

src/specify_cli/integrations/hermes/__init__.py

@@ -257,7 +257,7 @@ class HermesIntegration(SkillsIntegration):
         mapping slash-command invocations to the appropriate skill-based
         dispatch.
         """
-        args = [self.key, "chat", "-Q"]
+        args = [self._resolve_executable(), "chat", "-Q"]
 
         if model:
             args.extend(["-m", model])

src/specify_cli/integrations/opencode/__init__.py

@@ -28,7 +28,7 @@ class OpencodeIntegration(MarkdownIntegration):
         model: str | None = None,
         output_json: bool = True,
     ) -> list[str] | None:
-        args = [self.key, "run"]
+        args = [self._resolve_executable(), "run"]
         # Apply operator-injected extra args before the prompt-derived
         # --command and the canonical --format/-m flags so Spec Kit's
         # later appends remain authoritative under repeated-flag CLI