feat(workflows): add per-step integration configuration

[philo-x]

Assisted-by: OpenAI Codex (model: GPT-5, autonomous)

Summary

• add optional per-step integration_args and integration_options to workflow command steps
• resolve, validate, isolate, and persist runtime integration configuration for deterministic resume behavior
• add Docker Agent support for per-step agent references and validated agent, model, and safety options while preserving the legacy extra-args environment variable
• document the workflow syntax and audit all built-in execution signatures for compatibility

Closes #4275

Testing

• .venv/bin/python -m pytest tests/integrations/test_base.py tests/integrations/test_integration_docker_agent.py tests/test_workflows.py -q — 1105 passed
• targeted Ruff checks for syntax, imports, subprocess safety rules, and fatal errors
• git diff --check
• Full suite result: 7523 passed, 195 skipped, with 3 failures in untouched areas (PowerShell launcher availability and two bundler reference tests)

AI Disclosure

• I did use AI assistance

Implementation, tests, documentation, and this PR description were authored by OpenAI Codex (model: GPT-5, autonomous) on behalf of @philo-x.

[Copilot]

🟡 Changes recommended

Combining per-step Docker Agent arguments with the documented legacy environment value can emit two conflicting agent references.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds per-step runtime configuration for workflow command integrations, including deterministic resume support and Docker Agent-specific handling.

Changes:

• Resolves, validates, persists, and dispatches per-step integration arguments/options.
• Adds Docker Agent runtime options and agent references.
• Updates compatibility tests and workflow documentation.

File summaries

File	Description
workflows/README.md	Documents runtime configuration syntax.
tests/test_workflows.py	Tests resolution, isolation, validation, and resume.
tests/integrations/test_integration_docker_agent.py	Tests Docker Agent argv and validation.
tests/integrations/test_base.py	Verifies base behavior and signatures.
src/specify_cli/workflows/steps/command/__init__.py	Resolves and dispatches runtime configuration.
src/specify_cli/workflows/engine.py	Persists configuration for resume.
src/specify_cli/workflows/base.py	Marks resumed execution contexts.
src/specify_cli/integrations/base.py	Extends integration runtime APIs.
src/specify_cli/integrations/docker_agent/__init__.py	Implements Docker Agent configuration support.
src/specify_cli/integrations/copilot/__init__.py	Updates custom dispatch signatures.
src/specify_cli/integrations/agy/__init__.py	Updates execution signature.
src/specify_cli/integrations/codex/__init__.py	Updates execution signature.
src/specify_cli/integrations/cursor_agent/__init__.py	Updates execution signature.
src/specify_cli/integrations/devin/__init__.py	Updates execution signature.
src/specify_cli/integrations/droid/__init__.py	Updates execution signature.
src/specify_cli/integrations/dsh/__init__.py	Updates execution signature.
src/specify_cli/integrations/goose/__init__.py	Updates execution signature.
src/specify_cli/integrations/grok/__init__.py	Updates execution signature.
src/specify_cli/integrations/hermes/__init__.py	Updates execution signature.
src/specify_cli/integrations/muse/__init__.py	Updates execution signature.
src/specify_cli/integrations/omp/__init__.py	Updates execution signature.
src/specify_cli/integrations/opencode/__init__.py	Updates execution signature.
src/specify_cli/integrations/rovodev/__init__.py	Updates execution signature.

Review details

• Files reviewed: 23/23 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mnriem]

Please address Copilot feedback

[philo-x]

Posted on behalf of @philo-x by OpenAI Codex (model: GPT-5).

Addressed the review feedback in 83b6b9a2f743bf505f0de59ea0618ebb6bbfa9e4:

• replaced the legacy Docker Agent config reference when per-step integration_args is present while preserving legacy flags
• made the command-step model field the single Docker Agent model source
• re-resolved the complete dispatch configuration consistently on resume
• enforced runtime configuration validation for direct execution-argument builders
• added regression coverage and updated the workflow reference documentation

Validation: 1,111 targeted tests pass; Ruff 0.15.0 and git diff --check pass. The broader integration suite reports 2,892 passed and 5 skipped, with only the pre-existing PowerShell launcher availability failure remaining.

[mnriem]

Thanks — and good that this rides on the agreed #4275 design, with disclosure. One merge-blocker to resolve from the review: when the legacy Docker-Agent env var has its documented shape (e.g. ./default.yaml --hide-tool-results) and a step supplies integration_args, the current code appends both agent references, emitting two conflicting ones. Since preserving the legacy path is an explicit goal of this PR, please define the precedence (I'd expect per-step integration_args to win and the legacy value to be ignored when both are present) and add a test for that collision. Re-request review once that's in.

[Copilot]

🟢 Approval recommended

The implementation satisfies the linked acceptance criteria with comprehensive compatibility, isolation, validation, persistence, and resume coverage.

Review details

• Files reviewed: 24/24 changed files
• Comments generated: 0 new
• Review effort level: Balanced