@danieljvdm/dev-kit 0.12.0 → 0.14.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,9 +199,14 @@ tool versions. A project-local process lock also prevents concurrent applies.
 ```
 
 - `dev-kit` installs guidance for operating the toolkit itself.
+- `open-pull-request` provides a conventional, context-complete PR workflow
+  with terse English descriptions and verified proof of work.
 - `effect` expands to the package-guidance `effect-ts` bootstrap, the
-  opinionated `effect-architecture-audit`, and `build-effect-apis` for shared
-  HTTP contracts, Effect Atom clients, TanStack Start, and Cloudflare Workers.
+  opinionated `effect-architecture-audit`, `build-effect-apis` for shared HTTP
+  contracts and clients, and `build-effect-clis` for typed command-line
+  applications, one-off scripts, and CI/deploy/build automation. The focused
+  references cover Effect Atom, TanStack Start, Cloudflare Workers, child
+  processes, runtime entrypoints, and script/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.
@@ -305,7 +311,9 @@ export default defineConfig({
 
 Spread the returned top-level config before local options. When overriding a
 `fmt`, `lint`, `run`, or `staged` block, spread that returned block as well so
-its defaults remain composed.
+its defaults remain composed. Merge nested collections too; for example, a
+local lint rule block starts with `...recommended.lint.rules` before adding
+repository-specific rules.
 
 The factory configures `vp staged`, matching Oxlint/Oxfmt ignores for Dev Kit's
 tool-owned paths, and separate `vp run check` and pure `vp run typecheck` tasks.
@@ -313,6 +321,13 @@ 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"],
@@ -439,7 +454,30 @@ Pin the compatible packages in the consuming project:
 {
   "$schema": "./node_modules/@effect/tsgo/schema.json",
   "compilerOptions": {
-    "plugins": [{ "name": "@effect/language-service" }],
+    "plugins": [
+      {
+        "name": "@effect/language-service",
+        "diagnosticSeverity": {
+          "anyUnknownInErrorContext": "warning",
+          "instanceOfSchema": "suggestion",
+          "nestedEffectGenYield": "suggestion",
+          "newSchemaClass": "suggestion",
+          "preferSchemaTypeProperty": "suggestion",
+          "unsafeEffectTypeAssertion": "warning",
+        },
+        "overrides": [
+          {
+            "include": ["src/**/*.ts"],
+            "options": {
+              "diagnosticSeverity": {
+                "nodeBuiltinImport": "warning",
+                "preferSchemaOverJson": "suggestion",
+              },
+            },
+          },
+        ],
+      },
+    ],
   },
 }
 ```
@@ -449,7 +487,12 @@ native TypeScript compiler. It does not download dependencies and skips an
 installation that is already patched. Use `dev-kit tsgo patch --dry-run` when
 troubleshooting the task directly.
 
-Dependency and `tsconfig.json` edits remain explicit.
+The same typed object is exported as `recommendedEffectTsgoPlugin` for
+programmatic configuration tooling. Dependency and `tsconfig.json` edits remain
+explicit. In a monorepo, put the plugin in the shared root config and ensure
+every workspace extends it without redeclaring `compilerOptions.plugins`:
+TypeScript replaces that array in child configs rather than merging it. Adjust
+the `src/**/*.ts` override to the source layout seen from each config file.
 
 ## Installed package skills
 

package/package.json

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

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

@@ -0,0 +1,92 @@
+---
+name: build-effect-clis
+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 Scripts and CLIs
+
+## 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 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
+   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.
+4. Keep expected operational failures typed with `Schema.TaggedError`; map
+   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 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
+  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
+  explicitly authorized non-interactive confirmation. Never prompt in JSON or
+  CI-oriented modes.
+
+## CLI ownership rules
+
+- Let `Command`, `Argument`, and `Flag` own syntax, defaults, aliases, examples,
+  and help text.
+- Let schemas own untrusted structured input and machine-readable output.
+- Let handlers own CLI-to-application mapping and presentation selection.
+- Let services own reusable behavior and external capabilities.
+- Let Layers own implementations and runtime dependencies.
+- Let the executable entrypoint own `Command.run`, platform provisioning,
+  scopes, signal handling, and `NodeRuntime.runMain` or `BunRuntime.runMain`.
+- Keep stdout stable for primary or machine-readable output. Send diagnostics
+  and progress elsewhere; never mix prose into JSON output.

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

@@ -0,0 +1,4 @@
+interface:
+  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/command-design.md

