Require preset-usage README with Spec Kit CLI syntax in preset submissions by mnriem · Pull Request #3104 · github/spec-kit

mnriem · 2026-06-22T22:35:25Z

Summary

Addresses #3103. The community preset submission workflow previously validated only that a README.md exists at the repository root, which passes trivially for monorepos even when the linked documentation points at a product pitch rather than preset-usage docs.

This PR tightens the workflow and docs to validate the README that documentation actually points to, and requires a valid Spec Kit CLI install command.

Changes

.github/workflows/add-community-preset.md — parse the documentation field; new validation step 2d fetches the linked README (converting blob → raw) and:
- fails the submission unless it contains a valid specify preset add ... invocation (preferring --from <download-url> with an exact URL match),
- flags monorepo submissions whose documentation points at a generic root README and recommends the preset-scoped one.
  Renumbered subsequent checks and recompiled add-community-preset.lock.yml (only the body hash changed).
.github/ISSUE_TEMPLATE/preset_submission.yml — required Documentation URL field + a new Submission Requirements checkbox.
presets/PUBLISHING.md — a 'Usage README Requirements' section, updated prerequisites/checklist, and a reviewer note about the residual human content check.

Acceptance criteria

Workflow validates the README referenced by documentation, not just root presence
Workflow fails/flags submissions whose linked README lacks a valid specify preset ... invocation
presets/PUBLISHING.md updated to document the stricter requirement
Reviewer guidance notes the residual human content check

Closes #3103

🤖 Authored autonomously by GitHub Copilot (model: Claude Opus 4.8) on behalf of @mnriem.

Tighten the community preset submission workflow so it validates the README referenced by the documentation field rather than merely checking for a root README. The workflow now fails submissions whose linked README lacks a valid 'specify preset add ...' command and flags monorepo submissions that point documentation at a generic root README. - Add a required Documentation URL field to the preset issue template - Add validation step 2d (documentation README + CLI-syntax check) to .github/workflows/add-community-preset.md and recompile the lock file - Document the stricter usage-README requirement and reviewer content check in presets/PUBLISHING.md Closes github#3103 Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

This PR hardens the community preset submission workflow by requiring submitters to provide a Documentation URL that points to the actual preset-usage README, and by documenting/enforcing that the linked README contains valid Spec Kit CLI install syntax (e.g., specify preset add ...). This addresses monorepo submissions that previously passed validation by linking to a generic repo-root README that wasn’t preset usage documentation.

Changes:

Updated the add-community-preset workflow spec to validate the README at the submitted documentation URL and require a specify preset add ... invocation (preferring --from <download-url>).
Extended the preset submission issue form to collect a required Documentation URL and add a submission requirement checkbox.
Updated presets/PUBLISHING.md with explicit “Usage README Requirements” and reviewer guidance for the residual content judgment.

Show a summary per file

File	Description
`presets/PUBLISHING.md`	Documents the new requirement for preset-scoped usage READMEs and Spec Kit CLI install syntax; adds reviewer note about remaining human judgment.
`.github/workflows/add-community-preset.md`	Updates the workflow spec to validate the README referenced by `documentation` and require `specify preset add ...` usage.
`.github/workflows/add-community-preset.lock.yml`	Regenerated lockfile reflecting the workflow spec body change (hash update).
`.github/ISSUE_TEMPLATE/preset_submission.yml`	Adds a required `documentation` field and a checkbox reinforcing the linked-README + CLI-syntax requirement.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 4/4 changed files
Comments generated: 3

Address PR review feedback on github#3104: - PUBLISHING.md: clarify that only README resolution + a valid 'specify preset add ...' command are mechanically enforced; the preset-scoped-README and minimum-structure items are reviewer expectations, not automated checks. - PUBLISHING.md: state that a missing 'specify preset add ...' command is a hard validation failure (check 2d), not just 'flagged for changes'. - preset_submission.yml: require 'specify preset add ...' (not the looser 'specify preset ...') to match the workflow validation. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

mnriem · 2026-06-23T11:46:53Z

Addressed the review feedback in e0ab77f:

presets/PUBLISHING.md (intro) — reworded so it's clear the workflow only mechanically enforces (a) the linked README resolving and (b) it containing a valid specify preset add ... command. The preset-scoped-README preference and minimum-structure items are now framed as reviewer expectations, and the enforced bullet is marked (enforced).
presets/PUBLISHING.md (closing line) — changed 'flagged for changes' to a hard fails validation (workflow check 2d) to match the workflow's actual behavior.
.github/ISSUE_TEMPLATE/preset_submission.yml — tightened the Documentation URL guidance from the looser specify preset ... to the exact specify preset add ... syntax the automation looks for (with the --from <download-url> form called out).

No change to the workflow .md, so the lockfile is unchanged.

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8, autonomous).

Copilot

Copilot's findings

Files reviewed: 4/4 changed files
Comments generated: 4

Address PR review feedback on github#3104: - Workflow Step 2c: drop the generic repo-root README.md check so the README requirement is enforced exactly once, in Step 2d, against the file the documentation field points to (avoids monorepo false-positive). - Workflow Step 2d: restrict the documentation URL to GitHub-hosted README URLs (github.com/.../blob/... or raw.githubusercontent.com/...) before fetching user-provided input. - PUBLISHING.md: add the required 'id' field to the example catalog entry. - preset_submission.yml: fix the Documentation URL placeholder to match the recommended monorepo presets/<id>/README.md pattern. - Recompile add-community-preset.lock.yml (body hash only). Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

mnriem · 2026-06-23T12:35:13Z

Addressed the review feedback in da15c18:

Workflow Step 2c — removed the generic repo-root README.md check so the README requirement is enforced exactly once, in Step 2d, against the file documentation points to. Added a note explaining why (avoids the monorepo false-positive). Recompiled the lockfile (body hash only).
Workflow Step 2d — added an explicit rule to restrict documentation to GitHub-hosted README URLs (github.com/.../blob/... or raw.githubusercontent.com/...) and fail before fetching anything else, since the value is user-provided input.
presets/PUBLISHING.md — added the required id field to the example catalog entry so the snippet matches real entries.
.github/ISSUE_TEMPLATE/preset_submission.yml — fixed the Documentation URL placeholder to the recommended presets/<id>/README.md monorepo pattern.

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8, autonomous).

Copilot

Copilot's findings

Files reviewed: 4/4 changed files
Comments generated: 4

+- **Include a valid Spec Kit CLI install command** *(enforced)*. The linked README must
+  contain at least one `specify preset add ...` invocation. Preferably use the
+  catalog-install form whose URL matches your Download URL:
+
+  ```bash
+  specify preset add --from https://github.com/<org>/<repo>/releases/download/vX.Y.Z/<id>-X.Y.Z.zip
+  ```


+- **Restrict the URL to GitHub before fetching.** The `documentation` value is
+  user-provided input. Only accept GitHub-hosted README URLs — `https://github.com/<owner>/<repo>/blob/<ref>/<path>`
+  or `https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>`. If the URL points
+  anywhere else (or isn't a URL), **fail this check** and do not fetch it.
+- Fetch the **exact URL** in the `documentation` field (convert GitHub `blob` URLs to
+  their `raw.githubusercontent.com` equivalent before fetching) and confirm it resolves
+  to a readable Markdown file.


+- **Validate that the README contains a valid Spec Kit CLI install command.** The fetched
+  README must contain at least one `specify preset add ...` invocation. The strongest
+  signal is the catalog-install form whose URL matches the submitted **Download URL**:
+  - `specify preset add --from <download-url>` (preferred — the URL must match exactly), or
+  - `specify preset add <preset-id>`, or
+  - `specify preset add --dev <path>`
+
+  If **no** `specify preset add ...` command is present, the README is treated as a generic
+  description/pitch rather than preset-usage documentation — **fail this check** and tell the
+  submitter to add a valid install command (ideally `specify preset add --from <download-url>`).


        - label: Valid `preset.yml` manifest included
          required: true
        - label: README.md with description and usage instructions
          required: true
+        - label: Linked README explains how to use this preset and includes a valid `specify preset add ...` command matching the download URL
+          required: true


Address PR review feedback on github#3104: - Workflow Step 2d: broaden the documentation URL allowlist to also accept github.com/.../raw/... URLs; strip any fragment/query before fetching so the target is deterministic; clarify that a 'specify preset add --from <url>' command only counts when its URL matches the submitted Download URL (a different --from URL does not satisfy the requirement, though other accepted forms still can). - PUBLISHING.md: show both accepted download URL shapes (tag archive and release asset) in the README install example instead of implying only the releases/download form. - preset_submission.yml: remove the ambiguous generic 'README.md with description and usage instructions' checkbox; the linked-README requirement is the single source of truth. - Recompile add-community-preset.lock.yml (body hash only). Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

mnriem · 2026-06-23T13:26:59Z

Addressed the review feedback in 843d700:

Workflow Step 2d (URL allowlist) — added github.com/.../raw/... as an accepted GitHub-hosted form, and now strip any #fragment/?query before converting to raw so the fetch target is deterministic.
Workflow Step 2d (--from matching) — clarified that a specify preset add --from <url> command only counts when its URL matches the submitted Download URL exactly; a --from pointing at a different URL is treated as absent, though the README can still pass on specify preset add <id> or --dev <path>.
presets/PUBLISHING.md — the README install example now shows both accepted Download URL shapes (tag archive and release asset) rather than implying only the releases/download/... form.
.github/ISSUE_TEMPLATE/preset_submission.yml — removed the ambiguous generic 'README.md with description and usage instructions' checkbox so the linked-README requirement is the single source of truth.

Lockfile recompiled (body hash only).

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8, autonomous).

Copilot AI review requested due to automatic review settings June 22, 2026 22:35

Copilot started reviewing on behalf of mnriem June 22, 2026 22:35 View session

Copilot AI reviewed Jun 22, 2026

View reviewed changes

Comment thread presets/PUBLISHING.md Outdated

Comment thread presets/PUBLISHING.md Outdated

Comment thread .github/ISSUE_TEMPLATE/preset_submission.yml Outdated

mnriem requested a review from Copilot June 23, 2026 11:48

Copilot started reviewing on behalf of mnriem June 23, 2026 11:49 View session

Copilot AI reviewed Jun 23, 2026

View reviewed changes

Comment thread .github/workflows/add-community-preset.md

Comment thread .github/workflows/add-community-preset.md Outdated

Comment thread presets/PUBLISHING.md

Comment thread .github/ISSUE_TEMPLATE/preset_submission.yml

mnriem requested a review from Copilot June 23, 2026 12:35

Copilot started reviewing on behalf of mnriem June 23, 2026 12:36 View session

Copilot AI reviewed Jun 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Require preset-usage README with Spec Kit CLI syntax in preset submissions#3104

Require preset-usage README with Spec Kit CLI syntax in preset submissions#3104
mnriem wants to merge 4 commits into
github:mainfrom
mnriem:mnriem-feat-3103-preset-usage-readme

mnriem commented Jun 22, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem commented Jun 23, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem commented Jun 23, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

mnriem commented Jun 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

mnriem commented Jun 22, 2026

Summary

Changes

Acceptance criteria

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem commented Jun 23, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem commented Jun 23, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

mnriem commented Jun 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants