@deslop/coding-standards 0.0.0-stage → 0.1.761

package/skills/engineering/SKILL.md

@@ -0,0 +1,562 @@
+---
+name: engineering
+description: 'Engineering rules for product code, paired with the shared lint. Use before designing or editing code, writing tests, or reviewing a diff.'
+---
+
+**Scope.** Apply these rules and repository-specific CODING_STANDARDS.md. CLI-installed copies are read-only; improve their package source, then refresh through the CLI.
+
+**Sources.** Match manifest/lock versions; inspect cloned upstream and nearest usage, never node_modules. Library APIs do not define coding policy.
+
+**Diagnostics.** Use the shown idiom, not casts, weakened rules or a rewrite trading one diagnostic for another.
+
+## Simplicity
+
+**Clarity.** Plain, explicit, idiomatic code, names and files; read top to bottom without commentary or cleverness.
+
+- **Requested only.** Build the smallest thing that does the requested job well and touch only what the request needs; an unrelated improvement is listed for the user. A refactor or cleanup request asks for depth instead: every rule applies to every line of the owned files.
+- **Inward layers.** Domain and service code never import HTTP, RPC, or other transport types.
+- **Building blocks.** Offer services, Layers, and functions the caller composes like any Effect module, never a wrapper that bundles them behind one call such as `serve(app)`.
+- **No machinery.** Behave correctly instead of building hooks, guards, or generators to enforce behavior.
+- **Behavior kept.** A refactor keeps behavior at every usage point. Two differences are accepted and reported with the change: one no usage point observes that makes the code simpler, and one a rule here causes, such as an error keeping its cause or sorted keys, unless a usage point parses it; printed diagnostics are not a contract. Any other behavior change is the user's decision, except a reachable bug's fix.
+- **Reachable bugs.** A bug a real input from a usage point triggers is fixed and reported, with every consumer of the changed output checked. Handling for input no caller produces is deleted; anything that looks intentional or that other code relies on is kept and reported as possibly intentional.
+- **Performance.** Improve performance in the touched code where you know how; measure on a realistic input only when a change claims speed or keeps a slower-looking form. Diagnose at the layer that owns the symptom: distributed spans for RPC/backend dependencies, React commits for rerenders, a browser performance profile for main-thread work. Correlate one real action before changing code, then repeat it on the fix; neither a screenshot nor a service name proves latency or trace coverage. Use the repository's instrumentation and the tool's help; profiling is not a ritual on every change.
+- **Type safety.** A fix never weakens types to make a symptom go away: no widened or erased type, cast, dropped generic, or loosened exported type.
+- **Domain.** Implement the definition the domain uses, such as a cycle for recursion, never the nearest syntactic proxy.
+- **Reread.** Before finishing, reread the diff and delete every line the outcome does not require.
+
+**Happy path.** Failures flow through the error channel: no catch, retry, fallback, backup, or defensive check unless the request or an existing contract needs it.
+
+**Trusted data.** Validate and transform once, at the boundary, with Effect Schema; inside, carry narrowed values forward and never re-check what the schema, the declared type, an earlier filter, or every caller guarantees.
+
+```ts
+// good
+const add = Effect.fn('Ledger.add')(function* (draft: LedgerDraft) {
+	yield* Ref.update(entries, Array.append(draft))
+})
+// bad
+Schema.decodeEffect(LedgerDraft)(draft) // draft is already a LedgerDraft
+variable.init?.type === 'TSSatisfiesExpression' // init was already narrowed to non-null
+```
+
+**Effect first.** Search matching cloned Effect modules before hand-writing traversal, state, configuration or platform operations. Replace dependencies covered by Effect or its platform adapters.
+
+```ts
+// good
+const cycles = Graph.stronglyConnectedComponents(graph)
+BigDecimal.format(amount)
+Duration.parts(DateTime.distance(oldest.timestamp, newest.timestamp)).days
+fs.glob('**/.env*.example', {exclude: ['**/node_modules'], root: config.cwd})
+// bad
+const digits = BigDecimal.scale(BigDecimal.abs(amount), 2).value.toString().padStart(3, '0')
+Math.floor(Duration.toDays(DateTime.distance(oldest.timestamp, newest.timestamp)))
+import {glob} from 'glob' // a dependency Effect's FileSystem replaces
+```
+
+**Whole values.** Pass whole values or spread them. No parameter/callback/loop destructuring except useState and component ref; project fields only to exclude data the recipient must not receive.
+
+```ts
+// good
+server => ({server: {...server, forwardConsole: true, warmup}})
+for (const schema of schemas) report(schema.name)
+Record.map(groups, entries => entries.length)
+upload({scope: input.scope, type: input.type}) // input also holds the bearer token
+// bad
+({host, port}) => ({server: {forwardConsole: true, host, port, warmup}})
+server: {forwardConsole: true, host: config.host, port: config.port, warmup}
+for (const {name} of schemas) report(name)
+Array.map(Record.toEntries(groups), ([key, entries]) => entries.length)
+```
+
+**Nearest sibling.** Extend the nearest implementation; match permissions, errors, refresh and tests. Reuse its helpers and change only affected state.
+
+**Once.** Extract repeated logic once; one fact has one owner.
+
+```ts
+// good
+const sandboxGone = Effect.mapError(cause => SandboxError.make({cause, message: 'The sandbox is gone'}))
+// bad — the same mapping written in three handlers
+pipe(
+	sandbox.exec(input),
+	Effect.mapError(cause => SandboxError.make({cause, message: 'The sandbox is gone'}))
+)
+pipe(
+	sandbox.read(path),
+	Effect.mapError(cause => SandboxError.make({cause, message: 'The sandbox is gone'}))
+)
+```
+
+**Canonical data.** Store/send canonical data, derive display values, expose each state once and remove states no caller produces.
+
+**One way.** Replace superseded paths; no duplicate/subset/superset fields, methods, options or exports.
+
+**No compatibility.** Rename the shape and every caller together. No alias, fallback, deprecated path or flag unless a documented/user-named contract requires it.
+
+**Present needs.** No speculative option, abstraction, layer, export, file or check. Configure only what callers vary.
+
+**Dead code.** Every superseded or unused file, export, type, branch, config, validation, doc, test, and dependency goes in the same change.
+
+## Lint pairs
+
+The forms below are the ones lint enforces without an autofix, and the single form that satisfies every rule involved.
+
+**Fallback.** A default is `??`; never a ternary on the same value.
+
+```ts
+// good
+const root = options?.root ?? '.'
+// bad — no-negated-condition flips it, then prefer-nullish-coalescing flags it
+const root = options?.root !== undefined ? options.root : '.'
+```
+
+**Conditions.** A boolean is tested bare; `=== true` only on a value that may be undefined.
+
+```tsx
+// good
+if (enabled) return
+aria-current={props.selected === true ? 'page' : undefined}
+// bad
+if (enabled === true) return // enabled is a boolean
+if (props.selected) return // props.selected may be undefined
+```
+
+**Flat.** Use early-return statements in Effect.fn. No nested ternaries or combinators deeper than equivalent statements. Match/combinators serve single expressions; Boolean.match selects a value, except one-line JSX-attribute ternaries.
+
+```ts
+// good
+const kill = Effect.fn('Sandbox.kill')(function* (sandbox?: Sandbox) {
+	if (sandbox?.status !== 'running') return
+
+	yield* sandbox.kill
+})
+Boolean.match(ignoreCase, {onFalse: () => undefined, onTrue: () => 'i'})
+// bad
+const type = event.type === 'text-delta' ? 'text' : event.type === 'reasoning-delta' ? 'reasoning' : 'unknown'
+const flags = ignoreCase ? 'i' : undefined // "instead of a ternary the Boolean.match would be cleaner"
+// bad
+Array.appendAll(
+	base,
+	Boolean.match(hasTools, {
+		onFalse: () => [],
+		onTrue: () =>
+			pipe(
+				tools,
+				Array.map(tool => pipe(tool, Option.toArray))
+			)
+	})
+)
+```
+
+**Choices.** `Match` for a union, never `switch`.
+
+```ts
+// good
+pipe(
+	Match.value(usage.kind),
+	Match.when('input', () => 'in'),
+	Match.when('output', () => 'out'),
+	Match.exhaustive
+)
+// bad
+switch (usage.kind) {
+	case 'input':
+		return 'in'
+}
+```
+
+**Options.** Use Option operators, never .value. Use Option where it composes; keep plain optional values otherwise. This is our convention, not a claim narrowing is unsafe.
+
+```ts
+// good
+Option.map(Number.parse(event.target.value), field.handleChange)
+Option.map(Array.head(parts), part => part.text)
+// bad
+if (Option.isSome(open)) open.value.append(event.delta)
+const parsed = Option.getOrUndefined(Number.parse(event.target.value))
+```
+
+**Handlers.** A handler used once is an arrow in place; a handler used twice is a `function`.
+
+**Pairs.** A tuple stays whole, read by index.
+
+**Accumulators.** No `let`: a fold or an Effect collection operation that says what it selects.
+
+```ts
+// good
+const total = Array.reduce(values, 0, Number.sum)
+pipe(teamId, String.split(','), Array.map(String.trim), Array.findFirst(String.isNonEmpty))
+Array.filterMap(items, item => (supports(item) ? Result.succeed(item.value) : Result.failVoid))
+// bad
+let total = 0
+for (const value of values) total += value
+const [first] = teamId
+	.split(',')
+	.map(value => value.trim())
+	.filter(value => value.length > 0)
+items.filter(item => supports(item)).map(item => item.value)
+```
+
+**Natives.** Use Effect modules instead of globals/native methods. Third-party-owned methods stay, with an inline diagnostic disable and reason when needed.
+
+```ts
+// good
+Number.parse(input.count)
+Predicate.isString(value)
+Predicate.isNotNullish(annotation)
+Array.isReadonlyArrayEmpty(node.arguments)
+String.isNonEmpty(event.delta)
+Array.get(items, 0)
+const serve = Effect.gen(function* () {
+	const start = yield* Clock.currentTimeMillis
+	const host = yield* pipe(Config.String('HOST'), Config.withDefault('0.0.0.0'))
+	const password = yield* Config.Redacted('SMTP_PASS')
+	yield* Effect.sleep(Duration.millis(delay))
+	return {host, password, start}
+})
+// bad
+parseInt(input.count)
+typeof value === 'string'
+annotation !== null && annotation !== undefined
+node.arguments.length === 0
+Effect.promise(() => new Promise(resolve => setTimeout(resolve, delay)))
+process.env.HOST ?? '0.0.0.0'
+```
+
+**Pipe.** A standalone `pipe`, nested at most three deep; never the `.pipe` method.
+
+**Failures.** In a generator a failure is `return yield* E.make(...)`; outside one, `Effect.fail`.
+
+```ts
+// good
+const text = Effect.fn('Ai.text')(function* (response: AiResponse) {
+	if (response.status === 'refused') return yield* AiError.make({message: 'The model refused the prompt'})
+
+	return response.text
+})
+// bad
+const text = Effect.fn('Ai.text')(function* (response: AiResponse) {
+	if (response.status === 'refused') yield* Effect.fail(AiError.make({message: 'The model refused the prompt'}))
+	if (response.status === 'refused') throw new Error('The model refused the prompt')
+	return response.text
+})
+```
+
+**Casts.** No `as`, `any`, or `unknown` annotation: decode unknown data once with a schema at the boundary; `satisfies` and `as const` are the only assertions.
+
+```ts
+// good
+const params = Schema.decodeUnknownOption(Schema.Record(Schema.String, Schema.Unknown))(part.params)
+return Effect.succeed([{text: part.text, type: 'text'} satisfies TextContent])
+// bad — a cast satisfies one rule and the next flags it
+const params = part.params as Record<string, unknown>
+create: Effect.fnUntraced(function* (input: unknown) {
+```
+
+**Decoders.** `Schema.decodeUnknownEffect` only for `unknown` input; typed input uses `Schema.decodeEffect`, and JSON text goes through `Schema.fromJsonString`.
+
+```ts
+// good
+const load = Effect.fn('Plugin.load')(function* (path: string) {
+	const endpoint = yield* Schema.decodeEffect(Endpoint)(config.endpoint)
+	const manifest = yield* Schema.decodeEffect(PackageManifest)(yield* fs.readFileString(path))
+	return {endpoint, manifest}
+})
+// bad
+Schema.decodeUnknownEffect(Endpoint)(config.endpoint) // config.endpoint is a string
+JSON.parse(text)
+```
+
+**Imports.** Keep module names; only generated shadcn aliases differ. Separate type imports; packages, blank line, then # aliases. Every export has a consumer.
+
+```ts
+// good
+import {Effect, Schema} from 'effect'
+import type {Plugin} from 'vite'
+
+import type {PortfolioState} from '#rpcs/contracts.ts'
+// bad — each line is a diagnostic
+import {Schema as S} from 'effect'
+import {type Plugin, createServer} from 'vite'
+export const EntryKind = Schema.Literals(['income', 'expense']) // no importer
+```
+
+**Readonly.** Every property of a service shape is readonly, as in Effect's services, and so may class members be; readonly appears nowhere else, except on a `Schema.suspend` cycle's hand-written types.
+
+**Disables.** Fix the idiom or reproduce a rule defect. Inline disables require an unavoidable conflict and -- reason; never disable ordering or weaken file configuration. Report dependency-only diagnostics; rename filename violations.
+
+```ts
+// good
+// oxlint-disable-next-line typescript/consistent-type-definitions -- TanStack Router augments this interface by name.
+// @effect-diagnostics-next-line nodeBuiltinImport:off -- Vite's plugin API hands over a Node server.
+// bad
+"exactOptionalPropertyTypes": false
+// oxlint-disable-next-line typescript/consistent-type-assertions
+// oxlint-disable-next-line sort-keys -- keeps the printed order
+// bad
+files: ['packages/components/src/components/agent-browser.tsx', 'packages/components/src/components/form.tsx'],
+```
+
+## Effect
+
+**Functions.** Traced argument boundary: Effect.fn('Name.method'). Internal helper: Effect.fnUntraced. Argument-free multi-statement effect: Effect.gen; one statement: the effect. Annotated return: Effect.fn.Return.
+
+```ts
+// good
+const prompt = Effect.fn('Ai.prompt')(function* (message: Prompt.UserMessage): Effect.fn.Return<void, AiError> {
+	const input = yield* piUserMessage(message)
+	yield* send(input)
+})
+const decodePart = Effect.fnUntraced(function* (part: Part) {
+	return yield* Schema.decodeEffect(Event)(part)
+})
+const stop = Effect.gen(function* () {
+	yield* setStatus('stopping')
+	yield* kill
+})
+const restart = setStatus('starting')
+// bad
+fetch: url => Effect.tryPromise(() => fetch(url))
+const decodePart = Effect.fn('decodePart')(function* (part: Part) {}) // a span on an internal helper
+const stop = Effect.gen(function* () {
+	yield* setStatus('stopping')
+}) // one statement
+```
+
+**Errors.** One domain error per service; preserve cause, redact secrets, map in Effect.fn's pipeline argument. Map SDK unknown errors at the adapter. No catch/retry/fallback without a required contract.
+
+```ts
+// good
+export class AiError extends Schema.TaggedError<AiError>()('AiError', {
+	cause: Schema.optional(Schema.Defect()),
+	message: Schema.String
+}) {}
+const prompt = Effect.fn('Ai.prompt')(
+	function* (message: Prompt.UserMessage) {
+		yield* send(message)
+	},
+	Effect.mapError(cause => AiError.make({cause, message: 'Cannot prompt the agent'}))
+)
+const pages = Effect.tryPromise({
+	catch: cause => NotionError.make({cause, message: 'Cannot list pages'}),
+	try: () => client.pages.list()
+})
+Effect.mapError(cause => WorkspaceError.make({cause: Redacted.make(cause), operation: 'exec input'}))
+Effect.tapError(() => cleanup)
+// bad
+pipe(
+	fs.readFileString(target),
+	Effect.catch(() => Effect.succeed(''))
+)
+pipe(loadConfig, Effect.retry(Schedule.recurs(3)))
+Effect.mapError(failure => new LedgerError({reason: failure.message})) // cause dropped, new
+Effect.catch(error => pipe(cleanup, Effect.andThen(Effect.fail(error)))) // fails again with the error it caught
+load: (path: string) => Effect.Effect<void, PlatformError | Schema.SchemaError> // library failures leak from the service
+```
+
+**Services.** Inline a sole implementation in its Layer; name layers for multiple backends. Defaults use Context.Reference. Implement with Service.of or satisfies; service methods are readonly properties.
+
+```ts
+// good
+export class Ledger extends Context.Service<Ledger, Ledger.Shape>()('@app/ledger/service/Ledger') {
+	static readonly layer = Layer.effect(
+		this,
+		Effect.gen(function* () {
+			const entries = yield* Ref.make(Array.empty<LedgerEntry>())
+			return Ledger.of({add: add(entries), balanceByTag: balanceByTag(entries)})
+		})
+	)
+}
+export class Ai extends Context.Service<Ai, Ai.Agent>()('@app/ai/service/Ai') {
+	static layerPi(config: Pi.Config) {
+		return Layer.effect(this, makePi(config))
+	}
+}
+export const Verbose = Context.Reference<boolean>('@app/ai/Verbose', {defaultValue: () => false})
+// bad
+class Logger extends Context.Service<Logger>()('Logger', {make: Effect.succeed(service)}) {}
+static readonly layer = Layer.effect(Ledger, makeLedger) // a make with one caller
+query(sql: string): Effect.Effect<Rows> // a method signature instead of a readonly property
+```
+
+**Primitives.** Use Effect's primitives directly; rpcs and services already trace, and one scope owns each lifetime.
+
+```ts
+// good
+const connect = Effect.gen(function* () {
+	const state = yield* SubscriptionRef.make(PortfolioState.make({}))
+	const socket = yield* Effect.acquireRelease(openSocket, closeSocket)
+	return {socket, state}
+})
+// bad
+class State {
+	update(f: (s: PortfolioState) => PortfolioState) {
+		return SubscriptionRef.update(this.ref, f)
+	}
+}
+const traced = Effect.withSpan('Notes.create')(notes.create(input))
+Effect.addFinalizer(() => closeSocket(socket)) // acquisition and release with different owners
+```
+
+**Runtime.** The owned runtime runs the program; a Promise an external contract demands is bridged once, where it is returned.
+
+```ts
+// good
+NodeRuntime.runMain(program)
+health: flow(rpc.health, Effect.runPromiseWith(Context.empty())),
+// bad
+const runtime = ManagedRuntime.make(AppLayer)
+const run = <A, E>(effect: Effect.Effect<A, E>) => Effect.runPromise(effect)
+```
+
+**Sorting.** `Order` for sorting, `Result` for a fallible pure value.
+
+```ts
+// good
+Array.sort(
+	entries,
+	Order.mapInput(Order.Number, entry => entry.tokens)
+)
+Result.fromOption(Array.head(parts), () => AiError.make({message: 'The model returned no parts'}))
+// bad
+entries.sort((left, right) => left.tokens - right.tokens)
+```
+
+## Types and Schema
+
+**Inference.** Infer types. Annotate recursion or branches TypeScript cannot unite; use schema types/indexed members in signatures. Keep intentional widening, not repeated inferred generics.
+
+```ts
+// good
+const balances = Array.reduce(decoded, HashMap.empty<Tag, BigDecimal.BigDecimal>(), sumByTag)
+const label = MutableRef.make('') // the initializer infers string, not just ''
+const [status, setStatus] = useState<'idle' | 'running'>('idle') // intentional widening
+function visit(node: Node): Result {
+	return visit(node.parent)
+}
+function settle(amount: LedgerEntry['amount']) {
+	return BigDecimal.format(amount)
+}
+export type Sandbox = ReturnType<typeof fromSdk>
+// bad
+const Input = Schema.Struct({value: Schema.String}) satisfies Schema.Schema<Input>
+const label = MutableRef.make<string>('') // repeats the inferred type
+export type SandboxLike = {id: string; renew: (seconds: number) => Promise<unknown>} // a copy of an inferred shape
+```
+
+**Schema pairs.** Type pair immediately before every schema. Structs use Schema.Struct, never Schema.Class; reuse fields by spreading. Call schema.make directly for validation/defaults.
+
+```ts
+// good
+export type LedgerDraft = typeof LedgerDraft.Type
+export const LedgerDraft = Schema.Struct({...LedgerEntry.fields, id: Schema.optionalKey(Schema.NonEmptyString)})
+RunEventCursor.make(value.toString())
+trails: pipe(Schema.Array(PortfolioTrail), Schema.withConstructorDefault(Effect.succeed([])))
+// bad
+export type EntryDraft = {amount: EntryAmount; id?: EntryId; tag: string} // a hand-written shape beside the schema
+// bad
+new AiError({message: 'The model returned no text'}) // the schema has make
+function cursorFromBigInt(value: bigint) {
+	return RunEventCursor.make(value.toString())
+}
+payload: Schema.Struct(pipe(PortfolioVisitor.fields, Struct.pick(['color', 'id', 'name', 'x', 'y']))) // the schema itself fits
+```
+
+**Cycles.** Handwrite each recursive-cycle type; annotate only Schema.suspend thunks. Noncycle types stay inferred; unions follow members.
+
+```ts
+// good
+export type CodeStep = typeof CodeStep.Type
+export const CodeStep = Schema.Struct({code: Schema.String, kind: Schema.Literal('code')})
+export type CallStep = {readonly do: readonly Step[]; readonly kind: 'call'}
+export const CallStep = Schema.Struct({
+	do: Schema.Array(Schema.suspend((): Schema.Codec<Step> => Step)),
+	kind: Schema.Literal('call')
+})
+export type Step = CallStep | CodeStep
+export const Step = Schema.Union([CallStep, CodeStep])
+```
+
+**Error predicates.** A predicate is a static member of its tagged error; a struct is checked inline with `Schema.is`.
+
+```ts
+// good
+class PathNotFound extends Schema.TaggedError<PathNotFound>()('PathNotFound', {
+	cause: Schema.optional(Schema.Defect())
+}) {
+	static matches = (error: Cause.UnknownError) => Schema.is(FileNotFound)(error.cause)
+}
+// bad
+function isPathNotFound(error: unknown) {
+	return Schema.is(FileNotFound)(error)
+}
+```
+
+## Shape
+
+**Inline.** Inline forwarding wrappers and single-use helpers/temporaries/constants. Argument-free functions are named values.
+
+```ts
+// good
+function randomIndex(length: number) {
+	return Random.Random.defaultValue().nextIntUnsafe() % length
+}
+const isApiUrl = Predicate.compose(String.isString, Predicate.or(Equal.equals('/api'), String.startsWith('/api/'))) // a predicate, reused
+static generateText = generateTextPi
+const notFound = HttpServerResponse.empty({status: 404})
+// bad
+const random = Random.Random.defaultValue()
+function isBackendRequest(request: IncomingMessage) {
+	return isApiUrl(request.url)
+} // "this is just a wrapper / factory function"
+Ref.set(entries, Array.copy(decoded)) // decoded is already an array
+const runPromise = Effect.runPromiseWith(Context.empty()) // "wrapper function, tmp variable ... that can be inlined"
+```
+
+**Linked state.** Linked state moves in one pure updater, never a setter that calls another.
+
+```ts
+// good
+setState(current => {
+	const draft = {...current.draft, files}
+	return {draft, owner: ownerAfter(draft)}
+})
+// bad
+setDraft(current => {
+	setOwner(ownerAfter(current))
+	return {...current, files}
+})
+```
+
+**File tree.** Use explicit kebab-case role names and one naming scheme. Prefer one substantive file to near-empty fragments; colocate <name>.test.ts; no barrels.
+
+**Package surface.** Explicit exports for imported subpaths; imports aliases for internal paths. Shared lint preset plus generated ignores only.
+
+```ts
+// good
+"exports": {"./plugin": "./src/generated/plugin.ts"}
+export {oxlint as default} from '@deslop/coding-standards'
+// bad — consumers import two names from a barrel of everything
+export * from './generated/Client.ts'
+const warned = ['sort-keys', 'typescript/no-restricted-types'] // a package rule list
+"typecheck": "tsc --noEmit" // type-aware lint already checks types
+```
+
+**Generated code.** A generator emits code that follows these rules as closely as it can; lint ignores its output.
+
+## React
+
+**Components.** React Compiler memoizes; state is destructured at its declaration; refs are props; logic lives in atoms.
+
+```tsx
+// good
+const editorRef = useRef<Lexical.LexicalEditor>(null)
+const [showShortcuts, setShowShortcuts] = useState(false)
+const moveRpc = useAtomSet(RpcClient.mutation('portfolio.move'))
+// bad
+const handle = useCallback(() => setOpen(true), [])
+const state = useState(false)
+```
+
+- **Pure render.** Derive display values from props and subscribed state during render; never mutate them or perform an RPC, write or subscription there. Event handlers own user-triggered actions; Effects synchronize external systems, not copied state or calculations. Reuse the existing router/atom integration rather than fetching in a new Effect.
+- **State identity.** Keep one owner for each value, stable domain keys for list items and deliberate reset boundaries. Compiler memoization is a performance optimization, never a correctness or lifetime guarantee. Do not add manual memoization, compiler escape directives or weakened hook rules to hide an ownership problem.
+
+Testing judgment, fixtures, assertions and verification belong to the testing skill; these engineering rules still apply to test code.

package/skills/testing/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: testing
+description: 'Curated black-box tests and trustworthy verification for Effect applications and tools. Read before writing, reviewing or running tests; apply engineering to the test code.'
+---
+
+# Testing
+
+**Scope.** Guard owned behavior, not coverage. CLI-installed skills are read-only; change their source and refresh via CLI.
+
+- **Worth it.** Test owned branching, computation, parsing/state transitions a plausible regression breaks; add missing valuable coverage before refactoring.
+- **Seam.** Test the exported layer, service, or function of a package or an app's service as a black box, so rewriting the implementation leaves every test green; the browser proves UI components.
+- **Redundant.** Delete touched cases merely asserting types/schema rules, Effect/dependency/platform internals, wiring, constants/counts, wording, removed/unreachable behavior or an already-covered input.
+- **Independent.** Expected values come from the contract/worked example, not implementation recomputation. Use the smallest reachable discriminating fixture.
+- **Bugs.** Reproduce a bug before fixing it; its failing case stays only when the fixed logic meets this bar, in the existing test that covers the fixed code.
+- **Throwaway.** Settle a worry with a throwaway test or prototype and delete it once answered.
+- **Honest.** No wrong expectations or rule workarounds. Change assertions only for recorded behavior changes; preserve every still-relevant value.
+
+**Assertions.** One representative input per behavior in its existing case; helpers serve every case. Use @effect/vitest assert for returned/flagged input or structured error identity. Doubles use Layers/public parameters, never vi/global/module mocks. Compose once; isolate state at its owning fixture.
+
+```ts
+// good — "test files only for the services/packages public interfaces"
+it.layer(Layer.provideMerge(Ledger.layer, NodeServices.layer))(test => {
+	test.effect('keeps the previous entries when the file is malformed', () => run(program))
+})
+assert.deepStrictEqual(customCodes(result.stdout), ['@deslop/coding-standards(no-typeof)'])
+assert.containsSubset(error, {_tag: 'SandboxUnavailable', cause: killed})
+Layer.succeed(OpenSandbox, openSandbox)
+// bad — "1 userful test is better than 1000 useless ones"
+it.effect('rejects an empty tag', () => run(ledger.add({tag: ''}))) // Schema.isNonEmpty already does
+// bad — "this test is useless, it doesn't test that the agent is working"
+it.effect('forwards the prompt', () => run(agent.prompt(message))) // wiring that only shows a call reaching a double
+additional?: {name: string; source: string}[] // a helper option one case needs
+it.effect('loads', () => pipe(program, Effect.provide(Ledger.layer))) // no owned behavior asserted
+assert.isTrue(Array.some(diagnostics, d => d.code === 'typescript(TS2456)')) // another tool's output
+expect(error).toMatchObject({_tag: 'SandboxUnavailable'}) // Vitest's expect
+assert.strictEqual(Array.flatMap(attioProvider.groups, group => group.actions).length, 75) // a pinned count
+```
+
+## Choose cases
+
+- **Contract.** Reachable input → observable output; a plausible wrong implementation must fail. Use the nearest public seam, not private helpers/new harnesses.
+- **Branches.** Exercise reachable empty/duplicate/concurrent/dependency-failure distinctions; no Cartesian product or random/repeated happy paths without a hypothesis.
+- **Failure.** Effect.flip for expected failure; Effect.exit for both outcomes. Assert domain identity and preserved state/resources: no partial write, lost value, extra retry or leak. Wording/rejection alone is insufficient; no incidental order assertions.
+- **Control.** Run against the unfixed implementation: the intended assertion fails, not setup/import/compilation. For refactoring, add missing coverage on old behavior first. Keep durable regressions, remove settled probes.
+
+## Effect and fixtures
+
+- **Entrypoint.** Plain it: sync/Promise public functions. it.effect(name, () => effect): virtual services; it.live: real services. Return Effect from a callback, no runner wrapper. it.layer caches its block context and exposes effect, not live; shared live layers use {excludeTestServices: true}. Verify matched cloned-source APIs/imports.
+- **Lifetime.** it.effect/live supply case Scope; it.layer acquisition belongs to its block. Use scoped platform resources, no redundant whole-case Effect.scoped. To assert cleanup, close the smaller operation scope before inspection.
+- **Isolation.** Shared layers share mutable services/TestClock/TestConsole; Layer.fresh does not reset cached context. Distinct keys, public reset or case-local fixtures; cases pass alone/together, never depend on earlier output.
+- **Clock.** TestClock/TestConsole from effect/testing. Fork, await a dependency-boundary Deferred carrying the actual key/path, adjust time, join; forking alone is not readiness. JavaScript timers/sockets/processes need live services, not TestClock.
+- **Concurrency.** Dependency entered/release pair: await entry, start competing action, release, assert contract. Set Effect.all concurrency for overlap. Cancellation: await acquisition, interrupt and await completion; unrelated outer Scope stays open. Don't test primitives/incidental ordering.
+- **Boundary.** Double only dependencies outside tested logic, via Layer/public parameter. SDK/process/filesystem/HTTP/browser/package integration claims require the real boundary, not matching mocks/spies.
+- **Artifacts.** Public-tool proof uses real packing/declared dependencies, not source imports/stubs. Generate fixtures with the real generator after one representative input settles; never alter expected output to fit a bug.
+- **Platform.** FileSystem.layerNoop is not memory storage; HttpServer.layerServices supplies no filesystem. Use platform Layer/scoped paths. RpcTest bypasses serialization; HttpApiTest bypasses sockets while testing routing/encoding/middleware/decoding. Neither proves deployment/external integration.
+
+## Run and reconcile
+
+- **Run.** Use root check/fix commands and documented test selectors; confirm intended collection/execution. Zero tests/setup-only/exit0 alone is not proof; no invented final suite.
+- **Inventory.** Collect independent failures once instead of cancelling the suite at the first failure. Distinguish separate cases from repeated observations. A timeout receives one isolated rerun of that same test; after a genuine pass, stop investigating it. Do not call a bypassed selector or a skipped operation flaky.
+- **Evidence.** Preserve the first failure, exact command, execution count and exit status. Separate cause from hypothesis, product defect from setup failure, and a skipped criterion from a passing one. A source read or overall green command never substitutes for a missing behavior check.
+- **Stable inputs.** No writer changes a running check's source, dependencies, configuration or build inputs. A relevant edit invalidates its prior result; rerun affected criteria and reuse unaffected evidence. Independent research or browser journeys may continue without mutating those inputs.
+- **Final proof.** Reconcile every required behavior on the final code. Screenshots/video prove visible outcomes; public-seam execution proves nonvisual behavior; fresh agents prove changed agent instructions. Keep the result and useful evidence, not disposable drivers, fixture installs, reports or preview services.

