@cubis/foundry 0.3.46 → 0.3.47

package/mcp/src/tools/skillGet.ts

@@ -7,8 +7,8 @@
 
 import { z } from "zod";
 import type { VaultManifest } from "../vault/types.js";
-import { readFullSkillContent } from "../vault/manifest.js";
-import { notFound } from "../utils/errors.js";
+import { readSkillContentWithReferences } from "../vault/manifest.js";
+import { invalidInput, notFound } from "../utils/errors.js";
 import {
   buildSkillToolMetrics,
   estimateTokensFromText,
@@ -17,10 +17,16 @@ import {
 export const skillGetName = "skill_get";
 
 export const skillGetDescription =
-  "Get the full content of a specific skill by ID. Returns the complete SKILL.md file content.";
+  "Get full content of a specific skill by ID. Returns SKILL.md content and optionally direct referenced markdown files.";
 
 export const skillGetSchema = z.object({
   id: z.string().describe("The skill ID (directory name) to retrieve"),
+  includeReferences: z
+    .boolean()
+    .optional()
+    .describe(
+      "Whether to include direct local markdown references from SKILL.md (default: true)",
+    ),
 });
 
 export async function handleSkillGet(
@@ -28,14 +34,38 @@ export async function handleSkillGet(
   manifest: VaultManifest,
   charsPerToken: number,
 ) {
-  const { id } = args;
+  const { id, includeReferences = true } = args;
+
+  if (id.startsWith("workflow-") || id.startsWith("agent-")) {
+    invalidInput(
+      `Skill id "${id}" appears to be a wrapper id. Use workflow/agent routing (for example $workflow-implement-track or $agent-backend-specialist) and call skill_get only for concrete skill ids.`,
+    );
+  }
 
   const skill = manifest.skills.find((s) => s.id === id);
   if (!skill) {
     notFound("Skill", id);
   }
 
-  const content = await readFullSkillContent(skill.path);
+  const { skillContent, references } = await readSkillContentWithReferences(
+    skill.path,
+    includeReferences,
+  );
+  const referenceSection =
+    references.length > 0
+      ? [
+          "",
+          "## Referenced Files",
+          "",
+          ...references.flatMap((ref) => [
+            `### ${ref.relativePath}`,
+            "",
+            ref.content.trimEnd(),
+            "",
+          ]),
+        ].join("\n")
+      : "";
+  const content = `${skillContent}${referenceSection}`;
   const loadedSkillEstimatedTokens = estimateTokensFromText(
     content,
     charsPerToken,
@@ -55,6 +85,7 @@ export async function handleSkillGet(
       },
     ],
     structuredContent: {
+      references: references.map((ref) => ({ path: ref.relativePath })),
       metrics,
     },
   };

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { mkdtempSync, statSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, statSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import type { VaultManifest } from "../vault/types.js";
@@ -147,6 +147,134 @@ describe("skill tools", () => {
     expect(toolMetrics.loadedSkillEstimatedTokens).toBeGreaterThan(0);
   });
 
+  it("includes 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");
+    mkdirSync(referencesDir, { recursive: true });
+    writeFileSync(
+      skillFile,
+      [
+        "---",
+        "name: referenced-skill",
+        "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",
+          category: "general",
+          path: skillFile,
+          fileBytes: skillBytes,
+        },
+      ],
+      fullCatalogBytes: skillBytes,
+      fullCatalogEstimatedTokens: Math.ceil(skillBytes / 4),
+    };
+
+    const result = await handleSkillGet({ id: "referenced-skill" }, 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");
+  });
+
+  it("skips referenced markdown files when includeReferences is false", async () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), "mcp-skill-ref-skip-"));
+    const skillFile = path.join(dir, "SKILL.md");
+    const referencesDir = path.join(dir, "references");
+    mkdirSync(referencesDir, { recursive: true });
+    writeFileSync(
+      skillFile,
+      [
+        "---",
+        "name: referenced-skill-no-refs",
+        "description: skill with refs",
+        "---",
+        "# Skill",
+        "See [Guide](references/guide.md).",
+      ].join("\n"),
+      "utf8",
+    );
+    writeFileSync(path.join(referencesDir, "guide.md"), "# Guide", "utf8");
+
+    const skillBytes = statSync(skillFile).size;
+    const manifest: VaultManifest = {
+      categories: ["general"],
+      skills: [
+        {
+          id: "referenced-skill-no-refs",
+          category: "general",
+          path: skillFile,
+          fileBytes: skillBytes,
+        },
+      ],
+      fullCatalogBytes: skillBytes,
+      fullCatalogEstimatedTokens: Math.ceil(skillBytes / 4),
+    };
+
+    const result = await handleSkillGet(
+      { id: "referenced-skill-no-refs", includeReferences: false },
+      manifest,
+      4,
+    );
+    expect(result.content[0].text).not.toContain("## Referenced Files");
+    expect(result.content[0].text).not.toContain("### references/guide.md");
+  });
+
+  it("loads 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(
+      skillFile,
+      [
+        "---",
+        "name: sibling-fallback-skill",
+        "description: fallback sibling",
+        "---",
+        "# Skill",
+      ].join("\n"),
+      "utf8",
+    );
+    writeFileSync(path.join(dir, "overview.md"), "# Overview\nSibling", "utf8");
+
+    const skillBytes = statSync(skillFile).size;
+    const manifest: VaultManifest = {
+      categories: ["general"],
+      skills: [
+        {
+          id: "sibling-fallback-skill",
+          category: "general",
+          path: skillFile,
+          fileBytes: skillBytes,
+        },
+      ],
+      fullCatalogBytes: skillBytes,
+      fullCatalogEstimatedTokens: Math.ceil(skillBytes / 4),
+    };
+
+    const result = await handleSkillGet(
+      { id: "sibling-fallback-skill" },
+      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");
+  });
+
   it("throws when skill_get cannot find the requested skill", async () => {
     const manifest = createManifest();
     await expect(handleSkillGet({ id: "missing" }, manifest, 4)).rejects.toThrow(
@@ -154,6 +282,20 @@ describe("skill tools", () => {
     );
   });
 
+  it("throws a wrapper guidance error when skill_get receives workflow id", async () => {
+    const manifest = createManifest();
+    await expect(
+      handleSkillGet({ id: "workflow-implement-track" }, manifest, 4),
+    ).rejects.toThrow("appears to be a wrapper id");
+  });
+
+  it("throws a wrapper guidance error when skill_get receives agent id", async () => {
+    const manifest = createManifest();
+    await expect(
+      handleSkillGet({ id: "agent-backend-specialist" }, manifest, 4),
+    ).rejects.toThrow("appears to be a wrapper id");
+  });
+
   it("returns consolidated budget rollup for selected and loaded skills", () => {
     const manifest = createManifest();
     const result = handleSkillBudgetReport(

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

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it } from "vitest";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import {
@@ -8,6 +8,7 @@ import {
   extractDescription,
   parseDescriptionFromFrontmatter,
   readFullSkillContent,
+  readSkillContentWithReferences,
 } from "./manifest.js";
 
 const tempDirs: string[] = [];
@@ -90,6 +91,75 @@ describe("skill content IO", () => {
 
     await expect(readFullSkillContent(file)).resolves.toBe(body);
   });
+
+  it("loads direct local markdown references from SKILL.md", async () => {
+    const dir = createTempDir("mcp-refs-read-");
+    const file = path.join(dir, "SKILL.md");
+    const refsDir = path.join(dir, "references");
+    const refFile = path.join(refsDir, "guide.md");
+    const nestedRefFile = path.join(dir, "notes.md");
+
+    writeFileSync(
+      file,
+      [
+        "---",
+        "name: ref-read",
+        "description: Read refs",
+        "---",
+        "# Skill",
+        "See [Guide](references/guide.md).",
+        "See [Notes](notes.md#section).",
+        "Ignore [External](https://example.com).",
+      ].join("\n"),
+      "utf8",
+    );
+    mkdirSync(refsDir, { recursive: true });
+    writeFileSync(refFile, "# Guide\nReference body", "utf8");
+    writeFileSync(nestedRefFile, "# Notes\nMore details", "utf8");
+
+    const result = await readSkillContentWithReferences(file, true);
+    expect(result.skillContent).toContain("# Skill");
+    expect(result.references).toEqual([
+      { relativePath: "references/guide.md", content: "# Guide\nReference body" },
+      { relativePath: "notes.md", content: "# Notes\nMore details" },
+    ]);
+  });
+
+  it("skips references when includeReferences is false", async () => {
+    const dir = createTempDir("mcp-refs-skip-");
+    const file = path.join(dir, "SKILL.md");
+    const refFile = path.join(dir, "reference.md");
+    writeFileSync(
+      file,
+      ["---", "name: skip", "description: skip", "---", "[Ref](reference.md)"].join(
+        "\n",
+      ),
+      "utf8",
+    );
+    writeFileSync(refFile, "ref", "utf8");
+
+    const result = await readSkillContentWithReferences(file, false);
+    expect(result.references).toEqual([]);
+  });
+
+  it("falls back to sibling markdown files when SKILL.md has no links", async () => {
+    const dir = createTempDir("mcp-refs-fallback-");
+    const file = path.join(dir, "SKILL.md");
+    const siblingRef = path.join(dir, "overview.md");
+    writeFileSync(
+      file,
+      ["---", "name: fallback", "description: fallback", "---", "# Skill"].join(
+        "\n",
+      ),
+      "utf8",
+    );
+    writeFileSync(siblingRef, "# Overview\nSibling content", "utf8");
+
+    const result = await readSkillContentWithReferences(file, true);
+    expect(result.references).toEqual([
+      { relativePath: "overview.md", content: "# Overview\nSibling content" },
+    ]);
+  });
 });
 
 describe("manifest enrichment", () => {

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 is read only by skill_get.
+ * Full SKILL.md content (and direct referenced markdown files) is read by skill_get.
  */
 
-import { readFile } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
 import type { SkillPointer, VaultManifest } from "./types.js";
 import { logger } from "../utils/logger.js";
 import { estimateTokensFromBytes } from "../telemetry/tokenBudget.js";
@@ -87,12 +88,136 @@ export function parseDescriptionFromFrontmatter(
 
 /**
  * Read the full content of a SKILL.md file.
- * This is the ONLY function that reads full file content (lazy model).
  */
 export async function readFullSkillContent(skillPath: string): Promise<string> {
   return readFile(skillPath, "utf8");
 }
 
+const MARKDOWN_LINK_RE = /\[[^\]]+\]\(([^)]+)\)/g;
+const MAX_REFERENCED_FILES = 25;
+
+export interface ReferencedSkillFile {
+  relativePath: string;
+  content: string;
+}
+
+function normalizeLinkTarget(rawTarget: string): string | null {
+  let target = String(rawTarget || "").trim();
+  if (!target) return null;
+
+  // Support links wrapped in angle brackets: [x](<references/doc.md>)
+  if (target.startsWith("<") && target.endsWith(">")) {
+    target = target.slice(1, -1).trim();
+  }
+
+  // Strip optional title segment: [x](path "title")
+  const firstSpace = target.search(/\s/);
+  if (firstSpace > 0) {
+    target = target.slice(0, firstSpace).trim();
+  }
+
+  // Ignore anchors/query fragments for file loading
+  target = target.split("#")[0].split("?")[0].trim();
+  if (!target) return null;
+
+  // Skip URLs/protocol links and absolute paths
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(target)) return null;
+  if (/^[a-zA-Z]:[\\/]/.test(target)) return null; // Windows absolute path
+  if (path.isAbsolute(target)) return null;
+
+  return target;
+}
+
+function collectReferencedMarkdownTargets(skillContent: string): string[] {
+  const targets: string[] = [];
+  const seen = new Set<string>();
+
+  for (const match of skillContent.matchAll(MARKDOWN_LINK_RE)) {
+    const raw = match[1];
+    const normalized = normalizeLinkTarget(raw);
+    if (!normalized) continue;
+    if (!normalized.toLowerCase().endsWith(".md")) continue;
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    targets.push(normalized);
+    if (targets.length >= MAX_REFERENCED_FILES) break;
+  }
+
+  return targets;
+}
+
+async function readReferencedMarkdownFiles(
+  skillPath: string,
+  skillContent: string,
+): Promise<ReferencedSkillFile[]> {
+  const skillDir = path.dirname(skillPath);
+  let targets = collectReferencedMarkdownTargets(skillContent);
+  if (targets.length === 0) {
+    targets = await collectSiblingMarkdownTargets(skillDir);
+  }
+  const references: ReferencedSkillFile[] = [];
+
+  for (const target of targets) {
+    const resolved = path.resolve(skillDir, target);
+    const relative = path.relative(skillDir, resolved);
+
+    // Prevent path traversal outside the skill directory.
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+      continue;
+    }
+
+    if (path.basename(resolved).toLowerCase() === "skill.md") continue;
+
+    try {
+      const content = await readFile(resolved, "utf8");
+      references.push({
+        relativePath: relative.split(path.sep).join("/"),
+        content,
+      });
+    } catch (err) {
+      logger.debug(`Failed to read referenced markdown ${resolved}: ${err}`);
+    }
+  }
+
+  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.isFile()) continue;
+    if (entry.name.startsWith(".")) continue;
+    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;
+}
+
+/**
+ * Read full SKILL.md content and any direct local markdown references declared
+ * in the skill document. Reference discovery is one-hop (no recursive crawling).
+ */
+export async function readSkillContentWithReferences(
+  skillPath: string,
+  includeReferences = true,
+): Promise<{ skillContent: string; references: ReferencedSkillFile[] }> {
+  const skillContent = await readFullSkillContent(skillPath);
+  if (!includeReferences) {
+    return { skillContent, references: [] };
+  }
+
+  const references = await readReferencedMarkdownFiles(skillPath, skillContent);
+  return { skillContent, references };
+}
+
 /**
  * Enrich skill pointers with descriptions (for browse/search results).
  */

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

@@ -22,6 +22,12 @@ function createSkill(root: string, id: string): void {
   );
 }
 
