@danieljvdm/dev-kit 0.11.3 → 0.12.0

package/skills/dev-kit/SKILL.md

@@ -66,6 +66,18 @@ 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.
+
 ```jsonc
 {
   "$schema": "./node_modules/@danieljvdm/dev-kit/schema/dev-kit.schema.json",
@@ -77,7 +89,6 @@ skill as `dev-kit` when project agents should carry the toolkit procedure.
     "vitePlus": {
       "hooks": { "enabled": true },
       "quality": {
-        "config": { "enabled": true },
         "workflow": { "enabled": true },
       },
     },
@@ -105,10 +116,16 @@ useful unified-toolchain overview, help and documentation entry points, and
 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>`; managed quality
-projects 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
+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
 script runner or call raw `tsc`, test, lint, or format binaries when a project
@@ -122,27 +139,30 @@ place.
 
 Enable `setup.vitePlus.hooks` when an installed direct `vite-plus` dependency
 should manage Git hooks. Each apply checks the local `.vite-hooks/_` dispatcher,
-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
+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.
 
-Enable `setup.vitePlus.quality.config` and
-`setup.vitePlus.quality.workflow` independently in supported Vite+/Effect
-repositories. Config owns canonical root `vite.config.ts`; workflow owns
-`.github/workflows/check.yml`; selecting one must not constrain the other's
-config, scripts, or TypeScript topology. Both require direct Dev Kit, compatible
-Vite+, Effect, Effect TypeScript-Go, and native TypeScript dependencies with
-`setup.effectTsgo.enabled`. Preserve unowned destinations and adopt only exact
-rendered matches.
-
-Managed config defines separate `check` and pure `typecheck` Vite tasks. Its
-default single-project strategy rejects project references; workspace mode
-requires explicit package directories with `typecheck` scripts and generates
-cached, dependency-ordered, bounded-concurrency filters. Keep project-reference
-builds custom. Workflow-only consumers may configure `workflow.beforeChecks`
-and `workflow.typecheck`; treat these commands as trusted manifest input.
+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.
+
+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
@@ -242,31 +262,24 @@ after the user accepts a potentially commit-incompatible TypeScript binary.
 
 ## Oxlint and Oxfmt configurations
 
-Use Dev Kit's canonical Oxlint and Oxfmt objects in Vite+ projects:
+Use Dev Kit's composable factory in Vite+ projects:
 
 ```ts
-import { recommendedOxlintConfig } from "@danieljvdm/dev-kit/oxlint";
-import { recommendedOxfmtConfig } from "@danieljvdm/dev-kit/oxfmt";
+import { createRecommendedVitePlusConfig } from "@danieljvdm/dev-kit/vite-plus";
 import { defineConfig } from "vite-plus";
 
-export default defineConfig({
-  fmt: {
-    ...recommendedOxfmtConfig,
-  },
-  lint: {
-    extends: [recommendedOxlintConfig],
-    rules: {
-      // Project-specific rules apply after the shared preset.
-    },
-  },
-});
+export default defineConfig(
+  createRecommendedVitePlusConfig({
+    ignorePatterns: ["src/routeTree.gen.ts"],
+  }),
+);
 ```
 
-Use `lint.extends` instead of spreading the object so Vite+ composes nested
-rule maps correctly. Oxfmt has no inheritance mechanism, so spread its object
-before project-local options. Standalone `oxlint.config.ts` uses the same
-`extends: [recommendedOxlintConfig]`; standalone `oxfmt.config.ts` spreads the
-same `recommendedOxfmtConfig`. The shared lint preset enables `typeAware` for
+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
@@ -290,8 +303,7 @@ in the consuming project.
 
 Manage skill outputs, the `setup.agentInstructions` marked sections, the
 `setup.claudeInstructions` link, the `setup.vitePlus.hooks` dispatcher, the
-independently opt-in `setup.vitePlus.quality` config and GitHub workflow, the
-`setup.effectSource` checkout, and the explicit `setup.effectTsgo` task.
-Dependency and `tsconfig.json` contributions remain deliberate user-owned
-edits. Custom Vite configs compose the Oxlint and Oxfmt package exports
-manually, leave managed config disabled, and may still use the managed workflow.
+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.

