@danieljvdm/dev-kit 0.14.0 → 0.15.0

package/skills/dev-kit/SKILL.md

@@ -1,24 +1,21 @@
 ---
 name: dev-kit
-description: Dev-kit operations for projects that configure dev-kit.jsonc, sync portable skills, run plan/apply or automatic postinstalls, perform locked CI checks, maintain dev-kit.lock.json, resolve ownership conflicts, patch managed ignores, or enable Effect TypeScript-Go.
+description: Dev-kit operations for projects that configure dev-kit.jsonc, sync portable skills, run plan/apply or automatic postinstalls, perform locked CI checks, maintain dev-kit.lock.json, resolve ownership conflicts, or enable Effect TypeScript-Go.
 ---
 
 # Dev Kit
 
 Treat `dev-kit.jsonc` as desired state, `dev-kit.lock.json` as the committed
-resolution, and `.dev-kit/state.json` as local ownership receipts.
+resolution, and `.dev-kit/state.json` as local ownership receipts. Deep
+reference — catalog maintenance, package-skill discovery rules, preset
+internals — lives in the package README
+(`node_modules/@danieljvdm/dev-kit/README.md`).
 
 Use the high-level commands for routine changes: `dev-kit init`, `dev-kit add
 <skill...>`, `dev-kit remove <skill...>`, `dev-kit list --all`, `dev-kit search
 <words...>`, and `dev-kit info <skill>`. Add and remove apply immediately unless
 passed `--no-apply`; `dev-kit sync` applies an already-edited manifest.
 
-For distro maintenance, use `dev-kit catalog add <repository>` to inspect and
-approve upstream skills, `catalog list`/`catalog info` to review provenance,
-`catalog remove <source-or-skill>` to revoke approval, and `catalog verify` in
-CI. Pass repeated `--skill` flags or `--all` outside a terminal. Approval always
-stores explicit skill names and exact commit/content digests.
-
 ## Apply loop
 
 1. Establish the Git root. Read project agent instructions, the current
@@ -33,14 +30,12 @@ stores explicit skill names and exact commit/content digests.
    requested creative or advisory skills even when they have no mechanical
    dependency signal.
 3. Choose the narrowest useful set. Prefer focused external skills over a
-   generic umbrella when they cover the repository's work. Select an umbrella
-   or external source family only when its full breadth is intentionally useful;
-   never select one merely because one member or product matches. Explain any
-   uncertain inclusion before applying it. Distinguish separately triggered
-   skills from lazy `references/` bundled inside one skill: unused reference
-   folders cost repository space but are not loaded into agent context unless
-   the skill routes to them. A multi-product repository can therefore justify
-   an umbrella while still excluding unrelated top-level skills.
+   generic umbrella; select an umbrella or source family only when its full
+   breadth is intentionally useful, never because one member matches. Explain
+   any uncertain inclusion before applying it. Unused `references/` folders
+   inside a selected skill cost repository space, not agent context, so a
+   multi-product repository can justify an umbrella while still excluding
+   unrelated top-level skills.
 4. Update `dev-kit.jsonc`. Preserve JSONC comments and validate against the
    package schema. Finish with each desired resource represented once and every
    external selection supported by repository evidence or an explicit request.
@@ -51,126 +46,108 @@ stores explicit skill names and exact commit/content digests.
 6. Resolve conflicts, then run `dev-kit apply`. Commit the manifest and
    regenerated `dev-kit.lock.json`; keep `.dev-kit/` local. Finish when a second
    plan reports only unchanged resources and setup tasks.
-7. Use `dev-kit apply` in the package lifecycle so intentional dependency
-   upgrades regenerate owned outputs and `dev-kit.lock.json`. For strict CI,
-   either disable lifecycle scripts before `dev-kit apply --locked`, or run the
-   normal lifecycle and require the tracked working tree to remain clean. Never
-   run an unlocked apply before locked verification. Finish when a clean install
-   converges from the committed manifest and lock.
 
 ## Manifest
 
 Use skill names or family names in `include`; subtract selections with
