@danieljvdm/dev-kit 0.2.0 → 0.2.3

package/README.md

@@ -14,18 +14,37 @@ collection of unrelated postinstall scripts. It can:
 
 ## Quick start
 
-Install Dev Kit from GitHub:
+Install the published Dev Kit package:
 
 ```bash
-bun add -d github:danieljvdm/agent-skills
+bun add -d @danieljvdm/dev-kit
 ```
 
 Initialize the project, browse the approved catalog, and add skills:
 
 ```bash
-bunx dev-kit init
-bunx dev-kit list --all
-bunx dev-kit add dev-kit effect
+bun x dev-kit init
+bun x dev-kit list --all
+bun x dev-kit add dev-kit effect
+```
+
+Before adding external skills, have the agent inspect repository instructions,
+workspace dependencies, framework and tool configuration, representative
+source boundaries, and CI workflows. It should compare that concrete capability
+inventory with catalog descriptions and select the narrowest useful set. Broad
+umbrella skills and source families belong only when their full breadth is
+intentional; explicit creative or advisory requests remain valid even without a
+mechanical dependency signal. Treat lazy reference folders inside one skill as
+progressive-disclosure content, not as separately triggered skills; a repository
+using several covered products may reasonably select that umbrella while still
+excluding unrelated top-level skills.
+
+Search and inspect candidates, then add the matching skills individually:
+
+```bash
+bun x dev-kit search cloudflare
+bun x dev-kit info workers-best-practices
+bun x dev-kit add workers-best-practices wrangler
 ```
 
 `add` updates `dev-kit.jsonc` and applies the selection immediately. The
@@ -49,8 +68,8 @@ or use `--no-apply` to edit the manifest without syncing yet.
 For review-first workflows, edit the manifest or pass `--no-apply`, then:
 
 ```bash
-bunx dev-kit plan
-bunx dev-kit apply
+bun x dev-kit plan
+bun x dev-kit apply
 ```
 
 Commit the generated `dev-kit.lock.json`, then use locked mode in your package