package/skills/effect-architecture-audit/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: effect-architecture-audit
+description: Audit an Effect TypeScript codebase's services, Layers, dependency ownership, hidden requirements, test substitutes, Schema boundaries, assertions, unknown values, and typed error channels. Use for architecture reviews, service refactors, dependency-injection audits, and type-boundary investigations; do not use as a general Effect API reference.
+---
+
+# Audit Effect Architecture
+
+Read the target repository's `node_modules/effect/AGENTS.md` completely before
+evaluating Effect code. Follow its version-matched references for library APIs;
+use this skill only for the application-architecture judgments it does not own.
+
+Read [service-and-boundary-audit.md](references/service-and-boundary-audit.md),
+then:
+
+1. Establish the repository's local architecture and testing rules.
+2. Inventory every service, Layer, dependency path, runtime authority, test
+   substitute, and unsafe type boundary in scope.
+3. Trace each capability to its owner and composition root.
+4. Classify each candidate as a built-in capability, application authority,
+   technology adapter, explicit value, framework boundary, or pass-through
+   abstraction.
+5. Report evidence-backed findings and explicit keep decisions. Do not propose
+   a wrapper, service, or Schema merely to make the inventory symmetrical.
+
+When asked only to audit or review, stop after the findings. Implement changes
+only when the user also requests them.

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

@@ -0,0 +1,4 @@
+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-architecture-audit/references/service-and-boundary-audit.md

