From 3758a9182e2bf6c173c7df6636c96cb2f508a55d Mon Sep 17 00:00:00 2001 From: Alex Smith Date: Thu, 13 Aug 2026 08:50:43 -0400 Subject: [PATCH 1/3] docs: settle the bestax-migrate bundling call, create-bestax ships it (#385) Direction (B) from #385: the skill stays in the create-bestax bundle. Drop the two remaining not-bundled statements (skills intro, migrate page), replace the contested note in bestax-migrate/CLAUDE.md with the settled policy, and cite the decision from create-bestax/CLAUDE.md's per-skill rule. No behavior changes; sync-skills.mjs and setupSkills() are untouched, and pnpm gen produced no diff. --- bestax-migrate/CLAUDE.md | 11 ++++++----- create-bestax/CLAUDE.md | 6 +++--- docs/docs/skills/intro.md | 3 +-- docs/docs/skills/migrate.mdx | 4 ++-- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/bestax-migrate/CLAUDE.md b/bestax-migrate/CLAUDE.md index 11b615275..b84d1b153 100644 --- a/bestax-migrate/CLAUDE.md +++ b/bestax-migrate/CLAUDE.md @@ -75,8 +75,9 @@ the component library), and `scripts/pack-manifest.mjs` resolves any remaining left in `devDependencies` only with the pack hooks present. It does **not** check which section `@allxsmith/bestax-bulma` sits in — re-adding it as a plain-semver runtime dependency passes CI, so that one is on review. The skill lives at repo-root -`skills/bestax-migrate/`. Whether it bundles into create-bestax is contested: the original -policy was existing-sites-only, but `sync-skills.mjs` has shipped it since #345 — see #385 -and don't change either side ahead of that call. When the mapping -gains or loses coverage, update `skills/bestax-migrate/references/` and the docs migration -guide in the same PR. +`skills/bestax-migrate/`. It **is** bundled into create-bestax (settled in #385): the +original existing-sites-only policy lost to one uniform bundle, and the skill sits idle +in a fresh scaffold until legacy imports show up. Keep `sync-skills.mjs`, the `CLAUDE_MD` +roster in `create-bestax/src/constants.ts`, and the docs skills pages in agreement. When +the mapping gains or loses coverage, update `skills/bestax-migrate/references/` and the +docs migration guide in the same PR. diff --git a/create-bestax/CLAUDE.md b/create-bestax/CLAUDE.md index 63990a60c..91f6a626f 100644 --- a/create-bestax/CLAUDE.md +++ b/create-bestax/CLAUDE.md @@ -22,9 +22,9 @@ path (`-y` + flags, no TTY) must never hang or regress (#192). package. An unlisted skill silently doesn't bundle; a delisted one silently vanishes (the script empties the destination first, and its success line reports the array length either way); no CI check compares the list against `skills/*`. Bundling is a per-skill policy - decision (see #385) — when adding a skill, decide it explicitly and keep the allowlist, - `skills/README.md`, `docs/docs/skills/intro.md`, and the `CLAUDE_MD` roster in - `src/constants.ts` in agreement. **Never edit the bundled copy** — change `skills/` at the + decision (bestax-migrate's was settled as bundled, #385) — when adding a skill, decide it + explicitly and keep the allowlist, `skills/README.md`, `docs/docs/skills/intro.md`, and + the `CLAUDE_MD` roster in `src/constants.ts` in agreement. **Never edit the bundled copy** — change `skills/` at the repo root; the build re-syncs. - The `CLAUDE_MD` template in `constants.ts` is what every generated app tells its AI agents. When library conventions, skills, or the canonical docs entrypoint change (#203), check diff --git a/docs/docs/skills/intro.md b/docs/docs/skills/intro.md index f1813d123..84019adc7 100644 --- a/docs/docs/skills/intro.md +++ b/docs/docs/skills/intro.md @@ -38,7 +38,6 @@ Then explore each skill — what it does, how to install it, and live examples: - **[Icons](./icons)** — use `Icon`/`IconText` with any of the five supported icon libraries: per-library setup, name formats, variants, and decorative-vs-labeled accessibility. - **[Migrate](./migrate)** — move an existing app off `react-bulma-components`: run the - `bestax-migrate` codemod, then resolve every `TODO(bestax-migrate)` it leaves. Not bundled by - `create-bestax` (it's for existing sites, not new ones). + `bestax-migrate` codemod, then resolve every `TODO(bestax-migrate)` it leaves. - **[Optimize](./optimize)** — reduce the built CSS size: measure raw+gzip, then the cheapest first-party lever that fits (lighter flavor, modular Sass build, import/asset hygiene). diff --git a/docs/docs/skills/migrate.mdx b/docs/docs/skills/migrate.mdx index 3e45c759b..874df52b4 100644 --- a/docs/docs/skills/migrate.mdx +++ b/docs/docs/skills/migrate.mdx @@ -13,8 +13,8 @@ skill teaches an agent to move an existing app from [`bestax-migrate` codemod](../guides/getting-started/migration/react-bulma-components.md) and then resolves everything the codemod flags. -Unlike the other skills, this one is **not** bundled by `create-bestax` — it's for existing sites, -not new ones. +Like the rest of the bundle, `create-bestax` preinstalls this skill; it stays idle until the +agent meets code that still imports `react-bulma-components`. ## Install From f3810b2e3a92d523034c8377fa1c38ad8730dbc8 Mon Sep 17 00:00:00 2001 From: Alex Smith Date: Thu, 13 Aug 2026 09:16:47 -0400 Subject: [PATCH 2/3] docs: point the bundling agreement roster at its canonical home The deep review flagged that this file's keep-in-agreement list and the one in create-bestax/CLAUDE.md enumerate different sets, which is how the original drift happened. One canonical list beats two copies: reference create-bestax/CLAUDE.md's sync rules instead of restating. --- bestax-migrate/CLAUDE.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/bestax-migrate/CLAUDE.md b/bestax-migrate/CLAUDE.md index b84d1b153..39496c0ea 100644 --- a/bestax-migrate/CLAUDE.md +++ b/bestax-migrate/CLAUDE.md @@ -77,7 +77,7 @@ check which section `@allxsmith/bestax-bulma` sits in — re-adding it as a plain-semver runtime dependency passes CI, so that one is on review. The skill lives at repo-root `skills/bestax-migrate/`. It **is** bundled into create-bestax (settled in #385): the original existing-sites-only policy lost to one uniform bundle, and the skill sits idle -in a fresh scaffold until legacy imports show up. Keep `sync-skills.mjs`, the `CLAUDE_MD` -roster in `create-bestax/src/constants.ts`, and the docs skills pages in agreement. When -the mapping gains or loses coverage, update `skills/bestax-migrate/references/` and the -docs migration guide in the same PR. +in a fresh scaffold until legacy imports show up. The canonical roster of surfaces that +must agree on bundling lives in `create-bestax/CLAUDE.md`'s sync rules — don't restate +it here. When the mapping gains or loses coverage, update +`skills/bestax-migrate/references/` and the docs migration guide in the same PR. From 3be3db5468367b952db9a32bd4d6b2470fb13a4c Mon Sep 17 00:00:00 2001 From: Alex Smith Date: Thu, 13 Aug 2026 09:22:14 -0400 Subject: [PATCH 3/3] docs: qualify the preinstall claim, widen the canonical bundling roster Two suppressed Copilot findings, both real. setupSkills() only runs when the user accepts the prompt or passes --skills, so migrate.mdx now says offers to preinstall, matching intro.md. And with bestax-migrate/CLAUDE.md delegating to the canonical roster, that roster now names per-skill docs pages that state bundling, so migrate.mdx sits inside the sync policy. --- create-bestax/CLAUDE.md | 5 +++-- docs/docs/skills/migrate.mdx | 4 ++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/create-bestax/CLAUDE.md b/create-bestax/CLAUDE.md index 91f6a626f..4b5a5fcfb 100644 --- a/create-bestax/CLAUDE.md +++ b/create-bestax/CLAUDE.md @@ -23,8 +23,9 @@ path (`-y` + flags, no TTY) must never hang or regress (#192). script empties the destination first, and its success line reports the array length either way); no CI check compares the list against `skills/*`. Bundling is a per-skill policy decision (bestax-migrate's was settled as bundled, #385) — when adding a skill, decide it - explicitly and keep the allowlist, `skills/README.md`, `docs/docs/skills/intro.md`, and - the `CLAUDE_MD` roster in `src/constants.ts` in agreement. **Never edit the bundled copy** — change `skills/` at the + explicitly and keep the allowlist, `skills/README.md`, `docs/docs/skills/intro.md`, any + per-skill docs page that states bundling (`docs/docs/skills/migrate.mdx` does), and the + `CLAUDE_MD` roster in `src/constants.ts` in agreement. **Never edit the bundled copy** — change `skills/` at the repo root; the build re-syncs. - The `CLAUDE_MD` template in `constants.ts` is what every generated app tells its AI agents. When library conventions, skills, or the canonical docs entrypoint change (#203), check diff --git a/docs/docs/skills/migrate.mdx b/docs/docs/skills/migrate.mdx index 874df52b4..0d8df17d9 100644 --- a/docs/docs/skills/migrate.mdx +++ b/docs/docs/skills/migrate.mdx @@ -13,8 +13,8 @@ skill teaches an agent to move an existing app from [`bestax-migrate` codemod](../guides/getting-started/migration/react-bulma-components.md) and then resolves everything the codemod flags. -Like the rest of the bundle, `create-bestax` preinstalls this skill; it stays idle until the -agent meets code that still imports `react-bulma-components`. +Like the rest of the bundle, `create-bestax` offers to preinstall this skill; it stays idle +until the agent meets code that still imports `react-bulma-components`. ## Install