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

[markuswondrak]

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:

1. Extension hook (after_implement, before_specify, etc.) — registered in .specify/extensions.yml, dispatched by the agent reading the core command template.
2. 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?