Move catalog source to main; generate downstream#2
Merged
Conversation
Seed 38 pattern files into patterns/ and categories.yml at the repo root, checked out verbatim from gh-pages (_patterns/ and _data/categories.yml). This is the first step of inverting the source-of-truth: main now holds the canonical catalog from which the plugin snapshot and site outputs will be generated downstream.
Add package.json with js-yaml devDependency for the upcoming build script (scripts/build.mjs) that will generate the plugin snapshot, llms.txt, and patterns.json from patterns/ + categories.yml. Add package-lock.json from npm install. Extend existing .gitignore with build/ to cover the output directory.
Adds the design spec and step-by-step implementation plan for inverting the catalog source-of-truth: patterns become canonical on main and the plugin snapshot, llms.txt, and patterns.json are generated downstream (with a byte-parity gate and related[] enrichment). Also captures the earlier skill-patterns-site planning docs that were never committed.
Adds scripts/build.mjs, the single generator that turns patterns/*.md + categories.yml into the three published outputs: the plugin snapshot (skills/skill-patterns/references/patterns.md), build/llms.txt, and build/patterns.json. It is a faithful byte-for-byte port of the former Jekyll Liquid templates (verified by empty diffs against captured goldens), plus one intentional addition: a related[] field surfaced in llms.txt (- Related: lines) and patterns.json (related key). The plugin snapshot now includes related[]. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add defense-in-depth input validation that throws before any output is
written, with actionable ${p._base}.md / categories.yml messages. All
checks are no-ops on today's catalog (parity gate still passes
byte-for-byte; snapshot unchanged):
- duplicate slug: detect two patterns sharing a slug (a Map silently
swallowed the collision); name the slug and both files
- filename/slug divergence: assert p.slug === p._base, since URLs use the
filename and related-lookups use the slug — they must agree
- related entry shape: require a non-empty string slug and note before the
existing unknown-slug check
- adds must be a list: reject a non-array adds up front instead of an
opaque .join stack trace
- category order: require a numeric order to guard the category sort
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
On pull_request, rebuild and fail if the committed snapshot (skills/skill-patterns/references/patterns.md) is stale. On push to main, regenerate llms.txt/patterns.json and sync them plus patterns/ and categories.yml into the gh-pages branch so the site rebuilds. Public repo, so Actions minutes are free.
Replace the 'update BOTH branches' guidance with the inverted flow: patterns are canonical on main, npm run build regenerates the snapshot, and the Sync catalog workflow generates and pushes the site's catalog files to gh-pages. Document the build's input validation and fix the SKILL.md note about how the snapshot is generated.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Inverts the catalog source-of-truth:
patterns/*.md+categories.ymlbecome canonical on main, and the plugin snapshot,llms.txt, andpatterns.jsonare generated byscripts/build.mjs. A newSync catalogworkflow verifies snapshot freshness on PRs and, on push to main, syncs generated files togh-pages.Contributors now edit one markdown file on the default branch and open one PR — no Jekyll, no second branch.
Verified locally: byte-identical parity with today's published output (faithful port), with
related[]added as the only intentional change; build-time input validation; and a full Jekyll sync rehearsal that built all 38 pattern pages from the static generated files.Spec + plan:
docs/superpowers/specs/2026-05-27-catalog-source-on-main-design.md,docs/superpowers/plans/2026-05-27-catalog-source-on-main.md.