Proposed enhancement: supported access to a run’s workflow definition

[digimangos]

I am integrating Spec Kit workflows into a GitHub Action that displays workflow progress and human review gates in issue comments.

At present, specify workflow status <run_id> --json provides the runtime state, but not the workflow definition or gate configuration. As an interim measure, the action reads the original workflow from:

.specify/workflows/runs/<run_id>/workflow.yml

This works, but it means integrations depend on Spec Kit’s internal run-state layout and file format.

I think Spec Kit could provide a supported API or library interface for retrieving the workflow definition associated with a run. The interface would return:

• workflow metadata and version;
• the resolved steps, including nested steps;
• gate messages, options, and verdict configuration;
• the exact definition used when the run was created.

The important detail is that this should resolve the definition from the run, rather than loading the current installed workflow by ID. That would keep progress rendering accurate if the workflow is later changed or removed.

I am not suggesting a command that simply dumps the underlying YAML or JSON. The value would be a stable abstraction that allows integrations to access the run’s definition without depending on internal storage details.

Would this be a useful feature for Spec Kit to support?

[mnriem]

Thanks for starting this discussion and explaining your Action use case. I think a supported run-scoped view of the workflow definition is worth exploring. An integration should not have to read the saved workflow.yml directly, and the currently installed workflow may no longer match the one used for a run.

I’d keep this distinct from workflow status, which reports execution progress and already includes details of the active gate. The new view would describe the definition saved for the run—its metadata, step tree, and configured gates. An illustrative, not final, JSON shape would be:

JSON

{
  "run_id": "662bf791",
  "definition": {
    "workflow": {"id": "spec-review", "name": "Spec review", "version": "1.0.0"},
    "steps": [
      {"id": "draft", "type": "command", "command": "speckit.specify"},
      {
        "id": "approve",
        "type": "gate",
        "message": "Review the specification.",
        "options": ["approve", "reject"],
        "on_reject": "abort"
      }
    ]
  }
}

Could you open a feature-request issue linking this discussion, with an example of what your Action needs to render? I’ll label it feature-assess and use that pipeline to examine the contract, nested and dynamic steps, and any concerns we haven’t spotted yet. If the assessment supports it, the next step would be a focused PR.