@cubis/foundry 0.3.31 → 0.3.33

package/bin/cubis.js

@@ -61,12 +61,23 @@ const WORKFLOW_PROFILES = {
       workflowDirs: [".agent/workflows"],
       agentDirs: [".agent/agents"],
       skillDirs: [".agent/skills"],
+      commandDirs: [".gemini/commands"],
       ruleFilesByPriority: [".agent/rules/GEMINI.md"]
     },
     global: {
-      workflowDirs: ["~/.gemini/antigravity/workflows"],
-      agentDirs: ["~/.gemini/antigravity/agents"],
-      skillDirs: ["~/.gemini/antigravity/skills"],
+      workflowDirs: [
+        "~/.gemini/antigravity/workflows",
+        "~/.gemini/antigravity/global_workflows"
+      ],
+      agentDirs: [
+        "~/.gemini/antigravity/agents",
+        "~/.gemini/antigravity/global_agents"
+      ],
+      skillDirs: [
+        "~/.gemini/antigravity/skills",
+        "~/.gemini/antigravity/global_skills"
+      ],
+      commandDirs: ["~/.gemini/commands"],
       ruleFilesByPriority: ["~/.gemini/GEMINI.md"]
     },
     detectorPaths: [".agent", ".agent/workflows", ".agent/rules/GEMINI.md"],
@@ -101,12 +112,14 @@ const WORKFLOW_PROFILES = {
       workflowDirs: [".github/copilot/workflows"],
       agentDirs: [".github/agents"],
       skillDirs: [".github/skills"],
+      promptDirs: [".github/prompts"],
       ruleFilesByPriority: ["AGENTS.md", ".github/copilot-instructions.md"]
     },
     global: {
       workflowDirs: ["~/.copilot/workflows"],
       agentDirs: ["~/.copilot/agents"],
       skillDirs: ["~/.copilot/skills"],
+      promptDirs: ["~/.copilot/prompts"],
       ruleFilesByPriority: ["~/.copilot/copilot-instructions.md"]
     },
     detectorPaths: [
@@ -236,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];
@@ -274,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();
@@ -295,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();
@@ -1131,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,
@@ -1145,7 +1221,8 @@ async function collectTechSnapshot(rootDir) {
       go: toSortedArray(goModules),
       python: toSortedArray(pythonPackages),
       rust: toSortedArray(rustCrates)
-    }
+    },
+    mcpSignals: toSortedArray(mcpSignals)
   };
 }
 
