[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7B45XMHJ2Q2JBJQQDYXH4MA":3,"skill-same:01M7B45XMHJ2Q2JBJQQDYXH4MA":54},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":32,"commitSha":33,"skillDirectory":34,"forksCount":35,"repositoryHtmlUrl":36,"repositoryHomepageUrl":6,"ownerHtmlUrl":37,"ownerBlogUrl":6,"ownerDescription":38,"updatedAt":39,"install":40,"resources":53},"01M7B45XMHJ2Q2JBJQQDYXH4MA","effect",null,"Any change to a file that imports from effect — a service, a layer, a verb, a schema at a boundary, a stream, a fiber, a schedule, a log or a metric — and the design or review of one: load it before reading, writing or judging such a file. How this repository writes Effect 4: read the docs installed with it first, reach for Effect's own primitives before writing one by hand, leave the Effect 3 names it no longer has, and keep our services, layers, Effect.fn verbs, tagged errors and programs, each where the runtime shows it.","emyann\u002Fnemia","emyann","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F4748419?v=4","01M7B458J23KJ5S5AEBR86G7RN","Yann RENAUDIN","01M7B458JPM0CCBDP4KCR6NATT",3,"MIT","https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Feffect\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: effect\ndescription: \"Any change to a file that imports from effect — a service, a layer, a verb, a schema at a boundary, a stream, a fiber, a schedule, a log or a metric — and the design or review of one: load it before reading, writing or judging such a file. How this repository writes Effect 4: read the docs installed with it first, reach for Effect's own primitives before writing one by hand, leave the Effect 3 names it no longer has, and keep our services, layers, Effect.fn verbs, tagged errors and programs, each where the runtime shows it.\"\napplies: [\"packages\u002Fagent-runtime\u002Fsrc\u002F**\", \"packages\u002Fagent-orchestrator\u002Fsrc\u002F**\u002F*.store.ts\", \"packages\u002Fagent-orchestrator\u002Fsrc\u002F**\u002F*.verb.ts\", \"packages\u002Fagent-orchestrator\u002Fsrc\u002Fruntime-client.ts\", \"packages\u002Fagent-orchestrator\u002Fsrc\u002Fcli\u002F**\", \"apps\u002Fapi\u002Fsrc\u002F**\", \"apps\u002Fweb\u002Fsrc\u002Flib\u002Fapi\u002F**\"]\n---\n\n# Writing Effect 4 here\n\n## Read the installed docs first\n\n`effect` is pinned to one exact version, the same in every package (`packages\u002Fagent-runtime\u002Ftest\u002Feffect-version.test.ts`\nrefuses a range or a second version). Its own guide ships with it and matches it:\n\n1. `node_modules\u002Feffect\u002FAGENTS.md` — the patterns and an index of worked examples.\n2. The topic you need under `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F` (`01_effect` for services, layers, errors and resources).\n3. The installed source and types, `node_modules\u002Feffect\u002Fdist\u002F*.d.ts`, when a name is in doubt.\n\nPrefer them to what you remember and to anything outside the repository: the package says outside copies may be outdated.\nThis file holds only what is ours.\n\n## Reach for Effect's own primitives\n\nBefore writing a loop, a list of listeners, a registry, a fan-out, a timer, a retry, a cache, a counter or a parser by hand, find the task\nhere and read its page.\n\n| task | primitive | page |\n| --- | --- | --- |\n| Tell every listener of one event: a feed, a watcher, a page kept live | `PubSub.unbounded`, `PubSub.subscribe` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F01_effect\u002F07_pubsub\u002F10_pubsub.ts` |\n| Do the same work over many items, a bounded number at once: a batch of reads, of removals, of processes | `Effect.forEach`, its concurrency option | `node_modules\u002Feffect\u002Fdist\u002FEffect.d.ts` |\n| Hand work from one fiber to another, bounded, the writer waiting when it is full | `Queue.bounded`, `Queue.take` | `node_modules\u002Feffect\u002Fdist\u002FQueue.d.ts` |\n| Read a sequence over time: the lines of a file, the events of a feed, the pages of a listing | `Stream.callback`, `Stream.fromQueue` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F03_stream\u002F10_creating-streams.ts` |\n| Keep a registry of running fibers, one per key, the old one interrupted when the key runs again | `FiberMap.make`, `FiberMap.run` | `node_modules\u002Feffect\u002Fdist\u002FFiberMap.d.ts` |\n| Run fibers that end with their scope, none left behind | `FiberSet.make`, `FiberSet.run` | `node_modules\u002Feffect\u002Fdist\u002FFiberSet.d.ts` |\n| Keep what was computed for a key, looked up again, refreshed or bounded: a memo, a hand-made cache | `Cache.make`, `Cache.get` | `node_modules\u002Feffect\u002Fdist\u002FCache.d.ts` |\n| Retry, poll or beat on a cadence: a backoff, a tick, a limit of tries | `Schedule.spaced`, `Schedule.exponential`, `Effect.retry`, `Effect.repeat` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F06_schedule\u002F10_schedules.ts` |\n| Count or measure what the code does: passes, reads, durations | `Metric.counter`, `Metric.histogram` | `node_modules\u002Feffect\u002Fdist\u002FMetric.d.ts` |\n| Say what happened, at a level, with its fields | `Effect.logInfo`, `Effect.annotateLogs`, `Logger.layer` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F08_observability\u002F10_logging.ts` |\n| Time a verb and tie it to its caller | `Effect.fn`, `Effect.withSpan`, `Tracer` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F08_observability\u002F20_otlp-tracing.ts` |\n| Send the spans and logs to a collector, over OTLP | `OtlpTracer.layer`, `OtlpLogger.layer`, `OtlpSerialization.layerJson` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F08_observability\u002F20_otlp-tracing.ts` |\n| Read a value that crosses a boundary: a file, a request, a harness's line, JSON | `Schema.Struct`, `Schema.decodeUnknownEffect` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F01_effect\u002F02_schema\u002F10_schema-basics.ts` |\n| Hold a resource and let it go whatever happens, the last taken first | `Effect.acquireRelease`, `Scope.addFinalizer` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F01_effect\u002F05_resources\u002F10_acquire-release.ts` |\n| Build a service from others and give it to a program | `Layer.effect`, `Layer.provide`, `Layer.mergeAll` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F01_effect\u002F03_services\u002F20_layer-composition.ts` |\n\nIn a review, a hand-rolled version of one of these is a finding.\n\nv4 is not v3: read the page, not your memory.\n\n`effect-version.test.ts` reads this table: each name must be one the pinned version exports, from `effect` or, for the exporters,\n`effect\u002Fobservability`, and each page installed.\n\n## Effect 3 names this version does not have\n\nMeasured on `4.1.2`. `tsc` catches each, but writing from memory costs a round per name.\n\n| Effect 3 | Effect 4 |\n| --- | --- |\n| `Context.Tag`, `Context.GenericTag`, `Effect.Service` | `Context.Service` |\n| `Effect.catchAll` | `Effect.catch` |\n| `Effect.catchAllCause` | `Effect.catchCause` |\n| `Effect.either` | `Effect.result` |\n| `Either` | `Result` |\n| `Effect.fork` | `Effect.forkChild` |\n| `Effect.forkDaemon` | `Effect.forkDetach` |\n| `Effect.zipRight` | `Effect.andThen` |\n| `Effect.tapErrorCause` | `Effect.tapCause` |\n| `Layer.scoped` | `Layer.effect` |\n| `Config.string` | `Config.String` |\n\n`effect-version.test.ts` reads this table: each name on the left must be gone and each on the right present in the pinned\nversion, and the version above must be the pin. An upgrade re-measures the table before it changes the pin.\n\n## Services and layers\n\n- A service is a `Context.Service` class, and its static `layer` turns any implementation into a layer: `Journal` in\n  `packages\u002Fagent-runtime\u002Fsrc\u002Fcore\u002Fengine\u002Fjournal.ts`, `Runner` in `src\u002Fharness\u002Fseam.ts`, each `Layer.succeed(Tag)(Tag.of({ ... }))`.\n- A value with a default is a `Context.Reference`, given by `Layer.succeed`: `TickMemo` and `tickMemoLayer` in `src\u002Fcore\u002Fengine\u002Fmemo.ts`.\n- A layer built from another service is `Layer.unwrap(Effect.gen(...))`: `a2aRunner` in `src\u002Fa2a\u002Fclient.ts`.\n- A service made from options is `Layer.effect(Tag, make(options))` under a static `layer`: `Engine` in `src\u002Fservice\u002Fengine.ts`,\n  whose `make` joins the engine's layers with `Layer.mergeAll` and provides them to each verb.\n- A service changed in one verb is a layer over it: `Layer.effect(Tag, ...)` that reads the service and returns `Tag.of({ ...e, verb })`,\n  `.pipe(Layer.provide(inner))` (`engineOf` in `packages\u002Fagent-orchestrator\u002Fsrc\u002Fruntime-client.ts`).\n- A test is given a stand-in as a layer, and hands no implementation of its own for what is outside the process: the place is\n  `testPlace()`'s layer (`packages\u002Fagent-orchestrator\u002Fplace\u002Fmemory`), and a new test file that makes an engine by hand\n  (`Layer.succeed(Tag)(Tag.of({ ... }))`, `promised`) is refused by `packages\u002Fagent-orchestrator\u002Ftest\u002Fstand-ins.test.ts`. An engine is the\n  runtime's stand-in, `testEngine()` of `agent-runtime\u002Ftesting` (`const engine = eachTest(testEngine);`), a verb it does not keep an\n  `Effect.die` naming itself.\n\n## Verbs\n\n- Each verb is `Effect.fn('name')(function* (...) { ... })`, which names its span: `file`, `admit` in\n  `src\u002Fcore\u002Fengine\u002Ffiling.ts`, `reconcile`, `tick` in `src\u002Fcore\u002Fengine\u002Fengine.ts`.\n- A verb refuses an argument it no longer takes, never ignores it (`packages\u002Fagent-runtime\u002FCLAUDE.md`, *Arguments and doors*):\n  `tick` declares no parameter and reads `[...arguments]` into `tickRefusalOf`.\n\n## Tagged errors\n\n- The runtime's errors are `Schema.TaggedError` classes from `effect`, each with a `message`: `FileRefused` in\n  `src\u002Fcore\u002Fengine\u002Ffiling.ts`, `TickRefused` in `src\u002Fcore\u002Fengine\u002Fengine.ts`, `JournalError` in `src\u002Fcore\u002Fengine\u002Fjournal.ts`,\n  `RunnerError` in `src\u002Fharness\u002Ferror.ts`. A verb fails with\n  `return yield* Effect.fail(new TickRefused({ message }))`, and a caller picks one out with `Effect.catchTag('TickMemoDiverged', ...)`\n  (`src\u002Fservice\u002Fengine.ts`).\n- A refusal written for a file that must not load the `effect` barrel — a pure file, or the orchestrator's refusals — is a\n  `Data.TaggedError` imported from `effect\u002FData`, never from `effect`, and carries `exitCode: 2` as every refusal here does\n  (the root `CLAUDE.md`, *Errors say what to do next*): `Missing`, `Conflict` and `Invalid` in\n  `packages\u002Fagent-orchestrator\u002Fsrc\u002Frefusal\u002Frefusal.ts`, thrown as `new Invalid({ message })`, and exported to the api by\n  `agent-orchestrator`. `effect\u002FData` loads 15 modules; the\n  barrel loads 216, about 130 ms, on every consumer of `agent-orchestrator\u002Frun` and `agent-orchestrator\u002Fworkflow`, whose modules\n  `packages\u002Fagent-orchestrator\u002Ftest\u002Frefusal.test.ts` pins.\n\n## Resources and the process\n\n- What a command holds while the process lives is `Effect.acquireRelease` in its scope, and a loop beside it `Effect.forkScoped`:\n  the claim on the store and the beat of `wf up`, and `watching` (the watcher of `wf watch`), in `packages\u002Fagent-orchestrator\u002Fsrc\u002Fcli\u002Fmain.ts`.\n  Finalizers run in reverse, so the beat is interrupted before the store is let go.\n- `runMain` in `packages\u002Fagent-orchestrator\u002Fsrc\u002Fcli\u002Fmain.ts` runs such a command: SIGINT, SIGTERM and SIGHUP interrupt it and\n  exit 130, 143 or 129 once the finalizers ran; otherwise it resolves the value or rejects with the failure itself (`Cause.squash`),\n  so a refusal's `exitCode` reaches `bin\u002Fwf.ts`. Not `NodeRuntime.runMain` of `@effect\u002Fplatform-node`, which is not installed: its\n  default teardown (`Runtime.defaultTeardown`) exits 130 on any interruption, whichever signal came, it handles no SIGHUP, and it\n  hands no failure back to the caller.\n- What an api route holds is let go in its scope too. A live reader is a stream that takes what it holds in its own scope: `followFeed`\n  in `packages\u002Fagent-orchestrator\u002Fsrc\u002Ffeed\u002Ffeed.verb.ts` subscribes to the process's `PubSub.sliding` (`FeedHub`), so a slow reader never\n  holds up the writer, reads what the hub dropped from the file, and is counted while it is open; `feedEvents` in\n  `apps\u002Fapi\u002Fsrc\u002Fgauges\u002Ffeed.ts` maps it to the stream's events. Hono's `streamSSE` runs it with the app's `runtime.runPromiseExit(program, { signal })`, the signal\n  aborted from `stream.onAbort`: `runPromiseExit`, since `streamSSE` prints a rejection. A child process is `acquireRelease` with its\n  release reading the `Exit`, under `Effect.timeoutOrElse`, which waits for the release: `claudeQuota` in\n  `packages\u002Fagent-runtime\u002Fsrc\u002Fharness\u002Fclaude\u002Fquota.ts`, `serverAsk` in `apps\u002Fapi\u002Fsrc\u002Fcapabilities\u002Fcapabilities.ts`.\n\n## The api's runtime\n\n- The api runs its handlers on one `ManagedRuntime`, built from its layer (`appOf` in `apps\u002Fapi\u002Fsrc\u002Fapp.ts`), as\n  `ai-docs\u002Fsrc\u002F04_integration\u002F10_managed-runtime.ts` does for Hono: a middleware puts it on each request (`c.var.runtime`), and\n  `served` (`apps\u002Fapi\u002Fsrc\u002Flayer.ts`) runs a handler over the services — the environment, the engine, the store's root, the MCP asker,\n  the quota asker, and what its reads keep between requests (`ApiConfig`, `Engine`, `StoreRoot`, `McpAsker`, `QuotaAsker`, `ReadMemo`).\n- What an app keeps between requests is a service built with its runtime (`Layer.sync`), never module state: each `ManagedRuntime`\n  builds its layer afresh, so an app over another engine keeps nothing of another's.\n- A test builds an app over `Layer.merge(liveOf(), …)`, the service it replaces given last: `Layer.merge` keeps the later of two.\n- A handler's body stays a plain `async` function: a failure yielded inside `Effect.gen` never reaches a `try` around the `yield*`,\n  and the routes catch what they word themselves. `runPromise` rejects with the failure itself, so a refusal reaches `app.onError`\n  as the instance it was.\n\n## Programs\n\n- The packages' entries are Effect, and the api is the system's public interface. No function the runtime's entries export runs a\n  program for its caller or answers a Promise (`packages\u002Fagent-runtime\u002Ftest\u002Fplain-faces.test.ts`, its `PROMISED` empty): a program is\n  run at its edge — the CLI (`ae`), the api's server, a test — with `Effect.runPromise` or `Effect.runSync`.\n- A caller of the runtime builds its engine once from `Engine.layer(options)` (`agent-runtime`, `src\u002Findex.ts`, which does not export\n  `decide`) and runs each verb as an Effect: `ae` (`packages\u002Fagent-runtime\u002Fsrc\u002Fcli\u002Fmain.ts`) and the orchestrator's client (`engineOf`\n  in `packages\u002Fagent-orchestrator\u002Fsrc\u002Fruntime-client.ts`). A refusal a caller answers with a sentence and an exit code is worded by\n  `refusalWords` (`src\u002Fservice\u002Frefusal.ts`): an `Error` led by the verb whose `exitCode` is 2.\n- Stores and pure files stay plain TypeScript: `decide` in `src\u002Fcore\u002Fdomain.ts` imports no Effect.\n- A controller is an `Effect.fn` program that requires the engine as a service (`EngineService`): it reads the engine with `asked`,\n  which dies of a runtime refusal in the runtime's words, and lifts every other read with `tried` or `awaited`, failing with a\n  `Refusal` and dying of anything else. Its caller runs it with `runWith(e, program)` over the engine it built once — the CLI, the\n  daemon, the api's handlers and the tests — and the Promise rejects with the refusal or the defect as it was thrown: `decideRun`,\n  `forgetRun`, the verbs a person asks of a run (`roundRun`, `acceptRun`, `retryRun`, `approveRun`, `sayRun`, `cancelRun`, `hold`), the\n  views' reads (`taskPhasesRead`, `checkReportsRead`, `refusalRead`, `parentRead`, `parentsRead`), and the tick\n  (`tickRun`), whose pass is metered through `meteredPass` over the module-global meter. A command's `handler` is a program too. An\n  engine refusal a controller answers itself is read off the raw verb: `toldBy` in `say.verb.ts` turns the runtime's refusal into a\n  `Conflict`, and a journal that does not read is told by `unreadableJournal`.\n- A controller that reads no engine requires none: `unhold`, run with `Effect.runPromise` or `runWith` alike.\n- A controller that asks where a run's work lives requires the place (`PlaceService` in\n  `packages\u002Fagent-orchestrator\u002Fsrc\u002Fplace\u002Fplace.store.ts`, a service with no default): `startRun` requires it alone, `tickRun` beside the\n  engine. `runWith` removes the engine's requirement only, so whoever runs the program gives the place by name\n  (`Effect.provide(gitPlaceLayer)`, `builtin(program)`), and a program given none does not compile. A test gives the test place's\n  layer (`runOver(runEngine, () => stand().layer)`, `test\u002Fplaced.ts`); the git place is named only in a `.boundary.test.ts` file.\n\n## Logs and traces\n\n- **A span is a verb's `Effect.fn` name**, nested by the fiber: `tick` > `pass` > `advancePass` > `fileReady` in the orchestrator's tick,\n  then the runtime's `file` > `append` (`packages\u002Fagent-orchestrator\u002Ftest\u002Ftelemetry-nesting.test.ts`). A runtime verb run in its own\n  `Effect.runPromise` starts a root of its own: a caller yields the engine's verbs (`engineOf`), never runs them apart.\n- **Each layer annotates in its own words**, on its spans and its logs alike: the orchestrator the `run` (`advancePass`) and the `step`\n  (`forStep` in `packages\u002Fagent-orchestrator\u002Fsrc\u002Ftelemetry\u002Ftelemetry.store.ts`); the runtime the `task`, `kind` and `attempt`\n  (`appendFields` in `packages\u002Fagent-runtime\u002Fsrc\u002Fcore\u002Fengine\u002Fjournal.ts`), and never a run or a step.\n- **Levels**: Info is what a person reads in `nemia up`'s lines (`logPass` in `packages\u002Fagent-orchestrator\u002Fsrc\u002Fdaemon\u002Fup.verb.ts`) and\n  each line of the feed, said once as it is written (`emitFeed` in `packages\u002Fagent-orchestrator\u002Fsrc\u002Ffeed\u002Ffeed.verb.ts`); a\n  warning or worse goes to stderr; Debug is the journal, an append said by its kind, below the default level.\n- **One `telemetryLayer`, provided by the process around its program**, never by a verb: `nemia up` in\n  `packages\u002Fagent-orchestrator\u002Fsrc\u002Fcli\u002Fmain.ts` and the api's daemon in `apps\u002Fapi\u002Fsrc\u002Fmain.ts`. A test provides its own logger\n  (`Logger.layer`) and tracer (`Effect.withTracer`), and `References.MinimumLogLevel` to read Debug.\n- **OTLP only when `OTEL_EXPORTER_OTLP_ENDPOINT` is set**, under the service `OTEL_SERVICE_NAME`, `nemia` by default (`otlpOf` in\n  `packages\u002Fagent-orchestrator\u002Fsrc\u002Ftelemetry\u002Ftelemetry.ts`); a test that spawns a daemon sets it, blank where it wants none.\n\n## Tests\n\n`node:test`, with `Effect.runPromise` and the layers provided in the test (`const run` in\n`packages\u002Fagent-runtime\u002Ftest\u002Fengine.test.ts`). No `@effect\u002Fvitest`, though `ai-docs\u002Fsrc\u002F09_testing` uses it.\n\n## Why\n\n`docs\u002Feval-2026-09-28-effect-everywhere.md` weighs Effect in every layer and orders the cards that adopt it.\n","# Writing Effect 4 here\n\n## Read the installed docs first\n\n`effect` is pinned to one exact version, the same in every package (`packages\u002Fagent-runtime\u002Ftest\u002Feffect-version.test.ts`\nrefuses a range or a second version). Its own guide ships with it and matches it:\n\n1. `node_modules\u002Feffect\u002FAGENTS.md` — the patterns and an index of worked examples.\n2. The topic you need under `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F` (`01_effect` for services, layers, errors and resources).\n3. The installed source and types, `node_modules\u002Feffect\u002Fdist\u002F*.d.ts`, when a name is in doubt.\n\nPrefer them to what you remember and to anything outside the repository: the package says outside copies may be outdated.\nThis file holds only what is ours.\n\n## Reach for Effect's own primitives\n\nBefore writing a loop, a list of listeners, a registry, a fan-out, a timer, a retry, a cache, a counter or a parser by hand, find the task\nhere and read its page.\n\n| task | primitive | page |\n| --- | --- | --- |\n| Tell every listener of one event: a feed, a watcher, a page kept live | `PubSub.unbounded`, `PubSub.subscribe` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F01_effect\u002F07_pubsub\u002F10_pubsub.ts` |\n| Do the same work over many items, a bounded number at once: a batch of reads, of removals, of processes | `Effect.forEach`, its concurrency option | `node_modules\u002Feffect\u002Fdist\u002FEffect.d.ts` |\n| Hand work from one fiber to another, bounded, the writer waiting when it is full | `Queue.bounded`, `Queue.take` | `node_modules\u002Feffect\u002Fdist\u002FQueue.d.ts` |\n| Read a sequence over time: the lines of a file, the events of a feed, the pages of a listing | `Stream.callback`, `Stream.fromQueue` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F03_stream\u002F10_creating-streams.ts` |\n| Keep a registry of running fibers, one per key, the old one interrupted when the key runs again | `FiberMap.make`, `FiberMap.run` | `node_modules\u002Feffect\u002Fdist\u002FFiberMap.d.ts` |\n| Run fibers that end with their scope, none left behind | `FiberSet.make`, `FiberSet.run` | `node_modules\u002Feffect\u002Fdist\u002FFiberSet.d.ts` |\n| Keep what was computed for a key, looked up again, refreshed or bounded: a memo, a hand-made cache | `Cache.make`, `Cache.get` | `node_modules\u002Feffect\u002Fdist\u002FCache.d.ts` |\n| Retry, poll or beat on a cadence: a backoff, a tick, a limit of tries | `Schedule.spaced`, `Schedule.exponential`, `Effect.retry`, `Effect.repeat` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F06_schedule\u002F10_schedules.ts` |\n| Count or measure what the code does: passes, reads, durations | `Metric.counter`, `Metric.histogram` | `node_modules\u002Feffect\u002Fdist\u002FMetric.d.ts` |\n| Say what happened, at a level, with its fields | `Effect.logInfo`, `Effect.annotateLogs`, `Logger.layer` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F08_observability\u002F10_logging.ts` |\n| Time a verb and tie it to its caller | `Effect.fn`, `Effect.withSpan`, `Tracer` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F08_observability\u002F20_otlp-tracing.ts` |\n| Send the spans and logs to a collector, over OTLP | `OtlpTracer.layer`, `OtlpLogger.layer`, `OtlpSerialization.layerJson` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F08_observability\u002F20_otlp-tracing.ts` |\n| Read a value that crosses a boundary: a file, a request, a harness's line, JSON | `Schema.Struct`, `Schema.decodeUnknownEffect` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F01_effect\u002F02_schema\u002F10_schema-basics.ts` |\n| Hold a resource and let it go whatever happens, the last taken first | `Effect.acquireRelease`, `Scope.addFinalizer` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F01_effect\u002F05_resources\u002F10_acquire-release.ts` |\n| Build a service from others and give it to a program | `Layer.effect`, `Layer.provide`, `Layer.mergeAll` | `node_modules\u002Feffect\u002Fai-docs\u002Fsrc\u002F01_effect\u002F03_services\u002F20_layer-composition.ts` |\n\nIn a review, a hand-rolled version of one of these is a finding.\n\nv4 is not v3: read the page, not your memory.\n\n`effect-version.test.ts` reads this table: each name must be one the pinned version exports, from `effect` or, for the exporters,\n`effect\u002Fobservability`, and each page installed.\n\n## Effect 3 names this version does not have\n\nMeasured on `4.1.2`. `tsc` catches each, but writing from memory costs a round per name.\n\n| Effect 3 | Effect 4 |\n| --- | --- |\n| `Context.Tag`, `Context.GenericTag`, `Effect.Service` | `Context.Service` |\n| `Effect.catchAll` | `Effect.catch` |\n| `Effect.catchAllCause` | `Effect.catchCause` |\n| `Effect.either` | `Effect.result` |\n| `Either` | `Result` |\n| `Effect.fork` | `Effect.forkChild` |\n| `Effect.forkDaemon` | `Effect.forkDetach` |\n| `Effect.zipRight` | `Effect.andThen` |\n| `Effect.tapErrorCause` | `Effect.tapCause` |\n| `Layer.scoped` | `Layer.effect` |\n| `Config.string` | `Config.String` |\n\n`effect-version.test.ts` reads this table: each name on the left must be gone and each on the right present in the pinned\nversion, and the version above must be the pin. An upgrade re-measures the table before it changes the pin.\n\n## Services and layers\n\n- A service is a `Context.Service` class, and its static `layer` turns any implementation into a layer: `Journal` in\n  `packages\u002Fagent-runtime\u002Fsrc\u002Fcore\u002Fengine\u002Fjournal.ts`, `Runner` in `src\u002Fharness\u002Fseam.ts`, each `Layer.succeed(Tag)(Tag.of({ ... }))`.\n- A value with a default is a `Context.Reference`, given by `Layer.succeed`: `TickMemo` and `tickMemoLayer` in `src\u002Fcore\u002Fengine\u002Fmemo.ts`.\n- A layer built from another service is `Layer.unwrap(Effect.gen(...))`: `a2aRunner` in `src\u002Fa2a\u002Fclient.ts`.\n- A service made from options is `Layer.effect(Tag, make(options))` under a static `layer`: `Engine` in `src\u002Fservice\u002Fengine.ts`,\n  whose `make` joins the engine's layers with `Layer.mergeAll` and provides them to each verb.\n- A service changed in one verb is a layer over it: `Layer.effect(Tag, ...)` that reads the service and returns `Tag.of({ ...e, verb })`,\n  `.pipe(Layer.provide(inner))` (`engineOf` in `packages\u002Fagent-orchestrator\u002Fsrc\u002Fruntime-client.ts`).\n- A test is given a stand-in as a layer, and hands no implementation of its own for what is outside the process: the place is\n  `testPlace()`'s layer (`packages\u002Fagent-orchestrator\u002Fplace\u002Fmemory`), and a new test file that makes an engine by hand\n  (`Layer.succeed(Tag)(Tag.of({ ... }))`, `promised`) is refused by `packages\u002Fagent-orchestrator\u002Ftest\u002Fstand-ins.test.ts`. An engine is the\n  runtime's stand-in, `testEngine()` of `agent-runtime\u002Ftesting` (`const engine = eachTest(testEngine);`), a verb it does not keep an\n  `Effect.die` naming itself.\n\n## Verbs\n\n- Each verb is `Effect.fn('name')(function* (...) { ... })`, which names its span: `file`, `admit` in\n  `src\u002Fcore\u002Fengine\u002Ffiling.ts`, `reconcile`, `tick` in `src\u002Fcore\u002Fengine\u002Fengine.ts`.\n- A verb refuses an argument it no longer takes, never ignores it (`packages\u002Fagent-runtime\u002FCLAUDE.md`, *Arguments and doors*):\n  `tick` declares no parameter and reads `[...arguments]` into `tickRefusalOf`.\n\n## Tagged errors\n\n- The runtime's errors are `Schema.TaggedError` classes from `effect`, each with a `message`: `FileRefused` in\n  `src\u002Fcore\u002Fengine\u002Ffiling.ts`, `TickRefused` in `src\u002Fcore\u002Fengine\u002Fengine.ts`, `JournalError` in `src\u002Fcore\u002Fengine\u002Fjournal.ts`,\n  `RunnerError` in `src\u002Fharness\u002Ferror.ts`. A verb fails with\n  `return yield* Effect.fail(new TickRefused({ message }))`, and a caller picks one out with `Effect.catchTag('TickMemoDiverged', ...)`\n  (`src\u002Fservice\u002Fengine.ts`).\n- A refusal written for a file that must not load the `effect` barrel — a pure file, or the orchestrator's refusals — is a\n  `Data.TaggedError` imported from `effect\u002FData`, never from `effect`, and carries `exitCode: 2` as every refusal here does\n  (the root `CLAUDE.md`, *Errors say what to do next*): `Missing`, `Conflict` and `Invalid` in\n  `packages\u002Fagent-orchestrator\u002Fsrc\u002Frefusal\u002Frefusal.ts`, thrown as `new Invalid({ message })`, and exported to the api by\n  `agent-orchestrator`. `effect\u002FData` loads 15 modules; the\n  barrel loads 216, about 130 ms, on every consumer of `agent-orchestrator\u002Frun` and `agent-orchestrator\u002Fworkflow`, whose modules\n  `packages\u002Fagent-orchestrator\u002Ftest\u002Frefusal.test.ts` pins.\n\n## Resources and the process\n\n- What a command holds while the process lives is `Effect.acquireRelease` in its scope, and a loop beside it `Effect.forkScoped`:\n  the claim on the store and the beat of `wf up`, and `watching` (the watcher of `wf watch`), in `packages\u002Fagent-orchestrator\u002Fsrc\u002Fcli\u002Fmain.ts`.\n  Finalizers run in reverse, so the beat is interrupted before the store is let go.\n- `runMain` in `packages\u002Fagent-orchestrator\u002Fsrc\u002Fcli\u002Fmain.ts` runs such a command: SIGINT, SIGTERM and SIGHUP interrupt it and\n  exit 130, 143 or 129 once the finalizers ran; otherwise it resolves the value or rejects with the failure itself (`Cause.squash`),\n  so a refusal's `exitCode` reaches `bin\u002Fwf.ts`. Not `NodeRuntime.runMain` of `@effect\u002Fplatform-node`, which is not installed: its\n  default teardown (`Runtime.defaultTeardown`) exits 130 on any interruption, whichever signal came, it handles no SIGHUP, and it\n  hands no failure back to the caller.\n- What an api route holds is let go in its scope too. A live reader is a stream that takes what it holds in its own scope: `followFeed`\n  in `packages\u002Fagent-orchestrator\u002Fsrc\u002Ffeed\u002Ffeed.verb.ts` subscribes to the process's `PubSub.sliding` (`FeedHub`), so a slow reader never\n  holds up the writer, reads what the hub dropped from the file, and is counted while it is open; `feedEvents` in\n  `apps\u002Fapi\u002Fsrc\u002Fgauges\u002Ffeed.ts` maps it to the stream's events. Hono's `streamSSE` runs it with the app's `runtime.runPromiseExit(program, { signal })`, the signal\n  aborted from `stream.onAbort`: `runPromiseExit`, since `streamSSE` prints a rejection. A child process is `acquireRelease` with its\n  release reading the `Exit`, under `Effect.timeoutOrElse`, which waits for the release: `claudeQuota` in\n  `packages\u002Fagent-runtime\u002Fsrc\u002Fharness\u002Fclaude\u002Fquota.ts`, `serverAsk` in `apps\u002Fapi\u002Fsrc\u002Fcapabilities\u002Fcapabilities.ts`.\n\n## The api's runtime\n\n- The api runs its handlers on one `ManagedRuntime`, built from its layer (`appOf` in `apps\u002Fapi\u002Fsrc\u002Fapp.ts`), as\n  `ai-docs\u002Fsrc\u002F04_integration\u002F10_managed-runtime.ts` does for Hono: a middleware puts it on each request (`c.var.runtime`), and\n  `served` (`apps\u002Fapi\u002Fsrc\u002Flayer.ts`) runs a handler over the services — the environment, the engine, the store's root, the MCP asker,\n  the quota asker, and what its reads keep between requests (`ApiConfig`, `Engine`, `StoreRoot`, `McpAsker`, `QuotaAsker`, `ReadMemo`).\n- What an app keeps between requests is a service built with its runtime (`Layer.sync`), never module state: each `ManagedRuntime`\n  builds its layer afresh, so an app over another engine keeps nothing of another's.\n- A test builds an app over `Layer.merge(liveOf(), …)`, the service it replaces given last: `Layer.merge` keeps the later of two.\n- A handler's body stays a plain `async` function: a failure yielded inside `Effect.gen` never reaches a `try` around the `yield*`,\n  and the routes catch what they word themselves. `runPromise` rejects with the failure itself, so a refusal reaches `app.onError`\n  as the instance it was.\n\n## Programs\n\n- The packages' entries are Effect, and the api is the system's public interface. No function the runtime's entries export runs a\n  program for its caller or answers a Promise (`packages\u002Fagent-runtime\u002Ftest\u002Fplain-faces.test.ts`, its `PROMISED` empty): a program is\n  run at its edge — the CLI (`ae`), the api's server, a test — with `Effect.runPromise` or `Effect.runSync`.\n- A caller of the runtime builds its engine once from `Engine.layer(options)` (`agent-runtime`, `src\u002Findex.ts`, which does not export\n  `decide`) and runs each verb as an Effect: `ae` (`packages\u002Fagent-runtime\u002Fsrc\u002Fcli\u002Fmain.ts`) and the orchestrator's client (`engineOf`\n  in `packages\u002Fagent-orchestrator\u002Fsrc\u002Fruntime-client.ts`). A refusal a caller answers with a sentence and an exit code is worded by\n  `refusalWords` (`src\u002Fservice\u002Frefusal.ts`): an `Error` led by the verb whose `exitCode` is 2.\n- Stores and pure files stay plain TypeScript: `decide` in `src\u002Fcore\u002Fdomain.ts` imports no Effect.\n- A controller is an `Effect.fn` program that requires the engine as a service (`EngineService`): it reads the engine with `asked`,\n  which dies of a runtime refusal in the runtime's words, and lifts every other read with `tried` or `awaited`, failing with a\n  `Refusal` and dying of anything else. Its caller runs it with `runWith(e, program)` over the engine it built once — the CLI, the\n  daemon, the api's handlers and the tests — and the Promise rejects with the refusal or the defect as it was thrown: `decideRun`,\n  `forgetRun`, the verbs a person asks of a run (`roundRun`, `acceptRun`, `retryRun`, `approveRun`, `sayRun`, `cancelRun`, `hold`), the\n  views' reads (`taskPhasesRead`, `checkReportsRead`, `refusalRead`, `parentRead`, `parentsRead`), and the tick\n  (`tickRun`), whose pass is metered through `meteredPass` over the module-global meter. A command's `handler` is a program too. An\n  engine refusal a controller answers itself is read off the raw verb: `toldBy` in `say.verb.ts` turns the runtime's refusal into a\n  `Conflict`, and a journal that does not read is told by `unreadableJournal`.\n- A controller that reads no engine requires none: `unhold`, run with `Effect.runPromise` or `runWith` alike.\n- A controller that asks where a run's work lives requires the place (`PlaceService` in\n  `packages\u002Fagent-orchestrator\u002Fsrc\u002Fplace\u002Fplace.store.ts`, a service with no default): `startRun` requires it alone, `tickRun` beside the\n  engine. `runWith` removes the engine's requirement only, so whoever runs the program gives the place by name\n  (`Effect.provide(gitPlaceLayer)`, `builtin(program)`), and a program given none does not compile. A test gives the test place's\n  layer (`runOver(runEngine, () => stand().layer)`, `test\u002Fplaced.ts`); the git place is named only in a `.boundary.test.ts` file.\n\n## Logs and traces\n\n- **A span is a verb's `Effect.fn` name**, nested by the fiber: `tick` > `pass` > `advancePass` > `fileReady` in the orchestrator's tick,\n  then the runtime's `file` > `append` (`packages\u002Fagent-orchestrator\u002Ftest\u002Ftelemetry-nesting.test.ts`). A runtime verb run in its own\n  `Effect.runPromise` starts a root of its own: a caller yields the engine's verbs (`engineOf`), never runs them apart.\n- **Each layer annotates in its own words**, on its spans and its logs alike: the orchestrator the `run` (`advancePass`) and the `step`\n  (`forStep` in `packages\u002Fagent-orchestrator\u002Fsrc\u002Ftelemetry\u002Ftelemetry.store.ts`); the runtime the `task`, `kind` and `attempt`\n  (`appendFields` in `packages\u002Fagent-runtime\u002Fsrc\u002Fcore\u002Fengine\u002Fjournal.ts`), and never a run or a step.\n- **Levels**: Info is what a person reads in `nemia up`'s lines (`logPass` in `packages\u002Fagent-orchestrator\u002Fsrc\u002Fdaemon\u002Fup.verb.ts`) and\n  each line of the feed, said once as it is written (`emitFeed` in `packages\u002Fagent-orchestrator\u002Fsrc\u002Ffeed\u002Ffeed.verb.ts`); a\n  warning or worse goes to stderr; Debug is the journal, an append said by its kind, below the default level.\n- **One `telemetryLayer`, provided by the process around its program**, never by a verb: `nemia up` in\n  `packages\u002Fagent-orchestrator\u002Fsrc\u002Fcli\u002Fmain.ts` and the api's daemon in `apps\u002Fapi\u002Fsrc\u002Fmain.ts`. A test provides its own logger\n  (`Logger.layer`) and tracer (`Effect.withTracer`), and `References.MinimumLogLevel` to read Debug.\n- **OTLP only when `OTEL_EXPORTER_OTLP_ENDPOINT` is set**, under the service `OTEL_SERVICE_NAME`, `nemia` by default (`otlpOf` in\n  `packages\u002Fagent-orchestrator\u002Fsrc\u002Ftelemetry\u002Ftelemetry.ts`); a test that spawns a daemon sets it, blank where it wants none.\n\n## Tests\n\n`node:test`, with `Effect.runPromise` and the layers provided in the test (`const run` in\n`packages\u002Fagent-runtime\u002Ftest\u002Fengine.test.ts`). No `@effect\u002Fvitest`, though `ai-docs\u002Fsrc\u002F09_testing` uses it.\n\n## Why\n\n`docs\u002Feval-2026-09-28-effect-everywhere.md` weighs Effect in every layer and orders the cards that adopt it.\n",{"name":5,"applies":24,"description":7},[25,26,27,28,29,30,31],"packages\u002Fagent-runtime\u002Fsrc\u002F**","packages\u002Fagent-orchestrator\u002Fsrc\u002F**\u002F*.store.ts","packages\u002Fagent-orchestrator\u002Fsrc\u002F**\u002F*.verb.ts","packages\u002Fagent-orchestrator\u002Fsrc\u002Fruntime-client.ts","packages\u002Fagent-orchestrator\u002Fsrc\u002Fcli\u002F**","apps\u002Fapi\u002Fsrc\u002F**","apps\u002Fweb\u002Fsrc\u002Flib\u002Fapi\u002F**","main","2c3b65dc5afd9cba060388bacf97f24a7208d1ee",".claude\u002Fskills\u002Feffect",0,"https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia","https:\u002F\u002Fgithub.com\u002Femyann","Senior Software Engineer","2026-11-15 05:55:45",{"source":8,"skillName":5,"commands":41,"prompt":51,"zipAvailable":52},[42,45,48],{"tool":43,"command":44},"npx","npx skills add emyann\u002Fnemia --skill effect",{"tool":46,"command":47},"bunx","bunx skills add emyann\u002Fnemia --skill effect",{"tool":49,"command":50},"pnpm","pnpm dlx skills add emyann\u002Fnemia --skill effect","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Feffect\u002FSKILL.md",true,[],[55,62,69,76,83,90],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M7BGEY7EKSRDFAB7B9567QKJ","groom-the-inbox","Read each card in play in the inbox against the repository and say, per card, done (the commit on the base that landed it), replaced (the decision or card that did), stale (each fact that moved, what it said and what it says now) or standing, reading closely only what the period touched. For the janitor's step, which proposes and never acts: a person removes or amends each card by the command the check writes.","https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002Fpackages\u002Ftemplates\u002Fsdlc\u002Fskills\u002Fgroom-the-inbox\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M7B4AD0ZJYZ3HAJCCBM4CPTY","write-a-spec","Turn an accepted intent into a spec an engineer can build from in this repository: the goal restated, the approach and why, every path it touches, the steps, the tests that prove it, the risks, and what is still open. For a step that designs a change before anyone builds it.","https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002Fpackages\u002Ftemplates\u002Fsdlc\u002Fskills\u002Fwrite-a-spec\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M7B4A88P2FKWCS1RND507WHE","review-a-change","Review a change in this repository as a second engineer would: against its intent and spec, by reading the diff and the suite's verdict, with findings that name the file, the line and what goes wrong. For a read-only step that decides whether the work goes round again.","https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002Fpackages\u002Ftemplates\u002Fsdlc\u002Fskills\u002Freview-a-change\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M7B4A2HFW8F53E390A2KM0R8","read-the-stats","Read a factory's stats since the janitor's last run, against the same length of time before it, write a short report, and propose one correction per card — an allow or deny by name, a line in an agent's body or a skill, or a refusal kept on purpose — each with the numbers behind it, never one already in the inbox. For the janitor's step, which proposes and never acts.","https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002Fpackages\u002Ftemplates\u002Fsdlc\u002Fskills\u002Fread-the-stats\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M7B49Z4GJ2G8T76X744YHAAN","land-a-branch","Land a run's result on the base branch in this repository's own checkout, the way the step says it lands: make that one act, read its result, and write the message that records what landed — or change nothing and say why it refused. For a gated ending step (workspace: base).","https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002Fpackages\u002Ftemplates\u002Fsdlc\u002Fskills\u002Fland-a-branch\u002FSKILL.md",[],[],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":19},"01M7B49TMM0QAWF5WQ0QBXM9BG","implement-a-change","Build a change from its spec in this repository: tests first where a rule is claimed, small commits, the tests of what changed green for the right reason, and each review finding answered in the next round. For a step that writes the code.","https:\u002F\u002Fgithub.com\u002Femyann\u002Fnemia\u002Fblob\u002Fmain\u002Fpackages\u002Ftemplates\u002Fsdlc\u002Fskills\u002Fimplement-a-change\u002FSKILL.md",[],[]]