package/src/css-properties.d.ts

@@ -0,0 +1,9 @@
+export {}
+
+declare module 'react' {
+	// oxlint-disable-next-line typescript/consistent-type-definitions -- React accepts CSS custom properties in style only through this interface augmentation.
+	interface CSSProperties {
+		// oxlint-disable-next-line typescript/consistent-indexed-object-style -- the augmentation merges this member into React's interface, which a Record type cannot do.
+		[property: `--${string}`]: string
+	}
+}

package/tsconfig.json

@@ -0,0 +1,34 @@
+{
+	"compilerOptions": {
+		"strict": true,
+		"noUnusedLocals": true,
+		"noImplicitReturns": true,
+		"noErrorTruncation": true,
+		"allowUnusedLabels": false,
+		"noUnusedParameters": true,
+		"noImplicitOverride": true,
+		"allowUnreachableCode": false,
+		"noUncheckedIndexedAccess": true,
+		"noFallthroughCasesInSwitch": true,
+		"noPropertyAccessFromIndexSignature": true,
+
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleDetection": "force",
+		"moduleResolution": "bundler",
+
+		"skipLibCheck": true,
+		"esModuleInterop": true,
+		"isolatedModules": true,
+		"resolveJsonModule": true,
+		"erasableSyntaxOnly": true,
+		"verbatimModuleSyntax": true,
+		"allowImportingTsExtensions": true,
+		"noUncheckedSideEffectImports": true,
+
+		"noEmit": true,
+		"incremental": false,
+
+		"plugins": [{"name": "@effect/language-service", "effectFn": ["span", "untraced"]}]
+	}
+}