Skip to content

💫 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.md
index 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.
+
## Expressions
Steps 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__.py
index 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 sin
from __future__ import annotations
import re
+from collections.abc import Mapping, Sequence
from pathlib import Path
from 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.py
index e58d231d3..529803922 100644
--- a/src/specify_cli/integrations/base.py
+++ b/src/specify_cli/integrations/base.py
@@ -21,6 +21,7 @@ import shutil
import subprocess
import sys
from abc import ABC
+from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from pathlib import Path
from 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 None
args = [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 None
args = [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 None
args = [self._resolve_executable(), "-p", prompt]
diff --git a/src/specify_cli/integrations/codex/__init__.py b/src/specify_cli/integrations/codex/__init__.py
index 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__.py
index 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 json
import os
import 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_name
if 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__.py
index 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 approval
prompt.
"""
+ 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__.py
index 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/overview
from __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`` is
kept 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__.py
index 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 annotations
import os
import shlex
+from collections.abc import Mapping, Sequence
+from typing import Any
from 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
-
@classmethod
def 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__.py
index 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/skills
from __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 None
args = [
diff --git a/src/specify_cli/integrations/dsh/__init__.py b/src/specify_cli/integrations/dsh/__init__.py
index 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-harness
from __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 output
flag, 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__.py
index 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 own
session 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__.py
index 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 permission
gates (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 None
args = [
diff --git a/src/specify_cli/integrations/hermes/__init__.py b/src/specify_cli/integrations/hermes/__init__.py
index 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, Sequence
from pathlib import Path
from shutil import rmtree
from 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-based
dispatch.
"""
+ 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__.py
index 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-code
from __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__.py
index 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__.py
index 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's
diff --git a/src/specify_cli/integrations/rovodev/__init__.py b/src/specify_cli/integrations/rovodev/__init__.py
index 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 annotations
import os
+from collections.abc import Mapping, Sequence
from pathlib import Path
from 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.py
index 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 = None
diff --git a/src/specify_cli/workflows/engine.py b/src/specify_cli/workflows/engine.py
index 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__.py
index 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 a
diff --git a/tests/integrations/test_base.py b/tests/integrations/test_base.py
index 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 inspect
import shlex
import sys
from 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.py
index 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.py
index 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 WorkflowEngine
return 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 _json
from specify_cli.workflows.engine import WorkflowDefinition
diff --git a/workflows/README.md b/workflows/README.md
index 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 Steps
Send an arbitrary inline prompt to an integration CLI (no command file needed):