@danieljvdm/dev-kit 0.13.0 → 0.15.0

package/README.md

@@ -179,6 +179,7 @@ tool versions. A project-local process lock also prevents concurrent applies.
   "include": [
     "dev-kit",
     "effect",
+    "open-pull-request",
     "workers-best-practices",
     "wrangler",
     "serve-sim",
@@ -198,18 +199,14 @@ tool versions. A project-local process lock also prevents concurrent applies.
 ```
 
 - `dev-kit` installs guidance for operating the toolkit itself.
-- `effect` expands to the package-guidance `effect-ts` bootstrap, the
-  opinionated `effect-architecture-audit`, `build-effect-apis` for shared HTTP
-  contracts and clients, and `build-effect-clis` for typed command-line
-  applications. The focused references cover Effect Atom, TanStack Start,
-  Cloudflare Workers, child processes, runtime entrypoints, and CLI testing.
-- Prefer individual external skills such as `workers-best-practices` and
-  `wrangler`, selected after scanning the project for relevant technologies.
-- `serve-sim` selects the approved Evan Bacon simulator skill directly.
+- `effect` is a built-in family: the `effect-ts` bootstrap,
+  `effect-architecture-audit`, `build-effect-apis`, and `build-effect-clis`.
+- External Git skills (`workers-best-practices`, `serve-sim`, …) are selected
+  individually after scanning the project for relevant technologies. An
+  approved source ID selects every skill from that source; use it only when
+  the scan confirms that every member applies.
 - `@tanstack/ai#ai-core` explicitly selects a skill discovered in that direct
   project dependency; discovery alone never selects it.
-- An approved source ID is broad shorthand that selects every skill from that
-  source. Use it only when the scan confirms that every member applies.
 
 Dev Kit reserves `.repos/<source-id>` for project-local source checkouts. Run
 `dev-kit gitignore` to add `.repos/` and `.dev-kit/` to the project ignore file.
@@ -235,18 +232,17 @@ bridge in the manifest:
 `AGENTS.md`, preserving handwritten project guidance around them. The Dev Kit
 section contains a short description and a pointer to the installed `dev-kit`
 skill. When the root `package.json` declares `vite-plus` directly, Dev Kit
-renders its own repository-specific Vite+ guidance, including the unified
-toolchain overview, help and documentation entry points, and `vp env doctor`
-troubleshooting. It does not import Vite+'s generic `AGENTS.md`, which can
-conflict with the repository's exact commands; transitive installations do not
-opt a project in. Previously managed Vite+ sections are removed during a safe
-owned update. Ambiguous or malformed managed markers fail closed.
+renders its own repository-specific Vite+ guidance — toolchain overview, help
+and documentation entry points, `vp env doctor` troubleshooting — rather than
+importing Vite+'s generic `AGENTS.md`, which can contradict the repository's
+exact commands; transitive installations do not opt a project in. Ambiguous or
+malformed managed markers fail closed.
 
 The Dev Kit section also renders an opinionated project command policy. A
 direct Vite+ dependency makes `vp` the only supported front door: built-in
 format, lint, and test commands use `vp`, while repository tasks and package
-scripts use `vp run`. When Dev Kit manages the quality config, the canonical
-full validation and typecheck commands are `vp run check` and
+scripts use `vp run`. When the manifest enables the Vite+ workflow scaffold,
+the canonical full validation and typecheck commands are `vp run check` and
 `vp run typecheck`; `vp check` alone is only the Vite+ static-check command.
 Without Vite+, Bun is the required package-script runner and Dev Kit lists only
 quality scripts the root package actually declares. The package manager named
@@ -287,7 +283,7 @@ worktree converges its own copy during install while the project-owned
 ## Vite+ quality setup
 
 The repository always owns `vite.config.ts`. Compose Dev Kit's quality defaults
-from that project-owned config, then opt into the hardened GitHub Actions
+from that project-owned config, then opt into the scaffolded GitHub Actions
 workflow independently:
 
 ```ts
@@ -317,13 +313,6 @@ Project and framework-generated paths belong in `ignorePatterns` as shown;
 custom harness target paths belong there too. Dev Kit does not grow a global
 framework ignore list.
 
-Vite+ 0.2.6 forwards JavaScript-plugin declarations into its effective lint
-config but its bundled native Oxlint path does not register or execute those
-rules. Native Oxlint rules and Oxfmt settings remain active; run standalone
-Oxlint when enforcement of Dev Kit's `effect/*` or
-`stylistic/padding-line-between-statements` rules is required. This limitation
-can be removed once a supported Vite+ release executes configured JS plugins.
-
 ```jsonc
 {
   "include": ["dev-kit", "effect"],
@@ -331,19 +320,24 @@ can be removed once a supported Vite+ release executes configured JS plugins.
     "effectTsgo": { "enabled": true },
     "vitePlus": {
       "hooks": { "enabled": true },
-      "quality": {
-        "workflow": { "enabled": true },
-      },
+      "workflow": { "enabled": true },
     },
   },
 }
 ```
 
-`quality.workflow.enabled` owns `.github/workflows/check.yml` but never reads,
-rewrites, adopts, or removes `vite.config.ts`. Workflow setup requires direct
-`@danieljvdm/dev-kit`, `vite-plus`, `effect`, `@effect/tsgo`, and native
-TypeScript dependencies with `setup.effectTsgo.enabled`. The installed Vite+
-must satisfy Dev Kit's peer range.
+`setup.vitePlus.workflow` scaffolds `.github/workflows/check.yml` and never
+reads, rewrites, adopts, or removes `vite.config.ts`. Scaffolds are
+create-only: the file is written only when missing, never recorded in
+`dev-kit.lock.json`, and never touched again — the repository owns it from
+creation, and disabling the task leaves it in place. Edit the YAML directly
+for repository-specific preparation steps or a custom typecheck command; when
+the shipped template improves, compare against the installed copy under
+`node_modules/@danieljvdm/dev-kit/templates/` and merge what fits.
+Scaffolding requires direct `@danieljvdm/dev-kit`, `vite-plus`, `effect`,
+`@effect/tsgo`, and native TypeScript dependencies with
+`setup.effectTsgo.enabled`, and the installed Vite+ must satisfy Dev Kit's
+peer range.
 
 Workspaces select bounded, dependency-ordered typechecking in their config:
 
@@ -359,44 +353,51 @@ export default defineConfig(
 );
 ```
 
-Each listed package must expose a pure `typecheck` script. Repositories can
-also declare workflow-specific preparation and typecheck commands:
+Each listed package must expose a pure `typecheck` script.
+
+The scaffolded workflow performs one frozen, script-suppressed install, runs
+`dev-kit apply --locked`, and only then runs formatting, linting, tests, and
+`vp run typecheck`. See the primary
+[`setup-vp` versioning guidance](https://github.com/voidzero-dev/setup-vp#versioning),
+[Vite+ install guide](https://viteplus.dev/guide/install), and
+[Vite Task run guide](https://viteplus.dev/guide/run) when maintaining the
+templates.
+
+## Worktrunk project config
+
+Enable a scaffolded default [Worktrunk](https://worktrunk.dev) project config
+in the manifest:
 
 ```jsonc
 {
+  "include": ["dev-kit"],
   "setup": {
-    "effectTsgo": { "enabled": true },
-    "vitePlus": {
-      "quality": {
-        "workflow": {
-          "enabled": true,
-          "beforeChecks": [
-            {
-              "name": "Install media tools",
-              "run": ["sudo apt-get update", "sudo apt-get install --yes ffmpeg"],
-            },
-          ],
-          "typecheck": [
-            "vp run -F './apps/*' -F './packages/*' check",
-            "vp exec tsc --noEmit -p scripts/tsconfig.json",
-          ],
-        },
-      },
-    },
+    "worktrunk": { "config": { "enabled": true } },
   },
 }
 ```
 
-The workflow performs one frozen, script-suppressed install, runs
-`dev-kit apply --locked`, and only then runs preparation, formatting, linting,
-tests, and typechecking. Its default typecheck command is `vp run typecheck`;
-`workflow.typecheck` replaces it. Existing workflows remain user-owned until
-their rendered content matches exactly—Dev Kit never merges YAML. See the
-primary
-[`setup-vp` versioning guidance](https://github.com/voidzero-dev/setup-vp#versioning),
-[Vite+ install guide](https://viteplus.dev/guide/install), and
-[Vite Task run guide](https://viteplus.dev/guide/run) when maintaining the
-templates.
+`setup.worktrunk.config` scaffolds `.config/wt.toml` with the portable hooks an
+app repository wants in every worktree: a `pre-start` pipeline that copies
+gitignored files matched by `.worktreeinclude` (a no-op without that file) and
+then installs dependencies, plus a `pre-merge` full-validation hook. Hook
+commands render for the repository's command runner: a direct `vite-plus`
+dependency selects `vp install` and `vp run check`; otherwise Dev Kit requires
+a declared root `check` package script, runs it through `bun run check`, and
+takes the install command from the detected package manager. Repositories with
+neither fail the plan instead of shipping a broken hook.
+
+The config follows the same create-only scaffold semantics as the check
+workflow above: created once, never locked or touched again, owned by the
+repository. Edit hooks freely after creation.
+
+The config intentionally carries no worktree-path template or other user
+preferences—those belong in each user's `~/.config/worktrunk/config.toml`. A
+commented `post-start` block shows how to run a per-worktree dev server on a
+stable branch-derived port (`{{ branch | hash_port }}`) under `wt step tether`;
+point it at the repository's dev entrypoint and uncomment to opt in. Worktrunk
+never runs project hooks until each user approves them with
+`wt config approvals add`.
 
 ## Effect source checkout
 
@@ -518,31 +519,20 @@ bun x dev-kit add @tanstack/ai#ai-core
 That writes `@tanstack/ai#ai-core` to `dev-kit.jsonc` and, unless
 `--no-apply` is passed, installs it through the normal ownership-safe sync
 path. The qualifier prevents ambiguity when two dependencies publish the same
-skill name, and the installed output carries it too: the copied directory is
-named by flattening the package name (drop `@`, turn every other
-non-alphanumeric run into one dash) and appending the skill name, so
-`@tanstack/ai#ai-core` installs as `tanstack-ai-ai-core`. Agent harnesses
-identify a project skill by its directory name, so the copied `SKILL.md`
-frontmatter `name:` is rewritten to that same install name; all other content
-is copied verbatim. Symlink-mode targets link straight into `node_modules`, so
-only the link itself carries the qualified name while the linked frontmatter
-keeps the upstream bare name. Two selected skills that would both write the
-same destination are rejected before any output is changed.
-
-The initial compatibility boundary is intentionally small and deterministic:
-
-- only packages named in the root project's `dependencies`,
-  `devDependencies`, `optionalDependencies`, or `peerDependencies` are
-  scanned;
-- package code is never imported or executed;
-- npm-style and pnpm/workspace symlinks under `node_modules` are supported;
-- Yarn Plug'n'Play and transitive dependency traversal are not scanned; and
-- immediate `skills/<name>/SKILL.md` roots are listed. Nested topic skills and
-  references remain part of that root and are copied with it.
-
-The last rule adapts Intent's routed, nested skill trees to the immediate folder
-and frontmatter-name invariants expected by Agent Skills targets. Dev Kit does
-not rewrite nested names or ask Intent to manage agent configuration.
+skill name, and the installed output carries it: the copied directory flattens
+the package name and appends the skill name (`@tanstack/ai#ai-core` →
+`tanstack-ai-ai-core`), and the copied `SKILL.md` frontmatter `name:` is
+rewritten to match because harnesses identify a skill by its directory name.
+Symlink-mode targets link straight into `node_modules`, so only the link
+carries the qualified name. Two selections that would write the same
+destination are rejected before any output changes.
+
+The compatibility boundary is intentionally small and deterministic: only the
+root project's direct dependencies are scanned, package code is never imported
+or executed, npm-style and pnpm/workspace symlinks are supported (Yarn
+Plug'n'Play and transitive traversal are not), and only immediate
+`skills/<name>/SKILL.md` roots are listed — nested topic skills and references
+are copied as part of their root.
 
 The project `dev-kit.lock.json` records the selected package name, installed
 version, original bare skill name, and the `node_modules` content digest.
@@ -648,7 +638,11 @@ export default defineConfig({
 The Oxlint preset enables `stylistic/padding-line-between-statements`: adjacent
 variable declarations remain grouped, while the next logical statement and
 all `return` statements require a separating blank line. The rule is fixable,
-so `vp lint --fix` repairs missing spacing automatically.
+so `vp lint --fix` repairs missing spacing automatically. Vite+ 0.2.6 forwards
+the preset's JavaScript-plugin declarations but its native Oxlint path does not
+execute their rules — run standalone Oxlint when `effect/*` or the padding rule
+must be enforced, until a supported Vite+ release executes configured JS
+plugins.
 
 The preset also registers the shared `effect` JavaScript plugin. Effect
 projects opt into its rules in path-specific overrides, for example

package/dev-kit.example.jsonc

@@ -8,9 +8,10 @@
     "effectTsgo": { "enabled": true },
     "vitePlus": {
       "hooks": { "enabled": true },
-      "quality": {
-        "workflow": { "enabled": true },
-      },
+      "workflow": { "enabled": true },
+    },
+    "worktrunk": {
+      "config": { "enabled": true },
     },
   },
   "targets": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danieljvdm/dev-kit",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "private": false,
   "description": "Declarative project development toolkit with portable agent skills.",
   "license": "MIT",

package/schema/dev-kit.schema.json

@@ -48,6 +48,9 @@
         },
         "vitePlus": {
           "$ref": "#/$defs/vitePlusSetup"
+        },
+        "worktrunk": {
+          "$ref": "#/$defs/worktrunkSetup"
         }
       },
       "default": {}
@@ -144,8 +147,8 @@
         "hooks": {
           "$ref": "#/$defs/vitePlusHooksSetup"
         },
-        "quality": {
-          "$ref": "#/$defs/vitePlusQualitySetup"
+        "workflow": {
+          "$ref": "#/$defs/vitePlusWorkflowSetup"
         }
       }
     },
@@ -160,61 +163,35 @@
         }
       }
     },
-    "vitePlusQualitySetup": {
-      "description": "Manage the Vite+ quality workflow while the repository owns and extends vite.config.ts.",
+    "vitePlusWorkflowSetup": {
+      "description": "Scaffold the canonical GitHub Actions check workflow (.github/workflows/check.yml); the repository owns the file after creation.",
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "workflow": {
-          "$ref": "#/$defs/vitePlusQualityWorkflowSetup"
+        "enabled": {
+          "type": "boolean",
+          "default": false
         }
       }
     },
-    "vitePlusQualityWorkflowSetup": {
-      "description": "Manage the canonical GitHub Actions check workflow without requiring Dev Kit to own the Vite config.",
+    "worktrunkSetup": {
+      "description": "Manage project-local Worktrunk setup tasks.",
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "enabled": {
-          "type": "boolean",
-          "default": false
-        },
-        "beforeChecks": {
-          "description": "Repository-specific preparation steps inserted after locked setup verification and before quality checks.",
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/vitePlusQualityWorkflowStep"
-          },
-          "default": []
-        },
-        "typecheck": {
-          "description": "Shell commands for the workflow's pure typecheck step.",
-          "type": "array",
-          "minItems": 1,
-          "items": {
-            "type": "string",
-            "minLength": 1
-          },
-          "default": ["vp run typecheck"]
+        "config": {
+          "$ref": "#/$defs/worktrunkConfigSetup"
         }
       }
     },
-    "vitePlusQualityWorkflowStep": {
+    "worktrunkConfigSetup": {
+      "description": "Scaffold the default Worktrunk project config (.config/wt.toml) with portable pre-start and pre-merge hooks rendered for the repository's command runner; the repository owns the file after creation.",
       "type": "object",
       "additionalProperties": false,
-      "required": ["name", "run"],
       "properties": {
-        "name": {
-          "type": "string",
-          "minLength": 1
-        },
-        "run": {
-          "type": "array",
-          "minItems": 1,
-          "items": {
-            "type": "string",
-            "minLength": 1
-          }
+        "enabled": {
+          "type": "boolean",
+          "default": false
         }
       }
     },

package/skills/build-effect-apis/SKILL.md

@@ -64,6 +64,28 @@ from another version.
   runs on Cloudflare Workers or uses `effect-cf`, bindings, Durable Objects,
   Queues, WebSockets, streaming, or raw byte routes.
 
+## Choose typed Schema codecs by default
+
+Match the codec to the static type at the call site. When decoding a value that
+is already typed as the schema's `Encoded` type, use `Schema.decodeEffect` or
+the typed `Schema.decodeSync`, `Schema.decodeExit`, `Schema.decodeOption`,
+`Schema.decodeResult`, or `Schema.decodePromise` variant. When encoding a value
+that is already typed as the schema's `Type`, use `Schema.encodeEffect` or the
+corresponding typed `Schema.encodeSync`, `Schema.encodeExit`,
+`Schema.encodeOption`, `Schema.encodeResult`, or `Schema.encodePromise` variant.
+
+Reserve `Schema.decodeUnknown*` and `Schema.encodeUnknown*` for genuinely
+untyped boundaries: values from `JSON.parse`, `Response.json`, external
+messages, or persistence APIs whose declared result is actually `unknown`.
+Never choose an unknown codec to bypass a `Schema.Class` or other static type
+mismatch. Map the source value or construct the correct schema `Type` first,
+then use the typed encoder; similarly, establish the correct `Encoded` value
+before using a typed decoder.
+
+This rule is toolchain-neutral. A repository may reinforce it with a lint
+warning and a documented local suppression for a justified untyped boundary,
+but the boundary and type reasoning remain the source of truth.
+
 ## Boundary rules
 
 - Let schemas own wire validation, encoding, status metadata, and branded IDs.

package/skills/build-effect-apis/references/verification.md

@@ -11,6 +11,20 @@ test integration and command authority.
 - Assert each expected error carries the intended HTTP status and body encoding.
 - Compare or smoke-test generated OpenAPI when the public contract changes.
 
+## Unknown codec audit
+
+Inventory every `Schema.decodeUnknown*` and `Schema.encodeUnknown*` call in the
+changed scope. Record a concrete untyped-boundary justification for each one,
+such as `JSON.parse`, `Response.json`, an external message, or a persistence API
+whose declared result is actually `unknown`. Replace any call whose input is
+already the schema's `Encoded` or `Type` with the corresponding typed `Effect`,
+`Sync`, `Exit`, `Option`, `Result`, or `Promise` codec.
+
+An unknown codec is not a valid workaround for a `Schema.Class` or other static
+type mismatch: map or construct the correct typed value instead. If the
+repository enforces this policy with a lint warning, keep any necessary local
+suppression documented with the same concrete boundary justification.
+
 ## Server tests
 
 - Build every changed group and fail the test if an endpoint handler is missing.
@@ -47,4 +61,5 @@ 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 and the repository's formatter, linter, typechecker, and tests pass.
+column, every unknown codec call has a concrete boundary justification, and the
+repository's formatter, linter, typechecker, and tests pass.

package/skills/build-effect-clis/SKILL.md

@@ -1,30 +1,61 @@
 ---
 name: build-effect-clis
-description: Build and maintain command-line applications entirely with Effect. Use when creating or changing CLI commands, arguments, flags, subcommands, prompts, help, JSON output, dry-run or confirmation flows, platform services, child processes, Node/Bun entrypoints, or CLI integration tests.
+description: Write and maintain every executable script and command-line application in an Effect repository as an Effect program. Use when creating or changing any script, one-off automation, CI check, deploy/release/build glue, package-script entrypoint, CLI command, arguments, flags, prompts, child process, filesystem or environment workflow, Node/Bun entrypoint, or integration test—including extending an existing plain-TypeScript script.
 ---
 
-# Build Effect CLIs
+# Build Effect Scripts and CLIs
 
-Treat a CLI as an Effect application: the `Command` tree owns the user-facing
-contract, handlers adapt decoded input into application workflows, services own
-capabilities, and the executable entrypoint supplies platform Layers and runs
-the program. Do not introduce a separate CLI framework for new command work.
+## Effect-first scope
+
+Every executable script and CLI in an Effect repository is an Effect program.
+This includes one-off scripts, CI checks, deploy/release/build glue, files under
+`scripts/`, package-script targets, migrations, and application entrypoints—not
+only polished command-line tools.
+
+Apply this rule when modifying code as well as when creating it. When a task
+touches an existing plain-TypeScript script, convert the whole script to Effect
+in the same change; matching the surrounding file's style or minimizing the
+diff is not a valid exception. Prefer the repository's established Effect
+patterns, including those in sibling scripts, over legacy patterns in the file
+being converted.
+
+Leave a script outside Effect only for a good, concrete technical or user
+constraint that makes Effect unsuitable. Explicitly state that reason before
+proceeding and in the final handoff, and keep the exception as narrow as
+possible. Convenience, one-off status, and existing plain-TypeScript style are
+not sufficient reasons.
+
+Use Effect platform services for filesystem, path, environment, terminal, and
+child-process work. Raw `node:*` or Bun runtime imports, `process.env`, `fs`,
+`path`, `child_process`, and synchronous helpers such as `execFileSync` do not
+belong in script workflows. If the installed Effect platform has no required
+capability, isolate the runtime call in an explicit boundary adapter whose API
+returns an Effect with typed errors, and document why that adapter is required.
+
+Treat each executable as an Effect application. For a CLI, the `Command` tree
+owns the user-facing contract, handlers adapt decoded input into application
+workflows, services own capabilities, and the executable entrypoint supplies
+platform Layers and runs the program. A fixed automation script with no public
+arguments may export an Effect workflow directly instead of inventing a
+`Command` tree. Do not introduce a separate CLI framework for command work.
 
 Effect CLI and process APIs are version-sensitive. Read the target repository's
 `node_modules/effect/AGENTS.md` completely, follow its CLI and child-process
 references, and confirm exact signatures from the installed declarations before
 editing.
 
-## Build the command boundary
+## Build the executable boundary
 
 1. Inventory the existing executable entrypoints, package scripts, command
    tree, shared flags, prompts, application services, platform Layers, output
    modes, and subprocess helpers. Finish when every way to invoke and test the
-   CLI is known.
-2. Read [command-design.md](references/command-design.md). Define arguments and
-   flags with `Argument` and `Flag`, compose commands with `Command`, and give
-   every public input useful help. Use `Effect.fn` handlers and yield the root
-   command when a subcommand needs shared parent input.
+   affected scripts or CLI is known, including sibling Effect scripts whose
+   patterns should replace legacy plain-TypeScript style.
+2. When the executable accepts public arguments or flags, read
+   [command-design.md](references/command-design.md). Define arguments and flags
+   with `Argument` and `Flag`, compose commands with `Command`, and give every
+   public input useful help. Use `Effect.fn` handlers and yield the root command
+   when a subcommand needs shared parent input.
 3. Keep handlers thin. Decode user and file input at the boundary, enforce
    cross-input invariants, then call an application service. Keep persistence,
    network calls, orchestration, retries, and transactions in services.
@@ -32,15 +63,15 @@ editing.
    platform failures into application-owned errors near the adapter that knows
    what the operation means. Let defects remain defects.
 5. Read [entrypoints-and-testing.md](references/entrypoints-and-testing.md).
-   Export the command tree without running it, wire one Node or Bun entrypoint,
-   and verify help, parsing, successful execution, expected failure, JSON
-   output, and every dry-run or confirmation path.
+   Export the command tree or fixed script workflow without running it, wire
+   one Node or Bun entrypoint, and verify the applicable success, expected
+   failure, help, parsing, JSON, dry-run, and confirmation paths.
 
 ## Optional branches
 
 - Read [processes-and-platform.md](references/processes-and-platform.md) when a
-  command reads files, inspects the environment, starts child processes,
-  streams their output, or differs between Node and Bun.
+  script or command reads files, inspects the environment, starts child
+  processes, streams their output, or differs between Node and Bun.
 - Use `Prompt` only for an intentionally interactive path. Keep required inputs
   expressible as arguments or flags so automation never depends on a terminal.
 - Add `--dry-run` for commands that mutate important state and `--yes` for

package/skills/build-effect-clis/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "Build Effect CLIs"
-  short_description: "Build typed Effect command-line applications"
-  default_prompt: "Use $build-effect-clis to build a typed Effect CLI with clear commands, platform boundaries, and tests."
+  display_name: "Build Effect Scripts and CLIs"
+  short_description: "Write every script and CLI with Effect"
+  default_prompt: "Use $build-effect-clis to write or modify this script or CLI as an Effect program with explicit platform boundaries and tests."

package/skills/build-effect-clis/references/entrypoints-and-testing.md

@@ -4,6 +4,11 @@ Separate command definition from execution. Importing a command module in a test
 or another program must not parse `process.argv`, start fibers, or terminate the
 process.
 
+For a fixed CI or automation script with no public command syntax, export its
+Effect workflow and provide platform Layers only in a thin executable module;
+it does not need an artificial `Command` tree. Use the same `runMain` boundary,
+typed failures, platform services, and import-safety rules shown below.
+
 ```ts
 // src/cli/command.ts
 export const command = root.pipe(Command.withSubcommands([deploy, status]));

package/skills/build-effect-clis/references/processes-and-platform.md

@@ -1,8 +1,9 @@
 # Processes and platform services
 
 Use Effect platform services inside CLI workflows. Keep direct `node:*`, Bun
-globals, `process`, filesystem calls, and shell execution at explicit adapters
-or the executable boundary.
+globals, `process`, filesystem calls, and shell execution inside explicit
+boundary adapters. The executable boundary itself should use Effect platform
+runtime and service APIs.
 
 ## Own subprocess behavior in a service