+function createSkillFromContent(root: string, id: string, content: string): void {
+  const skillDir = path.join(root, id);
+  mkdirSync(skillDir, { recursive: true });
+  writeFileSync(path.join(skillDir, "SKILL.md"), content, "utf8");
+}
+
 afterEach(() => {
   while (tempDirs.length > 0) {
     const dir = tempDirs.pop();
@@ -68,4 +74,33 @@ describe("scanVaultRoots", () => {
     expect(skills[0].id).toBe("qa-automation-engineer");
     expect(skills[0].category).toBe("testing");
   });
+
+  it("excludes codex wrapper skills from vault discovery", async () => {
+    const root = createTempDir("mcp-vault-wrapper-");
+
+    createSkill(root, "lint-and-validate");
+    createSkill(root, "tdd-workflow");
+    createSkill(root, "workflow-implement-track");
+    createSkill(root, "agent-backend-specialist");
+    createSkillFromContent(
+      root,
+      "custom-wrapper-id",
+      [
+        "---",
+        "name: custom-wrapper-id",
+        "description: Wrapper by metadata only",
+        "metadata:",
+        "  wrapper: workflow",
+        "---",
+        "",
+        "# wrapper",
+        "",
+      ].join("\n"),
+    );
+
+    const skills = await scanVaultRoots([root], "/unused");
+    const ids = skills.map((s) => s.id).sort();
+
+    expect(ids).toEqual(["lint-and-validate", "tdd-workflow"]);
+  });
 });

package/mcp/src/vault/scanner.ts

@@ -5,7 +5,7 @@
  * Description extraction is deferred to browse/search operations.
  */
 
-import { readdir, stat } from "node:fs/promises";
+import { open, readdir, stat } from "node:fs/promises";
 import path from "node:path";
 import { logger } from "../utils/logger.js";
 import type { SkillPointer } from "./types.js";
@@ -40,6 +40,14 @@ export async function scanVaultRoots(
       const skillStat = await stat(skillFile).catch(() => null);
       if (!skillStat?.isFile()) continue;
 
+      const wrapperKind = await detectWrapperKind(entry, skillFile);
+      if (wrapperKind) {
+        logger.debug(
+          `Skipping wrapper skill ${entry} (${wrapperKind}) at ${skillFile}`,
+        );
+        continue;
+      }
+
       // Derive category from the skill's frontmatter or default to "general"
       // At scan time we only store the path; category is derived from directory structure
       skills.push({
@@ -55,6 +63,88 @@ export async function scanVaultRoots(
   return skills;
 }
 
+const WRAPPER_PREFIXES = ["workflow-", "agent-"] as const;
+const WRAPPER_KINDS = new Set(["workflow", "agent"]);
+const FRONTMATTER_PREVIEW_BYTES = 8192;
+
+function extractWrapperKindFromId(skillId: string): "workflow" | "agent" | null {
+  const lower = skillId.toLowerCase();
+  if (lower.startsWith(WRAPPER_PREFIXES[0])) return "workflow";
+  if (lower.startsWith(WRAPPER_PREFIXES[1])) return "agent";
+  return null;
+}
+
+async function readFrontmatterPreview(skillFile: string): Promise<string | null> {
+  const handle = await open(skillFile, "r").catch(() => null);
+  if (!handle) return null;
+
+  try {
+    // Read only a small head chunk; wrapper metadata lives in frontmatter.
+    const buffer = Buffer.alloc(FRONTMATTER_PREVIEW_BYTES);
+    const { bytesRead } = await handle.read(
+      buffer,
+      0,
+      FRONTMATTER_PREVIEW_BYTES,
+      0,
+    );
+    return buffer.toString("utf8", 0, bytesRead);
+  } finally {
+    await handle.close();
+  }
+}
+
+function parseFrontmatter(rawPreview: string): string | null {
+  const match = rawPreview.match(/^---\s*\n([\s\S]*?)\n---/);
+  return match?.[1] ?? null;
+}
+
+function extractMetadataWrapper(frontmatter: string): string | null {
+  const lines = frontmatter.split(/\r?\n/);
+  let inMetadata = false;
+
+  for (const line of lines) {
+    if (!inMetadata) {
+      if (/^\s*metadata\s*:\s*$/.test(line)) {
+        inMetadata = true;
+      }
+      continue;
+    }
+
+    if (!line.trim()) continue;
+    if (!/^\s+/.test(line)) break;
+
+    const match = line.match(/^\s+wrapper\s*:\s*(.+)\s*$/);
+    if (!match) continue;
+
+    const value = match[1].trim().replace(/^['"]|['"]$/g, "").toLowerCase();
+    if (WRAPPER_KINDS.has(value)) {
+      return value;
+    }
+  }
+
+  return null;
+}
+
+async function detectWrapperKind(
+  skillId: string,
+  skillFile: string,
+): Promise<"workflow" | "agent" | null> {
+  const byId = extractWrapperKindFromId(skillId);
+  if (byId) return byId;
+
+  const rawPreview = await readFrontmatterPreview(skillFile);
+  if (!rawPreview) return null;
+  const frontmatter = parseFrontmatter(rawPreview);
+  if (!frontmatter) return null;
+
+  const byMetadata = extractMetadataWrapper(frontmatter);
+  if (byMetadata === "workflow" || byMetadata === "agent") {
+    return byMetadata;
+  }
+
+  return null;
+}
+
 /**
  * Simple category derivation from skill ID conventions.
  * Skills with common prefixes are grouped together.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubis/foundry",
-  "version": "0.3.46",
+  "version": "0.3.47",
   "description": "Cubis Foundry CLI for workflow-first AI agent environments",
   "type": "module",
   "bin": {

package/workflows/workflows/agent-environment-setup/platforms/codex/rules/AGENTS.md

@@ -79,6 +79,12 @@ After finishing skill selection/loading, publish:
 - `loaded_skills`: skill IDs loaded via `skill_get`
 - `skipped_skills`: considered but not loaded
 
+Workflow boundary for this block:
+
+- `selected_skills` / `loaded_skills` must never include workflow IDs.
+- IDs like `workflow-implement-track` are workflow routes, not skills.
+- Never call `skill_get` with `workflow-*`; keep workflow mentions in the workflow decision log using raw $workflow-* wrappers.
+
 ## Context Budget Block (Required, Estimated)
 
 Immediately after the Skill Log block, publish estimated budget fields:

package/workflows/workflows/agent-environment-setup/platforms/copilot/rules/AGENTS.md

@@ -87,6 +87,12 @@ After finishing skill selection/loading, publish:
 - `loaded_skills`: skill IDs loaded via `skill_get`
 - `skipped_skills`: considered but not loaded
 
+Workflow boundary for this block:
+
+- `selected_skills` / `loaded_skills` must never include workflow IDs.
+- IDs like `workflow-implement-track` are workflow routes, not skills.
+- Never call `skill_get` with `workflow-*`; keep workflow mentions in workflow decisions (`/workflow`) and keep skill logs skill-only.
+
 ## Context Budget Block (Required, Estimated)
 
 Immediately after the Skill Log block, publish estimated budget fields:

package/workflows/workflows/agent-environment-setup/platforms/copilot/rules/copilot-instructions.md

@@ -87,6 +87,12 @@ After finishing skill selection/loading, publish:
 - `loaded_skills`: skill IDs loaded via `skill_get`
 - `skipped_skills`: considered but not loaded
 
+Workflow boundary for this block:
+
+- `selected_skills` / `loaded_skills` must never include workflow IDs.
+- IDs like `workflow-implement-track` are workflow routes, not skills.
+- Never call `skill_get` with `workflow-*`; keep workflow mentions in workflow decisions (`/workflow`) and keep skill logs skill-only.
+
 ## Context Budget Block (Required, Estimated)
 
 Immediately after the Skill Log block, publish estimated budget fields: