Skip to content

feat(speckit-ext): file catalog updates as an issue, not a PR - #587

Merged
alfredoperez merged 3 commits into
mainfrom
feat/catalog-submission-skill
Aug 25, 2026
Merged

alfredoperez merged 3 commits into
mainfrom
feat/catalog-submission-skill

Conversation

@alfredoperez

Copy link
Copy Markdown
Owner

Summary

Our release docs told us to update the spec-kit community catalog by opening a PR against extensions/catalog.community.json. The upstream publishing guide forbids exactly that — "Do not open a pull request directly to edit extensions/catalog.community.json" — and github/spec-kit#3937 was closed unmerged: "Updates to extensions must use the extension submission issue template."

So the catalog entry is still pinned at 0.11.0 while we ship 0.20.2, and following our own docs is what wasted the round trip. This corrects the docs and adds the tool that does it properly.

The interesting part: heading drift

GitHub serializes an issue form as ### <label> / blank / value, and the maintainers' validation parses that. Filing with gh issue create --body-file means hand-building that markdown — so hardcoded headings that drift from the upstream template would silently break validation.

render_submission.py therefore fetches .github/ISSUE_TEMPLATE/extension_submission.yml from github/spec-kit at run time and renders from its live labels. If it can't fetch, it aborts rather than falling back to a remembered shape — that fallback is precisely the failure it exists to prevent.

Verified against our own accepted submission #2926: the rendered heading set is identical, including the (optional) suffixes (### Homepage (optional), ### Number of Hooks (optional)) that would be easy to guess wrong.

Other things the tool gets right

  • Merges onto the live catalog entry, never rebuilds it. The entry carries verified, downloads, stars, and created_at that exist nowhere in extension.yml; rebuilding drops them and reads as a destructive edit.
  • Passes no --label. We hold only pull on github/spec-kit, so gh issue create --label errors and nothing gets filed. Maintainers apply extension-submission at triage.
  • Version-pinned download URL, never companion-latest — the catalog requires declared version to equal downloaded bits.
  • category and description are explicit overrides, not silent defaults, because a reclassification or a copy change is editorial and shouldn't ride along with a version bump.
  • Stdlib only — PyYAML isn't installed and the repo's own loader chokes on the template's | block scalars, so it carries a small purpose-built parser.

Manifest tags re-synced

They were spec-driven-development, tracking, companion — one of them the extension's own name, none covering living specs, drift, or the composable command model added since. Now vscode, progress, living-specs, drift, hooks.

Chosen against all 155 catalog entries: living-specs has 0 other users so we coin and own it, while drift has 5 and carries the actual search traffic for "my specs went stale". Dropped status/resume (near-duplicates of progress, and 2 others already rank for resume) and the vague configurable/extensible. The catalog had separately drifted to a different set of six — the two now come from one place.

Quality checklist

  • Verified end to end — rendered body diffed heading-for-heading against #2926; 0 template drift; 0 unticked required checkboxes; 0 companion-latest occurrences; verified/downloads/stars/created_at all preserved
  • Suites green — 554 python tests pass with the manifest change
  • Docs corrected — publish-speckit-ext.md step 10-11 and publishing.md steps 9-10; the stale paste block (pinned at 0.11.0, >=0.8.5, 6 commands, and a companion-latest URL contradicting the pinning rule) is replaced with a pointer, since a paste-ready copy only rots
  • README count fixed — prose said "Seventeen commands… Thirteen are yours to run" while its own tables list 18
  • Changelog — speckit-extension/CHANGELOG.md under ## [Unreleased]
  • No version bump — release flow owns it
  • No pinned URL committed to repo source; the issue body is generated to a scratch dir

Gaps / how to verify

python3 .claude/skills/submit-catalog-update/render_submission.py --version 0.20.2 --print-labels

should list all 23 fields with ids, types, and live labels.

The upstream submission issue for 0.20.2 is not filed by this PR — it's a separate outward action, held for explicit approval.

Two things deliberately left alone: by-name install stays unavailable (the community catalog is discovery-only, independent of this), and extension.yml's per-command descriptions for specify/plan/tasks are stale relative to behavior — real, but a separate cleanup that doesn't affect the form.

🤖 Generated with Claude Code

Our docs told us to update the community catalog with a PR against
extensions/catalog.community.json. The upstream guide forbids exactly
that, and github/spec-kit#3937 was closed unmerged with "Updates to
extensions must use the extension submission issue template." Both first
listings and version updates go through the same submission issue.

Adds /submit-catalog-update, which renders the issue body from the LIVE
upstream issue-form template rather than hardcoded headings — a heading
that drifts from theirs breaks the maintainers' validation, and that is
the whole failure this guards. Verified its rendered heading set is
identical to our accepted submission #2926, including the "(optional)"
suffixes. It merges onto the live catalog entry instead of rebuilding it,
so verified/downloads/stars/created_at survive; keeps the version-pinned
download URL; and passes no --label, since we hold only pull upstream and
--label would fail the create outright.

Also re-syncs the manifest tags. They were spec-driven-development,
tracking, companion — one of them the extension's own name, none covering
living specs, drift, or the composable command model. The catalog had
separately drifted to a different set of six, so the two now come from one
place.

Corrects the docs that produced the rejected PR, and the README's command
count (its own tables list 18, the prose said seventeen).
@alfredoperez
alfredoperez merged commit 0c57b4d into main Aug 25, 2026
3 checks passed
@alfredoperez
alfredoperez deleted the feat/catalog-submission-skill branch September 4, 2026 19:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant