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

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).

…eset-usage-readme

mnriem · 2026-06-24T20:43:38Z

The failing test_issue_template_agent_lists_match_runtime_integrations (missing firebender) was unrelated to this PR — the branch was 32 commits behind main, so CI ran against a state where firebender existed in AGENT_CONFIG but hadn't yet been added to the issue-template agent lists. That was fixed on main since.

Merged the latest upstream/main into the branch (276ddf5, clean — no conflicts). The previously-failing test and the preset suite now pass locally. No changes to the preset-README work itself.

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: 3

Address PR review feedback on github#3104: the previous 'matching the download URL' wording overstated the requirement. Only the 'specify preset add --from <url>' form needs an exact download-URL match; other accepted forms ('specify preset add <id>' / '--dev <path>') don't reference the download URL at all. - preset_submission.yml: reword the Documentation URL description and the Submission Requirements checkbox to reflect what's enforced vs preferred. - PUBLISHING.md: clarify the reviewer note so the exact-match rule is scoped to the --from form. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

mnriem · 2026-06-24T20:47:31Z

Addressed the review feedback in 5dcea60. All three comments were about the same over-strict 'matching the download URL' wording — only the --from <url> form needs an exact download-URL match; specify preset add <id> and --dev <path> are also accepted and don't reference the download URL:

.github/ISSUE_TEMPLATE/preset_submission.yml — reworded the Documentation URL field description and the Submission Requirements checkbox to say a valid specify preset add ... command is required, with --from <download-url> (exact match) as the preferred form and the other forms noted as accepted.
presets/PUBLISHING.md — scoped the reviewer note's exact-match statement specifically to the --from form.

No workflow .md change, 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: 2

Address PR review feedback on github#3104: - Workflow Step 2d: add an explicit check that the documentation URL path ends with README.md (case-insensitive) after stripping fragment/query, so a non-README markdown file is rejected before fetching. - PUBLISHING.md: reword the release-ZIP note, which conflicted with the earlier preset structure guidance. The real requirement is that the README is reachable at the documentation URL before download; it's fine for the same file to also ship inside the release ZIP. - 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-24T20:53:00Z

Addressed the review feedback in b51fc37:

Workflow Step 2d — added an explicit requirement that the documentation URL path ends with README.md (case-insensitive, after stripping fragment/query), so a non-README markdown file is rejected before fetching.
presets/PUBLISHING.md — reworded the release-ZIP note that conflicted with the earlier preset-structure guidance. The real requirement is that the README is reachable at the documentation URL before download; it's fine for the same file to also ship inside the release ZIP.

Lockfile recompiled (body hash only).

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: 2

Address PR review feedback on github#3104: drop the '6.' prefix from the 'Usage README Requirements' heading so its GitHub anchor isn't tied to a section number (brittle under renumbering, and avoids confusion with the top-level 'Best Practices' TOC item). Update the Prerequisites cross-link to the new #usage-readme-requirements anchor. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

mnriem · 2026-06-24T21:03:06Z

Addressed the review feedback in 8ea0f9a. Both comments were about the numbered ### 6. Usage README Requirements heading:

