@danieljvdm/dev-kit 0.14.0 → 0.16.0

package/skills/dev-kit/SKILL.md

@@ -1,24 +1,21 @@
 ---
 name: dev-kit
-description: Dev-kit operations for projects that configure dev-kit.jsonc, sync portable skills, run plan/apply or automatic postinstalls, perform locked CI checks, maintain dev-kit.lock.json, resolve ownership conflicts, patch managed ignores, or enable Effect TypeScript-Go.
+description: Dev-kit operations for projects that configure dev-kit.jsonc, sync portable skills, run plan/apply or automatic postinstalls, perform locked CI checks, maintain dev-kit.lock.json, resolve ownership conflicts, or enable Effect TypeScript-Go.
 ---
 
 # Dev Kit
 
 Treat `dev-kit.jsonc` as desired state, `dev-kit.lock.json` as the committed
-resolution, and `.dev-kit/state.json` as local ownership receipts.
+resolution, and `.dev-kit/state.json` as local ownership receipts. Deep
+reference — catalog maintenance, package-skill discovery rules, preset
+internals — lives in the package README
+(`node_modules/@danieljvdm/dev-kit/README.md`).
 
 Use the high-level commands for routine changes: `dev-kit init`, `dev-kit add
 <skill...>`, `dev-kit remove <skill...>`, `dev-kit list --all`, `dev-kit search
 <words...>`, and `dev-kit info <skill>`. Add and remove apply immediately unless
 passed `--no-apply`; `dev-kit sync` applies an already-edited manifest.
 
-For distro maintenance, use `dev-kit catalog add <repository>` to inspect and
-approve upstream skills, `catalog list`/`catalog info` to review provenance,
-`catalog remove <source-or-skill>` to revoke approval, and `catalog verify` in
-CI. Pass repeated `--skill` flags or `--all` outside a terminal. Approval always
-stores explicit skill names and exact commit/content digests.
-
 ## Apply loop
 
 1. Establish the Git root. Read project agent instructions, the current
@@ -33,14 +30,12 @@ stores explicit skill names and exact commit/content digests.
    requested creative or advisory skills even when they have no mechanical
    dependency signal.
 3. Choose the narrowest useful set. Prefer focused external skills over a
-   generic umbrella when they cover the repository's work. Select an umbrella
-   or external source family only when its full breadth is intentionally useful;
-   never select one merely because one member or product matches. Explain any
-   uncertain inclusion before applying it. Distinguish separately triggered
-   skills from lazy `references/` bundled inside one skill: unused reference
-   folders cost repository space but are not loaded into agent context unless
-   the skill routes to them. A multi-product repository can therefore justify
-   an umbrella while still excluding unrelated top-level skills.
+   generic umbrella; select an umbrella or source family only when its full
+   breadth is intentionally useful, never because one member matches. Explain
+   any uncertain inclusion before applying it. Unused `references/` folders
+   inside a selected skill cost repository space, not agent context, so a
+   multi-product repository can justify an umbrella while still excluding
+   unrelated top-level skills.
 4. Update `dev-kit.jsonc`. Preserve JSONC comments and validate against the
    package schema. Finish with each desired resource represented once and every
    external selection supported by repository evidence or an explicit request.
@@ -51,126 +46,108 @@ stores explicit skill names and exact commit/content digests.
 6. Resolve conflicts, then run `dev-kit apply`. Commit the manifest and
    regenerated `dev-kit.lock.json`; keep `.dev-kit/` local. Finish when a second
    plan reports only unchanged resources and setup tasks.
-7. Use `dev-kit apply` in the package lifecycle so intentional dependency
-   upgrades regenerate owned outputs and `dev-kit.lock.json`. For strict CI,
-   either disable lifecycle scripts before `dev-kit apply --locked`, or run the
-   normal lifecycle and require the tracked working tree to remain clean. Never
-   run an unlocked apply before locked verification. Finish when a clean install
-   converges from the committed manifest and lock.
 
 ## Manifest
 
 Use skill names or family names in `include`; subtract selections with
