[Feature]: Compose workflows — run an installed workflow as a step

Start in the Specify CLI initialization and commands component, locating workflow step registration and the engine.resume entry point. Trace how installed workflow IDs, child runs, outputs, and ancestry are represented; done means all listed acceptance criteria are covered by documentation and tests, including re-entry, cycle rejection, validation, and failure propagation.

Problem Statement

Workflows can orchestrate commands but not other workflows. There is no workflow step type and overlays only edit a single base workflow, so a meta-workflow that routes to different workflows must copy their steps or shell out to specify workflow run opaquely.

Proposed Solution

Add a workflow step type that runs an already-installed workflow by ID:

- id: route
  type: if
  condition: "{{ steps.triage.output.stdout | contains('bug') }}"
  then:
    - id: run-bug
      type: workflow
      workflow: bug            # installed workflow id
      input: { spec: "{{ inputs.spec }}" }
  else:
    - id: run-speckit
      type: workflow
      workflow: speckit        # installed workflow id
      input: { spec: "{{ inputs.spec }}" }

Installed IDs only. The step starts the sub-workflow as its own run and exposes typed output:

{ "status": ..., "run_id": ..., "steps": {<child step id>: <child step_result>} }

downstream as {{ steps.run-bug.output.steps.<child_id>.output... }} (scoped under the parent step id, so no collision with other top-level step results).

Re-entry: the child run_id is deterministic — sanitize(f"{parent_run_id}-{effective_step_id}") (the effective id already carries loop/fan-out iteration). On re-execution the step looks up that run: paused/failed → engine.resume(child_run_id); terminal → reuse the persisted result; absent → start it. A sub-workflow that pauses at a gate therefore resumes from its own top-level state, with no duplicate runs even if the parent crashed before recording output.

Cycle safety: each run carries a path-based workflow_ancestry; the step refuses a child already on the path (or exceeding a max depth) and passes ancestry + [current_id] down — diamonds stay legal, only true cycles are blocked. Checked at runtime since target IDs may be expressions.

Alternatives Considered

• Shell step calling specify workflow run --json — opaque, loses typed output, can't re-enter a paused sub-run.
• Copying steps / overlays — duplicates logic and drifts.
• Generic nested-resume via the top-level step index — engine-wide redesign; sidestepped by the deterministic run-id handoff.

Component

Specify CLI (initialization, commands)

AI Agent

Not applicable

Use Cases

1. Triage/routing meta-workflow dispatching to existing bug vs. speckit workflows.
2. Reusing a shared sub-workflow across several parent workflows.

Acceptance Criteria

• workflow step type registered, documented, and tested.
• Resolves installed IDs only; rejects unknown, path-like, and disabled workflows.
• input: supports expressions and validates against the target schema.
• Output {status, run_id, steps} exposed and readable downstream.
• Deterministic child run_id; paused/failed child resumed via engine.resume; terminal child reused; no duplicate runs after a crash.
• Path-based cycle detection plus max-depth backstop.
• Failed/aborted child surfaces as a failed/aborted parent step.

Additional Context

Follow-up to discussion #4647 (maintainer approved).

AI Disclosure

Created with opencode (model: deepseek-v4.1-flash, human-supervised) on behalf of @markuswondrak, based on the AI-assisted draft in discussion #4647.