@kontourai/flow-agents 1.0.1 → 1.2.0

package/src/cli.ts

@@ -2,7 +2,7 @@
 import { basename } from "node:path";
 import { main as effectiveBacklogSettings } from "./cli/effective-backlog-settings.js";
 import { main as consoleLearningProjection } from "./cli/console-learning-projection.js";
-import { main as flowKit } from "./cli/flow-kit.js";
+import { main as kit } from "./cli/kit.js";
 import { main as fixtureRetirementAudit } from "./cli/fixture-retirement-audit.js";
 import { main as init } from "./cli/init.js";
 import { main as promoteWorkflowArtifact } from "./cli/promote-workflow-artifact.js";
@@ -28,7 +28,7 @@ const availableCommands = new Map<string, (argv: string[]) => number | Promise<n
   ["effective-backlog-settings", effectiveBacklogSettings],
   ["filter-installed-packs", filterInstalledPacks],
   ["fixture-retirement-audit", fixtureRetirementAudit],
-  ["flow-kit", flowKit],
+  ["kit", kit],
   ["init", init],
   ["promote-workflow-artifact", promoteWorkflowArtifact],
   ["publish-change", publishChange],
@@ -51,7 +51,7 @@ const aliases = new Map<string, string>([
   ["flow-agents-effective-backlog-settings", "effective-backlog-settings"],
   ["flow-agents-filter-installed-packs", "filter-installed-packs"],
   ["flow-agents-fixture-retirement-audit", "fixture-retirement-audit"],
-  ["flow-agents-flow-kit", "flow-kit"],
+  ["flow-agents-kit", "kit"],
   ["flow-agents-promote-workflow-artifact", "promote-workflow-artifact"],
   ["flow-agents-publish-change", "publish-change"],
   ["flow-agents-pull-work-provider", "pull-work-provider"],

package/src/flow-kit/validate.ts

@@ -2,7 +2,8 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { readJson } from "../lib/fs.js";
 
-const ASSET_CLASSES = ["flows", "skills", "docs", "adapters", "evals", "assets"] as const;
+// Extension-only asset classes: validated by Flow Agents. Flows are validated by @kontourai/flow.
+const EXTENSION_ASSET_CLASSES = ["skills", "docs", "adapters", "evals", "assets"] as const;
 
 // Core container fields owned by kontourai/flow (flow-kit-container.schema.json).
 // agent-extension fields are skills, docs, adapters, evals, assets.
@@ -33,43 +34,52 @@ export interface KitTargetsResult {
   third_party_extensions: string[];
 }
 
+// Lazy-loaded cache for validateKitContainer from @kontourai/flow.
+// list/status/activate are runtime ops that never call validation and must NOT load
+// @kontourai/flow (it is unresolvable in a standalone installed bundle).
+// Only validate/inspect (authoring ops) trigger this load.
+type ValidateKitContainerFn = (kitDir: string, manifest: Record<string, unknown>) => { valid: boolean; diagnostics: { severity: string; path: string; message: string }[] };
+let _validateKitContainerCache: ValidateKitContainerFn | null = null;
+
+async function loadValidateKitContainer(): Promise<ValidateKitContainerFn> {
+  if (_validateKitContainerCache) return _validateKitContainerCache;
+  let mod: { validateKitContainer?: unknown };
+  try {
+    mod = await import("@kontourai/flow") as { validateKitContainer?: unknown };
+  } catch (err) {
+    throw new Error(
+      "container validation requires @kontourai/flow; run from an npm-installed flow-agents workspace " +
+      `or use 'flow kit validate' (original error: ${(err as Error).message})`
+    );
+  }
+  if (typeof mod.validateKitContainer !== "function") {
+    throw new Error("@kontourai/flow did not export validateKitContainer");
+  }
+  _validateKitContainerCache = mod.validateKitContainer as ValidateKitContainerFn;
+  return _validateKitContainerCache;
+}
+
 /**
- * Validates that the manifest satisfies the core Flow Kit container contract
- * (as specified by kontourai/flow PR #67) with all agent-extension fields stripped.
- * Returns a list of violation messages (empty = valid).
+ * Delegates core Flow Kit container validation to @kontourai/flow's validateKitContainer.
+ * The container contract lives once, in Flow. Returns a list of violation messages (empty = valid).
  *
  * The degradation invariant: every Flow Agents Kit MUST remain a valid core
  * Flow Kit container when agent-extension fields are ignored.
+ *
+ * Loads @kontourai/flow lazily (on first call) so that runtime ops (list/status/activate)
+ * that never invoke validation can run in standalone installed bundles where
+ * @kontourai/flow is not present.
+ *
+ * @param kitDir  Real kit directory path for file-existence checks on flows[].path entries.
+ *                Pass the actual kit directory when available; pass "" for structural-only checks.
  */
-export function validateCoreContainer(manifest: Record<string, unknown>, label: string): string[] {
-  const errors: string[] = [];
-  if (manifest.schema_version !== "1.0") {
-    errors.push(`${label}: .schema_version must be "1.0"`);
-  }
-  if (typeof manifest.id !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(manifest.id)) {
-    errors.push(`${label}: .id must be a stable kebab-case string`);
-  }
-  if (typeof manifest.name !== "string" || !manifest.name.trim()) {
-    errors.push(`${label}: .name must be a non-empty string`);
-  }
-  if (!Array.isArray(manifest.flows) || manifest.flows.length === 0) {
-    errors.push(`${label}: .flows must be a non-empty list`);
-  } else {
-    manifest.flows.forEach((entry: unknown, index: number) => {
-      if (typeof entry !== "object" || entry === null) {
-        errors.push(`${label}: flows[${index}] must be an object`);
-        return;
-      }
-      const flow = entry as Record<string, unknown>;
-      if (typeof flow.id !== "string" || !flow.id) {
-        errors.push(`${label}: flows[${index}].id must be a string`);
-      }
-      if (typeof flow.path !== "string" || !flow.path) {
-        errors.push(`${label}: flows[${index}].path must be a string`);
-      }
-    });
-  }
-  return errors;
+async function delegateCoreContainerValidation(kitDir: string, manifest: Record<string, unknown>): Promise<string[]> {
+  const validateKitContainer = await loadValidateKitContainer();
+  const result = validateKitContainer(kitDir, manifest);
+  if (result.valid) return [];
+  return result.diagnostics
+    .filter((d) => d.severity === "error")
+    .map((d) => `${d.path}: ${d.message}`);
 }
 
 /**
@@ -83,12 +93,17 @@ export function validateCoreContainer(manifest: Record<string, unknown>, label:
  *  - targets.flow: always present when K0 (any Flow consumer can evaluate gates).
  *  - targets.flow-agents: present when K1 (agent extension assets activate in >=1 harness).
  *  - third-party: any top-level keys that are not core fields and not Flow Agents extension classes.
+ *
+ * @param manifest  The kit.json manifest object.
+ * @param kitDir    Kit directory for flow file-existence checks. Defaults to "" (structural-only).
+ *                  Pass the real kit directory from `inspect` to get authoritative K0 validation.
  */
-export function deriveKitTargets(manifest: Record<string, unknown>): KitTargetsResult {
+export async function deriveKitTargets(manifest: Record<string, unknown>, kitDir = ""): Promise<KitTargetsResult> {
   const kitId = typeof manifest.id === "string" ? manifest.id : "<unknown>";
   const kitName = typeof manifest.name === "string" ? manifest.name : "<unknown>";
 
-  const coreErrors = validateCoreContainer(manifest, "kit.json");
+  // Delegate core container validation to @kontourai/flow.
+  const coreErrors = await delegateCoreContainerValidation(kitDir, manifest);
   const k0 = coreErrors.length === 0;
 
   const hasAgentExtension = AGENT_EXTENSION_CLASSES.size > 0 &&
@@ -119,7 +134,7 @@ export function deriveKitTargets(manifest: Record<string, unknown>): KitTargetsR
   };
 }
 
-export function validateKitRepository(kitDir: string): string[] {
+export async function validateKitRepository(kitDir: string): Promise<string[]> {
   const errors: string[] = [];
   const manifestPath = path.join(kitDir, "kit.json");
   let manifest: Record<string, unknown>;
@@ -129,25 +144,17 @@ export function validateKitRepository(kitDir: string): string[] {
     errors.push(`${manifestPath}: invalid JSON: ${(error as Error).message}`);
     return errors;
   }
-  if (manifest.schema_version !== "1.0") errors.push(`${manifestPath}: .schema_version must be "1.0"`);
-  if (typeof manifest.id !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(manifest.id)) {
-    errors.push(`${manifestPath}: .id must be a stable kebab-case string`);
-  }
-  if (typeof manifest.name !== "string" || !manifest.name.trim()) errors.push(`${manifestPath}: .name must be a non-empty string`);
 
-  // Degradation invariant: every Flow Agents Kit must remain a valid core Flow Kit container
-  // when agent-extension fields are stripped. Strip extensions and re-validate core contract.
-  const coreManifest: Record<string, unknown> = {};
-  for (const key of Object.keys(manifest)) {
-    if (CORE_CONTAINER_FIELDS.has(key)) coreManifest[key] = manifest[key];
-  }
-  const coreErrors = validateCoreContainer(coreManifest, manifestPath);
-  for (const err of coreErrors) {
-    // Deduplicate: only add if not already covered by top-level checks above.
-    if (!errors.some((existing) => existing === err)) errors.push(err);
-  }
+  // Delegate core container validation (schema_version, id, name, flows including file
+  // existence) to @kontourai/flow — the container contract lives once, in Flow.
+  // This enforces the degradation invariant: a Flow Agents Kit must remain a valid
+  // core Flow Kit container when extension fields are stripped.
+  const coreErrors = await delegateCoreContainerValidation(kitDir, manifest);
+  for (const err of coreErrors) errors.push(err);
 
-  for (const section of ASSET_CLASSES) {
+  // Flow Agents extension validation: skills, docs, adapters, evals, assets.
+  // Flows are validated above by @kontourai/flow; only extension classes are checked here.
+  for (const section of EXTENSION_ASSET_CLASSES) {
     const entries = manifest[section];
     if (entries === undefined) continue;
     if (!Array.isArray(entries)) {
@@ -182,16 +189,15 @@ export function validateKitRepository(kitDir: string): string[] {
         return;
       }
       if (!fs.existsSync(resolved)) {
-        const noun = section === "flows" ? "Flow Definition" : "asset";
-        errors.push(`${manifestPath}: ${section}[${index}].path points at missing ${noun}: ${rel}`);
+        errors.push(`${manifestPath}: ${section}[${index}].path points at missing asset: ${rel}`);
       }
     });
   }
   return errors;
 }
 
-export function assertKitRepository(kitDir: string): Record<string, unknown> {
-  const errors = validateKitRepository(kitDir);
+export async function assertKitRepository(kitDir: string): Promise<Record<string, unknown>> {
+  const errors = await validateKitRepository(kitDir);
   if (errors.length) {
     const error = new Error("Flow Kit repository validation failed") as Error & { diagnostics?: string[] };
     error.diagnostics = errors;

package/src/runtime-adapters.ts

@@ -126,31 +126,47 @@ function safeSegment(value: string): string {
   return value.replace(/[^A-Za-z0-9_.-]+/g, "-").replace(/^[.-]+|[.-]+$/g, "") || "asset";
 }
 
+// Asset classes that are directly activated (copied to the runtime directory) by both adapters.
+// flows: gate definitions read by the adapter's flow-routing layer.
+// skills: agent guidance markdown copied to skills/<kit-id>/ for agent discovery.
+// docs: documentation markdown copied to docs/<kit-id>/ for agent reference.
+const ACTIVATED_ASSET_CLASSES = new Set(["flows", "skills", "docs"]);
+
 export function activateCodexLocal(sourceRoot: string, dest: string): Record<string, unknown> {
   const inventory = readKitInventory(sourceRoot, dest);
   const runtimeDir = path.join(dest, ".flow-agents", "runtime", "codex");
   const generated: Record<string, string>[] = [];
   const skipped: Record<string, string | null>[] = [];
   for (const asset of inventory.assets) {
-    if (asset.asset_class !== "flows") {
-      skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: asset.asset_id, reason: "asset class is diagnostic-only for codex-local" });
-      continue;
-    }
-    if (!asset.asset_id) {
-      skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: null, reason: "flow asset is missing an id" });
-      continue;
+    if (asset.asset_class === "flows") {
+      if (!asset.asset_id) {
+        skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: null, reason: "flow asset is missing an id" });
+        continue;
+      }
+      const output = path.join(runtimeDir, "flows", safeSegment(asset.kit_id), `${safeSegment(asset.asset_id)}.flow.json`);
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.copyFileSync(asset.source_path, output);
+      generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id, source_path: asset.source_path.split(path.sep).join("/") });
+    } else if (asset.asset_class === "skills" || asset.asset_class === "docs") {
+      // Copy skills and docs to runtime/<adapter>/<class>/<kit-id>/<filename> so the
+      // agent's guidance index (AGENTS.md) can reference them and they are co-located
+      // with flow definitions for the same kit.
+      const filename = path.basename(asset.source_path);
+      const output = path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), filename);
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.copyFileSync(asset.source_path, output);
+      generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id ?? "", source_path: asset.source_path.split(path.sep).join("/") });
+    } else {
+      skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: asset.asset_id, reason: "asset class is not activated by codex-local" });
     }
