npx @luccapinto/agentic-data-kit@latest init

Contents

• 🧠 What it is
• 📈 The Power BI loop (Desktop open)
• 🚀 Install
• ✅ Prerequisites for the Power BI loop
• 🎯 What's inside
• 🧪 Validation scripts
• 🔄 Multi-tool sync
• 🤝 Contributing
• 🙏 Credits & references
• 📄 License

🧠 What it is

Generic LLMs don't know your standards, but they already write clean code. So this kit captures
only what a model can't supply on its own: how Power BI projects are laid out (PBIP, TMDL, PBIR),
how to drive Power BI Desktop while it is open, real quality gates (Best Practice Analyzer, PBIR
validation), and your brand. Power BI is the flagship; the kit also ships dbt naming conventions,
documentation templates and presentation builders (HTML decks, editable PPTX). Everything is
authored once in .agent/ and compiled into each assistant's native format.

📈 The Power BI loop (Desktop open)

You keep Power BI Desktop open on the .pbip. The assistant changes the model live and the
report on disk, then reloads Desktop and looks at the result.

Model / measures                         Report visuals
────────────────                         ──────────────
Modeling MCP  ──► change goes LIVE       edit PBIR files
in Desktop                                   │
     │                                       ▼
you save in Desktop                     validate_pbir.py
(TMDL lands in the PBIP)                     │
     │                                       ▼
     ▼                                Desktop has no unsaved changes?
run_bpa.py (BPA)                             │
                                             ▼
                                   powerbi-report-author preview --reload
                                             │
                                             ▼
                                   --screenshot <dir> --all-pages
                                             │
                                             ▼
                              pbi-visual-reviewer (fresh context) ─► PASS / FAIL per page & visual

Visual loop in order: edit PBIR → validate_pbir.py → confirm Desktop has no unsaved changes
(powerbi-report-author preview <folder> --host desktop --status, details.hasUnsavedChanges must
be false) → --reload → --screenshot <dir> --all-pages → pbi-visual-reviewer.

Three pitfalls

1. Reload discards unsaved Desktop changes. Check the status first; save in Desktop if needed.
2. Reload only covers the report. Model and measure changes go through the Modeling MCP, not
   through file reload.
3. An edited theme may not reload. Rename the theme file (and its reference) to force a pick-up.

Details: desktop-bridge.md
and modeling-mcp.md.

Desktop-closed alternative. No Desktop Bridge, an older Desktop, or CI? The disk-only path
stays supported: edit TMDL/PBIR on disk, validate with the scripts, then reopen the project in
Desktop. It is documented in
pbi-report-layer-pbir › Alternative: Desktop closed
and pbi-semantic-layer-tmdl › Alternative: Desktop closed.

🚀 Install

npx @luccapinto/agentic-data-kit@latest init

Pick your assistant in the prompt, or skip it with --target:

npx @luccapinto/agentic-data-kit@latest init --target cursor

OpenAI Codex reads the root AGENTS.md. Instructions are written in English; the assistant
replies in your language.

✅ Prerequisites for the Power BI loop

Without these you still get the Desktop-closed path and the scripts' fallbacks.

🎯 What's inside

Agent. An agent only exists if it imposes something the model can't impose on itself:
restricted tools, an independent fresh-context review, a different model, or an automatic trigger.
pbi-visual-reviewer has read-only tools (Read, Grep, Glob) and never sees the author's
reasoning. It checks screenshots + spec + PBIR for overlap, clipped text, empty/error visuals,
alignment, theme consistency and titles, and returns PASS/FAIL per page and per visual.

Skills

Workflows

🧪 Validation scripts

Validation lives in scripts inside the skills, not in agents. All three accept
--format text|json; exit code 0 = no errors, 1 = errors found, 2 = usage or tool failure.

Python 3.9+, standard library only. Run the repo's own tests with npm test.

🔄 Multi-tool sync

.agent/ is the single source of truth. One script compiles it into every tool's native format:

python3 scripts/sync_agents.py          # regenerate .claude/ .github/ .opencode/ .cursor/ AGENTS.md
python3 scripts/sync_agents.py --check  # exit 1 if generated folders are stale (used by CI)

.agent/                ← edit here
├── agents/            # 1 independent reviewer
├── skills/            # 9 on-demand knowledge modules (+ scripts, references)
├── workflows/         # 3 slash commands
└── rules/             # always-on rules (rules.md)

.claude/  .github/  .opencode/  .cursor/  AGENTS.md   ← generated (do not edit)

The generated folders ship in the package because init installs one folder per tool.

🤝 Contributing

See CONTRIBUTING.md: author in .agent/ only, sync, test — and apply the
agent-survival rule before adding anything. Release history is in CHANGELOG.md.

🙏 Credits & references

• Power BI Desktop Bridge
• Power BI Report skill
• Power BI Authoring MCP server
• microsoft/skills-for-fabric (MIT) — skill powerbi-report-cli
• DESIGN.md follows the Google Labs spec (Apache-2.0). See THIRD_PARTY_NOTICES.md.

📄 License

MIT © Lucca Pinto — repository:
luccapinto/agentic-data-kit