-`exclude`. Built-in families such as `effect` are intentional bundles. An
-external source ID is also a family, but expands to every approved skill from
-that source, so prefer individually relevant external skills. Include this
-skill as `dev-kit` when project agents should carry the toolkit procedure.
-
-Select skills bundled inside installed packages with the exact
-`<package>#<skill>` selector. The selector stays package-qualified in the
-manifest, lock, and CLI listings, and the installed output keeps that identity:
-the copied directory is named by flattening the package name (drop `@`, turn
-every other non-alphanumeric run into one dash) and appending the skill name,
-so `@tanstack/table-core#core` installs as `tanstack-table-core-core`. The
-copied `SKILL.md` frontmatter `name:` is rewritten to the same install name;
-everything else is verbatim. Symlink-mode targets still point at
-`node_modules`, so their frontmatter keeps the upstream bare name. Two selected
-skills that flatten to the same install name are rejected before any output
-changes.
+`exclude`. Built-in families such as `effect` are intentional bundles. Include
+this skill as `dev-kit` when project agents should carry the toolkit
+procedure. Skills bundled inside installed packages need the exact
+`<package>#<skill>` selector; the copied output flattens that identity into
+one directory name (`@tanstack/table-core#core` → `tanstack-table-core-core`)
+and rewrites the copied frontmatter `name:` to match.
 
 ```jsonc
 {
   "$schema": "./node_modules/@danieljvdm/dev-kit/schema/dev-kit.schema.json",
   "include": ["dev-kit", "effect"],
-  "exclude": [],
   "setup": {
     "agentInstructions": { "enabled": true },
     "claudeInstructions": { "enabled": true },
     "vitePlus": {
       "hooks": { "enabled": true },
-      "quality": {
-        "workflow": { "enabled": true },
-      },
+      "workflow": { "enabled": true },
+    },
+    "worktrunk": {
+      "config": { "enabled": true },
     },
   },
   "targets": {
     "agents": { "enabled": true, "mode": "copy" },
     "claude": { "enabled": true, "mode": "symlink" },
-    "opencode": { "enabled": false, "mode": "symlink" },
   },
 }
 ```
 
 Prefer a copied `.agents/skills` target as the project-local source of truth;
 use symlinks for additional harness discovery paths. Keep every target path
-project-relative and separate from the manifest, lock, state, and process-lock
-paths.
-
-Enable `setup.agentInstructions` to manage marked sections in a project-root
-`AGENTS.md` while preserving handwritten project guidance. The Dev Kit section
-points agents back to this skill. When `vite-plus` is a declared direct
-dependency, dev-kit synthesizes repository-specific Vite+ guidance inside its
-own section instead of importing Vite+'s generic `AGENTS.md`. Preserve the
-useful unified-toolchain overview, help and documentation entry points, and
-`vp env doctor` troubleshooting without duplicating generic commands that can
-contradict the repository policy. Treat duplicate, overlapping, reversed, or
-unmatched managed markers as a conflict rather than guessing which content Dev
-Kit owns; remove a legacy owned Vite+ section during migration.
-When `effect` is a declared direct dependency and the installed package ships a
-regular `node_modules/effect/AGENTS.md` file, the managed section also directs
-agents to read that version-matched guide completely and use
-`node_modules/effect/src` for gaps. Omit the pointer when the package is absent,
-transitive, or too old to ship the guide; never generate a dangling path.
-The managed section also publishes the repository's command authority. Direct
-Vite+ projects must use `vp` built-ins and `vp run <task>`; projects using the
-recommended Vite+ factory use `vp run check` for the complete
-format/lint/test/typecheck suite and `vp run typecheck` for the Effect-patched
-compiler. Non-Vite+ projects run
-existing root quality scripts through `bun run`; package-manager metadata and
-lockfiles affect dependency-install guidance only. Never substitute another
+project-relative and separate from the manifest, lock, and state paths.
+
+## Managed instructions
+
+`setup.agentInstructions` manages marked sections in the project-root
+`AGENTS.md` and preserves handwritten content around them; edit only outside
+the markers. The section points agents at this skill, renders the repository's
+command policy from live evidence (a direct `vite-plus` dependency makes `vp`
+the only front door; otherwise Bun runs declared root scripts), and adds the
+Effect guide pointer when the installed `effect` package ships one. Treat
+duplicate, overlapping, reversed, or unmatched managed markers as a conflict
+rather than guessing which content Dev Kit owns. Never substitute another
 script runner or call raw `tsc`, test, lint, or format binaries when a project
 command exists.