Renamed the heading to an unnumbered Usage README Requirements so its GitHub anchor (#usage-readme-requirements) is stable under renumbering and doesn't collide conceptually with the top-level 'Best Practices' TOC item.
Updated the Prerequisites cross-link to the new anchor.

Docs-only change; no workflow/lockfile impact.

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: - PUBLISHING.md: the 'mechanically enforces' summary now lists all Step 2d checks (GitHub-hosted URL, path ends with README.md, resolves, contains a valid 'specify preset add ...' command), instead of only two. - PUBLISHING.md: reword the PR checklist item so a usage README + install command is the requirement, with preset-scoped README recommended for monorepos (matches the workflow's flag-not-fail behavior). - preset_submission.yml: include the full 'specify preset add' prefix on the --dev and --from forms in the field description and checklist so submitters copy the exact syntax. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

mnriem · 2026-06-24T21:32:45Z

Addressed the review feedback in 3b4923d:

presets/PUBLISHING.md (intro) — the 'mechanically enforces' summary now lists all Step 2d checks (GitHub-hosted URL, path ends with README.md, resolves to a readable file, contains a valid specify preset add ... command) instead of only two.
presets/PUBLISHING.md (PR checklist) — reworded so a usage README + install command is the requirement, with a preset-scoped README recommended for monorepos — matching the workflow's flag-not-fail behavior.
.github/ISSUE_TEMPLATE/preset_submission.yml — added the full specify preset add prefix to the --dev and --from forms in both the field description and the checklist so submitters copy the exact syntax.

Docs/template-only; no workflow .md or lockfile change.

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: 1

Address PR review feedback on github#3104: remove the incorrect colon after 'the linked README' so the sentence reads naturally. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

mnriem · 2026-06-24T21:40:38Z

Fixed the grammar nit in 61db1eb — removed the stray colon so it reads '...enforces that the linked README is a GitHub-hosted URL...'.

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: 1

Address PR review feedback on github#3104: rewriting documentation URLs into the raw.githubusercontent.com/<owner>/<repo>/<ref>/<path> form can't reliably represent refs that contain slashes (e.g. a feature/foo branch). Step 2d now fetches github.com blob URLs by swapping only /blob/ -> /raw/, and fetches github.com/.../raw/... and raw.githubusercontent.com/... URLs as-is, instead of reconstructing the raw host form. 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-24T21:53:57Z

Addressed the review feedback in 696dcc0. Good catch on the lossy ref rewrite — reconstructing raw.githubusercontent.com/<owner>/<repo>/<ref>/<path> can't disambiguate refs containing slashes (e.g. a feature/foo branch).

Step 2d now resolves the raw content without that rewrite:

github.com/.../blob/... → fetch the same URL with only /blob/ swapped to /raw/.
github.com/.../raw/... and raw.githubusercontent.com/... are fetched as-is.

Lockfile recompiled (body hash only).

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: 0 new

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

Comment thread presets/PUBLISHING.md

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

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

Comment thread .github/ISSUE_TEMPLATE/preset_submission.yml

Merge remote-tracking branch 'upstream/main' into mnriem-feat-3103-pr…

276ddf5

…eset-usage-readme

Copilot AI review requested due to automatic review settings June 24, 2026 20:43

Copilot started reviewing on behalf of mnriem June 24, 2026 20:43 View session

Copilot AI reviewed Jun 24, 2026

View reviewed changes

Comment thread .github/ISSUE_TEMPLATE/preset_submission.yml

Comment thread .github/ISSUE_TEMPLATE/preset_submission.yml Outdated

Comment thread presets/PUBLISHING.md Outdated

mnriem requested a review from Copilot June 24, 2026 20:48

Copilot started reviewing on behalf of mnriem June 24, 2026 20:49 View session

Copilot AI reviewed Jun 24, 2026

View reviewed changes

Comment thread presets/PUBLISHING.md Outdated

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

mnriem requested a review from Copilot June 24, 2026 20:55

Copilot started reviewing on behalf of mnriem June 24, 2026 20:56 View session

Copilot AI reviewed Jun 24, 2026

View reviewed changes

Comment thread presets/PUBLISHING.md Outdated

Comment thread presets/PUBLISHING.md Outdated

mnriem requested a review from Copilot June 24, 2026 21:14

Copilot started reviewing on behalf of mnriem June 24, 2026 21:14 View session

Copilot AI reviewed Jun 24, 2026

View reviewed changes

Comment thread presets/PUBLISHING.md Outdated

Comment thread presets/PUBLISHING.md

Comment thread .github/ISSUE_TEMPLATE/preset_submission.yml Outdated

Comment thread .github/ISSUE_TEMPLATE/preset_submission.yml Outdated

mnriem requested a review from Copilot June 24, 2026 21:33

Copilot started reviewing on behalf of mnriem June 24, 2026 21:33 View session

Copilot AI reviewed Jun 24, 2026

View reviewed changes

Comment thread presets/PUBLISHING.md Outdated

mnriem requested a review from Copilot June 24, 2026 21:42

Copilot started reviewing on behalf of mnriem June 24, 2026 21:42 View session

Copilot AI reviewed Jun 24, 2026

View reviewed changes

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

mnriem requested a review from Copilot June 24, 2026 21:58

Copilot started reviewing on behalf of mnriem June 24, 2026 21:58 View session

Copilot AI reviewed Jun 24, 2026

View reviewed changes

mnriem merged commit 96039d3 into github:main Jun 24, 2026
12 checks passed

mnriem deleted the mnriem-feat-3103-preset-usage-readme branch June 24, 2026 22:06

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem commented Jun 23, 2026

Uh oh!

mnriem commented Jun 24, 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!

mnriem commented Jun 24, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

mnriem commented Jun 24, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

mnriem commented Jun 24, 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 24, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

mnriem commented Jun 24, 2026