-    const output = path.join(runtimeDir, "flows", safeSegment(asset.kit_id), `${safeSegment(asset.asset_id)}.flow.json`);
-    fs.mkdirSync(path.dirname(output), { recursive: true });
-    fs.copyFileSync(asset.source_path, output);
-    generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id, source_path: asset.source_path.split(path.sep).join("/") });
   }
   fs.mkdirSync(runtimeDir, { recursive: true });
-  const manifest = { schema_version: "1.0", adapter: "codex-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
+  const supportedClasses = Array.from(ACTIVATED_ASSET_CLASSES);
+  const manifest = { schema_version: "1.0", adapter: "codex-local", supported_asset_classes: supportedClasses, generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
   const manifestPath = path.join(runtimeDir, "activation.json");
   writeJson(manifestPath, manifest);
   generated.push({ asset_class: "activation-manifest", path: relPath(dest, manifestPath), kit_id: "runtime", asset_id: "codex-local.activation", source_path: manifestPath.split(path.sep).join("/") });
-  return { selected_adapter: "codex-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
+  return { selected_adapter: "codex-local", supported_asset_classes: supportedClasses, generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
 }
 
 // Decision Q3 (Issue #32): Option (a) — new adapter id "strands-local" rather than
@@ -163,27 +179,39 @@ export function activateStrandsLocal(sourceRoot: string, dest: string): Record<s
   const inventory = readKitInventory(sourceRoot, dest);
   // Runtime flows land at .flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json
   // so the Strands steering context can glob for *.flow.json under this path.
+  // Runtime skills land at .flow-agents/runtime/strands/skills/<kit-id>/<filename> and
+  // docs at .flow-agents/runtime/strands/docs/<kit-id>/<filename> for system-prompt injection.
   const runtimeDir = path.join(dest, ".flow-agents", "runtime", "strands");
   const generated: Record<string, string>[] = [];
   const skipped: Record<string, string | null>[] = [];
   for (const asset of inventory.assets) {
-    if (asset.asset_class !== "flows") {
-      skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: asset.asset_id, reason: "asset class is diagnostic-only for strands-local" });
-      continue;
-    }
-    if (!asset.asset_id) {
-      skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: null, reason: "flow asset is missing an id" });
-      continue;
+    if (asset.asset_class === "flows") {
+      if (!asset.asset_id) {
+        skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: null, reason: "flow asset is missing an id" });
+        continue;
+      }
+      const output = path.join(runtimeDir, "flows", safeSegment(asset.kit_id), `${safeSegment(asset.asset_id)}.flow.json`);
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.copyFileSync(asset.source_path, output);
+      generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id, source_path: asset.source_path.split(path.sep).join("/") });
+    } else if (asset.asset_class === "skills" || asset.asset_class === "docs") {
+      // Mirror the codex-local layout: strands/<class>/<kit-id>/<filename>.
+      // The Strands system-prompt injection layer can glob for all *.md files under
+      // .flow-agents/runtime/strands/skills/ to include agent guidance in the context.
+      const filename = path.basename(asset.source_path);
+      const output = path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), filename);
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.copyFileSync(asset.source_path, output);
+      generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id ?? "", source_path: asset.source_path.split(path.sep).join("/") });
+    } else {
+      skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: asset.asset_id, reason: "asset class is not activated by strands-local" });
     }