-Enable `setup.claudeInstructions` when Claude Code should consume the same
-project-root instructions; it manages `CLAUDE.md` as a relative symlink to the
-section-managed file or to an existing regular `AGENTS.md`. Preserve
-conflicting paths; when disabled, dev-kit removes only unchanged marked
-sections recorded in local ownership state and leaves handwritten content in
-place.
-
-Enable `setup.vitePlus.hooks` when an installed direct `vite-plus` dependency
-should manage Git hooks. Each apply checks the local `.vite-hooks/_` dispatcher,
-its internal `.gitignore`, the portable `.vite-hooks/pre-commit` hook, and
-`core.hooksPath`, then runs the project-local `vp config --no-agent` when they
-need convergence. This recreates ignored dispatchers in linked worktrees.
-Preserve other hook managers; Dev Kit
-refuses to replace an unrelated `core.hooksPath`. Use `VITE_GIT_HOOKS=0` or
-`HUSKY=0` to skip hook setup for an invocation.
+
+`setup.claudeInstructions` manages `CLAUDE.md` as a relative symlink to
+`AGENTS.md`. Disabling either task removes only unchanged managed content and
+leaves handwritten content in place.
+
+## Vite+ setup
 
 The repository always owns `vite.config.ts`. Compose
-`createRecommendedVitePlusConfig` from `@danieljvdm/dev-kit/vite-plus` there;
-Dev Kit never adopts, rewrites, or removes the config. The factory provides
-matching Oxlint/Oxfmt ignores, staged checks, and separate `check` and pure
-`typecheck` Vite tasks. Add repository/framework-generated paths through its
-`ignorePatterns` option, including any harness target paths that override the
-manifest defaults. Workspace mode accepts explicit package directories with
-pure `typecheck` scripts and generates cached, dependency-ordered,
-bounded-concurrency filters. Spread the returned top-level config before local
-options; spread a returned nested block before overriding that block, and merge
-nested collections such as `lint.rules` so the recommended rules remain active.
-
-Enable `setup.vitePlus.quality.workflow` to own only
-`.github/workflows/check.yml`. It requires direct Dev Kit, compatible Vite+,
-Effect, Effect TypeScript-Go, and native TypeScript dependencies with
-`setup.effectTsgo.enabled`. Preserve unowned workflows and adopt only an exact
-rendered match. Consumers may configure `workflow.beforeChecks` and
-`workflow.typecheck`; treat these commands as trusted manifest input.
-
-The workflow must use one frozen, script-suppressed install, then locked Dev Kit
-convergence before preparation or checks. Set up Bun from the consumer's
-`packageManager` or `engines.bun` declaration before Vite+ setup. Follow the
-maintained `setup-bun` major tag, name an explicit `setup-vp` release because
-its `v1` tag is frozen, and let Vite+ resolve the consumer's compatible locked
-version.
+`createRecommendedVitePlusConfig` from `@danieljvdm/dev-kit/vite-plus` there,
+adding repository/framework-generated paths (and any overridden harness target
+paths) through `ignorePatterns`. Spread the returned top-level config before
+local options, spread a returned nested block before overriding it, and merge
+nested collections such as `lint.rules` so the recommended rules stay active.
+The factory provides matching Oxlint/Oxfmt ignores, staged checks, and
+separate `check` and pure `typecheck` tasks; standalone Oxc projects import
+`recommendedOxlintConfig`/`recommendedOxfmtConfig` directly.
+
+Run the Effect-patched compiler separately with `vp run typecheck`; neither
+Oxlint's bundled `tsgolint` nor Vite+'s native lint path uses the Effect patch,
+and Vite+ 0.2.6 does not execute the preset's JavaScript-plugin rules — use
+standalone Oxlint when `effect/*` or
+`stylistic/padding-line-between-statements` must be enforced. The `effect`
+plugin's scope-sensitive rules stay consumer-scoped: enable them per path in
+Effect-owned code, with exceptions for tests and host boundaries.
+
+`setup.vitePlus.hooks` converges the Git-ignored `.vite-hooks/_` dispatcher by
+running the project-local `vp config --no-agent`, recreating it in linked
+worktrees. It requires a direct `vite-plus` dependency, refuses to replace an
+unrelated `core.hooksPath`, and is skipped per invocation with
+`VITE_GIT_HOOKS=0` or `HUSKY=0`.
+
+## Scaffolds
+
+`setup.vitePlus.workflow` and `setup.worktrunk.config` are create-only
+scaffolds: apply writes the file only when it is missing, records nothing in
+the lock, and never reads, updates, or removes an existing file — the
+repository owns it from creation and edits it directly. When the shipped
+template improves, diff the repository's file against the installed template
+under `node_modules/@danieljvdm/dev-kit/templates/` and merge what fits.
+
+- `setup.vitePlus.workflow` scaffolds `.github/workflows/check.yml`. It
+  requires direct Dev Kit, compatible Vite+, Effect, Effect TypeScript-Go, and
+  native TypeScript dependencies with `setup.effectTsgo.enabled`. Add
+  preparation steps or a custom typecheck command by editing the YAML.
+- `setup.worktrunk.config` scaffolds `.config/wt.toml`: a
+  copy-ignored-then-install pre-start pipeline, a full-validation pre-merge
+  hook, and a commented per-worktree dev-server block to enable deliberately.
+  Hook commands render for the repository's runner — `vp` with a direct
+  `vite-plus` dependency, otherwise the detected package manager's install
+  command with `bun run check` from a declared root `check` script. Keep
+  user-level Worktrunk settings such as worktree-path templates out of the
+  project config; each user approves the hooks once with
+  `wt config approvals add`.
 
 ## Ownership and conflicts
 