@@ -0,0 +1,150 @@
+# Service And Boundary Audit
+
+## Contents
+
+- [Establish authority](#establish-authority)
+- [Build the inventory](#build-the-inventory)
+- [Trace requirements](#trace-requirements)
+- [Classify candidates](#classify-candidates)
+- [Audit type boundaries](#audit-type-boundaries)
+- [Audit test substitutes](#audit-test-substitutes)
+- [Report findings](#report-findings)
+
+## Establish authority
+
+Read the repository's architecture guidance and version-matched Effect package
+instructions. Treat installed declarations and source as the authority for API
+signatures. Record local conventions that affect service ownership, adapter
+placement, error translation, and testing.
+
+## Build the inventory
+
+Find every:
+
+- Effect service, tag, Layer, constructor, and provisioning call.
+- Service-shaped interface, class, dependency bag, registry, or callback.
+- Direct use of time, randomness, IDs, configuration, credentials, HTTP,
+  persistence, filesystems, runtime bindings, or mutable globals.
+- Test Layer, fake, in-memory implementation, and module mock.
+- Public Effect with an `unknown` or overly broad error channel.
+- `any`, assertion, non-null assertion, custom predicate, structural probe,
+  unvalidated JSON parse, Promise rejection mapper, and expected throw.
+- Schema or codec that overlaps another representation of the same logical
+  model.
+
+Record one row per service or candidate:
+
+| Field        | Question                                             |
+| ------------ | ---------------------------------------------------- |
+| Owner        | Which module owns the capability's meaning?          |
+| Contract     | Where is its public contract defined?                |
+| Construction | Are all construction requirements visible?           |
+| Production   | Who chooses the concrete implementation?             |
+| Consumers    | Is the capability yielded or drilled as a value?     |
+| Boundary     | Who owns decoding, narrowing, and error translation? |
+| Tests        | Is its substitute strategy intentional and honest?   |
+| Verdict      | Keep, deepen, relocate, merge, remove, or create?    |
+
+Complete the inventory when each discovered capability and unsafe boundary
+appears exactly once.
+
+## Trace requirements
+
+For each row:
+
+1. Trace one caller-visible operation through every effect it performs.
+2. Mark where each dependency first appears and whether code yields, passes,
+   captures, or concretely provides it.
+3. Verify that the module selecting a concrete Layer owns that implementation
+   choice.
+4. Follow every Layer requirement to a composition root or an explicit value
+   boundary.
+5. Check version-matched Effect capabilities before recommending an
+   application wrapper.
+
+Flag hidden requirements created by inner provisioning, dependency bags,
+handler-builder service values, mutable registries, or Layer selection inside
+business operations. Prefer provision at a program or subsystem edge. Avoid
+thin exported helpers that only yield a service and forward one method.
+
+## Classify candidates
+
+Assign one evidence-backed classification:
+
+- **Built-in Effect capability** — yield the existing capability directly.
+- **Application-owned authority** — define a narrow port beside the operation
+  whose policy gives it meaning.
+- **Technology adapter** — implement an application-owned port at the external
+  boundary.
+- **Request or domain value** — keep deterministic, per-call data explicit.
+- **Framework boundary** — contain framework-required state or assertions in
+  the adapter or composition root.
+- **Pass-through abstraction** — fold it into the actual owner.
+
+Apply the deletion test: if removing an abstraction leaves equally clear code
+without spreading authority, resource ownership, or policy, remove it. Prefer
+an existing owner or a merge over a generic registry.
+
+## Audit type boundaries
+
+Assign every `unknown` value a boundary owner.
+
+- Reserve `unknown` for external input, foreign library output, and opaque
+  diagnostic causes.
+- Decode structured external data once, at the earliest boundary that owns its
+  meaning.
+- Pass decoded values and concrete error unions through internal services.
+- Keep unavoidable framework assertions at the narrowest adapter and document
+  the contract they bridge.
+- Remove runtime narrowing already guaranteed by the inferred type.
+- Preserve irreducible foreign causes as diagnostic fields inside concrete
+  domain errors instead of broadening public error channels.
+
+Prefer one source Schema per logical model. Use Schema transformations or
+derived variants when a storage or transport representation differs without
+changing the model's meaning. Create a separate Schema only for a real semantic
+difference.
+
+Keep a helper only when it owns domain policy, reusable refinement, repeated
+non-trivial mechanics, or a meaningful observability boundary. Inline one-use
+tag comparisons and structural checks that add no meaning.
+
+## Audit test substitutes
+
+Record the intended test strategy for every production service.
+
+- Make a shared test Layer's name match the behavior it fully provides.
+- Keep partial fixtures local instead of publishing them as general in-memory
+  implementations.
+- Use a real local adapter when persistence, transactions, serialization, or
+  lifecycle behavior is the subject under test.
+- Keep timing deterministic; never add wall-clock sleeps to stabilize a test.
+- Test protocol round trips when encoding or decoding behavior is a durable,
+  regression-prone public seam.
+
+An explicit production-only rationale is valid when a substitute would not
+protect durable behavior.
+
+## Report findings
+
+Prioritize findings by impact:
+
+- **P0** — hidden authority, unsafe runtime access, wrong implementation
+  ownership, unchecked external data, or expected failures escaping the typed
+  channel.
+- **P1** — dependency drilling, hidden Layer requirements, duplicated
+  capabilities, manual shape discovery, unjustified assertions, pass-through
+  abstractions, or dishonest test substitutes.
+- **P2** — naming and co-location cleanup that belongs with a nearby change.
+
+For each finding, include:
+
+1. File, line, or symbol evidence.
+2. The hidden requirement or caller burden.
+3. The smallest target shape and its owner.
+4. Composition-root and testing impact.
+5. Behavior and modules that must remain unchanged.
+
+End with explicit keep decisions for pure functions, request values, framework
+boundaries, correctly separated ports and adapters, and services whose
+requirements already remain visible.

package/skills/effect-ts/SKILL.md

@@ -1,270 +1,35 @@
 ---
 name: effect-ts
-description: Use this skill whenever working in a repository that uses Effect, even if the current task is in a new file or the user does not explicitly ask for Effect help. Apply it to Effect patterns, services, layers, schemas, streams, runtimes, typed errors, DateTime, Effect Atom, observability, testing, HTTP, SQL, command-line scripts, project automation, and supporting tooling.
+description: Use this skill when setting up a repository that uses the Effect Typescript library.
 ---
 
-# Effect Expert
+# Step 1: Install effect
 
-Expert guidance for programming with the Effect library, covering error handling, dependency injection, composability, and testing patterns.
+Use the users preferred package manager:
 
-## Version Baseline
+```
+pnpm add effect@beta
+```
 
-This skill targets Effect v4. The guidance was last reviewed against
-`effect@4.0.0-beta.102` and the matching `@effect/*` v4 packages.
+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`.
 
-Before changing code, determine the version installed by the target repository.
-The target repository's manifest and lockfile are authoritative. Do not migrate
-or upgrade it merely to match this review baseline.
+```
+pnpm add -D effect@beta
+```
 
-Read `./references/version-and-source.md` before installing packages, resolving
-version-sensitive APIs, or using upstream source as evidence.
+# Step 2: Update AGENTS.md / CLAUDE.md
 
-## Research Strategy
+Ensure that the agent instructions contain the following:
 
-Effect has many ways to accomplish the same task. Proactively research best practices when working with Effect patterns, especially for moderate to high complexity tasks.
+```md
+# Learning more about the Effect
 
-Use the local guides in `./references/` first. They are the preferred source for best practices, conventions, and common implementation patterns.
+This repository uses the Effect Typescript library.
 
-Only go directly to the canonical Effect source when:
+Before writing any Effect code, first read `node_modules/effect/AGENTS.md`
+**completely**, and follow the links in the file when required.
 
-- the guides do not cover the question
-- you need exact API details or signatures
-- you need deeper implementation details
-- you need to verify a behavior against the source
-
-### Research Sources
-
-1. Local skill guides first. Start with the relevant files in `./references/`
-   before doing deeper research.
-2. Codebase patterns second. Examine similar patterns in the current project
-   before implementing. If Effect patterns already exist, follow them for
-   consistency unless they conflict with an explicit local policy in this
-   skill.
-3. Installed package source third. Use the target repository's resolved
-   `effect` and `@effect/*` packages for exact exports, declarations, and API
-   signatures.
-4. Version-matched upstream source last. For gaps in the guides, complex type
-   errors, unclear behavior, or implementation details, inspect the canonical
-   `Effect-TS/effect` source at the tag or commit matching the installed
-   version. A project-local source checkout is optional, never a prerequisite.
-
-### When To Research
-
-- Always research for services, layers, or complex dependency injection.
-- Always research for error handling with multiple error types or complex error hierarchies.
-- Always research for stream-based operations and reactive patterns.
-- Always research for resource management with scoped effects and cleanup.
-- Always research for concurrent or performance-critical code.
-- Always research for unfamiliar testing patterns.
-- Research when needed for complex refactors from promises or try/catch into Effect.
-- Research when needed for new service dependencies or layer restructuring.
-- Research when needed for custom error types or extensions of existing error hierarchies.
-- Research when needed for integrations with external systems such as databases, APIs, or third-party services.
-
-### Research Approach
-
-- Focus on canonical, readable, and maintainable solutions rather than clever optimizations.
-- Verify suggested approaches against existing codebase patterns when those
-  patterns exist.
-- When multiple approaches are possible, prefer the most idiomatic Effect
-  solution supported by the codebase, these local policies, and version-matched
-  Effect source.
-
-### Codebase Pattern Discovery
-
-When working in a project that uses Effect, check for existing patterns before implementing new code:
-
-1. Search for Effect imports and existing module usage to understand current conventions.
-2. Identify how services and layers are structured in the project.
-3. Note how errors are defined and propagated.
-4. Examine how Effect code is tested in the project.
-
-If no Effect patterns exist in the codebase, proceed using these guides and
-canonical patterns from version-matched Effect source and examples. Do not
-block on missing codebase patterns or a missing source checkout.
-
-### Feature Discovery
-
-When you need to discover available Effect modules, packages, or capabilities, search `./references/features.md` first.
-
-- Use it to identify the right package or module for a task.
-- Treat listed repo paths as discovery hints. Confirm them against the target
-  repository's installed version before relying on exact names or signatures.
-- Use it before inventing custom abstractions when Effect may already provide the functionality.
-
-### Guide Discovery
-
-When the task touches one of these areas, consult the matching guide before implementing:
-
-- `./references/guide-effect.md` for core `Effect` usage patterns, common constructors, composition, provisioning, and runtime boundaries
-- `./references/guide-error-handling.md` for defining errors, schema-based errors, failure handling, defects, and interrupts
-- `./references/guide-layers.md` for service ownership, service design, layer
-  construction, dependency visibility, composition, and provisioning
-- `./references/guide-observability.md` for `Effect.fn`, spans, structured
-  logging, metrics, annotations, and telemetry wiring
-- `./references/guide-retries.md` for retry policies, retry conditions, fallback strategies, and `ExecutionPlan`
-- `./references/guide-schedule.md` for retries, repeats, backoff, polling, cron, and schedule composition
-- `./references/guide-schema.md` for schema-first application modeling,
-  service contracts, transformations, unions, recursion, and branded types
-- `./references/guide-datetime.md` for current time, parsing, UTC and zoned
-  values, time zones, DST-safe arithmetic, formatting, Date interoperability,
-  and deterministic `TestClock` tests
-- `./references/guide-atom-data-fetching.md` for the core Effect Atom HTTP
-  data-fetching workflow, React hook choice, and action-lifetime ownership rules
-- `./references/atom-cache-lifecycle.md` for Effect Atom registry scope,
-  runtime memoization, families, TTL, SWR, polling, and aggregation resets
-- `./references/atom-http-and-invalidation.md` for `AtomHttpApi.Service`,
-  queries, mutations, reactivity keys, and invalidation
-- `./references/atom-tanstack-start.md` only for TanStack Start provider
-  placement, SSR isolation, hydration, and focus guidance
-- `./references/atom-testing.md` when adding or diagnosing deterministic Effect
-  Atom lifecycle tests
-- `./references/guide-sql.md` for Effect SQL usage, transactions, resolvers, schema-aware SQL, and migrations
-- `./references/guide-testing.md` for `@effect/vitest`, deterministic testing,
-  honest test Layers, property tests, and protocol round trips
-- `./references/guide-cli.md` for Effect-powered command-line scripts and
-  project automation
-- `./references/guide-http-boundaries.md` for `HttpApi` contracts, handlers,
-  DTOs, transport errors, and route boundaries
-- `./references/audit-services.md` for a complete service and type-boundary
-  audit workflow
-- `./references/guide-type-safety-and-boundaries.md` for `unknown`, assertions,
-  runtime shape checks, external decoding, and boundary ownership
-
-Treat each topic guide as the single authority for that topic. Do not skip the
-guides and jump straight to source unless source-level confirmation is needed
-or the guides do not answer the question.
-
-## Effect Principles
-
-Apply these core principles when writing Effect code.
-
-## Installation
-
-When installing Effect v4 packages in a user repository:
-
-- use the current `effect@beta` version only for a new v4 installation
-- preserve the repository's resolved v4 beta for existing installations unless
-  the user asks for an upgrade
-- keep `effect` and all v4 `@effect/*` packages on the exact same beta version
-- install only the packages needed for the user's runtime and actual task
-
-### Version Rules
-
-- `effect@latest` is still the v3 release line; use `effect@beta` when creating
-  a new v4 repository.
-- Resolve the beta tag at installation time. Do not assume the review baseline
-  is still current.
-- If you install any v4 `@effect/*` package, make sure it and `effect` use the
-  same exact beta version.
-- Do not mix v3 integration packages with Effect v4 packages.
-
-### Package Selection
-
-Choose packages based on the runtime and the work being done.
-
-- core library: `effect@beta`
-- Node.js runtime needs: install the matching `@effect/platform-node@beta`
-- browser runtime needs: install the matching `@effect/platform-browser@beta`
-- Bun runtime needs: install the matching `@effect/platform-bun@beta`
-- Vitest integration needs: install the matching `@effect/vitest@beta`
-- OpenTelemetry integration needs: install the matching
-  `@effect/opentelemetry@beta`
-
-Install additional `@effect/*` packages only when the user task actually needs them.
-
-### Practical Rule
-
-- start with the current resolved `effect@beta`
-- add matching v4 `@effect/*` packages only as needed by runtime and features
-- pin the full installed Effect v4 package set to the same exact beta
-
-### Error Handling
-
-- Use Effect's typed error system instead of throwing exceptions.
-- Define descriptive error types with proper error propagation.
-- Prefer `Schema.TaggedErrorClass` when the error can be schema-defined.
-- Use `Effect.fail`, `Effect.catchTag`, and `Effect.catch` for error control flow.
-
-### Dependency Injection
-
-- Implement dependency injection using services and layers.
-- Define services with `Context.Service`.
-- Compose layers with `Layer.merge` and `Layer.provide`.
-- Use `Effect.provide` to inject dependencies at the edge, avoid providing locally.
-- Keep services encapsulated; avoid exporting trivial accessor wrappers that only forward to one service method.
-
-### Composability
-
-- Leverage Effect composability for complex operations.
-- Use appropriate constructors such as `Effect.succeed`, `Effect.fail`, `Effect.tryPromise`, `Effect.try`, and `Effect.sync`.
-- Apply proper resource management with scoped effects.
-- Chain operations with `Effect.flatMap`, `Effect.map`, and `Effect.tap`.
-
-### Business Logic Functions
-
-- Prefer `Effect.fn` for reusable business-logic functions that return `Effect`.
-- Prefer `Effect.fn` over raw `Effect.gen` definitions even when the function takes no arguments.
-- If you do not want an explicit named span, use `Effect.fn` without a span name.
-- Do not use `Effect.fnUntraced` as the default.
-- Use `Effect.fnUntraced` only for edge cases with a concrete low-level reason, such as measured hot-path overhead.
-
-### TypeScript Preferences
-
-- Do not use `any` in Effect application, service, or workflow code.
-- Decode external values instead of asserting their shape.
-- Isolate unavoidable compiler or framework adapter assertions at the
-  narrowest boundary and document the contract they bridge.
-- Do not use `namespace` to hide services, layers, or mutable state.
-- Prefer correct typing, schema-driven decoding, narrowing, and proper generic constraints instead of forcing types.
-- If a value comes from an external boundary, validate or decode it instead of asserting its type.
-- If a type is hard to express, simplify the design or introduce a properly typed helper instead of using unsafe TypeScript.
-- For layers, do not hide them inside `namespace` blocks. Prefer either `static` members on the service class or plain exported layer constants.
-
-### Date and Time
-
-- Prefer Effect `DateTime` over vanilla JavaScript `Date` for application
-  logic. Keep `Date` as an interoperability type at external boundaries.
-- Use `DateTime.now` inside Effect programs so current time remains driven by
-  the `Clock` service and deterministic under `TestClock`.
-- Preserve the distinction between instants, zoned wall-clock values, and
-  date-only domain values.
-
-### Code Quality
-
-- Write type-safe code that leverages Effect's type system.
-- Use `Effect.gen` for readable sequential code.
-- Implement proper testing patterns using Effect testing utilities.
-- Prefer existing Effect primitives before introducing custom helpers.
-- Prefer `Schema.Class` / `Schema.TaggedClass` variants over plain `Schema.Struct` for named reusable schemas when possible.
-
-### Explaining Solutions
-
-When providing solutions, explain the Effect concepts being used and why they
-fit the specific use case. If you encounter patterns not covered in local
-references, prefer consistency with the codebase when possible and otherwise
-rely on installed declarations and version-matched canonical Effect source.
-
-## References
-
-- `./references/features.md`
-- `./references/guide-effect.md`
-- `./references/guide-error-handling.md`
-- `./references/guide-layers.md`
-- `./references/guide-observability.md`
-- `./references/guide-retries.md`
-- `./references/guide-schedule.md`
-- `./references/guide-schema.md`
-- `./references/guide-datetime.md`
-- `./references/guide-atom-data-fetching.md`
-- `./references/atom-cache-lifecycle.md`
-- `./references/atom-http-and-invalidation.md`
-- `./references/atom-tanstack-start.md`
-- `./references/atom-testing.md`
-- `./references/guide-sql.md`
-- `./references/guide-testing.md`
-- `./references/guide-cli.md`
-- `./references/guide-http-boundaries.md`
-- `./references/audit-services.md`
-- `./references/guide-type-safety-and-boundaries.md`
-- `./references/version-and-source.md`
+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 +1,4 @@
 interface:
-  display_name: "Effect Expert"
-  short_description: "Apply current Effect v4 patterns and tooling"
-  default_prompt: "Use $effect-ts to apply the relevant Effect architecture, DateTime, Atom, schema, service, error, testing, HTTP, SQL, observability, or CLI guidance."
+  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."

package/skills/testing/SKILL.md

@@ -21,3 +21,8 @@ Write a test only when every condition holds:
 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.