@@ -1165,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");
@@ -1194,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");
@@ -1359,7 +1515,9 @@ async function recordBundleInstallState({ scope, platform, bundleId, artifacts,
     installedAt: new Date().toISOString(),
     workflows: artifacts.workflows.map(toPosixPath),
     agents: artifacts.agents.map(toPosixPath),
-    skills: artifacts.skills.map(toPosixPath)
+    skills: artifacts.skills.map(toPosixPath),
+    commands: (artifacts.commands || []).map(toPosixPath),
+    prompts: (artifacts.prompts || []).map(toPosixPath)
   };
 
   await writeState(scope, state, cwd);
@@ -1381,11 +1539,27 @@ async function resolveProfilePaths(profileId, scope, cwd = process.cwd()) {
   const profile = WORKFLOW_PROFILES[profileId];
   if (!profile) throw new Error(`Unknown platform '${profileId}'.`);
   const cfg = profile[scope];
+  const workflowDirs = Array.isArray(cfg.workflowDirs) ? cfg.workflowDirs : [];
+  const agentDirs = Array.isArray(cfg.agentDirs) ? cfg.agentDirs : [];
+  const skillDirs = Array.isArray(cfg.skillDirs) ? cfg.skillDirs : [];
+  const commandDirs = Array.isArray(cfg.commandDirs) ? cfg.commandDirs : [];
+  const promptDirs = Array.isArray(cfg.promptDirs) ? cfg.promptDirs : [];
+
+  const resolvePreferredDir = async (dirs) => {
+    if (dirs.length === 0) return null;
+    const expanded = dirs.map((dirPath) => expandPath(dirPath, cwd));
+    for (const candidate of expanded) {
+      if (await pathExists(candidate)) return candidate;
+    }
+    return expanded[0];
+  };
 
   return {
-    workflowsDir: expandPath(cfg.workflowDirs[0], cwd),
-    agentsDir: expandPath(cfg.agentDirs[0], cwd),
-    skillsDir: expandPath(cfg.skillDirs[0], cwd),
+    workflowsDir: await resolvePreferredDir(workflowDirs),
+    agentsDir: await resolvePreferredDir(agentDirs),
+    skillsDir: await resolvePreferredDir(skillDirs),
+    commandsDir: commandDirs[0] ? expandPath(commandDirs[0], cwd) : null,
+    promptsDir: promptDirs[0] ? expandPath(promptDirs[0], cwd) : null,
     ruleFilesByPriority: cfg.ruleFilesByPriority.map((filePath) => expandPath(filePath, cwd))
   };
 }
@@ -1399,7 +1573,9 @@ async function resolveArtifactProfilePaths(profileId, scope, cwd = process.cwd()
   return {
     ...scopedPaths,
     workflowsDir: workspacePaths.workflowsDir,
-    agentsDir: workspacePaths.agentsDir
+    agentsDir: workspacePaths.agentsDir,
+    commandsDir: workspacePaths.commandsDir ?? scopedPaths.commandsDir,
+    promptsDir: workspacePaths.promptsDir ?? scopedPaths.promptsDir
   };
 }
 
@@ -1456,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 [];
 
@@ -1498,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()));
@@ -3643,9 +3905,14 @@ async function findNestedSkillDirs(rootDir, depth = 0, nested = []) {
     if (!entry.isDirectory()) continue;
     const childDir = path.join(rootDir, entry.name);
     const skillFile = path.join(childDir, "SKILL.md");
-    if (depth >= 1 && (await pathExists(skillFile))) {
+
+    // Treat direct children and deeper descendants as nested skills.
+    // Once a nested skill boundary is detected, stop descending further.
+    if (depth >= 0 && (await pathExists(skillFile))) {
       nested.push(childDir);
+      continue;
     }
+
     await findNestedSkillDirs(childDir, depth + 1, nested);
   }
   return nested;
@@ -3700,6 +3967,8 @@ async function installBundleArtifacts({
   overwrite,
   profilePathsOverride = null,
   extraSkillIds = [],
+  skillProfile = DEFAULT_SKILL_PROFILE,
+  includeMcp = false,
   terminalVerifierSelection = null,
   dryRun = false,
   cwd = process.cwd()
@@ -3717,6 +3986,12 @@ async function installBundleArtifacts({
     if (platformInstallsCustomAgents(platform)) {
       await mkdir(profilePaths.agentsDir, { recursive: true });
     }
+    if (profilePaths.commandsDir && Array.isArray(platformSpec.commands) && platformSpec.commands.length > 0) {
+      await mkdir(profilePaths.commandsDir, { recursive: true });
+    }
+    if (profilePaths.promptsDir && Array.isArray(platformSpec.prompts) && platformSpec.prompts.length > 0) {
+      await mkdir(profilePaths.promptsDir, { recursive: true });
+    }
   }
 
   const bundleRoot = path.join(agentAssetsRoot(), "workflows", bundleId);
@@ -3724,7 +3999,7 @@ async function installBundleArtifacts({
 
   const installed = [];
   const skipped = [];
-  const artifacts = { workflows: [], agents: [], skills: [] };
+  const artifacts = { workflows: [], agents: [], skills: [], commands: [], prompts: [] };
 
   const workflowFiles = Array.isArray(platformSpec.workflows) ? platformSpec.workflows : [];
   for (const workflowFile of workflowFiles) {
@@ -3760,16 +4035,52 @@ async function installBundleArtifacts({
     else installed.push(destination);
   }
 
+  const commandFiles = Array.isArray(platformSpec.commands) ? platformSpec.commands : [];
+  for (const commandFile of commandFiles) {
+    if (!profilePaths.commandsDir) continue;
+    const source = path.join(platformRoot, "commands", commandFile);
+    const destination = path.join(profilePaths.commandsDir, path.basename(commandFile));
+
+    if (!(await pathExists(source))) {
+      throw new Error(`Missing command source file: ${source}`);
+    }
+
+    const result = await copyArtifact({ source, destination, overwrite, dryRun });
+    artifacts.commands.push(destination);
+    if (result.action === "skipped" || result.action === "would-skip") skipped.push(destination);
+    else installed.push(destination);
+  }
+
+  const promptFiles = Array.isArray(platformSpec.prompts) ? platformSpec.prompts : [];
+  for (const promptFile of promptFiles) {
+    if (!profilePaths.promptsDir) continue;
+    const source = path.join(platformRoot, "prompts", promptFile);
+    const destination = path.join(profilePaths.promptsDir, path.basename(promptFile));
+
+    if (!(await pathExists(source))) {
+      throw new Error(`Missing prompt source file: ${source}`);
+    }
+
+    const result = await copyArtifact({ source, destination, overwrite, dryRun });
+    artifacts.prompts.push(destination);
+    if (result.action === "skipped" || result.action === "would-skip") skipped.push(destination);
+    else installed.push(destination);
+  }
+
   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 });
@@ -3779,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 });
@@ -3969,6 +4280,18 @@ async function removeBundleArtifacts({
     if (await safeRemove(destination, dryRun)) removed.push(destination);
   }
 
+  for (const commandFile of platformSpec.commands || []) {
+    if (!profilePaths.commandsDir) continue;
+    const destination = path.join(profilePaths.commandsDir, path.basename(commandFile));
+    if (await safeRemove(destination, dryRun)) removed.push(destination);
+  }
+
+  for (const promptFile of platformSpec.prompts || []) {
+    if (!profilePaths.promptsDir) continue;
+    const destination = path.join(profilePaths.promptsDir, path.basename(promptFile));
+    if (await safeRemove(destination, dryRun)) removed.push(destination);
+  }
+
   const skillIds = await resolveInstallSkillIds({ platformSpec, extraSkillIds: [] });
   for (const skillId of skillIds) {
     const destination = path.join(profilePaths.skillsDir, skillId);
@@ -3997,14 +4320,26 @@ function printPlatforms() {
       `  project agents:    ${agentsEnabled ? profile.project.agentDirs[0] : "(disabled for this platform)"}`
     );
     console.log(`  project skills:    ${profile.project.skillDirs[0]}`);
+    if (Array.isArray(profile.project.commandDirs) && profile.project.commandDirs.length > 0) {
+      console.log(`  project commands:  ${profile.project.commandDirs[0]}`);
+    }
+    if (Array.isArray(profile.project.promptDirs) && profile.project.promptDirs.length > 0) {
+      console.log(`  project prompts:   ${profile.project.promptDirs[0]}`);
+    }
     console.log(`  project rules:     ${profile.project.ruleFilesByPriority.join(" | ")}`);
     console.log(`  global workflows:  ${profile.global.workflowDirs[0]}`);
     console.log(
       `  global agents:     ${agentsEnabled ? profile.global.agentDirs[0] : "(disabled for this platform)"}`
     );
     console.log(`  global skills:     ${profile.global.skillDirs[0]}`);
+    if (Array.isArray(profile.global.commandDirs) && profile.global.commandDirs.length > 0) {
+      console.log(`  global commands:   ${profile.global.commandDirs[0]}`);
+    }
+    if (Array.isArray(profile.global.promptDirs) && profile.global.promptDirs.length > 0) {
+      console.log(`  global prompts:    ${profile.global.promptDirs[0]}`);
+    }
     console.log(`  global rules:      ${profile.global.ruleFilesByPriority.join(" | ")}`);
-    console.log("  default install:   workflows/agents -> project, skills -> global");
+    console.log("  default install:   workflows/agents/commands/prompts -> project, skills -> global");
   }
 }
 
@@ -4225,6 +4560,16 @@ async function createDoctorReport({ platform, scope, cwd = process.cwd() }) {
     skills: {
       path: artifactPaths.skillsDir,
       exists: await pathExists(artifactPaths.skillsDir)
+    },
+    commands: {
+      path: artifactPaths.commandsDir,
+      enabled: Boolean(artifactPaths.commandsDir),
+      exists: artifactPaths.commandsDir ? await pathExists(artifactPaths.commandsDir) : null
+    },
+    prompts: {
+      path: artifactPaths.promptsDir,
+      enabled: Boolean(artifactPaths.promptsDir),
+      exists: artifactPaths.promptsDir ? await pathExists(artifactPaths.promptsDir) : null
     }
   };
 
@@ -4306,9 +4651,11 @@ async function createDoctorReport({ platform, scope, cwd = process.cwd() }) {
   if (
     !pathStatus.workflows.exists &&
     !pathStatus.skills.exists &&
-    !(pathStatus.agents.enabled && pathStatus.agents.exists)
+    !(pathStatus.agents.enabled && pathStatus.agents.exists) &&
+    !(pathStatus.commands.enabled && pathStatus.commands.exists) &&
+    !(pathStatus.prompts.enabled && pathStatus.prompts.exists)
   ) {
-    recommendations.push("No workflow/agent/skill directories found in this scope.");
+    recommendations.push("No workflow/agent/skill/command/prompt directories found in this scope.");
   }
 
   if (platform === "codex" && scope === "project") {
@@ -4369,6 +4716,20 @@ async function createDoctorReport({ platform, scope, cwd = process.cwd() }) {
     );
   }
 
+  if (platform === "antigravity" && pathStatus.workflows.exists && pathStatus.commands.enabled && !pathStatus.commands.exists) {
+    warnings.push("Antigravity workflows are present but .gemini/commands is missing.");
+    recommendations.push(
+      `Reinstall to generate command files: cbx workflows install --platform antigravity --bundle agent-environment-setup --scope ${scope} --overwrite`
+    );
+  }
+
+  if (platform === "copilot" && pathStatus.workflows.exists && pathStatus.prompts.enabled && !pathStatus.prompts.exists) {
+    warnings.push("Copilot workflows are present but prompts directory is missing.");
+    recommendations.push(
+      `Reinstall to generate prompt files: cbx workflows install --platform copilot --bundle agent-environment-setup --scope ${scope} --overwrite`
+    );
+  }
+
   if (platform === "copilot" && pathStatus.skills.exists) {
     const findings = await validateCopilotSkillsSchema(artifactPaths.skillsDir);
     if (findings.length > 0) {
@@ -4434,6 +4795,16 @@ function printDoctorReport(report) {
     console.log(`- Agents: ${report.paths.agents.path} : ${report.paths.agents.exists ? "exists" : "missing"}`);
   }
   console.log(`- Skills: ${report.paths.skills.path} : ${report.paths.skills.exists ? "exists" : "missing"}`);
+  if (report.paths.commands.enabled === false) {
+    console.log(`- Commands: (disabled)`);
+  } else {
+    console.log(`- Commands: ${report.paths.commands.path} : ${report.paths.commands.exists ? "exists" : "missing"}`);
+  }
+  if (report.paths.prompts.enabled === false) {
+    console.log(`- Prompts: (disabled)`);
+  } else {
+    console.log(`- Prompts: ${report.paths.prompts.path} : ${report.paths.prompts.exists ? "exists" : "missing"}`);
+  }
 
   console.log("\nManaged block:");
   console.log(`- Status: ${report.managedBlockStatus}`);
@@ -4502,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");
 }
@@ -4713,6 +5091,7 @@ async function runWorkflowInstall(options) {
       options,
       cwd
     });
+    const skillInstallOptions = resolveWorkflowSkillInstallOptions(options);
 
     const installResult = await installBundleArtifacts({
       bundleId,
@@ -4722,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
@@ -4834,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) {
@@ -5601,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`,
@@ -5617,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.");
     }
@@ -5655,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")
@@ -5721,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")
@@ -5784,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);