@@ -190,17 +167,10 @@ Preserve a conflicting path and inspect it:
 Retain `.dev-kit/state.json` across routine applies and branch changes so its
 receipts can update or remove previously applied outputs safely.
 
-## Project plumbing
-
-Run `dev-kit gitignore` to add `.repos/` and `.dev-kit/` additively. Preview with
-`dev-kit gitignore --dry-run`. Treat `.repos/<source-id>` as the reserved source
-checkout root.
+## Lifecycle
 
-Require Bun 1.3 or newer wherever Dev Kit runs. The published `dev-kit`
-executable uses Bun directly and rejects Node execution; keep Bun available to
-package lifecycle scripts and locked CI verification.
-
-For one lifecycle entry point, configure:
+Run `dev-kit gitignore` to add `.repos/` and `.dev-kit/` additively
+(`--dry-run` to preview). For one lifecycle entry point, configure:
 
 ```jsonc
 {
@@ -210,117 +180,40 @@ For one lifecycle entry point, configure:
 }
 ```
 
-This intentionally refreshes the committed lock and owned outputs when the
-package manager installs a new Dev Kit or selected package-skill version.
-Review and commit those changes with the dependency update. Keep
-`dev-kit apply --locked` as a verification command, not the normal local
-lifecycle; in CI, run it only before any unlocked apply. Invoke locked consumer
-verification as
+This intentionally refreshes the committed lock and owned outputs when an
+installed Dev Kit or selected package-skill version changes; review and commit
+those changes with the dependency update. Keep `dev-kit apply --locked` as a
+verification command, never the local lifecycle, and never run an unlocked
+apply before locked verification. Invoke locked consumer verification as
 `bun ./node_modules/@danieljvdm/dev-kit/bin/dev-kit.mjs apply --locked` so a
 package script named `dev-kit` cannot shadow the executable.
 
