feat(workflows): add per-step integration configuration by philo-x · Pull Request #4425 · github/spec-kit

philo-x · 2026-09-03T14:09:07Z

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 and safety options, using the command-step model field for model selection while retaining the legacy extra-args path for steps without per-step integration_args
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 — 1121 passed on b4bcd5f7 after syncing main
Ruff 0.15.0 targeted checks (E9,F63,F7,F82,S602,S604,S605)
git diff --check
Earlier full suite result (not rerun for this precedence follow-up): 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.

Precedence follow-up, regression tests, documentation updates, and main synchronization authored by OpenAI Codex (model: GPT-6, autonomous) on behalf of @philo-x.

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

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

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

philo-x · 2026-09-04T13:18:02Z

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 · 2026-09-08T21:58:16Z

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

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

philo-x · 2026-09-09T06:52:24Z

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

Thanks @mnriem. The stricter precedence is implemented in 88d6abd: when per-step integration_args supplies an agent reference, the entire SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS value is ignored for that step, including malformed quoting. The legacy environment behavior remains unchanged when no per-step agent reference is supplied.

For completeness, the previous head (83b6b9a2) already replaced the legacy agent reference with the per-step one, but still inherited any trailing legacy flags. This follow-up makes the precedence stricter by ignoring the legacy value entirely whenever a per-step agent reference is present.

Regression coverage now includes legacy agent-plus-flags, flags-only, and malformed quoting. Both workflow guides document the precedence, and the PR description identifies the command-step model field as the model source.

Synced with main at 0c8e31ff; final head is b4bcd5f. Validation on that head: 1,121 targeted tests passed, Ruff 0.15.0 targeted checks passed, and git diff --check passed. CI workflows are currently awaiting maintainer approval.

@mnriem, this is ready for another review. Thanks again.

mnriem · 2026-09-09T16:20:39Z

Thanks — that's exactly the precedence I wanted: when a per-step integration_args agent reference is present, ignore the legacy SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS entirely (including malformed quoting), and the regression coverage for legacy-agent-plus-flags / flags-only / malformed quoting nails the cases down. Re-requesting review/CI on 88d6abd; once it's green I'll merge (closes #4275).

Copilot

🟢 Approval recommended

The implementation matches the linked requirements and includes comprehensive compatibility and regression coverage.

Review details

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

mnriem · 2026-09-09T18:16:15Z

Thank you!

Upstream github#4425 (per-step integration configuration) landed after this branch was pushed and collided with it in two ways. The textual conflict is one region of dispatch_command(): github#4425 inserted a validate_runtime_config() call on the line above the one this branch changed. The two edits are independent, so both survive -- validation first, then _build_dispatch_prompt() builds the prompt. The second collision is semantic and git does not flag it. github#4425 widened build_exec_args() with integration_args/integration_options and updated all fifteen integrations that override it. Bob's override arrives with this branch, so github#4425 had nothing to update, and merging alone would raise TypeError on every Bob dispatch -- the path this branch exists to make work. tests/integrations/test_base.py enumerates the registry and catches it: AssertionError: bob TypeError: BobIntegration.build_exec_args() got an unexpected keyword argument 'integration_args' Bob therefore takes the same four lines as every other integration: the two keyword-only parameters and a validate_runtime_config() call first, copied from CursorAgentIntegration and DroidIntegration. Bob accepts no per-step runtime configuration, so the inherited default -- which rejects non-empty values rather than ignoring them -- is the correct behaviour. Verified: 2915 integration tests pass; the registry test is red without the Bob change and green with it; ruff reports nothing on the three changed files; and dispatch renders /speckit.specify for a legacy project, /speckit-git-commit for a skills project. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TqDT4qTj3sFBeg9tMRiXqZ

feat(workflows): add per-step integration configuration

aad0370

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

philo-x requested a review from mnriem as a code owner September 3, 2026 14:09

mnriem requested a balanced review from Copilot September 3, 2026 14:41

Copilot started reviewing on behalf of mnriem September 3, 2026 14:42 View session

Copilot AI reviewed Sep 3, 2026

View reviewed changes

Comment thread src/specify_cli/integrations/docker_agent/__init__.py Outdated

mnriem requested changes Sep 3, 2026

View reviewed changes

fix(workflows): address per-step integration review feedback

83b6b9a

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

philo-x requested a review from mnriem September 4, 2026 13:18

mnriem requested a balanced review from Copilot September 8, 2026 21:56

Copilot started reviewing on behalf of mnriem September 8, 2026 21:57 View session

mnriem added author-awaiting Waiting on author response triage-nice-to-have Verdict: evidence-backed fix or greenlit feature — land after review labels Sep 8, 2026

Copilot AI reviewed Sep 8, 2026

View reviewed changes

philo-y added 2 commits September 9, 2026 14:49

fix(workflows): let per-step Docker Agent args override legacy config

88d6abd

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

Merge upstream main into feat/4275-per-step-integration-config

b4bcd5f

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

mnriem requested a balanced review from Copilot September 9, 2026 16:20

Copilot started reviewing on behalf of mnriem September 9, 2026 16:21 View session

Copilot AI reviewed Sep 9, 2026

View reviewed changes

mnriem removed the author-awaiting Waiting on author response label Sep 9, 2026

mnriem merged commit f43768d into github:main Sep 9, 2026
14 checks passed

Navigation Menu

Uh oh!

feat(workflows): add per-step integration configuration - #4425

feat(workflows): add per-step integration configuration#4425
mnriem merged 4 commits into
github:mainfrom
philo-x:feat/4275-per-step-integration-config

philo-x commented Sep 3, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

mnriem left a comment

Uh oh!

philo-x commented Sep 4, 2026

Uh oh!

mnriem commented Sep 8, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

philo-x commented Sep 9, 2026 •

edited

Loading

Uh oh!

mnriem commented Sep 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

mnriem commented Sep 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

philo-x commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Testing

AI Disclosure

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

philo-x commented Sep 4, 2026

Uh oh!

mnriem commented Sep 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

philo-x commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mnriem commented Sep 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Uh oh!

mnriem commented Sep 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

philo-x commented Sep 3, 2026 •

edited

Loading

philo-x commented Sep 9, 2026 •

edited

Loading