[Feature]: Add local (--dev) installation for custom workflow step types

[markuswondrak]

Problem Statement

Custom workflow step types are the only first-class Spec-Kit component that cannot be installed from a local path. Every other artifact supports local development, but steps are catalog/HTTPS-only:

Component	Local/dev install	Custom URL
Extension	specify extension add --dev <dir>	--from <url>
Preset	specify preset add --dev <dir>	--from <url>
Workflow	specify workflow add <path> --dev	--from <url>
Bundle	specify bundle install <path>	—
Step	none	none

specify workflow step add accepts only a catalog step id and fetches step.yml/__init__.py (and optional extra_files) over HTTPS (src/specify_cli/workflows/step/command_add.py, _safe_fetch rejects non-HTTPS). There is no --dev or --from.

This makes custom steps impossible to iterate on or test from a checkout:

1. A developer must publish the step package to an HTTPS catalog (or run a localhost catalog server) before they can run it once.
2. CI cannot install a step from the repository under test without a network round-trip to a hosted catalog.
3. Bundles that declare provides.steps cannot be developed or validated offline — bundle install delegates step installs to workflow_step_add(component.id) (bundler/services/primitives.py), which always resolves through the step catalog.
4. Manually copying files into .specify/workflows/steps/<id>/ works at runtime (load_custom_steps scans the directory) but is undocumented, unvalidated, and leaves the registry out of sync.

Net effect: the step type is second-class relative to extensions, presets, and workflows, and the only way to develop one is a throwaway localhost HTTPS/HTTP catalog.

Proposed Solution

Bring specify workflow step add to feature parity with the other components:

• Add --dev <dir> to install a custom step from a local package directory containing step.yml, __init__.py, and any extra_files. It copies the package into .specify/workflows/steps/<id>/ and records it in the step registry with source: local, mirroring preset add --dev / extension add --dev.
• Add --from <url> to install a single step package directly from a URL, mirroring the other components' --from.
• Apply the same safety guards the catalog path already uses: validate step.type_key, reject ids that collide with built-in step types, reject duplicate installs (with a consistent --force/reinstall semantic), and keep the symlink/.. path-escape guards on the destination.
• Optionally support bundle install <local dir> resolving provides.steps from the local bundle directory instead of the catalog stack, so step-bearing bundles work offline.

Alternatives Considered

• Manual copy into .specify/workflows/steps/<id>/ — works because load_custom_steps scans the directory, but it's undocumented, skips validation, and doesn't register provenance, so workflow step list/remove/bundle tracking miss it.
• Localhost step catalog — _validate_catalog_url already permits http://localhost, so a developer can run a local server and register it as a catalog. This is the current workaround, but it is heavy, undocumented, and not usable in CI without extra plumbing.
• Ship the step inside a preset/extension archive — not possible: the engine only loads custom steps from .specify/workflows/steps/.

Component

Specify CLI (initialization, commands)

AI Agent (if applicable)

Not applicable

Use Cases

1. Iterating on a custom step type while developing a bundle that uses it, without publishing to a catalog on every change.
2. Running a bundle's integration tests in CI against a local checkout of the step package.
3. Authoring a step locally, then publishing it to a catalog only once it is stable.
4. Offline development of step-bearing bundles.

Acceptance Criteria

• specify workflow step add --dev <dir> installs a local step package into .specify/workflows/steps/<id>/.
• The installed step is loaded by workflow run, workflow resume, and workflow add, and appears in workflow step list.
• --dev validates step.yml/__init__.py, rejects collisions with built-in step types, and rejects duplicate installs with the same semantics as the catalog path.
• Destination path/symlink safety guards match the catalog install path.
• Registry provenance records a local source (consistent with presets/extensions), so workflow step remove cleans up correctly.
• --from <url> installs a single step package from a URL.
• bundle install <local dir> resolves and installs provides.steps from the local bundle source (or the limitation is explicitly documented).
• Docs (docs/reference/workflows.md step-type section) and tests cover the new paths.

