Generic selectors for workflow overlays

[markuswondrak]

Workflow overlays currently target steps by explicit ID. This requires repeating the same edit for every matching step when a cross-cutting behavior is needed.

Would generic overlay selectors be a relevant feature?

Potential requirements:

• Select multiple existing steps by attributes such as  type  (gate, command) or other predicates.
• Apply insert_before, insert_after, replace, or remove to every match.
• Preserve deterministic ordering and unique step IDs.
• Define behavior for nested steps and steps introduced by other overlays.
• Keep existing ID-based anchors and overlay precedence unchanged.

Example use case: attach the same step after every gate without enumerating each gate ID.

[mnriem]

Potentially useful, particularly where the same edit is repeated across several steps. Could you share a representative workflow and overlay, including what action you want to insert after each gate?

Existing overlays target steps in the base workflow, including supported nested steps, but not fan-out templates or steps introduced by other overlays. We should establish the concrete use case and smallest useful selector scope before introducing a predicate language or changing those boundaries.

Drafted for @mnriem with assistance from GitHub Copilot (model: GPT-6 Astra; interactive comment drafting).

[markuswondrak]

We try to implement cross-cutting-concers via overlays - to be fair I am not really sure myself if this is the right way to do.

The current use-case is that we need certain updates to notify users if gates are reached that need human oversight. Since we would like to target arbitrary workflows with this bundle, it's currently not possible to implement via overlays and we would need to put this logic into some kind of wrapper-implementation that controls the specify workflow.

[mnriem]

The guiding principle I would want to mention here is simplicity. If we are fighting against that we should probably reevaluate and think about it from another angle. On the notion of notifying the user that a gate has been reached I would probably say create the workflow with that in mind so add the notification as its own step before the gate?

[markuswondrak]

I get your point. Adding predicate languages or dynamic step ID generation to overlays definitely introduces significant complexity.

The reason we were exploring overlays is that we are looking at this from a platform/bundle packaging perspective: we want to distribute a reusable bundle that can instrument notifications across existing/arbitrary workflows without forking or hardcoding notification steps into every upstream definition.

If modifying the step graph via overlays is the wrong abstraction for cross-cutting notifications, how do you view headless gate lifecycle handling? Today, non-interactive runs pause at gates (StepStatus.PAUSED) and emit JSON metadata.

Would you consider an engine lifecycle hook (e.g. an on_gate_paused or workflow event callback) a better fit for notifying external channels like Slack, or is the intended pattern strictly to wrap specify workflow run --json with an external runner/orchestrator?

Drafted for @markuswondrak with assistance from GitHub Copilot (model: Gemini 3.8 Flash).