@danieljvdm/dev-kit 0.3.3 → 0.5.0

package/src/manifest.ts

@@ -1,5 +1,6 @@
 import { Schema } from "effect";
 
+import { SKILL_SELECTOR_PATTERN } from "./skill-selector.ts";
 import { TYPESCRIPT_PACKAGE_NAME_PATTERN } from "./typescript-package-name.ts";
 
 export type HarnessTarget = "agents" | "claude" | "opencode";
@@ -36,12 +37,19 @@ export const EffectSourceSetupSchema = Schema.Struct({
 
 export type EffectSourceSetup = typeof EffectSourceSetupSchema.Type;
 
+export const ClaudeInstructionsSetupSchema = Schema.Struct({
+  enabled: Schema.optional(Schema.Boolean),
+});
+
+export type ClaudeInstructionsSetup = typeof ClaudeInstructionsSetupSchema.Type;
+
 export const DevKitManifestSchema = Schema.Struct({
   $schema: Schema.optional(Schema.String),
-  include: Schema.Array(Schema.String),
-  exclude: Schema.optional(Schema.Array(Schema.String)),
+  include: Schema.Array(Schema.String.check(Schema.isPattern(SKILL_SELECTOR_PATTERN))),
+  exclude: Schema.optional(Schema.Array(Schema.String.check(Schema.isPattern(SKILL_SELECTOR_PATTERN)))),
   setup: Schema.optional(
     Schema.Struct({
+      claudeInstructions: Schema.optional(ClaudeInstructionsSetupSchema),
       effectSource: Schema.optional(EffectSourceSetupSchema),
       effectTsgo: Schema.optional(EffectTsgoSetupSchema),
     }),
@@ -67,6 +75,9 @@ export type NormalizedManifest = {
   readonly include: ReadonlyArray<string>;
   readonly exclude: ReadonlyArray<string>;
   readonly setup: {
+    readonly claudeInstructions: {
+      readonly enabled: boolean;
+    };
     readonly effectSource: {
       readonly enabled: boolean;
       readonly packageName: string;
@@ -114,6 +125,9 @@ export const normalizeManifest = (manifest: DevKitManifest): NormalizedManifest
     exclude: manifest.exclude ?? [],
     include: manifest.include,
     setup: {
+      claudeInstructions: {
+        enabled: manifest.setup?.claudeInstructions?.enabled ?? false,
+      },
       effectSource: {
         enabled: manifest.setup?.effectSource?.enabled ?? false,
         packageName: manifest.setup?.effectSource?.packageName ?? "effect",

package/src/oxfmt.js

@@ -0,0 +1,18 @@
+/**
+ * Runtime form of the typed preset declared in oxfmt.ts.
+ *
+ * This file is intentionally plain JavaScript because Node does not strip
+ * TypeScript from packages in node_modules when tools load their config.
+ */
+export const recommendedOxfmtConfig = {
+  arrowParens: "always",
+  endOfLine: "lf",
+  printWidth: 100,
+  semi: true,
+  singleQuote: false,
+  sortImports: true,
+  sortPackageJson: true,
+  tabWidth: 2,
+  trailingComma: "all",
+  useTabs: false,
+};

package/src/oxfmt.ts

@@ -0,0 +1,22 @@
+import type { OxfmtConfig } from "oxfmt";
+
+/**
+ * Canonical formatting defaults for standalone Oxfmt and Vite+ projects.
+ *
+ * Oxfmt does not support config inheritance. Spread this object into a
+ * standalone Oxfmt config or Vite+'s `fmt` block before local overrides.
+ */
+export const recommendedOxfmtConfig = {
+  arrowParens: "always",
+  endOfLine: "lf",
+  printWidth: 100,
+  semi: true,
+  singleQuote: false,
+  sortImports: true,
+  sortPackageJson: true,
+  tabWidth: 2,
+  trailingComma: "all",
+  useTabs: false,
+} satisfies OxfmtConfig;
+
+export type RecommendedOxfmtConfig = typeof recommendedOxfmtConfig;

package/src/oxlint-plugin-effect.d.ts

@@ -0,0 +1,17 @@
+interface EffectOxlintRule {
+  readonly meta: {
+    readonly type: "problem";
+    readonly docs: { readonly description: string };
+    readonly messages: Readonly<Record<string, string>>;
+  };
+  readonly create: (context: {
+    report(descriptor: { node: unknown; messageId: string }): void;
+  }) => Readonly<Record<string, (node: unknown) => void>>;
+}
+
+declare const effectOxlintPlugin: {
+  readonly meta: { readonly name: "dev-kit-effect" };
+  readonly rules: Readonly<Record<string, EffectOxlintRule>>;
+};
+
+export default effectOxlintPlugin;

package/src/oxlint-plugin-effect.js

@@ -0,0 +1,166 @@
+const noUntypedThrow = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow throw statements from Effect-owned application code." },
+    messages: {
+      noUntypedThrow:
+        "Do not throw from Effect-owned code. Fail with a tagged error in the Effect error channel.",
+    },
+  },
+  create(context) {
+    return {
+      ThrowStatement(node) {
+        context.report({ node, messageId: "noUntypedThrow" });
+      },
+    };
+  },
+};
+
+const noPromiseAtomMode = {
+  meta: {
+    type: "problem",
+    docs: { description: "Require Effect Atom AsyncResult mode for React mutations." },
+    messages: {
+      noPromiseAtomMode:
+        'Do not use Effect Atom mode: "promise". Compose the workflow with Atom.fn and render its AsyncResult.',
+    },
+  },
+  create(context) {
+    return {
+      Property(node) {
+        const key = node.key;
+        const value = node.value;
+        const isMode =
+          (key.type === "Identifier" && key.name === "mode") ||
+          (key.type === "Literal" && key.value === "mode");
+        if (isMode && value.type === "Literal" && value.value === "promise") {
+          context.report({ node, messageId: "noPromiseAtomMode" });
+        }
+      },
+    };
+  },
+};
+
+const noEffectRun = {
+  meta: {
+    type: "problem",
+    docs: { description: "Keep Effect runtime execution at explicit host entry points." },
+    messages: {
+      noEffectRun:
+        "Do not execute Effect with Effect.run* inside application code. Return or compose the Effect instead.",
+    },
+  },
+  create(context) {
+    return {
+      MemberExpression(node) {
+        if (
+          node.object.type === "Identifier" &&
+          node.object.name === "Effect" &&
+          !node.computed &&
+          node.property.type === "Identifier" &&
+          node.property.name.startsWith("run")
+        ) {
+          context.report({ node, messageId: "noEffectRun" });
+        }
+      },
+    };
+  },
+};
+
+const noUnsafePromise = {
+  meta: {
+    type: "problem",
+    docs: { description: "Require rejecting Promise boundaries to preserve typed failures." },
+    messages: {
+      noEffectPromise:
+        "Effect.promise turns rejection into a defect. Use Effect.tryPromise and map a tagged boundary error.",
+      noPromiseConstructor:
+        "Do not construct workflow Promises directly. Use Effect async/scheduling/concurrency operators.",
+    },
+  },
+  create(context) {
+    return {
+      MemberExpression(node) {
+        if (
+          node.object.type === "Identifier" &&
+          node.object.name === "Effect" &&
+          !node.computed &&
+          node.property.type === "Identifier" &&
+          node.property.name === "promise"
+        ) {
+          context.report({ node, messageId: "noEffectPromise" });
+        }
+      },
+      NewExpression(node) {
+        if (node.callee.type === "Identifier" && node.callee.name === "Promise") {
+          context.report({ node, messageId: "noPromiseConstructor" });
+        }
+      },
+    };
+  },
+};
+
+const noAsyncWorkflow = {
+  meta: {
+    type: "problem",
+    docs: { description: "Keep business workflows in Effect instead of async functions." },
+    messages: {
+      noAsyncWorkflow:
+        "Do not implement application workflows as async functions. Return an Effect and capture foreign Promises with Effect.tryPromise.",
+    },
+  },
+  create(context) {
+    const check = (node) => {
+      if (!node.async) return;
+      const parent = node.parent;
+      const isCapturedTryThunk =
+        parent?.type === "Property" &&
+        ((parent.key.type === "Identifier" && parent.key.name === "try") ||
+          (parent.key.type === "Literal" && parent.key.value === "try"));
+      if (!isCapturedTryThunk) context.report({ node, messageId: "noAsyncWorkflow" });
+    };
+    return {
+      ArrowFunctionExpression: check,
+      FunctionDeclaration: check,
+      FunctionExpression: check,
+    };
+  },
+};
+
+const noSyncBoundaryDecode = {
+  meta: {
+    type: "problem",
+    docs: { description: "Prevent external values from becoming synchronous schema defects." },
+    messages: {
+      noSyncBoundaryDecode:
+        "Do not synchronously decode route, persisted, or native input. Use Schema.decodeUnknownEffect/Option and handle the typed failure.",
+    },
+  },
+  create(context) {
+    return {
+      MemberExpression(node) {
+        if (
+          node.object.type === "Identifier" &&
+          node.object.name === "Schema" &&
+          !node.computed &&
+          node.property.type === "Identifier" &&
+          node.property.name === "decodeUnknownSync"
+        ) {
+          context.report({ node, messageId: "noSyncBoundaryDecode" });
+        }
+      },
+    };
+  },
+};
+
+export default {
+  meta: { name: "dev-kit-effect" },
+  rules: {
+    "no-async-workflow": noAsyncWorkflow,
+    "no-effect-run": noEffectRun,
+    "no-promise-atom-mode": noPromiseAtomMode,
+    "no-sync-boundary-decode": noSyncBoundaryDecode,
+    "no-untyped-throw": noUntypedThrow,
+    "no-unsafe-promise": noUnsafePromise,
+  },
+};

package/src/oxlint.js

@@ -8,6 +8,12 @@ export const recommendedOxlintConfig = {
   options: {
     typeAware: true,
   },
+  jsPlugins: [
+    {
+      name: "effect",
+      specifier: "@danieljvdm/dev-kit/oxlint-plugin-effect",
+    },
+  ],
   plugins: ["import", "react", "vitest"],
   rules: {
     eqeqeq: "error",

package/src/oxlint.ts

@@ -1,15 +1,22 @@
-import type { OxlintConfig } from "vite-plus/lint";
+import type { OxlintConfig } from "oxlint";
 
 /**
- * High-signal Oxlint defaults for TypeScript projects using Vite+.
+ * High-signal Oxlint defaults for TypeScript projects.
  *
- * Extend this object from `lint.extends` so project-local plugins, rules, and
- * overrides compose without losing nested configuration.
+ * Extend this object from standalone Oxlint's `extends`, or from Vite+'s
+ * `lint.extends`, so project-local plugins, rules, and overrides compose
+ * without losing nested configuration.
  */
 export const recommendedOxlintConfig = {
   options: {
     typeAware: true,
   },
+  jsPlugins: [
+    {
+      name: "effect",
+      specifier: "@danieljvdm/dev-kit/oxlint-plugin-effect",
+    },
+  ],
   plugins: ["import", "react", "vitest"],
   rules: {
     eqeqeq: "error",

package/src/package-skill-source.ts

@@ -0,0 +1,272 @@
+import { Effect, FileSystem, Path, Result, Schema } from "effect";
+
+import { observeSymbolicLink } from "./node-symbolic-link.ts";
+import { isSkillName, parseSkillSelector } from "./skill-selector.ts";
+import { isTypeScriptPackageName } from "./typescript-package-name.ts";
+
+export class PackageSkillSourceError extends Schema.TaggedErrorClass<PackageSkillSourceError>()(
+  "PackageSkillSourceError",
+  { message: Schema.String },
+) {}
+
+export type PackageSkillDiagnostic = {
+  readonly package: string;
+  readonly message: string;
+};
+
+export type DiscoveredPackageSkill = {
+  readonly selector: string;
+  readonly name: string;
+  readonly description: string;
+  readonly package: string;
+  readonly version: string;
+  readonly path: string;
+  readonly linkPath: string;
+};
+
+const ProjectPackageSchema = Schema.fromJsonString(Schema.Struct({
+  dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  devDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  optionalDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  peerDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+}));
+
+const PackageMetadataSchema = Schema.fromJsonString(Schema.Struct({
+  name: Schema.String,
+  version: Schema.String,
+  intent: Schema.optional(Schema.Unknown),
+  repository: Schema.optional(Schema.Unknown),
+}));
+
+const nonEmptyString = (value: unknown): value is string =>
+  typeof value === "string" && value.trim().length > 0;
+
+const hasIntentDiscoveryMetadata = (metadata: typeof PackageMetadataSchema.Type): boolean => {
+  const intent = metadata.intent;
+  if (typeof intent === "object" && intent !== null &&
+    "version" in intent && intent.version === 1 &&
+    "repo" in intent && nonEmptyString(intent.repo) &&
+    "docs" in intent && nonEmptyString(intent.docs)) {
+    return true;
+  }
+  const repository = metadata.repository;
+  return nonEmptyString(repository) ||
+    (typeof repository === "object" && repository !== null &&
+      "url" in repository && nonEmptyString(repository.url));
+};
+
+const isSafePackageVersion = (value: string): boolean =>
+  value.length > 0 && value.trim() === value && ![...value].some((character) => {
+    const code = character.charCodeAt(0);
+    return code <= 32 || (code >= 127 && code <= 159);
+  });
+
+const isContained = (path: Path.Path, root: string, candidate: string): boolean => {
+  const relative = path.relative(root, candidate);
+  return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+};
+
+const frontmatterScalar = (document: string, key: string): string | undefined => {
+  const body = document.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+  if (body === undefined) return undefined;
+  const lines = body.split(/\r?\n/);
+  const index = lines.findIndex((line) => line.startsWith(`${key}:`));
+  if (index < 0) return undefined;
+  const raw = lines[index]?.slice(key.length + 1).trim() ?? "";
+  const block = raw.match(/^([|>])(?:[1-9][+-]?|[+-][1-9]?)?$/)?.[1];
+  if (block !== undefined) {
+    const values: Array<string> = [];
+    for (const line of lines.slice(index + 1)) {
+      if (line.length > 0 && !/^\s/.test(line)) break;
+      values.push(line.trim());
+    }
+    const value = block === "|" ? values.join("\n").trim() : values.join(" ").trim();
+    return value.length > 0 ? value : undefined;
+  }
+  const quoted = raw.match(/^(['"])([\s\S]*?)\1(?:\s+#.*)?$/)?.[2];
+  const value = (quoted ?? raw.replace(/\s+#.*$/, "")).trim();
+  return value.length > 0 ? value : undefined;
+};
+
+const skillName = (document: string): string | undefined =>
+  frontmatterScalar(document, "name");
+
+const skillDescription = (document: string): string | undefined =>
+  frontmatterScalar(document, "description");
+
+const rejectNestedSymlinks = Effect.fn("rejectPackageSkillSymlinks")(function* (skillRoot: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const pending = [skillRoot];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (current === undefined) continue;
+    if ((yield* observeSymbolicLink(current)).kind === "symlink") {
+      return yield* new PackageSkillSourceError({ message: `package skill contains a symlink: ${current}` });
+    }
+    const info = yield* fs.stat(current).pipe(
+      Effect.mapError(() => new PackageSkillSourceError({ message: `could not inspect package skill: ${current}` })),
+    );
+    if (info.type !== "Directory") continue;
+    for (const entry of yield* fs.readDirectory(current).pipe(
+      Effect.mapError(() => new PackageSkillSourceError({ message: `could not read package skill: ${current}` })),
+    )) pending.push(path.join(current, entry));
+  }
+});
+
+const readDirectDependencyNames = Effect.fn("readDirectPackageSkillDependencyNames")(function* (projectDir: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const manifestPath = path.join(projectDir, "package.json");
+  const manifest = yield* fs.readFileString(manifestPath).pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(ProjectPackageSchema)),
+    Effect.mapError(() => new PackageSkillSourceError({ message: `invalid project package.json: ${manifestPath}` })),
+  );
+  return [...new Set([
+    ...Object.keys(manifest.dependencies ?? {}),
+    ...Object.keys(manifest.devDependencies ?? {}),
+    ...Object.keys(manifest.optionalDependencies ?? {}),
+    ...Object.keys(manifest.peerDependencies ?? {}),
+  ])].sort();
+});
+
+type InstalledPackageSkills = {
+  readonly package: string;
+  readonly version: string;
+  readonly packageLink: string;
+  readonly skillsRoot: string;
+  readonly names: ReadonlyArray<string>;
+};
+
+const loadInstalledPackageSkills = Effect.fn("loadInstalledPackageSkills")(function* (
+  projectDir: string,
+  packageName: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const packageLink = path.join(projectDir, "node_modules", ...packageName.split("/"));
+  const packageRoot = yield* fs.realPath(packageLink).pipe(
+    Effect.mapError(() => new PackageSkillSourceError({ message: `package skill package is not installed: ${packageName}` })),
+  );
+  const packageInfo = yield* fs.stat(packageRoot).pipe(
+    Effect.mapError(() => new PackageSkillSourceError({ message: `could not inspect package skill package: ${packageName}` })),
+  );
+  if (packageInfo.type !== "Directory") return yield* new PackageSkillSourceError({ message: `package skill package is not a directory: ${packageName}` });
+  const metadata = yield* fs.readFileString(path.join(packageRoot, "package.json")).pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(PackageMetadataSchema)),
+    Effect.mapError(() => new PackageSkillSourceError({ message: `invalid package.json for package skill package: ${packageName}` })),
+  );
+  if (metadata.name !== packageName) return yield* new PackageSkillSourceError({ message: `package.json name does not match package skill package: ${packageName}` });
+  if (!isSafePackageVersion(metadata.version)) return yield* new PackageSkillSourceError({ message: `package.json has an invalid version for package skill package: ${packageName}` });
+  if (!hasIntentDiscoveryMetadata(metadata)) return yield* new PackageSkillSourceError({ message: `package does not declare Intent-compatible discovery metadata: ${packageName}` });
+  const skillsPath = "skills";
+  const skillsLink = path.join(packageLink, skillsPath);
+  if ((yield* observeSymbolicLink(skillsLink)).kind === "symlink") return yield* new PackageSkillSourceError({ message: `package skills path is a symlink: ${packageName}/${skillsPath}` });
+  const skillsRoot = yield* fs.realPath(skillsLink).pipe(
+    Effect.mapError(() => new PackageSkillSourceError({ message: `package skill package has no skills directory: ${packageName}` })),
+  );
+  if (!isContained(path, packageRoot, skillsRoot)) return yield* new PackageSkillSourceError({ message: `package skills path resolves outside package root: ${packageName}/${skillsPath}` });
+  const skillsInfo = yield* fs.stat(skillsRoot);
+  if (skillsInfo.type !== "Directory") return yield* new PackageSkillSourceError({ message: `package skills path is not a directory: ${packageName}/${skillsPath}` });
+  const names = (yield* fs.readDirectory(skillsRoot).pipe(
+    Effect.mapError(() => new PackageSkillSourceError({
+      message: `package skill package has no readable skills directory: ${packageName}`,
+    })),
+  )).filter(isSkillName).sort();
+  return {
+    package: packageName,
+    version: metadata.version,
+    packageLink,
+    skillsRoot,
+    names,
+  } satisfies InstalledPackageSkills;
+});
+
+const inspectPackageSkill = Effect.fn("inspectInstalledPackageSkill")(function* (
+  installed: InstalledPackageSkills,
+  name: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  if (!isSkillName(name)) {
+    return yield* new PackageSkillSourceError({ message: `invalid package skill name: ${name}` });
+  }
+  const selector = `${installed.package}#${name}`;
+  const linkPath = path.join(installed.packageLink, "skills", name);
+  if ((yield* observeSymbolicLink(linkPath)).kind === "symlink") {
+    return yield* new PackageSkillSourceError({ message: `package skill contains a symlink: ${selector}` });
+  }
+  const skillRoot = yield* fs.realPath(linkPath).pipe(
+    Effect.mapError(() => new PackageSkillSourceError({ message: `package skill does not exist: ${selector}` })),
+  );
+  if (!isContained(path, installed.skillsRoot, skillRoot) ||
+    (yield* fs.stat(skillRoot)).type !== "Directory") {
+    return yield* new PackageSkillSourceError({ message: `package skill is not a contained directory: ${selector}` });
+  }
+  yield* rejectNestedSymlinks(skillRoot);
+  const document = yield* fs.readFileString(path.join(skillRoot, "SKILL.md")).pipe(
+    Effect.mapError(() => new PackageSkillSourceError({ message: `package skill is missing SKILL.md: ${selector}` })),
+  );
+  if (skillName(document) !== name) {
+    return yield* new PackageSkillSourceError({
+      message: `package skill SKILL.md name must match directory: ${selector}`,
+    });
+  }
+  const description = skillDescription(document);
+  if (description === undefined) {
+    return yield* new PackageSkillSourceError({
+      message: `package skill SKILL.md must declare a description: ${selector}`,
+    });
+  }
+  return {
+    selector,
+    name,
+    description,
+    package: installed.package,
+    version: installed.version,
+    path: skillRoot,
+    linkPath,
+  } satisfies DiscoveredPackageSkill;
+});
+
+/** Read direct project dependencies only; malformed packages are returned as diagnostics, never executed. */
+export const discoverPackageSkills = Effect.fn("discoverInstalledPackageSkills")(function* (projectDir: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const candidates: Array<DiscoveredPackageSkill> = [];
+  const diagnostics: Array<PackageSkillDiagnostic> = [];
+  if (!(yield* fs.exists(path.join(projectDir, "package.json")))) {
+    return { candidates, diagnostics };
+  }
+  for (const packageName of yield* readDirectDependencyNames(projectDir)) {
+    if (!isTypeScriptPackageName(packageName)) {
+      diagnostics.push({ package: packageName, message: `invalid direct dependency package name: ${packageName}` });
+      continue;
+    }
+    const skillsLink = path.join(projectDir, "node_modules", ...packageName.split("/"), "skills");
+    if (!(yield* fs.exists(skillsLink))) continue;
+    const installed = yield* Effect.result(loadInstalledPackageSkills(projectDir, packageName));
+    if (Result.isFailure(installed)) {
+      diagnostics.push({ package: packageName, message: installed.failure.message });
+      continue;
+    }
+    for (const name of installed.success.names) {
+      const inspected = yield* Effect.result(inspectPackageSkill(installed.success, name));
+      if (Result.isSuccess(inspected)) candidates.push(inspected.success);
+      else diagnostics.push({ package: packageName, message: inspected.failure.message });
+    }
+  }
+  return { candidates: candidates.sort((left, right) => left.selector.localeCompare(right.selector)), diagnostics };
+});
+
+/** Resolve one explicitly selected package skill. Unlike browsing, every malformed or missing part is an error. */
+export const resolvePackageSkillSelector = Effect.fn("resolvePackageSkillSelector")(function* (projectDir: string, selector: string) {
+  const parsed = parseSkillSelector(selector);
+  if (parsed?.type !== "package") return yield* new PackageSkillSourceError({ message: `invalid package skill selector: ${selector}` });
+  const directDependencies = yield* readDirectDependencyNames(projectDir);
+  if (!directDependencies.includes(parsed.package)) return yield* new PackageSkillSourceError({ message: `package skill package is not a direct dependency: ${parsed.package}` });
+  return yield* inspectPackageSkill(
+    yield* loadInstalledPackageSkills(projectDir, parsed.package),
+    parsed.skill,
+  );
+});

package/src/project-state.ts

@@ -2,6 +2,21 @@ import { Schema } from "effect";
 
 import { DigestSchema } from "./path-digest.ts";
 
+export const CatalogProvenanceSchema = Schema.Union([
+  Schema.Struct({
+    source: Schema.String,
+    repository: Schema.String,
+    resolved: Schema.String,
+  }),
+  Schema.Struct({
+    package: Schema.String,
+    version: Schema.String,
+    skill: Schema.String,
+    digest: DigestSchema,
+  }),
+]);
+export type CatalogProvenance = typeof CatalogProvenanceSchema.Type;
+
 export const ManagedSkillOutputSchema = Schema.Struct({
   resourceId: Schema.String,
   path: Schema.String,
@@ -10,16 +25,26 @@ export const ManagedSkillOutputSchema = Schema.Struct({
   mode: Schema.Literals(["copy", "symlink"]),
   kind: Schema.Literals(["directory", "symlink"]),
   digest: DigestSchema,
-  catalog: Schema.optional(
-    Schema.Struct({
-      source: Schema.String,
-      repository: Schema.String,
-      resolved: Schema.String,
-    }),
-  ),
+  catalog: Schema.optional(CatalogProvenanceSchema),
 });
 export type ManagedSkillOutput = typeof ManagedSkillOutputSchema.Type;
 
+export const ManagedInstructionOutputSchema = Schema.Struct({
+  resourceId: Schema.Literal("setup:claude-instructions"),
+  path: Schema.String,
+  sourcePath: Schema.String,
+  mode: Schema.Literal("symlink"),
+  kind: Schema.Literal("symlink"),
+  digest: DigestSchema,
+});
+export type ManagedInstructionOutput = typeof ManagedInstructionOutputSchema.Type;
+
+export const ManagedOutputSchema = Schema.Union([
+  ManagedSkillOutputSchema,
+  ManagedInstructionOutputSchema,
+]);
+export type ManagedOutput = typeof ManagedOutputSchema.Type;
+
 export const EffectTsgoLockSchema = Schema.Struct({
   effectTsgoVersion: Schema.String,
   typescriptPackage: Schema.String,
@@ -46,7 +71,7 @@ export const DevKitLockSchema = Schema.Struct({
       effectTsgo: Schema.optional(EffectTsgoLockSchema),
     }),
   ),
-  outputs: Schema.Array(ManagedSkillOutputSchema),
+  outputs: Schema.Array(ManagedOutputSchema),
 });
 export type DevKitLock = typeof DevKitLockSchema.Type;