π« Toolkit to help you get started with SDD or any other process!
feat(workflows): add workflow step submission intake (#4861)
Manfred Riem1111ee59ca16
diff --git a/.github/ISSUE_TEMPLATE/workflow_step_submission.yml b/.github/ISSUE_TEMPLATE/workflow_step_submission.ymlnew file mode 100644index 000000000..70120d472--- /dev/null+++ b/.github/ISSUE_TEMPLATE/workflow_step_submission.yml@@ -0,0 +1,254 @@+name: Workflow Step Type Submission+description: Submit a custom workflow step package for community catalog intake+title: "[Workflow Step]: Add "+labels: ["triage-must-have"]+body:+ - type: markdown+ attributes:+ value: |+ Thanks for contributing a workflow step type! This form captures the package, release, and catalog metadata needed for manual community catalog review.++ **Before submitting:**+ - Review the [Community Workflow Step Types guide](https://github.com/github/spec-kit/blob/main/docs/community/workflow-steps.md)+ - Publish a package containing root-level `step.yml` and `__init__.py` files+ - Ensure `step.type_key`, the catalog ID, and the matching `StepBase.type_key` are identical+ - Create a GitHub release with a versioned step package archive+ - Provide version-pinned URLs and SHA-256 digests for every catalog-downloaded file+ - Test the release artifact with `specify workflow step add <step-id> --from <download-url>`++ **After submitting:** GitHub automatically applies only the `triage-must-have` intake verdict. This phase is intake-only: no validation workflow or draft pull request is triggered. Maintainers currently review the metadata manually and, when accepted, update the community catalog through the normal reviewed pull request process.++ - type: input+ id: step-id+ attributes:+ label: Step Type ID+ description: Exact catalog key and `step.type_key`; it must be one safe path component and must not collide with a built-in step type+ placeholder: "e.g., deploy"+ validations:+ required: true++ - type: input+ id: step-name+ attributes:+ label: Step Type Name+ description: Human-readable name declared in `step.yml`+ placeholder: "e.g., Deploy"+ validations:+ required: true++ - type: input+ id: version+ attributes:+ label: Version+ description: PEP 440-compatible release version; it must match `step.version` in the submitted `step.yml`+ placeholder: "e.g., 1.0.0"+ validations:+ required: true++ - type: textarea+ id: description+ attributes:+ label: Description+ description: Concise description of the workflow behavior this step type implements+ placeholder: Deploys the current project to a configured environment and returns the deployment URL+ validations:+ required: true++ - type: input+ id: author+ attributes:+ label: Author+ description: Name or organization declared for the package+ placeholder: "e.g., Jane Doe or Acme Corp"+ validations:+ required: true++ - type: input+ id: repository+ attributes:+ label: Repository URL+ description: Public source repository containing the submitted package+ placeholder: "https://github.com/your-org/spec-kit-step-deploy"+ validations:+ required: true++ - type: input+ id: download-url+ attributes:+ label: Download URL+ description: URL to the versioned `.zip`, `.tar.gz`, or `.tgz` step package archive for this release+ placeholder: "https://github.com/your-org/spec-kit-step-deploy/releases/download/v1.0.0/deploy-1.0.0.zip"+ validations:+ required: true++ - type: input+ id: step-yml-url+ attributes:+ label: step.yml URL+ description: Exact tag-pinned HTTPS URL used as the catalog `step_yml_url` (or `url`)+ placeholder: "https://raw.githubusercontent.com/your-org/spec-kit-step-deploy/v1.0.0/step.yml"+ validations:+ required: true++ - type: input+ id: init-url+ attributes:+ label: __init__.py URL+ description: Exact tag-pinned HTTPS URL used as the catalog `init_url`+ placeholder: "https://raw.githubusercontent.com/your-org/spec-kit-step-deploy/v1.0.0/__init__.py"+ validations:+ required: true++ - type: textarea+ id: extra-files+ attributes:+ label: Extra File URLs+ description: >-+ JSON mapping of every additional package-relative file path to its exact tag-pinned HTTPS URL.+ Paths must use forward slashes, be relative and non-empty, contain no empty, `.` or `..` segments,+ and must not case-insensitively alias `step.yml` or `__init__.py`. Enter `{}` when there are no extra files.+ render: json+ placeholder: |+ {+ "helpers.py": "https://raw.githubusercontent.com/your-org/spec-kit-step-deploy/v1.0.0/helpers.py"+ }+ validations:+ required: true++ - type: textarea+ id: file-sha256+ attributes:+ label: Per-file SHA-256 Digests+ description: JSON mapping containing exactly `step.yml`, `__init__.py`, and every Extra File URL path, each with a 64-character hexadecimal SHA-256 digest+ render: json+ placeholder: |+ {+ "step.yml": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",+ "__init__.py": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",+ "helpers.py": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"+ }+ validations:+ required: true++ - type: input+ id: license+ attributes:+ label: License+ description: SPDX license identifier for the package; the repository must include the corresponding license text+ placeholder: "e.g., MIT or Apache-2.0"+ validations:+ required: true++ - type: input+ id: speckit-compatibility+ attributes:+ label: Spec Kit Compatibility+ description: Spec Kit version constraint tested with this release; the current step catalog does not yet enforce this constraint+ placeholder: "e.g., >=0.11.0"+ validations:+ required: true++ - type: textarea+ id: runtime-dependencies+ attributes:+ label: Runtime and Tool Dependencies+ description: List required Python packages, executables, services, environment variables, or platform constraints; enter `None` when the package has no external dependencies+ placeholder: |+ - Python package: requests>=2.32+ - Executable: kubectl>=1.30+ - Environment variable: KUBECONFIG+ validations:+ required: true++ - type: dropdown+ id: step-type-count+ attributes:+ label: Number of Provided Step Types+ description: One installed package currently registers exactly one `step.type_key`+ options:+ - "1"+ validations:+ required: true++ - type: textarea+ id: step-types-provided+ attributes:+ label: Step Type Provided+ description: Name the single `StepBase` subclass and its exact `type_key`+ placeholder: "DeployStep β deploy"+ validations:+ required: true++ - type: input+ id: documentation+ attributes:+ label: Documentation URL+ description: Tag-pinned documentation covering configuration, outputs, failure behavior, side effects, and an example workflow+ placeholder: "https://github.com/your-org/spec-kit-step-deploy/blob/v1.0.0/README.md"+ validations:+ required: true++ - type: input+ id: changelog+ attributes:+ label: Changelog URL+ description: Tag-pinned changelog for this release; leave empty only for an initial release with no prior versions+ placeholder: "https://github.com/your-org/spec-kit-step-deploy/blob/v1.0.0/CHANGELOG.md"++ - type: textarea+ id: testing-details+ attributes:+ label: Testing Details+ description: Describe positive and negative configuration tests, execution/status/output tests, and any resume, nested, or concurrent behavior that applies+ placeholder: |+ **Tested with:** Spec Kit 0.11.0 on macOS and Ubuntu++ **Evidence:**+ - Valid configuration completes with the documented outputs+ - Invalid configuration returns a failed result with an actionable error+ - Release artifact installs with `specify workflow step add deploy --from ...`+ validations:+ required: true++ - type: checkboxes+ id: attestations+ attributes:+ label: Required Attestations+ description: Confirm the submitted release satisfies the current external step-package contract+ options:+ - label: The release artifact contains regular, non-symlink `step.yml` and `__init__.py` files at the package root or under exactly one top-level directory+ required: true+ - label: The catalog ID, `step.type_key`, and the matching `StepBase.type_key` are identical and do not collide with a built-in step type+ required: true+ - label: The submitted version matches `step.version`, the download URL identifies that versioned release, and every catalog file URL is version-pinned+ required: true+ - label: The SHA-256 mapping covers exactly every file the catalog installer downloads+ required: true+ - label: The release artifact installs successfully with `specify workflow step add <step-id> --from <download-url>`+ required: true+ - label: Runtime and tool dependencies, side effects, configuration, outputs, and failure behavior are documented+ required: true+ - label: The repository includes the submitted license and complete source for the released package+ required: true+ - label: I understand that custom workflow steps execute Python with the user's privileges and that a community catalog listing is not a code audit, endorsement, or support commitment+ required: true++ - type: textarea+ id: additional-context+ attributes:+ label: Additional Context+ description: Optional links or notes that help maintainers verify the submitted metadata+ placeholder: Release notes, compatibility notes, or related issue links++ - type: textarea+ id: ai-disclosure+ attributes:+ label: AI Disclosure+ description: >-+ Per our [Contributing guidelines](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#ai-contributions-in-spec-kit),+ any AI assistance used to create this issue must be disclosed. If you used AI, name the agent/tool, model(s),+ settings/mode (reasoning effort; autonomous vs. human-supervised), and extent. Otherwise leave this as "N/A".+ This does not change how your issue is handled β it just gives maintainers visibility into model/agent usage.+ value: "N/A"+ validations:+ required: truediff --git a/docs/community/overview.md b/docs/community/overview.mdindex 48b0d42d7..3a03856ac 100644--- a/docs/community/overview.md+++ b/docs/community/overview.md@@ -24,6 +24,13 @@ Bundles compose extensions, presets, workflows, and steps into role or team stac[Browse community bundles β](bundles.md)+## Workflow step types++Workflow step types add reusable executable behavior that workflows can select+with `type:`.++[Submit a community workflow step type β](workflow-steps.md)+## WalkthroughsStep-by-step guides that show Spec-Driven Development in action across different scenarios, languages, and frameworks.@@ -41,5 +48,6 @@ Community projects that extend, visualize, or build on Spec Kit β including VSTo publish your own work, follow the[Extension Publishing Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md),the [Presets Publishing Guide](https://github.com/github/spec-kit/blob/main/presets/PUBLISHING.md),-or the [Community Bundles guide](bundles.md). For help choosing a component type,-see [Customize Spec Kit](../guides/customization.md).+the [Community Bundles guide](bundles.md), or the+[Community Workflow Step Types guide](workflow-steps.md). For help choosing a+component type, see [Customize Spec Kit](../guides/customization.md).diff --git a/docs/community/workflow-steps.md b/docs/community/workflow-steps.mdnew file mode 100644index 000000000..530fb514f--- /dev/null+++ b/docs/community/workflow-steps.md@@ -0,0 +1,129 @@+# Community Workflow Step Types++> [!NOTE]+> Community workflow step types are independently created and maintained by+> their authors. Maintainers verify submission metadata and package shape; they+> do **not review, audit, endorse, or support the executable Python code**.+> Installation validates and copies the package without importing its Python+> code. Later `specify workflow add`, `run`, and `resume` commands load installed+> step packages, executing import-time code with the user's privileges. Review+> the source before using an installed step.++Custom workflow step packages add a `type:` that workflows can use beyond the+built-in step types. The canonical intake path is the+[Workflow Step Type Submission](https://github.com/github/spec-kit/issues/new?template=workflow_step_submission.yml)+issue form.++This is currently an **intake-only** process. Opening the form applies only the+`triage-must-have` verdict. It does not trigger catalog validation, create a+branch, or open a draft pull request. Maintainers review submissions manually+and, when accepted, update+[`workflows/step-catalog.community.json`](https://github.com/github/spec-kit/blob/main/workflows/step-catalog.community.json)+through the normal reviewed pull request process.++The built-in community catalog is **discovery-only**. Accepted entries can+appear in `specify workflow step search` and `info`, but+`specify workflow step add <id>` will not install executable code from that+source. After reviewing the source, install the submitted versioned archive+directly with `--from`, or use a separately configured step catalog that you+explicitly allow for installation.++## Package Contract++One installed package provides one workflow step type:++```text+my-step/+βββ step.yml+βββ __init__.py+βββ helpers.py # optional; every catalog-downloaded extra file is declared+```++The package must satisfy the current installer and loader contract:++- `step.yml` and `__init__.py` are regular, non-symlink files at the package+ root. An archive may wrap the package in exactly one top-level directory.+- `step.type_key`, the catalog key/ID, and the matching+ `StepBase.type_key` are identical.+- The ID is one safe path component. The installer rejects separators, leading+ dots, trailing dots or spaces, reserved names, control characters, and+ Windows-invalid filename characters.+- `__init__.py` defines a `StepBase` subclass matching that single type key.+ Additional classes do not make the package provide additional registered+ step types.+- Extra-file paths use forward slashes, are relative and non-empty, contain no+ empty, `.` or `..` segments, and do not case-insensitively alias `step.yml`+ or `__init__.py`.+- The package stays within the current installer limits: 512 retained entries,+ 32 directory levels, and 50 MiB of retained content.+- `.git`, `__pycache__`, and `.DS_Store` are excluded from installation.++See [Custom step packages](../reference/workflows.md#custom-step-packages) for+the complete install, validation, and runtime behavior.++## Submission Contract++The issue form separates fields consumed by the current package/catalog code+from provenance and disclosure fields used during manual review.++| Submission data | Current contract |+| --- | --- |+| Step type ID | Catalog key, `step.type_key`, and matching `StepBase.type_key` |+| Name, version, description, author | `step.yml` metadata and catalog/installed registry metadata |+| Download URL | Versioned release archive used to test the supported direct-URL installation path |+| `step.yml`, `__init__.py`, and extra-file URLs | Exact HTTPS file URLs consumed when installing from an explicitly install-allowed catalog; extra-file keys follow the package-relative path restrictions above |+| Per-file SHA-256 mapping | Catalog `sha256`; keys must be exactly the files the installer downloads |+| Provided type name/count | Loader invariant: one matching type key per installed package |+| Repository, license, documentation, changelog | Source provenance and manual-review evidence; these are not `step.yml` fields |+| Spec Kit compatibility | Required intake disclosure; the step catalog accepts a `requires` mapping but does not yet define or enforce a Spec Kit compatibility schema |+| Runtime and tool dependencies | Required intake disclosure; the CLI does not resolve or install dependencies for custom steps |++Use a versioned release URL for the archive, consistent with the other+community submission forms. Use version-pinned URLs for every catalog file; the+required per-file SHA-256 mapping detects changed bytes even if a referenced+tag is later moved. Do not submit branch URLs, `releases/latest` URLs, or other+floating targets. Exact-release installation from an install-allowed catalog+requires a valid release version and a 64-character hexadecimal SHA-256 digest+for `step.yml`, `__init__.py`, and every `extra_files` path.++The direct `--from` archive installer does not currently accept or verify an+archive digest. The submitted Download URL and Testing Details fields provide+versioned-release and installation-test evidence, not an immutable content+guarantee; the per-file digests protect the separate catalog-installation path.++## Prepare a Submission++1. Create a public source repository with the complete package, license,+ documentation, and changelog where applicable.+2. Test valid and invalid configuration, `StepStatus`, outputs, errors, and any+ relevant resume, nested-step, or concurrent execution behavior.+3. Publish a versioned release archive (`.zip`, `.tar.gz`, or `.tgz`) and test+ it:++ ```bash+ specify workflow step add my-step \+ --from https://github.com/your-org/my-step/releases/download/v1.0.0/my-step-1.0.0.zip+ ```++4. Publish tag-pinned HTTPS URLs for `step.yml`, `__init__.py`, and every extra+ package file. Compute the SHA-256 digest of each downloaded file.+5. File the canonical submission issue with the exact release metadata and+ test evidence.++## Current Review Scope++Maintainers currently check the form manually for:++- complete identity, release, repository, license, and documentation metadata;+- consistency between the package ID, manifest type key, provided class, and+ version;+- versioned release and catalog file URLs;+- complete per-file checksum and extra-file mappings;+- disclosed compatibility and runtime dependencies; and+- evidence that the released archive follows the supported package shape and+ installation path.++There is no workflow-step submission validator or draft-PR generator in this+phase. A future automation phase will need a canonical step catalog entry+schema, including defined compatibility and dependency shapes, before all+submission fields can be machine-validated rather than reviewed as text.diff --git a/docs/reference/workflows.md b/docs/reference/workflows.mdindex b99fbea42..9e524c1c8 100644--- a/docs/reference/workflows.md+++ b/docs/reference/workflows.md@@ -594,6 +594,9 @@ my-step/βββ helpers.py # optional nested modules and data files```+To prepare a public package for community catalog intake, see+[Community Workflow Step Types](../community/workflow-steps.md).+`step.yml` declares the step's identity. `step.type_key` must exactly match the`<step_id>` passed on the command line β the ID is never inferred from packagecontent:diff --git a/docs/toc.yml b/docs/toc.ymlindex 4889ceeb5..8761b8a49 100644--- a/docs/toc.yml+++ b/docs/toc.yml@@ -102,6 +102,8 @@href: community/presets.md- name: Bundleshref: community/bundles.md+ - name: Workflow Step Types+ href: community/workflow-steps.md- name: Walkthroughshref: community/walkthroughs.md- name: Friendsdiff --git a/tests/test_github_workflows.py b/tests/test_github_workflows.pyindex 59776b9c6..d6cf31729 100644--- a/tests/test_github_workflows.py+++ b/tests/test_github_workflows.py@@ -525,14 +525,154 @@ def test_bundle_submission_form_applies_only_automatic_intake_verdict():assert "bundle-submission" not in bundle_form["labels"]+def test_workflow_step_submission_form_applies_only_automatic_intake_verdict():+ forms_dir = REPO_ROOT / ".github" / "ISSUE_TEMPLATE"+ workflow_step_form = yaml.safe_load(+ (forms_dir / "workflow_step_submission.yml").read_text(encoding="utf-8")+ )++ assert workflow_step_form["labels"] == ["triage-must-have"]+ assert not {+ "enhancement",+ "needs-triage",+ "workflow-step-submission",+ "validation-passed",+ "validation-failed",+ } & set(workflow_step_form["labels"])+++def test_workflow_step_submission_form_has_valid_complete_field_contract():+ forms_dir = REPO_ROOT / ".github" / "ISSUE_TEMPLATE"+ workflow_step_form = yaml.safe_load(+ (forms_dir / "workflow_step_submission.yml").read_text(encoding="utf-8")+ )+ fields = [item for item in workflow_step_form["body"] if "id" in item]+ field_ids = [field["id"] for field in fields]++ assert len(field_ids) == len(set(field_ids))+ assert all(re.fullmatch(r"[A-Za-z0-9_-]+", field_id) for field_id in field_ids)+ assert set(field_ids) == {+ "step-id",+ "step-name",+ "version",+ "description",+ "author",+ "repository",+ "download-url",+ "step-yml-url",+ "init-url",+ "extra-files",+ "file-sha256",+ "license",+ "speckit-compatibility",+ "runtime-dependencies",+ "step-type-count",+ "step-types-provided",+ "documentation",+ "changelog",+ "testing-details",+ "attestations",+ "additional-context",+ "ai-disclosure",+ }+ required_ids = {+ "step-id",+ "step-name",+ "version",+ "description",+ "author",+ "repository",+ "download-url",+ "step-yml-url",+ "init-url",+ "extra-files",+ "file-sha256",+ "license",+ "speckit-compatibility",+ "runtime-dependencies",+ "step-type-count",+ "step-types-provided",+ "documentation",+ "testing-details",+ "ai-disclosure",+ }+ assert {+ field["id"]+ for field in fields+ if field.get("validations", {}).get("required") is True+ } == required_ids+ field_by_id = {field["id"]: field for field in fields}+ assert field_by_id["step-type-count"][+ "attributes"+ ]["options"] == ["1"]+ assert all(+ option["required"] is True+ for option in field_by_id["attestations"]["attributes"]["options"]+ )+ bundle_form = yaml.safe_load(+ (forms_dir / "bundle_submission.yml").read_text(encoding="utf-8")+ )+ bundle_fields = {+ item["id"]: item for item in bundle_form["body"] if "id" in item+ }+ assert field_by_id["download-url"]["attributes"]["label"] == (+ bundle_fields["download-url"]["attributes"]["label"]+ )+ download_description = field_by_id["download-url"]["attributes"]["description"]+ assert "versioned" in download_description+ assert "immutable" not in download_description+ assert "immutable" not in yaml.safe_dump(workflow_step_form).lower()+ extra_files_description = field_by_id["extra-files"]["attributes"]["description"]+ assert "forward slashes" in extra_files_description+ assert "relative and non-empty" in extra_files_description+ assert "no empty, `.` or `..` segments" in extra_files_description+ assert "case-insensitively alias `step.yml` or `__init__.py`" in (+ extra_files_description+ )+ feature_form = yaml.safe_load(+ (forms_dir / "feature_request.yml").read_text(encoding="utf-8")+ )+ feature_fields = {+ item["id"]: item for item in feature_form["body"] if "id" in item+ }+ assert field_by_id["ai-disclosure"] == feature_fields["ai-disclosure"]+++def test_workflow_step_submission_form_documents_intake_only_phase():+ forms_dir = REPO_ROOT / ".github" / "ISSUE_TEMPLATE"+ workflow_step_form = yaml.safe_load(+ (forms_dir / "workflow_step_submission.yml").read_text(encoding="utf-8")+ )+ introduction = workflow_step_form["body"][0]["attributes"]["value"]++ assert "This phase is intake-only" in introduction+ assert "no validation workflow or draft pull request is triggered" in introduction+ assert "update the community catalog through the normal reviewed pull request" in (+ introduction+ )++def test_other_issue_forms_do_not_apply_automatic_intake_verdict():forms_dir = REPO_ROOT / ".github" / "ISSUE_TEMPLATE"- for form_name in (+ automatic_intake_forms = {+ "bundle_submission.yml",+ "extension_submission.yml",+ "preset_submission.yml",+ "workflow_step_submission.yml",+ }+ other_forms = sorted(+ path+ for path in forms_dir.glob("*.yml")+ if path.name != "config.yml" and path.name not in automatic_intake_forms+ )++ assert [path.name for path in other_forms] == ["agent_request.yml","bug_report.yml","feature_request.yml",- ):- form = yaml.safe_load((forms_dir / form_name).read_text(encoding="utf-8"))+ ]+ for form_path in other_forms:+ form = yaml.safe_load(form_path.read_text(encoding="utf-8"))assert "triage-must-have" not in form["labels"]