@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/design-ui/references/components.md

@@ -0,0 +1,33 @@
+# Component details
+
+## Feedback and continuity
+
+Give a button clear pressed and pending states. Keep the control available
+according to the action's actual lifecycle; decorative motion should not add
+latency. Scale can provide press feedback when it does not compromise text or
+hit targets.
+
+For related tooltips in a toolbar, consider a shared delay policy: delay the
+first discovery, then let nearby tooltips appear promptly as the user explores.
+Keep hoverable surfaces reachable across small gaps and usable by keyboard.
+
+For toasts and other transient content, consider pausing dismissal while the
+user interacts or the page is hidden. Repeated additions and dismissals must
+preserve readable order and stable pointer targets.
+
+## Defaults and API design
+
+Choose useful defaults before adding options. Expose variations that represent
+real product needs. Keep the public API simple without concealing ownership or
+introducing global state that conflicts with the application architecture.
+
+Use realistic content to judge density, alignment, wrapping, and truncation.
+Compare populated, empty, pending, error, and overflow states when they are
+relevant to the component. Retain focus and selection through updates.
+
+## Evaluate
+
+Exercise the flow at normal speed before slow inspection. Compare against the
+rest of the product. If two presentations are both viable and the user wants
+exploration, use a small set of working prototypes with explicit tradeoffs.
+Do not turn a small polish task into a mandatory redesign or multi-day review.

package/skills/design-ui/references/exploration.md

@@ -0,0 +1,50 @@
+# Explore UI alternatives
+
+Build distinct responses to the requested brief. Keep the exploration separate
+from production integration until the user chooses or delegates the choice.
+
+## Alternatives
+
+Identify the component's job, surrounding UI, existing tokens, and important
+interaction states. Choose a small set of directions that differ in layout,
+density, hierarchy, or interaction. Three is a useful starting point, not a quota.
+Name the distinction so the user knows what each alternative explores.
+
+Build in an isolated route or page when there is a project, or in a standalone
+artifact when appropriate. Make relevant interactions work with realistic
+content. Use the same surrounding context to make comparison meaningful.
+
+Run the alternatives and check the interactions and console. Capture useful
+evidence when tools permit. Present the picker with a short explanation of
+each direction's tradeoff. Leave the selection to the user unless they have
+already asked you to choose.
+
+## Comparison control
+
+Use a compact, accessible selector that stays clear of the work. Render one
+alternative at full size unless side-by-side comparison better serves the
+request. Make the active selection explicit to sighted and assistive users.
+
+Provide buttons and optionally number or arrow shortcuts. Ignore shortcuts
+while the user edits an input or holds a modifier. Keep the selector usable by
+keyboard, show focus, and give each alternative a descriptive name.
+
+Preserve selection across reload when useful, for example with a validated URL
+parameter. Invalid or missing selections fall back to a valid alternative.
+Switch promptly; avoid adding a transition that obscures the differences.
+
+Add replay only for motion that needs it. Define whether changing alternatives
+resets their interaction state; use a keyed remount when reset is intended.
+Adapt appearance to the project and ensure the picker never covers the behavior
+being evaluated.
+
+## Promote a selection
+
+Integrate the selected design using the repository's existing component,
+state, and style ownership. Preserve the chosen behavior and verify it in the
+real destination. The prototype may have simplified data or lifecycle handling
+that needs the application's established implementation.
+
+Remove temporary alternatives and the picker after integration unless the user
+wants them retained. For another exploration round, keep useful infrastructure
+and vary the chosen direction according to the new brief.

package/skills/design-ui/references/libraries.md

