@cubis/foundry 0.3.67 → 0.3.68

package/mcp/src/tools/skillTools.test.ts

@@ -65,12 +65,14 @@ function createManifest(): VaultManifest {
         category: "frontend",
         path: reactFile,
         fileBytes: reactBytes,
+        description: "React performance and architecture guidance",
       },
       {
         id: "fastapi-expert",
         category: "backend",
         path: fastapiFile,
         fileBytes: fastapiBytes,
+        description: "FastAPI async backend patterns",
       },
     ],
     fullCatalogBytes,
@@ -117,6 +119,7 @@ function createRouteManifest(): RouteManifest {
           codex: { compatibilityAlias: "$workflow-mobile", workflowFile: "mobile.md" },
           copilot: { workflowFile: "mobile.md", promptFile: "workflow-mobile.prompt.md" },
           antigravity: { workflowFile: "mobile.md", commandFile: "mobile.toml" },
+          claude: { workflowFile: "mobile.md" },
         },
       },
       {
@@ -187,6 +190,23 @@ function createRouteManifest(): RouteManifest {
           antigravity: { agentFile: "mobile-developer.md" },
         },
       },
+      {
+        kind: "agent",
+        id: "test-engineer",
+        command: null,
+        displayName: "test-engineer",
+        description: "Expert in testing and regression strategy",
+        triggers: ["test", "qa", "regression", "playwright"],
+        primaryAgent: "test-engineer",
+        supportingAgents: [],
+        primarySkills: ["test-master", "playwright-expert"],
+        supportingSkills: ["webapp-testing"],
+        artifacts: {
+          codex: { compatibilityAlias: "$agent-test-engineer", agentFile: "test-engineer.md" },
+          copilot: { agentFile: "test-engineer.md" },
+          antigravity: { agentFile: "test-engineer.md" },
+        },
+      },
     ],
   };
 }
@@ -207,6 +227,7 @@ interface GeneratedSkillManifest {
     id: string;
     category: string;
     description?: string;
+    path?: string;
     fileBytes: number;
     metadata?: Record<string, string>;
   }>;