-`exclude`. Built-in families such as `effect` are intentional bundles. An
-external source ID is also a family, but expands to every approved skill from
-that source, so prefer individually relevant external skills. Include this
-skill as `dev-kit` when project agents should carry the toolkit procedure.
-
-Select skills bundled inside installed packages with the exact
-`<package>#<skill>` selector. The selector stays package-qualified in the
-manifest, lock, and CLI listings, and the installed output keeps that identity:
-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/table-core#core` installs as `tanstack-table-core-core`. The
-copied `SKILL.md` frontmatter `name:` is rewritten to the same install name;
-everything else is verbatim. Symlink-mode targets still point at
-`node_modules`, so their frontmatter keeps the upstream bare name. Two selected
-skills that flatten to the same install name are rejected before any output
-changes.
+`exclude`. Built-in families such as `effect` are intentional bundles. Include
+this skill as `dev-kit` when project agents should carry the toolkit
+procedure. Skills bundled inside installed packages need the exact
+`<package>#<skill>` selector; the copied output flattens that identity into
+one directory name (`@tanstack/table-core#core` → `tanstack-table-core-core`)
+and rewrites the copied frontmatter `name:` to match.
 
 ```jsonc
 {
   "$schema": "./node_modules/@danieljvdm/dev-kit/schema/dev-kit.schema.json",
   "include": ["dev-kit", "effect"],
-  "exclude": [],
   "setup": {
     "agentInstructions": { "enabled": true },
     "claudeInstructions": { "enabled": true },
     "vitePlus": {
       "hooks": { "enabled": true },
-      "quality": {
-        "workflow": { "enabled": true },
-      },
+      "workflow": { "enabled": true },
+    },
+    "worktrunk": {
+      "config": { "enabled": true },
     },
   },
   "targets": {
     "agents": { "enabled": true, "mode": "copy" },
     "claude": { "enabled": true, "mode": "symlink" },
-    "opencode": { "enabled": false, "mode": "symlink" },
   },
 }
 ```
 
 Prefer a copied `.agents/skills` target as the project-local source of truth;
 use symlinks for additional harness discovery paths. Keep every target path
-project-relative and separate from the manifest, lock, state, and process-lock
-paths.
-
-Enable `setup.agentInstructions` to manage marked sections in a project-root
-`AGENTS.md` while preserving handwritten project guidance. The Dev Kit section
-points agents back to this skill. When `vite-plus` is a declared direct
-dependency, dev-kit synthesizes repository-specific Vite+ guidance inside its
-own section instead of importing Vite+'s generic `AGENTS.md`. Preserve the
-useful unified-toolchain overview, help and documentation entry points, and
-`vp env doctor` troubleshooting without duplicating generic commands that can
-contradict the repository policy. Treat duplicate, overlapping, reversed, or
-unmatched managed markers as a conflict rather than guessing which content Dev
-Kit owns; remove a legacy owned Vite+ section during migration.
-When `effect` is a declared direct dependency and the installed package ships a
-regular `node_modules/effect/AGENTS.md` file, the managed section also directs
-agents to read that version-matched guide completely and use
-`node_modules/effect/src` for gaps. Omit the pointer when the package is absent,
-transitive, or too old to ship the guide; never generate a dangling path.
-The managed section also publishes the repository's command authority. Direct
-Vite+ projects must use `vp` built-ins and `vp run <task>`; projects using the
-recommended Vite+ factory use `vp run check` for the complete
-format/lint/test/typecheck suite and `vp run typecheck` for the Effect-patched
-compiler. Non-Vite+ projects run
-existing root quality scripts through `bun run`; package-manager metadata and
-lockfiles affect dependency-install guidance only. Never substitute another
+project-relative and separate from the manifest, lock, and state paths.
+
+## Managed instructions
+
+`setup.agentInstructions` manages marked sections in the project-root
+`AGENTS.md` and preserves handwritten content around them; edit only outside
+the markers. The section points agents at this skill, renders the repository's
+command policy from live evidence (a direct `vite-plus` dependency makes `vp`
+the only front door; otherwise Bun runs declared root scripts), and adds the
+Effect guide pointer when the installed `effect` package ships one. Treat
+duplicate, overlapping, reversed, or unmatched managed markers as a conflict
+rather than guessing which content Dev Kit owns. Never substitute another
 script runner or call raw `tsc`, test, lint, or format binaries when a project
 command exists.