@@ -135,7 +154,13 @@ tool versions. A project-local process lock also prevents concurrent applies.
 ```jsonc
 {
   "$schema": "./node_modules/@danieljvdm/dev-kit/schema/dev-kit.schema.json",
-  "include": ["dev-kit", "effect", "emilkowalski-skills"],
+  "include": [
+    "dev-kit",
+    "effect",
+    "workers-best-practices",
+    "wrangler",
+    "serve-sim"
+  ],
   "exclude": ["animation-vocabulary"],
   "targets": {
     "agents": { "enabled": true, "mode": "copy" },
@@ -147,8 +172,11 @@ tool versions. A project-local process lock also prevents concurrent applies.
 
 - `dev-kit` installs guidance for operating the toolkit itself.
 - `effect` expands to the consolidated `effect-ts` skill.
-- An approved source ID selects every skill from that catalog source.
-- An individual catalog skill can be selected directly.
+- 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.
+- An approved source ID is broad shorthand that selects every skill from that
+  source. Use it only when the scan confirms that every member applies.
 
 Dev Kit reserves `.repos/<source-id>` for project-local source checkouts. Run
 `dev-kit gitignore` to add `.repos/` and `.dev-kit/` to the project ignore file.
@@ -196,7 +224,7 @@ Pin the compatible packages in the consuming project:
 ```jsonc
 {
   "devDependencies": {
-    "@danieljvdm/dev-kit": "github:danieljvdm/agent-skills",
+    "@danieljvdm/dev-kit": "^0.2.0",
     "@effect/tsgo": "0.24.3",
     "typescript": "7.0.2"
   }

package/dev-kit.example.jsonc

@@ -1,6 +1,6 @@
 {
   "$schema": "./schema/dev-kit.schema.json",
-  "include": ["dev-kit", "effect", "emilkowalski-skills"],
+  "include": ["dev-kit", "effect"],
   "setup": {
     "effectSource": { "enabled": true },
     "effectTsgo": { "enabled": true }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@danieljvdm/dev-kit",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "private": false,
   "type": "module",
   "description": "Declarative project development toolkit with portable agent skills.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/danieljvdm/agent-skills.git"
+    "url": "git+https://github.com/danieljvdm/dev-kit.git"
   },
   "license": "MIT",
   "bin": {
@@ -34,7 +34,7 @@
     "prepare": "./bin/dev-kit.mjs apply --locked",
     "dev-kit": "./bin/dev-kit.mjs",
     "changeset": "changeset",
-    "version-packages": "changeset version",
+    "version-packages": "changeset version && ./bin/dev-kit.mjs apply",
     "release": "changeset publish",
     "check": "tsc --noEmit",
     "plan": "./bin/dev-kit.mjs plan",

package/schema/dev-kit.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/danieljvdm/agent-skills/main/schema/dev-kit.schema.json",
+  "$id": "https://raw.githubusercontent.com/danieljvdm/dev-kit/main/schema/dev-kit.schema.json",
   "title": "Dev Kit Manifest",
   "description": "Project-local desired state for portable skills and explicit dev-kit setup tasks.",
   "type": "object",
@@ -10,7 +10,7 @@
       "type": "string"
     },
     "include": {
-      "description": "Skill names or family names to sync. External source ids are available as family names.",
+      "description": "Skill names or family names to sync. Prefer individually relevant external skills; an external source id selects every approved skill from that source.",
       "type": "array",
       "items": {
         "type": "string",

package/schema/skill-sources.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/danieljvdm/agent-skills/main/schema/skill-sources.schema.json",
+  "$id": "https://raw.githubusercontent.com/danieljvdm/dev-kit/main/schema/skill-sources.schema.json",
   "title": "External Agent Skill Sources",
   "description": "Repository-level sources approved for the skill catalog.",
   "type": "object",
@@ -23,7 +23,7 @@
       "additionalProperties": false,
       "properties": {
         "id": {
-          "description": "Unique source id. It also becomes a family name in project manifests.",
+          "description": "Unique source id. It also becomes broad family shorthand that selects every approved source skill in project manifests.",
           "type": "string",
           "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
         },

package/skills/dev-kit/SKILL.md

@@ -21,26 +21,46 @@ stores explicit skill names and exact commit/content digests.
 
 ## Apply loop
 
-1. Establish the Git root. Read `dev-kit.jsonc`, `dev-kit.lock.json` when
-   present, `package.json`, and the configured target paths. Finish with the
-   intended skill selection, targets, and setup tasks identified.
-2. Update `dev-kit.jsonc`. Preserve JSONC comments and validate against the
-   package schema. Finish when every desired resource is represented once.
-3. Run `dev-kit plan`. Use `--manifest`, `--project-dir`, or `--lockfile` when
+1. Establish the Git root. Read project agent instructions, the current
+   manifest and lock, package and workspace manifests, framework and tool
+   configuration, representative source boundaries, and CI workflows. Build a
+   concrete inventory of the platforms, frameworks, tools, and workflows the
+   repository actually uses; do not infer capabilities from a product or
+   company name alone.
+2. Run `dev-kit list --all`, then use `dev-kit search <terms>` and `dev-kit info
+   <skill>` for each capability in the inventory. Compare every candidate's
+   trigger description with concrete repository evidence. Keep explicitly
+   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.
+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.
+5. Run `dev-kit plan`. Use `--manifest`, `--project-dir`, or `--lockfile` when
    the project overrides their defaults. Planning is read-only; inspect every
    create, update, remove, adoption, and conflict before proceeding. Finish
    when the plan contains only intended actions and understood conflicts.
-4. Resolve conflicts, then run `dev-kit apply`. Commit the manifest and
+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.
-5. Use `dev-kit apply --locked` in CI and the package lifecycle. Finish when a
+7. Use `dev-kit apply --locked` in CI and the package lifecycle. 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`. Include this skill as `dev-kit` when project agents should carry the
-toolkit procedure.
+`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.
 
 ```jsonc
 {

package/src/project-process-lock.ts

@@ -9,7 +9,7 @@ export class ProjectAlreadyLockedError extends Schema.TaggedErrorClass<ProjectAl
   { path: Schema.String },
 ) {
   override get message() {
-    return `another dev-kit apply may be active (${this.path}); verify the owner before removing a stale lock`;
+    return `another dev-kit operation may be active (${this.path}); verify the owner before removing a stale lock`;
   }
 }
 

package/src/skill-manager.ts

@@ -5,6 +5,7 @@ import { Prompt } from "effect/unstable/cli";
 import { loadSkillCatalog } from "./catalog.ts";
 import { isInteractiveTerminal, printDetail, printLine, printStatus } from "./cli-ui.ts";
 import { DevKitManifestSchema } from "./manifest.ts";
+import { observeSymbolicLink } from "./node-symbolic-link.ts";
 import { runProjectSkillPlan } from "./sync.ts";
 import { patchProjectGitignore } from "./gitignore.ts";
 
@@ -27,22 +28,83 @@ const packageRoot = Effect.fn("skillManagerPackageRoot")(function* () {
 const resolvePaths = Effect.fn("resolveSkillManagerPaths")(function* (
   options: ManagerOptions,
 ) {
+  const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const projectDir = path.resolve(options.projectDir ?? ".");
+  const candidate = options.manifestPath ?? "dev-kit.jsonc";
+  if (candidate.length === 0 || path.isAbsolute(candidate)) {
+    return yield* new SkillManagerError({
+      message: "--manifest must be a non-empty project-relative path",
+    });
+  }
+  const manifestPath = path.resolve(projectDir, candidate);
+  const relative = path.relative(projectDir, manifestPath);
+  if (
+    relative === ".." ||
+    relative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative)
+  ) {
+    return yield* new SkillManagerError({
+      message: "--manifest must resolve inside the project",
+    });
+  }
+  let ancestor = projectDir;
+  for (const segment of relative.split(path.sep).slice(0, -1)) {
+    ancestor = path.join(ancestor, segment);
+    if ((yield* observeSymbolicLink(ancestor)).kind === "symlink") {
+      return yield* new SkillManagerError({
+        message: `manifest ancestor is a symlink: ${path.relative(projectDir, ancestor)}`,
+      });
+    }
+  }
+  const destination = yield* observeSymbolicLink(manifestPath);
+  if (destination.kind === "symlink") {
+    return yield* new SkillManagerError({ message: `manifest is a symlink: ${relative}` });
+  }
+  if (destination.kind === "not-symlink" && (yield* fs.stat(manifestPath)).type !== "File") {
+    return yield* new SkillManagerError({ message: `manifest is not a regular file: ${relative}` });
+  }
   return {
     projectDir,
-    manifestPath: path.resolve(projectDir, options.manifestPath ?? "dev-kit.jsonc"),
+    manifestPath,
   };
 });
 
-const defaultManifest = `{
-  "$schema": "./node_modules/@danieljvdm/dev-kit/schema/dev-kit.schema.json",
-  "include": [],
-  "targets": {
-    "agents": { "enabled": true, "mode": "copy" }
-  }
-}
-`;
+const renderDefaultManifest = (projectDir: string, manifestPath: string, path: Path.Path) => {
+  const rawSchemaPath = path.relative(
+    path.dirname(manifestPath),
+    path.join(projectDir, "node_modules", "@danieljvdm", "dev-kit", "schema", "dev-kit.schema.json"),
+  );
+  const portableSchemaPath = path.sep === "/"
+    ? rawSchemaPath
+    : rawSchemaPath.split(path.sep).join("/");
+  const schemaPath = portableSchemaPath.startsWith(".")
+    ? portableSchemaPath
+    : `./${portableSchemaPath}`;
+  return `${JSON.stringify({
+    $schema: schemaPath,
+    include: [],
+    targets: { agents: { enabled: true, mode: "copy" } },
+  }, null, 2)}\n`;
+};
+
+const createDefaultManifest = Effect.fn("createDefaultSkillManifest")(function* (
+  paths: { readonly projectDir: string; readonly manifestPath: string },
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  yield* fs.makeDirectory(path.dirname(paths.manifestPath), { recursive: true });
+  const staged = yield* fs.makeTempFileScoped({
+    directory: path.dirname(paths.manifestPath),
+    prefix: ".dev-kit-init-",
+  });
+  yield* fs.writeFileString(
+    staged,
+    renderDefaultManifest(paths.projectDir, paths.manifestPath, path),
+  );
+  yield* fs.rename(staged, paths.manifestPath);
+  yield* patchProjectGitignore({ projectDir: paths.projectDir });
+});
 
 const readManifest = Effect.fn("readManagedSkillManifest")(function* (
   options: ManagerOptions,
@@ -56,8 +118,7 @@ const readManifest = Effect.fn("readManagedSkillManifest")(function* (
         message: "dev-kit.jsonc not found. Run `dev-kit init` first.",
       });
     }
-    yield* fs.writeFileString(paths.manifestPath, defaultManifest);
-    yield* patchProjectGitignore({ projectDir: paths.projectDir });
+    yield* createDefaultManifest(paths);
   }
   const raw = yield* fs.readFileString(paths.manifestPath);
   const errors: Array<ParseError> = [];
@@ -147,8 +208,7 @@ export const initProject = Effect.fn("initDevKitProject")(function* (options: Ma
     yield* printStatus("info", "Already initialized", paths.manifestPath);
     return;
   }
-  yield* fs.writeFileString(paths.manifestPath, defaultManifest);
-  yield* patchProjectGitignore({ projectDir: paths.projectDir });
+  yield* createDefaultManifest(paths);
   yield* printStatus("success", "Created dev-kit.jsonc");
   yield* printDetail("Add a skill with: dev-kit add <name>");
 });
@@ -166,6 +226,16 @@ export const addSkills = Effect.fn("addManagedSkills")(function* (
       message: `unknown skill${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}. Try \`dev-kit search ${unknown[0]}\`.`,
     });
   }
+  for (const source of catalog.lock?.sources ?? []) {
+    if (!names.includes(source.id)) continue;
+    yield* printStatus(
+      "info",
+      `Source family ${source.id} selects all ${source.skills.length} approved skills`,
+    );
+    yield* printDetail(
+      `Prefer individual skill names unless every skill applies. Inspect with: dev-kit search ${source.id}`,
+    );
+  }
   const include = [...new Set([...current.manifest.include, ...names])];
   const exclude = (current.manifest.exclude ?? []).filter((name) => !names.includes(name));
   yield* writeArray(current.manifestPath, current.raw, "include", include);
@@ -234,7 +304,8 @@ export const listSkills = Effect.fn("listManagedSkills")(function* (
   for (const skill of visible) {
     const marker = selected.has(skill.name) ? "✓" : " ";
     const origin = skill.bundled ? "built in" : skill.source;
-    yield* printLine(`${marker} ${skill.name}  ${summary(skill.description, origin)}`);
+    const provenance = skill.bundled ? "" : ` [${skill.source}]`;
+    yield* printLine(`${marker} ${skill.name}${provenance}  ${summary(skill.description, origin)}`);
   }
   yield* printLine();
   yield* printLine(`${selected.size} selected · ${catalog.skills.length} approved`);

package/src/sync.ts

@@ -786,7 +786,13 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
   yield* fs.writeFileString(stagedLock, canonicalLock(plan.nextLock));
   yield* fs.writeFileString(stagedState, canonicalState(plan.nextState));
 
-  type Replacement = { readonly destination: string; readonly backup: string; readonly staged?: string };
+  type Replacement = {
+    readonly destination: string;
+    readonly backup: string;
+    readonly expected?: ObservedPath;
+    readonly path: string;
+    readonly staged?: string;
+  };
   const replacements: Array<Replacement> = [];
   let replacementIndex = 0;
   for (const action of mutating) {
@@ -801,12 +807,24 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
     replacements.push({
       destination: action.action === "remove" ? action.destination : action.desired.destination,
       backup: path.join(backupDir, String(replacementIndex++)),
+      expected: action.observed,
+      path: action.action === "remove" ? action.previous.path : action.desired.path,
       ...(staged === undefined ? {} : { staged }),
     });
   }
   replacements.push(
-    { destination: plan.lockfilePath, backup: path.join(backupDir, "lock"), staged: stagedLock },
-    { destination: plan.statePath, backup: path.join(backupDir, "state"), staged: stagedState },
+    {
+      destination: plan.lockfilePath,
+      backup: path.join(backupDir, "lock"),
+      path: plan.lockfilePath,
+      staged: stagedLock,
+    },
+    {
+      destination: plan.statePath,
+      backup: path.join(backupDir, "state"),
+      path: plan.statePath,
+      staged: stagedState,
+    },
   );
 
   const installed: Array<string> = [];
@@ -824,6 +842,12 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
   const apply = Effect.gen(function* () {
     for (const replacement of replacements) {
       const observed = yield* observePath(replacement.destination);
+      if (
+        replacement.expected !== undefined &&
+        !observationsEqual(observed, replacement.expected)
+      ) {
+        return yield* new ApplyRaceError({ path: replacement.path });
+      }
       if (observed.kind !== "missing") {
         yield* fs.makeDirectory(path.dirname(replacement.backup), { recursive: true });
         yield* fs.rename(replacement.destination, replacement.backup);

package/src/vendor.ts

@@ -4,6 +4,7 @@ import { ChildProcess } from "effect/unstable/process";
 
 import { printStatus, withSpinner } from "./cli-ui.ts";
 import { observePath, type Digest } from "./path-digest.ts";
+import { acquireProjectProcessLock } from "./project-process-lock.ts";
 
 import {
   SkillSourcesLockSchema,
@@ -754,6 +755,7 @@ export const refreshSkillCatalog = Effect.fn("refreshSkillCatalog")(function* (
         : Effect.fail(error),
     ),
   );
+  yield* acquireProjectProcessLock(repoDir);
   const sourcesPath = path.resolve(repoDir, options.sourcesPath ?? DEFAULT_SOURCES_PATH);
   const lockfilePath = path.resolve(repoDir, options.lockfilePath ?? DEFAULT_LOCKFILE_PATH);
   const manifest = yield* readJsonc(sourcesPath, SkillSourcesManifestSchema);