@cubis/foundry 0.3.32 → 0.3.33

package/workflows/scripts/generate-powers.mjs

@@ -2,22 +2,10 @@
 /**
  * generate-powers.mjs
  *
- * Generates POWER.md files for Kiro from the canonical SKILL.md files in the
- * skills/ directory. Powers are Kiro-specific wrappers around skills; the
- * install source of truth for `cbx install` is ALWAYS `skills/<id>/SKILL.md`.
- *
- * Source priority (matching cubis.js installBundleArtifacts):
- *   1. skills/<name>/SKILL.md  ← canonical (what `cbx install` uses)
- *   2. powers/<name>/SKILL.md  ← fallback (local override only)
- *
- * Usage:
- *   node "workflows/scripts/generate-powers.mjs" [--dry-run] [--force] [--from-skills] [--sync-skills]
- *
- * Options:
- *   --dry-run      Preview changes without writing files
- *   --force        Overwrite existing POWER.md files
- *   --from-skills  Also create missing power directories from skills/
- *   --sync-skills  Sync canonical SKILL.md from skills/ → powers/ for every power
+ * Generates POWER.md files for Kiro from canonical SKILL.md files.
+ * Supports both workflow and MCP catalogs:
+ * - workflows/skills -> workflows/powers
+ * - mcp/skills -> mcp/powers
  */
 
 import path from "node:path";
@@ -27,9 +15,19 @@ import { promises as fs } from "node:fs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, "..", "..");
-const ASSETS_ROOT = path.join(ROOT, "workflows");
-const POWERS_ROOT = path.join(ASSETS_ROOT, "powers");
-const SKILLS_ROOT = path.join(ASSETS_ROOT, "skills");
+
+const ROOT_PAIRS = [
+  {
+    label: "workflows",
+    skillsRoot: path.join(ROOT, "workflows", "skills"),
+    powersRoot: path.join(ROOT, "workflows", "powers")
+  },
+  {
+    label: "mcp",
+    skillsRoot: path.join(ROOT, "mcp", "skills"),
+    powersRoot: path.join(ROOT, "mcp", "powers")
+  }
+];
 
 const ARGS = new Set(process.argv.slice(2));
 const DRY_RUN = ARGS.has("--dry-run");
@@ -37,14 +35,10 @@ const FORCE = ARGS.has("--force");
 const FROM_SKILLS = ARGS.has("--from-skills");
 const SYNC_SKILLS = ARGS.has("--sync-skills");
 
-// ─── Kiro POWER.md frontmatter keys ────────────────────────────────────────
-// Keys added/ensured for Kiro power format
 const KIRO_REQUIRED_KEYS = {
-  inclusion: "manual",
+  inclusion: "manual"
 };
 