-## Effect source checkout
-
-Enable the source task when agents should have canonical source matching the
-installed Effect package:
-
-```jsonc
-{
-  "setup": {
-    "effectSource": { "enabled": true },
-  },
-}
-```
-
-The task reads the exact installed `effect` version and converges the ignored
-`.repos/effect` checkout on the corresponding `effect@<version>` tag. It skips
-CI, preserves a dirty or unrelated destination, and never deletes the checkout
-when disabled. Use `dev-kit effect sync --dry-run` for focused diagnosis.
-
-Override `packageName`, `path`, or `repository` only for a compatible Effect
-distribution or a deliberate mirror.
-
-## Effect TypeScript-Go
-
-Enable the setup task in the same manifest:
-
-```jsonc
-{
-  "setup": {
-    "effectTsgo": { "enabled": true },
-  },
-}
-```
-
-Install the exact `@effect/tsgo` and native `typescript` versions required by
-the installed dev-kit. Point `tsconfig.json` at
-`./node_modules/@effect/tsgo/schema.json` and configure the
-`@effect/language-service` compiler plugin with Dev Kit's exported
-`recommendedEffectTsgoPlugin` profile: warnings for
-`anyUnknownInErrorContext` and `unsafeEffectTypeAssertion`; suggestions for
-`instanceOfSchema`, `nestedEffectGenYield`, `newSchemaClass`, and
-`preferSchemaTypeProperty`; plus a `src/**/*.ts` override that warns on
-`nodeBuiltinImport` and suggests `preferSchemaOverJson`. Copy the exact JSON
-profile from the README into JSON tsconfigs. In monorepos, child
+## Effect setup tasks
+
+`setup.effectSource` converges the ignored `.repos/effect` checkout on the
+`effect@<version>` tag matching the installed package. It skips CI, preserves
+a dirty or unrelated destination, and never deletes the checkout when
+disabled. Diagnose with `dev-kit effect sync --dry-run`; override
+`packageName`, `path`, or `repository` only for a compatible Effect
+distribution.
+
+`setup.effectTsgo` validates and patches the project-local native TypeScript
+compiler. Install the exact `@effect/tsgo` and `typescript` versions required
+by the installed dev-kit, point `tsconfig.json` at
+`./node_modules/@effect/tsgo/schema.json`, and configure the
+`@effect/language-service` plugin with the `recommendedEffectTsgoPlugin`
+profile — copy the exact JSON from the package README. In monorepos, child
 `compilerOptions.plugins` arrays replace rather than merge the root array, so
-workspace configs must inherit the root plugin without redeclaring it and the
-source override must be relative to the config that contains it. `dev-kit plan`
-validates the local dependencies; `dev-kit apply` patches once and then
-converges.
-
-Use `dev-kit tsgo patch --dry-run` for focused diagnosis. Use `--force` only
-after the user accepts a potentially commit-incompatible TypeScript binary.
-
-## Oxlint and Oxfmt configurations
-
-Use Dev Kit's composable factory in Vite+ projects:
-
-```ts
-import { createRecommendedVitePlusConfig } from "@danieljvdm/dev-kit/vite-plus";
-import { defineConfig } from "vite-plus";
-
-export default defineConfig(
-  createRecommendedVitePlusConfig({
-    ignorePatterns: ["src/routeTree.gen.ts"],
-  }),
-);
-```
-
-The factory composes the canonical Oxlint/Oxfmt objects, excludes tracked skill
-copies plus symlinked harness targets from both tools, and accepts additional
-project-owned ignores. Standalone `oxlint.config.ts` uses
-`extends: [recommendedOxlintConfig]`; standalone `oxfmt.config.ts` spreads
-`recommendedOxfmtConfig`. The shared lint preset enables `typeAware` for
-semantic lint rules but leaves `typeCheck` disabled. Effect TypeScript-Go
-projects must run the patched native compiler separately with
-`vp run typecheck` after `vp fmt --check`, `vp lint`, and `vp test`; Oxlint's
-bundled `tsgolint` does not use the Effect patch.
-
-The Oxlint preset enables the fixable
-`stylistic/padding-line-between-statements` rule. It keeps adjacent variable
-declarations grouped, requires a blank line before the next logical statement,
-and separates every `return` statement from the preceding statement.
-
-Vite+ 0.2.6 forwards the preset's JavaScript-plugin declarations but its native
-Oxlint path does not register or execute their rules. Treat native rules and
-Oxfmt as active through `vp`, and use standalone Oxlint when the `effect/*` or
-`stylistic/padding-line-between-statements` rules must be enforced. Re-enable a
-Vite+ execution assertion when a supported release adds JS-plugin execution.
-
-The Oxlint preset registers Dev Kit's shared Effect plugin as `effect`, but
-does not enable its scope-sensitive rules globally. Effect projects should
-enable rules such as `effect/no-effect-run`, `effect/no-unsafe-promise`, and
-`effect/no-untyped-throw` only in Effect-owned code, with explicit exceptions
-for tests and host boundaries. The stricter `effect/no-async-workflow`,
-`effect/no-promise-atom-mode`, and `effect/no-sync-boundary-decode` rules also
-need consumer-owned scopes. Keep repository-specific paths and platform rules
-in the consuming project.
+workspace configs must inherit the root plugin without redeclaring it, and the
+`src/**/*.ts` override must be relative to the config that contains it.
+Diagnose with `dev-kit tsgo patch --dry-run`; use `--force` only after the
+user accepts a potentially commit-incompatible TypeScript binary.
 
 ## Current boundary
 
 Manage skill outputs, the `setup.agentInstructions` marked sections, the
 `setup.claudeInstructions` link, the `setup.vitePlus.hooks` dispatcher, the
