@luquimbo/bi-superpowers 1.0.0 → 1.1.1

package/bin/commands/install.js

@@ -0,0 +1,321 @@
+/**
+ * Install Command - Multi-agent skill installer
+ * ===============================================
+ *
+ * Installs BI Agent Superpowers skills into the correct directories
+ * for each AI coding agent. Inspired by the `npx skills` CLI from Vercel Labs.
+ *
+ * Skills are always installed at the user level (~/) to protect licensed content.
+ *
+ * Usage:
+ *   npx @luquimbo/bi-superpowers install
+ *   super install
+ *   super install --agent claude-code --agent codex
+ *   super install --all --yes
+ *
+ * @module commands/install
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+// Agent registry: each agent's skill directory path (relative to project or home)
+// Based on the Agent Skills specification supported by 45+ agents
+const AGENTS = {
+  'claude-code': { name: 'Claude Code', dir: '.claude/skills' },
+  'github-copilot': { name: 'GitHub Copilot', dir: '.github/skills' },
+  codex: { name: 'Codex (OpenAI)', dir: '.agents/skills' },
+  cursor: { name: 'Cursor', dir: '.cursor/skills' },
+  windsurf: { name: 'Windsurf', dir: '.windsurf/skills' },
+  cline: { name: 'Cline', dir: '.cline/skills' },
+  continue: { name: 'Continue', dir: '.continue/skills' },
+  'roo-code': { name: 'Roo Code', dir: '.roo/skills' },
+  augment: { name: 'Augment', dir: '.augment/skills' },
+  amp: { name: 'Amp', dir: '.amp/skills' },
+  kilo: { name: 'Kilo Code', dir: '.kilocode/skills' },
+  opencode: { name: 'OpenCode', dir: '.agents/skills' },
+  openhands: { name: 'OpenHands', dir: '.openhands/skills' },
+  goose: { name: 'Goose', dir: '.goose/skills' },
+  'gemini-cli': { name: 'Gemini CLI', dir: '.gemini/skills' },
+};
+
+// Universal path — most agents read from .agents/skills/
+const UNIVERSAL_DIR = '.agents/skills';
+
+/**
+ * Detect which agents are available by checking for their config directories
+ * @param {string} baseDir - Directory to check (project root or home)
+ * @returns {string[]} Array of detected agent IDs
+ */
+function detectAgents(baseDir) {
+  const detected = [];
+  for (const [id, agent] of Object.entries(AGENTS)) {
+    const agentRoot = path.dirname(agent.dir);
+    const checkPath = path.join(baseDir, agentRoot);
+    if (fs.existsSync(checkPath)) {
+      detected.push(id);
+    }
+  }
+  return detected;
+}
+
+/**
+ * Create readline interface for interactive prompts
+ */
+function createReadline() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+/**
+ * Prompt user with a question
+ */
+function prompt(rl, question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => resolve(answer.trim()));
+  });
+}
+
+/**
+ * Display a numbered list and let user pick multiple items
+ * @param {readline.Interface} rl
+ * @param {Array<{id: string, name: string}>} items
+ * @param {string[]} preselected - IDs to preselect
+ * @returns {Promise<string[]>} Selected IDs
+ */
+async function selectMultiple(rl, items, preselected = []) {
+  items.forEach((item, i) => {
+    const marker = preselected.includes(item.id) ? '●' : '○';
+    console.log(`  ${i + 1}) ${marker} ${item.name}`);
+  });
+  console.log();
+  console.log('  Enter numbers separated by commas (e.g. 1,2,3)');
+  console.log('  Press Enter for detected agents, or "a" for all');
+
+  const answer = await prompt(rl, '\n  > ');
+
+  if (answer.toLowerCase() === 'a') {
+    return items.map((item) => item.id);
+  }
+
+  if (answer === '') {
+    return preselected.length > 0 ? preselected : items.map((item) => item.id);
+  }
+
+  const indices = answer
+    .split(',')
+    .map((s) => parseInt(s.trim(), 10) - 1)
+    .filter((i) => i >= 0 && i < items.length);
+
+  return indices.map((i) => items[i].id);
+}
+
+/**
+ * Copy a skill directory to a target location
+ * @param {string} srcDir - Source skill directory (containing SKILL.md)
+ * @param {string} destDir - Destination directory
+ */
+function copySkillDir(srcDir, destDir) {
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copySkillDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Main install command handler
+ * @param {string[]} args - CLI arguments
+ * @param {Object} config - Command config from CLI
+ */
+async function installCommand(args, config) {
+  const chalk = require('chalk');
+  const boxen = require('boxen');
+
+  const isYes = args.includes('--yes') || args.includes('-y');
+  const isAll = args.includes('--all');
+  const agentFlags = [];
+
+  // Parse --agent flags
+  for (let i = 0; i < args.length; i++) {
+    if ((args[i] === '--agent' || args[i] === '-a') && args[i + 1]) {
+      agentFlags.push(args[i + 1]);
+      i++;
+    }
+  }
+
+  // Always install at user level (home directory) to protect licensed content
+  const baseDir = os.homedir();
+
+  // Find skills from the package
+  const packageDir = config.packageDir || path.dirname(__dirname);
+  const skillsSourceDir = path.join(packageDir, 'skills');
+
+  if (!fs.existsSync(skillsSourceDir)) {
+    console.error(chalk.red('Skills directory not found. Try reinstalling the package.'));
+    process.exit(1);
+  }
+
+  // Read available skills
+  const skillDirs = fs
+    .readdirSync(skillsSourceDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && fs.existsSync(path.join(skillsSourceDir, d.name, 'SKILL.md')))
+    .map((d) => d.name);
+
+  // Header
+  console.log(
+    boxen(
+      chalk.bold.cyan('BI Agent Superpowers') +
+        chalk.gray(` v${config.version}`) +
+        '\n' +
+        chalk.gray('Multi-agent skill installer'),
+      {
+        padding: 1,
+        borderStyle: 'round',
+        borderColor: 'cyan',
+      }
+    )
+  );
+
+  console.log(chalk.gray(`  Install path: ~/${UNIVERSAL_DIR}/`));
+  console.log(chalk.gray(`  Skills: ${skillDirs.length} available\n`));
+
+  // Determine which agents to install for
+  let selectedAgents;
+
+  if (isAll) {
+    selectedAgents = Object.keys(AGENTS);
+  } else if (agentFlags.length > 0) {
+    selectedAgents = agentFlags.filter((a) => AGENTS[a]);
+    const unknown = agentFlags.filter((a) => !AGENTS[a]);
+    if (unknown.length > 0) {
+      console.log(chalk.yellow(`  Unknown agents: ${unknown.join(', ')}`));
+      console.log(chalk.gray(`  Available: ${Object.keys(AGENTS).join(', ')}\n`));
+    }
+  } else if (isYes) {
+    selectedAgents = Object.keys(AGENTS);
+  } else {
+    // Interactive mode: detect and ask
+    const detected = detectAgents(baseDir);
+
+    console.log(chalk.cyan('  Select agents to install for:\n'));
+
+    const items = Object.entries(AGENTS).map(([id, agent]) => ({
+      id,
+      name: detected.includes(id) ? `${agent.name} ${chalk.green('(detected)')}` : agent.name,
+    }));
+
+    const rl = createReadline();
+    try {
+      selectedAgents = await selectMultiple(rl, items, detected);
+    } finally {
+      rl.close();
+    }
+  }
+
+  if (selectedAgents.length === 0) {
+    console.log(chalk.yellow('\n  No agents selected. Nothing to install.'));
+    return;
+  }
+
+  console.log(
+    chalk.cyan(`\n  Installing ${skillDirs.length} skills for ${selectedAgents.length} agents...\n`)
+  );
+
+  // Always install to universal path first
+  const universalTarget = path.join(baseDir, UNIVERSAL_DIR);
+  let installedCount = 0;
+
+  for (const skill of skillDirs) {
+    const src = path.join(skillsSourceDir, skill);
+    const dest = path.join(universalTarget, skill);
+    copySkillDir(src, dest);
+    installedCount++;
+  }
+  console.log(chalk.green(`  ✓ ${UNIVERSAL_DIR}/ (${installedCount} skills)`));
+
+  // Symlink agent-specific directories to universal path
+  const agentResults = [];
+  for (const agentId of selectedAgents) {
+    const agent = AGENTS[agentId];
+    if (agent.dir === UNIVERSAL_DIR) continue; // Already handled
+
+    const agentTarget = path.join(baseDir, agent.dir);
+
+    // If the directory already exists and is not a symlink, copy instead
+    if (fs.existsSync(agentTarget) && !fs.lstatSync(agentTarget).isSymbolicLink()) {
+      // Copy skills into existing directory
+      for (const skill of skillDirs) {
+        copySkillDir(path.join(skillsSourceDir, skill), path.join(agentTarget, skill));
+      }
+      agentResults.push({ agent: agent.name, method: 'copied', dir: agent.dir });
+    } else {
+      // Create symlink to universal directory
+      const parentDir = path.dirname(agentTarget);
+      if (!fs.existsSync(parentDir)) {
+        fs.mkdirSync(parentDir, { recursive: true });
+      }
+
+      // Remove existing symlink if present
+      if (fs.existsSync(agentTarget)) {
+        fs.unlinkSync(agentTarget);
+      }
+
+      try {
+        // Relative symlink from agent dir to universal dir
+        const relPath = path.relative(parentDir, universalTarget);
+        fs.symlinkSync(relPath, agentTarget);
+        agentResults.push({ agent: agent.name, method: 'symlinked', dir: agent.dir });
+      } catch (_e) {
+        // Fallback to copy if symlink fails (e.g. Windows without admin)
+        if (!fs.existsSync(agentTarget)) {
+          fs.mkdirSync(agentTarget, { recursive: true });
+        }
+        for (const skill of skillDirs) {
+          copySkillDir(path.join(skillsSourceDir, skill), path.join(agentTarget, skill));
+        }
+        agentResults.push({ agent: agent.name, method: 'copied', dir: agent.dir });
+      }
+    }
+  }
+
+  // Print results
+  for (const result of agentResults) {
+    const icon = result.method === 'symlinked' ? '→' : '✓';
+    console.log(chalk.green(`  ${icon} ${result.dir}/ (${result.method}) — ${result.agent}`));
+  }
+
+  // Summary
+  const totalAgents = agentResults.length + 1; // +1 for universal
+  console.log(
+    boxen(
+      chalk.green.bold(`Installed ${installedCount} skills for ${totalAgents} agents`) +
+        '\n\n' +
+        chalk.gray('Skills are ready to use. Open your AI agent and start prompting.') +
+        '\n' +
+        chalk.gray('Example: "Help me write a DAX measure for YTD sales"'),
+      {
+        padding: 1,
+        margin: { top: 1 },
+        borderStyle: 'round',
+        borderColor: 'green',
+      }
+    )
+  );
+}
+
+module.exports = installCommand;

package/bin/lib/microsoft-mcp.js

@@ -13,9 +13,11 @@ const path = require('path');
 
 const REMOTE_POWERBI_URL = 'https://api.fabric.microsoft.com/v1/mcp/powerbi';
 const FABRIC_MCP_PACKAGE = '@microsoft/fabric-mcp@latest';
+const MICROSOFT_LEARN_URL = 'https://learn.microsoft.com/api/mcp';
 const MODELING_SERVER_NAME = 'powerbi-modeling-mcp';
 const REMOTE_SERVER_NAME = 'powerbi-remote';
 const FABRIC_SERVER_NAME = 'fabric-mcp-server';
+const LEARN_SERVER_NAME = 'microsoft-learn';
 const ABSOLUTE_LAUNCHER_MODE = 'absolute';
 const PLUGIN_ROOT_LAUNCHER_MODE = 'plugin-root';
 
@@ -63,6 +65,10 @@ function createPluginMcpConfig(options = {}) {
       command: 'node',
       args: [launcherPath],
     },
+    [LEARN_SERVER_NAME]: {
+      type: 'http',
+      url: MICROSOFT_LEARN_URL,
+    },
   };
 }
 
