Workflow extension points — how should downstream add deterministic steps without overriding installed YAML? #3473

markuswondrak · 2026-07-11T17:38:00Z

markuswondrak
Jul 11, 2026

I am working on a end-to-end agent development flow: Extended Flow, that ships three workflows (feature, bugfix, quick) that downstream projects install via specify bundle install incuding preset and extension.

A problem I am currently facing: a downstream project (a project that uses extended-flow) that needs a deterministic step (e.g. lint, type-check, security scan) cannot add it without overriding the upstream workflow YAML, which breaks upgradeability.

I see two approches for downstream projects to implement this, but both have short-comings:

Extension hook (after_implement, before_specify, etc.) — registered in .specify/extensions.yml, dispatched by the agent reading the core command template.
Local workflow override - editing .specify/workflows/<workflow-id>/workflow.yml directly.

Why hooks are not the answer

Spec-Kit's HookExecutor persists hook metadata at install time, but has no runtime callers. check_hooks_for_event() and execute_hook() are documented as "designed to be called by AI agents" — the actual execution is delegated to the agent. The workflow engine (engine.py, CommandStep.execute) has zero hook awareness.

Additionally, hook instructions are re-injected into the prompt on every command invocation inside the QA do-while loop. #2943 already documents template bloat; repeated hook checks amplify the token waste.

(I talked about this in my article in April)

Why workflow overrides are not the answer

.specify/workflows/<id>/workflow.yml is installed config. The next specify bundle install or specify bundle update will replace it. A downstream project that edits the workflow locally must re-merge on every Extended Flow release. This is documented maintenance debt with no migration tooling.

The actual problem

The root cause is not in Extended Flow's workflow design. It is in Spec-Kit's workflow architecture: there is no mechanism for an upstream workflow to declare an optional, named extension point that a downstream project can fill without touching the workflow file itself.

Possible solutions

The design space has two axes: who declares the extension point (upstream opts in vs. downstream imposes) and how the extension is resolved (manifest, file convention, inheritance, engine-level execution).

1. Step override

Downstream provides a step definition that replaces or augments a named step in the upstream workflow. The engine merges at load time.

Implementation: .specify/overrides/<workflow-id>/<step-name>.yml contains the replacement step definition. The workflow engine resolves overrides after loading the base workflow YAML.

Trade-offs:

Downstream imposes the override; upstream does not opt in
Fragile if upstream renames or restructures steps
Similar to CSS override or Nix overlays — powerful but coupling

2. Workflow inheritance

Downstream creates a workflow that extends the upstream one, adding steps at named anchors (before/after/replace).

Implementation: .specify/workflows/<id>/workflow.yml declares extends: extended-flow/feature and uses insert_after: implement or replace: verify-spec to position new steps. The engine resolves the base workflow and merges the step list.

Trade-offs:

Like class inheritance; downstream owns the extension
Upstream can still evolve the base workflow; downstream only breaks if anchors change
Requires a merge algorithm in the engine (order, conflict resolution)

3. Runtime-executed hooks (pre/post-phase)

Spec-Kit adds actual runtime hook execution at well-defined lifecycle points — not agent-dispatched, but engine-executed.

Implementation: The workflow engine calls HookExecutor.execute_hook() before and after each phase. Hooks are shell commands defined in .specify/extensions.yml with auto_run: true. The engine, not the agent, is responsible for execution.

Trade-offs:

