@danieljvdm/dev-kit 0.13.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,11 +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`, `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.
+  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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danieljvdm/dev-kit",
-  "version": "0.13.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

@@ -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
 

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."