### Problem Statement Workflow steps currently allow specifying an integration, but do not provide a way to configure that integration independently for a particular step. This is limiting for integrations whose CLI requires additional runtime arguments or options. For example, [Docker Agent](https://docs.docker.com/ai/docker-agent/getting-started/introduction/#how-it-works) may be launched like: ```bash docker-agent run ./agent.yaml --exec "<prompt>" ``` The `./agent.yaml` path must be passed before the prompt as a positional argument. Also, an integration may require additional key-value options such as: ```text --agent root --model provider/model --safety balanced ``` The current `SPECKIT_INTEGRATION_<KEY>_EXTRA_ARGS` environment variable applies to the **entire process** rather than to an individual workflow step. This prevents a workflow from using different integration configurations for different steps and makes the effective configuration invisible in the workflow definition. ### Proposed Solution Add per-step integration configuration to the workflow step definition. The existing `integration` field remains a string containing the integration key: ```yaml - id: specify command: speckit.specify integration: docker-agent input: args: "{{ inputs.spec }}" ``` Add two optional fields: ```yaml - id: specify command: speckit.specify integration: docker-agent integration_args: - ./agent.yaml integration_options: agent: root safety: balanced input: args: "{{ inputs.spec }}" ``` Where **integration_args** `integration_args` is an ordered list of positional arguments passed to the selected integration before the generated prompt. For Docker Agent: ```yaml integration_args: - ./agent.yaml ``` should produce a command equivalent to: ```bash docker-agent run ./agent.yaml --exec --json "<prompt>" ``` The order of values in `integration_args` must be preserved. **integration_options** `integration_options` is a mapping of key-value options passed to the selected integration. ```yaml integration_options: agent: root safety: balanced ``` The integration is responsible for translating these options into its native CLI representation: ```bash --agent root --safety balanced ``` Integration-specific options should be validated by the selected integration. Unknown options must result in an actionable validation error. **Runtime API** The workflow runner should resolve and pass these values only to the current step: ```python integration.dispatch_command( command, args=command_args, project_root=project_root, model=model, integration_args=resolved_integration_args, integration_options=resolved_integration_options, ) ``` The integration API should expose the values to command construction: ```python def build_exec_args( self, prompt: str, *, model: str | None = None, output_json: bool = True, integration_args: Sequence[str] | None = None, integration_options: Mapping[str, Any] | None = None, ) -> list[str] | None: ... ``` The existing integrations must remain compatible. Integrations that do not use per-step configuration should ignore empty `integration_args` and `integration_options`. ### Alternatives Considered **Global environment variables** ```bash export SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS=./agent.yaml specify workflow run speckit -i spec="..." ``` This is already available for some use cases, but it applies to the whole workflow process. It cannot express different configurations for individual steps and hides important workflow configuration outside the workflow definition. **Step-level environment variables** ```yaml - id: specify type: command env: SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS: ./agent.yaml ``` This would require adding per-step environment handling and carefully isolating child-process environments. It also retains the ambiguity of treating a path as an untyped arbitrary environment string. **A dedicated `agent_config` field** ```yaml integration: name: docker-agent agent_config: ./agent.yaml ``` This is clear for Docker Agent, but introduces an integration-specific field into the common workflow schema. It does not generalize well to integrations that need multiple positional arguments or different key-value options. **Changing `integration` from a string to a mapping** ```yaml integration: name: docker-agent options: ... ``` This could express the desired configuration, but would change the existing type and break compatibility with current workflow definitions that use: ```yaml integration: docker-agent ``` Keeping `integration` as a string and adding `integration_args` and `integration_options` avoids that breaking change. ### Component Agent integrations (command files, workflows) ### AI Agent (if applicable) None ### Use Cases _No response_ ### Acceptance Criteria - [ ] Workflow steps accept an optional `integration_args` list. - [ ] Workflow steps accept an optional `integration_options` mapping. - [ ] `integration_args` values are resolved using the existing workflow expression mechanism. - [ ] `integration_options` values are resolved using the existing workflow expression mechanism. - [ ] Positional arguments preserve their declared order. - [ ] Integration arguments are passed only to the step where they are declared. - [ ] Integration options are passed only to the step where they are declared. - [ ] Integrations that do not use these fields continue to work unchanged. - [ ] Unknown or malformed integration options produce actionable validation errors. - [ ] Relative file paths are resolved relative to the workflow project root where appropriate. - [ ] Per-step integration configuration is persisted in workflow run state so resume behavior is deterministic. - [ ] Configuration values are not interpolated into shell commands as unescaped strings. - [ ] Existing `SPECKIT_INTEGRATION_<KEY>_EXTRA_ARGS` behavior remains backward compatible. - [ ] Tests cover: - [ ] no per-step configuration; - [ ] positional arguments; - [ ] key-value options; - [ ] expression-based values; - [ ] separate configurations across multiple steps; - [ ] workflow resume. ### Additional Context _No response_