-opt-in `setup.vitePlus.quality.workflow`, the `setup.effectSource` checkout,
-and the explicit `setup.effectTsgo` task. `vite.config.ts`, dependency, and
-`tsconfig.json` contributions remain deliberate user-owned edits. Compose the
-Vite+ factory or lower-level Oxlint/Oxfmt exports locally.
+`setup.effectSource` checkout, and the explicit `setup.effectTsgo` task. The
+`setup.vitePlus.workflow` and `setup.worktrunk.config` scaffolds belong to the
+repository once created. `vite.config.ts`, dependency, and `tsconfig.json`
+contributions remain deliberate user-owned edits.

package/skills/effect-atom-state/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: effect-atom-state
+description: Manage client-side state and server data in React with Effect Atom, which fills the role TanStack/React Query, SWR, Zustand, Redux, or Jotai play in other stacks — use this skill instead of reaching for those libraries or hand-rolled useEffect fetching whenever a component needs shared state, data fetching, caching, mutations, or optimistic updates. Also use when reading or dispatching atoms (useAtomValue, useAtomSet, useAtom), refactoring promise chains or useState-held server state into atom workflows, choosing reactivity keys and invalidation, deriving AtomHttpApi or HttpApiClient clients from a shared contract, deciding where the Effect→Promise boundary sits, or wiring RegistryProvider and SSR with TanStack Start.
+---
+
+# Effect Atom State
+
+Effect Atom is the client-state and server-data layer in an Effect repository:
+the role other stacks give TanStack Query, SWR, Zustand, Redux, or Jotai.
+Every need that would reach for one of those libraries — or for hand-rolled
+`useEffect` fetching — is atom work; never introduce a second state or query
+library beside it.
+
+Business logic stays in Effect for as long as possible. Components read
+`AsyncResult` values and dispatch actions; workflows, optimistic updates, and
+cache invalidation live in atoms, not in promise chains at the React boundary.
+
+Effect Atom APIs are version-sensitive. Read the target repository's manifests
+and lockfile, inspect its existing imports, and confirm exact signatures from
+the installed `effect` and `@effect/atom-react` declarations before editing.
+In current Effect v4 betas the atom modules live in
+`effect/unstable/reactivity` and the React hooks in `@effect/atom-react`.
+
+## Build the client state graph
+
+1. Inventory the existing `RegistryProvider`, runtime factories,
+   `AtomHttpApi.Service` clients, query atoms and families, mutation and
+   workflow atoms, reactivity-key constructors, state atoms, and promise-mode
+   dispatch sites. Finish when every consumer of the affected state is
+   identified.
+2. Read [effect-atom-client.md](references/effect-atom-client.md), then derive
+   one `AtomHttpApi.Service` per contract, stable query atoms or families,
+   mutation atoms, and one reactivity-key vocabulary. For non-React Effect
+   code, use the direct `HttpApiClient` branch. Finish when consumers call the
+   shared contract rather than redefining wire types or using ad hoc `fetch`
+   for declared endpoints.
+3. Read [effect-atom-workflows.md](references/effect-atom-workflows.md), then
+   express every multi-step action — mutate then invalidate, optimistic echo
+   then rollback — as an `Atom.fn` effect composing other atoms through the fn
+   context. Finish when no component or route chains `.then`/`.catch` on a
+   dispatch and no `useState` holds state a workflow atom must own.
+4. Read [effect-atom-lifecycle.md](references/effect-atom-lifecycle.md) when
+   changing registry scope, atom identity, retention, freshness, polling,
+   cancellation, or aggregate stability.
+5. Read [effect-atom-testing.md](references/effect-atom-testing.md), then give
+   changed atom behavior deterministic coverage below React first, with a
+   deterministic HTTP layer so request encoding, invalidation, and lifecycle
+   remain observable. Run the repository's format, lint, typecheck, and test
+   commands. Finish when changed queries, mutations, invalidation, and
+   workflow atoms have deterministic tests and every repository check passes.
+
+## Optional branches
+
+- Read [tanstack-start.md](references/tanstack-start.md) when the client is
+  TanStack Start, SSR, hydration, `ClientOnly`, loaders, server functions, or a
+  proxied separate API.
+- Use the `$build-effect-apis` skill when the change reaches the contract or
+  server: shared `HttpApiEndpoint`/`HttpApiGroup` definitions, handlers,
+  middleware, or runtime assembly.
+
+## Keep the Promise boundary logic-free
+
+The Effect→Promise boundary sits at the outermost edge and carries no logic.
+
+- Return a promise-mode dispatch (`useAtomSet(action, { mode: "promise" })`)
+  bare to a leaf component whose contract is promise-shaped — a pending
+  button, a composer that owns its in-flight state. A `.then` or `.catch`
+  chain in a component or route is a violation: move that logic into the
+  action's Effect.
+- Express multi-step workflows as `Atom.fn` effects composing other atoms
+  through the fn context: `get.setResult` awaits another fn atom, `get.set`
+  writes state atoms. Reads through the fn context callable are untracked, so
+  mutating a state atom from inside the effect cannot re-trigger the workflow.
+- Declare cross-query invalidation as reactivity keys on the mutation; never
+  chain a manual refresh at a call site. When several `AtomHttpApi` services
+  share one Atom runtime, one `Reactivity` instance spans them, so a mutation
+  on one client invalidates another client's query keys.
+- Keep optimistic UI state in `Atom.family` state atoms keyed by the entity,
+  not `useState`, so the workflow atom that writes it owns its lifecycle.
+- Genuine view state — controlled inputs, open/closed toggles, reconciling
+  optimistic rows against rendered props — stays in React; do not force it
+  into Effect.
+
+A repository may reinforce the boundary with a lint warning on `then` scoped
+to component and route modules, with a documented local suppression for a
+genuinely promise-shaped contract, but the boundary reasoning remains the
+source of truth.
+
+## Boundary rules
+
+- Let client data modules own API services, query identity, cache policy,
+  invalidation keys, mutation atoms, and workflow atoms.
+- Let workflow atoms own orchestration, optimistic echo, rollback, and
+  cross-query invalidation.
+- Let UI action owners own navigation, toasts, form reset, and presentation
+  derived from `AsyncResult` state.
+- Let React own view state that no atom needs to write.

package/skills/effect-atom-state/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Effect Atom State"
+  short_description: "Manage Effect Atom client state and React integration"
+  default_prompt: "Use $effect-atom-state to move this component's client state and workflows into Effect Atom."