@luquimbo/bi-superpowers 4.1.6 → 5.0.1

package/.claude-plugin/marketplace.json

@@ -6,20 +6,22 @@
   },
   "metadata": {
     "description": "AI-powered skills for Power BI Desktop development. Works with Claude Code, GitHub Copilot, Codex, Gemini CLI, and Kilo Code.",
-    "version": "4.1.6",
+    "version": "5.0.1",
     "repository": "https://github.com/luquimbo/bi-superpowers"
   },
   "plugins": [
     {
       "name": "bi-superpowers",
-      "description": "4 AI skills + Power BI Modeling and Microsoft Learn MCP servers for local Power BI Desktop workflows across 5 AI agents.",
+      "description": "6 AI skills + Power BI Modeling and Microsoft Learn MCP servers for local Power BI Desktop workflows across 5 AI agents.",
       "source": "./",
       "strict": false,
       "skills": [
-        "./skills/bi-start",
-        "./skills/pbi-connect",
-        "./skills/project-kickoff",
-        "./skills/report-design"
+        "./skills/bi-connect",
+        "./skills/bi-dax",
+        "./skills/bi-kickoff",
+        "./skills/bi-modeling",
+        "./skills/bi-performance",
+        "./skills/bi-start"
       ]
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "bi-superpowers",
   "description": "Claude Code plugin for Power BI, Microsoft Fabric, and semantic model workflows powered by the official Microsoft MCP servers.",
-  "version": "4.1.6",
+  "version": "5.0.1",
   "author": {
     "name": "Lucas Sanchez"
   },

package/.claude-plugin/skill-manifest.json

@@ -1,39 +1,55 @@
 {
   "name": "bi-superpowers",
-  "version": "4.1.6",
-  "skillCount": 4,
+  "version": "5.0.1",
+  "skillCount": 6,
   "skills": [
     {
-      "name": "bi-start",
-      "title": "BI Start Skill",
-      "description": "Use when the user asks about BI Start Skill, especially phrases like \"bi-start\", \"bi start\", \"/bi-start\", \"empezar\", \"comenzar\", \"arranco\".",
+      "name": "bi-connect",
+      "title": "Power BI MCP Connection Skill",
+      "description": "Use when the user asks about Power BI MCP Connection Skill, especially phrases like \"connect Power BI\", \"PBI connection\", \"MCP connection\", \"Power BI MCP\", \"DAX UDF\", \"DAX user-defined function\".",
       "category": "command",
-      "triggerCount": 22,
-      "path": "skills/bi-start/SKILL.md"
+      "triggerCount": 26,
+      "path": "skills/bi-connect/SKILL.md"
     },
     {
-      "name": "pbi-connect",
-      "title": "Power BI MCP Connection Skill",
-      "description": "Use when the user asks about Power BI MCP Connection Skill, especially phrases like \"connect Power BI\", \"PBI connection\", \"MCP connection\", \"Power BI MCP\", \"modeling mcp\", \"Power BI Modeling MCP\".",
+      "name": "bi-dax",
+      "title": "Power BI DAX Expert Skill",
+      "description": "Use when the user asks about Power BI DAX Expert Skill, especially phrases like \"bi-dax\", \"/bi-dax\", \"DAX\", \"medida DAX\", \"DAX measure\", \"fórmula DAX\".",
       "category": "command",
-      "triggerCount": 15,
-      "path": "skills/pbi-connect/SKILL.md"
+      "triggerCount": 51,
+      "path": "skills/bi-dax/SKILL.md"
     },
     {
-      "name": "project-kickoff",
+      "name": "bi-kickoff",
       "title": "Project Kickoff Skill",
       "description": "Use when the user asks about Project Kickoff Skill, especially phrases like \"I'm starting a brand-new BI project from scratch\", \"analizar proyecto\", \"analyze project\", \"project kickoff\", \"nuevo proyecto\", \"new project\".",
       "category": "command",
       "triggerCount": 15,
-      "path": "skills/project-kickoff/SKILL.md"
+      "path": "skills/bi-kickoff/SKILL.md"
     },
     {
-      "name": "report-design",
-      "title": "Report Design Skill",
-      "description": "Use when the user asks about Report Design Skill, especially phrases like \"crear reportes\", \"armar el reporte\", \"diseñar reporte\", \"report design\", \"create reports\", \"build dashboard\".",
+      "name": "bi-modeling",
+      "title": "Power BI Data Modeling Skill",
+      "description": "Use when the user asks about Power BI Data Modeling Skill, especially phrases like \"bi-modeling\", \"bi modeling\", \"/bi-modeling\", \"modelar\", \"modelo semántico\", \"semantic model\".",
       "category": "command",
-      "triggerCount": 9,
-      "path": "skills/report-design/SKILL.md"
+      "triggerCount": 39,
+      "path": "skills/bi-modeling/SKILL.md"
+    },
+    {
+      "name": "bi-performance",
+      "title": "Power BI Performance Skill",
+      "description": "Use when the user asks about Power BI Performance Skill, especially phrases like \"bi-performance\", \"/bi-performance\", \"performance\", \"rendimiento\", \"lento\", \"slow\".",
+      "category": "command",
+      "triggerCount": 42,
+      "path": "skills/bi-performance/SKILL.md"
+    },
+    {
+      "name": "bi-start",
+      "title": "BI Start Skill",
+      "description": "Use when the user asks about BI Start Skill, especially phrases like \"bi-start\", \"bi start\", \"/bi-start\", \"empezar\", \"comenzar\", \"arranco\".",
+      "category": "command",
+      "triggerCount": 22,
+      "path": "skills/bi-start/SKILL.md"
     }
   ]
 }

package/.plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "spec": "open-plugin-spec@1",
   "name": "bi-superpowers",
-  "version": "4.1.6",
+  "version": "5.0.1",
   "description": "Claude Code plugin for Power BI, Microsoft Fabric, and semantic model workflows powered by the official Microsoft MCP servers.",
   "author": {
     "name": "Lucas Sanchez"

package/AGENTS.md

@@ -6,15 +6,114 @@
 
 ## Project Overrides
 - Primary interface is the `super` CLI and the slash-command skills listed below.
+- Codex is the product's primary development and end-to-end validation baseline. Other agent adapters are compatibility targets unless a specific release cycle explicitly tests them.
 - Adapters generate tool-specific configs; treat adapters as derived artifacts.
 - No lessons/tasks files are required unless the user requests them.
 - AI-generated code must include beginner-friendly comments and remain optimal for agent comprehension.
+- Plugin skills must default to teacher mode: teach DAX, modeling, report reasoning, and Git/version-control habits as work is performed, calibrated to the user's level.
+- Power BI users should be coached toward developer-grade workflow. Saving in Power BI Desktop is the authoring action; reviewing diffs and committing meaningful snapshots is the engineering action. Agents should explain the Git step, recommend commits after significant saved changes, and offer to create the commit automatically when the repo is clean and the change is coherent.
+- PBIP files are version-control snapshots, not an authoring surface for agents. Agents may read `.pbip`, `.SemanticModel/`, and `.Report/` files for diagnostics, diffs, and validation only.
+- All semantic-model changes must go through the Power BI Modeling MCP against Power BI Desktop, then be persisted by Desktop save/export. Do not hand-edit `.tmdl` or other semantic model files.
+- Report and visual design changes are manual Power BI Desktop work. Never edit PBIR report artifacts directly: no `.Report/**/visual.json`, `page.json`, `report.json`, `definition.pbir`, theme/resource JSON, coordinates, bookmarks, slicers, card settings, conditional formatting, or free-form visual changes by file patch.
+- The only permitted report mutation is the plugin-owned field-swap/rebind command for template adaptation. Agents may not patch PBIR by hand, even when the requested change is "just replacing a measure." The command may write PBIR only to replace source fields/measures in existing visuals with target model fields/measures, using an explicit source-to-target mapping and preserving visual type, layout, formatting, interactions, IDs, theme, and bookmarks. The command must support dry-run, backup, validation, and a tight write scope limited to data bindings (`projections`, `prototypeQuery`, query refs, field parameters, sort/filter field references when required). If that command is unavailable, field swaps stay manual in Power BI Desktop.
+- **Template is the reference.** The BISuperpowers smoke-test template (`examples/smoke-test/pbip-files/template.pbip`) encodes the patterns this plugin treats as default for any project: Auto Date/Time disabled, Date Table marked, `discourageImplicitMeasures: true`, the dedicated `Métricas` table with one-level display folders (`Auxiliar`, fact-table folders such as `Ventas`, and `Ratios`), period comparison via `Aux Comparaciones` (Sallieri pattern), parameterizable currency conversion via the Power Query `MonedaBase` parameter + `Modelo Configuración[ValorTexto]` + `Tipo de cambio[TipoCambioBase]`, dynamic dimensions via field parameters (`Aux Dimensiones ventas`), calculation groups for time intelligence, IBCS-aligned JSON theme. All specialist skills (`bi-kickoff`, `bi-modeling`, `bi-dax`, `bi-performance`, `bi-connect`) replicate these patterns in new projects and audit/migrate existing projects toward them. They are the floor, not optional decoration.
 
 ## Project Entry Points
-- `AGENTS.md` (this file)
-- `src/content/`
-- `bin/`
-- `config.json`
+- `AGENTS.md` (this file) — operational context, conventions, install + publish flow.
+- `CLAUDE.md` — companion file referenced at session start; lists the five context files in read order.
+- `ROADMAP.md` — strategic backlog, session log, decisions per cycle.
+- `CHANGELOG.md` — historical record of every release plus the `[Unreleased]` accumulator.
+- `README.md` — public-facing overview of skills, MCPs, install paths, supported agents.
+- `validation/README.md` — repo-only validation harness guidance.
+- `src/content/` — source of truth for skills (canonical authoring location).
+- `bin/` — CLI, generators, MCP launcher, install helpers.
+- `config.json` — local plugin user preferences template.
+
+## Documentation Maintenance Contract
+
+**Every commit that changes plugin behavior, conventions, install contracts, or strategic direction MUST update the relevant context files in the same commit.** This contract took effect on 2026-05-01 and exists because Lucas switches between Claude Code and Codex frequently — these files are the only handoff between sessions.
+
+Per-commit checklist:
+
+| File | Update when |
+|---|---|
+| `CHANGELOG.md` | Any user-visible change. Add an entry under `[Unreleased]` with the right section (Added / Changed / Fixed / Deprecated / Removed / Security / Breaking). |
+| `ROADMAP.md` | Mark DONE items, append to the session log at the **top** of the section (most recent first), update "Where we are right now" if the strategic state changed, add Open Questions if you spot them. |
+| `AGENTS.md` | Conventions, install contract, skill list, MCP list, or context-file references change. |
+| `CLAUDE.md` | Same triggers as `AGENTS.md` if the change affects the read-order at session start. |
+| `README.md` | User-visible API, install path, agent table, or capabilities change. |
+| `validation/README.md` | Validation harness contract changes. |
+
+Never ship a plugin-code commit without checking these. Acceptable exceptions (no doc update needed): pure refactors with no behavior change, dependency bumps, lint/format fixes. When in doubt, add at least a one-line `[Unreleased]` entry.
+
+## Atomic Commits Strategy
+
+**Codified 2026-05-01.** The agent commits autonomously as work progresses; the user explicitly authorizes pushes. The agent does NOT ask permission to commit each chunk — that's noise. The agent DOES ask before pushing to `origin`.
+
+For BI project work, do not hide Git from the user. After MCP or manual Power BI
+Desktop changes are saved/exported, inspect the diff, explain what changed in
+plain language, and recommend a commit when the snapshot is meaningful. If the
+user asks the agent to handle versioning, create the commit automatically once
+the change is coherent and verified; otherwise offer the exact commit action and
+teach why it matters.
+
+### When to commit (autonomous triggers)
+
+Commit immediately, without asking, when **all four** are true:
+
+1. **Coherent unit complete** — one feature, one fix, one refactor, one doc batch, one test batch. Describable in a single conventional-commit subject line.
+2. **Verified clean** — for code: `npm run lint` + `npm run format:check` pass; relevant `npm test` subset (or full suite) green. For docs only: visual diff sanity-checked.
+3. **Documentation contract honored** — the 5 context files updated where relevant (per "Documentation Maintenance Contract" above). For pure-doc commits this folds into the same commit.
+4. **Working tree was the agent's intent** — no leftover scratch files, no half-applied edits, no untracked binaries.
+
+### When NOT to commit (autonomous anti-triggers)
+
+Hold off committing — keep working — when any of these:
+
+- Tests are failing or weren't run on touched code paths.
+- Multiple unrelated changes are mixed in the working tree (split first; commit each separately).
+- Mid-flight refactor, multi-file rename, or mid-spec implementation that's coherent only end-to-end.
+- The user is mid-thought (clarification pending, design not approved, plan not validated).
+- The commit would carry untrusted/secret content (`.env`, credentials, customer data).
+
+### Commit message convention
+
+Conventional Commits style. Subject ≤ 72 chars. Body explains the **why** when non-trivial.
+
+| Prefix | Use for |
+|---|---|
+| `feat(scope):` | New user-visible capability |
+| `fix(scope):` | Behavior bug fix |
+| `docs(scope):` | Documentation-only changes |
+| `chore(scope):` | Maintenance, deps, packaging |
+| `refactor(scope):` | Internal restructure, no behavior change |
+| `test(scope):` | Test additions/refactors only |
+| `style:` | Formatting/whitespace only |
+| `feat(scope)!:` or `BREAKING CHANGE:` | Breaking change |
+
+Scopes used in this repo: `bi-start`, `bi-kickoff`, `bi-connect`, `bi-modeling`, `bi-dax`, `bi-performance`, `mcp`, `cli`, `install`, `update-check`, `generators`, `build-desktop`, `validation`, `docs`, `ci`, `release`, `roadmap`, `smoke-test`, `agents`. Add new scopes when needed.
+
+Always include the `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>` trailer when Claude Code is the author. Codex sessions sign their own way.
+
+### Push policy
+
+**Never push autonomously.** When a coherent batch of commits is ready, surface it to the user:
+
+> "Hay N commits listos para pushear a `origin/main`. ¿Pusheo?"
+
+Include a one-line summary per commit. Wait for explicit confirmation. Multiple commits accumulating locally is normal and fine.
+
+The only exception is when the user explicitly authorizes a push as part of a workflow ("commit and push", "tag and push for release", "do it"). In that case treat it as a one-time grant, not standing.
+
+### Verify-before-commit checklist (cheap, do every time)
+
+```bash
+npm run lint           # ~3s
+npm run format:check   # ~1s
+git status             # confirm intent
+```
+
+Run `npm test` when touching `bin/` code or scripts. Run `npm run build:plugin` when touching `src/content/` to confirm idempotent regen.
 
 ## Publishing to npm (for AI agents)
 
@@ -81,7 +180,7 @@ The repo uses **GitHub Actions** to publish automatically. The `NPM_TOKEN` is st
 
 ---
 
-AI-powered toolkit for Power BI Desktop development across Claude Code, GitHub Copilot, Codex, Gemini CLI, and Kilo Code.
+AI-powered toolkit for Power BI Desktop development, developed and stress-tested first in Codex, with compatibility adapters for Claude Code, GitHub Copilot, Gemini CLI, and Kilo Code.
 
 Developed by **Lucas Sanchez** ([@luquimbo](https://github.com/luquimbo))
 
@@ -99,19 +198,19 @@ npm install -g @luquimbo/bi-superpowers
 super install
 ```
 
-The shared v4.1.x contract is:
-- **4 skills** — `bi-start` (session opener), `project-kickoff`, `pbi-connect`, `report-design`
+The shared v5.0.x contract is:
+- **6 skills** — `bi-start` (session opener), `bi-kickoff` (new-project bootstrap), `bi-modeling` (semantic-model design + audit), `bi-dax` (DAX authoring + optimization), `bi-performance` (profiling + BPA via Tabular Editor 2), `bi-connect` (MCP connection + DAX UDFs)
 - **2 MCP servers** — `powerbi-modeling-mcp`, `microsoft-learn`
 
 Agent-specific behavior:
 - **All agents** — the primary install is user-level via `super install`, not repo-local.
-- **Claude Code** — `super kickoff` can optionally generate a project-local plugin with slash commands: `/bi-start`, `/project-kickoff`, `/pbi-connect`, `/report-design`.
-- **GitHub Copilot** — uses the installed user-level skills + MCP config via natural-language prompts.
-- **Codex** — uses the installed user-level skills + MCP config via natural-language prompts. Do not run `super kickoff` for Codex setup.
-- **Gemini CLI** — uses the installed user-level skills + MCP config via natural-language prompts.
-- **Kilo Code** — uses the installed user-level skills + MCP config via natural-language prompts.
+- **Codex** — primary tested baseline. Uses installed user-level skills + MCP config via natural-language prompts. Do not run `super kickoff` for Codex setup.
+- **Claude Code** — compatibility adapter. `super kickoff` can optionally generate a project-local plugin with slash commands: `/bi-start`, `/bi-kickoff`, `/bi-connect`, but Claude Code is not currently the end-to-end release QA baseline.
+- **GitHub Copilot** — compatibility adapter. Uses installed user-level skills + MCP config via natural-language prompts, but is not currently the end-to-end release QA baseline.
+- **Gemini CLI** — compatibility adapter. Uses installed user-level skills + MCP config via natural-language prompts, but is not currently the end-to-end release QA baseline.
+- **Kilo Code** — compatibility adapter. Uses installed user-level skills + MCP config via natural-language prompts, but is not currently the end-to-end release QA baseline.
 
-`/report-design` has one extra runtime prerequisite on every agent: **Windows + Power BI Desktop (standalone) + Python 3.10+ + `pipx` + `pbi-cli-tool`**. The bundled Node scripts handle visual/theme authoring, but the current flow still uses `pbi` for connect, page ops, and validate. If that stack is not available yet, start with `bi-start`, `project-kickoff`, or `pbi-connect`.
+All current local Power BI project skills require **Windows + Power BI Desktop**. Do not present Mac/Linux as supported for local Desktop workflows; only future cloud/Fabric skills may become cross-platform when they do not depend on Desktop.
 
 ### Claude Desktop
 
@@ -120,18 +219,19 @@ super build-desktop --output dist
 # Double-click bi-superpowers.mcpb para instalar en Claude Desktop
 ```
 
-Los 4 skills quedan disponibles como MCP prompts.
+Los 6 skills quedan disponibles como MCP prompts. Claude Desktop is a compatibility target, not the primary end-to-end QA baseline.
 
 ---
 
 ## Workflow Orchestration
 
-1. **Plan Mode (when allowed)**: For non-trivial work (3+ steps or architectural decisions), use plan mode when the environment supports it or the user asks. Re-plan if context changes.
-2. **Subagents (when available)**: Use subagents only if the environment provides them. Delegate research/exploration in parallel, one task per subagent.
-3. **Self-Improvement Loop (context-aware)**: Capture corrections only if the repo uses a lessons file or the user asks. Keep rules concise. Review lessons only when such a file exists.
-4. **Verification Before Done**: Do not mark complete without proof. Run tests/checks when available, document limitations if you cannot.
-5. **Demand Elegance (balanced)**: For non-trivial changes, prefer the elegant solution; avoid hacky fixes.
-6. **Autonomous Bug Fixing**: For bug reports, own the fix end-to-end using logs/tests as evidence.
+1. **Single-session by default (since 2026-05-01)**: Lucas runs one active dev session at a time on this repo. Do not create git worktrees, parallel branches, or async coordination files unless he explicitly asks. The previous worktrees convention (OQ-2) is deprecated in practice — keep it documented for emergencies only.
+2. **Plan Mode (when allowed)**: For non-trivial work (3+ steps or architectural decisions), use plan mode when the environment supports it or the user asks. Re-plan if context changes.
+3. **Subagents (when available)**: Use subagents only if the environment provides them. Delegate research/exploration in parallel, one task per subagent.
+4. **Self-Improvement Loop (context-aware)**: Capture corrections only if the repo uses a lessons file or the user asks. Keep rules concise. Review lessons only when such a file exists.
+5. **Verification Before Done**: Do not mark complete without proof. Run tests/checks when available, document limitations if you cannot.
+6. **Demand Elegance (balanced)**: For non-trivial changes, prefer the elegant solution; avoid hacky fixes.
+7. **Autonomous Bug Fixing**: For bug reports, own the fix end-to-end using logs/tests as evidence.
 
 ## Task Management
 
@@ -142,20 +242,42 @@ Los 4 skills quedan disponibles como MCP prompts.
 5. **Document Results**: Add a review section when task tracking is in scope.
 6. **Capture Lessons**: Update lessons only when the repo uses it or the user requests it.
 
+## Project Validation Harness
+
+Use `validation/` when the user wants to test the plugin against public fixtures
+or private client projects. Keep this boundary:
+
+- `examples/smoke-test/` is the public fixture area.
+- `validation/projects/*.json` stores sanitized metadata only.
+- `validation/cases/*.md` stores manual validation playbooks.
+- `validation.local.json` stores private local repo paths and is gitignored.
+- `validation/runs/` stores local logs and is gitignored.
+
+Never copy customer repositories, `.pbix`, Excel files, credentials,
+screenshots with private data, or private Git remotes into this public repo. Run
+structural checks with:
+
+```bash
+super validate-projects --project template
+super validate-projects --strict
+```
+
+MCP-backed validation still happens in the external client repo or public
+fixture; this repo records only sanitized evidence and repeatable checks.
+
 ## Core Principles
 
 - **Simplicity First**: Minimal, clear changes.
 - **No Laziness**: Fix root causes, avoid temporary patches.
 - **Minimal Impact**: Touch only what is necessary.
 
-## Available Skills (4)
+## Available Skills (3)
 
 | Skill | Purpose | Trigger |
 |-------|---------|---------|
 | `/bi-start` | Session opener: environment snapshot, update check, and routing to the specialist skills | "bi-start", "empezar", "start session" |
-| `/project-kickoff` | Analyze and plan BI projects | "analyze project", "new project" |
-| `/pbi-connect` | Connect to Power BI Desktop | "connect Power BI", "MCP" |
-| `/report-design` | Generate PBIR report pages via bundled Node scripts | "report design", "crear reportes" |
+| `/bi-kickoff` | Analyze and plan BI projects | "analyze project", "new project" |
+| `/bi-connect` | Connect to Power BI Desktop and guide DAX UDF authoring with Microsoft Learn + DAXLIB references | "connect Power BI", "MCP", "DAX UDF", "DAXLIB" |
 
 ## MCP Servers (2)
 
@@ -186,8 +308,8 @@ BI Agent Superpowers installs skills and MCP configuration at the user level for
 project/
 ├── .claude-plugin/plugin.json   # Plugin manifest
 ├── .mcp.json                    # Power BI Modeling + Microsoft Learn MCPs
-├── commands/*.md                # 4 slash commands (bi-start, pbi-connect, project-kickoff, report-design)
-├── skills/*/SKILL.md            # 4 skills (discoverable)
+├── commands/*.md                # 3 slash commands (bi-start, bi-connect, bi-kickoff)
+├── skills/*/SKILL.md            # 6 skills (discoverable)
 └── config.json                  # User preferences
 ```
 
@@ -265,6 +387,8 @@ Connect AI assistants directly to Power BI and Excel:
 | MCP Protocol | https://modelcontextprotocol.io |
 | Power BI Docs | https://docs.microsoft.com/power-bi |
 | DAX Guide | https://dax.guide |
+| DAX UDF Docs | https://learn.microsoft.com/en-us/dax/best-practices/dax-user-defined-functions |
+| DAXLIB | https://github.com/daxlib/daxlib |
 
 ---