@danieljvdm/dev-kit 0.10.0 → 0.11.0

package/README.md

@@ -20,6 +20,9 @@ Install the published Dev Kit package:
 bun add -d @danieljvdm/dev-kit
 ```
 
+Dev Kit requires Bun 1.3 or newer. Its published executable runs TypeScript
+natively with Bun and rejects direct Node.js execution.
+
 Initialize the project, browse available built-in, approved Git, and installed
 package skills, then add the ones you want:
 
@@ -94,12 +97,14 @@ before running locked mode:
 
 ```bash
 bun install --ignore-scripts
-bun x dev-kit apply --locked
+bun ./node_modules/@danieljvdm/dev-kit/bin/dev-kit.mjs apply --locked
 ```
 
 Or allow the normal postinstall and fail CI when it leaves tracked changes.
 Do not run an unlocked apply before a locked verification because that would
 regenerate the drift being checked.
+The package-qualified path cannot be shadowed by a consumer script named
+`dev-kit`.
 
 This repository dogfoods the same flow with its committed `dev-kit.jsonc` and
 `dev-kit.lock.json`. From this source checkout, invoke the local CLI with:
@@ -211,7 +216,7 @@ The patch is idempotent, preserves existing lines, and refuses symlinked
 
 ## Agent instructions
 
-Enable a managed project-root instruction wrapper and a portable Claude Code
+Enable managed project-root instruction sections and a portable Claude Code
 bridge in the manifest:
 
 ```jsonc
@@ -224,18 +229,37 @@ bridge in the manifest:
 }
 ```
 
-`setup.agentInstructions` manages `AGENTS.md` as a generated wrapper with a
-short description of dev-kit and a pointer to the installed `dev-kit` skill.
-When the root `package.json` declares `vite-plus` directly, the wrapper also
-includes Vite+'s installed `node_modules/vite-plus/AGENTS.md` instructions.
-Transitive installations do not opt a project in.
+`setup.agentInstructions` manages marked sections in the project-root
+`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.
+
+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
+`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
+by `package.json#packageManager`, or inferred from a single recognized root
+lockfile, is used only for dependency-install guidance. The policy forbids
+switching script runners or bypassing project entry points with raw `tsc`,
+test-runner, linter, or formatter commands.
 
 `setup.claudeInstructions` manages `CLAUDE.md` as the relative symlink
-`CLAUDE.md → AGENTS.md`. It can link to the generated wrapper in the same apply,
+`CLAUDE.md → AGENTS.md`. It can link to the section-managed file in the same apply,
 or retain the older behavior of linking to an existing regular `AGENTS.md` when
-the wrapper task is disabled. Both outputs are recorded independently in the
-lockfile and local ownership state. Dev Kit refuses to replace unowned files
-and removes only unchanged owned outputs.
+the section task is disabled. Both outputs are recorded independently in the
+lockfile and local ownership state. Disabling agent instructions removes only
+unchanged managed sections and deletes `AGENTS.md` only when no handwritten
+content remains.
 
 ## Vite+ Git hooks
 
@@ -351,10 +375,11 @@ scripts, or TypeScript topology. It performs one frozen, script-suppressed
 install, runs `dev-kit apply --locked`, and only then runs custom preparation,
 formatting, linting, tests, and typechecking. Its default typecheck command is
 `vp run typecheck`; `workflow.typecheck` replaces it. Vite+ maps install flags
-to the detected package manager. The template pins an exact `setup-vp` release
-commit because its `v1` tag is frozen; keep it current with Renovate or
-Dependabot. Existing workflows remain user-owned until their rendered content
-matches exactly—Dev Kit never merges YAML. See the primary
+to the detected package manager. The template installs the consumer's declared
+Bun version and pins exact `setup-bun` and `setup-vp` releases; the latter's
+`v1` tag is frozen. Keep both current with Renovate or Dependabot. 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

package/bin/dev-kit.mjs

@@ -1,3 +1,17 @@
-#!/usr/bin/env -S node --import tsx
+#!/usr/bin/env bun
 
-import "../src/bin/dev-kit.ts";
+import semver from "semver";
+
+const MINIMUM_BUN_VERSION = "1.3.0";
+const bunVersion = globalThis.Bun?.version;
+
+if (bunVersion === undefined) {
+  throw new Error(
+    `Dev Kit requires the Bun runtime, version ${MINIMUM_BUN_VERSION} or newer. Install Bun and run \`dev-kit\` again.`,
+  );
+}
+if (!semver.satisfies(bunVersion, `>=${MINIMUM_BUN_VERSION}`)) {
+  throw new Error(`Dev Kit requires Bun ${MINIMUM_BUN_VERSION} or newer; found ${bunVersion}.`);
+}
+
+await import("../src/bin/dev-kit.ts");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danieljvdm/dev-kit",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": false,
   "description": "Declarative project development toolkit with portable agent skills.",
   "license": "MIT",
