💫 Toolkit to help you get started with SDD or any other process!
feat(workflows): add per-step integration configuration (#4425)
小画家f43768d2f843
diff --git a/docs/reference/workflows.md b/docs/reference/workflows.mdindex e2deaf181..a547a10e4 100644--- a/docs/reference/workflows.md+++ b/docs/reference/workflows.md@@ -540,6 +540,44 @@ specify workflow run speckit -i spec="Build a kanban board with drag-and-drop ta> **Security note:** a `shell` step runs a local command with **your** privileges. There is no capability sandbox — `requires` is an advisory pre-condition block (spec-kit version, integrations), not a runtime gate, so it does **not** restrict what a step can do. In particular there is no `requires.permissions` capability gate: it is rejected by validation precisely because it would imply a sandbox that does not exist. Review any catalog or downloaded workflow before running it, and use a `gate` step to require explicit approval before sensitive or destructive shell commands.+### Per-Step Integration Configuration++Command steps may pass structured runtime configuration to integrations that+support it:++```yaml+- id: implement-with-docker-agent+ type: command+ command: speckit.implement+ integration: docker-agent+ integration_args:+ - "{{ inputs.agent_config }}"+ integration_options:+ agent: root+ safety: balanced+ model: "openai/gpt-5"+ input:+ args: "{{ inputs.spec }}"+```++`integration_args` is an ordered list of strings. `integration_options` is a+mapping with string keys. Values in both fields are resolved with the workflow+expression mechanism and validated by the selected integration; unsupported,+unknown, or malformed values fail with an actionable error. Docker Agent uses+its single positional argument as the agent configuration reference and accepts+`agent` and `safety` as named integration options. Configure its model through+the command step's top-level `model` field.++When Docker Agent `integration_args` supplies an agent reference for a command+step, it takes precedence over `SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS`;+the entire legacy environment value is ignored for that step. Without a per-step+agent reference, the legacy environment behavior is unchanged.++Resolved runtime configuration is recorded in workflow run state. When a failed+or paused command is resumed, the complete dispatch configuration is re-resolved+from the current inputs, so values supplied with `workflow resume --input` take+effect consistently. A resume without updated inputs reproduces the same values.+## ExpressionsSteps can reference inputs and previous step outputs using `{{ expression }}` syntax:diff --git a/src/specify_cli/integrations/agy/__init__.py b/src/specify_cli/integrations/agy/__init__.pyindex a07415856..958f922c1 100644--- a/src/specify_cli/integrations/agy/__init__.py+++ b/src/specify_cli/integrations/agy/__init__.py@@ -6,6 +6,7 @@ Antigravity uses ``.agents/skills/speckit-<name>/SKILL.md`` layout (enforced sinfrom __future__ import annotationsimport re+from collections.abc import Mapping, Sequencefrom pathlib import Pathfrom typing import TYPE_CHECKING, Any@@ -87,8 +88,11 @@ class AgyIntegration(SkillsIntegration):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:# agy does not support --model or JSON output; both params are ignored+ self.validate_runtime_config(integration_args, integration_options)args = [self._resolve_executable(), "--print", prompt]# Honor SPECKIT_INTEGRATION_AGY_EXTRA_ARGS (operator-supplied flags),# appended after the positional prompt like the devin integration.diff --git a/src/specify_cli/integrations/base.py b/src/specify_cli/integrations/base.pyindex e58d231d3..529803922 100644--- a/src/specify_cli/integrations/base.py+++ b/src/specify_cli/integrations/base.py@@ -21,6 +21,7 @@ import shutilimport subprocessimport sysfrom abc import ABC+from collections.abc import Mapping, Sequencefrom dataclasses import dataclassfrom pathlib import Pathfrom typing import TYPE_CHECKING, Any@@ -245,6 +246,8 @@ class IntegrationBase(ABC):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:"""Build CLI arguments for non-interactive execution.@@ -254,8 +257,38 @@ class IntegrationBase(ABC):Subclasses for CLI-based integrations should override this."""+ self.validate_runtime_config(integration_args, integration_options)return None+ def validate_runtime_config(+ self,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,+ ) -> None:+ """Validate per-step CLI configuration for this integration.++ Runtime configuration is deliberately separate from :meth:`options`,+ which describes install-time ``--integration-options`` accepted by+ ``specify init`` and the integration management commands. Integrations+ opt in by overriding this hook and translating the validated values in+ :meth:`build_exec_args` (or a custom :meth:`dispatch_command`).++ The default accepts empty configuration for backward compatibility and+ rejects non-empty values instead of silently ignoring a misspelled or+ unsupported runtime option.+ """+ if integration_args:+ raise ValueError(+ f"Integration {self.key!r} does not support per-step "+ "'integration_args'."+ )+ if integration_options:+ option_names = ", ".join(sorted(str(key) for key in integration_options))+ raise ValueError(+ f"Integration {self.key!r} does not support per-step "+ f"'integration_options' ({option_names})."+ )+def _resolve_executable(self) -> str:"""Return the executable for this integration's CLI tool.@@ -345,6 +378,8 @@ class IntegrationBase(ABC):model: str | None = None,timeout: int = 600,stream: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> dict[str, Any]:"""Dispatch a Spec Kit command through this integration's CLI.@@ -365,11 +400,16 @@ class IntegrationBase(ABC):"""import subprocess+ self.validate_runtime_config(integration_args, integration_options)prompt = self.build_command_invocation(command_name, args)# When streaming to the terminal, request text output so the# user sees readable output instead of raw JSONL events.exec_args = self.build_exec_args(- prompt, model=model, output_json=not stream+ prompt,+ model=model,+ output_json=not stream,+ integration_args=integration_args,+ integration_options=integration_options,)if exec_args is None:@@ -1025,7 +1065,10 @@ class MarkdownIntegration(IntegrationBase):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:+ self.validate_runtime_config(integration_args, integration_options)if not self.config or not self.config.get("requires_cli"):return Noneargs = [self._resolve_executable(), "-p", prompt]@@ -1116,7 +1159,10 @@ class TomlIntegration(IntegrationBase):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:+ self.validate_runtime_config(integration_args, integration_options)if not self.config or not self.config.get("requires_cli"):return Noneargs = [self._resolve_executable(), "-p", prompt]@@ -1585,7 +1631,10 @@ class SkillsIntegration(IntegrationBase):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:+ self.validate_runtime_config(integration_args, integration_options)if not self.config or not self.config.get("requires_cli"):return Noneargs = [self._resolve_executable(), "-p", prompt]diff --git a/src/specify_cli/integrations/codex/__init__.py b/src/specify_cli/integrations/codex/__init__.pyindex 2ffa59ca4..8d80e0537 100644--- a/src/specify_cli/integrations/codex/__init__.py+++ b/src/specify_cli/integrations/codex/__init__.py@@ -6,6 +6,9 @@ Commands are deprecated; ``--skills`` defaults to ``True``.from __future__ import annotations+from collections.abc import Mapping, Sequence+from typing import Any+from ..base import IntegrationOption, SkillsIntegration@@ -46,10 +49,13 @@ class CodexIntegration(SkillsIntegration):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:# Codex uses ``codex exec "prompt"`` for non-interactive mode.# Resolve argv[0] via the shared executable resolver so operators can# override the binary with SPECKIT_INTEGRATION_CODEX_EXECUTABLE.+ self.validate_runtime_config(integration_args, integration_options)args: list[str] = [self._resolve_executable(), "exec", prompt]self._apply_extra_args_env_var(args)if model:diff --git a/src/specify_cli/integrations/copilot/__init__.py b/src/specify_cli/integrations/copilot/__init__.pyindex 0a9b4e159..74c6589bb 100644--- a/src/specify_cli/integrations/copilot/__init__.py+++ b/src/specify_cli/integrations/copilot/__init__.py@@ -18,6 +18,8 @@ agents:from __future__ import annotations+from collections.abc import Mapping, Sequence+import jsonimport osimport shutil@@ -305,7 +307,10 @@ class CopilotIntegration(IntegrationBase):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:+ self.validate_runtime_config(integration_args, integration_options)# GitHub Copilot CLI uses ``copilot -p "prompt"`` for# non-interactive mode. --yolo enables all permissions# (tools, paths, and URLs) so the agent can perform file@@ -348,6 +353,8 @@ class CopilotIntegration(IntegrationBase):model: str | None = None,timeout: int = 600,stream: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> dict[str, Any]:"""Dispatch via ``--agent speckit.<stem>`` instead of slash-commands.@@ -360,6 +367,8 @@ class CopilotIntegration(IntegrationBase):"""import subprocess+ self.validate_runtime_config(integration_args, integration_options)+stem = command_nameif stem.startswith("speckit."):stem = stem[len("speckit."):]diff --git a/src/specify_cli/integrations/cursor_agent/__init__.py b/src/specify_cli/integrations/cursor_agent/__init__.pyindex 45c5522a0..eb28286a9 100644--- a/src/specify_cli/integrations/cursor_agent/__init__.py+++ b/src/specify_cli/integrations/cursor_agent/__init__.py@@ -12,6 +12,9 @@ is what indicates dispatch support, mirroring ``CopilotIntegration``.from __future__ import annotations+from collections.abc import Mapping, Sequence+from typing import Any+from ..base import IntegrationOption, SkillsIntegration@@ -63,6 +66,8 @@ class CursorAgentIntegration(SkillsIntegration):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:"""Build CLI arguments for non-interactive ``cursor-agent`` execution.@@ -94,6 +99,7 @@ class CursorAgentIntegration(SkillsIntegration):either drops tool calls or exits non-zero on the first approvalprompt."""+ self.validate_runtime_config(integration_args, integration_options)args = [self._resolve_executable(),"-p",diff --git a/src/specify_cli/integrations/devin/__init__.py b/src/specify_cli/integrations/devin/__init__.pyindex 480736534..7391aaea0 100644--- a/src/specify_cli/integrations/devin/__init__.py+++ b/src/specify_cli/integrations/devin/__init__.py@@ -10,6 +10,9 @@ See: https://cli.devin.ai/docs/extensibility/skills/overviewfrom __future__ import annotations+from collections.abc import Mapping, Sequence+from typing import Any+from ..base import IntegrationOption, SkillsIntegration@@ -58,6 +61,8 @@ class DevinIntegration(SkillsIntegration):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:"""Build non-interactive CLI args for Devin for Terminal.@@ -68,6 +73,7 @@ class DevinIntegration(SkillsIntegration):stdout instead of structured JSON. ``requires_cli=True`` iskept on the integration for tool detection."""+ self.validate_runtime_config(integration_args, integration_options)args = [self._resolve_executable(), "-p", prompt]self._apply_extra_args_env_var(args)if model:diff --git a/src/specify_cli/integrations/docker_agent/__init__.py b/src/specify_cli/integrations/docker_agent/__init__.pyindex d962f1f99..c823dc96a 100644--- a/src/specify_cli/integrations/docker_agent/__init__.py+++ b/src/specify_cli/integrations/docker_agent/__init__.py@@ -9,6 +9,8 @@ from __future__ import annotationsimport osimport shlex+from collections.abc import Mapping, Sequence+from typing import Anyfrom specify_cli._utils import docker_agent_command@@ -37,6 +39,12 @@ class DockerAgentIntegration(SkillsIntegration):# Keep co-installation opt-in until shared manifest ownership is supported.multi_install_safe = False+ _RUNTIME_OPTION_FLAGS = {+ "agent": "--agent",+ "safety": "--safety",+ }+ _SAFETY_MODES = {"strict", "balanced", "restricted", "autonomous"}+# Docker Agent hooks are configured in the selected agent YAML under# ``agents.<name>.hooks``. Spec Kit does not edit that user-owned file, so# hooks are intentionally not exposed through the integration event system.@@ -56,7 +64,6 @@ class DockerAgentIntegration(SkillsIntegration):return [executable, "run"]return command-@classmethoddef options(cls) -> list[IntegrationOption]:opts = super().options()@@ -76,39 +83,55 @@ class DockerAgentIntegration(SkillsIntegration):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:"""Build a headless Docker Agent invocation with an agent config."""+ self.validate_runtime_config(integration_args, integration_options)+ runtime_args = list(integration_args or ())extra_env_name = "SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS"extra_args = os.environ.get(extra_env_name, "").strip()- if not extra_args:+ if not runtime_args and not extra_args:raise ValueError("Docker Agent requires an agent configuration reference. "- f"Set {extra_env_name}, for example: "- f"{extra_env_name}=./agent.yaml"+ "Set per-step 'integration_args', for example "+ "integration_args: ['./agent.yaml'], or use the legacy "+ f"{extra_env_name}=./agent.yaml environment variable.")# Validate only the argument shape here: require a first positional# agent reference and reject malformed quoting or a leading option.# The reference may be a local file or a registry reference, so its# existence and validity are intentionally left to Docker Agent.- try:- first_arg = shlex.split(extra_args)[0]- except (IndexError, ValueError) as exc:- raise ValueError(- f"{extra_env_name} must start with an agent configuration reference, "- "for example ./agent.yaml"- ) from exc- if first_arg.startswith("-"):- raise ValueError(- f"{extra_env_name} must start with an agent configuration reference, "- "for example ./agent.yaml"- )+ legacy_args: list[str] = []+ # Per-step arguments are authoritative; ignore the entire legacy value,+ # including malformed quoting, when an agent reference is supplied.+ if not runtime_args:+ try:+ legacy_args = shlex.split(extra_args)+ except ValueError as exc:+ raise ValueError(+ f"{extra_env_name} is not parseable as a POSIX-quoted "+ f"command line (value: {extra_args!r})."+ ) from exc++ if not legacy_args:+ raise ValueError(+ f"{extra_env_name} must start with an agent configuration "+ "reference, for example ./agent.yaml"+ )+ first_arg = legacy_args[0]+ if not first_arg or first_arg.startswith("-"):+ raise ValueError(+ f"{extra_env_name} must start with an agent configuration "+ "reference, for example ./agent.yaml"+ )args = [*self._agent_command(), "--exec"]- # Extra args carry the required agent source (for example- # ``./agent.yaml``) and any Docker Agent CLI flags. The shared helper- # also preserves shell-style quoting when splitting multiple args.- self._apply_extra_args_env_var(args)+ args.extend(runtime_args or legacy_args)++ for option, value in (integration_options or {}).items():+ args.extend([self._RUNTIME_OPTION_FLAGS[option], value])if output_json:args.append("--json")@@ -124,3 +147,58 @@ class DockerAgentIntegration(SkillsIntegration):args.extend(["--", prompt])return args++ def validate_runtime_config(+ self,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,+ ) -> None:+ """Validate Docker Agent's per-step agent reference and CLI options."""+ runtime_args = list(integration_args or ())+ if not all(isinstance(value, str) and value.strip() for value in runtime_args):+ raise ValueError(+ "Docker Agent 'integration_args' values must be non-empty strings."+ )+ if len(runtime_args) > 1:+ raise ValueError(+ "Docker Agent accepts at most one per-step 'integration_args' "+ "value: the agent configuration reference."+ )+ if runtime_args and runtime_args[0].startswith("-"):+ raise ValueError(+ "Docker Agent 'integration_args' must start with an agent "+ "configuration reference, for example ./agent.yaml."+ )++ options = integration_options or {}+ if not all(isinstance(name, str) for name in options):+ raise ValueError(+ "Docker Agent 'integration_options' keys must be strings."+ )+ if "model" in options:+ raise ValueError(+ "Docker Agent model selection must use the command-step "+ "'model' field, not 'integration_options.model'."+ )+ unknown = sorted(set(options) - self._RUNTIME_OPTION_FLAGS.keys())+ if unknown:+ names = ", ".join(repr(name) for name in unknown)+ allowed = ", ".join(sorted(self._RUNTIME_OPTION_FLAGS))+ raise ValueError(+ f"Docker Agent received unknown integration option(s): {names}. "+ f"Supported options: {allowed}."+ )++ for name, value in options.items():+ if not isinstance(value, str) or not value.strip():+ raise ValueError(+ f"Docker Agent integration option {name!r} must be a "+ "non-empty string."+ )+ safety = options.get("safety")+ if safety is not None and safety not in self._SAFETY_MODES:+ allowed = ", ".join(sorted(self._SAFETY_MODES))+ raise ValueError(+ f"Docker Agent integration option 'safety' must be one of: "+ f"{allowed}."+ )diff --git a/src/specify_cli/integrations/droid/__init__.py b/src/specify_cli/integrations/droid/__init__.pyindex d6a5c084a..7e41d76b0 100644--- a/src/specify_cli/integrations/droid/__init__.py+++ b/src/specify_cli/integrations/droid/__init__.py@@ -10,6 +10,9 @@ See: https://docs.factory.ai/cli/configuration/skillsfrom __future__ import annotations+from collections.abc import Mapping, Sequence+from typing import Any+from ..base import SkillsIntegration@@ -90,6 +93,8 @@ class DroidIntegration(SkillsIntegration):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:"""Build CLI arguments for non-interactive ``droid`` execution.@@ -109,6 +114,7 @@ class DroidIntegration(SkillsIntegration):canonical one, so operators can still override ``--model`` or``--output-format``."""+ self.validate_runtime_config(integration_args, integration_options)if not self.config or not self.config.get("requires_cli"):return Noneargs = [diff --git a/src/specify_cli/integrations/dsh/__init__.py b/src/specify_cli/integrations/dsh/__init__.pyindex 9b533dec9..381d4c08c 100644--- a/src/specify_cli/integrations/dsh/__init__.py+++ b/src/specify_cli/integrations/dsh/__init__.py@@ -16,6 +16,9 @@ See: https://github.com/deepseek-ai/deepseek-harnessfrom __future__ import annotations+from collections.abc import Mapping, Sequence+from typing import Any+from ..base import SkillsIntegration@@ -46,6 +49,8 @@ class DshIntegration(SkillsIntegration):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:"""Build non-interactive CLI args for DSH.@@ -58,6 +63,7 @@ class DshIntegration(SkillsIntegration):an interactive session would. The CLI has no structured-JSON outputflag, so ``output_json`` and ``model`` are ignored."""+ self.validate_runtime_config(integration_args, integration_options)args = [self._resolve_executable(), "--profile", "headless"]self._apply_extra_args_env_var(args)args.append(prompt)diff --git a/src/specify_cli/integrations/goose/__init__.py b/src/specify_cli/integrations/goose/__init__.pyindex caed191b9..d02537f29 100644--- a/src/specify_cli/integrations/goose/__init__.py+++ b/src/specify_cli/integrations/goose/__init__.py@@ -2,6 +2,9 @@from __future__ import annotations+from collections.abc import Mapping, Sequence+from typing import Any+from ..base import YamlIntegration@@ -27,6 +30,8 @@ class GooseIntegration(YamlIntegration):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:"""Build CLI arguments for non-interactive ``goose`` execution.@@ -50,6 +55,7 @@ class GooseIntegration(YamlIntegration):the agent's own resolver. Any other prompt -- including Goose's ownsession commands such as ``/help`` or ``/plan`` -- goes to ``-t``."""+ self.validate_runtime_config(integration_args, integration_options)args = [self._resolve_executable(), "run"]# Extra args are applied first, matching the opencode / codex /# cursor-agent ordering. Positional parity only, NOT precedence:diff --git a/src/specify_cli/integrations/grok/__init__.py b/src/specify_cli/integrations/grok/__init__.pyindex 781e17298..ca078a30d 100644--- a/src/specify_cli/integrations/grok/__init__.py+++ b/src/specify_cli/integrations/grok/__init__.py@@ -7,6 +7,9 @@ Grok Build discovers project skills from ``.grok/skills/speckit-<name>/SKILL.md`from __future__ import annotations+from collections.abc import Mapping, Sequence+from typing import Any+from ..base import SkillsIntegration@@ -35,6 +38,8 @@ class GrokIntegration(SkillsIntegration):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:"""Build CLI arguments for non-interactive ``grok`` execution.@@ -44,6 +49,7 @@ class GrokIntegration(SkillsIntegration):dispatch and ``dispatch_command()`` are not blocked at permissiongates (same role as Cursor's ``--force`` / Copilot's ``--yolo``)."""+ self.validate_runtime_config(integration_args, integration_options)if not self.config or not self.config.get("requires_cli"):return Noneargs = [diff --git a/src/specify_cli/integrations/hermes/__init__.py b/src/specify_cli/integrations/hermes/__init__.pyindex a82eb6fd4..1954d968f 100644--- a/src/specify_cli/integrations/hermes/__init__.py+++ b/src/specify_cli/integrations/hermes/__init__.py@@ -12,6 +12,7 @@ Usage::from __future__ import annotations+from collections.abc import Mapping, Sequencefrom pathlib import Pathfrom shutil import rmtreefrom typing import Any@@ -272,6 +273,8 @@ class HermesIntegration(SkillsIntegration):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:"""Build Hermes CLI invocation for programmatic dispatch.@@ -279,6 +282,7 @@ class HermesIntegration(SkillsIntegration):mapping slash-command invocations to the appropriate skill-baseddispatch."""+ self.validate_runtime_config(integration_args, integration_options)args = [self._resolve_executable(), "chat", "-Q"]# Operator-supplied SPECKIT_INTEGRATION_HERMES_EXTRA_ARGS go here —diff --git a/src/specify_cli/integrations/muse/__init__.py b/src/specify_cli/integrations/muse/__init__.pyindex e812ae386..14d9d53da 100644--- a/src/specify_cli/integrations/muse/__init__.py+++ b/src/specify_cli/integrations/muse/__init__.py@@ -9,6 +9,9 @@ See: https://dev.meta.ai/docs/muse-codefrom __future__ import annotations+from collections.abc import Mapping, Sequence+from typing import Any+from ..base import IntegrationOption, SkillsIntegration@@ -50,10 +53,13 @@ class MuseIntegration(SkillsIntegration):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:# Muse Code uses ``muse exec "<prompt>"`` for non-interactive mode.# Resolve argv[0] via the shared executable resolver so operators can# override the binary with SPECKIT_INTEGRATION_MUSE_EXECUTABLE.+ self.validate_runtime_config(integration_args, integration_options)args: list[str] = [self._resolve_executable(), "exec", prompt]self._apply_extra_args_env_var(args)if model:diff --git a/src/specify_cli/integrations/omp/__init__.py b/src/specify_cli/integrations/omp/__init__.pyindex 0a93237d4..2cf2f7b03 100644--- a/src/specify_cli/integrations/omp/__init__.py+++ b/src/specify_cli/integrations/omp/__init__.py@@ -2,6 +2,9 @@from __future__ import annotations+from collections.abc import Mapping, Sequence+from typing import Any+from ..base import MarkdownIntegration@@ -28,6 +31,8 @@ class OmpIntegration(MarkdownIntegration):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:# Diverges from MarkdownIntegration.build_exec_args because OMP's# CLI parser treats `-p`/`--print` as a boolean (one-shot mode) and@@ -35,6 +40,7 @@ class OmpIntegration(MarkdownIntegration):# can1357/oh-my-pi. JSON output is selected via `--mode json`.if not self.config or not self.config.get("requires_cli"):return None+ self.validate_runtime_config(integration_args, integration_options)args = [self._resolve_executable(), "--print"]self._apply_extra_args_env_var(args)if model:diff --git a/src/specify_cli/integrations/opencode/__init__.py b/src/specify_cli/integrations/opencode/__init__.pyindex 007c1187b..cf7041865 100644--- a/src/specify_cli/integrations/opencode/__init__.py+++ b/src/specify_cli/integrations/opencode/__init__.py@@ -1,5 +1,8 @@"""opencode integration."""+from collections.abc import Mapping, Sequence+from typing import Any+from ..base import MarkdownIntegration@@ -43,7 +46,10 @@ class OpencodeIntegration(MarkdownIntegration):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:+ self.validate_runtime_config(integration_args, integration_options)args = [self._resolve_executable(), "run"]# Apply operator-injected extra args before the prompt-derived# --command and the canonical --format/-m flags so Spec Kit'sdiff --git a/src/specify_cli/integrations/rovodev/__init__.py b/src/specify_cli/integrations/rovodev/__init__.pyindex fe0fcb30b..f8ba45910 100644--- a/src/specify_cli/integrations/rovodev/__init__.py+++ b/src/specify_cli/integrations/rovodev/__init__.py@@ -8,6 +8,7 @@ under ``.rovodev/prompts/`` and a ``prompts.yml`` manifest.from __future__ import annotationsimport os+from collections.abc import Mapping, Sequencefrom pathlib import Pathfrom typing import Any@@ -63,6 +64,8 @@ class RovodevIntegration(SkillsIntegration):*,model: str | None = None,output_json: bool = True,+ integration_args: Sequence[str] | None = None,+ integration_options: Mapping[str, Any] | None = None,) -> list[str] | None:"""Build non-interactive ACLI args for RovoDev.@@ -79,6 +82,7 @@ class RovodevIntegration(SkillsIntegration):- ``SPECKIT_INTEGRATION_ROVODEV_EXTRA_ARGS`` injects extra CLI flags"""_ = model+ self.validate_runtime_config(integration_args, integration_options)args = [self._resolve_executable(), "rovodev", "run", prompt]self._apply_extra_args_env_var(args)if output_json:diff --git a/src/specify_cli/workflows/base.py b/src/specify_cli/workflows/base.pyindex 2466db8b1..59d8319d4 100644--- a/src/specify_cli/workflows/base.py+++ b/src/specify_cli/workflows/base.py@@ -77,6 +77,9 @@ class StepContext:#: Current run ID.run_id: str | None = None+ #: Whether the engine is re-executing the current step during resume.+ is_resume: bool = False+#: Source directory of the workflow definition file.workflow_dir: str | None = Nonediff --git a/src/specify_cli/workflows/engine.py b/src/specify_cli/workflows/engine.pyindex 411c1aac8..5abcf45d5 100644--- a/src/specify_cli/workflows/engine.py+++ b/src/specify_cli/workflows/engine.py@@ -1121,6 +1121,7 @@ class WorkflowEngine:default_options=definition.default_options,project_root=str(self.project_root),run_id=state.run_id,+ is_resume=True,workflow_dir=state.workflow_dir,)@@ -1237,6 +1238,11 @@ class WorkflowEngine:"status": result.status.value,"error": result.error,}+ if step_type == "command" and "integration_args" in result.output:+ step_data["integration_args"] = result.output["integration_args"]+ step_data["integration_options"] = result.output[+ "integration_options"+ ]self._record_result(context, state, step_id, step_data)state.append_log(diff --git a/src/specify_cli/workflows/steps/command/__init__.py b/src/specify_cli/workflows/steps/command/__init__.pyindex 8ab777089..f242c74a7 100644--- a/src/specify_cli/workflows/steps/command/__init__.py+++ b/src/specify_cli/workflows/steps/command/__init__.py@@ -128,20 +128,44 @@ class CommandStep(StepBase):)options.update(step_options)- # Attempt CLI dispatch- args_str = str(resolved_input.get("args", ""))- dispatch_result = self._try_dispatch(- command, integration, model, args_str, context- )+ runtime_config = self._resolve_runtime_config(config, context)+ if isinstance(runtime_config, str):+ return StepResult(status=StepStatus.FAILED, error=runtime_config)+ integration_args, integration_options = runtime_config+ args_str = str(resolved_input.get("args", ""))output: dict[str, Any] = {"command": command,"integration": integration,"model": model,"options": options,"input": resolved_input,+ "integration_args": integration_args,+ "integration_options": integration_options,}+ # Attempt CLI dispatch. Integration-specific runtime validation occurs+ # before executable detection so malformed options remain actionable+ # even when the selected CLI is not installed.+ try:+ dispatch_result = self._try_dispatch(+ command,+ integration,+ model,+ args_str,+ context,+ integration_args,+ integration_options,+ )+ except ValueError as exc:+ output["exit_code"] = 1+ output["dispatched"] = False+ return StepResult(+ status=StepStatus.FAILED,+ output=output,+ error=f"Command step {config.get('id', '?')!r}: {exc}",+ )+if dispatch_result is not None:output["exit_code"] = dispatch_result["exit_code"]output["stdout"] = dispatch_result["stdout"]@@ -177,6 +201,8 @@ class CommandStep(StepBase):model: str | None,args: str,context: StepContext,+ integration_args: list[str],+ integration_options: dict[str, Any],) -> dict[str, Any] | None:"""Invoke *command* by name through the integration CLI.@@ -205,8 +231,14 @@ class CommandStep(StepBase):if impl is None:return None+ impl.validate_runtime_config(integration_args, integration_options)+# Build sample args for fallback executable detection when impl.key is not executable.- exec_args = impl.build_exec_args("test")+ exec_args = impl.build_exec_args(+ "test",+ integration_args=integration_args,+ integration_options=integration_options,+ )# Check if the CLI tool is actually installed.# Try the integration key first (covers most agents), then fall back@@ -224,10 +256,53 @@ class CommandStep(StepBase):args=args,project_root=project_root,model=model,+ integration_args=integration_args,+ integration_options=integration_options,)except (NotImplementedError, OSError):return None+ @staticmethod+ def _resolve_runtime_config(+ config: dict[str, Any], context: StepContext+ ) -> tuple[list[str], dict[str, Any]] | str:+ """Resolve and validate this step's per-integration runtime config."""+ step_id = config.get("id", "?")++ raw_args = config.get("integration_args", [])+ if not isinstance(raw_args, list):+ return (+ f"Command step {step_id!r}: 'integration_args' must be a list."+ )++ resolved_args: list[str] = []+ for index, value in enumerate(raw_args):+ resolved = evaluate_expression(value, context)+ if not isinstance(resolved, str):+ return (+ f"Command step {step_id!r}: 'integration_args[{index}]' "+ f"must resolve to a string, got {type(resolved).__name__}."+ )+ resolved_args.append(resolved)++ raw_options = config.get("integration_options", {})+ if not isinstance(raw_options, dict):+ return (+ f"Command step {step_id!r}: 'integration_options' must be a "+ "mapping."+ )+ if not all(isinstance(key, str) for key in raw_options):+ return (+ f"Command step {step_id!r}: 'integration_options' keys must be "+ "strings."+ )++ resolved_options = {+ key: evaluate_expression(value, context)+ for key, value in raw_options.items()+ }+ return resolved_args, resolved_options+def validate(self, config: dict[str, Any]) -> list[str]:errors = super().validate(config)if "command" not in config:@@ -257,6 +332,34 @@ class CommandStep(StepBase):errors.append(f"Command step {config.get('id', '?')!r}: 'options' must be a mapping.")+ if "integration_args" in config and not isinstance(+ config["integration_args"], list+ ):+ errors.append(+ f"Command step {config.get('id', '?')!r}: 'integration_args' "+ "must be a list."+ )+ elif isinstance(config.get("integration_args"), list):+ for index, value in enumerate(config["integration_args"]):+ if not isinstance(value, str):+ errors.append(+ f"Command step {config.get('id', '?')!r}: "+ f"'integration_args[{index}]' must be a string."+ )+ if "integration_options" in config and not isinstance(+ config["integration_options"], dict+ ):+ errors.append(+ f"Command step {config.get('id', '?')!r}: "+ "'integration_options' must be a mapping."+ )+ elif isinstance(config.get("integration_options"), dict) and not all(+ isinstance(key, str) for key in config["integration_options"]+ ):+ errors.append(+ f"Command step {config.get('id', '?')!r}: "+ "'integration_options' keys must be strings."+ )# execute() passes 'integration' to get_integration(), which uses it as a# dict key — a non-string (list/dict) raises a raw TypeError (unhashable),# even on a validated run — and feeds 'model' into the CLI argv. Reject adiff --git a/tests/integrations/test_base.py b/tests/integrations/test_base.pyindex 713cf7552..30938dd7b 100644--- a/tests/integrations/test_base.py+++ b/tests/integrations/test_base.py@@ -1,5 +1,6 @@"""Tests for IntegrationOption, IntegrationBase, MarkdownIntegration, and primitives."""+import inspectimport shleximport sysfrom types import SimpleNamespace@@ -51,6 +52,37 @@ class TestIntegrationBase:def test_options_default_empty(self):assert StubIntegration.options() == []+ def test_runtime_config_default_accepts_empty_and_rejects_non_empty(self):+ integration = StubIntegration()++ integration.validate_runtime_config([], {})+ with pytest.raises(ValueError, match="integration_args"):+ integration.validate_runtime_config(["./agent.yaml"], {})+ with pytest.raises(ValueError, match="integration_options.*unknown"):+ integration.validate_runtime_config([], {"unknown": "value"})++ def test_all_builtin_exec_builders_accept_runtime_config(self):+ from specify_cli.integrations import INTEGRATION_REGISTRY++ for key, integration in INTEGRATION_REGISTRY.items():+ parameters = inspect.signature(integration.build_exec_args).parameters+ assert "integration_args" in parameters, key+ assert "integration_options" in parameters, key++ def test_unsupported_exec_builders_reject_runtime_config_directly(self):+ from specify_cli.integrations import INTEGRATION_REGISTRY++ for integration in INTEGRATION_REGISTRY.values():+ if (+ type(integration).validate_runtime_config+ is not IntegrationBase.validate_runtime_config+ ):+ continue+ with pytest.raises(ValueError, match="integration_args"):+ integration.build_exec_args(+ "prompt", integration_args=["unexpected"]+ )+def test_shared_commands_dir(self):i = StubIntegration()cmd_dir = i.shared_commands_dir()diff --git a/tests/integrations/test_integration_docker_agent.py b/tests/integrations/test_integration_docker_agent.pyindex d962ba978..fa2207927 100644--- a/tests/integrations/test_integration_docker_agent.py+++ b/tests/integrations/test_integration_docker_agent.py@@ -45,6 +45,144 @@ def test_extra_args_are_applied_to_build_exec_args(monkeypatch):]+def test_per_step_runtime_config_builds_ordered_argv(monkeypatch):+ monkeypatch.delenv("SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", raising=False)+ monkeypatch.setattr(+ "shutil.which",+ lambda name: "/usr/bin/docker-agent" if name == "docker-agent" else None,+ )++ args = DockerAgentIntegration().build_exec_args(+ "prompt",+ output_json=False,+ integration_args=["./agent.yaml"],+ integration_options={+ "agent": "root",+ "safety": "balanced",+ },+ model="openai/gpt-5",+ )++ assert args == [+ "docker-agent",+ "run",+ "--exec",+ "./agent.yaml",+ "--agent",+ "root",+ "--safety",+ "balanced",+ "--model",+ "openai/gpt-5",+ "--",+ "prompt",+ ]+++def test_per_step_args_ignore_legacy_extra_flags(monkeypatch):+ monkeypatch.setenv(+ "SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", "--hide-tool-results"+ )+ monkeypatch.setattr("shutil.which", lambda name: None)++ args = DockerAgentIntegration().build_exec_args(+ "prompt",+ output_json=False,+ integration_args=["./agent.yaml"],+ )++ assert args == [+ "docker-agent",+ "run",+ "--exec",+ "./agent.yaml",+ "--",+ "prompt",+ ]++[email protected]("legacy_value", ["./global.yaml --hide-tool-results", '"broken'])+def test_per_step_args_override_legacy_extra_args(monkeypatch, legacy_value):+ monkeypatch.setenv(+ "SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS",+ legacy_value,+ )+ monkeypatch.setattr("shutil.which", lambda name: None)++ args = DockerAgentIntegration().build_exec_args(+ "prompt",+ output_json=False,+ integration_args=["./step.yaml"],+ )++ assert args == [+ "docker-agent",+ "run",+ "--exec",+ "./step.yaml",+ "--",+ "prompt",+ ]+++def test_command_step_model_is_the_only_model_source(monkeypatch):+ monkeypatch.delenv("SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", raising=False)+ monkeypatch.setattr("shutil.which", lambda name: None)++ args = DockerAgentIntegration().build_exec_args(+ "prompt",+ output_json=False,+ model="openai/gpt-5",+ integration_args=["./agent.yaml"],+ )++ assert args.count("--model") == 1+ assert args[args.index("--model") + 1] == "openai/gpt-5"+++def test_integration_options_model_is_rejected():+ with pytest.raises(ValueError, match="command-step 'model' field"):+ DockerAgentIntegration().build_exec_args(+ "prompt",+ integration_args=["./agent.yaml"],+ integration_options={"model": "openai/gpt-5"},+ )+++ ("options", "message"),+ [+ ({"unknown": "value"}, "unknown integration option"),+ ({"agent": ""}, "must be a non-empty string"),+ ({"safety": "unsafe"}, "must be one of"),+ ],+)+def test_per_step_runtime_options_are_validated(options, message):+ with pytest.raises(ValueError, match=message):+ DockerAgentIntegration().build_exec_args(+ "prompt",+ integration_args=["./agent.yaml"],+ integration_options=options,+ )+++def test_per_step_runtime_args_reject_multiple_agent_references():+ with pytest.raises(ValueError, match="at most one"):+ DockerAgentIntegration().build_exec_args(+ "prompt",+ integration_args=["./first.yaml", "./second.yaml"],+ )++[email protected]("integration_args", [[""], [42]])+def test_per_step_runtime_args_reject_malformed_values(integration_args):+ with pytest.raises(ValueError, match="non-empty strings"):+ DockerAgentIntegration().build_exec_args(+ "prompt",+ integration_args=integration_args,+ )++def test_prompt_is_passed_after_agent_config(monkeypatch):monkeypatch.setenv("SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", "./agent.yaml"@@ -85,6 +223,13 @@ def test_requires_agent_config(monkeypatch):DockerAgentIntegration().build_exec_args("prompt", output_json=False)+def test_legacy_agent_config_cannot_resolve_to_empty_token_list(monkeypatch):+ monkeypatch.setenv("SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", '""')++ with pytest.raises(ValueError, match="must start with an agent configuration"):+ DockerAgentIntegration().build_exec_args("prompt", output_json=False)++def test_uses_standalone_executable(monkeypatch):monkeypatch.setenv("SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", "./agent.yaml")monkeypatch.setattr(diff --git a/tests/test_workflows.py b/tests/test_workflows.pyindex 980cc21a6..2c7141e95 100644--- a/tests/test_workflows.py+++ b/tests/test_workflows.py@@ -1098,6 +1098,200 @@ class TestCommandStep:assert result.output["integration"] == "claude"assert result.output["input"]["args"] == "login"+ def test_per_step_integration_config_is_resolved_and_isolated(+ self, tmp_path, monkeypatch+ ):+ from specify_cli.workflows.base import StepContext, StepStatus+ from specify_cli.workflows.steps.command import CommandStep++ calls = []++ def fake_run(args, **kwargs):+ calls.append((args, kwargs))+ return type("Result", (), {"returncode": 0})()++ monkeypatch.delenv(+ "SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", raising=False+ )+ monkeypatch.setattr(+ "shutil.which",+ lambda name: (+ "/usr/bin/docker-agent"+ if name in {"docker-agent", "/usr/bin/docker-agent"}+ else None+ ),+ )+ monkeypatch.setattr("subprocess.run", fake_run)++ step = CommandStep()+ context = StepContext(+ inputs={"config": "./review.yaml", "agent": "reviewer"},+ project_root=str(tmp_path),+ )+ first = step.execute(+ {+ "id": "review",+ "command": "speckit.plan",+ "integration": "docker-agent",+ "integration_args": ["{{ inputs.config }}"],+ "integration_options": {+ "agent": "{{ inputs.agent }}",+ "safety": "balanced",+ },+ },+ context,+ )+ second = step.execute(+ {+ "id": "implement",+ "command": "speckit.implement",+ "integration": "docker-agent",+ "integration_args": ["./implement.yaml"],+ "integration_options": {"agent": "implementer"},+ },+ context,+ )++ assert first.status is StepStatus.COMPLETED+ assert second.status is StepStatus.COMPLETED+ assert first.output["integration_args"] == ["./review.yaml"]+ assert first.output["integration_options"] == {+ "agent": "reviewer",+ "safety": "balanced",+ }+ assert calls[0][0] == [+ "/usr/bin/docker-agent",+ "run",+ "--exec",+ "./review.yaml",+ "--agent",+ "reviewer",+ "--safety",+ "balanced",+ "--",+ "/speckit-plan",+ ]+ assert calls[1][0] == [+ "/usr/bin/docker-agent",+ "run",+ "--exec",+ "./implement.yaml",+ "--agent",+ "implementer",+ "--",+ "/speckit-implement",+ ]+ assert calls[0][1]["cwd"] == str(tmp_path)+ assert calls[1][1]["cwd"] == str(tmp_path)++ @pytest.mark.parametrize(+ ("step_model", "default_model", "expected_model"),+ [+ ("step/model", "workflow/model", "step/model"),+ (None, "workflow/model", "workflow/model"),+ ],+ )+ def test_docker_agent_uses_one_effective_model(+ self,+ tmp_path,+ monkeypatch,+ step_model,+ default_model,+ expected_model,+ ):+ from specify_cli.workflows.base import StepContext, StepStatus+ from specify_cli.workflows.steps.command import CommandStep++ calls = []++ def fake_run(args, **kwargs):+ calls.append(args)+ return type("Result", (), {"returncode": 0})()++ monkeypatch.delenv(+ "SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", raising=False+ )+ monkeypatch.setattr(+ "shutil.which",+ lambda name: (+ "/usr/bin/docker-agent"+ if name in {"docker-agent", "/usr/bin/docker-agent"}+ else None+ ),+ )+ monkeypatch.setattr("subprocess.run", fake_run)++ config = {+ "id": "implement",+ "command": "speckit.implement",+ "integration": "docker-agent",+ "integration_args": ["./agent.yaml"],+ }+ if step_model is not None:+ config["model"] = step_model++ result = CommandStep().execute(+ config,+ StepContext(+ default_model=default_model,+ project_root=str(tmp_path),+ ),+ )++ assert result.status is StepStatus.COMPLETED+ assert calls[0].count("--model") == 1+ assert calls[0][calls[0].index("--model") + 1] == expected_model++ def test_unsupported_runtime_config_fails_with_actionable_error(self):+ from specify_cli.workflows.base import StepContext, StepStatus+ from specify_cli.workflows.steps.command import CommandStep++ result = CommandStep().execute(+ {+ "id": "review",+ "command": "speckit.plan",+ "integration": "claude",+ "integration_options": {"saftey": "balanced"},+ },+ StepContext(),+ )++ assert result.status is StepStatus.FAILED+ assert result.output["dispatched"] is False+ assert "does not support per-step 'integration_options'" in (+ result.error or ""+ )+ assert "saftey" in (result.error or "")++ def test_validate_rejects_malformed_runtime_config(self):+ from specify_cli.workflows.steps.command import CommandStep++ step = CommandStep()+ errors = step.validate(+ {+ "id": "review",+ "command": "speckit.plan",+ "integration_args": "./agent.yaml",+ "integration_options": ["agent", "root"],+ }+ )++ assert any("'integration_args' must be a list" in error for error in errors)+ assert any(+ "'integration_options' must be a mapping" in error for error in errors+ )++ errors = step.validate(+ {+ "id": "review",+ "command": "speckit.plan",+ "integration_args": [42],+ "integration_options": {1: "root"},+ }+ )+ assert any("'integration_args[0]' must be a string" in error for error in errors)+ assert any("keys must be strings" in error for error in errors)+def test_try_dispatch_resolves_rovodev_via_acli(self, tmp_path):"""When acli is installed, rovodev dispatch succeeds via acli."""from unittest.mock import patch, MagicMock@@ -11432,6 +11626,57 @@ steps:verdict_input: spec_verdict"""+ _WF_RUNTIME_CONFIG = """+schema_version: "1.0"+workflow:+ id: "resume-runtime-config-wf"+ name: "Resume Runtime Config WF"+ version: "1.0.0"+inputs:+ config:+ type: string+ default: "./initial-agent.yaml"+ agent_name:+ type: string+ default: "initial-root"+ model_name:+ type: string+ default: "initial/model"+steps:+ - id: implement+ type: command+ command: speckit.implement+ integration: docker-agent+ integration_args:+ - "{{ inputs.config }}"+ integration_options:+ agent: "{{ inputs.agent_name }}"+ safety: balanced+ model: "{{ inputs.model_name }}"+"""++ _WF_DYNAMIC_INTEGRATION = """+schema_version: "1.0"+workflow:+ id: "resume-dynamic-integration-wf"+ name: "Resume Dynamic Integration WF"+ version: "1.0.0"+inputs:+ integration:+ type: string+ default: docker-agent+ config:+ type: string+ default: "./initial-agent.yaml"+steps:+ - id: implement+ type: command+ command: speckit.implement+ integration: "{{ inputs.integration }}"+ integration_args:+ - "{{ inputs.config }}"+"""+def _engine(self, project_dir):from specify_cli.workflows.engine import WorkflowEnginereturn WorkflowEngine(project_dir)@@ -11464,6 +11709,102 @@ steps:assert resumed.status == RunStatus.FAILED # still "exit 1"assert resumed.inputs["cmd"] == "exit 1"+ def test_resume_re_resolves_complete_integration_config(+ self, project_dir, monkeypatch+ ):+ from specify_cli.workflows.base import RunStatus+ from specify_cli.workflows.engine import WorkflowDefinition++ calls = []+ return_codes = iter((1, 0))++ def fake_run(args, **kwargs):+ calls.append(args)+ return type("Result", (), {"returncode": next(return_codes)})()++ monkeypatch.delenv(+ "SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", raising=False+ )+ monkeypatch.setattr(+ "shutil.which",+ lambda name: (+ "/usr/bin/docker-agent"+ if name in {"docker-agent", "/usr/bin/docker-agent"}+ else None+ ),+ )+ monkeypatch.setattr("subprocess.run", fake_run)++ definition = WorkflowDefinition.from_string(self._WF_RUNTIME_CONFIG)+ engine = self._engine(project_dir)+ state = engine.execute(definition)++ assert state.status is RunStatus.FAILED+ assert state.step_results["implement"]["integration_args"] == [+ "./initial-agent.yaml"+ ]+ assert state.step_results["implement"]["integration_options"] == {+ "agent": "initial-root",+ "safety": "balanced",+ }++ resumed = engine.resume(+ state.run_id,+ {+ "config": "./changed-on-resume.yaml",+ "agent_name": "changed-root",+ "model_name": "changed/model",+ },+ )++ assert resumed.status is RunStatus.COMPLETED+ assert resumed.inputs["config"] == "./changed-on-resume.yaml"+ assert len(calls) == 2+ assert "./initial-agent.yaml" in calls[0]+ assert "./changed-on-resume.yaml" in calls[1]+ assert "./initial-agent.yaml" not in calls[1]+ assert calls[1][calls[1].index("--agent") + 1] == "changed-root"+ assert calls[1][calls[1].index("--model") + 1] == "changed/model"++ def test_resume_does_not_mix_new_integration_with_old_runtime_config(+ self, project_dir, monkeypatch+ ):+ from specify_cli.workflows.base import RunStatus+ from specify_cli.workflows.engine import WorkflowDefinition++ monkeypatch.delenv(+ "SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", raising=False+ )+ monkeypatch.setattr(+ "shutil.which",+ lambda name: (+ "/usr/bin/docker-agent"+ if name in {"docker-agent", "/usr/bin/docker-agent"}+ else None+ ),+ )+ monkeypatch.setattr(+ "subprocess.run",+ lambda *args, **kwargs: type("Result", (), {"returncode": 1})(),+ )++ definition = WorkflowDefinition.from_string(self._WF_DYNAMIC_INTEGRATION)+ engine = self._engine(project_dir)+ state = engine.execute(definition)+ assert state.status is RunStatus.FAILED++ resumed = engine.resume(+ state.run_id,+ {"integration": "claude", "config": "./changed-on-resume.yaml"},+ )++ assert resumed.status is RunStatus.FAILED+ step_result = resumed.step_results["implement"]+ assert step_result["integration"] == "claude"+ assert step_result["integration_args"] == ["./changed-on-resume.yaml"]+ assert "Integration 'claude'" in (step_result["error"] or "")+ assert "./initial-agent.yaml" not in str(step_result)+def test_resume_merges_and_coerces_typed_input(self, project_dir):import json as _jsonfrom specify_cli.workflows.engine import WorkflowDefinitiondiff --git a/workflows/README.md b/workflows/README.mdindex 676ea6faf..2c1a9f2bb 100644--- a/workflows/README.md+++ b/workflows/README.md@@ -100,6 +100,39 @@ Invoke an installed Spec Kit command by name via the integration CLI:model: "claude-sonnet-4-20250514" # Optional: override model```+CLI integrations can expose per-step positional arguments and named runtime+options. For example, Docker Agent accepts an agent reference plus validated+`agent` and `safety` options. Use the command step's top-level `model` field for+model selection:++```yaml+- id: specify-with-docker-agent+ command: speckit.specify+ integration: docker-agent+ integration_args:+ - "{{ inputs.agent_config }}"+ integration_options:+ agent: root+ safety: balanced+ model: "openai/gpt-5"+ input:+ args: "{{ inputs.spec }}"+```++`integration_args` must be an ordered list of strings. Expressions are resolved+one element at a time. `integration_options` must be a mapping with string keys;+its values are likewise expression-resolved and validated by the selected+integration. Non-empty runtime configuration is rejected when an integration+does not support it. Resolved values are stored in workflow run state for audit+and recovery. On resume, the complete dispatch configuration (`integration`,+`model`, `integration_args`, and `integration_options`) is re-resolved from the+current workflow inputs; without updated inputs this reproduces the prior values.++When Docker Agent `integration_args` supplies an agent reference for a command+step, it takes precedence over `SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS`;+the entire legacy environment value is ignored for that step. Without a per-step+agent reference, the legacy environment behavior is unchanged.+### Prompt StepsSend an arbitrary inline prompt to an integration CLI (no command file needed):