@cubis/foundry 0.3.32 → 0.3.33

package/bin/cubis.js

@@ -249,6 +249,13 @@ const TECH_RUST_FRAMEWORK_SIGNALS = [
   ["rocket", "Rocket"],
   ["tokio", "Tokio"]
 ];
+const SKILL_PROFILES = new Set(["core", "web-backend", "full"]);
+const DEFAULT_SKILL_PROFILE = "core";
+const CATALOG_FILES = Object.freeze({
+  core: path.join("skills", "catalogs", "core.json"),
+  "web-backend": path.join("skills", "catalogs", "web-backend.json"),
+  mcp: path.join("catalogs", "default.json")
+});
 
 function platformInstallsCustomAgents(platformId) {
   const profile = WORKFLOW_PROFILES[platformId];
@@ -287,6 +294,22 @@ function agentAssetsRoot() {
   return existsSync(preferred) ? preferred : packageRoot();
 }
 
+function workflowSkillsRoot() {
+  return path.join(agentAssetsRoot(), "skills");
+}
+
+function mcpRoot() {
+  return path.join(packageRoot(), "mcp");
+}
+
+function mcpSkillsRoot() {
+  return path.join(mcpRoot(), "skills");
+}
+
+function mcpCatalogRoot() {
+  return path.join(mcpRoot(), "catalogs");
+}
+
 function expandPath(inputPath, cwd = process.cwd()) {
   if (!inputPath) return cwd;
   if (inputPath === "~") return os.homedir();
@@ -308,6 +331,32 @@ function normalizeScope(value) {
   throw new Error(`Unknown scope '${value}'. Use --scope project or --scope global.`);
 }
 
+function normalizeSkillProfile(value) {
+  const normalized = String(value || DEFAULT_SKILL_PROFILE)
+    .trim()
+    .toLowerCase();
+  if (!SKILL_PROFILES.has(normalized)) {
+    throw new Error(`Unknown skill profile '${value}'. Use core|web-backend|full.`);
+  }
+  return normalized;
+}
+
+function resolveWorkflowSkillInstallOptions(options) {
+  const allSkills = Boolean(options.allSkills);
+  let skillProfile = normalizeSkillProfile(options.skillProfile || DEFAULT_SKILL_PROFILE);
+  let includeMcp = Boolean(options.includeMcp);
+
+  if (allSkills) {
+    skillProfile = "full";
+    includeMcp = true;
+  }
+
+  return {
+    skillProfile,
+    includeMcp
+  };
+}
+
 function normalizeMcpScope(value, fallback = "project") {
   if (!value) return fallback;
   const normalized = value.trim().toLowerCase();
@@ -1144,6 +1193,20 @@ async function collectTechSnapshot(rootDir) {
     keyScripts.push({ name, command: packageScripts.get(name) });
   }
 
+  const mcpSignals = [];
+  const mcpSignalPaths = [
+    "cbx_config.json",
+    ".cbx/mcp",
+    ".vscode/mcp.json",
+    ".gemini/settings.json",
+    ".copilot/mcp-config.json"
+  ];
+  for (const signalPath of mcpSignalPaths) {
+    if (fileExists(signalPath)) {
+      mcpSignals.push(signalPath);
+    }
+  }
+
   return {
     rootDir,
     scannedFiles: discoveredFiles.length,
@@ -1158,7 +1221,8 @@ async function collectTechSnapshot(rootDir) {
       go: toSortedArray(goModules),
       python: toSortedArray(pythonPackages),
       rust: toSortedArray(rustCrates)
-    }
+    },
+    mcpSignals: toSortedArray(mcpSignals)
   };
 }
 
@@ -1178,13 +1242,66 @@ function appendTechPackageSection(lines, heading, packages) {
   lines.push("");
 }
 
-function buildTechMd(snapshot) {
+function inferRecommendedSkills(snapshot) {
+  const recommended = new Set();
+  const hasFramework = (name) => snapshot.frameworks.includes(name);
+
+  if (hasFramework("Next.js")) {
+    recommended.add("nextjs-developer");
+    recommended.add("react-expert");
+    recommended.add("typescript-pro");
+  }
+  if (hasFramework("React")) {
+    recommended.add("react-expert");
+  }
+  if (hasFramework("NestJS")) {
+    recommended.add("nestjs-expert");
+    recommended.add("nodejs-best-practices");
+  }
+  if (hasFramework("FastAPI")) {
+    recommended.add("fastapi-expert");
+    recommended.add("python-pro");
+  }
+  if (hasFramework("Go Modules")) {
+    recommended.add("golang-pro");
+  }
+  if (hasFramework("Rust Cargo")) {
+    recommended.add("rust-pro");
+  }
+  if (hasFramework("Flutter")) {
+    recommended.add("flutter-expert");
+    recommended.add("mobile-design");
+  }
+  if (recommended.size === 0) {
+    recommended.add("clean-code");
+    recommended.add("plan-writing");
+  }
+
+  return [...recommended].sort((a, b) => a.localeCompare(b));
+}
+
+function inferContextBudget(snapshot) {
+  const webBackendSignals = new Set(["Next.js", "React", "NestJS", "FastAPI", "Go Modules", "Rust Cargo"]);
+  const webBackendDetected = snapshot.frameworks.some((framework) => webBackendSignals.has(framework));
+  const suggestedProfile = webBackendDetected ? "web-backend" : "core";
+  const includeMcp = Array.isArray(snapshot.mcpSignals) && snapshot.mcpSignals.length > 0;
+  return {
+    suggestedProfile,
+    includeMcp
+  };
+}
+
+function buildTechMd(snapshot, { compact = false } = {}) {
   const lines = [];
+  const recommendedSkills = inferRecommendedSkills(snapshot);
+  const contextBudget = inferContextBudget(snapshot);
+
   lines.push("# TECH.md");
   lines.push("");
   lines.push(`Generated by cbx on ${new Date().toISOString()}.`);
   lines.push(`Root: \`${toPosixPath(snapshot.rootDir)}\``);
   lines.push(`Files scanned: ${snapshot.scannedFiles} (max ${TECH_SCAN_MAX_FILES}).`);
+  lines.push(`Mode: ${compact ? "compact" : "full"}.`);
   lines.push("");
 
   lines.push("## Stack Snapshot");
@@ -1207,43 +1324,69 @@ function buildTechMd(snapshot) {
   }
   lines.push("");
 
-  lines.push("## Package Signals");
-  appendTechPackageSection(lines, "JavaScript / TypeScript (package.json)", snapshot.packageSignals.javascript);
-  appendTechPackageSection(lines, "Dart / Flutter (pubspec.yaml)", snapshot.packageSignals.dart);
-  appendTechPackageSection(lines, "Go Modules (go.mod)", snapshot.packageSignals.go);
-  appendTechPackageSection(lines, "Python Packages (requirements / pyproject)", snapshot.packageSignals.python);
-  appendTechPackageSection(lines, "Rust Crates (Cargo.toml)", snapshot.packageSignals.rust);
-
-  lines.push("## Tooling and Lockfiles");
-  if (snapshot.lockfiles.length === 0) {
-    lines.push("- No lockfiles detected.");
-  } else {
-    lines.push(`- ${snapshot.lockfiles.join(", ")}`);
+  lines.push("## Recommended Skills");
+  for (const skillId of recommendedSkills) {
+    lines.push(`- \`${skillId}\``);
   }
   lines.push("");
 
-  lines.push("## Key Scripts");
-  if (snapshot.keyScripts.length === 0) {
-    lines.push("- No common scripts detected.");
+  lines.push("## MCP Footprint");
+  if (!snapshot.mcpSignals || snapshot.mcpSignals.length === 0) {
+    lines.push("- No MCP configuration signals detected in workspace.");
   } else {
-    for (const script of snapshot.keyScripts) {
-      lines.push(`- \`${script.name}\`: \`${script.command}\``);
+    for (const signal of snapshot.mcpSignals) {
+      lines.push(`- \`${signal}\``);
     }
   }
   lines.push("");
 
-  lines.push("## Important Top-Level Paths");
-  if (snapshot.topDirs.length === 0) {
-    lines.push("- No significant top-level directories detected.");
-  } else {
-    for (const dir of snapshot.topDirs) {
-      lines.push(`- \`${dir}/\``);
+  lines.push("## Context Budget Notes");
+  lines.push(`- Suggested install profile: \`${contextBudget.suggestedProfile}\``);
+  lines.push(`- Suggested MCP inclusion: \`${contextBudget.includeMcp ? "--include-mcp" : "skip --include-mcp"}\``);
+  lines.push("- Use `--all-skills` only when task scope clearly requires full catalog breadth.");
+  lines.push("");
+
+  if (!compact) {
+    lines.push("## Package Signals");
+    appendTechPackageSection(lines, "JavaScript / TypeScript (package.json)", snapshot.packageSignals.javascript);
+    appendTechPackageSection(lines, "Dart / Flutter (pubspec.yaml)", snapshot.packageSignals.dart);
+    appendTechPackageSection(lines, "Go Modules (go.mod)", snapshot.packageSignals.go);
+    appendTechPackageSection(lines, "Python Packages (requirements / pyproject)", snapshot.packageSignals.python);
+    appendTechPackageSection(lines, "Rust Crates (Cargo.toml)", snapshot.packageSignals.rust);
+
+    lines.push("## Tooling and Lockfiles");
+    if (snapshot.lockfiles.length === 0) {
+      lines.push("- No lockfiles detected.");
+    } else {
+      lines.push(`- ${snapshot.lockfiles.join(", ")}`);
+    }
+    lines.push("");
+
+    lines.push("## Key Scripts");
+    if (snapshot.keyScripts.length === 0) {
+      lines.push("- No common scripts detected.");
+    } else {
+      for (const script of snapshot.keyScripts) {
+        lines.push(`- \`${script.name}\`: \`${script.command}\``);
+      }
+    }
+    lines.push("");
+
+    lines.push("## Important Top-Level Paths");
+    if (snapshot.topDirs.length === 0) {
+      lines.push("- No significant top-level directories detected.");
+    } else {
+      for (const dir of snapshot.topDirs) {
+        lines.push(`- \`${dir}/\``);
+      }
     }
+    lines.push("");
   }
-  lines.push("");
 
   lines.push("## Maintenance");
-  lines.push("- Re-run `cbx rules tech-md --overwrite` after major stack or architecture changes.");
+  lines.push(
+    `- Re-run \`cbx rules tech-md --overwrite${compact ? " --compact" : ""}\` after major stack or architecture changes.`
+  );
   lines.push("");
 
   return lines.join("\n");
@@ -1489,7 +1632,7 @@ function extractSkillIdFromIndexPath(indexPathValue) {
 }
 
 async function resolveTopLevelSkillIdsFromIndex() {
-  const skillsRoot = path.join(agentAssetsRoot(), "skills");
+  const skillsRoot = workflowSkillsRoot();
   const indexPath = path.join(skillsRoot, "skills_index.json");
   if (!(await pathExists(indexPath))) return [];
 
@@ -1531,11 +1674,97 @@ async function resolveTopLevelSkillIdsFromIndex() {
   return topLevelIds;
 }
 
-async function resolveInstallSkillIds({ platformSpec, extraSkillIds = [] }) {
-  const indexedSkillIds = await resolveTopLevelSkillIdsFromIndex();
+async function readSkillCatalogIds(catalogPath) {
+  if (!(await pathExists(catalogPath))) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(catalogPath, "utf8"));
+  } catch {
+    return [];
+  }
+
+  const values = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.skills) ? parsed.skills : [];
+  const ids = [];
+  const seen = new Set();
+  for (const value of values) {
+    const id = String(value || "").trim();
+    if (!id || id.startsWith(".")) continue;
+    const key = id.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    ids.push(id);
+  }
+  return ids;
+}
+
+async function listTopLevelSkillIdsFromRoot(rootPath) {
+  if (!(await pathExists(rootPath))) return [];
+  const entries = await readdir(rootPath, { withFileTypes: true });
+  const out = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+    const skillId = entry.name;
+    const skillFile = path.join(rootPath, skillId, "SKILL.md");
+    if (!(await pathExists(skillFile))) continue;
+    out.push(skillId);
+  }
+  return out.sort((a, b) => a.localeCompare(b));
+}
+
+async function resolveSkillSourceDirectory(skillId) {
+  const normalized = String(skillId || "").trim();
+  if (!normalized) return null;
+  const candidates = [
+    path.join(mcpSkillsRoot(), normalized),
+    path.join(workflowSkillsRoot(), normalized)
+  ];
+  for (const candidate of candidates) {
+    const skillFile = path.join(candidate, "SKILL.md");
+    if ((await pathExists(candidate)) && (await pathExists(skillFile))) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+async function resolveCatalogSkillIds({
+  profile,
+  includeMcp
+}) {
+  const workflowCatalogPath = path.join(workflowSkillsRoot(), CATALOG_FILES[profile] || "");
+  const workflowCatalogIds = await readSkillCatalogIds(workflowCatalogPath);
+  const workflowProfileIds =
+    workflowCatalogIds.length > 0
+      ? workflowCatalogIds
+      : profile === "full"
+        ? await listTopLevelSkillIdsFromRoot(workflowSkillsRoot())
+        : [];
+
+  if (!includeMcp) return workflowProfileIds;
+
+  const mcpCatalogPath = path.join(mcpCatalogRoot(), CATALOG_FILES.mcp);
+  const mcpCatalogIds = await readSkillCatalogIds(mcpCatalogPath);
+  const mcpIds = mcpCatalogIds.length > 0 ? mcpCatalogIds : await listTopLevelSkillIdsFromRoot(mcpSkillsRoot());
+  return unique([...workflowProfileIds, ...mcpIds]);
+}
+
+async function resolveInstallSkillIds({
+  platformSpec,
+  extraSkillIds = [],
+  skillProfile = DEFAULT_SKILL_PROFILE,
+  includeMcp = false
+}) {
   const fallbackManifestSkillIds = Array.isArray(platformSpec.skills) ? platformSpec.skills : [];
+  const catalogSelectedIds = await resolveCatalogSkillIds({
+    profile: normalizeSkillProfile(skillProfile),
+    includeMcp
+  });
 
-  let selected = indexedSkillIds.length > 0 ? indexedSkillIds : fallbackManifestSkillIds;
+  let selected = catalogSelectedIds.length > 0 ? catalogSelectedIds : fallbackManifestSkillIds;
+  if (selected.length === 0) {
+    const indexedSkillIds = await resolveTopLevelSkillIdsFromIndex();
+    selected = indexedSkillIds;
+  }
   if (Array.isArray(platformSpec.skillAllowList) && platformSpec.skillAllowList.length > 0) {
     const allow = new Set(platformSpec.skillAllowList.map((item) => String(item).toLowerCase()));
     selected = selected.filter((skillId) => allow.has(String(skillId).toLowerCase()));
@@ -3738,6 +3967,8 @@ async function installBundleArtifacts({
   overwrite,
   profilePathsOverride = null,
   extraSkillIds = [],
+  skillProfile = DEFAULT_SKILL_PROFILE,
+  includeMcp = false,
   terminalVerifierSelection = null,
   dryRun = false,
   cwd = process.cwd()
@@ -3838,14 +4069,18 @@ async function installBundleArtifacts({
 
   const skillIds = await resolveInstallSkillIds({
     platformSpec,
-    extraSkillIds
+    extraSkillIds,
+    skillProfile,
+    includeMcp
   });
   for (const skillId of skillIds) {
-    const source = path.join(agentAssetsRoot(), "skills", skillId);
+    const source = await resolveSkillSourceDirectory(skillId);
     const destination = path.join(profilePaths.skillsDir, skillId);
 
-    if (!(await pathExists(source))) {
-      throw new Error(`Missing skill source directory: ${source}`);
+    if (!source) {
+      throw new Error(
+        `Missing skill source directory for '${skillId}' (checked ${workflowSkillsRoot()} and ${mcpSkillsRoot()}).`
+      );
     }
 
     const result = await copyArtifact({ source, destination, overwrite, dryRun });
@@ -3855,7 +4090,7 @@ async function installBundleArtifacts({
   }
 
   // Copy skills_index.json if it exists in the package skills root
-  const skillsIndexSource = path.join(agentAssetsRoot(), "skills", "skills_index.json");
+  const skillsIndexSource = path.join(workflowSkillsRoot(), "skills_index.json");
   if (await pathExists(skillsIndexSource)) {
     const skillsIndexDest = path.join(profilePaths.skillsDir, "skills_index.json");
     const indexResult = await copyArtifact({ source: skillsIndexSource, destination: skillsIndexDest, overwrite, dryRun });
@@ -4638,6 +4873,13 @@ function withInstallOptions(command) {
       "--terminal-verifier <provider>",
       "Antigravity only: verifier provider (codex|gemini). Implies --terminal-integration."
     )
+    .option(
+      "--skill-profile <profile>",
+      "skill install profile: core|web-backend|full (default: core)",
+      DEFAULT_SKILL_PROFILE
+    )
+    .option("--include-mcp", "include MCP catalog skills in install selection")
+    .option("--all-skills", "alias for --skill-profile full --include-mcp")
     .option("--dry-run", "preview install without writing files")
     .option("-y, --yes", "skip interactive confirmation");
 }
@@ -4849,6 +5091,7 @@ async function runWorkflowInstall(options) {
       options,
       cwd
     });
+    const skillInstallOptions = resolveWorkflowSkillInstallOptions(options);
 
     const installResult = await installBundleArtifacts({
       bundleId,
@@ -4858,6 +5101,8 @@ async function runWorkflowInstall(options) {
       overwrite: Boolean(options.overwrite),
       profilePathsOverride: artifactProfilePaths,
       extraSkillIds: postmanSelection.enabled ? [POSTMAN_SKILL_ID] : [],
+      skillProfile: skillInstallOptions.skillProfile,
+      includeMcp: skillInstallOptions.includeMcp,
       terminalVerifierSelection,
       dryRun,
       cwd
@@ -4970,6 +5215,147 @@ async function runWorkflowInstall(options) {
   }
 }
 
+async function listInstalledTopLevelSkillDirs(skillsDir) {
+  if (!skillsDir || !(await pathExists(skillsDir))) return [];
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+  const out = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+    const skillId = entry.name;
+    const skillFile = path.join(skillsDir, skillId, "SKILL.md");
+    if (!(await pathExists(skillFile))) continue;
+    out.push(path.join(skillsDir, skillId));
+  }
+  return out.sort((a, b) => path.basename(a).localeCompare(path.basename(b)));
+}
+
+function isProtectedInstalledSkillId(skillId) {
+  const normalized = String(skillId || "").trim().toLowerCase();
+  if (!normalized) return true;
+  if (normalized.startsWith("workflow-") || normalized.startsWith("agent-")) return true;
+  return normalized.startsWith(".");
+}
+
+async function runWorkflowPruneSkills(options) {
+  try {
+    const cwd = process.cwd();
+    const scope = normalizeScope(options.scope);
+    const dryRun = Boolean(options.dryRun);
+    const platform = await resolvePlatform(options.platform, scope, cwd);
+    const profilePaths = await resolveArtifactProfilePaths(platform, scope, cwd);
+    const bundleId = await chooseBundle(options.bundle || "agent-environment-setup");
+    const manifest = await readBundleManifest(bundleId);
+    const platformSpec = manifest.platforms?.[platform];
+    if (!platformSpec) {
+      throw new Error(`Bundle '${bundleId}' does not define platform '${platform}'.`);
+    }
+    if (!profilePaths.skillsDir || !(await pathExists(profilePaths.skillsDir))) {
+      console.log(`No skills directory found at ${profilePaths.skillsDir || "(unset)"}. Nothing to prune.`);
+      return;
+    }
+
+    const skillInstallOptions = resolveWorkflowSkillInstallOptions(options);
+    const desiredSkillIds = await resolveInstallSkillIds({
+      platformSpec,
+      extraSkillIds: [],
+      skillProfile: skillInstallOptions.skillProfile,
+      includeMcp: skillInstallOptions.includeMcp
+    });
+    const desiredSet = new Set(desiredSkillIds.map((skillId) => String(skillId).toLowerCase()));
+
+    const installedSkillDirs = await listInstalledTopLevelSkillDirs(profilePaths.skillsDir);
+    const installedSkillIds = installedSkillDirs.map((dirPath) => path.basename(dirPath));
+    const nestedPlan = await cleanupNestedDuplicateSkills({
+      skillsRootDir: profilePaths.skillsDir,
+      installedSkillDirs,
+      dryRun: true
+    });
+
+    const removeOutOfProfile = installedSkillIds
+      .filter((skillId) => !isProtectedInstalledSkillId(skillId))
+      .filter((skillId) => !desiredSet.has(skillId.toLowerCase()))
+      .sort((a, b) => a.localeCompare(b));
+
+    const hasWork = nestedPlan.length > 0 || removeOutOfProfile.length > 0;
+    if (!hasWork) {
+      console.log("No stale skills found. Installed set already matches selected profile.");
+      console.log(
+        `Profile: ${skillInstallOptions.skillProfile} (include MCP: ${skillInstallOptions.includeMcp ? "yes" : "no"})`
+      );
+      return;
+    }
+
+    if (!dryRun && !options.yes && process.stdin.isTTY) {
+      const proceed = await confirm({
+        message: `Prune ${nestedPlan.length + removeOutOfProfile.length} stale skill path(s) for ${platform} (${scope})?`,
+        default: true
+      });
+      if (!proceed) {
+        console.log("Cancelled.");
+        process.exit(0);
+      }
+    }
+
+    const nestedResult = await cleanupNestedDuplicateSkills({
+      skillsRootDir: profilePaths.skillsDir,
+      installedSkillDirs,
+      dryRun
+    });
+
+    const removedOutOfProfile = [];
+    for (const skillId of removeOutOfProfile) {
+      const targetDir = path.join(profilePaths.skillsDir, skillId);
+      if (!dryRun) {
+        await rm(targetDir, { recursive: true, force: true });
+      }
+      removedOutOfProfile.push({
+        skillId,
+        path: targetDir,
+        action: dryRun ? "would-remove" : "removed"
+      });
+    }
+
+    const beforeCount = installedSkillIds.length;
+    const afterCount = dryRun
+      ? beforeCount - nestedResult.length - removedOutOfProfile.length
+      : (await listInstalledTopLevelSkillDirs(profilePaths.skillsDir)).length;
+
+    console.log("Skill prune summary:");
+    console.log(`- Platform/scope: ${platform}/${scope}`);
+    console.log(`- Bundle: ${bundleId}`);
+    console.log(
+      `- Profile: ${skillInstallOptions.skillProfile} (include MCP: ${skillInstallOptions.includeMcp ? "yes" : "no"})`
+    );
+    console.log(`- Installed before: ${beforeCount}`);
+    console.log(`- Nested duplicates: ${nestedResult.length}`);
+    console.log(`- Out-of-profile: ${removedOutOfProfile.length}`);
+    console.log(`- Installed after: ${afterCount}`);
+
+    if (nestedResult.length > 0) {
+      console.log("\nNested duplicate removals:");
+      for (const item of nestedResult) {
+        console.log(`- ${item.action}: ${item.path}`);
+      }
+    }
+    if (removedOutOfProfile.length > 0) {
+      console.log("\nOut-of-profile removals:");
+      for (const item of removedOutOfProfile) {
+        console.log(`- ${item.action}: ${item.path}`);
+      }
+    }
+    if (dryRun) {
+      console.log("\nDry-run complete. Re-run without `--dry-run` to apply changes.");
+    }
+  } catch (error) {
+    if (error?.name === "ExitPromptError") {
+      console.error("\nCancelled.");
+      process.exit(130);
+    }
+    console.error(`\nError: ${error.message}`);
+    process.exit(1);
+  }
+}
+
 async function runWorkflowRemove(target, options) {
   try {
     if (!target) {
@@ -5737,11 +6123,12 @@ async function runRulesTechMd(options) {
   try {
     const dryRun = Boolean(options.dryRun);
     const overwrite = Boolean(options.overwrite);
+    const compact = Boolean(options.compact);
     const cwd = process.cwd();
     const workspaceRoot = findWorkspaceRoot(cwd);
     const outputPath = options.output ? expandPath(options.output, cwd) : path.join(workspaceRoot, "TECH.md");
     const snapshot = await collectTechSnapshot(workspaceRoot);
-    const content = buildTechMd(snapshot);
+    const content = buildTechMd(snapshot, { compact });
     const result = await writeTextFile({
       targetPath: outputPath,
       content: `${content}\n`,
@@ -5753,6 +6140,7 @@ async function runRulesTechMd(options) {
     console.log(`File: ${result.filePath}`);
     console.log(`Root scanned: ${toPosixPath(workspaceRoot)}`);
     console.log(`Files scanned: ${snapshot.scannedFiles}`);
+    console.log(`Mode: ${compact ? "compact" : "full"}`);
     if (dryRun) {
       console.log("\nDry-run complete. Re-run without `--dry-run` to apply changes.");
     }
@@ -5791,6 +6179,22 @@ withWorkflowBaseOptions(
     .option("-y, --yes", "skip interactive confirmation")
 ).action(runWorkflowRemove);
 
+withWorkflowBaseOptions(
+  workflowsCommand
+    .command("prune-skills")
+    .description("Prune nested duplicates and out-of-profile installed skills")
+    .option("-b, --bundle <bundle>", "bundle id (default: agent-environment-setup)")
+    .option(
+      "--skill-profile <profile>",
+      "skill prune profile: core|web-backend|full (default: core)",
+      DEFAULT_SKILL_PROFILE
+    )
+    .option("--include-mcp", "include MCP catalog skills in desired profile set")
+    .option("--all-skills", "alias for --skill-profile full --include-mcp")
+    .option("--dry-run", "preview prune operations without deleting files")
+    .option("-y, --yes", "skip interactive confirmation")
+).action(runWorkflowPruneSkills);
+
 withWorkflowBaseOptions(
   workflowsCommand
     .command("sync-rules")
@@ -5857,6 +6261,25 @@ withWorkflowBaseOptions(
   await runWorkflowRemove(target, options);
 });
 
+withWorkflowBaseOptions(
+  skillsCommand
+    .command("prune-skills")
+    .description("Alias for workflows prune-skills")
+    .option("-b, --bundle <bundle>", "bundle id (default: agent-environment-setup)")
+    .option(
+      "--skill-profile <profile>",
+      "skill prune profile: core|web-backend|full (default: core)",
+      DEFAULT_SKILL_PROFILE
+    )
+    .option("--include-mcp", "include MCP catalog skills in desired profile set")
+    .option("--all-skills", "alias for --skill-profile full --include-mcp")
+    .option("--dry-run", "preview prune operations without deleting files")
+    .option("-y, --yes", "skip interactive confirmation")
+).action(async (options) => {
+  printSkillsDeprecation();
+  await runWorkflowPruneSkills(options);
+});
+
 withWorkflowBaseOptions(
   skillsCommand
     .command("sync-rules")
@@ -5920,6 +6343,7 @@ rulesCommand
   .description("Scan the codebase and generate/update TECH.md")
   .option("--output <path>", "output path (default: <workspace-root>/TECH.md)")
   .option("--overwrite", "overwrite existing TECH.md")
+  .option("--compact", "generate compact TECH.md (stack + context budget only)")
   .option("--dry-run", "preview generation without writing files")
   .action(runRulesTechMd);
 

package/mcp/README.md

@@ -0,0 +1,17 @@
+# MCP Skill Catalog
+
+This directory contains MCP-focused skills and powers separated from workflow-first skills.
+
+## Layout
+
+- `mcp/skills/<skill-id>/...`: canonical MCP skills
+- `mcp/powers/<skill-id>/...`: canonical MCP powers
+- `mcp/catalogs/default.json`: default MCP profile used by `--include-mcp`
+
+## Install Behavior
+
+- `cbx workflows install` defaults to workflow profile `core` (no MCP skills).
+- Add `--include-mcp` to append MCP skills from `mcp/catalogs/default.json`.
+- Use `--all-skills` to install workflow full profile + MCP skills.
+
+Legacy wrappers remain in `workflows/skills/*` and `workflows/powers/*` for compatibility.