-Enable `setup.claudeInstructions` when Claude Code should consume the same
-project-root instructions; it manages `CLAUDE.md` as a relative symlink to the
-section-managed file or to an existing regular `AGENTS.md`. Preserve
-conflicting paths; when disabled, dev-kit removes only unchanged marked
-sections recorded in local ownership state and leaves handwritten content in
-place.
-
-Enable `setup.vitePlus.hooks` when an installed direct `vite-plus` dependency
-should manage Git hooks. Each apply checks the local `.vite-hooks/_` dispatcher,
-its internal `.gitignore`, the portable `.vite-hooks/pre-commit` hook, and
-`core.hooksPath`, then runs the project-local `vp config --no-agent` when they
-need convergence. This recreates ignored dispatchers in linked worktrees.
-Preserve other hook managers; Dev Kit
-refuses to replace an unrelated `core.hooksPath`. Use `VITE_GIT_HOOKS=0` or
-`HUSKY=0` to skip hook setup for an invocation.
+
+`setup.claudeInstructions` manages `CLAUDE.md` as a relative symlink to
+`AGENTS.md`. Disabling either task removes only unchanged managed content and
+leaves handwritten content in place.
+
+## Vite+ setup
 
 The repository always owns `vite.config.ts`. Compose
-`createRecommendedVitePlusConfig` from `@danieljvdm/dev-kit/vite-plus` there;
-Dev Kit never adopts, rewrites, or removes the config. The factory provides
-matching Oxlint/Oxfmt ignores, staged checks, and separate `check` and pure
-`typecheck` Vite tasks. Add repository/framework-generated paths through its
-`ignorePatterns` option, including any harness target paths that override the
-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, 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+,
-Effect, Effect TypeScript-Go, and native TypeScript dependencies with
-`setup.effectTsgo.enabled`. Preserve unowned workflows and adopt only an exact
-rendered match. Consumers may configure `workflow.beforeChecks` and
-`workflow.typecheck`; treat these commands as trusted manifest input.
-
-The workflow must use one frozen, script-suppressed install, then locked Dev Kit
-convergence before preparation or checks. Set up Bun from the consumer's
-`packageManager` or `engines.bun` declaration before Vite+ setup. Follow the
-maintained `setup-bun` major tag, name an explicit `setup-vp` release because
-its `v1` tag is frozen, and let Vite+ resolve the consumer's compatible locked
-version.
+`createRecommendedVitePlusConfig` from `@danieljvdm/dev-kit/vite-plus` there,
+adding repository/framework-generated paths (and any overridden harness target
+paths) through `ignorePatterns`. Spread the returned top-level config before
+local options, spread a returned nested block before overriding it, and merge
+nested collections such as `lint.rules` so the recommended rules stay active.
+The factory provides matching Oxlint/Oxfmt ignores, staged checks, and
+separate `check` and pure `typecheck` tasks; standalone Oxc projects import
+`recommendedOxlintConfig`/`recommendedOxfmtConfig` directly.
+
+Run the Effect-patched compiler separately with `vp run typecheck`; neither
+Oxlint's bundled `tsgolint` nor Vite+'s native lint path uses the Effect patch,
+and Vite+ 0.2.6 does not execute the preset's JavaScript-plugin rules — use
+standalone Oxlint when `effect/*` or
+`stylistic/padding-line-between-statements` must be enforced. The `effect`
+plugin's scope-sensitive rules stay consumer-scoped: enable them per path in
+Effect-owned code, with exceptions for tests and host boundaries.
+
+`setup.vitePlus.hooks` converges the Git-ignored `.vite-hooks/_` dispatcher by
+running the project-local `vp config --no-agent`, recreating it in linked
+worktrees. It requires a direct `vite-plus` dependency, refuses to replace an
+unrelated `core.hooksPath`, and is skipped per invocation with
+`VITE_GIT_HOOKS=0` or `HUSKY=0`.
+
+## Scaffolds
+
+`setup.vitePlus.workflow` and `setup.worktrunk.config` are create-only
+scaffolds: apply writes the file only when it is missing, records nothing in
+the lock, and never reads, updates, or removes an existing file — the
+repository owns it from creation and edits it directly. When the shipped
+template improves, diff the repository's file against the installed template
+under `node_modules/@danieljvdm/dev-kit/templates/` and merge what fits.
+
+- `setup.vitePlus.workflow` scaffolds `.github/workflows/check.yml`. It
+  requires direct Dev Kit, compatible Vite+, Effect, Effect TypeScript-Go, and
+  native TypeScript dependencies with `setup.effectTsgo.enabled`. Add
+  preparation steps or a custom typecheck command by editing the YAML.
+- `setup.worktrunk.config` scaffolds `.config/wt.toml`: a
+  copy-ignored-then-install pre-start pipeline, a full-validation pre-merge
+  hook, and a commented per-worktree dev-server block to enable deliberately.
+  Hook commands render for the repository's runner — `vp` with a direct
+  `vite-plus` dependency, otherwise the detected package manager's install
+  command with `bun run check` from a declared root `check` script. Keep
+  user-level Worktrunk settings such as worktree-path templates out of the
+  project config; each user approves the hooks once with
+  `wt config approvals add`.
 
 ## Ownership and conflicts
 
@@ -190,17 +167,10 @@ Preserve a conflicting path and inspect it:
 Retain `.dev-kit/state.json` across routine applies and branch changes so its
 receipts can update or remove previously applied outputs safely.
 
-## Project plumbing
-
-Run `dev-kit gitignore` to add `.repos/` and `.dev-kit/` additively. Preview with
-`dev-kit gitignore --dry-run`. Treat `.repos/<source-id>` as the reserved source
-checkout root.
+## Lifecycle
 
-Require Bun 1.3 or newer wherever Dev Kit runs. The published `dev-kit`
-executable uses Bun directly and rejects Node execution; keep Bun available to
-package lifecycle scripts and locked CI verification.
-
-For one lifecycle entry point, configure:
+Run `dev-kit gitignore` to add `.repos/` and `.dev-kit/` additively
+(`--dry-run` to preview). For one lifecycle entry point, configure:
 
 ```jsonc
 {
@@ -210,117 +180,40 @@ For one lifecycle entry point, configure:
 }
 ```
 
-This intentionally refreshes the committed lock and owned outputs when the
-package manager installs a new Dev Kit or selected package-skill version.
-Review and commit those changes with the dependency update. Keep
-`dev-kit apply --locked` as a verification command, not the normal local
-lifecycle; in CI, run it only before any unlocked apply. Invoke locked consumer
-verification as
+This intentionally refreshes the committed lock and owned outputs when an
+installed Dev Kit or selected package-skill version changes; review and commit
+those changes with the dependency update. Keep `dev-kit apply --locked` as a
+verification command, never the local lifecycle, and never run an unlocked
+apply before locked verification. Invoke locked consumer verification as
 `bun ./node_modules/@danieljvdm/dev-kit/bin/dev-kit.mjs apply --locked` so a
 package script named `dev-kit` cannot shadow the executable.
 