@@ -0,0 +1,93 @@
+# Command design
+
+Model the CLI's public surface as a typed contract. Prefer a small root command,
+shared parent flags, focused subcommands, and Effect handlers.
+
+```ts
+import { Effect } from "effect";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+
+const workspace = Flag.string("workspace").pipe(
+  Flag.withAlias("w"),
+  Flag.withDescription("Workspace to operate on"),
+  Flag.withDefault("personal"),
+);
+
+const root = Command.make("acme").pipe(
+  Command.withSharedFlags({
+    workspace,
+    verbose: Flag.boolean("verbose").pipe(
+      Flag.withAlias("v"),
+      Flag.withDescription("Print diagnostic output"),
+    ),
+  }),
+  Command.withDescription("Operate Acme projects"),
+);
+
+const deploy = Command.make(
+  "deploy",
+  {
+    environment: Argument.string("environment").pipe(
+      Argument.withDescription("Target environment"),
+    ),
+    dryRun: Flag.boolean("dry-run").pipe(
+      Flag.withDescription("Show the deployment plan without applying it"),
+    ),
+    json: Flag.boolean("json").pipe(Flag.withDescription("Print machine-readable JSON")),
+  },
+  Effect.fn("deployCommand")(function* ({ dryRun, environment, json }) {
+    const shared = yield* root;
+    const deployments = yield* Deployments;
+    const plan = yield* deployments.plan({ environment, workspace: shared.workspace });
+
+    if (dryRun) return yield* renderPlan(plan, { json });
+
+    const result = yield* deployments.apply(plan);
+    return yield* renderDeployment(result, { json });
+  }),
+).pipe(
+  Command.withDescription("Deploy a workspace"),
+  Command.withExamples([
+    {
+      command: "acme --workspace team deploy production --dry-run",
+      description: "Preview a production deployment",
+    },
+  ]),
+);
+
+export const command = root.pipe(Command.withSubcommands([deploy]));
+```
+
+## Input and help
+
+- Use arguments for essential positional identity and flags for optional
+  behavior. Prefer named flags when position would be ambiguous.
+- Give public commands, arguments, and non-obvious flags descriptions. Add
+  examples for quoting, shared flags, or surprising combinations.
+- Put cross-command inputs in `Command.withSharedFlags`; read them by yielding
+  the parent command instead of duplicating parsing or reading globals.
+- Use `Flag.choice` for closed vocabularies and schemas for structured values
+  loaded from JSON, files, or environment boundaries.
+- Keep aliases additive and unsurprising. Never give two concepts the same
+  short flag in one command path.
+
+## Interactive and automated use
+
+- Make every required value available non-interactively. A fallback `Prompt`
+  may improve terminal use but must not be the only way to supply input.
+- Prompt only after deterministic discovery cannot choose safely. Summarize the
+  detected state and the exact mutation before requesting confirmation.
+- Pair destructive execution with a genuine plan/apply split. `--dry-run` must
+  run the real discovery and planning logic while skipping writes.
+- Require explicit `--yes` or an equivalent authorization flag when a
+  non-interactive destructive path cannot prompt.
+
+## Output contract
+
+- Treat human and machine output as separate renderers over the same result.
+- In `--json` mode, emit one documented schema-encoded value to stdout. Send no
+  headings, spinners, progress, or warnings to stdout.
+- Use stderr for diagnostics and failures. Keep normal human output concise and
+  stable enough for users to understand without reading source.
+- Do not expose stack traces for expected failures. Preserve causes for logs and
+  tests, then render an actionable message at the executable boundary.

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

