feat(dev): add effect ts skill

Author: skulidropek

.codex/skills/effect-ts-guide/SKILL.md

@@ -1,36 +1,75 @@
 ---
 name: effect-ts-guide
-description: Teach and apply Effect-TS practices (effect, @effect/schema, @effect/platform) for architecture, typed errors, Layers, dependency injection, resource safety, testing, and migration from async/await/Promise. Use when a user asks how to use Effect, requests best practices, wants to refactor to Effect, or needs mapping from platform modules to Node/Bun/Browser APIs.
+description: Effect-TS guidance for architecture, typed errors, Layers, boundary validation, resource safety, compliance checks, and editor tooling. Use when a task is explicitly about reviewing or implementing Effect or @effect/* application and library code, refactoring code to Effect, validating Effect-style conventions, or wiring Effect editor/language-service setup. Do not use for generic package publishing or plugin scaffolding tasks unless the code under review is the Effect code itself.
 ---
 
 # Effect TS Guide
 
-## Overview
+## Workflow
 
-Use this skill to teach Effect-TS fundamentals and best practices, then apply them to user code and architecture questions.
+1. Confirm the codebase or request is actually Effect-oriented. If it is not, stop and do not force this skill.
+2. Run the quick compliance check first:
 
-## Teaching workflow
+```bash
+SKILL_DIR=<directory containing this SKILL.md>
+bash "$SKILL_DIR/scripts/run-effect-ts-check.sh" .
+```
 
-1. Clarify context: runtime (node/bun/browser), goal (new app, refactor, review), and constraints.
-2. Separate core vs shell: identify pure domain logic vs effects and boundaries.
-3. Model errors and dependencies: define tagged error types and Context.Tag service interfaces.
-4. Compose with Effect: use pipe/Effect.gen, typed errors, and Layer provisioning.
-5. Validate inputs at boundaries with @effect/schema before entering core.
-6. Explain resource safety: acquireRelease, scoped lifetimes, and clean finalizers.
-7. Provide minimal, runnable examples tailored to the user context.
-8. If the user asks for version-specific or "latest" details, verify with official docs before answering.
+If the repository is mostly tooling, docs, or test fixtures for the checker itself, scope the command to the relevant Effect source directories instead of blindly linting the whole workspace.
 
-## Core practices (short list)
+3. For stricter product-code policy checks, run:
 
-- Use Effect for all side effects; keep core functions pure and total.
-- Avoid async/await, raw Promise chains, and try/catch in application logic.
-- Use Context.Tag + Layer for dependency injection and testability.
-- Use tagged error unions and Match.exhaustive for total handling.
-- Decode unknown at the boundary with @effect/schema; never leak unknown into core.
-- Use Effect.acquireRelease/Effect.scoped for resource safety.
-- Use @effect/platform services instead of host APIs (fetch, fs, child_process, etc.).
+```bash
+bash "$SKILL_DIR/scripts/run-effect-ts-check.sh" <effect-source-paths> --profile strict
+```
+
+4. If the repository wants the official Effect dprint formatting gate too, run:
+
+```bash
+bash "$SKILL_DIR/scripts/run-effect-ts-check.sh" <effect-source-paths> --profile strict-format
+```
+
+5. Fix the violations that are machine-detectable.
+6. Apply the manual rules from the references for architecture and style decisions.
+7. Re-run the relevant check before finishing.
+
+For editor integration tasks, treat `effect-ts-check` as the reusable CLI/compliance package and `@effect/language-service` plus VSCode settings/extensions as a separate setup concern.
+
+The skill is intentionally self-contained. Resolve `scripts/run-effect-ts-check.sh` relative to the skill directory so the same instructions work for standalone installs, repo-local skills, and plugin-contributed skills without hardcoding `~/.codex`.
+
+## What The Check Covers
+
+The compliance check is for fast, repeatable signals:
+
+- direct `async/await`
+- raw `Promise` usage
+- `try/catch` in product code
+- `switch`
+- `require`
+- common JavaScript and TypeScript module extensions, including `.jsx`, `.mts`, and `.cts`
+
+The `strict` profile also layers in unsafe host import checks, obvious typing-policy violations such as `any` and `ts-ignore`, direct `fetch`, eslint-disable hygiene, thrown-literal checks, and path-aware CORE boundary rules for casts, `unknown`, `catchAll`, CORE-to-SHELL imports, and runtime execution calls such as `Effect.runPromise` / `Effect.runSync`.
+
+The `strict-format` profile runs `strict` plus the official `@effect/dprint` formatting preset. Use it when formatting should be part of the compliance gate; use `strict` when you need semantic policy results without formatting noise.
+
+The wrapper uses `npx` with a bundled `effect-ts-check` tarball. It can run from a standalone skill install, but npm registry access or an npm cache is required for package dependencies.
+
+## What Still Needs Judgment
+
+The check does not replace architectural reasoning. Apply manual rules for:
+
+- CORE vs SHELL boundaries
+- typed error design
+- Layer and dependency injection shape
+- boundary decoding with `@effect/schema`
+- resource safety with `Effect.acquireRelease` and `Effect.scoped`
+- exhaustive handling of unions
+- project-specific service factories, local package boundaries, and allowed runtime entrypoint layouts outside the default CORE/SHELL convention
 
 ## References
 
-- Read `references/best-practices.md` for the extended checklist and examples.
-- Read `references/platform-map.md` when comparing @effect/platform to Node/Bun/Browser APIs.
+- [Best Practices](references/best-practices.md)
+- [Platform Map](references/platform-map.md)
+- [Lint Checks](references/lint-checks.md)
+- [Manual Writing Rules](references/manual-writing-rules.md)
+- [Editor Tooling](references/editor-tooling.md)

.codex/skills/effect-ts-guide/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Effect TS Guide"
+  short_description: "Effect-TS guidance, checks, and editor setup"
+  default_prompt: "Use $effect-ts-guide to review or implement Effect-TS code; run the bundled checker from the skill directory first."
+
+policy:
+  allow_implicit_invocation: true

.codex/skills/effect-ts-guide/assets/effect-ts-check/prover-coder-ai-effect-ts-check-0.1.0.tgz

@@ -1,71 +1,48 @@
-# Effect-TS Best Practices (concise)
+# Best Practices
 
-## Design principles
+## Core Principles
 
-- Keep core logic pure; isolate IO in a thin shell.
-- Model errors explicitly with tagged unions; avoid exceptions.
+- Keep core logic pure.
+- Keep IO in a thin shell.
+- Model errors explicitly with tagged unions.
 - Prefer immutable data and total functions.
 
 ## Composition
 
-- Use pipe + Effect.flatMap/map or Effect.gen for sequential flows.
-- Interop with Promise only at boundaries via Effect.try/Effect.tryPromise.
-- Use Match.exhaustive for union handling; avoid switch in domain logic.
+- Use `pipe`, `Effect.flatMap`, `Effect.map`, or `Effect.gen` for sequential flows.
+- Use `Match.exhaustive` for union handling.
+- Use `Effect.try` and `Effect.tryPromise` only at boundaries.
 
-## Dependency injection
+## Dependency Injection
 
-- Define services with Context.Tag and small interfaces.
-- Provide live layers at runtime; provide test layers in unit tests.
-- Keep service interfaces free of concrete implementations and globals.
+- Define services with `Context.Tag`.
+- Provide live layers at runtime.
+- Provide test layers in tests.
 
-## Boundary validation
+## Boundary Validation
 
-- Accept unknown at the boundary only.
-- Decode with @effect/schema and pass validated types into core.
-- Fail fast on invalid input; keep validation errors typed.
+- Accept `unknown` only at the boundary.
+- Decode with `@effect/schema`.
+- Pass validated values into core logic.
 
-## Resource safety
+## Resource Safety
 
-- Use Effect.acquireRelease for resources (connections, files, locks).
-- Use Effect.scoped to control lifetimes and ensure finalizers run.
+- Use `Effect.acquireRelease` for resources.
+- Use `Effect.scoped` for controlled lifetimes.
 
-## Platform usage
+## Platform Usage
 
-- Use @effect/platform services instead of host APIs:
-  - HttpClient/HttpServer for HTTP
-  - FileSystem/Path for files and paths
-  - Command/Terminal for CLI and processes
-  - KeyValueStore for local storage-like needs
-
-## Runtime and entrypoints
-
-- Use Effect.runMain (or platform runtime helpers) for application entry.
-- Use Logger/PlatformLogger for structured logging.
+- Prefer `@effect/platform` services over host APIs.
+- Use `HttpClient`, `FileSystem`, `Path`, `Command`, and `PlatformLogger` where appropriate.
 
 ## Testing
 
-- Write tests as Effects; provide test layers/mocks.
-- Use TestClock/Ref for deterministic time and state.
-- Use property-based tests for invariants when appropriate.
-
-## Minimal example (service + layer)
-
-```ts
-import { Context, Effect, Layer, pipe } from "effect"
-
-class Clock extends Context.Tag("Clock")<Clock, {
-  readonly nowMillis: Effect.Effect<number, never>
-}>() {}
-
-const ClockLive = Layer.succeed(Clock, {
-  nowMillis: Effect.sync(() => Date.now())
-})
+- Write tests as Effects.
+- Use test layers and mocks.
+- Add property-based tests when a rule should hold for many inputs.
 
-const program = pipe(
-  Clock,
-  Effect.flatMap((clock) => clock.nowMillis),
-  Effect.map((ms) => ({ now: ms }))
-)
+## Editor Setup
 
-const main = Effect.provide(program, ClockLive)
-```
+- Use `@effect/language-service` in `tsconfig.base.json` for editor diagnostics and Effect-aware suggestions.
+- Recommend the Effect VSCode extension alongside ESLint, but treat it as authoring support rather than a runtime or CI dependency.
+- Keep the editor language service separate from the reusable CLI compliance package.

.codex/skills/effect-ts-guide/references/best-practices.md

@@ -0,0 +1,23 @@
+# Editor Tooling
+
+## Scope
+
+- `@prover-coder-ai/effect-ts-check` is the reusable CLI/compliance package.
+- `scripts/run-effect-ts-check.sh` is the self-contained skill entrypoint for running that package before npm publish.
+- `@effect/language-service` is the editor-facing TypeScript plugin for Effect-aware diagnostics and suggestions.
+- VSCode integration is a separate setup layer, not part of the CLI package.
+
+## What To Mention
+
+- Add `@effect/language-service` to `tsconfig.base.json` `compilerOptions.plugins`.
+- Recommend the Effect VSCode extension `effectful-tech.effect-vscode` when the repo is used interactively in the editor.
+- Keep `dbaeumer.vscode-eslint` alongside the Effect extension so editor lint feedback matches the CLI package.
+- Keep ESLint and language-service responsibilities separate:
+  - ESLint/CLI catches repeatable policy violations.
+  - The language service improves editor diagnostics and suggestions.
+
+## Practical Guidance
+
+- If a task is about code quality enforcement in CI, use the CLI/package docs.
+- If a task is about authoring experience, completion, or diagnostics in the editor, use the editor tooling docs.
+- Do not describe the language service as a replacement for the CLI check.

.codex/skills/effect-ts-guide/references/editor-tooling.md

@@ -0,0 +1,69 @@
+# Lint Checks
+
+## Quick Command
+
+Run this first:
+
+```bash
+SKILL_DIR=<directory containing this SKILL.md>
+bash "$SKILL_DIR/scripts/run-effect-ts-check.sh" .
+```
+
+Resolve `scripts/run-effect-ts-check.sh` relative to the skill directory. The wrapper resolves the bundled `effect-ts-check` tarball without assuming a specific install location such as `~/.codex`.
+
+If the repository is mostly tooling, docs, or test fixtures for the checker itself, run the command only against the relevant Effect source paths instead of `.`.
+
+The wrapper installs the bundled tarball through `npx --package`, so npm registry access or a warm npm cache is required for the package dependencies.
+
+## Minimal Profile
+
+The minimal profile should catch the high-signal Effect violations:
+
+- `async` functions and `await`
+- raw `Promise` construction and `Promise.*`
+- `try/catch`
+- `switch`
+- `require`
+- common JavaScript and TypeScript module extensions, including `.jsx`, `.mts`, and `.cts`
+
+## Strict Profile
+
+The strict profile should add deeper policy checks:
+
+- direct host imports that bypass Effect platform services
+- obvious unsafe typing policy violations
+- safer handling around casts and `unknown`
+- direct `fetch` and other host API restrictions
+- eslint comment hygiene
+- thrown-literal checks
+- path-aware CORE/SHELL boundary checks
+
+The CORE/SHELL checks apply to `src/core/**` by default:
+
+- CORE must not import from SHELL.
+- `Effect.runPromise`, `Effect.runSync`, and `Effect.runSyncExit` are shell/runtime-boundary only.
+- `catchAll`, casts, and `unknown` are blocked in CORE, except casts are allowed in `src/core/axioms.ts`.
+
+## Strict Format Profile
+
+Use `--profile strict-format` when formatting should be part of the gate:
+
+```bash
+bash "$SKILL_DIR/scripts/run-effect-ts-check.sh" <effect-source-paths> --profile strict-format
+```
+
+This runs `strict` plus the official `@effect/dprint` preset. Keep it separate from `strict` when you need actionable semantic findings without formatting noise.
+
+Runtime execution boundaries outside the default `src/core/**` / `src/shell/**` convention still need manual review because the correct answer depends on the repository's entrypoint layout.
+
+## Editor Tooling Boundary
+
+- `effect-ts-check` is the reusable command-line compliance layer.
+- `@effect/language-service` and VSCode settings belong to the editor experience layer.
+- Do not expect the CLI to provide completion or hover behavior; that comes from the language service.
+
+## How To Use Results
+
+- Fix machine-detectable violations first.
+- Treat remaining issues as architecture or design decisions.
+- Do not use the lint output as a substitute for boundary modeling or type design.

.codex/skills/effect-ts-guide/references/lint-checks.md

@@ -0,0 +1,39 @@
+# Manual Writing Rules
+
+## Applicability Gate
+
+Only apply this skill when the task is explicitly Effect-related.
+
+## Architecture Rules
+
+- CORE must not depend on SHELL.
+- Effects belong in the shell or boundary layer.
+- Every external input should be decoded before entering core.
+- Every failure that matters should be typed.
+
+## Code Style Rules
+
+- Prefer `Effect.gen` for readable effect composition.
+- Prefer `Match.exhaustive` over `switch`.
+- Avoid `async/await` in product logic.
+- Avoid `try/catch` except at boundaries where you immediately convert to typed errors.
+- Avoid raw `Promise` chains.
+- Keep `Effect.runPromise`, `Effect.runSync`, and similar runtime execution calls in shell entrypoints.
+
+## Review Rules
+
+- If the code compiles but violates the architecture, call that out.
+- Separate machine-checkable issues from design issues.
+- If the one-command check passes, still inspect boundaries, error types, and resource lifetimes.
+
+## Response Rules
+
+- Be concrete about what should change.
+- Prefer minimal diffs.
+- Explain why a change preserves purity, typing, or boundary safety.
+
+## Editor Integration Rules
+
+- When the user asks about Effect editor support, mention both `@effect/language-service` and the VSCode extension.
+- Keep the explanation split between reusable compliance tooling and editor authoring setup.
+- If a repo already has CLI checks, do not imply the language service replaces them.

.codex/skills/effect-ts-guide/references/manual-writing-rules.md

@@ -1,41 +1,18 @@
-# @effect/platform map (what it replaces)
+# Platform Map
 
-## Core idea
+`@effect/platform` replaces host APIs with typed services and Layers.
 
-- @effect/platform provides platform-neutral service interfaces and Layers.
-- It does not monkey-patch globals; you must provide a platform layer.
+## Common Mappings
 
-## Implementation packages
+- `HttpClient` replaces `fetch`, `undici`, and `axios`
+- `FileSystem` replaces `fs` and `fs.promises`
+- `Path` replaces `node:path`
+- `Command` replaces `child_process`
+- `Runtime` replaces direct `process` handling
+- `PlatformLogger` replaces `console` for structured logging
 
-- Node: @effect/platform-node
-- Bun: @effect/platform-bun
-- Browser: @effect/platform-browser
+## Guidance
 
-## Common mappings
-
-- FileSystem -> node:fs / fs.promises / Bun file APIs
-- Path -> node:path / Bun path / Deno path
-- Command (+ CommandExecutor) -> child_process.spawn/exec / Deno.Command / Bun.spawn
-- Terminal -> process.stdin/stdout / readline
-- KeyValueStore -> Map / localStorage / file-backed KV
-- PlatformConfigProvider -> dotenv + process.env + file tree config
-- PlatformLogger -> console + file logging
-- Runtime/runMain -> manual main + process signal handling
-
-## HTTP stack
-
-- HttpClient -> fetch / undici / axios
-- FetchHttpClient -> fetch implementation
-- HttpServer/HttpRouter/HttpMiddleware -> node:http + express/fastify/koa
-- HttpApi/OpenApi -> manual route + schema + OpenAPI toolchain
-
-## Sockets and workers
-
-- Socket/SocketServer -> net / ws / WebSocket
-- Worker/WorkerRunner -> worker_threads / Web Workers
-
-## Data and utilities
-
-- Headers/Cookies/Multipart/Etag -> manual header/cookie parsing or third-party middleware
-- Url/UrlParams -> URL / URLSearchParams
-- Ndjson/MsgPack -> ad-hoc codecs or third-party libs
+- Prefer Effect platform services over host APIs.
+- Use host APIs only when no Effect replacement is needed and the boundary is already isolated.
+- Editor tooling such as `@effect/language-service` is not a runtime replacement for host APIs; it only improves authoring feedback.