-## Effect source checkout
-
-Enable the source task when agents should have canonical source matching the
-installed Effect package:
-
-```jsonc
-{
-  "setup": {
-    "effectSource": { "enabled": true },
-  },
-}
-```
-
-The task reads the exact installed `effect` version and converges the ignored
-`.repos/effect` checkout on the corresponding `effect@<version>` tag. It skips
-CI, preserves a dirty or unrelated destination, and never deletes the checkout
-when disabled. Use `dev-kit effect sync --dry-run` for focused diagnosis.
-
-Override `packageName`, `path`, or `repository` only for a compatible Effect
-distribution or a deliberate mirror.
-
-## Effect TypeScript-Go
-
-Enable the setup task in the same manifest:
-
-```jsonc
-{
-  "setup": {
-    "effectTsgo": { "enabled": true },
-  },
-}
-```
-
-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 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
+## Effect setup tasks
+
+`setup.effectSource` converges the ignored `.repos/effect` checkout on the
+`effect@<version>` tag matching the installed package. It skips CI, preserves
+a dirty or unrelated destination, and never deletes the checkout when
+disabled. Diagnose with `dev-kit effect sync --dry-run`; override
+`packageName`, `path`, or `repository` only for a compatible Effect
+distribution.
+
+`setup.effectTsgo` validates and patches the project-local native TypeScript
+compiler. Install the exact `@effect/tsgo` and `typescript` versions required
+by the installed dev-kit, point `tsconfig.json` at
+`./node_modules/@effect/tsgo/schema.json`, and configure the
+`@effect/language-service` plugin with the `recommendedEffectTsgoPlugin`
+profile — copy the exact JSON from the package README. 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.
-
-## Oxlint and Oxfmt configurations
-
-Use Dev Kit's composable factory in Vite+ projects:
-
-```ts
-import { createRecommendedVitePlusConfig } from "@danieljvdm/dev-kit/vite-plus";
-import { defineConfig } from "vite-plus";
-
-export default defineConfig(
-  createRecommendedVitePlusConfig({
-    ignorePatterns: ["src/routeTree.gen.ts"],
-  }),
-);
-```
-
-The factory composes the canonical Oxlint/Oxfmt objects, excludes tracked skill
-copies plus symlinked harness targets from both tools, and accepts additional
-project-owned ignores. Standalone `oxlint.config.ts` uses
-`extends: [recommendedOxlintConfig]`; standalone `oxfmt.config.ts` spreads
-`recommendedOxfmtConfig`. The shared lint preset enables `typeAware` for
-semantic lint rules but leaves `typeCheck` disabled. Effect TypeScript-Go
-projects must run the patched native compiler separately with
-`vp run typecheck` after `vp fmt --check`, `vp lint`, and `vp test`; Oxlint's
-bundled `tsgolint` does not use the Effect patch.
-
-The Oxlint preset enables the fixable
-`stylistic/padding-line-between-statements` rule. It keeps adjacent variable
-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
-`effect/no-untyped-throw` only in Effect-owned code, with explicit exceptions
-for tests and host boundaries. The stricter `effect/no-async-workflow`,
-`effect/no-promise-atom-mode`, and `effect/no-sync-boundary-decode` rules also
-need consumer-owned scopes. Keep repository-specific paths and platform rules
-in the consuming project.
+workspace configs must inherit the root plugin without redeclaring it, and the
+`src/**/*.ts` override must be relative to the config that contains it.
+Diagnose with `dev-kit tsgo patch --dry-run`; use `--force` only after the
+user accepts a potentially commit-incompatible TypeScript binary.
 
 ## Current boundary
 
 Manage skill outputs, the `setup.agentInstructions` marked sections, the
 `setup.claudeInstructions` link, the `setup.vitePlus.hooks` dispatcher, the
-opt-in `setup.vitePlus.quality.workflow`, the `setup.effectSource` checkout,
-and the explicit `setup.effectTsgo` task. `vite.config.ts`, dependency, and
-`tsconfig.json` contributions remain deliberate user-owned edits. Compose the
-Vite+ factory or lower-level Oxlint/Oxfmt exports locally.
+`setup.effectSource` checkout, and the explicit `setup.effectTsgo` task. The
+`setup.vitePlus.workflow` and `setup.worktrunk.config` scaffolds belong to the
+repository once created. `vite.config.ts`, dependency, and `tsconfig.json`
+contributions remain deliberate user-owned edits.

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Open pull requests with conventional commits, reviewer-complete descriptions, links to vital code, and concrete evidence. Use whenever preparing or opening a pull request, including checking commit history, explaining a bug or architectural change, drafting the title or body, and attaching screenshots or other evidence.
 ---
 
 # Open a Pull Request