@@ -0,0 +1,64 @@
+# Entrypoints and testing
+
+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]));
+
+// src/bin/acme.ts
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { Effect } from "effect";
+import { Command } from "effect/unstable/cli";
+import { command } from "../cli/command";
+
+const program = Command.run(command, { version: VERSION }).pipe(
+  Effect.scoped,
+  Effect.provide(ApplicationLive),
+  Effect.provide(NodeServices.layer),
+);
+
+NodeRuntime.runMain(program, { disableErrorReporting: true });
+```
+
+Use `BunRuntime` and `BunServices` together when Bun owns the executable. Let
+`runMain` own signals, interruption, and process completion. Do not call
+`Effect.runPromise`, `process.exit`, or runtime globals inside command handlers.
+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
+
+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:
+   - root and changed-command `--help`;
+   - representative valid arguments and flags;
+   - missing or invalid input and a non-zero exit;
+   - one expected operational failure with an actionable message;
+   - exact JSON output with no prose contamination;
+   - dry-run proving writes did not occur;
+   - confirmation behavior in both interactive and non-interactive modes.
+
+Run executable tests through Effect's child-process APIs with an explicit `cwd`,
+captured stdout/stderr, and controlled environment. Use the repository's normal
+runtime launcher and command authority; a test that bypasses the packaged or
+declared entrypoint does not prove the CLI works for users.
+
+## Completion checks
+
+- Ensure every executable TypeScript entrypoint belongs to a checked project.
+- Run the repository's formatter, linter, typechecker, and tests.
+- Execute `--help` through the real entrypoint.
+- Exercise a harmless dry-run or read-only command outside the source module.
+- Verify non-zero exits for parsing and expected operational failures.

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

@@ -0,0 +1,74 @@
+# Processes and platform services
+
+Use Effect platform services inside CLI workflows. Keep direct `node:*`, Bun
+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
+
+```ts
+import { Context, Effect, Layer, Schema, String } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+export class ToolError extends Schema.TaggedError<ToolError>()("ToolError", {
+  command: Schema.String,
+  cause: Schema.Defect(),
+}) {}
+
+export class Tools extends Context.Service<
+  Tools,
+  {
+    readonly gitVersion: Effect.Effect<string, ToolError>;
+    changedFiles(baseRef: string): Effect.Effect<ReadonlyArray<string>, ToolError>;
+  }
+>()("app/Tools") {
+  static readonly layer = Layer.effect(
+    Tools,
+    Effect.gen(function* () {
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+      const gitVersion = spawner.string(ChildProcess.make("git", ["--version"])).pipe(
+        Effect.map(String.trim),
+        Effect.mapError((cause) => new ToolError({ command: "git --version", cause })),
+      );
+      const changedFiles = Effect.fn("Tools.changedFiles")(function* (baseRef: string) {
+        return yield* spawner
+          .lines(ChildProcess.make("git", ["diff", "--name-only", `${baseRef}...HEAD`]))
+          .pipe(
+            Effect.mapError(
+              (cause) =>
+                new ToolError({ command: `git diff --name-only ${baseRef}...HEAD`, cause }),
+            ),
+          );
+      });
+
+      return Tools.of({ changedFiles, gitVersion });
+    }),
+  );
+}
+```
+
+Pass the executable and arguments separately to `ChildProcess.make`; never
+construct a shell command from user input. Set `cwd` explicitly when repository
+identity matters. Provide `env` narrowly and choose `extendEnv` deliberately so
+tests and CI do not inherit accidental machine state.
+
+Use the smallest spawner operation that matches the contract:
+
+- `string` for bounded complete output;
+- `lines` for bounded line-oriented output;
+- `spawn` plus a scoped process handle for streaming, interactive, or
+  exit-code-sensitive work;
+- `ChildProcess.pipeTo` for a real pipeline without invoking a shell.
+
+When using `spawn`, consume stdout/stderr without deadlocking, inspect
+`handle.exitCode`, and wrap the whole process lifetime in `Effect.scoped`.
+Map platform failures once into an operation-specific error; do not expose a
+generic subprocess error throughout the application.
+
+## Keep the runtime choice at the edge
+
+Application services may require `FileSystem`, `Path`, `Terminal`, or
+`ChildProcessSpawner`, but they should not import `NodeServices` or `BunServices`.
+Provide the matching platform Layer only in the executable entrypoint. This
+keeps workflows reusable and lets tests provide deterministic substitutes.

package/skills/dev-kit/SKILL.md

@@ -155,7 +155,8 @@ matching Oxlint/Oxfmt ignores, staged checks, and separate `check` and pure
 manifest defaults. Workspace mode accepts explicit package directories with
 pure `typecheck` scripts and generates cached, dependency-ordered,
 bounded-concurrency filters. Spread the returned top-level config before local
-options; spread a returned nested block before overriding that block.
+options; spread a returned nested block before overriding that block, and merge
+nested collections such as `lint.rules` so the recommended rules remain active.
 
 Enable `setup.vitePlus.quality.workflow` to own only
 `.github/workflows/check.yml`. It requires direct Dev Kit, compatible Vite+,
@@ -254,8 +255,18 @@ Enable the setup task in the same manifest:
 Install the exact `@effect/tsgo` and native `typescript` versions required by
 the installed dev-kit. Point `tsconfig.json` at
 `./node_modules/@effect/tsgo/schema.json` and configure the
-`@effect/language-service` compiler plugin. `dev-kit plan` validates these local
-dependencies; `dev-kit apply` patches once and then converges.
+`@effect/language-service` compiler plugin with Dev Kit's exported
+`recommendedEffectTsgoPlugin` profile: warnings for
+`anyUnknownInErrorContext` and `unsafeEffectTypeAssertion`; suggestions for
+`instanceOfSchema`, `nestedEffectGenYield`, `newSchemaClass`, and
+`preferSchemaTypeProperty`; plus a `src/**/*.ts` override that warns on
+`nodeBuiltinImport` and suggests `preferSchemaOverJson`. Copy the exact JSON
+profile from the README into JSON tsconfigs. In monorepos, child
+`compilerOptions.plugins` arrays replace rather than merge the root array, so
+workspace configs must inherit the root plugin without redeclaring it and the
+source override must be relative to the config that contains it. `dev-kit plan`
+validates the local dependencies; `dev-kit apply` patches once and then
+converges.
 
 Use `dev-kit tsgo patch --dry-run` for focused diagnosis. Use `--force` only
 after the user accepts a potentially commit-incompatible TypeScript binary.
@@ -290,6 +301,12 @@ The Oxlint preset enables the fixable
 declarations grouped, requires a blank line before the next logical statement,
 and separates every `return` statement from the preceding statement.
 
+Vite+ 0.2.6 forwards the preset's JavaScript-plugin declarations but its native
+Oxlint path does not register or execute their rules. Treat native rules and
+Oxfmt as active through `vp`, and use standalone Oxlint when the `effect/*` or
+`stylistic/padding-line-between-statements` rules must be enforced. Re-enable a
+Vite+ execution assertion when a supported release adds JS-plugin execution.
+
 The Oxlint preset registers Dev Kit's shared Effect plugin as `effect`, but
 does not enable its scope-sensitive rules globally. Effect projects should
 enable rules such as `effect/no-effect-run`, `effect/no-unsafe-promise`, and

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

@@ -0,0 +1,83 @@
+---
+name: open-pull-request
+description: Open pull requests with conventional commits, terse context-complete English descriptions, and verified proof of work. Use whenever preparing or opening a pull request, including checking commit history, drafting the title or body, and attaching screenshots or other evidence.
+---
+
+# Open a Pull Request
+
+Produce a PR that a reviewer can understand and trust without access to the
+task conversation.
+
+## Prepare the branch
+
+1. Read the repository's contribution instructions and PR template. Identify
+   the intended base branch, then inspect the full commit range, diff, and
+   working tree. Finish when the PR scope contains no accidental changes and
+   the description will cover the branch as it exists, not merely the latest
+   task.
+2. Use Conventional Commits for every commit you create and for the PR title:
+   `type(scope): imperative summary`. Follow repository-specific types and
+   scopes, and omit the scope when it adds no useful context. Otherwise use a
+   precise standard type such as `feat`, `fix`, `refactor`, `docs`, `test`,
+   `build`, `ci`, or `chore`. Keep each commit to one logical concern. Rewrite
+   only commits you created and know are unshared; get approval before
+   rewriting user-authored or published history.
+3. Run the repository's required validation on the final branch state. Record
+   the exact commands and results, then collect the strongest available proof
+   of the changed behavior. Finish when every claim in the PR can be traced to
+   the diff, a check result, or an artifact.
+
+## Write for the reviewer
+
+Write terse, plain English for someone with little context. Lead with the
+observable outcome and add only the minimum reason needed to understand it.
+Prefer short bullets and concrete nouns. Expand uncommon acronyms. Describe
+behavior and impact rather than narrating files, implementation steps, or the
+task conversation.
+
+Use the repository's required template when present. Otherwise use this small
+shape and omit empty sections:
+
+```md
+## Summary
+
+- <What changes for a user, operator, or developer>
+- <Why it matters, only when the first bullet does not make that clear>
+
+## Proof
+
+- `<validation command>` — passed
+- <Screenshot, sample output, or other verified artifact>
+```
+
+Keep the summary to one to three bullets. Make the title specific enough to
+stand alone in release notes and conventional enough to become the squash
+commit without editing.
+
+## Show proof of work
+
+Proof is something the reviewer can inspect, not an assertion that the change
+works.
+
+- For a runnable UI or visual feature, capture and attach a screenshot or short
+  recording of the actual final state. Use a representative viewport, add a
+  short caption, and check the artifact for secrets or personal data.
+- For CLI, API, or automation behavior, include concise terminal output, a
+  request/response example, generated artifact, or execution log when it proves
+  more than the validation command alone.
+- For a bug fix or behavior change, prefer before/after evidence when it is
+  practical and materially clarifies the result.
+- For internal-only changes, exact passing validation commands may be the most
+  useful proof.
+
+Include only evidence that was actually produced and verified. When expected
+visual proof cannot be produced, state the concrete reason briefly instead of
+silently substituting a claim. Preserve terse descriptions by choosing the
+smallest set of evidence that proves the outcome.
+
+## Open and verify
+
+Open the PR against the intended base with the conventional title and prepared
+body. Then read back the rendered PR and verify the base/head branches, title,
+description, links, screenshots, and check results. Finish only when the PR is
+reviewable as rendered and return its URL.

package/skills/open-pull-request/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Open Pull Request"
+  short_description: "Open clear, evidence-backed pull requests"
+  default_prompt: "Use $open-pull-request to prepare and open a clear pull request with conventional commits and proof of work."

package/src/catalog.ts

@@ -181,7 +181,7 @@ export const loadSkillCatalog = Effect.fn("loadSkillCatalog")(function* (
     });
   }
   const families: Readonly<Record<string, ReadonlyArray<string>>> = {
-    effect: ["effect-ts", "effect-architecture-audit", "build-effect-apis"],
+    effect: ["effect-ts", "effect-architecture-audit", "build-effect-apis", "build-effect-clis"],
     ...Object.fromEntries(externalFamilies),
   };
 

package/src/effect-tsgo.ts

@@ -9,6 +9,43 @@ export const EFFECT_TSGO_VERSION = "0.33.0";
 export const EFFECT_TSGO_TYPESCRIPT_VERSION = "7.0.2";
 export const EFFECT_TSGO_PLUGIN_NAME = "@effect/language-service";
 
+export type EffectTsgoDiagnosticSeverity = "off" | "error" | "warning" | "message" | "suggestion";
+
+export type EffectTsgoPluginConfig = {
+  readonly name: typeof EFFECT_TSGO_PLUGIN_NAME;
+  readonly diagnosticSeverity: Readonly<Record<string, EffectTsgoDiagnosticSeverity>>;
+  readonly overrides: ReadonlyArray<{
+    readonly include: ReadonlyArray<string>;
+    readonly options: {
+      readonly diagnosticSeverity: Readonly<Record<string, EffectTsgoDiagnosticSeverity>>;
+    };
+  }>;
+};
+
+/** Recommended diagnostics for projects using the Effect TypeScript-Go plugin. */
+export const recommendedEffectTsgoPlugin = {
+  name: EFFECT_TSGO_PLUGIN_NAME,
+  diagnosticSeverity: {
+    anyUnknownInErrorContext: "warning",
+    instanceOfSchema: "suggestion",
+    nestedEffectGenYield: "suggestion",
+    newSchemaClass: "suggestion",
+    preferSchemaTypeProperty: "suggestion",
+    unsafeEffectTypeAssertion: "warning",
+  },
+  overrides: [
+    {
+      include: ["src/**/*.ts"],
+      options: {
+        diagnosticSeverity: {
+          nodeBuiltinImport: "warning",
+          preferSchemaOverJson: "suggestion",
+        },
+      },
+    },
+  ],
+} as const satisfies EffectTsgoPluginConfig;
+
 export type EffectTsgoPatchOptions = {
   readonly dryRun?: boolean;
   readonly force?: boolean;

package/src/index.ts

@@ -43,13 +43,16 @@ export {
   EFFECT_TSGO_PLUGIN_NAME,
   EFFECT_TSGO_TYPESCRIPT_VERSION,
   EFFECT_TSGO_VERSION,
+  type EffectTsgoDiagnosticSeverity,
   EffectTsgoDependencyError,
   InvalidEffectTsgoPackageNameError,
   type EffectTsgoPatchOptions,
   type EffectTsgoPatchPlan,
+  type EffectTsgoPluginConfig,
   EffectTsgoPatchCommandError,
   patchEffectTsgo,
   planEffectTsgoPatch,
+  recommendedEffectTsgoPlugin,
 } from "./effect-tsgo.ts";
 export {
   ExternalSkillSourceSchema,

package/src/skill-manager.ts

@@ -143,9 +143,9 @@ const readManifest = Effect.fn("readManagedSkillManifest")(function* (
   if (errors.length > 0) {
     return yield* SkillManagerError.make({ message: `could not parse ${paths.manifestPath}` });
   }
-  const manifest = yield* Schema.decodeUnknownEffect(DevKitManifestSchema)(parsed).pipe(
-    Effect.mapError((error) => SkillManagerError.make({ message: error.message })),
-  );
+  const manifest = yield* Schema.decodeUnknownEffect(DevKitManifestSchema, {
+    onExcessProperty: "error",
+  })(parsed).pipe(Effect.mapError((error) => SkillManagerError.make({ message: error.message })));
 
   return { ...paths, manifest, raw };
 });

package/src/sync.ts

@@ -270,7 +270,7 @@ const encodePlanSnapshotJson = Schema.encodeSync(Schema.fromJsonString(Schema.Un
 const encodeAppliedStatePrettyJson = Schema.encodeSync(fromJsonString(AppliedStateSchema, 2));
 
 const SKILL_FAMILIES: SkillCatalog = {
-  effect: ["effect-ts", "effect-architecture-audit", "build-effect-apis"],
+  effect: ["effect-ts", "effect-architecture-audit", "build-effect-apis", "build-effect-clis"],
 };
 
 export const DEFAULT_MANIFEST = "dev-kit.jsonc";
@@ -564,6 +564,7 @@ const parseStructuredFile = Effect.fn("parseStructuredFile")(function* <A>(
   filePath: string,
   raw: string,
   schema: Schema.ConstraintDecoder<A>,
+  options: { readonly rejectExcessProperties?: boolean } = {},
 ) {
   const errors: Array<ParseError> = [];
   const parsed = parseJsonc(raw, errors, { allowTrailingComma: true });
@@ -576,7 +577,10 @@ const parseStructuredFile = Effect.fn("parseStructuredFile")(function* <A>(
     });
   }
 
-  return yield* Schema.decodeUnknownEffect(schema)(parsed).pipe(
+  return yield* Schema.decodeUnknownEffect(
+    schema,
+    options.rejectExcessProperties ? { onExcessProperty: "error" } : undefined,
+  )(parsed).pipe(
     Effect.mapError((cause) =>
       StructuredFileError.make({ path: filePath, message: cause.message }),
     ),
@@ -591,7 +595,9 @@ const readManifest = Effect.fn("readManifest")(function* (manifestPath: string)
   }
   const raw = yield* fs.readFileString(manifestPath);
 
-  return yield* parseStructuredFile(manifestPath, raw, DevKitManifestSchema);
+  return yield* parseStructuredFile(manifestPath, raw, DevKitManifestSchema, {
+    rejectExcessProperties: true,
+  });
 });
 
 const readOptionalStructuredFile = Effect.fn("readOptionalStructuredFile")(function* <A>(
@@ -1752,7 +1758,7 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
   });
   const stageDir = path.join(tempDir, "stage");
   const backupDir = path.join(tempDir, "backup");
-  const stagedByResource = new Map<string, string>();
+  const stagedByAction = new Map<(typeof mutating)[number], string>();
   let stageIndex = 0;
 
   for (const action of mutating) {
@@ -1816,10 +1822,7 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
         });
       }
     }
-    stagedByResource.set(
-      action.action === "remove" ? action.previous.resourceId : action.desired.resourceId,
-      staged,
-    );
+    stagedByAction.set(action, staged);
   }
 
   yield* verifyPackageSkillSources(plan);
@@ -1841,10 +1844,7 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
   let replacementIndex = 0;
 
   for (const action of mutating) {
-    const staged =
-      action.action === "remove"
-        ? stagedByResource.get(action.previous.resourceId)
-        : stagedByResource.get(action.desired.resourceId);
+    const staged = stagedByAction.get(action);
 
     if (
       (action.action !== "remove" || action.stagedContent !== undefined) &&

package/src/vite-plus.js

@@ -68,7 +68,7 @@ export const createRecommendedVitePlusConfig = (options = {}) => {
       ignorePatterns,
     },
     lint: {
-      extends: [recommendedOxlintConfig],
+      ...recommendedOxlintConfig,
       ignorePatterns,
     },
     run: {

package/src/vite-plus.ts

@@ -89,7 +89,7 @@ export const createRecommendedVitePlusConfig = (options: RecommendedVitePlusConf
       ignorePatterns,
     },
     lint: {
-      extends: [recommendedOxlintConfig],
+      ...recommendedOxlintConfig,
       ignorePatterns,
     },
     run: {