-    const output = path.join(runtimeDir, "flows", safeSegment(asset.kit_id), `${safeSegment(asset.asset_id)}.flow.json`);
-    fs.mkdirSync(path.dirname(output), { recursive: true });
-    fs.copyFileSync(asset.source_path, output);
-    generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id, source_path: asset.source_path.split(path.sep).join("/") });
   }
   fs.mkdirSync(runtimeDir, { recursive: true });
-  const manifest = { schema_version: "1.0", adapter: "strands-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
+  const supportedClasses = Array.from(ACTIVATED_ASSET_CLASSES);
+  const manifest = { schema_version: "1.0", adapter: "strands-local", supported_asset_classes: supportedClasses, generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
   const manifestPath = path.join(runtimeDir, "activation.json");
   writeJson(manifestPath, manifest);
   generated.push({ asset_class: "activation-manifest", path: relPath(dest, manifestPath), kit_id: "runtime", asset_id: "strands-local.activation", source_path: manifestPath.split(path.sep).join("/") });
-  return { selected_adapter: "strands-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
+  return { selected_adapter: "strands-local", supported_asset_classes: supportedClasses, generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
 }

package/src/tools/build-universal-bundles.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { loadJson, readText, root, walkFiles, writeText } from "./common.js";
 
@@ -11,6 +12,57 @@ const textExtensions = new Set([".css", ".html", ".js", ".json", ".md", ".sh", "
 const dropDiagnostics: string[] = [];
 const printDiagnostics = !["0", "false", "no"].includes(String(process.env.FLOW_AGENTS_EXPORT_DIAGNOSTICS ?? "1").toLowerCase());
 
+/**
+ * Collect all skill source paths across skills/ and kit-owned skills.
+ * Returns an array of {name, src} pairs where name is the install name
+ * (same as the directory name) and src is the absolute SKILL.md path.
+ * Kit-owned skills are discovered by reading kit.json `skills` arrays;
+ * each entry's `path` is resolved relative to the kit directory.
+ */
+function collectAllSkills(): Array<{ name: string; src: string }> {
+  const results: Array<{ name: string; src: string }> = [];
+  const seen = new Set<string>();
+
+  // 1. Top-level skills/ directory (tools pending reclassification).
+  const skillsDir = path.join(root, "skills");
+  if (fs.existsSync(skillsDir)) {
+    for (const skill of fs.readdirSync(skillsDir).sort()) {
+      const skillPath = path.join(skillsDir, skill, "SKILL.md");
+      if (fs.existsSync(skillPath) && !seen.has(skill)) {
+        seen.add(skill);
+        results.push({ name: skill, src: skillPath });
+      }
+    }
+  }
+
+  // 2. Kit-owned skills declared in kits/<kit>/kit.json `skills` arrays.
+  const kitsDir = path.join(root, "kits");
+  if (fs.existsSync(kitsDir)) {
+    for (const kitName of fs.readdirSync(kitsDir).sort()) {
+      const kitJson = path.join(kitsDir, kitName, "kit.json");
+      if (!fs.existsSync(kitJson)) continue;
+      let kitManifest: Record<string, unknown>;
+      try { kitManifest = loadJson<Record<string, unknown>>(kitJson); } catch { continue; }
+      const skills = Array.isArray(kitManifest["skills"]) ? kitManifest["skills"] as unknown[] : [];
+      for (const entry of skills) {
+        if (typeof entry !== "object" || entry === null) continue;
+        const skillEntry = entry as Record<string, unknown>;
+        const relPath = typeof skillEntry["path"] === "string" ? skillEntry["path"] : null;
+        if (!relPath) continue;
+        // Derive install name from the directory containing SKILL.md (one level up).
+        const absPath = path.resolve(path.join(kitsDir, kitName), relPath);
+        const skillName = path.basename(path.dirname(absPath));
+        if (fs.existsSync(absPath) && !seen.has(skillName)) {
+          seen.add(skillName);
+          results.push({ name: skillName, src: absPath });
+        }
+      }
+    }
+  }
+
+  return results.sort((a, b) => a.name.localeCompare(b.name));
+}
+
 function resetDir(dir: string): void {
   fs.rmSync(dir, { recursive: true, force: true });
   fs.mkdirSync(dir, { recursive: true });
@@ -301,9 +353,8 @@ function buildClaudeCode(agents: Agent[]): void {
   copySharedContent(bundle, "claude-code", "<bundle-root>");
   writeText(path.join(bundle, manifest.claude_code.task_dir, ".gitkeep"), "");
   for (const spec of agents) writeText(path.join(bundle, ".claude/agents", `${spec.name}.md`), exportClaudeAgent(spec));
-  for (const skill of fs.readdirSync(path.join(root, "skills"))) {
-    const skillPath = path.join(root, "skills", skill, "SKILL.md");
-    if (fs.existsSync(skillPath)) writeText(path.join(bundle, ".claude/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "claude-code", "<bundle-root>"));
+  for (const { name, src } of collectAllSkills()) {
+    writeText(path.join(bundle, ".claude/skills", name, "SKILL.md"), sanitizeText(readText(src), "claude-code", "<bundle-root>"));
   }
   writeText(path.join(bundle, ".claude/settings.json"), exportClaudeSettings());
   writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Claude Code", agents, manifest.claude_code.task_dir));
@@ -323,9 +374,8 @@ function buildCodex(agents: Agent[]): void {
   for (const [profileName, profile] of Object.entries(manifest.codex.profiles ?? {})) writeText(path.join(bundle, ".codex", `${profileName}.config.toml`), exportCodexProfileConfig(profile as Record<string, unknown>, settings));
   writeText(path.join(bundle, ".codex/hooks.json"), exportCodexHooks());
   for (const spec of targetAgents) writeText(path.join(bundle, ".codex/agents", `${spec.name}.toml`), exportCodexAgent(spec));
-  for (const skill of fs.readdirSync(path.join(root, "skills"))) {
-    const skillPath = path.join(root, "skills", skill, "SKILL.md");
-    if (fs.existsSync(skillPath)) writeText(path.join(bundle, ".codex/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "codex", "<bundle-root>"));
+  for (const { name, src } of collectAllSkills()) {
+    writeText(path.join(bundle, ".codex/skills", name, "SKILL.md"), sanitizeText(readText(src), "codex", "<bundle-root>"));
   }
   writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Codex", targetAgents, manifest.codex.task_dir));
   writeText(path.join(bundle, "README.md"), exportTargetReadme("Codex", "bash install.sh /path/to/workspace"));
@@ -489,9 +539,8 @@ function buildOpencode(agents: Agent[]): void {
   for (const spec of agents) {
     writeText(path.join(bundle, ".opencode/agents", `${spec.name}.md`), exportOpencodeAgent(spec));
   }
-  for (const skill of fs.readdirSync(path.join(root, "skills"))) {
-    const skillPath = path.join(root, "skills", skill, "SKILL.md");
-    if (fs.existsSync(skillPath)) writeText(path.join(bundle, ".opencode/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "opencode", "<bundle-root>"));
+  for (const { name, src } of collectAllSkills()) {
+    writeText(path.join(bundle, ".opencode/skills", name, "SKILL.md"), sanitizeText(readText(src), "opencode", "<bundle-root>"));
   }
   writeText(path.join(bundle, ".opencode/plugins/flow-agents.js"), exportOpencodePlugin());
   writeText(path.join(bundle, "opencode.json"), exportOpencodeConfig());
@@ -601,9 +650,8 @@ function buildPi(agents: Agent[]): void {
   writeText(path.join(bundle, manifest.pi.task_dir, ".gitkeep"), "");
   // pi has no named-subagent registry; agents are left canonical/unexported.
   // Skills are exported to .pi/skills/ (direct .md files supported in that dir).
-  for (const skill of fs.readdirSync(path.join(root, "skills"))) {
-    const skillPath = path.join(root, "skills", skill, "SKILL.md");
-    if (fs.existsSync(skillPath)) writeText(path.join(bundle, ".pi/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "pi", "<bundle-root>"));
+  for (const { name, src } of collectAllSkills()) {
+    writeText(path.join(bundle, ".pi/skills", name, "SKILL.md"), sanitizeText(readText(src), "pi", "<bundle-root>"));
   }
   writeText(path.join(bundle, ".pi/extensions/flow-agents.ts"), exportPiExtension());
   writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("pi", agents, manifest.pi.task_dir));
@@ -616,7 +664,7 @@ function buildCatalog(agents: Agent[]): Record<string, unknown> {
   return {
     source_root: ".",
     agents: agents.slice().sort((a, b) => a.name.localeCompare(b.name)).map((spec) => spec.name),
-    skills: fs.readdirSync(path.join(root, "skills")).filter((name) => fs.existsSync(path.join(root, "skills", name, "SKILL.md"))).sort(),
+    skills: collectAllSkills().map(({ name }) => name),
     powers: fs.readdirSync(path.join(root, "powers")).filter((name) => fs.existsSync(path.join(root, "powers", name, "mcp.json"))).sort(),
     packs: packs.packs ?? [],
     kits: fs.existsSync(kitsCatalog) ? loadJson<Record<string, unknown>>(kitsCatalog).kits ?? [] : [],
@@ -646,4 +694,9 @@ export function main(): number {
   }
   return 0;
 }
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

package/src/tools/generate-context-map.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { exists, loadJson, markdownTable, oneLine, readText, rel, root, writeText } from "./common.js";
 
@@ -73,15 +74,45 @@ function repoShape(manifest: Record<string, unknown>): string[][] {
   return rows;
 }
 
+/** Collect all skill {name, absPath} pairs from skills/ and kit-owned skills. */
+function allSkillPaths(): Array<{ name: string; absPath: string }> {
+  const results: Array<{ name: string; absPath: string }> = [];
+  const seen = new Set<string>();
+  const skillsDir = path.join(root, "skills");
+  if (exists(skillsDir)) {
+    for (const name of fs.readdirSync(skillsDir).sort()) {
+      const absPath = path.join(skillsDir, name, "SKILL.md");
+      if (exists(absPath) && !seen.has(name)) { seen.add(name); results.push({ name, absPath }); }
+    }
+  }
+  const kitsDir = path.join(root, "kits");
+  if (exists(kitsDir)) {
+    for (const kitName of fs.readdirSync(kitsDir).sort()) {
+      const kitJson = path.join(kitsDir, kitName, "kit.json");
+      if (!exists(kitJson)) continue;
+      let kitManifest: Record<string, unknown>;
+      try { kitManifest = loadJson<Record<string, unknown>>(kitJson); } catch { continue; }
+      const skills = Array.isArray(kitManifest["skills"]) ? kitManifest["skills"] as unknown[] : [];
+      for (const entry of skills) {
+        if (typeof entry !== "object" || entry === null) continue;
+        const skillEntry = entry as Record<string, unknown>;
+        const relPath = typeof skillEntry["path"] === "string" ? skillEntry["path"] : null;
+        if (!relPath) continue;
+        const absPath = path.resolve(path.join(kitsDir, kitName), relPath);
+        const skillName = path.basename(path.dirname(absPath));
+        if (exists(absPath) && !seen.has(skillName)) { seen.add(skillName); results.push({ name: skillName, absPath }); }
+      }
+    }
+  }
+  return results.sort((a, b) => a.name.localeCompare(b.name));
+}
+
 function listSkillRows(): [string[][], string[][]] {
   const workflowRows: string[][] = [];
   const supportRows: string[][] = [];
-  const skillsDir = path.join(root, "skills");
-  for (const name of fs.readdirSync(skillsDir).sort()) {
-    const skillPath = path.join(skillsDir, name, "SKILL.md");
-    if (!exists(skillPath)) continue;
-    const meta = frontmatter(readText(skillPath));
-    const row = [meta.name ?? name, rel(skillPath), oneLine(meta.description ?? "")];
+  for (const { name, absPath } of allSkillPaths()) {
+    const meta = frontmatter(readText(absPath));
+    const row = [meta.name ?? name, rel(absPath), oneLine(meta.description ?? "")];
     if (workflowSkills.has(row[0])) workflowRows.push(row);
     else supportRows.push(row);
   }
@@ -196,4 +227,9 @@ export function main(argv = process.argv.slice(2)): number {
   return 0;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

package/src/tools/validate-package.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import path from "node:path";
 
 export function main(argv = process.argv.slice(2)): number {
@@ -54,4 +55,9 @@ export function main(argv = process.argv.slice(2)): number {
   console.log(errors === 0 ? "Result: PASS" : `Result: FAIL (${errors} error(s))`);
   return errors === 0 ? 0 : 1;
 }
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

package/src/tools/validate-source-tree.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { loadJson, readText, rel, root, walkFiles } from "./common.js";
@@ -36,7 +37,7 @@ const publicScriptWrappers = new Map<string, { target: string; significantLines:
   ] }],
   ["scripts/filter-installed-packs.js", { target: "../build/src/tools/filter-installed-packs.js", significantLines: ['import("../build/src/tools/filter-installed-packs.js").then(({ main }) => process.exit(main(process.argv.slice(2))));'] }],
   ["scripts/generate-context-map.js", { target: "../build/src/tools/generate-context-map.js", significantLines: ['import("../build/src/tools/generate-context-map.js").then(({ main }) => process.exit(main(process.argv.slice(2))));'] }],
-  ["scripts/flow-kit.js", { target: "../build/src/cli/flow-kit.js", significantLines: ['import("../build/src/cli/flow-kit.js").then(({ main }) => process.exit(main()));'] }],
+  ["scripts/kit.js", { target: "../build/src/cli/kit.js", significantLines: ['import("../build/src/cli/kit.js").then(({ main }) => main().then((code) => process.exit(code)));'] }],
   ["scripts/pull-work-provider.js", { target: "../build/src/cli/pull-work-provider.js", significantLines: ['import("../build/src/cli/pull-work-provider.js").then(({ main }) => process.exit(main()));'] }],
   ["scripts/effective-backlog-settings.js", { target: "../build/src/cli/effective-backlog-settings.js", significantLines: ['import("../build/src/cli/effective-backlog-settings.js").then(({ main }) => process.exit(main()));'] }],
   ["scripts/publish-change-helper.js", { target: "../build/src/cli/publish-change-helper.js", significantLines: ['import("../build/src/cli/publish-change-helper.js").then(({ main }) => process.exit(main()));'] }],
@@ -300,6 +301,28 @@ function validateAgentPaths(reporter: Reporter, manifest: any): void {
   }
 }
 function validateLegacyRefs(reporter: Reporter): void {
+  // Collect all kit-owned asset relative paths so legacy-ref scanning can skip matches
+  // that are subpaths of kit-owned assets. E.g. legacyRefRe matches "skills/plan-work/SKILL.md"
+  // within "kits/builder/skills/plan-work/SKILL.md"; the kit declares and validates these.
+  const kitOwnedSubPaths = new Set<string>();
+  const kitsDir = path.join(root, "kits");
+  if (fs.existsSync(kitsDir)) {
+    for (const kitName of fs.readdirSync(kitsDir)) {
+      const kitJson = path.join(kitsDir, kitName, "kit.json");
+      if (!fs.existsSync(kitJson)) continue;
+      try {
+        const kitManifest = loadJson<Record<string, unknown>>(kitJson);
+        for (const section of ["skills", "docs", "adapters", "evals", "assets"]) {
+          const entries = Array.isArray(kitManifest[section]) ? kitManifest[section] as unknown[] : [];
+          for (const entry of entries) {
+            if (typeof entry !== "object" || entry === null) continue;
+            const relPath = (entry as Record<string, unknown>)["path"];
+            if (typeof relPath === "string" && relPath) kitOwnedSubPaths.add(relPath);
+          }
+        }
+      } catch { /* skip invalid kit.json */ }
+    }
+  }
   for (const file of walkFiles(path.join(root, "evals")).sort()) {
     if (!textRefExtensions.has(path.extname(file))) continue;
     const parts = path.relative(path.join(root, "evals"), file).split(path.sep);
@@ -309,6 +332,10 @@ function validateLegacyRefs(reporter: Reporter): void {
       const ref = match[0].replace(/[.,)'"\]]+$/, "");
       if (/[{}$]/.test(ref)) continue;
       if (ref.split(/[\\/]/).includes("node_modules")) continue;
+      // Skip refs that are declared kit-owned asset paths or their parent directories
+      // (e.g. "skills/plan-work/SKILL.md" or "skills/plan-work" matched inside
+      // "kits/builder/skills/plan-work/SKILL.md" in eval files).
+      if (kitOwnedSubPaths.has(ref) || [...kitOwnedSubPaths].some((p) => p.startsWith(ref + "/"))) continue;
       const candidates = [path.join(root, ref), ...(ref.startsWith("evals/") ? [] : [path.join(root, "evals", ref)])];
       if (!candidates.some(fs.existsSync)) reporter.fail(`${rel(file)}: references missing source path: ${ref}`);
     }
@@ -491,4 +518,9 @@ export function main(argv = process.argv.slice(2)): number {
   console.log("Source tree validation passed.");
   return 0;
 }
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

package/scripts/flow-kit.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import("../build/src/cli/flow-kit.js").then(({ main }) => process.exit(main()));