@@ -0,0 +1,39 @@
+# Choose a UI library
+
+Match the requested capability to the choices below, then inspect dependencies
+and architecture. If the user names a library, answer about that library; explain
+a material mismatch before suggesting a replacement. Keep an adequate installed
+dependency. Install or migrate only within the requested scope.
+
+Effect Atom is our default for shared React state, queries, and mutations.
+Preserve an existing application's state architecture unless migration is part
+of the task. For theme handling, read [themes](themes.md).
+
+## Curated choices
+
+These are Dev Kit defaults, subject to the user's chosen tools and repository
+conventions. Check current official documentation before adopting a dependency.
+
+| Capability                                                   | Default                                                                                                      |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| Accessible unstyled dialogs, menus, selects, and popovers    | [Base UI](https://base-ui.com)                                                                               |
+| Command menus                                                | [cmdk](https://cmdk.paco.me)                                                                                 |
+| Toasts                                                       | [Sonner](https://sonner.emilkowal.ski)                                                                       |
+| One-time password inputs                                     | [input-otp](https://input-otp.rodz.dev)                                                                      |
+| Interactive control panels                                   | [Leva](https://github.com/pmndrs/leva); consider [dialkit](https://joshpuckett.me/dialkit) for motion tuning |
+| Springs, layout animation, exit animation, and gestures      | [Motion](https://motion.dev); use CSS for simple transitions                                                 |
+| Animated numbers                                             | [NumberFlow](https://number-flow.barvian.me)                                                                 |
+| Animated text                                                | [torph](https://torph.lochie.me/)                                                                            |
+| 3D globes                                                    | [Cobe](https://cobe.vercel.app)                                                                              |
+| Generated SVG or social images                               | [Satori](https://github.com/vercel/satori)                                                                   |
+| Syntax highlighting                                          | [Shiki](https://shiki.style)                                                                                 |
+| Streaming charts                                             | [Liveline](https://github.com/benjitaylor/liveline)                                                          |
+| General dashboard charts                                     | [Recharts](https://recharts.org)                                                                             |
+| Drag and drop                                                | [dnd kit](https://dndkit.com)                                                                                |
+| Long-list virtualization                                     | [Virtuoso](https://virtuoso.dev)                                                                             |
+| Shared React state, server queries, mutations, and workflows | Effect Atom; consult the installed Effect documentation and `effect-development` skill when available        |
+| Conditional class names                                      | [clsx](https://github.com/lukeed/clsx)                                                                       |
+| Typed component style variants                               | [CVA](https://cva.style)                                                                                     |
+
+For a capability outside this list, say that the recommendation is outside the
+curated defaults and establish its fit from current primary sources.

package/skills/design-ui/references/themes.md

@@ -0,0 +1,23 @@
+# Theme ownership
+
+Inspect the existing theme preference, CSS selector, document bootstrap, and
+server rendering path before choosing a library. Reuse that implementation
+when it already supports the requested behavior.
+
+For our Effect Atom and TanStack applications, keep the shared preference in
+the existing atom or settings service. Let one document integration apply the
+resolved theme. Avoid introducing another state provider for the same value.
+
+Distinguish the saved preference, such as light, dark, or system, from the
+resolved color scheme. A system preference should continue following system
+changes. Use the project's existing persistence and SSR conventions to make
+first paint agree with hydration. A browser-only preference needs an appropriate
+pre-paint bootstrap; a server-readable preference must still handle first visits
+and system settings. Verify reload, navigation, and preference changes.
+
+`next-themes` has React and React DOM peer dependencies, not a Next.js runtime
+dependency. It can be considered when a project wants its behavior, but is not
+our blanket default. Check how its provider and injected script fit the actual
+SSR setup rather than copying Next.js layout instructions into TanStack Start.
+See the [package metadata](https://github.com/pacocoursey/next-themes/blob/main/next-themes/package.json)
+and [official usage guide](https://github.com/pacocoursey/next-themes).

package/skills/dev-kit/SKILL.md

@@ -1,48 +1,29 @@
 ---
 name: dev-kit
-description: Set up or reshape TypeScript repositories through agent-led, repo-owned changes. Use when scaffolding a new repository, establishing or modernizing project tooling, adding an application or package, composing a Cloudflare Worker API, ejecting legacy dev-kit.jsonc and dev-kit.lock.json management, or copying and updating curated agent skills with the transient Dev Kit CLI.
+description: Set up TypeScript repositories, change project tooling, migrate legacy Dev Kit management, or maintain repository skills.
 ---
 
 # Dev Kit
 
-Build repositories from intent, then leave every output under normal repository
-ownership. Use the transient CLI for catalog and migration mechanics; use agent
-judgment for architecture and configuration.
+Build from the user's requirements and leave outputs under normal repository
+ownership. Use the transient CLI for catalog and migration mechanics; inspect
+the existing repository before changing its architecture or configuration.
 
-## Route
+Read only the references for the requested work:
 
-Read every reference whose branch applies before editing:
+- Scaffold or reorganize a repository: [repository setup](references/repository-setup.md).
+- Adopt the Dev Kit default or Vite+ foundation:
+  [TypeScript defaults](references/default-typescript-repository.md).
+- Add or configure a Cloudflare Worker API:
+  [Worker API](references/cloudflare-worker-api.md).
+- Remove legacy Dev Kit manifests or managed configuration:
+  [legacy ejection](references/legacy-eject.md).
+- Discover, add, update, fork, or detach skills: [skills](references/skills.md).
 
-- Read [repository-setup.md](references/repository-setup.md) for every new,
-  existing, or expanded repository.
-- Read [default-typescript-repository.md](references/default-typescript-repository.md)
-  when the user wants the Dev Kit default or a Vite+ TypeScript foundation.
-- Read [cloudflare-worker-api.md](references/cloudflare-worker-api.md) when adding
-  a Cloudflare Worker, Worker API, bindings, Durable Objects, or Wrangler.
-- Read [legacy-eject.md](references/legacy-eject.md) when `dev-kit.jsonc`,
-  `dev-kit.lock.json`, `.dev-kit/state.json`, managed markers, or Dev Kit config
-  imports exist.
-- Read [skills.md](references/skills.md) when discovering, adding, refreshing,
-  merging, or detaching repository skills.
+Preserve repository conventions and existing authorization. Explain material
+architecture or dependency choices when they affect the outcome; infer routine
+placement and naming from the project. Follow installed API documentation and
+the repository's command authority, including its Effect and testing policies.
 
-## Workflow
-
-1. Establish the Git root and read repository instructions. Inventory package
-   manifests, workspaces, tool configuration, source boundaries, CI, and current
-   validation commands. Finish with every existing convention that constrains
-   the change accounted for.
-2. Translate the request into outcomes and invariants. Resolve consequential
-   choices with the user; infer naming and file placement from repository
-   evidence. Finish with a coherent target architecture rather than a list of
-   templates.
-3. Present the material file, dependency, and command changes before broad or
-   destructive work. Treat existing files as repository-owned and reconcile
-   them in place.
-4. Implement against current installed APIs and local documentation. When the
-   repository uses Effect, read `node_modules/effect/AGENTS.md` completely before
-   writing Effect code and follow its relevant references.
-5. Run the repository's command authority and exercise the changed behavior.
-   Finish when validation passes and the generated setup works from the same
-   entry points future contributors will use.
-6. Hand off the architecture and any deliberate choices. The finished repository
-   has no Dev Kit dependency, manifest, lock, lifecycle hook, or managed output.
+Verify the changed entrypoints with the normal project commands. Generated
+repositories keep no Dev Kit runtime dependency or lifecycle manager.

package/skills/dev-kit/references/cloudflare-worker-api.md

@@ -1,6 +1,6 @@
 # Cloudflare Worker API
 
-Use the `build-effect-apis`, `workers-best-practices`, and `wrangler` skills when
+Use the `effect-development` and `cloudflare-workers` skills when
 they are available. Read current installed or primary Cloudflare documentation
 before choosing Wrangler configuration, compatibility dates, bindings, or local
 development commands.

package/skills/dev-kit/references/skills.md

@@ -12,8 +12,8 @@ prefer the narrowest matching skills:
 
 ```bash
 bunx @danieljvdm/dev-kit@latest skills search cloudflare
-bunx @danieljvdm/dev-kit@latest skills info workers-best-practices
-bunx @danieljvdm/dev-kit@latest skills add workers-best-practices wrangler
+bunx @danieljvdm/dev-kit@latest skills info cloudflare-workers
+bunx @danieljvdm/dev-kit@latest skills add cloudflare-workers
 ```
 
 Treat source families as broad selections: add one only when every member applies.

package/skills/effect-development/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: effect-development
+description: Set up Effect, implement Atom React state, HTTP APIs or CLIs, and review Effect architecture.
+---
+
+# Effect development
+
+Read the repository's `node_modules/effect/AGENTS.md` completely before writing
+or evaluating Effect code, then follow its relevant links. Installed declarations
+and repository policy own version-sensitive APIs and verification commands.
+
+Read only the guide for the requested boundary:
+
+- React queries, mutations, shared state, workflows, or SSR: [Effect Atom](references/atom/index.md).
+- HTTP contracts, handlers, middleware, or server runtimes: [HTTP APIs](references/api/index.md).
+- Scripts, CI automation, or command-line applications: [CLIs](references/cli/index.md).
+- A requested architecture review or service-boundary refactor: [architecture](references/architecture/index.md).
+- Adding Effect dependencies or its agent guidance: [setup](references/setup.md).
+
+For Effect React applications, Effect Atom owns shared state and server data;
+React renders and dispatches. View-local state can stay in React. Keep business
+logic in Effect workflows and declare cross-query invalidation as mutation
+reactivity keys. Read the Atom guide for runtime and registry ownership.
+
+Preserve the requested scope. A component edit does not require a server rewrite
+or architecture audit. Follow repository policy for committed tests; changes to
+an atom, endpoint, or script do not by themselves justify a new test.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Effect Development"
+  short_description: "Effect Atom state, APIs, scripts, and architecture"
+  default_prompt: "Use $effect-development for this Effect change, reading only the guide for its client, server, CLI, or architecture boundary."

package/skills/effect-development/references/api/index.md

@@ -0,0 +1,32 @@
+# Effect HTTP APIs
+
+Use the shared `HttpApi` value as the source for request and response schemas,
+server handlers, generated documentation, and clients. Keep transport contracts
+isomorphic and runtime behavior in handlers, services, and Layers.
+
+Read repository Effect instructions and inspect installed declarations for
+version-sensitive APIs. Existing imports and the lockfile establish the version
+being changed; a name from another release is not a reason to upgrade it.
+
+## Read for the changed boundary
+
+- Endpoint schemas, errors, groups, or API composition:
+  [shared contracts](shared-contracts.md).
+- Handler implementation, middleware, or request-scoped services:
+  [server and middleware](server-and-middleware.md).
+- Schema codec selection: [typed codecs](schema-codecs.md).
+- Server entrypoint or generated API documentation:
+  [runtime assembly](runtime-assembly.md).
+- Workers bindings, Durable Objects, streams, or raw transport routes:
+  [Cloudflare Workers](cloudflare-workers.md).
+- Cross-boundary verification: [verification](verification.md).
+
+For React client queries, mutations, and invalidation, read the
+[Effect Atom guide](../atom/index.md).
+Change consumers when the requested contract or server change affects them.
+
+Let schemas own wire encoding and validation, handlers adapt transport to the
+application, and services own orchestration and persistence. Assemble required
+Layers at the runtime boundary. Verify changed request and failure behavior with
+the repository's commands and testing policy; adding an endpoint does not imply
+a new committed test.

package/skills/effect-development/references/api/schema-codecs.md

@@ -0,0 +1,15 @@
+# Typed Schema codecs
+
+Match the codec to the type known at the call site. Use the typed decode variant
+when the input is the schema's Encoded type, and the typed encode variant when
+it is the schema's Type. Consult installed declarations for the Effect, Sync,
+Exit, Option, Result, or Promise form needed by that boundary.
+
+Reserve unknown codecs for values whose declared type is actually unknown,
+such as untyped JSON, external messages, or persistence results. A static
+mismatch with a Schema.Class is not a reason to bypass type checking; construct
+or map the correct schema value first.
+
+Follow the repository's policy for lint suppressions at justified untyped
+boundaries. Keep the explanation with the boundary rather than duplicating it
+across contract consumers.

package/skills/{build-effect-apis/references → effect-development/references/api}/verification.md

@@ -1,5 +1,10 @@
 # Verification
 
+Follow repository testing policy. Use existing checks and direct requests when
+sufficient; add committed tests only for an authorized or evidenced regression.
+Choose from the scenarios below based on the changed boundary, rather than
+creating a test suite for every endpoint edit.
+
 Test the contract spine at its seams. Use the repository's established Effect
 test integration and command authority.
 
@@ -48,8 +53,8 @@ decoding are skipped.
   `HttpApiMiddleware.layerClient` and assert that it transforms the request.
 - Assert params, query, headers, payload, and expected errors at least once for
   every changed request shape.
-- For Atom clients, complete every applicable scenario in the
-  `$effect-atom-state` skill's testing reference; use a deterministic HTTP
+- For Atom clients, select the relevant scenarios from the
+  [Effect Atom testing reference](../atom/effect-atom-testing.md); use a deterministic HTTP
   layer so request encoding, invalidation, and lifecycle remain observable.
 
 ## Completion matrix
@@ -60,6 +65,6 @@ Account for every changed endpoint across these columns:
 | ------------------------------------------------ | -------------------------------- | -------------------------------- | ---------------------------------------------- | -------------------------------- |
 | Params, query, headers, payload, success, errors | Scope, provided services, errors | Identifier, invariants, workflow | Typed call shape, identity, cache/invalidation | Round-trip and boundary behavior |
 
-Completion means every changed endpoint has an entry in every applicable
-column, every unknown codec call has a concrete boundary justification, and the
-repository's formatter, linter, typechecker, and tests pass.
+Use the matrix when it helps trace a cross-boundary change. Completion means
+the changed behavior is verified, untyped boundaries are justified, and the
+repository's required checks pass. Empty test cells do not mandate new tests.

package/skills/{effect-architecture-audit/SKILL.md → effect-development/references/architecture/index.md}

@@ -1,15 +1,10 @@
----
-name: effect-architecture-audit
-description: Audit an Effect TypeScript codebase's services, Layers, dependency ownership, hidden requirements, test substitutes, Schema boundaries, assertions, unknown values, and typed error channels. Use for architecture reviews, service refactors, dependency-injection audits, and type-boundary investigations; do not use as a general Effect API reference.
----
-
 # Audit Effect Architecture
 
 Read the target repository's `node_modules/effect/AGENTS.md` completely before
 evaluating Effect code. Follow its version-matched references for library APIs;
 use this skill only for the application-architecture judgments it does not own.
 
-Read [service-and-boundary-audit.md](references/service-and-boundary-audit.md),
+Read [service-and-boundary-audit.md](service-and-boundary-audit.md),
 then:
 
 1. Establish the repository's local architecture and testing rules.

package/skills/{effect-atom-state/references → effect-development/references/atom}/effect-atom-client.md

@@ -11,10 +11,10 @@ and expected errors owned by the contract.
 
 ## Inventory the client boundary
 
-Before changing Atom code, locate every `RegistryProvider`, runtime factory,
-`AtomHttpApi.Service`, query atom, mutation atom, reactivity-key constructor,
-and route aggregate. Confirm the installed `effect` and `@effect/atom-react`
-versions before copying signatures.
+Trace the affected queries and mutations through their `RegistryProvider`,
+runtime, `AtomHttpApi.Service`, and reactivity keys. Expand the inspection only
+when ownership or invalidation crosses another boundary. Confirm installed
+`effect` and `@effect/atom-react` versions before copying signatures.
 
 ## Build one Atom API service
 
@@ -127,8 +127,10 @@ Choose invalidation breadth from the server write:
 - invalidate every affected namespace when a write crosses aggregates.
 
 Combine invalidation with manual refresh only when two requests are intended.
-Keep navigation, toasts, form reset, and presentation-level optimistic state
-with the initiating UI.
+Keep mutation-dependent sequencing and optimistic state in the owning workflow
+atom. React renders and dispatches; view-local input and presentation state can
+stay in React. See [workflows](effect-atom-workflows.md) when the action needs
+optimistic updates, navigation, or other follow-up behavior.
 
 ## Use a direct client outside React
 

package/skills/{effect-atom-state/references → effect-development/references/atom}/effect-atom-testing.md

@@ -1,8 +1,13 @@
 # Deterministic Effect Atom testing
 
+Use this reference only when a test is requested or warranted by repository
+policy. Select the cases that reproduce the relevant failure; this is not a
+required suite for every changed atom. Existing tests and app verification may
+already cover the behavior.
+
 Test cache policy below React first with `AtomRegistry.make()`. Add a React
-integration test for provider placement, hook behavior, browser-only SSR
-boundaries, hydration, or Strict Mode ownership.
+integration test only when the failure involves provider placement, hook
+behavior, browser-only SSR boundaries, hydration, or Strict Mode ownership.
 
 Use fake timers, a request counter, controllable Effects, and explicit mounts:
 

package/skills/effect-development/references/atom/index.md

@@ -0,0 +1,40 @@
+# Effect Atom state
+
+Effect Atom owns shared client state and server data in an Effect application.
+React renders results and dispatches actions. Keep workflows, optimistic updates,
+and cross-query invalidation in Effect; keep view-local state in React.
+
+Read the repository's Effect instructions and inspect installed declarations for
+the APIs being changed. Preserve existing runtime and registry ownership.
+
+## Read for the changed boundary
+
+- API clients, queries, or mutations: [client state](effect-atom-client.md).
+- Multi-step actions, optimistic updates, or Promise dispatch:
+  [workflows](effect-atom-workflows.md).
+- Registry scope, atom identity, retention, freshness, polling, or cancellation:
+  [lifecycle](effect-atom-lifecycle.md).
+- TanStack Start loaders, SSR, hydration, or server functions:
+  [TanStack Start](tanstack-start.md).
+- A regression test allowed by repository policy or explicitly requested by the
+  user: [testing](effect-atom-testing.md). Read only the relevant cases.
+
+## Ownership constraints
+
+- Derive clients from the shared HTTP contract. Change contracts and server
+  handlers with the [HTTP API guide](../api/index.md) when that work is in scope.
+- Declare cross-query invalidation as mutation reactivity keys. Queries and
+  mutations that must invalidate each other need the same Reactivity instance.
+- Compose multi-step actions in workflow atoms. Return Promise-mode dispatch
+  directly to a component with a Promise-shaped contract; put success, failure,
+  and sequencing logic in the Effect workflow.
+- Keep optimistic state with the workflow that writes it, keyed by entity where
+  needed. Preserve ordinary controlled inputs and view-local toggles in React.
+- Reuse the application's state layer instead of introducing another query or
+  shared-state library for a single component.
+
+## Verify
+
+Follow the repository's command authority and testing policy. Exercise the
+changed user flow and the relevant invalidation or lifecycle behavior. Reuse
+existing checks; changed atoms do not by themselves justify committed tests.

package/skills/{build-effect-clis/references → effect-development/references/cli}/entrypoints-and-testing.md

@@ -34,14 +34,18 @@ Use `BunRuntime` and `BunServices` together when Bun owns the executable. Let
 If expected errors need custom presentation, catch and render them immediately
 before `runMain` while preserving CLI control-flow errors such as help output.
 
-## Test at three seams
+## Choose a verification boundary
+
+Follow repository testing policy before adding a committed test. Use existing
+checks or direct command execution when sufficient. The options below are
+alternatives selected by the changed behavior, not a required three-part suite.
 
 1. Test application services directly with deterministic Layers. Cover domain
    success, expected failure, interruption, and plan/apply separation without
    involving argument parsing.
 2. Test thin command handlers through their services when CLI input mapping or
    output-mode selection contains meaningful logic.
-3. Spawn the real executable for boundary behavior. At minimum cover:
+3. Spawn the real executable for boundary behavior. Select relevant cases:
    - root and changed-command `--help`;
    - representative valid arguments and flags;
    - missing or invalid input and a non-zero exit;

package/skills/effect-development/references/cli/index.md

@@ -0,0 +1,39 @@
+# Effect scripts and CLIs
+
+Use Effect for new executable TypeScript scripts in an Effect repository.
+For an existing script, follow repository policy and the requested scope.
+A small maintenance edit does not require converting the whole script;
+undertake that migration when requested or necessary for the change.
+
+When changing Effect behavior, read `node_modules/effect/AGENTS.md` and the
+relevant CLI or process reference. A help-text-only edit in an existing script
+needs its declared entrypoint and help output; it does not require API research.
+Use installed signatures and sibling Effect programs when implementing behavior.
+
+## Choose the reference
+
+- Designing public arguments, flags, or subcommands:
+  [command design](command-design.md).
+- Files, environment, terminal, subprocesses, or runtime differences:
+  [processes and platform](processes-and-platform.md).
+- Executable startup, import safety, or verification:
+  [entrypoints and testing](entrypoints-and-testing.md).
+
+## Boundaries
+
+Use Effect platform services for capabilities. When a required capability is
+missing, isolate the runtime call in a typed Effect adapter. Keep fixed scripts
+simple; they need no command tree when they expose no public command syntax.
+
+Arguments and flags own CLI input; schemas own structured input and output.
+Handlers adapt input and presentation, services own application behavior, and
+Layers supply capabilities. One executable edge owns the runtime and signals.
+Keep expected failures typed and preserve a nonzero exit for failure.
+
+Keep stdout stable for machine-readable output and send diagnostics elsewhere.
+Automation must be able to supply required inputs without a terminal. For
+consequential mutations, expose a preview or dry-run when useful and honor
+existing authorization. Prompt only on intentionally interactive paths.
+
+Verify through the declared entrypoint with the repository's command authority.
+Test only the changed behavior and follow repository policy for committed tests.

package/skills/effect-development/references/setup.md

@@ -0,0 +1,15 @@
+# Set up Effect
+
+Inspect the package boundaries and existing Effect version first. Use the
+repository's package manager and version policy to add Effect where it is
+needed. In a monorepo, make its source and instructions available at the root
+when that is how agents inspect installed APIs. Avoid an unrelated upgrade or
+copying a package-manager command from a different project.
+
+Ensure repository agent instructions direct Effect work to the installed
+`node_modules/effect/AGENTS.md`, require reading it completely before writing
+Effect code, and follow its relevant links. For APIs not covered there, consult
+`node_modules/effect/src`.
+
+Preserve existing agent guidance and keep one pointer to the installed source
+instead of copying library instructions into the repository.

package/skills/open-pull-request/SKILL.md

@@ -1,78 +1,18 @@
 ---
 name: open-pull-request
-description: Prepare, open, update, or land pull requests with brief summaries, architecture diagrams, API examples, and useful screenshots or videos.
+description: Prepare, open, update, or land pull requests with concise explanations and relevant review evidence.
 ---
 
 # Pull requests
 
-Give the reviewer a high-level account of what changed and why. Usually a
-short paragraph or a few bullets is enough. Add a risk, limitation, or manual
-deploy step only when it affects their decision. Skip code tours, investigation
-history, routine CI recaps, and prescribed sections or accordions.
+Lead with the concrete problem and resulting behavior. Give reviewers the
+context needed to assess the final change; simple changes need only a brief
+summary and relevant validation.
 
-## Explain architecture and APIs
+- Ownership, data flow, or API changes: [diagrams and examples](references/explanation.md).
+- UI or other visible behavior: [capture and publish evidence](references/evidence.md).
+- Commits, publication, readiness, or landing: [PR workflow](references/publication.md).
 
-Pick the smallest view that makes the change clear, and place it beside the
-short explanation it supports. Prefer a diagram or example over a long prose
-description; simple changes can stay prose-only.
-
-- For changes to component ownership, boundaries, or data flow, include a
-  focused Mermaid architecture chart. Use a sequence diagram when call order
-  matters. Name the actual components, label the interactions, and make the
-  changed responsibility or path clear without mapping the whole system.
-- For new or changed APIs, show a concrete caller example: an HTTP request and
-  response, or a typed function/SDK call and its result. Include the inputs,
-  outputs, and error behavior relevant to the change. Use a small before/after
-  diff when callers must migrate; show the complete example when the API is new.
-
-Use fenced Mermaid and code blocks directly in the PR. A call tree or pseudocode
-can replace a chart when it explains the change more clearly. Match diagrams
-and examples to the final implementation, use safe fixture data, and distinguish
-illustrative or expected output from output actually observed during validation.
-Include both a chart and an API example when they answer different review
-questions, not just to fill sections.
-
-## Capture visible behavior
-
-For UI or visible features, capture the final running implementation during
-verification and reuse it for the PR. A screenshot is the default; use a short
-video when the sequence matters, such as an agent exchange or animation. Both
-are rarely needed. Nonvisual changes need no screenshots or recordings.
-
-Use existing capture tools; load `playwright-cli` for browser capture. Keep
-recordings focused, usually under 30 seconds, without changing product timing.
-Use safe fixture data and review the image or whole clip once for correctness
-and private content. Treat published assets as public; unreviewed media stays
-local. If inspection is unavailable, use a safe alternative or report the
-blocker. Do not build viewers, extract frame galleries, or reconstruct GitHub.
-
-Publish reviewed media with:
-
-```sh
-vp run publish-pr-asset -- <file> <label> --caption "What this shows"
-```
-
-Use the returned Markdown in the PR. Keep originals until publication succeeds;
-if it fails, report the exact local path. Never extract browser cookies, expose
-credentials in arguments, create asset branches, or invent an upload service.
-
-## Open or update the PR
-
-For an already verified change, aim to publish within two minutes:
-
-1. Check the base, branch diff, and working tree for accidental changes. Reuse
-   review, validation, and evidence already completed for unchanged inputs;
-   `AGENTS.md` owns required checks.
-2. Use Conventional Commits for commits and the title. Commit and push the
-   intended changes, preserving unrelated work and published history.
-3. Open or update the PR with the short body, useful diagrams or API examples,
-   and existing evidence. With `gh`, use `--body-file` for multiline text.
-4. Read back base/head, title, and body once with `gh pr view`, then return the
-   URL. No GitHub browser inspection or wait for CI is required to open it.
-
-Follow `AGENTS.md` for merge approval and required checks; opening a PR does
-not authorize merging it.
-
-When an existing draft PR is the subject, interpret "open it" or "ready it"
-as making it ready for review unless the user asks to view it. State the intended
-transition before acting; use `gh pr ready` rather than opening a browser.
+Reuse verification and captures for unchanged inputs. Include limitations or
+manual steps when they affect review. Follow repository merge policy and
+existing authorization; opening a PR does not authorize merging it.