Workflow Step Catalog — community-installable step types

[mnriem]

Summary

Add a step catalog and CLI surface for discovering, installing, and managing custom workflow step types — engine behavior plugins that extend what the workflow engine can do (deploy, notify, approve-via-slack, etc.).

Motivation

PR #2158 shipped the workflow engine with 10 built-in step types and a dynamic STEP_REGISTRY. The registry already supports runtime registration, and _get_valid_step_types() reads from it dynamically. The missing piece is a distribution mechanism for community-authored step types.

Steps are fundamentally different from:

• Extensions — which deliver agent commands (instructions for LLMs)
• Workflows — which are YAML definitions orchestrating steps

Steps are engine behaviors — execution primitives that define what the engine can do. They deserve their own catalog, following the same pattern as extensions, presets, and workflows.

CLI Surface

specify workflow step list              # show installed step types (built-in + custom)
specify workflow step add <id>          # install from step catalog
specify workflow step remove <id>       # uninstall a custom step type
specify workflow step search [query]    # find community step types
specify workflow step info <id>         # show step type details
specify workflow step catalog list      # list configured step catalog sources
specify workflow step catalog add <url> # add a step catalog source
specify workflow step catalog remove <n> # remove by index

Nested under specify workflow step since steps only exist in the workflow engine context.

Step Package Structure

steps/deploy/
├── step.yml          # metadata: type_key, description, author, version, requires
└── __init__.py       # StepBase subclass

step.yml

schema_version: "1.0"
step:
  type_key: "deploy"
  name: "Deploy Step"
  version: "1.0.0"
  author: "example-org"
  description: "Deploy artifacts to a target environment"
requires:
  speckit_version: ">=0.7.0"

Installation Layout

.specify/workflows/
├── steps/
│   ├── step-registry.json       # installed custom steps + metadata
│   └── deploy/
│       ├── step.yml
│       └── __init__.py

Catalog Files

workflows/step-catalog.json              # official step catalog
workflows/step-catalog.community.json    # community step catalog

Same resolution stack: env var → project config → user config → built-in defaults.

Implementation Notes

• STEP_REGISTRY and _get_valid_step_types() already support dynamic registration
• StepBase is a public interface — custom steps use the same API as built-in ones
• Step loading should validate the StepBase subclass at install time (importable, has type_key, execute())
• Security: custom steps run Python code — same trust boundary as extension scripts

Related

• Workflow Engine with Catalog System #2142 — Workflow Engine with Catalog System (parent issue)
• Add workflow engine with catalog system #2158 — Implementation PR (shipped the engine + built-in steps)