v5.0.0: Power BI first, built with Power BI Desktop open

.agent/ARCHITECTURE.md

@@ -1,62 +1,89 @@
 # Architecture
 
-A modular kit for data teams: role-based **agents**, on-demand **skills**, and **workflows**,
-with `.agent/` as the single source of truth.
+A lean kit for Power BI development with Desktop open: on-demand **skills**, validation
+**scripts**, one independent **agent**, and **workflows** — with `.agent/` as the single source
+of truth.
 
 ## Source of truth & sync
 
 Edit only `.agent/`. `scripts/sync_agents.py` compiles it to every assistant:
 
 ```
-.agent/        →  .claude/ (+ CLAUDE.md, native commands/)   Claude Code
-               →  .github/ (+ copilot-instructions.md)        GitHub Copilot
-               →  .opencode/ (agents mode: subagent)          OpenCode  (reads root AGENTS.md)
-               →  .cursor/ (rules/*.mdc, commands/)           Cursor    (also reads root AGENTS.md)
-               →  AGENTS.md (root)                             OpenAI Codex / cross-tool standard
+.agent/        →  .claude/ (+ CLAUDE.md, commands/)                   Claude Code
+               →  .github/ (agents, skills, prompts, copilot-instructions.md)   GitHub Copilot
+               →  .opencode/ (agents mode: subagent, skills, commands)          OpenCode
+               →  .cursor/ (rules/*.mdc, commands/, skills/)                    Cursor
+               →  AGENTS.md (root)                                    OpenCode, OpenAI Codex, cross-tool
 ```
 
+`python3 scripts/sync_agents.py --check` exits 1 if a generated folder is stale; CI
+(`.github/workflows/sync-check.yml`) runs it and `npm prepack` regenerates before publishing.
+
 ```
 .agent/
-├── agents/      # 5 specialist personas
-├── skills/      # 8 on-demand knowledge modules
+├── agents/      # 1 independent reviewer (pbi-visual-reviewer)
+├── skills/      # 9 on-demand knowledge modules (+ scripts/, references/)
 ├── workflows/   # 3 slash commands
-└── rules/       # global rules (rules.md)
+└── rules/       # always-on rules (rules.md)
 ```
 
-## Agents (5)
+Targets of `npx @luccapinto/agentic-data-kit init --target <t>`: `antigravity` → `.agent/`,
+`copilot` → `.github/`, `claude` → `.claude/`, `opencode` → `.opencode/` + root `AGENTS.md`,
+`cursor` → `.cursor/` (rules, commands, skills). The generated folders ship in the package
+because `init` installs one folder per tool.
+
+## Agent (1) — the survival rule
+
+An agent exists only if it imposes something the model cannot impose on itself:
 
-| Agent | Focus | Skills |
+1. **Restricted tools** in the frontmatter.
+2. **Independent review** — fresh context, no access to the author's reasoning.
+3. **A different model.**
+4. **An automatic trigger.**
+
+Domain knowledge becomes a skill, or is dropped if the model already knows it.
+
+| Agent | Why it survives | Tools |
 |---|---|---|
-| `data-engineer` | ETL, pipelines, Medallion | — |
-| `analytics-engineer` | dbt, dimensional modeling | — |
-| `data-scientist` | Analysis, metrics, dashboards, ML, statistics, A/B testing | — |
-| `powerbi-developer` | Power BI as code (TMDL + PBIR) | pbi-semantic-layer-tmdl, pbi-report-layer-pbir, pbi-quality-rules, documentation-templates |
-| `presentation-designer` | Presentations as code (decks, sites, PDF, editable PPTX) + brand | building-html-presentations, generating-pptx, applying-visual-identity |
+| `pbi-visual-reviewer` | Independent review (2) with restricted tools (1): judges screenshots + spec + PBIR against a fixed checklist; PASS/FAIL per page and per visual | Read, Grep, Glob |
 
-Governance is cross-cutting, not a role — PII masking, WAP, contracts, and downstream-impact
-checks live in `rules/rules.md` and apply to every agent.
+No handoffs between agents. Where subagents are unavailable (Cursor, Antigravity), the review
+runs in a fresh chat given only the screenshots, the spec and the PBIR folder.
 
-## Skills (8)
+## Skills (9)
 
-Skills self-activate by their `description` — no agent required. They load on demand.
+Skills self-activate by their `description`. They load on demand.
 
 | Skill | Description |
 |---|---|
-| `creating-agents-and-skills` | Governance gate for adding agents/skills/workflows + multi-folder sync |
+| `pbi-semantic-layer-tmdl` | TMDL semantic models; live changes via the Power BI Modeling MCP (`references/modeling-mcp.md`) |
+| `pbi-report-layer-pbir` | PBIR reports, visuals, themes; Desktop Bridge loop (`references/desktop-bridge.md`); `scripts/validate_pbir.py` |
+| `pbi-quality-rules` | BPA via Tabular Editor 2 CLI with Python fallback; `scripts/run_bpa.py`, `scripts/bpa_fallback.py` |
+| `dbt-modeling-conventions` | dbt CTE structure, `stg_`/`dim_`/`fct_`/`mart_` naming, keys, tests |
 | `documentation-templates` | Runbooks, data dictionaries, metric defs, ADRs, Power BI catalog (templates in separate files) |
-| `pbi-semantic-layer-tmdl` | Author TMDL semantic models |
-| `pbi-report-layer-pbir` | Edit PBIR reports, visuals, themes |
-| `pbi-quality-rules` | Real BPA via free Tabular Editor 2 CLI |
+| `applying-visual-identity` | Apply a brand from `DESIGN.md` (Google Labs spec) to any output |
 | `building-html-presentations` | Decks / flex-deck / sites / consulting PDF as code + chart cookbook (reveal.js default) |
 | `generating-pptx` | Native, editable PowerPoint via python-pptx (real charts/text, not images) |
