#4613·spec-kit

[Feature]: capture mode for command and prompt workflow steps

Author: Quratulain-bilalCreated Sep 17, 2026Updated Sep 17, 2026
Labelstriage-nice-to-have

Problem

Workflow command and prompt steps always stream output to the terminal. The stdout and stderr fields in the step output dict are always empty strings, making them inaccessible to downstream steps via {{ steps.<id>.output.stdout }}.

This limits workflow authors who need to:

  • Parse AI agent output and branch on its content
  • Pipe command output into a later step as structured data
  • Conditionally act on specific output patterns (e.g. exit messages, generated file paths)

The command step docstring (line 26) notes this as a planned enhancement:

Full stdout/stderr capture is a planned enhancement.

Proposed Solution

Add an opt-in capture: true field to command and prompt step configs. When set, dispatch uses capture_output=True so stdout and stderr are returned in the step output dict and accessible to downstream steps.

# Before (streaming, stdout/stderr always empty):
- id: plan
  type: command
  config:
    command: speckit.plan
    integration: claude

# After (capture mode, stdout/stderr available):
- id: plan
  type: command
  config:
    command: speckit.plan
    integration: claude
    capture: true
    timeout: 300

Downstream steps can then reference:

- id: parse
  type: shell
  config:
    command: "echo '{{ steps.plan.output.stdout | from_json }}'"

Design Notes

  • Backward compatible: capture defaults to false; existing workflows are unaffected
  • Follows existing pattern: ShellStep already captures output with capture_output=True and supports output_format: json
  • Timeout support: A timeout field (seconds, default 600) prevents hung commands from blocking the workflow, consistent with dispatch_command() default
  • Implementation: Requires forwarding stream=not capture to IntegrationBase.dispatch_command() which already supports both modes

Affected Files

  • src/specify_cli/workflows/steps/command/__init__.py - config schema, dispatch call, output assembly
  • src/specify_cli/workflows/steps/prompt/__init__.py - same pattern for prompt steps
  • src/specify_cli/workflows/validators.py - capture (bool) and timeout (int) validation
  • tests/test_workflows.py - capture mode regression tests

Questions

  1. Does this direction align with your roadmap for the workflow engine?
  2. Should capture mode also apply to the prompt step, or only command steps?
  3. Any preferences on the field name (capture vs capture_output vs something else)?

Happy to implement if this is something you'd like to move forward with.