@@ -166,9 +172,11 @@ module.exports = {
   PLUGIN_ROOT_LAUNCHER_MODE,
   REMOTE_POWERBI_URL,
   FABRIC_MCP_PACKAGE,
+  MICROSOFT_LEARN_URL,
   MODELING_SERVER_NAME,
   REMOTE_SERVER_NAME,
   FABRIC_SERVER_NAME,
+  LEARN_SERVER_NAME,
   resolveModelingLauncherPath,
   createPluginMcpConfig,
   createMcpConfigForFormat,

package/bin/lib/microsoft-mcp.test.js

@@ -11,6 +11,7 @@ const {
   PLUGIN_ROOT_LAUNCHER_MODE,
   REMOTE_POWERBI_URL,
   FABRIC_MCP_PACKAGE,
+  MICROSOFT_LEARN_URL,
   createPluginMcpConfig,
   createMcpConfigForFormat,
   mergeMcpConfig,
@@ -58,6 +59,10 @@ describe('createPluginMcpConfig', () => {
     assert.strictEqual(config['powerbi-modeling-mcp'].type, 'stdio');
     assert.strictEqual(config['powerbi-modeling-mcp'].command, 'node');
     assert.ok(config['powerbi-modeling-mcp'].args[0].endsWith('powerbi-modeling-launcher.js'));
+    assert.deepStrictEqual(config['microsoft-learn'], {
+      type: 'http',
+      url: MICROSOFT_LEARN_URL,
+    });
   });
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luquimbo/bi-superpowers",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Plugin-first Claude Code toolkit for Power BI, Microsoft Fabric, and Excel workflows powered by official Microsoft MCP servers.",
   "main": "bin/cli.js",
   "bin": {

package/skills/contributions/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "contributions"
 description: "Contributions Validation Skill: Contribution validation."
-version: "1.0.0"
+version: "1.1.1"
 ---
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/contributions.md instead. -->

package/skills/data-model-design/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "data-model-design"
 description: "Use when the user asks about Data Model Design Skill, especially phrases like \"diseñar modelo de datos\", \"crear modelo Power BI\", \"arquitectura de datos\", \"empezar proyecto BI\", \"nuevo modelo semántico\"."
-version: "1.0.0"
+version: "1.1.1"
 ---
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/data-model-design.md instead. -->

package/skills/data-modeling/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "data-modeling"
 description: "Use when the user asks about Data Modeling Skill, especially phrases like \"data model\", \"star schema\", \"fact table\", \"relationship\", \"surrogate key\", \"SCD\"."
-version: "1.0.0"
+version: "1.1.1"
 ---
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/data-modeling.md instead. -->
@@ -30,56 +30,60 @@ Best practices for designing semantic models in Power BI.
 
 ### Fact Tables
 - Contain measurable events/transactions
+- **Plural names** (multiple events): `Sales`, `Orders`, `Transactions`
+- **No `Fact_` prefix** — that's developer jargon, users see this in the model
 - Granularity: one row per event/transaction
-- Include foreign keys to dimension tables
-- Include numeric measures (Amount, Quantity, etc.)
+- Include foreign keys to dimension tables (hidden from report view)
+- Hide raw numeric columns; expose them through explicit measures
 
 ```
-Fact_Sales
-├── SalesID (PK)
-├── DateKey (FK)
-├── ProductKey (FK)
-├── CustomerKey (FK)
-├── StoreKey (FK)
-├── Quantity
-├── UnitPrice
-└── TotalAmount
+Sales                              ← plural, business name, no prefix
+├── SalesKey (PK, hidden)
+├── DateKey (FK, hidden)
+├── ProductKey (FK, hidden)
+├── CustomerKey (FK, hidden)
+├── StoreKey (FK, hidden)
+├── Quantity (hidden, exposed via [Quantity Sold] measure)
+├── Unit Price (hidden, used in measures)
+└── Sales Amount (hidden, used in [Sales] measure)
 ```
 
 ### Dimension Tables
 - Contain descriptive attributes
-- Include surrogate key (integer PK)
+- **Singular names** (describes one entity): `Customer`, `Product`, `Date`
+- **No `Dim_` prefix** — users see this name
+- Include surrogate key (integer PK, hidden)
 - Denormalized for simplicity
 - Include business key for lookups
 
 ```
-Dim_Product
-├── ProductKey (PK, surrogate)
-├── ProductID (business key)
-├── ProductName
+Product                            ← singular, business name, no prefix
+├── ProductKey (PK, surrogate, hidden)
+├── Product ID (business key, visible)
+├── Product Name
 ├── Category
 ├── Subcategory
 ├── Brand
-└── UnitCost
+└── Unit Cost
 ```
 
 ### Date Dimension
-Essential for time intelligence. Mark as Date Table in Power BI.
+Essential for time intelligence. Mark as Date Table in Power BI. Singular: `Date`, never `Dates` or `Dim_Date`.
 
 ```
-Dim_Date
-├── DateKey (PK, YYYYMMDD integer)
+Date                               ← singular, no prefix
+├── DateKey (PK, YYYYMMDD integer, hidden)
 ├── Date (actual date)
 ├── Year
 ├── Quarter
 ├── Month
-├── MonthName
+├── Month Name
 ├── Week
-├── DayOfWeek
-├── DayName
-├── IsWeekend
-├── IsHoliday
-└── FiscalYear (if different from calendar)
+├── Day of Week
+├── Day Name
+├── Is Weekend
+├── Is Holiday
+└── Fiscal Year (if different from calendar)
 ```
 
 ## Relationship Best Practices
@@ -125,55 +129,62 @@ Option 2: Duplicate dimension tables (clearer but redundant)
 
 ## Naming Conventions
 
-| Element | Convention | Example |
-|---------|------------|---------|
-| Fact tables | `Fact_` prefix | `Fact_Sales`, `Fact_Inventory` |
-| Dimension tables | `Dim_` prefix | `Dim_Product`, `Dim_Customer` |
-| Bridge tables | `Bridge_` prefix | `Bridge_CustomerProduct` |
-| Foreign keys | Match dimension key name | `ProductKey`, `CustomerKey` |
-| Measures | Business-friendly names | `Total Sales`, `Avg Order Value` |
+**Core principle:** user-visible names speak business language, technical elements stay hidden. No `dim`, `fact`, `tbl` prefixes — those leak SQL jargon into the user experience.
+
+| Element | Convention | Example | Anti-Pattern |
+|---------|------------|---------|--------------|
+| Fact tables | Plural, business name | `Sales`, `Orders`, `Transactions` | `Fact_Sales`, `fct_sales` |
+| Dimension tables | Singular, business name | `Customer`, `Product`, `Date` | `Dim_Customer`, `dim_customers` |
+| Bridge tables | `Bridge` prefix | `Bridge Customer Region` | `BridgeCustomerRegion` |
+| Foreign keys | `[Entity]Key`, hidden | `ProductKey`, `CustomerKey` | `prod_id`, `FK_Product` |
+| Surrogate PK | `[Entity]Key`, hidden | `CustomerKey` | `ID`, `pk_customer` |
+| Business key | `[Entity] ID` or `Code` | `Customer ID`, `Product Code` | `BusinessKey` |
+| Attribute columns | Natural language | `First Name`, `Order Date` | `FrstNm`, `OrdDt` |
+| Measures | Auto-explicative, no prefix | `Sales`, `Margin %`, `Sales YTD` | `Total Sales`, `Sum of Sales` |
+
+See `/governance` for the complete naming guide.
 
 ## Common Patterns
 
 ### Many-to-Many with Bridge Table
 ```
-Dim_Customer ──(1:*)── Bridge_CustomerProduct ──(*:1)── Dim_Product
+Customer ──(1:*)── Bridge Customer Product ──(*:1)── Product
 ```
 
 ### Slowly Changing Dimensions (SCD)
 ```
 Type 1: Overwrite (no history)
 Type 2: Add new row with version tracking
-  - StartDate, EndDate, IsCurrent flag
+  - Start Date, End Date, Is Current flag
 
-Dim_Customer_SCD2
-├── CustomerKey (surrogate, unique per version)
-├── CustomerID (business key)
-├── CustomerName
+Customer (SCD2)
+├── CustomerKey (surrogate, unique per version, hidden)
+├── Customer ID (business key)
+├── Customer Name
 ├── Address
-├── StartDate
-├── EndDate
-└── IsCurrent
+├── Start Date
+├── End Date
+└── Is Current
 ```
 
 ### Junk Dimension (Low-Cardinality Flags)
 Combine multiple low-cardinality attributes:
 ```
-Dim_OrderFlags
-├── OrderFlagKey
-├── IsRush
-├── IsGift
-├── IsOnline
-└── PaymentType
+Order Flags
+├── OrderFlagKey (hidden)
+├── Is Rush
+├── Is Gift
+├── Is Online
+└── Payment Type
 ```
 
 ### Degenerate Dimension
 Attributes stored in fact table (no separate dimension):
 ```
-Fact_Sales
+Sales
 ├── ...
-├── InvoiceNumber    (degenerate dimension)
-├── OrderNumber      (degenerate dimension)
+├── Invoice Number    (degenerate dimension)
+├── Order Number      (degenerate dimension)
 └── ...
 ```
 
@@ -199,9 +210,12 @@ Fact_Sales
 
 ## Model Validation Checklist
 
+- [ ] No technical prefixes (`Dim_`, `Fact_`, `tbl_`)
+- [ ] Dimensions are singular (`Customer`), facts are plural (`Sales`)
+- [ ] Foreign keys hidden from report view
+- [ ] Sumable source columns hidden (only explicit measures visible)
 - [ ] All relationships are single-direction (except where required)
 - [ ] Date table marked as Date Table
-- [ ] Foreign keys hidden from report view
 - [ ] No circular dependencies
 - [ ] Measures in dedicated folder or table
 - [ ] Appropriate data types assigned
@@ -218,14 +232,26 @@ Fact_Sales
 
 ### Snowflake Complexity
 ```
-❌ Dim_Product → Dim_Category → Dim_Department
-✓ Denormalize: Dim_Product (includes Category, Department)
+❌ Product → Category → Department
+✓ Denormalize: Product (includes Category, Department columns)
 ```
 
 ### Calculated Columns for Measures
 ```
 ❌ Calculated column: [Profit] = [Revenue] - [Cost]
-✓ Measure: Profit = SUM([Revenue]) - SUM([Cost])
+✓ Measure: Profit = SUM(Sales[Revenue]) - SUM(Sales[Cost])
+```
+
+### Technical Prefixes on User-Visible Tables
+```
+❌ Fact_Sales, Dim_Customer (developer jargon leaks to users)
+✓ Sales, Customer (business names)
+```
+
+### Visible Sumable Columns
+```
+❌ Quantity column visible — users drag it into visuals as Sum/Average
+✓ Hide Quantity, expose explicit measure: Quantity Sold = SUM(Sales[Quantity])
 ```
 
 ### Missing Date Dimension

package/skills/data-quality/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "data-quality"
 description: "Use when the user asks about Data Quality Skill, especially phrases like \"data quality\", \"check for errors\", \"data profiling\", \"clean data\", \"calidad de datos\"."
-version: "1.0.0"
+version: "1.1.1"
 ---
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/data-quality.md instead. -->