pbir-authoring-adapter
Skill2 starsChanged 4 months agoApache-2.0View on GitHub
The Power BI report-AUTHORING adapter (F034 completion). Use when someone asks to apply a generated theme to a committed PBIR report, or (later increments) to set visual formatting or a page background by writing the report's PBIR JSON directly -- the settings a human sets by hand in the Power BI UI. This is a COMPANION execution/authoring adapter (the F029-dbt / F030-Dagster pattern), NOT part of the static DEFINE/CHECK core. It writes committed PBIR JSON within a tight allow-list, deterministically and validated; it uses NO pbi-cli, NO live Power BI, NO external dependency, and NO network. It grants no readiness pass and emits no score.
In this repository60 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- approval-consoleSkill
- approval-evidence-packSkill
- business-knowledge-interviewSkill
- capabilitiesSkill
- consumer-data-dictionarySkill
- cross-table-lineageSkill
- dagster-orchestration-adapterSkill
- dashboard-designSkill
- dashboard-intelligenceSkill
- dbt-transformation-adapterSkill
- evidence-pack-generatorSkill
- first-hour-compassSkill
- friendly-pr-reviewerSkill
- grain-confidence-reviewerSkill
- kpi-contract-builderSkill
- pbi-mcp-write-adapterSkill
- pbip-workflowSkill
- pbip-xraySkill
- portfolio-watchSkill
- powerbi-dashboard-designSkill
- pr-readiness-reviewerSkill
- readiness-viewerSkill
- release-notes-generatorSkill
- report-intent-interviewSkill
- retail-build-warehouseSkill
- retail-control-roomSkill
- retail-discover-portfolioSkill
- retail-governSkill
- retail-initSkill
- retail-onboard-tableSkill
- retail-orchestrateSkill
- retail-scaffoldSkill
- retail-semantic-checkSkill
- retail-validateSkill
- run-next-readinessSkill
- seshat-studioSkill
- showcase-buildSkill
- source-mappingSkill
- speckit-analyzeSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-git-commitSkill
- speckit-git-featureSkill
- speckit-git-initializeSkill
- speckit-git-remoteSkill
- speckit-git-validateSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
- bi-analyst-knowledgeSkill
- bi-bigdata-knowledgeSkill
- bi-dax-knowledgeSkill
- bi-python-knowledgeSkill
- bi-sql-knowledgeSkill
- retail-kpi-knowledgeSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 36
Allow-list only: Write ONLY the declared formatting/wiring properties (see templates/pbir-adapter-contract.md).
- Very specific: line 41
No external dependency: No pbi-cli, no Power BI MCP, no live connection, no network.
- Distinctive: line 98
STOP before writing anything outside the current increment's allow-list.
- Very specific: line 99
STOP unless the exact table's readiness record is committed and clean, with semantic_model_ready: pass and a complete named-human …
- Distinctive: line 102
STOP if ADR 0015 is not the recorded authorization (never self-grant the lift).
- Distinctive: line 103
STOP at the on-disk PBIR -- never open a live Power BI / workspace (that is F016).
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
pbir-authoring-adapter
The adapter that completes F034: it writes the committed PBIR report the kit previously left for a human to build in Power BI Desktop. Authorized by ADR 0015 (owner-ratified 2026-07-05), which lifts spec-001 FR-008/FR-009 for this bounded adapter only -- the static core stays forbidden from writing PBIR.
What it is (and is NOT)
- It is a companion authoring adapter: reads a generated theme (Slice 1
retail theme-gen) + committed PBIR, WRITES committed PBIR JSON within an allow-list, and validates every write. - It is NOT the brain: it defines no metric, mapping, or semantic logic; it writes formatting/wiring, never business meaning.
- It is NOT publish-capable: it stops at the committed on-disk PBIR. Publishing to a live workspace is the parked F016 adapter (separate, gated).
- It does NOT build a dashboard from nothing: it restyles/positions visuals a human authored. "Great professional dashboards" is a design-intelligence layer that would ride on top -- this adapter is the mechanism, not that layer.
The boundary (carry into every increment)
- Allow-list only. Write ONLY the declared formatting/wiring properties (see
templates/pbir-adapter-contract.md). Increment A's allow-list: the report'sthemeCollection.baseTheme+ itsresourcePackagesitem + the BaseTheme resource file. Nothing else -- novisual.json, nopage.jsongeometry, no semantic-model file. - No external dependency. No pbi-cli, no Power BI MCP, no live connection, no
network. stdlib
json+pathlibonly. The tool is complete in itself. - Deterministic + validated + reversible. Byte-identical re-run; reviewable git
diff; stage -> validate (valid JSON +
$schemapreserved + round-trip stable + R1 model-ref + R2 authoring-lint) -> commit-or-roll-back; all-or-nothing. - Evidence, not approval. A successful write is evidence formatting was applied;
it moves NO readiness stage and emits NO score (hard rule #9). The
dashboard_ready/ design-review sign-off stays a named human's decision. - The core polices; the adapter writes.
seshat checkR2 is the read-only core lint over the written report; the writer (src/seshat/pbir_theme_apply.py) is the adapter. The core never writes PBIR (ADR 0015 decision 1).
Increment A -- apply a generated theme (SHIPPED)
retail pbir-apply-theme --repo <root> --table <table> --theme <theme.json> --report <*.Report/> writes the theme
as a BaseTheme resource and repoints report.json's themeCollection at it. Works
on an empty report page (no visuals needed). This is the safe smallest slice.
Increment B -- per-visual formatting (SHIPPED)
retail pbir-format-visual --repo <root> --table <table> --visual <visual.json> --formatting <json> sets
allow-listed formatting under a visual's objects (chart-content: legend, labels,
dataPoint, axes) and visualContainerObjects (chrome: border, title, subTitle,
background, dropShadow) subtrees. The FR-003 guarantee: the visual's data
binding (query + visualType) is asserted byte-identical before+after; the write
is refused if it would change. It formats a visual a human already authored -- it
never binds data or creates a visual. (Latent until a human builds a visual in
Desktop; there is no live target to format yet.)
Increment C -- page background (SHIPPED)
retail pbir-set-page-background --repo <root> --table <table> --asset <img> --report <*.Report/> --page <name>
[--scaling Fit|Fill|Normal] sets a page's canvas background to a committed surface-2
image asset: it copies the asset into StaticResources/RegisteredResources/,
registers it in report.json (the RegisteredResources package), and references it
from page.json objects.background via a ResourcePackageItem URL + name +
scaling. Allow-list-only: touches ONLY objects.background + the RegisteredResources
package -- every other page object (e.g. outspacePane) and report key is preserved.
Surface-2 purity: references a static image, bakes no data into it. The wire format
(ResourcePackageItem, PackageType: 1) was taken verbatim from a real
Desktop-authored sample -- it was NOT guessed (increment C was held until that sample
existed).
Increment D -- visual geometry / layout (SHIPPED)
retail pbir-set-geometry --repo <root> --table <table> --visual <visual.json> --position <json> writes ONLY a
visual's layout rectangle -- x, y, width, height, z (stack/tab order) -- for
a visual that already exists and is already on the approved binding-map. It repositions
existing truth; it NEVER changes visualType, creates/deletes a visual, or adds/removes
a page (creation is authoring truth, out of scope here). Off-canvas positions are
rejected; overlap is allowed (a design judgment). Authorized separately by ADR 0016
(the formatting-only ADR 0015 deliberately refuses geometry). No --force: position
keys always pre-exist, so a differs-then-refuse gate would block every real move;
overwrite safety is the reviewable git diff + human ratification.
Hard stops
- STOP before writing anything outside the current increment's allow-list.
- STOP unless the exact table's readiness record is committed and clean, with
semantic_model_ready: passand a complete named-humandashboard_readyapproval. The command gate checks this before reading a mutation payload. - STOP if ADR 0015 is not the recorded authorization (never self-grant the lift).
- STOP at the on-disk PBIR -- never open a live Power BI / workspace (that is F016).
See also
- Authorization:
docs/decisions/0015-pbir-authoring-adapter-lifts-fr008-fr009.md(A/B/C),docs/decisions/0016-pbir-adapter-geometry-increment-d.md(D geometry), anddocs/decisions/0017-pbir-creation-primitive.md(the spec-123 blueprint->PBIR compiler, which CREATES pages/visuals -- a separate capability beyond this adapter). - Spec / plan / tasks:
specs/106-pbir-authoring-adapter/{spec,plan,tasks}.md. - The contract:
templates/pbir-adapter-contract.md. - The enumerated shape + allow-list:
docs/integrations/pbir-adapter.md. - The writer + verb:
src/seshat/pbir_theme_apply.py(retail pbir-apply-theme). - The core lint:
src/seshat/rules/pbir.py(R2). - The theme source consumed:
src/seshat/theme_gen.py(retail theme-gen, Slice 1). - The parked publish adapter (separate): F016.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

