@gallopsystems/agent-skills 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gallopsystems/agent-skills",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Gallop Systems Claude Code skills, symlinked into .claude/skills on install.",
   "license": "UNLICENSED",
   "repository": {

package/plugins/copier-template/skills/copier-template/SKILL.md

@@ -62,6 +62,20 @@ git ls-remote --tags --refs --sort=-v:refname <template-url> 'v*' | head -1
 
 If newer, it pushes a **static branch name** (e.g. `chore/template-update`) with an `--allow-empty` commit and opens a PR whose body contains the version delta, release-notes/compare links, and step-by-step instructions an agent can execute. Hard-won details to keep if reimplementing: an explicit `permissions: contents: write, pull-requests: write` block (default token can't open PRs), a static branch name (dated branches caused duplicate PRs), and comparing **tag versions, not commit SHAs**.
 
+## Branch Protection in Descendants
+
+A template **cannot** enable branch protection for the repos it generates — GitHub reads required status checks from repo config, never from committed workflow files. So every descendant starts with nothing gating merges until someone sets it once (after the first CI run, so the check is known). This template's CI exposes a **`ci-success`** summary job to be exactly that gate — require it on `main`:
+
+```bash
+echo '{"required_status_checks":{"strict":false,"contexts":["ci-success"]},"enforce_admins":false,"required_pull_request_reviews":null,"restrictions":null}' \
+  | gh api -X PUT repos/<owner>/<repo>/branches/main/protection --input -
+```
+
+- **Require the single `ci-success` context, not individual job names.** CI shards the test suite, so the per-leg check names embed the matrix size (`test (shard 1/4)`) and change as the project grows — protection pinned to them blocks every PR the moment the count shifts. `ci-success` is a summary job (`needs:` all gating jobs, `if: always()`, fails unless every `needs.*.result` is `success`); `needs.test.result` rolls the whole matrix into one value, so it stays correct at any shard count. If you add a template whose CI lacks such a job, create one rather than requiring the matrix legs directly.
+- **`coverage` is deliberately excluded** from `ci-success` so the report never blocks a merge — don't add it to the required contexts.
+- The PUT body must include `required_status_checks`, `enforce_admins`, `required_pull_request_reviews`, and `restrictions` (any may be `null`) or the call 422s. Needs admin on the repo.
+- A Conventional-Commits **PR-title check is only worth requiring on repos something actually reads the title** — i.e. a published package with release-please/changelog automation. A private app (no release tooling, `"private": true`, no version) gains nothing from it; don't gate on it there.
+
 ## Further Reading
 
 - **Template anatomy & testing changes**: [template-authoring.md](template-authoring.md)

package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vue-nuxt
-description: Author Vue 3 components inside a Nuxt 4 app. Covers Nuxt auto-import rules, component authoring (props/emits/withDefaults/generics), v-model/defineModel, slots, composables, reactivity, when watch is a code smell, page structure, display formatting, and Vue-shaped template idioms.
+description: Author Vue 3 components inside a Nuxt 4 app. Covers Nuxt auto-import rules, component authoring (props/emits/withDefaults/generics), v-model/defineModel, slots, composables, reactivity, when watch is a code smell, reaching for VueUse over hand-rolled effects, page structure, display formatting, and Vue-shaped template idioms.
 ---
 
 # Vue-in-Nuxt component authoring
@@ -23,6 +23,7 @@ cross-links to those rather than restating them.
 - Formatting display values (currency/date/number) consistently
 - Anything reactivity-shaped: `computed` vs `watch`, prop→state sync, DOM measurement
 - You see `watch` and want to know if it should be something else
+- About to hand-roll a `watch` + lifecycle teardown for a browser API (storage, timers, DOM, listeners, URL) — VueUse likely wraps it
 
 ## Reference Files
 
@@ -33,6 +34,7 @@ cross-links to those rather than restating them.
 - [composables.md](./composables.md) — `MaybeRefOrGetter`/`toValue` argument contract, return refs not `reactive()`, thin pure-core shell, `onScopeDispose`/`effectScope` cleanup
 - [reactivity.md](./reactivity.md) — `ref` over `reactive`, `useTemplateRef`, pure computeds, mutate-don't-reassign, DOM-measure + `ResizeObserver`, `shallowRef`, watch-getter prop sync, `:key` remount, listener cleanup
 - [watch.md](./watch.md) — **`watch` is the escape hatch, not the default**: when it's right, and the four smell shapes (with refactors) found auditing 159 real watchers
+- [vueuse.md](./vueuse.md) — reach for a VueUse composable before hand-rolling a `watch` + lifecycle teardown for an external-world effect (DOM, timers, storage, URL, listeners); the `@vueuse/nuxt` setup, the watch-sugar functions, and what to keep on Nuxt's own APIs
 - [template-idioms.md](./template-idioms.md) — duplicate-`@keyup` TS error, `:deep()`/`:slotted()`/`:global()`, click-outside marker class, `NuxtLink`/thin `app.vue`, `useHead`, `v-bind` shorthand, `useId`, `<Teleport>`/`<KeepAlive>`, `v-memo`/`v-once`, file-input reset
 - [page-structure.md](./page-structure.md) — keep pages thin: route-param parsing + layout in the page, data/logic/forms in components
 - [formatters.md](./formatters.md) — never inline a currency/date/number formatter; centralize in `useFormatters`, prefer Intl/date-fns
@@ -42,7 +44,7 @@ cross-links to those rather than restating them.
 1. **Lean on auto-imports.** `app/components`, `app/composables`, `app/utils`, and the Vue/Nuxt APIs all auto-import. Add an explicit `import` only for third-party symbols and TS types. A nested component's tag carries its directory as a prefix (`components/customers/ProfileCard.vue` → `<CustomersProfileCard>`).
 2. **Type props/emits, default the booleans.** Use the type-only macros (`defineProps<{...}>()`, `defineEmits<{...}>()`). A bare `boolean` prop coerces to `false` when absent (not `undefined`), so any "defaults-on" flag MUST be defaulted — via reactive destructure (`{ flag = true } = defineProps<…>()`, the 3.5 default, no factory needed for arrays/objects) or `withDefaults` (factory required for non-primitives).
 3. **`computed` for derivation, `watch` for escaping the graph.** If a watcher body just assigns one reactive value from others, it's a `computed`. Need to write a value back? A `computed` can have a setter — reach for a writable `computed` or `defineModel` before a sync watcher. Keep computed getters pure (no fetch, no mutation, no DOM).
-4. **Tie effects to lifecycle.** DOM measurement, listeners, observers, and timers go in `onMounted` and are torn down in `onUnmounted`. A computed reading live DOM geometry needs an explicit re-measure signal (DOM size isn't reactive).
+4. **Tie effects to lifecycle.** DOM measurement, listeners, observers, and timers go in `onMounted` and are torn down in `onUnmounted`. A computed reading live DOM geometry needs an explicit re-measure signal (DOM size isn't reactive). Before hand-rolling that effect-plus-teardown, check whether a **VueUse** composable already wraps it (`vueuse.md`) — they bundle the cleanup.
 5. **Call composables at the top of `<script setup>`** — never inside a callback or a template expression (both lose Nuxt's request scope). Derive display state with `computed`, guarding for possibly-null data.
 6. **Defer to the right skill.** Fetch/SSR/auth/middleware → `nuxt-nitro-api`. Volt components, `pt:` styling, color tokens, dark mode → `volt-primevue`. Don't duplicate them here.
 

package/plugins/vue-nuxt/skills/vue-nuxt/vueuse.md

@@ -0,0 +1,75 @@
+# VueUse — reach for a composable before hand-rolling an effect
+
+`watch.md` lists the cases where `watch` is legit: they're all effects that cross
+**out of** the reactive graph (DOM, timers, storage, URL, the network). For most
+of those, **VueUse already wraps the boundary** — and a VueUse composable bundles
+the *teardown* with the reactive effect, so it retires the manual-`onUnmounted`
+cleanup, not just the watch. Before you write a `watch` + `onMounted`/`onUnmounted`
+pair against a browser API, check whether a composable does it.
+
+> Not a replacement for the framework. Data fetching stays on
+> `useFetch`/`useAsyncData` (see `nuxt-nitro-api`); cookies use Nuxt's built-in
+> `useCookie`; derivation stays a `computed`. VueUse is for the *external-world*
+> effects — see the caveats at the bottom.
+
+## Setup in Nuxt
+
+Add the module; it auto-imports every `@vueuse/core` function, so they need no
+explicit `import` (same as Nuxt's own composables — see `auto-imports.md`):
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({ modules: ['@vueuse/nuxt'] })
+```
+
+The **`@vueuse/router`** and **`@vueuse/integrations`** add-ons are separate
+installs and are **not** auto-imported by the module — import them explicitly.
+
+## The boundary cases (mapped from `watch.md`)
+
+| You were about to `watch` for… | Reach for | Why it's better |
+|---|---|---|
+| `document.body.style.overflow` toggle | `useScrollLock(document.body)` | writable ref; restores the prior value on unmount |
+| `setInterval` polling | `useIntervalFn(fn, ms)` / `useTimeoutPoll` | **auto-clears on unmount** — no `clearInterval` to forget |
+| `setTimeout` | `useTimeoutFn(fn, ms)` | same auto-cleanup, with `start`/`stop` controls |
+| debounced auto-save | `useDebounceFn` / `refDebounced` | no manual timer ref + cleanup |
+| `localStorage`/`sessionStorage` write-back | `useLocalStorage(key, init)` / `useStorage` | a reactive ref mirrored to storage both ways — the write-back watch disappears |
+| `addEventListener` in `onMounted` | `useEventListener(target, evt, fn)` | auto-removes on unmount |
+| click-outside marker class | `onClickOutside(el, fn)` | replaces the hand-rolled document listener (cf. `template-idioms.md`) |
+| `ResizeObserver` re-measure | `useElementSize` / `useElementBounding` / `useResizeObserver` | reactive size, observer torn down for you (cf. `reactivity.md`) |
+| `matchMedia` listener | `useMediaQuery` / `usePreferredColorScheme` / `usePreferredDark` | reactive boolean, no listener bookkeeping |
+| clipboard write + "copied!" flag | `useClipboard()` → `{ copy, copied }` | `copied` auto-resets |
+
+URL sync (`router.replace({ query: { ...route.query, tab } })`) →
+`useRouteQuery('tab')` from `@vueuse/router` gives a ref bound two-way to the query
+param. Nuxt's own `useRoute()` is already reactive for *reads*; reach for
+`useRouteQuery` when you want a **writable** ref bound to a single param.
+
+## VueUse's `watch` sugar — when a `watch` IS warranted
+
+When the effect genuinely belongs in a watcher, VueUse's Watch category removes the
+boilerplate `watch.md` warns about:
+
+- **`watchDebounced(src, cb, { debounce: 300 })`** / **`watchThrottled`** — the
+  debounced-auto-save case without a `setTimeout` inside the callback.
+- **`whenever(source, cb)`** — fires only when `source` becomes truthy; the
+  "re-seed on dialog open" pattern (`watch(visible, v => { if (v) … })`) as one line.
+- **`until(source).toBe(x)`** — await a reactive condition instead of polling.
+- **`watchOnce`** — auto-stops after the first fire; no manual `stop()` handle.
+- **`watchIgnorable` / `watchPausable`** — suppress or pause a watcher around a
+  programmatic write (a cleaner answer than guard flags for the "re-fires on
+  programmatic reseed" trap in `watch.md`).
+
+`onWatcherCleanup` and `flush: 'post'` (in `watch.md`) still apply — these are sugar
+over the same watcher, not a different mechanism.
+
+## Caveats — don't over-reach
+
+- **Cookies:** use Nuxt's built-in **`useCookie`** (SSR-aware), not VueUse's
+  `@vueuse/integrations` `useCookies` (a `universal-cookie` wrapper).
+- **Fetching:** `useFetch`/`useAsyncData`/`$fetch` own the data layer
+  (`nuxt-nitro-api`). Skip VueUse's `useFetch`/`useAsyncState` in a Nuxt app.
+- **Head/title:** prefer Nuxt's `useHead`/`useSeoMeta` over `useTitle`/`useFavicon`.
+- **Derivation is still a `computed`.** VueUse doesn't change the core rule: if the
+  body just assigns one reactive value from others, it's a `computed`, not a
+  composable and not a watch.

package/plugins/vue-nuxt/skills/vue-nuxt/watch.md

@@ -74,6 +74,20 @@ Only when the effect crosses **out of** the reactive graph:
 - **Clone a server prop into a locally-editable draft** —
   `watch(() => props.record, (r) => { if (r) form.value = structuredClone(toRaw(r)) }, { immediate: true })`.
 
+> **Before hand-rolling the external-world cases, check VueUse.** Most of the
+> bullets above (DOM, timers, persist, URL) are exactly what VueUse wraps — and a
+> VueUse composable bundles the *teardown* with the reactive effect, so it
+> retires the manual-`onUnmounted` footgun, not just the watch:
+>
+> - **DOM / body scroll** — `useScrollLock(document.body)` over a watch toggling `document.body.style.overflow`.
+> - **Timers** — `useIntervalFn` / `useTimeoutFn` / `useTimeoutPoll` auto-clear on unmount (no manual `clearInterval`); `useDebounceFn` / `refDebounced` for debounce.
+> - **Persist** — `useLocalStorage` / `useStorage`: a reactive ref mirrored to storage, no write-back watch.
+> - **URL sync** — `useRouteQuery` (from `@vueuse/router`) for a ref bound to a query param.
+>
+> Nuxt caveats: cookies use the built-in `useCookie`, **not** VueUse's
+> `@vueuse/integrations` `useCookies`; data fetching stays on
+> `useFetch`/`useAsyncData`. Auto-import the rest via the `@vueuse/nuxt` module.
+
 ### Cancel stale work with `onWatcherCleanup`
 
 A watcher that starts async work (a keyed `$fetch`, a timer) must cancel the