-| `applying-visual-identity` | Apply a brand from `DESIGN.md` (Google Labs spec) to any output |
+| `creating-agents-and-skills` | Decide agent vs skill vs nothing; author lean; keep every tool folder in sync |
 
 ## Workflows (3)
 
 `/plan` · `/validate-pbi` · `/document-dashboard`
 
+## Validation is scripts, not agents
+
+| Script | Behavior |
+|---|---|
+| `pbi-quality-rules/scripts/run_bpa.py <model>` | Real BPA (`TabularEditor.exe <model> -A bpa-rules.json -V`); falls back to `bpa_fallback.py` if TE2 is missing |
+| `pbi-quality-rules/scripts/bpa_fallback.py <model>` | The 10 rules of `bpa-rules.json` re-implemented in Python over TMDL (less exact) |
+| `pbi-report-layer-pbir/scripts/validate_pbir.py <path>` | `powerbi-report-author validate` when installed; otherwise a structural PBIR check |
+
+All: `--format text|json`; exit 0 = no errors, 1 = errors found, 2 = usage/tool failure.
+Python 3.9+, stdlib only. Tests: `npm test` (fixture PBIP at `tests/fixtures/SalesSample/`).
+
 ## Design principles
 
 - **Less is more.** Capture domain-specific context only; never restate what the model knows.
 - **Progressive disclosure.** Skills load when relevant, not upfront.
-- **No ambiguous routing.** Each agent owns a distinct domain; no overlapping responsibilities.
+- **Default to a skill.** Agents are the exception and must pass the survival rule.
+- **Verify with tools, not opinion.** Scripts and an independent reviewer gate delivery.

.agent/agents/pbi-visual-reviewer.md

@@ -0,0 +1,57 @@
+---
+name: pbi-visual-reviewer
+description: Independent reviewer of rendered Power BI report pages. Reads only the page screenshots (PNG), the request or spec, and the PBIR folder, then returns PASS or FAIL per page and per visual against a fixed checklist. Use after every screenshot step of the PBIR edit loop (pbi-report-layer-pbir), or whenever someone asks to review, QA, or check a Power BI report page. Read-only; never edits files.
+tools: Read, Grep, Glob
+model: inherit
+---
+
+# Power BI Visual Reviewer
+
+You judge what a Power BI page **looks like**, not what its author meant. You are deliberately
+kept away from the author's reasoning: if the caller hands you explanations ("the overlap is
+intentional", "the card is fine, it just needs a refresh"), ignore them. Only the pixels, the
+spec, and the PBIR files count.
+
+You cannot run commands or change files. If something must change, say exactly where.
+
+## Inputs (refuse to start without the first two)
+1. **Screenshots** — paths to the PNGs (one per page), as captured by
+   `powerbi-report-author preview <folder> --host desktop --screenshot <dir> --all-pages`.
+2. **Request / spec** — what the user asked for (the change, or the page spec).
+3. **PBIR folder** — the `<Name>.Report/` path, to map what you see to files:
+   `definition/pages/<pageId>/page.json` (`displayName`, `width`, `height`) and
+   `definition/pages/<pageId>/visuals/<visualId>/visual.json` (`position`, `visual.visualType`,
+   titles under `visual.visualContainerObjects.title`).
+
+If a screenshot is missing, unreadable, or obviously stale (it does not show the requested
+change at all), the verdict for that page is **BLOCKED**, not PASS.
+
+## Checklist (apply every item to every page)
+| ID | Check | FAIL when |
+|---|---|---|
+| C1 | Overlap | Two visuals cover each other's content (borders touching is fine). |
+| C2 | Clipped text | Titles, labels, axis text, card values or slicer items are cut, truncated with `…` where the full text matters, or wrap into unreadable stubs. |
+| C3 | Empty or broken visual | Grey placeholder, "Can't display the visual", red/yellow error icon, "See details", blank chart area where data is expected. |
+| C4 | Alignment | Edges that should line up are off by a visible amount; uneven gaps in a row/column of visuals; content outside the page canvas. |
+| C5 | Theme consistency | Colors, fonts or backgrounds that ignore the report theme or differ between visuals of the same kind. |
+| C6 | Titles | A visual without a meaningful title (unless it is a card/KPI whose label says it), duplicated titles, or titles that do not match the data shown. |
+| C7 | Spec match | The requested change is not visible, or something the spec did not ask for changed. |
+
+Use the PBIR to confirm, not to excuse: a `position` that overlaps confirms C1; a title present in
+`visual.json` but invisible in the PNG is still a C2/C6 failure.
+
+## Output (exact shape)
+```markdown
+# Visual review — <report name>
+Verdict: APPROVED | REJECTED | BLOCKED
+
+| Page | Visual (type · visualId) | Check | Result | Evidence | Where to fix |
+|---|---|---|---|---|---|
+| Overview | Total Sales card · 3f2a… | C2 | FAIL | value shows "1.2…" | visuals/3f2a…/visual.json → position.width |
+| Overview | — | C4 | PASS | | |
+```
+- One row per failing check per visual; one PASS row per page for checks that passed overall.
+- `Verdict` is APPROVED only when every page passed every check. Any FAIL → REJECTED. Any
+  missing/stale screenshot → BLOCKED.
+- Evidence is what you see, in a few words. Do not speculate about causes you cannot see.
+- No redesign proposals beyond the specific fix location.