@danieljvdm/dev-kit 0.2.0

package/skill-sources.lock.json

@@ -0,0 +1,136 @@
+{
+  "version": 1,
+  "sources": [
+    {
+      "id": "emilkowalski-skills",
+      "repository": "https://github.com/emilkowalski/skills.git",
+      "ref": "main",
+      "resolved": "70744e3816f1d93eafb697161a8b880a7384c5ff",
+      "skillsPath": "skills",
+      "include": [
+        "animation-vocabulary",
+        "apple-design",
+        "emil-design-eng",
+        "find-animation-opportunities",
+        "improve-animations",
+        "pick-ui-library",
+        "prototype",
+        "review-animations"
+      ],
+      "skills": [
+        "animation-vocabulary",
+        "apple-design",
+        "emil-design-eng",
+        "find-animation-opportunities",
+        "improve-animations",
+        "pick-ui-library",
+        "prototype",
+        "review-animations"
+      ],
+      "descriptions": {
+        "animation-vocabulary": "Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term (\"the bouncy thing when a popover opens\" → Pop in; \"the iOS rubber-band scroll\" → Rubber-banding). Use when the user asks \"what's it called when…\", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.",
+        "apple-design": "Apple's approach to interface design and fluid, physical motion, translated for the web. Use when building or reviewing gesture-driven UI, spring animations, drag/swipe/sheet interactions, momentum and interruptible transitions, translucent materials and depth, typography (optical sizing, tracking, leading), reduced-motion, or the design foundations (feedback, spatial consistency, restraint) behind Apple-style interfaces.",
+        "emil-design-eng": "This skill encodes Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great.",
+        "find-animation-opportunities": "Search a codebase or UI for places that don't animate but should, and reject everything that shouldn't. Read-only; it proposes motion with exact values, it does not implement it. Use when the user asks \"what could be animated here?\" or wants to \"make this feel more alive\". For fixing existing animations, use improve-animations or review-animations instead.",
+        "improve-animations": "Survey a codebase's animation and motion code as a senior motion advisor, then produce a prioritized audit and self-contained implementation plans for other agents (or cheaper models) to execute. Read-only on source code — it plans improvements, it does not apply them. Use when the user asks to \"improve the animations\", \"audit the motion\", \"make this app feel better\", or wants a roadmap of animation fixes rather than a review of a single diff.",
+        "pick-ui-library": "Pick the right library for a given frontend task from a curated, opinionated list — numbers, OTP inputs, charts, command menus, virtualization, drag and drop, toasts, state, styling, and more. Only runs when explicitly invoked; it does not trigger on its own.",
+        "prototype": "Build multiple genuinely different versions of a UI piece you describe, rendered behind a visual picker so you can flip through them live and promote the one that feels right. Only runs when explicitly invoked; it does not trigger on its own.",
+        "review-animations": "Reviews animation and motion code against a high craft bar derived from Emil Kowalski's design engineering philosophy. Default to flagging; approval is earned."
+      },
+      "digests": {
+        "animation-vocabulary": "sha256:d270769a8a19c8ff48489c118e19d5f86113c6acfdd0e981116ffd74b01b9e6b",
+        "apple-design": "sha256:dabc421a391bd6b2ba0d004a8f4d4a1b632fc003a45d4676ab9f2ade8099fc7b",
+        "emil-design-eng": "sha256:cedac6e0b7ff8ca471d5d2b35dc7d91f13b57ff57c4395822e677f0df7ecebc8",
+        "find-animation-opportunities": "sha256:0c6f5d397c01cb02b4fc06f45836825d5cb576c006e1a4d6eaa721f9f126835e",
+        "improve-animations": "sha256:b02183838b096282eef43bbcbdb85fd76cf0687dac188eff5174a3010f2b86ba",
+        "pick-ui-library": "sha256:f507c1caaff077d6c7f0aedf56a888ea0248894ad80b5bac4f279924db5f44a3",
+        "prototype": "sha256:564efd1ce0ee72520058eccb5f47d2f77b1ece27ae9b399edb7c121c8f9f2dd5",
+        "review-animations": "sha256:d78c312f4102c0243fb524f85d1fd999e8c413a5afbef9ac3c7fe054fbb84570"
+      },
+      "licensePath": "LICENSE",
+      "stripFrontmatter": [
+        "disable-model-invocation"
+      ]
+    },
+    {
+      "id": "cloudflare-skills",
+      "repository": "https://github.com/cloudflare/skills.git",
+      "ref": "main",
+      "resolved": "30553f89ae1ef1e3c2917cd09d72dac992bb4e9a",
+      "skillsPath": "skills",
+      "include": [
+        "agents-sdk",
+        "cloudflare",
+        "cloudflare-email-service",
+        "cloudflare-one",
+        "cloudflare-one-migrations",
+        "durable-objects",
+        "sandbox-sdk",
+        "turnstile-spin",
+        "web-perf",
+        "workers-best-practices",
+        "wrangler"
+      ],
+      "skills": [
+        "agents-sdk",
+        "cloudflare",
+        "cloudflare-email-service",
+        "cloudflare-one",
+        "cloudflare-one-migrations",
+        "durable-objects",
+        "sandbox-sdk",
+        "turnstile-spin",
+        "web-perf",
+        "workers-best-practices",
+        "wrangler"
+      ],
+      "descriptions": {
+        "agents-sdk": "Build AI agents on Cloudflare Workers using the Agents SDK. Load when creating stateful agents, durable workflows, real-time WebSocket apps, scheduled tasks, MCP servers, chat applications, voice agents, or browser automation. Covers Agent class, state management, callable RPC, Workflows, durable execution, queues, retries, observability, and React hooks. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.",
+        "cloudflare": "Comprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), feature flags (Flagship), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). Use for any Cloudflare development task. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.",
+        "cloudflare-email-service": "Send and receive transactional emails with Cloudflare Email Service (Email Sending + Email Routing). Use when building email sending (Workers binding or REST API), email routing, Agents SDK email handling, or integrating email into any app — Workers, Node.js, Python, Go, etc. Also use for email deliverability, SPF/DKIM/DMARC, wrangler email setup, MCP email tools, or when a coding agent needs to send emails. Even for simple requests like \"add email to my Worker\" — this skill has critical config details.",
+        "cloudflare-one": "Guides Cloudflare One Zero Trust and SASE work across Access, Gateway, WARP, Tunnel, Cloudflare WAN, DLP, CASB, device posture, and identity. Use when designing, configuring, troubleshooting, or reviewing Cloudflare One deployments. Retrieval-first: use current Cloudflare docs/API schemas instead of embedded product docs.",
+        "cloudflare-one-migrations": "Plans migrations from Zscaler ZIA/ZPA, Palo Alto, legacy VPN, SWG, or SASE stacks to Cloudflare One. Use for migration assessments, policy mapping, rollout plans, and parity/gap analysis.",
+        "durable-objects": "Create and review Cloudflare Durable Objects. Use when building stateful coordination (chat rooms, multiplayer games, booking systems), implementing RPC methods, SQLite storage, alarms, WebSockets, or reviewing DO code for best practices. Covers Workers integration, wrangler config, and testing with Vitest. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.",
+        "sandbox-sdk": "Build sandboxed applications for secure code execution. Load when building AI code execution, code interpreters, CI/CD systems, interactive dev environments, or executing untrusted code. Covers Sandbox SDK lifecycle, commands, files, code interpreter, and preview URLs. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.",
+        "turnstile-spin": "Set up Cloudflare Turnstile end-to-end in a project. Scan the codebase, create the widget via the Cloudflare API, embed it where user requests need bot verification (form submissions, SPA actions, API endpoints, download links, comment or vote submissions, etc.), wire canonical server-side siteverify in the customer's existing backend, validate, and persist the skill. Load this when a user asks to add Turnstile, set up CAPTCHA, protect a form or endpoint from bots, or fix a Turnstile integration. Mirrors developers.cloudflare.com/turnstile/spin.",
+        "web-perf": "Analyzes web performance using Chrome DevTools MCP. Measures Core Web Vitals (LCP, INP, CLS) and supplementary metrics (FCP, TBT, Speed Index), identifies render-blocking resources, network dependency chains, layout shifts, caching issues, and accessibility gaps. Use when asked to audit, profile, debug, or optimize page load performance, Lighthouse scores, or site speed. Biases towards retrieval from current documentation over pre-trained knowledge.",
+        "workers-best-practices": "Reviews and authors Cloudflare Workers code against production best practices. Load when writing new Workers, reviewing Worker code, configuring wrangler.jsonc, or checking for common Workers anti-patterns (streaming, floating promises, global state, secrets, bindings, observability). Biases towards retrieval from Cloudflare docs over pre-trained knowledge.",
+        "wrangler": "Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. Load before running wrangler commands to ensure correct syntax and best practices. Biases towards retrieval from Cloudflare docs over pre-trained knowledge."
+      },
+      "digests": {
+        "agents-sdk": "sha256:721bd3f54bf45ce35827d90a1886ed92d644fe2bfff2e80c21bcd1777079dc54",
+        "cloudflare": "sha256:dfc92bac99350aa358617e0b8edd61fd7115cbf1a873ba01d32f93d967b9822e",
+        "cloudflare-email-service": "sha256:c74226f6ce9226640193a30142a2d5348cc276baefb91913db9dc44e97d971c0",
+        "cloudflare-one": "sha256:44c1455ac02448fab391795a7d84205387c3cdae457e3d17d5549207ff466bfa",
+        "cloudflare-one-migrations": "sha256:9b1e197c3cf33fd7061d5f7c2e654a9b72257ed2169d57b704bca4122a51febc",
+        "durable-objects": "sha256:533bfa75d2074cf6ac30ab77854a665465318dd0540ff4bdbb9c5f4ef8acfb38",
+        "sandbox-sdk": "sha256:e1ec676cfa5e9638f62673097850ec0e8e7f7e42dfd0606cc217b5854df0132b",
+        "turnstile-spin": "sha256:c6095261a7f69b2321729604a8f57b36456146fa6e544bfc54d764d206c1037a",
+        "web-perf": "sha256:4d6d66e3d36bee3f592a8ac76ec633c6a96c688c0c9767ef26c164f2509726a8",
+        "workers-best-practices": "sha256:f8925cccde1682df5e6c9aba8e3ee125355fc73761ba6581107d88adb8b44f47",
+        "wrangler": "sha256:217184cf167933b565466cf0d846e8085e8a985d6b7ff828316757d3fc4932cb"
+      },
+      "licensePath": "LICENSE"
+    },
+    {
+      "id": "evanbacon-serve-sim",
+      "repository": "https://github.com/EvanBacon/serve-sim.git",
+      "ref": "main",
+      "resolved": "14ad57ff922551bf7be81e907ddfcfa6191e64f2",
+      "skillsPath": "skills",
+      "include": [
+        "serve-sim"
+      ],
+      "skills": [
+        "serve-sim"
+      ],
+      "descriptions": {
+        "serve-sim": "Control and stream a running iOS, iPad, or Apple Watch Simulator with npx serve-sim. Use for simulator preview, taps, gestures, hardware buttons, rotation, camera injection, permissions, accessibility, and CoreAnimation debug."
+      },
+      "digests": {
+        "serve-sim": "sha256:782f41d4d79100d5bfc9ec1211e5d4766e978299bbb93fd8e34c6f8d2ecf2114"
+      },
+      "licensePath": "LICENSE"
+    }
+  ]
+}

package/skills/dev-kit/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: dev-kit
+description: Dev-kit operations for projects that configure dev-kit.jsonc, sync portable skills, run plan/apply or locked postinstalls, maintain dev-kit.lock.json, resolve ownership conflicts, patch managed ignores, 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.
+
+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 `dev-kit.jsonc`, `dev-kit.lock.json` when
+   present, `package.json`, and the configured target paths. Finish with the
+   intended skill selection, targets, and setup tasks identified.
+2. Update `dev-kit.jsonc`. Preserve JSONC comments and validate against the
+   package schema. Finish when every desired resource is represented once.
+3. Run `dev-kit plan`. Use `--manifest`, `--project-dir`, or `--lockfile` when
+   the project overrides their defaults. Planning is read-only; inspect every
+   create, update, remove, adoption, and conflict before proceeding. Finish
+   when the plan contains only intended actions and understood conflicts.
+4. 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.
+5. Use `dev-kit apply --locked` in CI and the package lifecycle. 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`. Include this skill as `dev-kit` when project agents should carry the
+toolkit procedure.
+
+```jsonc
+{
+  "$schema": "./node_modules/@danieljvdm/dev-kit/schema/dev-kit.schema.json",
+  "include": ["dev-kit", "effect"],
+  "exclude": [],
+  "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.
+
+## Ownership and conflicts
+
+Dev-kit adopts an existing destination only when its digest exactly matches a
+committed lock entry. Local receipts authorize later updates and cleanup only
+while the managed output still matches its recorded digest.
+
+Preserve a conflicting path and inspect it:
+
+- For an unknown destination, choose a different target or deliberately move
+  the user-owned content before applying.
+- For a modified managed destination, reconcile the local edits or restore its
+  recorded content before applying.
+- For a locked-plan mismatch, run an unlocked apply only when intentionally
+  updating desired state, review the new lock, and commit 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.
+
+For one lifecycle entry point, configure:
+
+```jsonc
+{
+  "scripts": {
+    "postinstall": "dev-kit apply --locked"
+  }
+}
+```
+
+## 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. `dev-kit plan` validates these 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.
+
+## Current boundary
+
+Manage skill outputs, the `setup.effectSource` checkout, and the explicit
+`setup.effectTsgo` task. Edit shared `package.json` and `tsconfig.json`
+contributions deliberately. Treat named bundles, Oxlint/Oxfmt presets, and
+broader setup tasks as future manifest capabilities until the installed CLI
+exposes them.

package/skills/dev-kit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Dev Kit"
+  short_description: "Configure and apply portable project tooling"
+  default_prompt: "Use $dev-kit to configure and safely apply this project's development toolkit."

package/skills/effect-ts/SKILL.md

@@ -0,0 +1,242 @@
+---
+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, observability, testing, HTTP, SQL, command-line scripts, project automation, and supporting tooling.
+---
+
+# Effect Expert
+
+Expert guidance for programming with the Effect library, covering error handling, dependency injection, composability, and testing patterns.
+
+## Version Baseline
+
+This skill targets Effect v4. The guidance was last reviewed against
+`effect@4.0.0-beta.102` and the matching `@effect/*` v4 packages.
+
+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.
+
+Read `./references/version-and-source.md` before installing packages, resolving
+version-sensitive APIs, or using upstream source as evidence.
+
+## Research Strategy
+
+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.
+
+Use the local guides in `./references/` first. They are the preferred source for best practices, conventions, and common implementation patterns.
+
+Only go directly to the canonical Effect source when:
+
+- 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-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.
+
+### 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-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`

package/skills/effect-ts/UPSTREAM.md

@@ -0,0 +1,28 @@
+# Upstream Baseline
+
+The general Effect guides in this skill were adapted from
+[`Effect-TS/skills`](https://github.com/Effect-TS/skills) at commit
+`a8b6bb40d1d4d550b49c0ff7a624b5e6da500a24`.
+
+They have been modified to:
+
+- remove the mandatory `.repos/effect` checkout
+- target the current canonical `Effect-TS/effect` v4 source
+- update version-sensitive guidance from the upstream beta.66 snapshot to
+  beta.102
+- preserve this repository's service ownership, layer construction,
+  schema-first modeling, type-boundary, HTTP, testing, logging, audit, and CLI
+  conventions
+
+## Local Authoring Checkout
+
+This repository keeps an ignored, version-matched Effect checkout for
+validating source paths and beta-sensitive APIs. `vp i` runs the equivalent
+dev-kit setup automatically; it can also be invoked directly:
+
+```bash
+./bin/dev-kit.mjs effect sync
+```
+
+Update the checkout, package dependencies, review baseline, feature index, and
+stale-API tests together when moving to a newer Effect beta.

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

@@ -0,0 +1,5 @@
+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, schema, service, error, testing, HTTP, SQL, observability, or CLI guidance."
+