@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/snapshots/wizard-setup.md

@@ -0,0 +1,134 @@
+# SnapshotPreviews Wizard Setup
+
+Use this only when no existing snapshot generator/setup exists and the user explicitly
+wants Sentry’s first-party SnapshotPreviews image source.
+
+## Flow
+
+1. Run the non-interactive wizard first.
+2. If the wizard succeeds, continue with the main skill’s completion checks.
+3. If the wizard stops for a known recoverable reason, follow the matching section
+   below.
+4. Use manual fallback only after the wizard is unavailable, rejects `appleSnapshots`,
+   or still cannot complete after requested disambiguation.
+
+## Run the Wizard
+
+Pass the directory that contains the selected `.xcodeproj` and let the wizard
+auto-detect app targets, hosted XCTest targets, and Swift previews:
+
+```bash
+npx @sentry/wizard@latest -i appleSnapshots --non-interactive \
+  --xcode-project-dir <path-to-xcode-project-dir>
+```
+
+Use `.` when the `.xcodeproj` is in the repository root.
+Use the parent directory when detection returned a nested bundle path, for example `ios`
+for `ios/MyApp.xcodeproj`.
+
+## Handle Wizard Outcomes
+
+| Outcome                                                                                        | Action                                                                                                                                                                                                                                    |
+| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Wizard completes                                                                               | Continue with the main skill’s completion checks.                                                                                                                                                                                         |
+| Dirty working tree blocks non-interactive mode                                                 | Inspect `git status --short`. If dirty files are pre-existing or expected for the user’s scenario, rerun the same command with `--ignore-git-changes`. Do not clean, stash, or revert user files just to satisfy the wizard safety check. |
+| Wizard asks for app target or hosted XCTest target                                             | Follow [Target Disambiguation](#target-disambiguation).                                                                                                                                                                                   |
+| Wizard reports no hosted XCTest target                                                         | Follow [Target Disambiguation](#target-disambiguation) to confirm. If no hosted target exists, stop and ask the user to add or identify one.                                                                                              |
+| Wizard reports no Swift previews                                                               | Stop and ask whether to add Swift previews or use another snapshot image source. Do not add, restore, or rewrite previews just to make SnapshotPreviews produce images unless the user explicitly approves that source change.            |
+| Wizard is unavailable, rejects `appleSnapshots`, or still fails after requested disambiguation | Follow [Manual Fallback](#manual-fallback) only if a hosted XCTest target exists.                                                                                                                                                         |
+
+## Target Disambiguation
+
+Use this only when the wizard asks for target values or reports that no hosted XCTest
+target was found. Start from the wizard’s error output.
+`--xcode-project-dir` should already be present.
+
+Only gather values the wizard asked for.
+Probe first; ask the user only if probing cannot identify a safe single target.
+
+| Wizard asks for      | How to investigate                                                              | Add flag                                   |
+| -------------------- | ------------------------------------------------------------------------------- | ------------------------------------------ |
+| App target           | `xcodebuild -list -project <Project>.xcodeproj 2>/dev/null`                     | `--app-target <AppTarget>`                 |
+| Hosted XCTest target | `grep -rE "TEST_HOST\|BUNDLE_LOADER" --include='project.pbxproj' . 2>/dev/null` | `--hosted-test-target <HostedTestsTarget>` |
+
+If the wizard asks for multiple values, gather all requested values through probing or
+user clarification, then rerun once with the complete requested flag set.
+
+```bash
+npx @sentry/wizard@latest -i appleSnapshots --non-interactive \
+  --xcode-project-dir <path-to-xcode-project-dir> \
+  --app-target <AppTarget> \
+  --hosted-test-target <HostedTestsTarget>
+```
+
+Use only the target flags the wizard requested.
+
+If the hosted-target probe returns no `TEST_HOST` or `BUNDLE_LOADER` entries, stop and
+ask the user to add a hosted Unit Testing Bundle target for the app or identify an
+existing hosted test target.
+Do not use the manual fallback until a hosted XCTest target exists; SnapshotPreviews
+renders through `xcodebuild test`, and a standalone app target cannot run the generated
+`SnapshotTest` class.
+
+If the rerun still fails after requested disambiguation, use manual fallback only when a
+hosted XCTest target exists.
+
+## Manual Fallback
+
+Use this only if the wizard is unavailable, rejects `appleSnapshots`, or cannot complete
+after disambiguation and the project has a hosted XCTest target.
+If no hosted XCTest target exists, stop and ask for one first.
+
+1. Add the Swift package to the Xcode project/workspace that builds the app and hosted
+   snapshot test target:
+
+```text
+https://github.com/getsentry/SnapshotPreviews
+```
+
+1. Link products:
+
+| Product               | Target                                                                       |
+| --------------------- | ---------------------------------------------------------------------------- |
+| `SnapshottingTests`   | Hosted snapshot/layout XCTest target                                         |
+| `SnapshotPreferences` | Preview-declaring target only when custom tags/context/thresholds are needed |
+| `PreviewGallery`      | Internal app target only when an in-app preview gallery is requested         |
+
+2. Add or verify one hosted XCTest class importing `SnapshottingTests` and inheriting
+   from `SnapshotTest`.
+3. Export images with `TEST_RUNNER_SNAPSHOTS_EXPORT_DIR` and `xcodebuild test`.
+4. Upload with `sentry-cli snapshots upload`.
+
+```bash
+TEST_RUNNER_SNAPSHOTS_EXPORT_DIR="$PWD/snapshot-images" \
+xcodebuild test \
+  -scheme MyApp \
+  -sdk iphonesimulator \
+  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
+  -only-testing:MyAppTests/MyAppSnapshotTest
+
+sentry-cli snapshots upload "$PWD/snapshot-images" \
+  --org your-org \
+  --project your-ios-project \
+  --app-id com.example.MyApp
+```
+
+Only after non-interactive wizard setup, requested target disambiguation, and manual
+fallback all fail, tell the user they can run the wizard interactively and return with
+the error output:
+
+```bash
+npx @sentry/wizard@latest -i appleSnapshots --xcode-project-dir <path-to-xcode-project-dir>
+```
+
+## Rules
+
+- `--app-id` is a stable app identifier/bundle id, not the Sentry project slug.
+- Use `sentry-cli snapshots upload`, not deprecated `sentry-cli build snapshots`.
+- SnapshotPreviews test-runner environment variables use the `TEST_RUNNER_` prefix so
+  values are forwarded into the app/test process.
+- Base branch uploads the full set.
+- PR selective uploads require a full image-name manifest; read `snapshots.md`.
+
+Completion for this route means the wizard completed, or manual fallback completed with
+the same project changes.

package/skills/testing/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/testing/NOTICE

@@ -0,0 +1,7 @@
+Dev Kit adaptation of https://github.com/mattpocock/skills
+Copyright (c) 2026 Matt Pocock. MIT license retained in LICENSE.
+Source revision: 2ab958093e83e0ec752e6c1c5932da465bf23e0c
+Includes the repository-owned TDD guidance previously distributed by Dev Kit.
+
+Modified by Dev Kit to reuse user-selected boundaries, avoid redundant
+confirmation, and let repository testing policy own committed test decisions.

package/skills/testing/SKILL.md

@@ -1,28 +1,22 @@
 ---
 name: testing
-description: Set an extremely high bar for automated tests. Use whenever software work raises the question of adding, changing, retaining, or removing tests.
+description: Decide whether committed tests are warranted, design regression tests, or follow explicitly requested TDD.
+license: MIT
 ---
 
 # Testing
 
-**If in doubt, don't test it.**
+Follow the repository's testing policy and the user's requested scope. Adding
+source code does not by itself justify committed tests. Prefer the cheapest
+verification that proves the changed behavior.
 
-Committed tests must prove durable value. Tests are permanent product code, not a reflexive companion to each source file.
+- Whether to add, retain, or remove a test: [test selection](references/selection.md).
+- A test boundary, substitute, or mocking decision: [test design](references/test-design.md).
+- An explicit TDD, red-green, or test-first request: [TDD](references/tdd.md).
+  Ordinary feature verification does not require this workflow.
 
-Write a test only when every condition holds:
+Honor an explicit testing request within its scope. Express expectations
+independently of implementation, exercise a stable public boundary, and follow
+repository evidence and placement rules. Keep the final suite green.
 
-- It protects stable product behavior rather than an implementation detail.
-- A regression is plausible and would be costly.
-- The behavior is observable through a stable public seam.
-- The test will survive likely refactors.
-- The expected result is independent of the implementation.
-- Existing tests, types, static checks, or a smoke check cannot cover the risk adequately.
-
-If any condition fails, skip the test and use the cheapest sufficient verification instead. Moving MVP behavior often warrants no committed tests.
-
-Test capabilities, not files. Use the fewest tests that protect the risk, and ignore coverage targets unless the user explicitly asks for them.
-
-Never commit an intentionally failing or red-only suite. Keep time-driven tests
-deterministic instead of stabilizing them with wall-clock sleeps. A shared fake
-or in-memory implementation must fully provide the behavior its name promises;
-keep partial substitutes local to the tests that need them.
+TDD attribution is in [NOTICE](NOTICE); terms are in [LICENSE](LICENSE).

package/skills/testing/agents/openai.yaml

@@ -1,4 +1,3 @@
 interface:
   display_name: "Testing"
-  short_description: "Set a very high bar for automated tests"
-  default_prompt: "Use $testing to decide whether this change truly warrants any automated tests."
+  short_description: "Regression test selection and requested TDD"

package/skills/testing/references/selection.md

@@ -0,0 +1,23 @@
+# Testing
+
+**If in doubt, don't test it.**
+
+Committed tests must prove durable value. Tests are permanent product code, not a reflexive companion to each source file.
+
+Write a test only when every condition holds:
+
+- It protects stable product behavior rather than an implementation detail.
+- A regression is plausible and would be costly.
+- The behavior is observable through a stable public seam.
+- The test will survive likely refactors.
+- The expected result is independent of the implementation.
+- Existing tests, types, static checks, or a smoke check cannot cover the risk adequately.
+
+If any condition fails, skip the test and use the cheapest sufficient verification instead. Moving MVP behavior often warrants no committed tests.
+
+Test capabilities, not files. Use the fewest tests that protect the risk, and ignore coverage targets unless the user explicitly asks for them.
+
+Never commit an intentionally failing or red-only suite. Keep time-driven tests
+deterministic instead of stabilizing them with wall-clock sleeps. A shared fake
+or in-memory implementation must fully provide the behavior its name promises;
+keep partial substitutes local to the tests that need them.

package/skills/testing/references/tdd.md

@@ -0,0 +1,19 @@
+# Test-driven development
+
+Use the repository's testing policy, command authority, and public boundaries.
+Reuse the behavior and test boundary the user already named. When those are
+unspecified, choose the strongest relevant public boundary from the existing
+design; ask only if the choice changes the intended behavior or scope.
+
+Write a failing test that independently expresses the requested behavior.
+Confirm the failure is meaningful, implement enough to pass, then refactor
+when it improves the code while keeping the test green. Work in small slices
+that can inform the next decision.
+
+For a difficult choice of boundary or substitute, read
+[test design](test-design.md). Avoid a new abstraction solely to
+make implementation details easier to mock.
+
+Keep the final suite green and obey the repository's evidence and placement
+rules. A TDD request authorizes test-first work within the requested task; it
+does not require a separate confirmation at every cycle.

package/skills/testing/references/test-design.md

@@ -0,0 +1,17 @@
+# Test design
+
+Observe behavior through the public boundary that owns it. Assert an expected
+result derived from the requirement, a worked example, or independent fixture,
+rather than repeating the implementation's calculation.
+
+Choose the boundary that exposes the failure with the fewest irrelevant moving
+parts. Persistence requirements may need real storage and migrations; UI
+interaction failures may need a browser. Follow the repository's substitutes
+and avoid mocks of internal collaborators that only prove the current wiring.
+
+Control nondeterministic inputs such as time or an external service when the
+failure requires it. A substitute must faithfully provide the behavior its
+interface promises. Keep its use local unless several justified tests need it.
+
+Use assertions that distinguish the failure from success and survive unrelated
+refactors. Do not add companion tests merely because a new source file exists.

package/src/catalog.ts

@@ -186,13 +186,7 @@ export const loadSkillCatalog = Effect.fn("loadSkillCatalog")(function* (
     });
   }
   const families = {
-    effect: [
-      "effect-ts",
-      "effect-architecture-audit",
-      "build-effect-apis",
-      "effect-atom-state",
-      "build-effect-clis",
-    ],
+    effect: ["effect-development"],
     ...Object.fromEntries(externalFamilies),
   } satisfies Readonly<Record<string, ReadonlyArray<string>>>;
 

package/skills/build-effect-apis/SKILL.md

@@ -1,81 +0,0 @@
----
-name: build-effect-apis
-description: Build contract-first Effect HTTP APIs. Use when defining shared HttpApiEndpoint/HttpApiGroup contracts, implementing HttpApiBuilder or HttpApiServer handlers and middleware, assembling server runtimes and OpenAPI docs, or serving on Cloudflare Workers/effect-cf. For consuming an API from client state, use $effect-atom-state.
----
-
-# Build Effect APIs
-
-Treat the shared `HttpApi` value as the **contract spine**: schemas, server,
-OpenAPI, and clients all derive from it. Keep transport contracts isomorphic;
-keep runtime behavior in handlers, services, layers, and client state modules.
-
-Effect HTTP APIs are version-sensitive. Read the target repository's manifests
-and lockfile, inspect its existing imports, and confirm exact signatures from
-the installed package declarations before editing. In current Effect v4 betas
-the server module is `HttpApiBuilder`; a request that mentions `HttpApiServer`
-may refer to the same server-building responsibility from another version.
-
-## Build the contract spine
-
-1. Inventory the existing API root, groups, endpoints, schemas, transport
-   errors, middleware, handler layers, client construction, and runtime edge.
-   Finish when every existing contract consumer and provider is identified.
-2. Read [shared-contracts.md](references/shared-contracts.md), then change the
-   shared domain package first: schemas and errors, one endpoint contract,
-   group composition, root API composition, and public exports. Finish when
-   server and client can import the same API value without runtime-specific
-   dependencies entering the domain package.
-3. Read [server-and-middleware.md](references/server-and-middleware.md), then
-   implement middleware and every changed group handler. Keep handlers as
-   decoded boundary adapters into application services and assemble all
-   requirements at the runtime edge. Finish when each endpoint identifier has
-   exactly one handler and every declared middleware has a provided layer.
-4. Route consumer changes through the `$effect-atom-state` skill: deriving
-   `AtomHttpApi` or direct `HttpApiClient` clients, query and mutation atoms,
-   reactivity keys, and React integration all live there. Finish when consumers
-   call the shared contract rather than redefining wire types or using ad hoc
-   `fetch` for declared endpoints.
-5. Read [verification.md](references/verification.md). Run the repository's
-   format, lint, typecheck, and test commands. Finish when changed schemas
-   round-trip, middleware failures use declared error channels, and server and
-   client agree on every request shape.
-
-## Optional branches
-
-- Read [runtime-assembly.md](references/runtime-assembly.md) when wiring a
-  conventional Node/Bun server, generated API docs, process entrypoint, or
-  serverless web handler.
-- Read [cloudflare-workers.md](references/cloudflare-workers.md) when the server
-  runs on Cloudflare Workers or uses `effect-cf`, bindings, Durable Objects,
-  Queues, WebSockets, streaming, or raw byte routes.
-
-## Choose typed Schema codecs by default
-
-Match the codec to the static type at the call site. When decoding a value that
-is already typed as the schema's `Encoded` type, use `Schema.decodeEffect` or
-the typed `Schema.decodeSync`, `Schema.decodeExit`, `Schema.decodeOption`,
-`Schema.decodeResult`, or `Schema.decodePromise` variant. When encoding a value
-that is already typed as the schema's `Type`, use `Schema.encodeEffect` or the
-corresponding typed `Schema.encodeSync`, `Schema.encodeExit`,
-`Schema.encodeOption`, `Schema.encodeResult`, or `Schema.encodePromise` variant.
-
-Reserve `Schema.decodeUnknown*` and `Schema.encodeUnknown*` for genuinely
-untyped boundaries: values from `JSON.parse`, `Response.json`, external
-messages, or persistence APIs whose declared result is actually `unknown`.
-Never choose an unknown codec to bypass a `Schema.Class` or other static type
-mismatch. Map the source value or construct the correct schema `Type` first,
-then use the typed encoder; similarly, establish the correct `Encoded` value
-before using a typed decoder.
-
-This rule is toolchain-neutral. A repository may reinforce it with a lint
-warning and a documented local suppression for a justified untyped boundary,
-but the boundary and type reasoning remain the source of truth.
-
-## Boundary rules
-
-- Let schemas own wire validation, encoding, status metadata, and branded IDs.
-- Let endpoint files own route inputs, success, and expected transport errors.
-- Let middleware own cross-cutting request behavior and request-scoped services.
-- Let handlers own transport-to-application mapping and boundary invariants.
-- Let application services own orchestration, persistence, retries, and
-  transactions.

package/skills/build-effect-apis/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Build Effect APIs"
-  short_description: "Build and consume typed Effect HTTP APIs"
-  default_prompt: "Use $build-effect-apis to build a shared Effect HTTP API and consume it from the application client."

package/skills/build-effect-clis/SKILL.md

@@ -1,92 +0,0 @@
----
-name: build-effect-clis
-description: Write and maintain every executable script and command-line application in an Effect repository as an Effect program. Use when creating or changing any script, one-off automation, CI check, deploy/release/build glue, package-script entrypoint, CLI command, arguments, flags, prompts, child process, filesystem or environment workflow, Node/Bun entrypoint, or integration test—including extending an existing plain-TypeScript script.
----
-
-# Build Effect Scripts and CLIs
-
-## Effect-first scope
-
-Every executable script and CLI in an Effect repository is an Effect program.
-This includes one-off scripts, CI checks, deploy/release/build glue, files under
-`scripts/`, package-script targets, migrations, and application entrypoints—not
-only polished command-line tools.
-
-Apply this rule when modifying code as well as when creating it. When a task
-touches an existing plain-TypeScript script, convert the whole script to Effect
-in the same change; matching the surrounding file's style or minimizing the
-diff is not a valid exception. Prefer the repository's established Effect
-patterns, including those in sibling scripts, over legacy patterns in the file
-being converted.
-
-Leave a script outside Effect only for a good, concrete technical or user
-constraint that makes Effect unsuitable. Explicitly state that reason before
-proceeding and in the final handoff, and keep the exception as narrow as
-possible. Convenience, one-off status, and existing plain-TypeScript style are
-not sufficient reasons.
-
-Use Effect platform services for filesystem, path, environment, terminal, and
-child-process work. Raw `node:*` or Bun runtime imports, `process.env`, `fs`,
-`path`, `child_process`, and synchronous helpers such as `execFileSync` do not
-belong in script workflows. If the installed Effect platform has no required
-capability, isolate the runtime call in an explicit boundary adapter whose API
-returns an Effect with typed errors, and document why that adapter is required.
-
-Treat each executable as an Effect application. For a CLI, the `Command` tree
-owns the user-facing contract, handlers adapt decoded input into application
-workflows, services own capabilities, and the executable entrypoint supplies
-platform Layers and runs the program. A fixed automation script with no public
-arguments may export an Effect workflow directly instead of inventing a
-`Command` tree. Do not introduce a separate CLI framework for command work.
-
-Effect CLI and process APIs are version-sensitive. Read the target repository's
-`node_modules/effect/AGENTS.md` completely, follow its CLI and child-process
-references, and confirm exact signatures from the installed declarations before
-editing.
-
-## Build the executable boundary
-
-1. Inventory the existing executable entrypoints, package scripts, command
-   tree, shared flags, prompts, application services, platform Layers, output
-   modes, and subprocess helpers. Finish when every way to invoke and test the
-   affected scripts or CLI is known, including sibling Effect scripts whose
-   patterns should replace legacy plain-TypeScript style.
-2. When the executable accepts public arguments or flags, read
-   [command-design.md](references/command-design.md). Define arguments and flags
-   with `Argument` and `Flag`, compose commands with `Command`, and give every
-   public input useful help. Use `Effect.fn` handlers and yield the root command
-   when a subcommand needs shared parent input.
-3. Keep handlers thin. Decode user and file input at the boundary, enforce
-   cross-input invariants, then call an application service. Keep persistence,
-   network calls, orchestration, retries, and transactions in services.
-4. Keep expected operational failures typed with `Schema.TaggedError`; map
-   platform failures into application-owned errors near the adapter that knows
-   what the operation means. Let defects remain defects.
-5. Read [entrypoints-and-testing.md](references/entrypoints-and-testing.md).
-   Export the command tree or fixed script workflow without running it, wire
-   one Node or Bun entrypoint, and verify the applicable success, expected
-   failure, help, parsing, JSON, dry-run, and confirmation paths.
-
-## Optional branches
-
-- Read [processes-and-platform.md](references/processes-and-platform.md) when a
-  script or command reads files, inspects the environment, starts child
-  processes, streams their output, or differs between Node and Bun.
-- Use `Prompt` only for an intentionally interactive path. Keep required inputs
-  expressible as arguments or flags so automation never depends on a terminal.
-- Add `--dry-run` for commands that mutate important state and `--yes` for
-  explicitly authorized non-interactive confirmation. Never prompt in JSON or
-  CI-oriented modes.
-
-## CLI ownership rules
-
-- Let `Command`, `Argument`, and `Flag` own syntax, defaults, aliases, examples,
-  and help text.
-- Let schemas own untrusted structured input and machine-readable output.
-- Let handlers own CLI-to-application mapping and presentation selection.
-- Let services own reusable behavior and external capabilities.
-- Let Layers own implementations and runtime dependencies.
-- Let the executable entrypoint own `Command.run`, platform provisioning,
-  scopes, signal handling, and `NodeRuntime.runMain` or `BunRuntime.runMain`.
-- Keep stdout stable for primary or machine-readable output. Send diagnostics
-  and progress elsewhere; never mix prose into JSON output.

package/skills/build-effect-clis/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Build Effect Scripts and CLIs"
-  short_description: "Write every script and CLI with Effect"
-  default_prompt: "Use $build-effect-clis to write or modify this script or CLI as an Effect program with explicit platform boundaries and tests."

package/skills/effect-architecture-audit/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Effect Architecture Audit"
-  short_description: "Audit Effect service and boundary ownership"
-  default_prompt: "Use $effect-architecture-audit to audit this Effect codebase's services, Layers, and type boundaries."

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

@@ -1,97 +0,0 @@
----
-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

@@ -1,4 +0,0 @@
-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."

package/skills/effect-ts/SKILL.md

@@ -1,35 +0,0 @@
----
-name: effect-ts
-description: Use this skill when setting up a repository that uses the Effect Typescript library.
----
-
-# Step 1: Install effect
-
-Use the users preferred package manager:
-
-```
-pnpm add effect@beta
-```
-
-If in a monorepo, install it as a dev dependency at the root, so you can access
-the source code from `node_modules/effect/src`.
-
-```
-pnpm add -D effect@beta
-```
-
-# Step 2: Update AGENTS.md / CLAUDE.md
-
-Ensure that the agent instructions contain the following:
-
-```md
-# Learning more about the Effect
-
-This repository uses the Effect Typescript library.
-
-Before writing any Effect code, first read `node_modules/effect/AGENTS.md`
-**completely**, and follow the links in the file when required.
-
-If you need to learn more about particular Effect apis and concepts that the
-guide doesn't cover, search through the source code in `node_modules/effect/src`.
-```

package/skills/effect-ts/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Effect TypeScript Setup"
-  short_description: "Set up version-matched Effect guidance"
-  default_prompt: "Use $effect-ts to set up Effect and its package-bundled agent guidance."