@@ -223,10 +244,13 @@ function loadGeneratedCatalog(): {
     categories: [...new Set(generated.skills.map((skill) => skill.category))].sort(),
     skills: generated.skills.map((skill) => ({
       id: skill.id,
+      canonicalId: skill.metadata?.alias_of ?? skill.metadata?.replaced_by,
       category: skill.category,
       description: skill.description,
       fileBytes: skill.fileBytes,
-      path: path.join(SKILLS_ROOT, skill.id, "SKILL.md"),
+      path: skill.path
+        ? path.resolve(REPO_ROOT, skill.path)
+        : path.join(SKILLS_ROOT, skill.id, "SKILL.md"),
     })),
     fullCatalogBytes: generated.skills.reduce(
       (sum, skill) => sum + skill.fileBytes,
@@ -424,6 +448,49 @@ describe("skill tools", () => {
     );
   });
 
+  it("prioritizes keyword and trigger matches ahead of description-only matches", async () => {
+    const apiFile = createSkillFile(
+      "api-designer",
+      "Contract design guidance",
+    );
+    const docsFile = createSkillFile(
+      "documentation-writer",
+      "Writes OpenAPI and Swagger documentation",
+    );
+    const apiBytes = statSync(apiFile).size;
+    const docsBytes = statSync(docsFile).size;
+    const manifest: VaultManifest = {
+      categories: ["api", "documentation"],
+      skills: [
+        {
+          id: "api-designer",
+          category: "api",
+          path: apiFile,
+          fileBytes: apiBytes,
+          description: "Contract design guidance",
+          keywords: ["openapi"],
+          triggers: ["swagger"],
+        },
+        {
+          id: "documentation-writer",
+          category: "documentation",
+          path: docsFile,
+          fileBytes: docsBytes,
+          description: "Writes OpenAPI and Swagger documentation",
+        },
+      ],
+      fullCatalogBytes: apiBytes + docsBytes,
+      fullCatalogEstimatedTokens: Math.ceil((apiBytes + docsBytes) / 4),
+    };
+
+    const result = payload(
+      await handleSkillSearch({ query: "swagger" }, manifest, 200, 4),
+    );
+
+    expect(result.count).toBe(2);
+    expect(result.results[0]).toMatchObject({ id: "api-designer" });
+  });
+
   it("resolves an explicit workflow command before skill discovery", async () => {
     const result = payload(
       await handleRouteResolve({ intent: "/mobile" }, createRouteManifest()),
@@ -435,6 +502,9 @@ describe("skill tools", () => {
       agent: "mobile-developer",
       matchedBy: "explicit-workflow-command",
     });
+    expect(result.artifacts).toMatchObject({
+      claude: { workflowFile: "mobile.md" },
+    });
   });
 
   it("resolves an explicit custom agent mention before skill discovery", async () => {
@@ -452,6 +522,33 @@ describe("skill tools", () => {
     });
   });
 
+  it("maps a legacy workflow command to the canonical workflow route", async () => {
+    const result = payload(
+      await handleRouteResolve({ intent: "/brainstorm" }, createRouteManifest()),
+    );
+    expect(result).toMatchObject({
+      resolved: true,
+      kind: "workflow",
+      id: "plan",
+      matchedBy: "legacy-workflow-alias",
+    });
+  });
+
+  it("maps a legacy agent mention to the canonical agent route", async () => {
+    const result = payload(
+      await handleRouteResolve(
+        { intent: "@qa-automation-engineer" },
+        createRouteManifest(),
+      ),
+    );
+    expect(result).toMatchObject({
+      resolved: true,
+      kind: "agent",
+      id: "test-engineer",
+      matchedBy: "legacy-agent-alias",
+    });
+  });
+
   it("resolves free-text trigger intent to a workflow route", async () => {
     const result = payload(
       await handleRouteResolve(
@@ -467,7 +564,7 @@ describe("skill tools", () => {
     expect(["trigger-match", "intent-match"]).toContain(result.matchedBy);
   });
 
-  it("routes skill authoring intent to create with skill-authoring as the primary skill hint", async () => {
+  it("routes skill creator intent to create with skill-creator as the primary skill hint", async () => {
     const result = payload(
       await handleRouteResolve(
         { intent: "create a new skill package for Copilot and Codex" },
@@ -478,12 +575,12 @@ describe("skill tools", () => {
       resolved: true,
       kind: "workflow",
       id: "create",
-      primarySkillHint: "skill-authoring",
-      matchedBy: "skill-authoring-intent",
+      primarySkillHint: "skill-creator",
+      matchedBy: "skill-creator-intent",
     });
   });
 
-  it("routes skill planning intent to plan with skill-authoring as the primary skill hint", async () => {
+  it("routes skill planning intent to plan with skill-creator as the primary skill hint", async () => {
     const result = payload(
       await handleRouteResolve(
         { intent: "plan a new skill and its sidecar references" },
@@ -494,12 +591,12 @@ describe("skill tools", () => {
       resolved: true,
       kind: "workflow",
       id: "plan",
-      primarySkillHint: "skill-authoring",
-      matchedBy: "skill-authoring-intent",
+      primarySkillHint: "skill-creator",
+      matchedBy: "skill-creator-intent",
     });
   });
 
-  it("routes skill review intent to review with skill-authoring as the primary skill hint", async () => {
+  it("routes skill review intent to review with skill-creator as the primary skill hint", async () => {
     const result = payload(
       await handleRouteResolve(
         { intent: "review this skill metadata and broken references" },
@@ -510,8 +607,8 @@ describe("skill tools", () => {
       resolved: true,
       kind: "workflow",
       id: "review",
-      primarySkillHint: "skill-authoring",
-      matchedBy: "skill-authoring-intent",
+      primarySkillHint: "skill-creator",
+      matchedBy: "skill-creator-intent",
     });
   });
 
@@ -627,6 +724,7 @@ describe("skill tools", () => {
         "  replaced_by: canonical-skill",
         "---",
         "# Skill",
+        "See [Guide](references/guide.md).",
       ].join("\n"),
       "utf8",
     );
@@ -767,7 +865,7 @@ describe("skill tools", () => {
     ).rejects.toThrow("appears to be a wrapper id");
   });
 
-  it("includes referenced markdown files in skill_get by default", async () => {
+  it("skips referenced markdown files in skill_get by default", async () => {
     const dir = mkdtempSync(path.join(os.tmpdir(), "mcp-skill-ref-default-"));
     const skillFile = path.join(dir, "SKILL.md");
     const referencesDir = path.join(dir, "references");
@@ -806,6 +904,54 @@ describe("skill tools", () => {
     };
 
     const result = await handleSkillGet({ id: "referenced-skill" }, manifest, 4);
+    expect(result.content[0].text).not.toContain("## Referenced Files");
+    expect(result.content[0].text).not.toContain("### references/guide.md");
+    expect(result.content[0].text).not.toContain("Referenced content");
+  });
+
+  it("includes referenced markdown files when includeReferences is true", async () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), "mcp-skill-ref-include-"));
+    const skillFile = path.join(dir, "SKILL.md");
+    const referencesDir = path.join(dir, "references");
+    mkdirSync(referencesDir, { recursive: true });
+    writeFileSync(
+      skillFile,
+      [
+        "---",
+        "name: referenced-skill-include-refs",
+        "description: skill with refs",
+        "---",
+        "# Skill",
+        "See [Guide](references/guide.md).",
+      ].join("\n"),
+      "utf8",
+    );
+    writeFileSync(
+      path.join(referencesDir, "guide.md"),
+      "# Guide\nReferenced content",
+      "utf8",
+    );
+
+    const skillBytes = statSync(skillFile).size;
+    const manifest: VaultManifest = {
+      categories: ["general"],
+      skills: [
+        {
+          id: "referenced-skill-include-refs",
+          category: "general",
+          path: skillFile,
+          fileBytes: skillBytes,
+        },
+      ],
+      fullCatalogBytes: skillBytes,
+      fullCatalogEstimatedTokens: Math.ceil(skillBytes / 4),
+    };
+
+    const result = await handleSkillGet(
+      { id: "referenced-skill-include-refs", includeReferences: true },
+      manifest,
+      4,
+    );
     expect(result.content[0].text).toContain("## Referenced Files");
     expect(result.content[0].text).toContain("### references/guide.md");
     expect(result.content[0].text).toContain("Referenced content");
@@ -854,7 +1000,7 @@ describe("skill tools", () => {
     expect(result.content[0].text).not.toContain("### references/guide.md");
   });
 
-  it("loads sibling markdown files when SKILL.md has no explicit links", async () => {
+  it("does not load sibling markdown files when SKILL.md has no explicit links", async () => {
     const dir = mkdtempSync(path.join(os.tmpdir(), "mcp-skill-ref-fallback-"));
     const skillFile = path.join(dir, "SKILL.md");
     writeFileSync(
@@ -890,9 +1036,9 @@ describe("skill tools", () => {
       manifest,
       4,
     );
-    expect(result.content[0].text).toContain("## Referenced Files");
-    expect(result.content[0].text).toContain("### overview.md");
-    expect(result.content[0].text).toContain("Sibling");
+    expect(result.content[0].text).not.toContain("## Referenced Files");
+    expect(result.content[0].text).not.toContain("### overview.md");
+    expect(result.content[0].text).not.toContain("Sibling");
   });
 
   it("throws when skill_get cannot find the requested skill", async () => {

package/mcp/src/tools/skillValidate.ts

@@ -70,9 +70,12 @@ export async function handleSkillValidate(
   }
 
   const frontmatter = await readSkillFrontmatter(skill.path);
-  const replacementId =
+  const frontmatterReplacementId =
     frontmatter.metadata.replaced_by || frontmatter.metadata.alias_of || null;
-  const isAlias = Boolean(replacementId || frontmatter.metadata.deprecated);
+  const replacementId = skill.canonicalId || frontmatterReplacementId || null;
+  const isAlias = Boolean(
+    skill.canonicalId || frontmatterReplacementId || frontmatter.metadata.deprecated,
+  );
   const availableReferences = await listReferencedMarkdownPaths(skill.path);
   const payload = {
     id,

package/mcp/src/vault/generatedManifest.ts

@@ -0,0 +1,77 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import type { SkillPointer } from "./types.js";
+import { logger } from "../utils/logger.js";
+
+interface GeneratedSkillManifestEntry {
+  id: string;
+  category: string;
+  description?: string;
+  keywords?: string[];
+  triggers?: string[];
+}
+
+interface GeneratedSkillManifest {
+  skills?: GeneratedSkillManifestEntry[];
+}
+
+function normalizeStringArray(values: unknown): string[] {
+  if (!Array.isArray(values)) return [];
+  return [...new Set(values.map((value) => String(value || "").trim()).filter(Boolean))];
+}
+
+export async function loadGeneratedSkillManifest(
+  mcpPackageRoot: string,
+): Promise<GeneratedSkillManifest | null> {
+  const filePath = path.resolve(mcpPackageRoot, "generated", "mcp-manifest.json");
+
+  try {
+    const raw = await readFile(filePath, "utf8");
+    const parsed = JSON.parse(raw) as GeneratedSkillManifest;
+    if (!Array.isArray(parsed.skills)) {
+      throw new Error("missing skills array");
+    }
+    return parsed;
+  } catch (error) {
+    logger.warn(
+      `Generated skill manifest unavailable at ${filePath}: ${String(error)}`,
+    );
+    return null;
+  }
+}
+
+export function mergeGeneratedSkillMetadata(
+  scannedSkills: SkillPointer[],
+  generatedManifest: GeneratedSkillManifest | null,
+): SkillPointer[] {
+  if (!generatedManifest?.skills?.length) {
+    return scannedSkills;
+  }
+
+  const generatedById = new Map(
+    generatedManifest.skills.map((entry) => [entry.id.toLowerCase(), entry]),
+  );
+  const missingIds = scannedSkills
+    .filter((skill) => !generatedById.has(skill.id.toLowerCase()))
+    .map((skill) => skill.id)
+    .sort((a, b) => a.localeCompare(b));
+
+  if (missingIds.length > 0) {
+    logger.warn(
+      `Generated skill manifest is missing ${missingIds.length} scanned skill(s): ${missingIds.slice(0, 8).join(", ")}${missingIds.length > 8 ? ", ..." : ""}. Run node scripts/generate-mcp-manifest.mjs to refresh the runtime index.`,
+    );
+  }
+
+  return scannedSkills.map((skill) => {
+    const generated = generatedById.get(skill.id.toLowerCase());
+    if (!generated) return skill;
+
+    return {
+      ...skill,
+      category: generated.category || skill.category,
+      description: generated.description || skill.description,
+      keywords: normalizeStringArray(generated.keywords),
+      triggers: normalizeStringArray(generated.triggers),
+    };
+  });
+}

package/mcp/src/vault/manifest.test.ts

@@ -192,7 +192,7 @@ describe("skill content IO", () => {
     expect(result.references).toEqual([]);
   });
 
-  it("falls back to sibling markdown files when SKILL.md has no links", async () => {
+  it("does not load sibling markdown files when SKILL.md has no explicit links", async () => {
     const dir = createTempDir("mcp-refs-fallback-");
     const file = path.join(dir, "SKILL.md");
     const siblingRef = path.join(dir, "overview.md");
@@ -206,12 +206,10 @@ describe("skill content IO", () => {
     writeFileSync(siblingRef, "# Overview\nSibling content", "utf8");
 
     const result = await readSkillContentWithReferences(file, true);
-    expect(result.references).toEqual([
-      { relativePath: "overview.md", content: "# Overview\nSibling content" },
-    ]);
+    expect(result.references).toEqual([]);
   });
 
-  it("lists available reference paths from explicit and sibling markdown files", async () => {
+  it("lists available reference paths only from explicit markdown links", async () => {
     const dir = createTempDir("mcp-refs-list-");
     const file = path.join(dir, "SKILL.md");
     const refsDir = path.join(dir, "references");
@@ -232,7 +230,6 @@ describe("skill content IO", () => {
     writeFileSync(path.join(dir, "overview.md"), "# Overview", "utf8");
 
     await expect(listReferencedMarkdownPaths(file)).resolves.toEqual([
-      "overview.md",
       "references/guide.md",
     ]);
   });

package/mcp/src/vault/manifest.ts

@@ -2,10 +2,11 @@
  * Cubis Foundry MCP Server – vault manifest.
  *
  * Browse/search operations extract frontmatter description only (truncated).
- * Full SKILL.md content (and direct referenced markdown files) is read by skill_get.
+ * Full SKILL.md content is read by skill_get; direct referenced markdown files
+ * are loaded only when requested.
  */
 
-import { readdir, readFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import type { SkillPointer, VaultManifest } from "./types.js";
 import { logger } from "../utils/logger.js";
@@ -211,10 +212,7 @@ async function readReferencedMarkdownFiles(
   skillContent: string,
 ): Promise<ReferencedSkillFile[]> {
   const skillDir = path.dirname(skillPath);
-  let targets = collectReferencedMarkdownTargets(skillContent);
-  if (targets.length === 0) {
-    targets = await collectSiblingMarkdownTargets(skillDir);
-  }
+  const targets = collectReferencedMarkdownTargets(skillContent);
   const references: ReferencedSkillFile[] = [];
 
   for (const target of targets) {
@@ -242,54 +240,17 @@ async function readReferencedMarkdownFiles(
   return references;
 }
 
-async function collectSiblingMarkdownTargets(
-  skillDir: string,
-): Promise<string[]> {
-  const entries = await readdir(skillDir, { withFileTypes: true }).catch(
-    () => [],
-  );
-  const targets: string[] = [];
-
-  for (const entry of entries) {
-    if (entry.name.startsWith(".")) continue;
-
-    if (entry.isDirectory()) {
-      // One level deep: scan subdirectories like references/, steering/, parts/
-      const subEntries = await readdir(path.join(skillDir, entry.name), {
-        withFileTypes: true,
-      }).catch(() => []);
-      for (const sub of subEntries) {
-        if (!sub.isFile()) continue;
-        if (sub.name.startsWith(".")) continue;
-        if (!sub.name.toLowerCase().endsWith(".md")) continue;
-        targets.push(`${entry.name}/${sub.name}`);
-        if (targets.length >= MAX_REFERENCED_FILES) break;
-      }
-    } else if (entry.isFile()) {
-      if (!entry.name.toLowerCase().endsWith(".md")) continue;
-      if (entry.name.toLowerCase() === "skill.md") continue;
-      targets.push(entry.name);
-    }
-
-    if (targets.length >= MAX_REFERENCED_FILES) break;
-  }
-
-  targets.sort((a, b) => a.localeCompare(b));
-  return targets;
-}
-
 export async function listReferencedMarkdownPaths(
   skillPath: string,
   skillContent?: string,
 ): Promise<string[]> {
   const source = skillContent ?? (await readFullSkillContent(skillPath));
   const skillDir = path.dirname(skillPath);
-  const explicitTargets = collectReferencedMarkdownTargets(source)
+  return collectReferencedMarkdownTargets(source)
     .map((target) => normalizeInSkillMarkdownTarget(skillDir, target))
-    .filter((target): target is string => Boolean(target));
-  const siblingTargets = await collectSiblingMarkdownTargets(skillDir);
-  const merged = new Set<string>([...explicitTargets, ...siblingTargets]);
-  return [...merged].sort((a, b) => a.localeCompare(b)).slice(0, MAX_REFERENCED_FILES);
+    .filter((target): target is string => Boolean(target))
+    .sort((a, b) => a.localeCompare(b))
+    .slice(0, MAX_REFERENCED_FILES);
 }
 
 export async function readSkillReferenceFile(

package/mcp/src/vault/scanner.test.ts

@@ -103,4 +103,33 @@ describe("scanVaultRoots", () => {
 
     expect(ids).toEqual(["lint-and-validate", "tdd-workflow"]);
   });
+
+  it("synthesizes compatibility aliases from canonical metadata", async () => {
+    const root = createTempDir("mcp-vault-alias-");
+    createSkillFromContent(
+      root,
+      "react-best-practices",
+      [
+        "---",
+        "name: react-best-practices",
+        "description: React review checklist",
+        "metadata:",
+        "  aliases: [nextjs-react-expert]",
+        "---",
+        "# Skill",
+      ].join("\n"),
+    );
+
+    const skills = await scanVaultRoots([root], "/unused");
+    const canonical = skills.find((skill) => skill.id === "react-best-practices");
+    const alias = skills.find((skill) => skill.id === "nextjs-react-expert");
+
+    expect(canonical?.canonicalId).toBeUndefined();
+    expect(alias).toMatchObject({
+      id: "nextjs-react-expert",
+      canonicalId: "react-best-practices",
+      category: "frontend",
+      path: canonical?.path,
+    });
+  });
 });