@@ -65,15 +65,15 @@
     "catalog:check": "./bin/dev-kit.mjs catalog verify"
   },
   "dependencies": {
-    "@effect/platform-node": "4.0.0-beta.102",
+    "@effect/platform-bun": "4.0.0-beta.102",
     "@stylistic/eslint-plugin": "5.10.0",
     "effect": "4.0.0-beta.102",
     "jsonc-parser": "3.3.1",
-    "semver": "7.8.5",
-    "tsx": "4.22.4"
+    "semver": "7.8.5"
   },
   "devDependencies": {
     "@changesets/cli": "3.0.0-next.10",
+    "@effect/platform-node": "4.0.0-beta.102",
     "@effect/tsgo": "0.24.3",
     "@effect/vitest": "4.0.0-beta.102",
     "@types/node": "25.9.1",
@@ -101,7 +101,7 @@
     }
   },
   "engines": {
-    "node": ">=22.12.0"
+    "bun": ">=1.3.0"
   },
   "packageManager": "bun@1.3.14"
 }

package/schema/dev-kit.schema.json

@@ -68,7 +68,7 @@
   "required": ["include"],
   "$defs": {
     "agentInstructionsSetup": {
-      "description": "Manage a project-root AGENTS.md wrapper with dev-kit guidance and conditional tool instructions.",
+      "description": "Manage marked sections in project-root AGENTS.md with dev-kit guidance and conditional tool instructions while preserving handwritten content.",
       "type": "object",
       "additionalProperties": false,
       "properties": {

package/skills/dev-kit/SKILL.md

@@ -95,14 +95,30 @@ 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 a project-root `AGENTS.md` wrapper
-that points agents back to this skill. When `vite-plus` is a declared direct
-dependency, dev-kit includes its installed agent instructions in the wrapper.
+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.
+The managed section also publishes the repository's command authority. Direct
+Vite+ projects must use `vp` built-ins and `vp run <task>`; managed quality
+projects 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
+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
-wrapper or to an existing regular `AGENTS.md`. Preserve conflicting paths;
-when disabled, dev-kit removes only unchanged outputs recorded in local
-ownership state.
+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,
@@ -129,9 +145,11 @@ builds custom. Workflow-only 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. Keep `setup-vp` pinned to a reviewed
-release commit—the `v1` tag is frozen—and let Vite+ resolve the consumer's
-compatible locked version.
+convergence before preparation or checks. Set up Bun from the consumer's
+`packageManager` or `engines.bun` declaration before Vite+ setup. Keep both
+`setup-bun` and `setup-vp` pinned to reviewed release commits—the `setup-vp`
+`v1` tag is frozen—and let Vite+ resolve the consumer's compatible locked
+version.
 
 ## Ownership and conflicts
 
@@ -157,6 +175,10 @@ Run `dev-kit gitignore` to add `.repos/` and `.dev-kit/` additively. Preview wit
 `dev-kit gitignore --dry-run`. Treat `.repos/<source-id>` as the reserved source
 checkout root.
 
+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:
 
 ```jsonc
@@ -171,7 +193,10 @@ 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.
+lifecycle; in CI, run it only before any unlocked apply. 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
 
@@ -263,7 +288,7 @@ in the consuming project.
 
 ## Current boundary
 
-Manage skill outputs, the `setup.agentInstructions` wrapper, the
+Manage skill outputs, the `setup.agentInstructions` marked sections, the
 `setup.claudeInstructions` link, the `setup.vitePlus.hooks` dispatcher, the
 independently opt-in `setup.vitePlus.quality` config and GitHub workflow, the
 `setup.effectSource` checkout, and the explicit `setup.effectTsgo` task.

package/src/bin/dev-kit.ts

@@ -1,4 +1,4 @@
-import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { BunRuntime, BunServices } from "@effect/platform-bun";
 import { Effect, Result } from "effect";
 import { Argument, CliError, Command as CliCommand, Flag } from "effect/unstable/cli";
 
@@ -399,7 +399,7 @@ const program = CliCommand.run(command, { version: DEV_KIT_VERSION }).pipe(
       ),
   ),
   Effect.scoped,
-  Effect.provide(NodeServices.layer),
+  Effect.provide(BunServices.layer),
 );
 
-NodeRuntime.runMain(program, { disableErrorReporting: true });
+BunRuntime.runMain(program, { disableErrorReporting: true });

package/src/project-package.ts

@@ -8,6 +8,7 @@ export class ProjectPackageError extends Schema.TaggedErrorClass<ProjectPackageE
 const ProjectPackageSchema = Schema.fromJsonString(
   Schema.Struct({
     name: Schema.optional(Schema.String),
+    packageManager: Schema.optional(Schema.String),
     scripts: Schema.optional(Schema.Record(Schema.String, Schema.String)),
     dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
     devDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),

package/src/sync.ts

@@ -26,7 +26,7 @@ import {
   observePathWithRawModes,
   type ObservedPath,
 } from "./path-digest.ts";
-import { readDirectDependencyNames } from "./project-package.ts";
+import { readDirectDependencyNames, readProjectPackage } from "./project-package.ts";
 import { acquireProjectProcessLock, PROJECT_PROCESS_LOCK_PATH } from "./project-process-lock.ts";
 import {
   AppliedStateSchema,
@@ -115,12 +115,14 @@ type SkillPlanAction =
       readonly action: "create" | "update";
       readonly desired: DesiredOutput;
       readonly observed: ObservedPath;
+      readonly stagedContent?: string;
     }
   | {
       readonly action: "remove";
       readonly previous: OwnershipReceipt;
       readonly destination: string;
       readonly observed: ObservedPath;
+      readonly stagedContent?: string;
     }
   | {
       readonly action: "unchanged";
@@ -234,6 +236,255 @@ const DEFAULT_LOCKFILE = "dev-kit.lock.json";
 const DEFAULT_STATE = ".dev-kit/state.json";
 const AGENT_INSTRUCTIONS_TEMPLATE = "templates/AGENTS.md";
 const DEV_KIT_SKILL_PATH_PLACEHOLDER = "{{DEV_KIT_SKILL_PATH}}";
+const PROJECT_COMMAND_POLICY_PLACEHOLDER = "{{PROJECT_COMMAND_POLICY}}";
+const AGENT_INSTRUCTION_MARKERS = [
+  { start: "<!-- DEV KIT START -->", end: "<!-- DEV KIT END -->" },
+  // Legacy Dev Kit releases copied this upstream section into AGENTS.md. Keep
+  // recognizing it so an owned section can be removed during migration.
+  { start: "<!--VITE PLUS START-->", end: "<!--VITE PLUS END-->" },
+] as const;
+
+type ManagedInstructionRange = {
+  readonly start: number;
+  readonly end: number;
+  readonly content: string;
+};
+
+type ManagedInstructionInspection =
+  | {
+      readonly kind: "valid";
+      readonly ranges: ReadonlyArray<ManagedInstructionRange>;
+      readonly content?: string;
+    }
+  | { readonly kind: "invalid"; readonly reason: string };
+
+const findOccurrences = (content: string, marker: string): ReadonlyArray<number> => {
+  const positions: Array<number> = [];
+  let offset = 0;
+
+  while (offset < content.length) {
+    const position = content.indexOf(marker, offset);
+
+    if (position === -1) break;
+    positions.push(position);
+    offset = position + marker.length;
+  }
+
+  return positions;
+};
+
+const inspectManagedInstructionSections = (content: string): ManagedInstructionInspection => {
+  const ranges: Array<ManagedInstructionRange> = [];
+
+  for (const markers of AGENT_INSTRUCTION_MARKERS) {
+    const starts = findOccurrences(content, markers.start);
+    const ends = findOccurrences(content, markers.end);
+
+    if (starts.length === 0 && ends.length === 0) continue;
+    if (
+      starts.length !== 1 ||
+      ends.length !== 1 ||
+      starts[0] === undefined ||
+      ends[0] === undefined
+    ) {
+      return {
+        kind: "invalid",
+        reason: `expected exactly one ${markers.start}/${markers.end} marker pair`,
+      };
+    }
+    if (starts[0] >= ends[0]) {
+      return { kind: "invalid", reason: `${markers.end} appears before ${markers.start}` };
+    }
+    const end = ends[0] + markers.end.length;
+
+    ranges.push({ start: starts[0], end, content: content.slice(starts[0], end) });
+  }
+  ranges.sort((left, right) => left.start - right.start);
+  for (let index = 1; index < ranges.length; index += 1) {
+    const previous = ranges[index - 1];
+    const current = ranges[index];
+
+    if (previous !== undefined && current !== undefined && current.start < previous.end) {
+      return { kind: "invalid", reason: "managed instruction marker pairs overlap" };
+    }
+  }
+
+  return {
+    kind: "valid",
+    ranges,
+    ...(ranges.length === 0
+      ? {}
+      : { content: `${ranges.map((range) => range.content.trim()).join("\n\n")}\n` }),
+  };
+};
+
+const removeManagedInstructionSections = (
+  content: string,
+  ranges: ReadonlyArray<ManagedInstructionRange>,
+): string => {
+  const first = ranges[0];
+  const last = ranges.at(-1);
+  const hasOnlyManagedSeparators = ranges.every((range, index) => {
+    const next = ranges[index + 1];
+
+    return next === undefined || /^\s*$/.test(content.slice(range.end, next.start));
+  });
+
+  if (first?.start === 0 && last !== undefined && hasOnlyManagedSeparators) {
+    let end = last.end;
+
+    if (content.startsWith("\r\n", end)) end += 2;
+    else if (content.startsWith("\n", end)) end += 1;
+
+    return content.slice(end);
+  }
+  let result = content;
+
+  for (const range of [...ranges].reverse()) {
+    result = result.slice(0, range.start) + result.slice(range.end);
+  }
+
+  return result;
+};
+
+const prependManagedInstructionSections = (content: string, managed: string): string => {
+  if (content.trim().length === 0) return managed;
+
+  return `${managed}${content}`;
+};
+
+const reconcileManagedInstructionSections = (
+  content: string,
+  inspection: Extract<ManagedInstructionInspection, { readonly kind: "valid" }>,
+  managed: string,
+): string =>
+  prependManagedInstructionSections(
+    removeManagedInstructionSections(content, inspection.ranges),
+    managed,
+  );
+
+const renderVitePlusCommandPolicy = (
+  scripts: Readonly<Record<string, string>>,
+  managesQualityConfig: boolean,
+): string => {
+  const hasCheck = managesQualityConfig || scripts.check !== undefined;
+  const hasTypecheck = managesQualityConfig || scripts.typecheck !== undefined;
+
+  return [
+    "## Project command policy",
+    "",
+    "Vite+ is the unified toolchain and command authority for this repository. It wraps Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task behind the `vp` CLI; Vite+ is distinct from Vite.",
+    "",
+    "Run `vp help` for available commands and `vp <command> --help` for command-specific options. Documentation is available locally in `node_modules/vite-plus/docs` and online at https://viteplus.dev/guide/.",
+    "",
+    "Use these repository commands:",
+    "",
+    "- Install dependencies: `vp install`.",
+    ...(hasCheck ? ["- Full validation: `vp run check`."] : []),
+    "- Static checks: `vp check`.",
+    "- Format check: `vp fmt --check`; format fixes: `vp fmt`.",
+    "- Lint only: `vp lint`; lint fixes: `vp lint --fix`.",
+    "- Tests only: `vp test`.",
+    ...(hasTypecheck ? ["- Typecheck only: `vp run typecheck`."] : []),
+    "- Other repository tasks and package scripts: `vp run <task>`.",
+    "- Toolchain or runtime troubleshooting: run `vp env doctor` and include its output when asking for help.",
+    "",
+    "Do not use `bun run`, `npm run`, `pnpm run`, or `yarn run` in this repository. Do not invoke underlying tools such as `tsc`, `vitest`, `oxlint`, or `oxfmt` directly; use the Vite+ entry points above.",
+  ].join("\n");
+};
+
+const PACKAGE_MANAGER_COMMANDS = {
+  bun: { install: "bun install", label: "Bun" },
+  npm: { install: "npm install", label: "npm" },
+  pnpm: { install: "pnpm install", label: "pnpm" },
+  yarn: { install: "yarn install", label: "Yarn" },
+} as const;
+
+type PackageManagerName = keyof typeof PACKAGE_MANAGER_COMMANDS;
+
+const packageManagerName = (declaration: string | undefined): PackageManagerName | undefined => {
+  const name = declaration?.split("@", 1)[0];
+
+  return name !== undefined && name in PACKAGE_MANAGER_COMMANDS
+    ? (name as PackageManagerName)
+    : undefined;
+};
+
+const detectPackageManager = Effect.fn("detectPackageManager")(function* (
+  projectDir: string,
+  declaration: string | undefined,
+) {
+  const declared = packageManagerName(declaration);
+
+  if (declared !== undefined || declaration !== undefined) return declared;
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const lockfiles: ReadonlyArray<readonly [PackageManagerName, ReadonlyArray<string>]> = [
+    ["bun", ["bun.lock", "bun.lockb"]],
+    ["npm", ["package-lock.json", "npm-shrinkwrap.json"]],
+    ["pnpm", ["pnpm-lock.yaml"]],
+    ["yarn", ["yarn.lock"]],
+  ];
+  const detected: Array<PackageManagerName> = [];
+
+  for (const [manager, files] of lockfiles) {
+    let found = false;
+
+    for (const file of files) {
+      if (yield* fs.exists(path.join(projectDir, file))) {
+        found = true;
+        break;
+      }
+    }
+    if (found) {
+      detected.push(manager);
+    }
+  }
+
+  return detected.length === 1 ? detected[0] : undefined;
+});
+
+const renderPackageScriptCommandPolicy = (
+  manager: PackageManagerName | undefined,
+  scripts: Readonly<Record<string, string>>,
+): string => {
+  const installer = manager === undefined ? undefined : PACKAGE_MANAGER_COMMANDS[manager];
+  const entries = [
+    ["check", "Full validation"],
+    ["format:check", "Format check"],
+    ["format", "Format"],
+    ["lint", "Lint"],
+    ["test", "Tests"],
+    ["typecheck", "Typecheck"],
+  ] as const;
+  const commands = entries.flatMap(([script, label]) =>
+    scripts[script] === undefined ? [] : [`- ${label}: \`bun run ${script}\`.`],
+  );
+  const knownScripts = new Set(entries.map(([script]) => script));
+  const additionalCommands = Object.keys(scripts)
+    .filter(
+      (script) =>
+        !knownScripts.has(script as (typeof entries)[number][0]) &&
+        /^(?:check|validate|fmt|format|lint|test|type-?check)(?::|$)/.test(script),
+    )
+    .sort()
+    .map((script) => `- Script \`${script}\`: \`bun run ${script}\`.`);
+  const qualityCommands = [...commands, ...additionalCommands];
+
+  return [
+    "## Project command policy",
+    "",
+    "Bun is the package-script runner for this repository:",
+    "",
+    ...(installer === undefined
+      ? []
+      : [`- Install dependencies with ${installer.label}: \`${installer.install}\`.`]),
+    ...qualityCommands,
+    ...(qualityCommands.length === 0 ? ["- No root quality scripts are currently declared."] : []),
+    "",
+    "Run only declared scripts through `bun run <script>`. Do not use `npm run`, `pnpm run`, or `yarn run`, invent missing scripts, or invoke underlying tools such as `tsc`, `vitest`, `eslint`, or `prettier` directly. The Bun script-runner requirement does not choose the package manager used to install dependencies.",
+  ].join("\n");
+};
 
 const resolvePackageRoot = Effect.fn("resolvePackageRoot")(function* () {
   const path = yield* Path.Path;
@@ -521,6 +772,7 @@ const renderAgentInstructions = Effect.fn("renderAgentInstructions")(function* (
   packageRoot: string,
   projectDir: string,
   sourceBySkill: ReadonlyMap<string, ResolvedSkillSource>,
+  managesVitePlusQuality: boolean,
 ) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
@@ -538,6 +790,11 @@ const renderAgentInstructions = Effect.fn("renderAgentInstructions")(function* (
       message: `dev-kit agent instructions template is missing ${DEV_KIT_SKILL_PATH_PLACEHOLDER}`,
     });
   }
+  if (!template.includes(PROJECT_COMMAND_POLICY_PLACEHOLDER)) {
+    return yield* new InvalidProjectStateError({
+      message: `dev-kit agent instructions template is missing ${PROJECT_COMMAND_POLICY_PLACEHOLDER}`,
+    });
+  }
 
   const devKitSkill = sourceBySkill.get("dev-kit");
   const devKitSkillPath =
@@ -550,21 +807,22 @@ const renderAgentInstructions = Effect.fn("renderAgentInstructions")(function* (
             path.join(devKitSkill.linkPath ?? devKitSkill.path, "SKILL.md"),
           ),
         );
-  const sections = [template.replaceAll(DEV_KIT_SKILL_PATH_PLACEHOLDER, devKitSkillPath).trimEnd()];
-
-  if ((yield* readDirectDependencyNames(projectDir)).includes("vite-plus")) {
-    const vitePlusTemplate = path.join(projectDir, "node_modules", "vite-plus", "AGENTS.md");
-
-    if ((yield* observePath(vitePlusTemplate)).kind !== "file") {
-      return yield* new InvalidProjectStateError({
-        message:
-          "Vite+ is a direct dependency but its agent instructions are not a regular file: node_modules/vite-plus/AGENTS.md",
-      });
-    }
-    sections.push((yield* fs.readFileString(vitePlusTemplate)).trim());
-  }
-
-  return `${sections.join("\n\n")}\n`;
+  const usesVitePlus = (yield* readDirectDependencyNames(projectDir)).includes("vite-plus");
+  const projectPackage = yield* readProjectPackage(projectDir).pipe(
+    Effect.catchTag("ProjectPackageError", (error) =>
+      error.message.startsWith("package.json not found:") ? Effect.void : Effect.fail(error),
+    ),
+  );
+  const manager = yield* detectPackageManager(projectDir, projectPackage?.packageManager);
+  const commandPolicy = usesVitePlus
+    ? renderVitePlusCommandPolicy(projectPackage?.scripts ?? {}, managesVitePlusQuality)
+    : renderPackageScriptCommandPolicy(manager, projectPackage?.scripts ?? {});
+  const devKitInstructions = template
+    .replaceAll(DEV_KIT_SKILL_PATH_PLACEHOLDER, devKitSkillPath)
+    .replaceAll(PROJECT_COMMAND_POLICY_PLACEHOLDER, commandPolicy)
+    .trimEnd();
+
+  return `${devKitInstructions}\n`;
 });
 
 const readGeneratedFileTemplate = Effect.fn("readGeneratedFileTemplate")(function* (
@@ -597,7 +855,12 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
 
   if (setup.agentInstructions.enabled) {
     const managed = yield* resolveManagedPath(projectDir, "AGENTS.md");
-    const content = yield* renderAgentInstructions(packageRoot, projectDir, sourceBySkill);
+    const content = yield* renderAgentInstructions(
+      packageRoot,
+      projectDir,
+      sourceBySkill,
+      setup.vitePlus.quality.config.enabled,
+    );
 
     outputs.push({
       resourceId: "setup:agent-instructions",
@@ -662,7 +925,7 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
       devKitCommand:
         projectDir === packageRoot
           ? "./bin/dev-kit.mjs apply --locked"
-          : "vp exec dev-kit apply --locked",
+          : "bun ./node_modules/@danieljvdm/dev-kit/bin/dev-kit.mjs apply --locked",
       workflow: setup.vitePlus.quality.workflow,
     });
 
@@ -803,6 +1066,89 @@ const planDesiredOutputs = Effect.fn("planDesiredSkillOutputs")(function* (
         (rawModeObservation?.kind === matchingLockedOutput.kind &&
           rawModeObservation.digest === matchingLockedOutput.digest));
 
+    if (output.resourceId === "setup:agent-instructions" && "content" in output) {
+      if (observed.kind === "missing") {
+        actions.push({
+          action: "create",
+          desired: output,
+          observed,
+          stagedContent: output.content,
+        });
+        continue;
+      }
+      if (observed.kind !== "file") {
+        actions.push({
+          action: "conflict",
+          path: output.path,
+          reason: "destination is not a regular file",
+        });
+        continue;
+      }
+      const existingContent = yield* FileSystem.FileSystem.pipe(
+        Effect.flatMap((fs) => fs.readFileString(output.destination)),
+      );
+      const inspection = inspectManagedInstructionSections(existingContent);
+
+      if (inspection.kind === "invalid") {
+        actions.push({ action: "conflict", path: output.path, reason: inspection.reason });
+        continue;
+      }
+      const managedDigest =
+        inspection.content === undefined ? undefined : yield* digestFileContent(inspection.content);
+      const receiptOwnsManaged =
+        sameReceipt !== undefined &&
+        (managedDigest === sameReceipt.digest || observed.digest === sameReceipt.digest);
+      const lockOwnsManaged =
+        matchingLockedOutput !== undefined &&
+        (managedDigest === matchingLockedOutput.digest ||
+          observed.digest === matchingLockedOutput.digest);
+      const legacyOwnsWholeFile =
+        (sameReceipt !== undefined &&
+          observed.digest === sameReceipt.digest &&
+          managedDigest !== sameReceipt.digest) ||
+        (matchingLockedOutput !== undefined &&
+          lockedOwnsObserved &&
+          managedDigest !== matchingLockedOutput.digest);
+
+      if (managedDigest === output.digest && !legacyOwnsWholeFile) {
+        if (sameReceipt !== undefined || lockOwnsManaged || lockedOwnsObserved) {
+          actions.push({
+            action: "unchanged",
+            desired: output,
+            observed,
+            adopted: sameReceipt === undefined,
+          });
+        } else {
+          actions.push({
+            action: "conflict",
+            path: output.path,
+            reason: "managed instruction sections exist but are not owned",
+          });
+        }
+      } else if (
+        managedDigest === undefined ||
+        receiptOwnsManaged ||
+        lockOwnsManaged ||
+        lockedOwnsObserved
+      ) {
+        actions.push({
+          action: "update",
+          desired: output,
+          observed,
+          stagedContent: legacyOwnsWholeFile
+            ? output.content
+            : reconcileManagedInstructionSections(existingContent, inspection, output.content),
+        });
+      } else {
+        actions.push({
+          action: "conflict",
+          path: output.path,
+          reason: "managed instruction sections exist but are not owned",
+        });
+      }
+      continue;
+    }
+
     if (observed.kind === "missing") {
       actions.push({ action: "create", desired: output, observed });
     } else if (observed.kind === output.kind && observed.digest === output.digest) {
@@ -839,6 +1185,46 @@ const planDesiredOutputs = Effect.fn("planDesiredSkillOutputs")(function* (
     const observed = yield* observePath(managed.absolute);
 
     if (observed.kind === "missing") continue;
+    if (receipt.resourceId === "setup:agent-instructions") {
+      if (observed.kind !== "file") {
+        actions.push({
+          action: "conflict",
+          path: receipt.path,
+          reason: "stale owned destination is not a regular file",
+        });
+        continue;
+      }
+      const existingContent = yield* FileSystem.FileSystem.pipe(
+        Effect.flatMap((fs) => fs.readFileString(managed.absolute)),
+      );
+      const inspection = inspectManagedInstructionSections(existingContent);
+
+      if (inspection.kind === "invalid") {
+        actions.push({ action: "conflict", path: receipt.path, reason: inspection.reason });
+        continue;
+      }
+      if (inspection.content === undefined) continue;
+      const managedDigest = yield* digestFileContent(inspection.content);
+
+      if (managedDigest === receipt.digest || observed.digest === receipt.digest) {
+        const remaining = removeManagedInstructionSections(existingContent, inspection.ranges);
+
+        actions.push({
+          action: "remove",
+          previous: receipt,
+          destination: managed.absolute,
+          observed,
+          ...(remaining.trim().length === 0 ? {} : { stagedContent: remaining }),
+        });
+      } else {
+        actions.push({
+          action: "conflict",
+          path: receipt.path,
+          reason: "stale owned managed instruction sections were modified",
+        });
+      }
+      continue;
+    }
     if (observed.kind === receipt.kind && observed.digest === receipt.digest) {
       actions.push({
         action: "remove",
@@ -1110,16 +1496,6 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
   const currentLock = yield* readOptionalStructuredFile(lockManaged.absolute, DevKitLockSchema);
   const currentState = yield* readOptionalStructuredFile(stateManaged.absolute, AppliedStateSchema);
 
-  if (
-    manifest.setup.claudeInstructions.enabled &&
-    !manifest.setup.agentInstructions.enabled &&
-    currentState?.outputs.some((output) => output.resourceId === "setup:agent-instructions")
-  ) {
-    return yield* new InvalidProjectStateError({
-      message:
-        "cannot disable agentInstructions while claudeInstructions still links to its AGENTS.md wrapper",
-    });
-  }
   yield* validateReservedPaths(projectDir, reservedPaths, [
     ...(currentLock?.outputs ?? []),
     ...(currentState?.outputs ?? []),
@@ -1143,6 +1519,19 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
     currentState,
     nextLock,
   );
+  const removesClaudeInstructionsSource = planned.actions.some(
+    (action) =>
+      action.action === "remove" &&
+      action.previous.resourceId === "setup:agent-instructions" &&
+      action.stagedContent === undefined,
+  );
+
+  if (manifest.setup.claudeInstructions.enabled && removesClaudeInstructionsSource) {
+    return yield* new InvalidProjectStateError({
+      message:
+        "cannot disable agentInstructions while claudeInstructions still links to an AGENTS.md that would be removed",
+    });
+  }
 
   return {
     projectDir,
@@ -1310,13 +1699,28 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
   let stageIndex = 0;
 
   for (const action of mutating) {
-    if (action.action === "remove") continue;
+    if (action.action === "remove" && action.stagedContent === undefined) continue;
     const staged = path.join(stageDir, String(stageIndex++));
 
     yield* fs.makeDirectory(path.dirname(staged), { recursive: true });
-    if (action.desired.mode === "copy") {
+    if (action.stagedContent !== undefined && action.observed.kind === "file") {
+      const destination =
+        action.action === "remove" ? action.destination : action.desired.destination;
+
+      yield* fs.copy(destination, staged, { overwrite: true });
+      yield* fs.writeFileString(staged, action.stagedContent);
+    } else if (action.action === "remove") {
+      if (action.stagedContent === undefined) {
+        return yield* new InvalidProjectStateError({
+          message: `missing staged content for ${action.previous.resourceId}`,
+        });
+      }
+      yield* fs.writeFileString(staged, action.stagedContent, { mode: 0o644 });
+    } else if (action.desired.mode === "copy") {
       if (action.desired.kind === "file") {
-        yield* fs.writeFileString(staged, action.desired.content, { mode: 0o644 });
+        yield* fs.writeFileString(staged, action.stagedContent ?? action.desired.content, {
+          mode: 0o644,
+        });
       } else {
         yield* fs.copy(action.desired.source, staged, { overwrite: true });
         const symbolicLink = yield* findNestedSymbolicLink(staged);
@@ -1330,14 +1734,35 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
     } else {
       yield* fs.symlink(action.desired.linkTarget, staged);
     }
-    const observation = yield* observePath(staged);
-
-    if (observation.kind !== action.desired.kind || observation.digest !== action.desired.digest) {
-      return yield* new InvalidProjectStateError({
-        message: `staged output digest mismatch for ${action.desired.path}`,
-      });
+    if (action.action !== "remove") {
+      const observation = yield* observePath(staged);
+
+      if (action.desired.resourceId === "setup:agent-instructions") {
+        const content = yield* fs.readFileString(staged);
+        const inspection = inspectManagedInstructionSections(content);
+        const digest =
+          inspection.kind === "valid" && inspection.content !== undefined
+            ? yield* digestFileContent(inspection.content)
+            : undefined;
+
+        if (observation.kind !== "file" || digest !== action.desired.digest) {
+          return yield* new InvalidProjectStateError({
+            message: `staged output digest mismatch for ${action.desired.path}`,
+          });
+        }
+      } else if (
+        observation.kind !== action.desired.kind ||
+        observation.digest !== action.desired.digest
+      ) {
+        return yield* new InvalidProjectStateError({
+          message: `staged output digest mismatch for ${action.desired.path}`,
+        });
+      }
     }
-    stagedByResource.set(action.desired.resourceId, staged);
+    stagedByResource.set(
+      action.action === "remove" ? action.previous.resourceId : action.desired.resourceId,
+      staged,
+    );
   }
 
   yield* verifyPackageSkillSources(plan);
@@ -1360,11 +1785,18 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
 
   for (const action of mutating) {
     const staged =
-      action.action === "remove" ? undefined : stagedByResource.get(action.desired.resourceId);
+      action.action === "remove"
+        ? stagedByResource.get(action.previous.resourceId)
+        : stagedByResource.get(action.desired.resourceId);
 
-    if (action.action !== "remove" && staged === undefined) {
+    if (
+      (action.action !== "remove" || action.stagedContent !== undefined) &&
+      staged === undefined
+    ) {
       return yield* new InvalidProjectStateError({
-        message: `missing staged output for ${action.desired.resourceId}`,
+        message: `missing staged output for ${
+          action.action === "remove" ? action.previous.resourceId : action.desired.resourceId
+        }`,
       });
     }
     replacements.push({

package/src/vite-plus-quality.ts

@@ -32,7 +32,8 @@ export type VitePlusQualitySelection = {
 };
 
 const SINGLE_PROJECT_TYPECHECK_TASK = '      typecheck: "tsc --noEmit",';
-const LOCKED_DEV_KIT_COMMAND = "vp exec dev-kit apply --locked";
+const LOCKED_DEV_KIT_COMMAND =
+  "bun ./node_modules/@danieljvdm/dev-kit/bin/dev-kit.mjs apply --locked";
 const BEFORE_CHECKS_MARKER =
   "      # Dev Kit inserts configured quality.workflow.beforeChecks steps here.\n\n";
 const DEFAULT_WORKFLOW_TYPECHECK = `      - name: Type check with Effect TypeScript-Go

package/templates/AGENTS.md

@@ -6,4 +6,6 @@ This project uses `@danieljvdm/dev-kit` to manage portable agent skills and repr
 
 For dev-kit operations, use the `dev-kit` skill and read `{{DEV_KIT_SKILL_PATH}}` before changing managed outputs.
 
+{{PROJECT_COMMAND_POLICY}}
+
 <!-- DEV KIT END -->

package/templates/vite-plus/github-actions-check.yml

@@ -22,6 +22,10 @@ jobs:
         with:
           persist-credentials: false
 
+      # setup-bun resolves the consumer's packageManager or engines.bun version.
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # setup-bun action v2.2.0
+
       # setup-vp's v1 tag is frozen. Keep this v1.16.1 commit current with
       # Renovate or Dependabot so fixes arrive through reviewed pull requests.
       - name: Set up Vite+ and install dependencies
@@ -34,7 +38,7 @@ jobs:
             args: ["--frozen-lockfile", "--ignore-scripts"]
 
       - name: Verify locked Dev Kit setup
-        run: vp exec dev-kit apply --locked
+        run: bun ./node_modules/@danieljvdm/dev-kit/bin/dev-kit.mjs apply --locked
 
       # Dev Kit inserts configured quality.workflow.beforeChecks steps here.