# Pbi Lifecycle > End-to-end Power BI delivery project lifecycle — folder bootstrap, PBIP file scaffold, Git tracking with private GitHub repo, theme refresh propagation, and environment promotion (Dev → Test → Prod). One skill that takes a Power BI delivery project from "empty disk" to "deployable, version-controlled, env-promotable" without requiring the operator to know git, the PBIP file format, or the MAX_PAT… - **Type:** Skill - **Install:** `agentstack add skill-gusbavia-pbi-lifecycle-pbi-lifecycle` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [gusbavia](https://agentstack.voostack.com/s/gusbavia) - **Installs:** 0 - **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [gusbavia](https://github.com/gusbavia) - **Source:** https://github.com/gusbavia/pbi-lifecycle ## Install ```sh agentstack add skill-gusbavia-pbi-lifecycle-pbi-lifecycle ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Power BI Project Lifecycle · v0.3.3 End-to-end skill for the disk lifecycle of a Power BI delivery project. From an empty folder to a version-controlled, env-promotable project, with safety rails that protect non-git users from destructive mistakes. ## Why this skill exists Power BI delivery has six recurring pain points the operator should not have to relearn each time: 1. The Power BI Desktop **MAX_PATH 256-char limit** — strict, undocumented at file level, instantly broken when Auto Date/Time auto-creates `DateTableTemplate_.tmdl` files inside long client paths. 2. The **PBIR-Legacy vs PBIR-Modular** confusion — modular looks cleaner but Power BI Desktop converts to legacy on first save and themes don't auto-apply when generated as modular. 3. **`gh auth setup-git` is a separate step from `gh auth login`** — without it, `git push` fails after a successful login with the misleading "Invalid username or token" error. 4. **Auto Date/Time** is enabled by default in Power BI but considered an anti-pattern by every senior practitioner. The skill ships PBIPs with it disabled by default. 5. Power BI devs are often **not git users**. The skill's audience does not learn git just to use this. The skill explains how to inspect changes via the VS Code Source Control panel without typing a single git command. 6. **Theme propagation across projects** is manual today (copy JSON into each PBIP). The skill (Phase 4) automates this with per-project override semantics so a client rebrand is one command. This skill captures every workaround once, locks it as a pre-flight check or runtime guard, and lets the operator focus on building reports. ## Generic positioning · MANDATORY for the agent running this skill This skill ships to any Power BI practitioner. The agent running it must enforce strict neutrality. Violating any rule below is a defect. 1. **Do not infer or use the operator's personal context.** Never read auto-memory, prior conversation history, or session context to invent defaults, examples, or questions. The skill's behavior must be identical for the skill author, an external consultant, or a complete stranger. 2. **Do not reference any specific organization, client, product, project, or person** in any prompt, message, default value, example, or option. If unsure whether a name is generic, omit it. 3. **Do not ask any questions beyond the inputs defined in each Phase's Inputs section.** No project-type wizards, no scaffolding presets, no organization-specific naming taxonomies. 4. **Do not propose any folder, file, or convention beyond what is defined in the Hierarchy section.** The structure is fixed and exhaustive for this version. 5. **All placeholders in user-facing examples must be neutral** — `Client A`, `Project Name`, `My Power BI Project`. No real client names from any context. 6. **The skill is conversational but not creative.** Do not "be helpful" by adding steps, options, or branching logic. The defined inputs and the fixed structure are the entire surface area. If the operator volunteers a specific client name like "Acme Corp", that is fine — it becomes the value of `clientName` for that run. The agent must not propose, suggest, or remember any specific name on its own. ## Forbidden pre-flight behaviors Before, during, and after this skill runs, the agent must not perform any of the following: 1. **Do not list, scan, or inspect the operator's filesystem before asking the Clients root question.** No `pwd`, `ls`, `Get-ChildItem`, `dir`, or any equivalent on the current working directory or any directory the operator has not explicitly named. The skill's first interactive action is the **mode triage** prompt; the second is the relevant input question for the chosen mode. 2. **Do not propose candidate locations** based on what already exists on the operator's machine. Every path comes from the operator's typed answer. 3. **Do not auto-wire companion skills** (`pbi-model-doc`, `pbi-model-audit`, `pbi-theme-audit`, etc.) during any phase. Mention them in closing handoffs only as one-line pointers. 4. **Do not skip a Phase to "save time".** Phases run in declared order with explicit operator confirmation between them. The agent's first message after the skill is invoked must be the **mode triage** prompt described in the next section, exactly. No greeting beyond that, no preamble, no context-gathering, no scanning of cwd. ## Mode triage · the first message the skill always sends The skill is the lifecycle skill — multiple operations are available. The agent must always start by asking the operator which mode they want. **First message — verbatim, in the operator's language (PT-BR or EN, match the input):** ``` What do you want to do? 1. Bootstrap a new Power BI project folder structure (creates Client + Global Info + Global Theme + Power BI Repository with 01.Dev/02.Test/03.Prod env hubs and per-project subfolders; auto-creates a junction at C:\PBI-Clients\\ if path budget requires it) — AVAILABLE 2. Scaffold a PBIP file inside an existing project folder (generates working .pbip in PBIR-Legacy from scratch with Auto Date/Time disabled, theme auto-applied if Global Theme has one, and short internal folder names to fit MAX_PATH 256) — AVAILABLE 3. Initialize Git tracking for the client and push to a private GitHub repo (one repo per client, gh CLI flow with the three mandatory steps install / auth login / auth setup-git) — AVAILABLE 4. Refresh the visual theme across all projects of a client (reads Global Theme, applies per-project theme.md overrides, writes new theme.json into each PBIP's RegisteredResources/, always backs up first, supports --dry-run preview) — AVAILABLE 5. Promote a project to the next environment OR close out a project (Dev → Test or Test → Prod: copies 02_Build/, rewrites only catalog / http host / path / auth from the target env's source.json, AND generates a diff-findings report (same editorial style as pbi-model-doc) comparing source vs target so operator approves consistency before the merge. On Test → Prod and on close-project: ALSO generates a unified deployment lifecycle report covering the entire project history — timeline, commits, audit scores, promotion records, sign-off — for client handoff into 03_Docs/client_handoff/docs/.) — DESIGN LOCKED, IMPLEMENTATION QUEUED 6. Help me read changes in VS Code (no git knowledge required) — AVAILABLE (educational walkthrough, no filesystem changes) 7. Validate, audit, or document an existing project — Use companion skills: pbi-model-audit, pbi-theme-audit, pbi-model-doc 8. Something else — Not in scope for this skill Type 1–8. ``` **Routing rules:** - Modes `1`, `2`, `3`, `4`, `6` → proceed to the corresponding Phase section below. - Mode `5` → reply: *"That phase has the design locked but is not yet executable in this skill version. The agent could perform individual steps manually based on the design notes in this skill, but the automation is queued for v0.5 after real-PBIP calibration. Want a manual walkthrough or stop here?"* If the operator wants the manual walkthrough, present the algorithm from the corresponding phase section but ask for explicit confirmation at every mutation. Do not improvise beyond the documented design. - Mode `7` → reply: *"Use the companion skill: `pbi-model-audit` to audit, `pbi-theme-audit` for the visual layer, `pbi-model-doc` to generate documentation. This skill (`pbi-lifecycle`) only handles folder lifecycle and version control."* Then stop. - Mode `8` or off-list → reply: *"That's outside the scope of `pbi-lifecycle`. This skill only handles the disk lifecycle and version control of Power BI projects."* Then stop. - If the operator's initial invocation already implies a specific mode (e.g. *"setup my new power bi project"* → mode 1, *"create the pbip"* → mode 2, *"init git for this project"* → mode 3), the agent may infer that mode and proceed directly, skipping the triage prompt. The triage list is fixed and exhaustive for this version. The agent must not add, remove, or reword the eight options. --- # Phase 1 · Folder Bootstrap (AVAILABLE) Phase 1 is **strictly additive**. It only creates folders and net-new placeholder files. It never deletes, moves, renames, copies, or modifies anything that already exists. ## What Phase 1 does 1. Asks the operator for the absolute local path of the **Clients root** (must already exist). 2. Asks the **client name**. If the client folder is missing, creates it together with the shared client-level subtrees: `Global Info/`, `Global Theme/`, and `Power BI Repository/`. 3. Asks the **project name**. Creates the project folder under `Power BI Repository/01. Dev//` with the per-project subfolders (`01_Context/`, `02_Build/`, `03_Docs/internal|client_handoff/audit|docs/`). Replicates the empty project shell into `02. Test/` and `03. Prod/` for future promotion. 4. Adds `.gitkeep` files in empty env folders and `Global Info/` so the structure persists in version control. 5. **Computes the path budget.** If the absolute path of the client root exceeds 80 characters, **automatically creates a NTFS junction** at `C:\PBI-Clients\\` pointing to the OneDrive/long path and tells the operator to use the junction path going forward. If ≤ 80 chars, no junction is created — the operator works directly at the original path. 6. Optionally accepts a `--theme ` flag (or interactive prompt) to seed the client's theme.json into `Global Theme/pbi-theme/theme/` from an existing source. ## Hierarchy created The skill creates this exact structure. Names in `` are operator-provided. All other names are fixed defaults — the agent must not rename them. ``` / ← operator provides; must exist / ← created if missing Global Info/ ← shared client info; .gitkeep placeholder Global Theme/ ← shared client visual identity logo/ ← operator manually places client logos brand-guideline/ ← operator manually places brand guidelines pbi-theme/ ← output of pbi-theme companion skill theme/ ← .json (importable) + canvas SVG design-system/ ← .pdf + .html documentation design-tokens/ ← .css custom properties html-visual-style/ ← DAX HTML visual examples Power BI Repository/ ← env hub 01. Dev/ ← Dev env (uses "01. " prefix with period and space) .gitkeep ← preserves env folder when projects absent / ← created per project; the work happens here 01_Context/ ← project briefing (lowercase snake_case) scope.md ← scope template (placeholder) source.json ← per-env connection schema (env=dev) theme.md ← optional per-project theme override notes wireframe_to_data_mapping.md ← placeholder for wireframe XLSX 02_Build/ ← where .pbip lives (Phase 2 target; empty after Phase 1) 03_Docs/ internal/ ← internal-only outputs (gitignored by default) audit/ ← auto-target for pbi-model-audit + pbi-theme-audit when invoked inside lifecycle docs/ ← auto-target for pbi-model-doc when invoked inside lifecycle client_handoff/ ← shareable with client (Git-tracked) audit/ ← operator manually promotes approved audits here docs/ ← operator manually promotes approved docs / manuals here 02. Test/ ← Test env (replicated empty) .gitkeep / ← same internal subtree, empty until promoted 03. Prod/ ← Prod env (replicated empty) .gitkeep / ``` ## Critical naming rules (every one was paid for during calibration) | Aspect | Rule | Why | |---|---|---| | Env folder prefix | `01. Dev/` (with period AND space) | Visual ordering + readability; do not use `01_Dev/` | | Per-env folders | `01. Dev`, `02. Test`, `03. Prod` (numbered in this exact order) | Promotion path is left-to-right | | Per-project subfolders | `01_Context`, `02_Build`, `03_Docs` (underscore, no space) | Distinguishes from env-level prefix | | Files inside `01_Context/` | lowercase snake_case (`scope.md`, `source.json`, `theme.md`, `wireframe_to_data_mapping.md`) | Filesystem-friendly + cross-platform | | Empty folders | Get a `.gitkeep` so they persist in git | Git does not track empty dirs | | `Global Info/` and `Global Theme/` | Created at client level, shared across all projects | Theme + reference docs are client-wide | ## Pre-flight: path budget detection Before creating folders, the agent computes the **absolute path length of the proposed client root**: ``` $clientPath = "$clientsRoot\$clientName" $pathLength = $clientPath.Length ``` Decision tree: | Path length | Action | |---|---| | ≤ 80 chars | No junction. Skill proceeds directly at the original path. Note in handoff: "Path budget is comfortable; no junction created." | | 81–110 chars | Junction recommended. Prompt: *"Your client root is `$pathLength` chars long. Power BI Desktop's MAX_PATH limit is 256 chars total, and complex projects can grow paths quickly. Recommend creating a NTFS junction at `C:\PBI-Clients\\`. Create junction? (y/N)"* — default Y. | | > 110 chars | Junction MANDATORY. Prompt: *"Your client root is `$pathLength` chars long. Without a junction at `C:\PBI-Clients\\`, Power BI Desktop will fail to save certain files. The junction is mandatory for this path."* — proceed to create. | Junction creation (no admin required): ```powershell $slug = $clientName.ToLower() -replace '[^a-z0-9]+','-' -replace '^-+|-+$','' $junctionRoot = "C:\PBI-Clients" if (-not (Test-Path $junctionRoot)) { New-Item -ItemType Directory -Path $junctionRoot | Out-Null } $junctionPath = "$junctionRoot\$slug" if (Test-Path $junctionPath) { # If junction exists pointing elsewhere, abort with clear error. # Otherwise (target matches), reuse silently. } New-Item -ItemType Junction -Path $junctionPath -Target $clientPath ``` After junction creation, **the agent informs the operator explicitly**: > Junction created at `C:\PBI-Clients\\` → ``. Always open `.pbip` files via the junction path. The OneDrive/SharePoint folder is the sync source of truth; the junction is your working entry point. Both stay in sync automatically. ## Cross-cutting · Companion skill auto-routing contract Once a client is bootstrapped with this skill, the four companion skills auto-detect they're inside a lifecycle-managed structure and route their outputs to the right subfolder. This is the contract every skill in the IF Power BI Quality Suite respects: | Companion skill | Detects lifecycle when invoked at | Auto-routes output to | Standalone fallback | |---|---|---|---| | `pbi-theme` (mode 2) | Any path under `/` | `/Global Theme/pbi-theme/{theme,design-system,design-tokens,html-visual-style}/` | Operator-chosen folder (mode 1) | | `pbi-model-audit` (v0.2.1+) | A `.pbip` inside `/Power BI Repository///02_Build/` | `/03_Docs/internal/audit/{YYYY-MM-DD}/` | `{project_root}/_out … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [gusbavia](https://github.com/gusbavia) - **Source:** [gusbavia/pbi-lifecycle](https://github.com/gusbavia/pbi-lifecycle) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-gusbavia-pbi-lifecycle-pbi-lifecycle - Seller: https://agentstack.voostack.com/s/gusbavia - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.