Fixes the current hook system's reliability problem
Hooks are flat (before/after phase), not positional within a workflow
Requires upstream Spec-Kit change to the engine — the maintainer has rejected this ([Feature]: Automatically run extensions #2104)

4. Plugin step (named extension point)

Upstream workflow explicitly declares a named slot at a specific position. Downstream fills it via a separate manifest.

Implementation: Upstream workflow contains { type: plugin, name: lint }. Engine looks up .specify/plugins/lint.yml for the concrete step definition (type, command, conditions). If no plugin is registered, the step is a no-op.

Trade-offs:

Upstream opts in to the extension point; controls where extensions can happen
Most decoupled option; upstream never knows the concrete implementation
Requires a new step type in the Spec-Kit schema
Generic — benefits all presets, not just Extended Flow

5. Workflow fragments (convention-based includes)

Upstream workflow declares an include point. Engine loads all matching fragment files from a well-known directory.

Implementation: Upstream workflow contains { include: post-implement }. Engine loads all .specify/fragments/post-implement/*.yml files and inserts them at that position. No explicit plugin registration needed.

Trade-offs:

Convention-based; like WordPress action hooks (do_action('post_implement'))
Lower ceremony than plugin steps — just drop a file in a directory
Less explicit than plugin steps; harder to validate or document available extension points
Requires upstream to declare include points

I am looking for the project's intended direction on this. The concrete pain point is a downstream project that uses Extended Flow and needs to add linting to its development workflow, but the architectural gap is upstream: how can a preset offer deterministic, upgrade-safe extension points when Spec-Kit workflows are static YAML with no templating or inheritance?

mnriem · 2026-07-13T13:38:21Z

mnriem
Jul 13, 2026
Maintainer

The cleanest path here is to reuse the architecture Spec-Kit already ships for presets, applied to workflows.

PresetResolver composes a template from a priority-ranked layer stack (project override → installed presets by priority → bundled base), where each layer declares a strategy (replace/prepend/append/wrap). Composition happens at resolution time — the base file on disk is never mutated, so bundle update stays non-destructive. That's exactly your upgrade-safety requirement, and it already exists.

Ported to workflows, the unit becomes the step list instead of text, and step ids (already unique-validated) become anchors:

# .specify/workflows/overlays/<id>/lint.yml
extends: extended-flow/feature
priority: 10
edits:
  - insert_after: implement
    step: { id: lint, type: shell, command: "npm run lint" }

A WorkflowResolver (mirroring PresetResolver) merges overlays by priority; workflow run calls it instead of from_yaml. This is load-time merge only — no per-phase engine execution, so it sidesteps the runtime-hook approach rejected in #2104, and validate_workflow still runs on the composed result.

This spans both axes you raised:

Downstream imposes → insert_after/replace/remove on named anchors (your options 1–2).
Upstream opts in → base declares { type: plugin, name: post-implement }, a no-op unless filled — the step-level analog of preset wrap's {CORE_TEMPLATE} placeholder (your options 4–5).

CLI parity would follow the preset verbs: workflow overlay add --priority, set-priority, enable/disable, and a workflow resolve <id> that prints which layer contributed each step (the key answer to "which layer won?").

Net: no new architecture to invent — it's re-instantiating the preset resolver/registry/priority/strategy model against steps. If you're up for it, a PR along these lines would be very welcome — happy to help shape the overlay schema and the resolver wiring.

7 replies

mnriem Jul 13, 2026
Maintainer

This is a great write-up — you've clearly read the resolver deeply, and the LayerStackResolver end-state is where this should land. The design instinct is right.

My one concern is scope and sequencing, not direction. As written this couples three separable efforts: (1) extracting the generic resolver, (2) refactoring PresetResolver onto it without regressing, and (3) delivering the new workflow overlay contract. Each is independently reviewable; bundled, they become a long arc where a reviewer has to validate open-heart surgery on PresetResolver.resolve() — today a ~130-line hardcoded 5-tier walk that every preset/bundle command leans on — and a brand-new subsystem at once. If the generic shape turns out wrong, it churns all three.

So I'd suggest inverting the order and not abstracting first:

PR 1 — Concrete WorkflowResolver. Build it standalone against the step list: insert_after/insert_before/replace/remove, the 3 tier sources, load-time merge, validate_workflow on the composed result, and workflow resolve <id> for attribution. Borrow whatever preset patterns are useful. This ships the entire downstream-extensibility win with zero risk to presets.
PR 2 — type: plugin slot for the upstream opt-in case (your options 4–5), once the resolver it plugs into exists.
PR 3 (optional, later) — Extract the shared LayerStackResolver. With two real implementations in hand, generalizing is a safe, mechanical DRY pass instead of a speculative one — and PriorityDirection, the tier abstraction, and skip_presets design themselves correctly because concrete requirements drive each seam.

This gets Extended Flow users the capability sooner, keeps each PR reviewable in isolation, and de-risks the abstraction by deriving it from reality rather than anticipation.

On your four questions — the ordering answers most of them:

Q1 (generic vs. parallel): parallel first, generic last. The tiers aren't an abstraction in the code today, they're inlined control flow in one method — don't pay the extraction cost until there's a second real consumer to shape it. Temporary duplication you can see beats an abstraction you're guessing at.
Q4 (skip_presets in the generic model): defer. It exists solely to stop {CORE_TEMPLATE} wrap-recursion — a text-composition concern. Whether workflows need an analog only becomes clear once the plugin-slot mechanism exists; promote it then, with two callers justifying it.
Q2 (fan-out templates as anchors): exclusion is correct — ship it. The engine validates a fan-out's step template with a throwaway seen_ids set precisely because it's a runtime-multiplied stamp (parentId:templateId:index), not a uniquely-addressable node. Anchoring to it would be ambiguous and change loop semantics. Addressing into a fan-out body can be a follow-up with its own design if anyone needs it.
Q3 (bundle component kind): scoped to PR 1 — shipping overlays inside workflows components is the smaller first step; a dedicated overlays kind can come later if it earns its keep.

Happy to review PR 1's overlay schema early if you want to sanity-check the anchor semantics before you wire up the sources.

markuswondrak Jul 16, 2026
Author

PR1: #3557

Worked locally - hope it meets your expectations.

I will be happy to hear your feedback!

markuswondrak Aug 27, 2026
Author

Sorry, got hung up with different stuff. Here is PR 2: #4352

markuswondrak Sep 2, 2026
Author

@mnriem PR 1 is implemented and merged, and while actually using overlays in a downstream project we hit a gap in the edit model that I think is worth discussing.

The problem: replace is a total operation

_traverse_and_apply deep-copies the overlay's step dict over the base step (merge.py:276-281). That means changing a single attribute on an existing step — e.g. setting a specific model for one step — requires restating the entire step definition in the overlay:

# today: to change only `model`, you must copy the whole step
edits:
  - replace: implement
    step:
      id: implement
      type: command
      command: ...        # entire upstream step duplicated,
      # ...               # frozen at the time the overlay was written

Two problems with that in practice:

Upgrade coupling returns at step granularity. The overlay holds a frozen copy of the upstream step. If upstream later fixes or extends the step, the overlay's copy keeps winning — exactly the failure mode overlays exist to prevent, just pushed down one level.
Doesn't scale. "Set a specific model per step" means duplicating every step of the workflow into overlays.

(We also considered workflow-level attribute overrides — integration/model/options on the workflow root — and concluded those should stay a non-goal: the engine already resolves them in a chain of step config → workflow default → global project default, so that belongs in global config, not in per-workflow patches. The real gap is the partial edit on a step.)

Proposal: patch as a fifth edit operation

# .specify/workflows/overlays/feature/models.yml
extends: extended-flow/feature
priority: 10
edits:
  - patch: implement
    set:
      model: claude-opus-4-6
  - patch: review
    set:
      model: claude-opus-4-6

It fits the existing architecture cleanly:

Field-level composition, not anchor-level. Unlike replace/remove, multiple overlays can patch the same step: non-conflicting fields compose; conflicting fields follow the existing lower-wins priority order.
Non-destructive. patch leaves the subtree intact, so it should be treated like inserts in _check_anchor_conflicts — a patch on an ancestor combined with edits on descendants is order-independent and safe.
Guards: id is immutable via patch (it's the anchor identity), type is rejected (changing a step's type is a semantic intervention — that's what replace is for). Everything else merges into the step dict.
Small schema cost: OverlayEdit gains the operation plus a set mapping; validate_edits requires a non-empty mapping and enforces the guards.

What do you say?

mnriem Sep 2, 2026
Maintainer

Thanks for raising this. I agree that total replacement creates step-level upgrade coupling, but I’m not convinced a generic patch operation is the right solution.

If a workflow author intends a value such as model to be configurable, they should expose it as a property. That creates an explicit, documented extension contract. Similarly, slots provide explicit structural extension points. A generic patch would make every internal field implicitly overridable, bypassing those contracts and turning overlays into a general YAML-patching mechanism.

I think the intended separation should be:

Properties customize values.
Slots customize structure.
replace remains the explicit escape hatch when downstream intentionally needs to override an implementation detail.

This preserves upgradeability where the workflow author has designed for it without promising that arbitrary internal fields are stable extension points.

Posted on behalf of @mnriem by GitHub Copilot (model: GPT-5.6 Sol).

lilisalinas936-design · 2026-09-02T21:26:46Z

lilisalinas936-design
Sep 2, 2026

0 replies

Sunbelt Computer Software

PL/B Language Development and Support

Navigation Menu

Uh oh!

Workflow extension points — how should downstream add deterministic steps without overriding installed YAML? #3473

Uh oh!

{{title}}

Uh oh!

Replies: 2 comments 7 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Sunbelt Computer Software

PL/B Language Development and Support

Uh oh!

Workflow extension points — how should downstream add deterministic steps without overriding installed YAML? #3473

Uh oh!

markuswondrak Jul 11, 2026

Why hooks are not the answer

Why workflow overrides are not the answer

The actual problem

Possible solutions

1. Step override

2. Workflow inheritance

3. Runtime-executed hooks (pre/post-phase)

4. Plugin step (named extension point)

5. Workflow fragments (convention-based includes)

Replies: 2 comments · 7 replies

Uh oh!

mnriem Jul 13, 2026 Maintainer

Uh oh!

mnriem Jul 13, 2026 Maintainer

Uh oh!

markuswondrak Jul 16, 2026 Author

Uh oh!

markuswondrak Aug 27, 2026 Author

Uh oh!

markuswondrak Sep 2, 2026 Author

Uh oh!

mnriem Sep 2, 2026 Maintainer

Uh oh!

lilisalinas936-design Sep 2, 2026

markuswondrak
Jul 11, 2026

Replies: 2 comments 7 replies

mnriem
Jul 13, 2026
Maintainer

mnriem Jul 13, 2026
Maintainer

markuswondrak Jul 16, 2026
Author

markuswondrak Aug 27, 2026
Author

markuswondrak Sep 2, 2026
Author

mnriem Sep 2, 2026
Maintainer

lilisalinas936-design
Sep 2, 2026