-// ─── Helpers ────────────────────────────────────────────────────────────────
-
 async function pathExists(p) {
   try {
     await fs.stat(p);
@@ -79,110 +73,72 @@ async function copyDir(src, dest) {
   }
 }
 
-/**
- * Strip an outer code fence wrapper from file content.
- * Handles both:
- *   ```skill        (backtick × 3)
- *   ````skill       (backtick × 4)
- * Returns the raw inner content (the markdown string inside the fence),
- * or the original content unchanged if no fence is found.
- */
 function stripCodeFence(content) {
   const trimmed = content.trim();
-  // Match opening fence: 3+ backticks followed by optional language identifier
   const fenceMatch = trimmed.match(/^(`{3,})([a-zA-Z]*)\n([\s\S]*)\n\1\s*$/);
   if (!fenceMatch) return trimmed;
   return fenceMatch[3];
 }
 
-/**
- * Parse YAML frontmatter block from raw markdown.
- * Returns { frontmatterRaw, body } or null if no frontmatter found.
- */
 function parseFrontmatter(markdown) {
   const match = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
   if (!match) return null;
   return {
     frontmatterRaw: match[1],
-    body: match[2],
+    body: match[2]
   };
 }
 
-/**
- * Inject Kiro-specific keys into a raw frontmatter string if they are absent.
- * Returns updated frontmatter string.
- */
 function injectKiroKeys(frontmatterRaw) {
   let result = frontmatterRaw;
   for (const [key, value] of Object.entries(KIRO_REQUIRED_KEYS)) {
     const keyPresent = new RegExp(`^${key}\\s*:`, "m").test(result);
     if (!keyPresent) {
-      // Prepend the key at the top of the frontmatter block
       result = `${key}: ${value}\n${result}`;
     }
   }
   return result;
 }
 
-/**
- * Build POWER.md content from a SKILL.md source string.
- * - Strips outer `skill` / ````skill fence if present
- * - Parses frontmatter and injects Kiro keys
- * - Re-wraps in a `markdown` code fence (matching the existing POWER.md convention)
- */
 function buildPowerContent(skillMdContent) {
-  // 1. Strip outer code fence (the ````skill ... ```` wrapper)
   const inner = stripCodeFence(skillMdContent);
-
-  // 2. Parse and update frontmatter
   const parsed = parseFrontmatter(inner);
   if (!parsed) {
-    // No frontmatter found – just re-wrap with markdown fence and return
     return `\`\`\`\`markdown\n${inner}\n\`\`\`\`\n`;
   }
 
   const updatedFrontmatter = injectKiroKeys(parsed.frontmatterRaw);
   const reconstructed = `---\n${updatedFrontmatter}\n---\n${parsed.body}`;
-
-  // 3. Wrap in markdown code fence for Kiro power format
   return `\`\`\`\`markdown\n${reconstructed}\n\`\`\`\`\n`;
 }
 
-// ─── Core logic ─────────────────────────────────────────────────────────────
-
 async function getSubdirectories(dir) {
-  try {
-    const entries = await fs.readdir(dir, { withFileTypes: true });
-    return entries
-      .filter((e) => e.isDirectory() && !e.name.startsWith("."))
-      .map((e) => e.name);
-  } catch {
-    return [];
-  }
+  if (!(await pathExists(dir))) return [];
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  return entries
+    .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+    .map((e) => e.name)
+    .sort((a, b) => a.localeCompare(b));
 }
 
-async function processPowerDir(powerName) {
-  const powerDir = path.join(POWERS_ROOT, powerName);
+async function processPowerDir(pair, powerName) {
+  const powerDir = path.join(pair.powersRoot, powerName);
   const powerMdPath = path.join(powerDir, "POWER.md");
 
-  // Source priority mirrors cubis.js installBundleArtifacts (line ~2097):
-  //   skills/<name>/SKILL.md  ← canonical; what `cbx install` copies to the platform
-  //   powers/<name>/SKILL.md  ← local fallback only (may be a stale copy)
-  // Using skills/ as primary ensures POWER.md is generated from the same
-  // content that users receive when they run `cbx install`.
-  const canonicalSkill = path.join(SKILLS_ROOT, powerName, "SKILL.md");
+  const canonicalSkill = path.join(pair.skillsRoot, powerName, "SKILL.md");
   const localSkill = path.join(powerDir, "SKILL.md");
 
   let skillSource;
   if (await pathExists(canonicalSkill)) {
     skillSource = canonicalSkill;
   } else if (await pathExists(localSkill)) {
-    skillSource = localSkill; // fallback: power-local override
+    skillSource = localSkill;
   } else {
     return {
       name: powerName,
       result: "skip",
       reason: "no SKILL.md found in skills/ or powers/",
+      pair: pair.label
     };
   }
 
@@ -192,45 +148,42 @@ async function processPowerDir(powerName) {
       name: powerName,
       result: "skip",
       reason: "POWER.md already exists (use --force to overwrite)",
+      pair: pair.label
     };
   }
 
   const skillContent = await readUtf8(skillSource);
   const powerContent = buildPowerContent(skillContent);
-
   await writeUtf8(powerMdPath, powerContent);
 
   return {
     name: powerName,
     result: powerExists ? "updated" : "created",
     source: path.relative(ROOT, skillSource),
+    pair: pair.label
   };
 }
 
-async function syncFromSkills() {
-  const skillDirs = await getSubdirectories(SKILLS_ROOT);
+async function syncFromSkills(pair) {
+  const skillDirs = await getSubdirectories(pair.skillsRoot);
   const created = [];
 
   for (const name of skillDirs) {
-    // Skip non-skill entries
-    if (name.startsWith(".") || name.endsWith(".json") || name.endsWith(".md"))
-      continue;
+    if (name.startsWith(".") || name.endsWith(".json") || name.endsWith(".md")) continue;
 
-    const powerDir = path.join(POWERS_ROOT, name);
-    const skillDir = path.join(SKILLS_ROOT, name);
+    const powerDir = path.join(pair.powersRoot, name);
+    const skillDir = path.join(pair.skillsRoot, name);
     const skillMdSrc = path.join(skillDir, "SKILL.md");
 
     if (!(await pathExists(skillMdSrc))) continue;
-    if (await pathExists(powerDir)) continue; // already exists
+    if (await pathExists(powerDir)) continue;
 
-    // Create power directory and copy SKILL.md
     const skillMdDest = path.join(powerDir, "SKILL.md");
     if (!DRY_RUN) {
       await fs.mkdir(powerDir, { recursive: true });
       await fs.copyFile(skillMdSrc, skillMdDest);
     }
 
-    // Copy steering/, templates/, references/ if they exist
     for (const subdir of ["steering", "templates", "references"]) {
       const srcSub = path.join(skillDir, subdir);
       const destSub = path.join(powerDir, subdir);
@@ -245,166 +198,106 @@ async function syncFromSkills() {
   return created;
 }
 
-/**
- * Sync canonical SKILL.md from skills/ → powers/ for every power directory.
- * This keeps powers/<name>/SKILL.md byte-identical to what `cbx install` will
- * deliver to users, so Kiro and cbx users always see the same skill content.
- */
-async function syncSkillsToPowers() {
-  const powerDirs = await getSubdirectories(POWERS_ROOT);
+async function syncSkillsToPowers(pair) {
+  const powerDirs = await getSubdirectories(pair.powersRoot);
   const synced = [];
   const unchanged = [];
   const missing = [];
 
   for (const name of powerDirs) {
-    const canonicalSkill = path.join(SKILLS_ROOT, name, "SKILL.md");
-    const powerSkill = path.join(POWERS_ROOT, name, "SKILL.md");
+    const canonicalSkill = path.join(pair.skillsRoot, name, "SKILL.md");
+    const powerSkill = path.join(pair.powersRoot, name, "SKILL.md");
 
     if (!(await pathExists(canonicalSkill))) {
       missing.push(name);
       continue;
     }
 
-    const canonical = await readUtf8(canonicalSkill);
-    const existing = (await pathExists(powerSkill))
-      ? await readUtf8(powerSkill)
-      : null;
+    const canonicalContent = await readUtf8(canonicalSkill);
+    const existingContent = (await pathExists(powerSkill)) ? await readUtf8(powerSkill) : null;
 
-    if (existing === canonical) {
+    if (existingContent === canonicalContent) {
       unchanged.push(name);
       continue;
     }
 
-    if (!DRY_RUN) {
-      await fs.mkdir(path.join(POWERS_ROOT, name), { recursive: true });
-      await fs.copyFile(canonicalSkill, powerSkill);
-    }
-
+    await writeUtf8(powerSkill, canonicalContent);
     synced.push(name);
   }
 
   return { synced, unchanged, missing };
 }
 
-// ─── Main ───────────────────────────────────────────────────────────────────
-
 async function main() {
-  console.log(`\nCubis Foundry — generate-powers.mjs`);
-  console.log(`Mode: ${DRY_RUN ? "DRY RUN (no files written)" : "LIVE"}`);
-  if (FORCE) console.log("Force: overwriting existing POWER.md files");
-  if (SYNC_SKILLS)
-    console.log(
-      "Sync-skills: syncing canonical SKILL.md from skills/ → powers/",
-    );
-  if (FROM_SKILLS)
-    console.log("From-skills: creating missing power dirs from skills/");
-  console.log();
-
-  // 1a. Sync canonical SKILL.md from skills/ → powers/ so powers/SKILL.md matches
-  //     what `cbx install` delivers (cubis.js always installs from skills/, not powers/).
-  if (SYNC_SKILLS) {
-    const { synced, missing } = await syncSkillsToPowers();
-    if (synced.length > 0) {
-      console.log(
-        `Synced SKILL.md for ${synced.length} power${synced.length === 1 ? "" : "s"} from skills/:`,
-      );
-      for (const name of synced) {
-        console.log(`  ↺ ${name}/SKILL.md`);
-      }
-      console.log();
-    } else {
-      console.log(
-        "All power SKILL.md files are already in sync with skills/.\n",
-      );
+  const pairResults = [];
+
+  for (const pair of ROOT_PAIRS) {
+    if (!(await pathExists(pair.skillsRoot)) && !(await pathExists(pair.powersRoot))) {
+      continue;
     }
-    if (missing.length > 0) {
-      console.log(
-        `Note: ${missing.length} power${missing.length === 1 ? "" : "s"} have no matching skills/ entry (local-only):`,
-      );
-      for (const name of missing) console.log(`  ~ ${name}`);
-      console.log();
+
+    if (FROM_SKILLS) {
+      const created = await syncFromSkills(pair);
+      if (created.length > 0) {
+        console.log(`${DRY_RUN ? "[dry-run] " : ""}Created ${created.length} missing powers from ${pair.label}/skills:`);
+        for (const name of created) {
+          console.log(`  + ${pair.label}/${name}`);
+        }
+      }
     }
-  }
 
-  // 1b. Create missing power directories from skills/
-  if (FROM_SKILLS) {
-    const created = await syncFromSkills();
-    if (created.length > 0) {
-      console.log(
-        `Created ${created.length} new power director${created.length === 1 ? "y" : "ies"} from skills/:`,
-      );
-      for (const name of created) {
-        console.log(`  + ${name}/`);
+    if (SYNC_SKILLS) {
+      const syncResult = await syncSkillsToPowers(pair);
+      if (syncResult.synced.length > 0) {
+        console.log(`${DRY_RUN ? "[dry-run] " : ""}Synced ${syncResult.synced.length} SKILL.md files from ${pair.label}/skills to ${pair.label}/powers`);
+      }
+      if (syncResult.missing.length > 0) {
+        console.log(`Skipping ${syncResult.missing.length} ${pair.label}/powers entries with no canonical ${pair.label}/skills source.`);
       }
-      console.log();
-    } else {
-      console.log("No new power directories needed from skills/.\n");
     }
-  }
 
-  // 2. Process each power directory
-  const powerDirs = await getSubdirectories(POWERS_ROOT);
-  const results = { created: [], updated: [], skipped: [], errors: [] };
+    const powerDirs = await getSubdirectories(pair.powersRoot);
+    if (powerDirs.length === 0) continue;
 
-  for (const name of powerDirs) {
-    try {
-      const result = await processPowerDir(name);
-      if (result.result === "created") results.created.push(result);
-      else if (result.result === "updated") results.updated.push(result);
-      else results.skipped.push(result);
-    } catch (err) {
-      results.errors.push({ name, error: err.message });
+    const results = [];
+    for (const powerName of powerDirs) {
+      results.push(await processPowerDir(pair, powerName));
     }
+    pairResults.push({ pair, results });
   }
 
-  // 3. Report
-  if (results.created.length > 0) {
-    console.log(
-      `Created ${results.created.length} POWER.md file${results.created.length === 1 ? "" : "s"}:`,
-    );
-    for (const r of results.created) {
-      console.log(`  ✓ ${r.name}/POWER.md  (from ${r.source})`);
-    }
-    console.log();
-  }
+  const allResults = pairResults.flatMap((item) => item.results);
+  const created = allResults.filter((r) => r.result === "created");
+  const updated = allResults.filter((r) => r.result === "updated");
+  const skipped = allResults.filter((r) => r.result === "skip");
 
-  if (results.updated.length > 0) {
-    console.log(
-      `Updated ${results.updated.length} POWER.md file${results.updated.length === 1 ? "" : "s"}:`,
-    );
-    for (const r of results.updated) {
-      console.log(`  ↺ ${r.name}/POWER.md  (from ${r.source})`);
-    }
-    console.log();
+  if (created.length === 0 && updated.length === 0 && skipped.length === 0) {
+    console.log("No powers directories found.");
+    return;
   }
 
-  if (results.skipped.length > 0) {
-    console.log(
-      `Skipped ${results.skipped.length} director${results.skipped.length === 1 ? "y" : "ies"}:`,
-    );
-    for (const r of results.skipped) {
-      console.log(`  - ${r.name}: ${r.reason}`);
-    }
-    console.log();
+  console.log("\nPOWER.md generation summary");
+  console.log(`  Created: ${created.length}`);
+  console.log(`  Updated: ${updated.length}`);
+  console.log(`  Skipped: ${skipped.length}`);
+
+  for (const result of [...created, ...updated]) {
+    console.log(`  ${result.result === "created" ? "+" : "~"} [${result.pair}] ${result.name} (${result.source})`);
   }
 
-  if (results.errors.length > 0) {
-    console.error(`Errors (${results.errors.length}):`);
-    for (const r of results.errors) {
-      console.error(`  ✗ ${r.name}: ${r.error}`);
+  if (skipped.length > 0) {
+    console.log("\nSkipped:");
+    for (const result of skipped) {
+      console.log(`  - [${result.pair}] ${result.name}: ${result.reason}`);
     }
-    console.log();
   }
 
-  const total = results.created.length + results.updated.length;
-  console.log(
-    `Done. ${total} POWER.md file${total === 1 ? "" : "s"} ${DRY_RUN ? "would be" : ""} generated.`,
-  );
-
-  if (results.errors.length > 0) process.exit(1);
+  if (DRY_RUN) {
+    console.log("\nDry-run mode: no files were written.");
+  }
 }
 
 main().catch((err) => {
-  console.error(err);
+  console.error(err?.stack || err?.message || String(err));
   process.exit(1);
 });

package/workflows/skills/atlassian-mcp/SKILL.md

@@ -1,88 +1,18 @@
 ---
-name: atlassian-mcp
-description: Use when querying Jira issues, searching Confluence pages, creating tickets, updating documentation, or integrating Atlassian tools via MCP protocol.
-license: MIT
+name: "atlassian-mcp"
+description: "Compatibility wrapper skill. Canonical MCP skill moved to mcp/skills/atlassian-mcp."
 metadata:
-  author: https://github.com/Jeffallan
-  version: "1.0.0"
-  domain: platform
-  triggers: Jira, Confluence, Atlassian, MCP, tickets, issues, wiki, JQL, CQL, sprint, backlog, project management
-  role: expert
-  scope: implementation
-  output-format: code
-  related-skills: mcp-developer, api-designer, security-reviewer
+  deprecated: true
+  replaced_by: "atlassian-mcp"
+  moved_to: "mcp/skills/atlassian-mcp/SKILL.md"
+  removal_target: "v0.6.0"
 ---
 
-# Atlassian MCP Expert
+# atlassian-mcp (Compatibility Wrapper)
 
-Senior integration specialist with deep expertise in connecting Jira, Confluence, and other Atlassian tools to AI systems via Model Context Protocol (MCP).
+This legacy workflow-path skill is kept for backward compatibility.
 
-## Role Definition
+Canonical MCP skill path:
+- mcp/skills/atlassian-mcp/SKILL.md
 
-You are an expert in Atlassian MCP integration with mastery of both official and open-source MCP servers, JQL/CQL query languages, OAuth 2.0 authentication, and production deployment patterns. You build robust workflows that automate issue triage, documentation sync, sprint planning, and cross-tool integration while respecting permissions and maintaining security.
-
-## When to Use This Skill
-
-- Querying Jira issues with JQL filters
-- Searching or creating Confluence pages
-- Automating sprint workflows and backlog management
-- Setting up MCP server authentication (OAuth/API tokens)
-- Syncing meeting notes to Jira tickets
-- Generating documentation from issue data
-- Debugging Atlassian API integration issues
-- Choosing between official vs open-source MCP servers
-
-## Core Workflow
-
-1. **Select server** - Choose official cloud, open-source, or self-hosted MCP server
-2. **Authenticate** - Configure OAuth 2.1, API tokens, or PAT credentials
-3. **Design queries** - Write JQL for Jira, CQL for Confluence, test filters
-4. **Implement workflow** - Build tool calls, handle pagination, error recovery
-5. **Deploy** - Configure IDE integration, test permissions, monitor rate limits
-
-## Reference Guide
-
-Load detailed guidance based on context:
-
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| Server Setup | `references/mcp-server-setup.md` | Installation, choosing servers, configuration |
-| Jira Operations | `references/jira-queries.md` | JQL syntax, issue CRUD, sprints, boards |
-| Confluence Ops | `references/confluence-operations.md` | CQL search, page creation, spaces, comments |
-| Authentication | `references/authentication-patterns.md` | OAuth 2.0, API tokens, permission scopes |
-| Common Workflows | `references/common-workflows.md` | Issue triage, doc sync, sprint automation |
-
-## Constraints
-
-### MUST DO
-- Respect user permissions and workspace access controls
-- Validate JQL/CQL queries before execution
-- Handle rate limits with exponential backoff
-- Use pagination for large result sets (50-100 items per page)
-- Implement error recovery for network failures
-- Log API calls for debugging and audit trails
-- Test with read-only operations first
-- Document required permission scopes
-
-### MUST NOT DO
-- Hardcode API tokens or OAuth secrets in code
-- Ignore rate limit headers from Atlassian APIs
-- Create issues without validating required fields
-- Skip input sanitization on user-provided query strings
-- Deploy without testing permission boundaries
-- Update production data without confirmation prompts
-- Mix different authentication methods in same session
-- Expose sensitive issue data in logs or error messages
-
-## Output Templates
-
-When implementing Atlassian MCP features, provide:
-1. MCP server configuration (JSON/environment vars)
-2. Query examples (JQL/CQL with explanations)
-3. Tool call implementation with error handling
-4. Authentication setup instructions
-5. Brief explanation of permission requirements
-
-## Knowledge Reference
-
-Atlassian MCP Server (official), mcp-atlassian (sooperset), atlassian-mcp (xuanxt), JQL (Jira Query Language), CQL (Confluence Query Language), OAuth 2.1, API tokens, Personal Access Tokens (PAT), Model Context Protocol, JSON-RPC 2.0, rate limiting, pagination, permission scopes, Jira REST API, Confluence REST API
+Install MCP skills with: cbx workflows install --include-mcp