Additional Context

• Command surface: src/specify_cli/workflows/step/command_add.py (workflow_step_add(step_id), _safe_fetch HTTPS-only).
• Catalog/URL validation: src/specify_cli/workflows/step/catalog/_domain.py (_validate_catalog_url).
• Loader: src/specify_cli/workflows/__init__.py (load_custom_steps) — confirms local directory loading already works at runtime; only installation tooling is missing.
• Bundle delegation: bundler/services/primitives.py (steps → workflow_step_add).
• Parity references: install_from_directory in src/specify_cli/presets/__init__.py, and --dev handling for extensions and workflows.
• Motivating use case: a bundle that ships a custom step to consolidate run setup currently has to choose between a network-only component and a localhost catalog workaround.

AI Disclosure

Drafted with opencode (model deepseek-v4.1-flash), human-supervised and reviewed before submission.

[github-actions]

Feature assessment — local-step-install · Stage 1/5: Intake\n\n# Idea Intake: Local installation for custom workflow steps

• Slug: local-step-install
• Created: 2026-09-23T16:42:35Z
• Source: [Feature]: Add local (--dev) installation for custom workflow step types #4695 (labeled feature-assess)
• Type: improvement

Idea (as captured)

Custom workflow step types should support local (--dev) installation and direct URL (--from) installation, with validation, provenance tracking, and safe cleanup comparable to extensions, presets, and workflows. Bundle installation should optionally resolve step components from a local bundle source so step-bearing bundles can be developed and tested offline.

The source is issue #4695, raised by markuswondrak. No issue comments added further scope.

Restated

The request proposes bringing custom workflow-step installation to parity with other Spec Kit component types by supporting local development packages and direct URL packages. It also proposes improving offline/local bundle handling for bundles that provide custom steps.

Origin & Context

• Raised by: markuswondrak (issue author)
• Trigger: A feature request describing the lack of local and direct-URL installation paths for custom workflow steps, and the resulting need to publish to a catalog or run a localhost catalog during development.

First-Glance Unknowns

• [NEEDS CLARIFICATION: Should --from accept the same package forms as local installation, or only a URL exposing the required files?]
• [NEEDS CLARIFICATION: What exact source/provenance schema should distinguish local and URL installs while preserving existing registry compatibility?]
• [NEEDS CLARIFICATION: Is local resolution for bundle install required in the first release or should it be explicitly deferred?]
• [NEEDS CLARIFICATION: What reinstall/force semantics are expected for an already-installed step?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4695 · copilot · gpt52codex · 4.26 AIC · ⌖ 8.61 AIC · ⊞ 24.2K · ◷

[github-actions]

Feature assessment — local-step-install · Stage 2/5: Research\n\n# Idea Research: Local installation for custom workflow steps

• Slug: local-step-install
• Created: 2026-09-23T16:42:35Z
• Evidence confidence (overall): medium

Users & Demand

• The issue identifies developers iterating on custom steps, CI authors testing bundles from a checkout, and authors who want to publish only after a step is stable — [source: [Feature]: Add local (--dev) installation for custom workflow step types #4695] (confidence: medium, cited).
• The repository has a first-class custom-step loader and registry, indicating that installed custom steps are an intended project capability rather than an entirely hypothetical use case — [source: src/specify_cli/workflows/__init__.py, src/specify_cli/workflows/step/catalog/_domain.py] (confidence: high, cited).
• No usage telemetry, support-ticket volume, or independent user interviews were found in the issue or repository search — [NEEDS CLARIFICATION: quantify demand and frequency of local-step development] (confidence: high, cited gap).

Prior Art

• Workflow installation already supports --dev for local YAML files/directories/archives and --from for custom URLs — [source: src/specify_cli/workflows/command_add.py, docs/reference/workflows.md] (confidence: high, cited).
• Extension and preset installation expose local development and direct URL paths, establishing a repository precedent for component parity — [source: src/specify_cli/extensions/command_add.py, src/specify_cli/presets/command_add.py] (confidence: high, cited).
• Current step installation accepts only a catalog id, downloads step.yml, __init__.py, and optional extra files, validates the declared type key, applies package limits, stages atomically, and records registry provenance as "source": "catalog" — [source: src/specify_cli/workflows/step/command_add.py] (confidence: high, cited).
• The runtime loader already scans .specify/workflows/steps/, rejects symlinked paths/files, validates the package shape, imports a matching StepBase, and registers it — [source: src/specify_cli/workflows/__init__.py] (confidence: high, cited).
• Bundle step installation delegates to workflow_step_add(component.id), and the bundler rejects offline step installation because it assumes catalog/network resolution — [source: src/specify_cli/bundles/primitives.py] (confidence: high, cited).

Market & Context

• Today’s documented alternatives are catalog publication or a localhost catalog; the issue also reports undocumented manual copying. The repository confirms the catalog-only command surface, but does not independently measure the cost of those workarounds — [source: [Feature]: Add local (--dev) installation for custom workflow step types #4695; src/specify_cli/workflows/step/command_add.py] (confidence: medium, cited).
• The cost of doing nothing is continued asymmetry between steps and other installable components, especially for offline bundle validation — [source: [Feature]: Add local (--dev) installation for custom workflow step types #4695; src/specify_cli/bundles/primitives.py] (confidence: medium, cited).

Data & Constraints

• Required package files are step.yml and __init__.py; catalog installs may include bounded extra_files, validate step.type_key, reject built-in collisions, and enforce size/file limits — [source: src/specify_cli/workflows/step/command_add.py] (confidence: high, cited).
• Destination safety requires a direct child of .specify/workflows/steps/ after resolution, and registry writes refuse symlinked parents or registry files — [source: src/specify_cli/workflows/step/_helpers.py, src/specify_cli/workflows/step/catalog/_domain.py] (confidence: high, cited).
• URL downloads allow HTTPS (with localhost HTTP exception) and reject insecure redirects; any --from path must preserve those download controls — [source: src/specify_cli/workflows/step/command_add.py, src/specify_cli/workflows/step/catalog/_domain.py] (confidence: high, cited).
• Bundle manifests can declare steps, but the current step primitive has no bundled/local-source branch — [source: src/specify_cli/bundles/manifest.py, src/specify_cli/bundles/primitives.py] (confidence: high, cited).

Evidence Against the Idea

• Demand is currently stated by one issue author with no observed usage metric, so a broad parity feature could exceed demonstrated need — [source: [Feature]: Add local (--dev) installation for custom workflow step types #4695] (confidence: medium, cited).
• Supporting arbitrary local packages and URL forms could duplicate validation and provenance logic or create inconsistent reinstall semantics unless a shared installation path is established — [source: src/specify_cli/workflows/step/command_add.py] (confidence: medium, cited).
• Offline bundle support may be a separate scope increase from single-step installation and could introduce source/version-resolution edge cases — [source: src/specify_cli/bundles/primitives.py] (confidence: medium, cited).

Gaps & Open Questions

• [NEEDS CLARIFICATION: What local package forms and URL package formats are required?]
• [NEEDS CLARIFICATION: Should --from accept a directory/archive URL or individual file URLs?]
• [NEEDS CLARIFICATION: What registry fields and update/remove semantics represent local and URL provenance?]
• [NEEDS CLARIFICATION: Is bundle-local step resolution a first-release requirement?]
• [NEEDS CLARIFICATION: What demand threshold justifies the larger bundle integration scope?]

Sources

• https://github.com/github/spec-kit/issues/4695 (host: github.com, policy: allowlisted)
• src/specify_cli/workflows/step/command_add.py (repository)
• src/specify_cli/workflows/step/catalog/_domain.py (repository)
• src/specify_cli/workflows/__init__.py (repository)
• src/specify_cli/bundles/primitives.py (repository)
• docs/reference/workflows.md (repository)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4695 · copilot · gpt52codex · 4.26 AIC · ⌖ 8.61 AIC · ⊞ 24.2K · ◷

[github-actions]

Feature assessment — local-step-install · Stage 3/5: Problem\n\n# Problem Definition: Local installation for custom workflow steps

• Slug: local-step-install
• Created: 2026-09-23T16:42:35Z
• Inputs used: intake.md | research.md

Problem Statement

Developers and CI maintainers who create or consume custom workflow steps cannot install a step package from the local checkout or a direct package URL, while comparable Spec Kit components support those paths. As a result, validating a custom step or a bundle that provides one requires catalog publication, a localhost catalog workaround, or undocumented manual copying, which increases iteration friction and weakens reproducibility.

Affected Users & Stakeholders

• Users: Custom-step authors — cannot iterate and test from a checkout through the supported CLI.
• Users: CI and bundle authors — cannot reliably validate step-bearing bundles offline or without a catalog round-trip.
• Stakeholders: Spec Kit maintainers — own CLI consistency, safety validation, registry provenance, and documentation.
• Stakeholders: Teams consuming custom steps — depend on predictable install, list, run, resume, and remove behavior.

Goals

• Enable a supported, validated development path for custom step packages from local sources.
• Enable a supported direct URL path where it is needed for parity with other components.
• Preserve safe destination handling, package validation, registry provenance, and reliable removal.
• Make the supported path usable in CI and offline/local bundle development where the source is available locally.

Non-Goals

• Redesigning workflow execution or the custom-step runtime loader.
• Defining new step semantics, APIs, or package contents beyond installation concerns.
• Replacing catalogs or changing the security policy for remote downloads.
• Expanding bundle behavior beyond the minimum needed to resolve local step sources.

Success Metrics

• A local custom step can be installed through the documented CLI and then appears in workflow step list, loads for workflow execution/resume, and can be removed cleanly (baseline: unsupported; target: covered by automated tests).
• Invalid type keys, built-in collisions, duplicates, path escapes, symlinked destinations, and malformed packages are rejected without leaving unregistered files (baseline: catalog path has guards; target: equivalent guards on new paths).
• A supported direct URL install, if included, preserves existing HTTPS/redirect/package-size safety behavior (baseline: no step URL command; target: documented and tested).
• A local step-bearing bundle can be installed without a catalog/network round-trip, if that scope is selected (baseline: _StepKindManager requires network; target: offline integration test).
• [NEEDS CLARIFICATION: quantitative target for developer setup/iteration time reduction.]

Cost of Inaction

Custom-step development remains less capable than extension, preset, and workflow development. Authors continue to publish unstable packages or maintain local catalog infrastructure, and CI cannot validate local step-bearing bundles through the supported installation path. Manual copies remain possible but outside registry and documentation guarantees.

Open Questions

• [NEEDS CLARIFICATION: Which local source forms are required: package directory only, archive, or single step.yml plus __init__.py files?]
• [NEEDS CLARIFICATION: Which URL package forms and provenance fields are required for --from?]
• [NEEDS CLARIFICATION: Is local bundle resolution in scope for the first release?]
• [NEEDS CLARIFICATION: What exact duplicate/reinstall/force semantics should apply?]
• [NEEDS CLARIFICATION: What measurable adoption or time-saving target should determine success?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4695 · copilot · gpt52codex · 4.26 AIC · ⌖ 8.61 AIC · ⊞ 24.2K · ◷

[github-actions]

Feature assessment — local-step-install · Stage 4/5: Concept\n\n# Concept: Local installation for custom workflow steps

• Slug: local-step-install
• Created: 2026-09-23T16:42:35Z
• Recommended option: Option A — parity-first local step install

Options

Option A — Parity-first local step install

• Sketch: Add a supported local development install for a validated step package, and add direct URL installation only if it can share the same package validation, staging, registry, and cleanup path. Keep bundle-local resolution as a narrowly bounded follow-on or explicitly document it as deferred.
• Appetite: medium
• Trade-offs: Directly addresses the clearest workflow and CI pain while reusing existing safety expectations; postponing bundle resolution leaves some offline bundle friction. Main risks are inconsistent source metadata and duplicated install logic.
• Rabbit holes: Reinstall/force semantics, archive/URL package formats, compatibility of registry schema, and extra-file handling.

Option B — Full component-parity release

• Sketch: Deliver local and direct-URL step installation together with local-source resolution for step-bearing bundles, presenting all sources through one consistent user-facing model.
• Appetite: large
• Trade-offs: Maximizes parity and offline capability; carries the greatest scope and source-resolution complexity, and may delay the basic local authoring win.
• Rabbit holes: Bundle manifest source conventions, version pinning, mixed local/catalog dependency graphs, and rollback across multiple component installs.

Option C — Documented local catalog workaround

• Sketch: Improve documentation and examples for running a localhost catalog and manually validating a step package, without adding new step installation modes.
• Appetite: small
• Trade-offs: Lowest implementation risk and preserves one install path; does not remove the network/server setup burden or provide true offline/local component parity.
• Rabbit holes: Keeping the workaround secure and reproducible across platforms, and documenting behavior that remains outside the registry/install contract.

Recommendation

Recommend Option A. The issue and repository evidence clearly support a parity gap at the single-step install boundary, while bundle-local resolution is a distinct expansion. A medium-sized, shared install path can target the stated success metrics for local authoring and CI without committing the project to the larger bundle dependency problem before its requirements are known.

Out of Scope (for the recommended option)

• Workflow engine or step runtime redesign.
• Replacing the catalog or weakening HTTPS/redirect/path safety controls.
• General dependency resolution for bundles.
• Full archive and multi-source bundle support unless required by clarified package semantics.
• A final decision on bundle-local step resolution before its source/version requirements are specified.

Assumptions to Validate

• A step package directory containing step.yml, __init__.py, and optional companion files is the minimum useful local source.
• Existing step validation and loader behavior can be shared by local and remote installation paths.
• Registry provenance can be extended without breaking existing list/remove behavior.
• Direct URL installation is valuable enough to include after its accepted package form is clarified.
• The first release can defer or separately scope bundle-local step resolution.

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4695 · copilot · gpt52codex · 4.26 AIC · ⌖ 8.61 AIC · ⊞ 24.2K · ◷

[github-actions]

Feature assessment — local-step-install · Stage 5/5: Decision — verdict needs-clarification\n\n# Decision: Local installation for custom workflow steps

• Slug: local-step-install
• Decided: 2026-09-23T16:42:35Z
• Verdict: needs-clarification
• Artifacts reviewed: intake.md | research.md | problem.md | concept.md

Scorecard

Criterion	Rating	Justification
Problem validity	adequate	The repository exposes custom-step loading and registry behavior, while the issue documents a concrete parity gap and development workaround.
Evidence strength	adequate	Code evidence is strong, but demand is primarily one issue report with no usage or time-saved metrics.
Value vs. inaction	adequate	Inaction preserves catalog/server friction and weak offline validation; the size of that cost is not quantified.
Feasibility / appetite	adequate	A parity-first local install is a credible medium concept, but package and reinstall semantics remain unresolved.
Strategic fit	strong	Local installation already exists for extensions, presets, and workflows, and step installation is a documented CLI concern.
Risk posture	weak	Path, package, and URL safety controls are known, but registry compatibility, remote package shape, and bundle source/version risks are not yet bounded.

Verdict & Rationale

The idea is promising and strategically aligned, but it is not ready for a go verdict. The recommended parity-first concept is plausible, yet the evidence and scope are blocked by unanswered package-format, provenance, reinstall, and bundle-local-resolution questions. Per the assessment gate, clarify those questions and revisit research/shape before handing the work to specification.

If needs-clarification

• Blocking questions:
  • [NEEDS CLARIFICATION: Is the first release limited to a local package directory, or must it support archives and/or individual-file URLs?]
  • [NEEDS CLARIFICATION: What exact --from URL contract and remote package provenance should be supported?]
  • [NEEDS CLARIFICATION: What duplicate, reinstall, and --force semantics are required?]
  • [NEEDS CLARIFICATION: Is local resolution for bundle install a first-release requirement, and how are source paths and version pins represented?]
  • [NEEDS CLARIFICATION: What measurable demand or iteration-time target should justify the medium/large scope?]
• Revisit stage: research | shape

If go — Handoff to /speckit-specify

Not applicable: the verdict is needs-clarification.

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4695 · copilot · gpt52codex · 4.26 AIC · ⌖ 8.61 AIC · ⊞ 24.2K · ◷

[mnriem]

@markuswondrak Go for it! Keeping mind that we want to indeed align as much as possible with how the other commands operate in this space. If you have to make a call please document it.

[markuswondrak]

Clarification resolution

Following the assessment and the maintainer direction to proceed while aligning with comparable commands, the open questions are resolved as follows.

• First-release source forms: Support a local package directory through specify workflow step add <step_id> --dev <directory> and a remote .zip, .tar.gz, or .tgz package through --from <url>. Bare step.yml and other individual-file URL forms are out of scope.
• Identity and flags: Keep <step_id> required in every mode and require step.yml to declare the same step.type_key. --dev and --from take values, are mutually exclusive, and reject empty values. This preserves the existing step ID positional while following the preset-style local source option.
• Package contents and validation: Copy the complete package recursively so helper modules and data files work. Require root-level step.yml and __init__.py; reject symlinks and special files; apply the existing 512-file/50 MiB limits; and use the shared safe archive extraction, path-containment, HTTPS/loopback, redirect, and bounded-download protections. Installation validates __init__.py as a required safe regular file but does not import untrusted Python merely to inspect it. Runtime loading continues to require a matching StepBase subclass.
• Duplicate and reinstall behavior: Preserve default duplicate rejection. Add --force uniformly for catalog, local, and URL installs. Replacement must stage and validate the new package before transactionally replacing the old package and registry entry, with rollback on failure. A separate workflow step update command is deferred.
• Trust prompt: Explicit --from installation uses the workflow/extension default-deny confirmation before any network request and warns that the package contains executable Python.
• Provenance: Record source kind as exactly catalog, local, or url. Retain catalog_name only for catalog installs. Do not persist local paths or URLs in the project registry.
• Bundle-local resolution: Defer resolving step payloads from local bundle directories, bundle.yml, or ZIP artifacts in the first release. Issue acceptance allows this limitation to be documented. A follow-up must define the bundle-relative source contract, containment/symlink rules, artifact behavior, and fallback policy before implementation.
• Documentation: Add custom step package and command documentation beneath the existing Step Types section in docs/reference/workflows.md, and document the deferred bundle-local limitation in docs/reference/bundles.md.
• Demand/evidence: No quantitative usage or iteration-time data is available. The maintainer’s “Go for it!” accepts the reported use cases and architectural parity gap as sufficient to proceed with this bounded scope; missing telemetry remains an evidence limitation, not an implementation blocker.

These decisions leave the feature ready for specification while documenting the calls required where extension, preset, and workflow conventions differ.

Posted on behalf of @markuswondrak by OpenCode (model: github-copilot/gpt-5.6-sol, autonomous); this comment was fully AI-drafted from the issue discussion and repository analysis.

[mnriem]

Eagerly awaiting the PR :)