@@ -22,18 +22,38 @@ task conversation.
    `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.
+3. Run the repository's required validation on the final branch state, then
+   collect the strongest available evidence of the changed behavior. Identify
+   the few files, symbols, or modules a reviewer must understand and prepare
+   links that resolve in the rendered PR. Finish when every claim can be traced
+   to the diff, CI, or a verified 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.
+Write clear, compact English for someone with little context. Give the reviewer
+enough explanation to agree with both the problem and the solution; do not
+sacrifice causal or architectural context for brevity. Lead with the observable
+outcome, then explain why the change was needed and how the important pieces
+fit together. Prefer concrete nouns and expand uncommon acronyms. Describe
+behavior and impact rather than narrating the task conversation.
+
+Link the vital implementation points from the summary or architecture section.
+Use descriptive link text that names each piece by its role, such as the request
+router or cache invalidation boundary, and verify every link after opening the
+PR. Link the core pieces a reviewer should inspect, not every touched file.
+
+For every bug fix, include a **What went wrong** section in plain English. State
+the incorrect behavior, its actual root cause and causal chain, and why the
+change fixes it. Make uncertainty or incomplete coverage explicit. A result
+such as "fixed stale state" is not a diagnosis; explain how the stale state was
+created or allowed to survive.
+
+When the change alters architecture, identify the affected components and
+boundaries, what each one owns after the change, and any important change to
+control flow, data flow, public contracts, or persistence. Link to the core
+implementation of each affected piece. Use a dedicated **Architecture** section
+when this would make the change easier to review; otherwise include the context
+in the summary.
 
 Use the repository's required template when present. Otherwise use this small
 shape and omit empty sections:
@@ -42,38 +62,57 @@ shape and omit empty sections:
 ## Summary
 
 - <What changes for a user, operator, or developer>
-- <Why it matters, only when the first bullet does not make that clear>
+- <Why it matters and the shape of the solution, with links to vital code>
+
+## What went wrong
+
+<For a bug fix: explain the symptom, root cause, causal chain, and why this fix
+addresses it.>
 
-## Proof
+## Architecture
 
-- `<validation command>` — passed
-- <Screenshot, sample output, or other verified artifact>
+- <When applicable: explain the changed components, ownership, and flow, with
+  links to their core implementations.>
+
+## Evidence
+
+- <Screenshot, before/after output, request/response, trace, or other verified
+  artifact>
 ```
 
-Keep the summary to one to three bullets. Make the title specific enough to
+Keep the body proportional to the change: a small change may need two useful
+bullets, while a subtle bug or architectural change may need several paragraphs.
+Omit conditional sections that do not apply. 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
+## Show useful evidence
 
-Proof is something the reviewer can inspect, not an assertion that the change
-works.
+Evidence 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.
+  the behavior more clearly than the CI result 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.
+- For internal-only changes, include focused regression output, a trace, a
+  generated artifact, or another result that demonstrates the changed behavior
+  when available.
+
+Routine validation commands that CI always runs, such as `vp check` or standard
+format, lint, typecheck, and test commands, add no useful context to the PR body.
+Let CI report them. Mention a command or CI result only when it is unusual,
+cannot run in CI, or its output itself helps the reviewer understand the change.
 
 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.
+silently substituting a claim. Choose the smallest set of evidence that makes
+the changed behavior easy to inspect. Omit the section when no evidence adds
+information beyond routine CI.
 
 ## Open and verify
 

package/src/index.ts

@@ -11,14 +11,14 @@ export {
   EffectTsgoSetupSchema,
   type HarnessTarget,
   TargetConfigSchema,
-  type VitePlusQualitySetup,
-  VitePlusQualitySetupSchema,
-  type VitePlusQualityWorkflowSetup,
-  VitePlusQualityWorkflowSetupSchema,
-  type VitePlusQualityWorkflowStep,
-  VitePlusQualityWorkflowStepSchema,
   type VitePlusSetup,
   VitePlusSetupSchema,
+  type VitePlusWorkflowSetup,
+  VitePlusWorkflowSetupSchema,
+  type WorktrunkConfigSetup,
+  WorktrunkConfigSetupSchema,
+  type WorktrunkSetup,
+  WorktrunkSetupSchema,
 } from "./manifest.ts";
 export {
   applyEffectSourcePlan,