add-dataverse

name	add-dataverse
description	Use when the user wants to add Dataverse tables (existing or new) to a Power Apps mobile app, extend an existing Dataverse table with new columns, or apply an approved data model plan.
user-invocable	true
allowed-tools	Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion, EnterPlanMode, ExitPlanMode, Task
model	opus

📋 Shared instructions: shared-instructions.md — read first.

Add Dataverse

Two paths:

• Existing tables only — skip to Step 5 (just runs npx power-apps add-data-source per table)
• New / extended tables — full workflow with Web API mutations in dependency order

Workflow

1. Verify project & auth → 2. Resolve plan → 3. Setup Dataverse Web API auth → 4. Review existing tables → 5. Create / extend tables → 5d. Create alternate keys → 6. Add data sources → 6b. Publish customizations → 6c. Verify tables → 6d. Write manifest → 7. Inspect generated files → 8. Type-check → 8.5. Offline profile reconciliation → 9. Summary

---

Step 1 — Verify project & auth

Confirm Power Apps mobile app:

test -f power.config.json && test -f app.config.js
node "${CLAUDE_SKILL_DIR}/../../scripts/resolve-environment.js" "$(node -e \"console.log(require('./power.config.json').environmentId)\")"

Capture the environment URL (https://orgXXX.crm.dynamics.com), environment ID, and tenant ID from resolve-environment.js — needed for Step 3. If only the environment URL is available, pass that URL instead of the ID.

Step 2 — Resolve plan

Look for native-app-plan.md in the project root:

test -f native-app-plan.md

If present: read the ## Data Model section. Extract:

• The reuse / extend / create table
• The Mermaid ER diagram (informational)
• The "Creation Order" tier list

If absent: check $ARGUMENTS for diagram hints (*.png, *.jpg, *.jpeg filename, erDiagram keyword, ||--o{ cardinality syntax).

• Diagram hint present → Path A (Step 2.5).

• No hint AND $ARGUMENTS describes what the app does (the typical case) → silently take Path B (Step 2.6 — spawn architect). No prompt.

• No hint AND $ARGUMENTS is empty / non-descriptive → only then prompt with AskUserQuestion:

  "How would you like to define the data model? (a) I have an existing ER diagram to upload (PNG/JPG path, Mermaid syntax, or text description) (b) Let the data-model-architect agent analyze and propose one (default) (c) Cancel — I'll plan it elsewhere first"

  Default the answer to (b) so empty/cancel input auto-proceeds. The 99% case (user gave a description but no diagram) skips this prompt entirely.

Step 2.5 — Path A: Parse user-provided diagram

Used when the user has an existing diagram from another tool (Visio, dbdiagram.io, screenshot, hand-drawn).

Accept three input formats:

Format	How
Image path (*.png / *.jpg / *.jpeg)	Use Read on the file path. The vision-capable model extracts entities, columns, relationships.
Mermaid syntax	User pastes a erDiagram block in chat. Parse the entities, columns, and ||--o{ cardinalities directly.
Text description	User types a structured description ("Account has many ServiceVisits; each ServiceVisit has many WorkItems and Photos"). Spawn data-model-architect agent in parse-only mode with the text as input.

Whichever format, normalize into the same structure used by the planner agent:

publisherPrefix: <from detected publisher prefix or user>
tables:
  - logicalName: contoso_servicevisit
    displayName: Service Visit
    status: new   # new | extend | reuse
    columns: [...]
    relationships: [...]

Then:

1. Query existing Dataverse (Step 4 logic) to mark each table as new, modified, or reused.
2. Generate a Mermaid ER diagram from the parsed structure for visual confirmation.
3. Present back to the user via EnterPlanMode for approval.
4. On ExitPlanMode, write the approved data model into native-app-plan.md ## Data Model section (creating the file if it doesn't exist).
5. Continue to Step 3.

Step 2.6 — Path B: Spawn architect agent

If the user picked Path B (or the user-provided diagram parse failed), spawn the mobile-app:data-model-architect agent via Task (the mobile-app: plugin-name prefix is required) with the user's high-level requirements as input. The agent returns _dm_section.md. Embed it in native-app-plan.md, present via EnterPlanMode for approval, then continue to Step 3.

If they need new tables and refuse both paths, recommend they run /setup-datamodel (alias of this skill) explicitly, or native-app-planner for a full app-level plan. STOP if neither.

Step 3 — Setup Dataverse Web API auth

Required only if creating or extending tables. Skip to Step 5 for read-only add-data-source.

Step 3a — Environment consistency check

npx power-apps and az authenticate independently — they can point to different accounts. Verify power.config.json resolves and az can token for the target tenant before making any Dataverse API calls:

ENV_JSON=$(node "${CLAUDE_SKILL_DIR}/../../scripts/resolve-environment.js" "$(node -e \"console.log(require('./power.config.json').environmentId)\")")
echo "$ENV_JSON"
az account show --query "{user: user.name, tenant: tenantId}" -o json

Compare the resolved environment URL with <envUrl> captured in Step 1. If they differ, STOP and warn:

"⚠️ Environment mismatch detected:

• resolver reports: <resolved_env_url>
• This project targets: <envUrl>

The Dataverse API token comes from az, which must target the same tenant as the selected environment. Run:

az login --tenant <tenant-id>      # switch az to the right tenant

Then re-run /add-dataverse."

Do NOT proceed with table creation if environments don't match — you'll create tables in the wrong org.

Step 3b — Acquire token

az account show --query "user.name" -o tsv

If empty, instruct az login and stop.

Script invocation contract — read this once, all subsequent calls in this skill follow it:

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> <METHOD> <apiPath> [--body '<json>'] [--include-headers]

• Three positional args, in order: <envUrl>, <METHOD> (GET / POST / PATCH / DELETE), <apiPath> (everything after /api/data/v9.2/).
• Body is a flag, not positional. --body '<json>' — required for POST/PATCH, never for GET/DELETE. Forgetting --body and passing the JSON as a 4th positional arg returns a usage error.
• --include-headers adds response headers (needed for OData-EntityId after a record create).
• Output is JSON: { "status": <code>, "data": <body> }. Token refresh on 401 and back-off on 429 are automatic — never wrap with manual retry.

Acquire a Dataverse access token and verify connectivity:

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET WhoAmI

WhoAmI is the Dataverse identity endpoint — capital W/A/I (case-sensitive). The response gives UserId, BusinessUnitId, OrganizationId but does NOT include the publisher prefix. To get the publisher prefix, query the solution's publisher (defaults to Default; pass a different solution name if the env uses a custom solution):

node "${CLAUDE_SKILL_DIR}/../../scripts/detect-publisher-prefix.js" <envUrl> [solutionName]
# solutionName defaults to "Default" if omitted

This runs the OData query: /api/data/v9.2/solutions?$select=uniquename&$expand=publisherid($select=customizationprefix)&$filter=uniquename eq '<solutionName>'

Capture customizationprefix from the solution's publisher (typical value: cr123 → schema names like cr123_jobsite). Also capture the solution uniquename — needed for the --solution flag on every Step 5 / 5b POST so artifacts land in our solution rather than landing wherever Dataverse defaults. Write both to memory-bank.md Power Platform context block.

Requires the user to hold System Administrator or System Customizer in this environment.

Step 4 — Review existing tables

Print before starting:

"→ Querying existing custom tables in the environment…"

Always query before creating:

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \
  "EntityDefinitions?\$filter=IsCustomEntity eq true&\$select=SchemaName,LogicalName,DisplayName"

For each plan entry classified Reuse or Extend, fetch the table's columns to confirm the match:

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \
  "EntityDefinitions(LogicalName='<table>')/Attributes?\$select=LogicalName,AttributeType,RequiredLevel"

Schema divergence handling is in Step 5b's per-column pre-flight (not a Step 4 prompt). The pre-flight auto-skips columns that already exist with the same type, and STOPs only on incompatible type drift — no separate confirmation needed here.

Step 5 — Create / extend tables

Print before starting:

"→ Creating/extending tables in tier order (sequential — Dataverse serializes metadata writes). For each: pre-flight check, then 'Creating

…' before the POST and '✓ ' on 2xx response."

⚠️ Concurrency rule — do not violate. All Dataverse metadata operations in Steps 5, 6, and 6b are strictly sequential: issue one HTTP request, wait for a 2xx response, then issue the next. Do NOT batch, parallelize, or fire concurrent requests. Dataverse serializes metadata writes via an exclusive lock; parallel calls return 429 TooManyRequests, MetadataLockHeldException, or 404 EntityNotFound for lookups whose parent hasn't committed yet.

Specifically:

• Within a tier: create tables one at a time.
• Across tiers: Tier 0 fully done (all tables + all columns committed) before any Tier 1 POST.
• Lookups: POST to /RelationshipDefinitions only after both endpoint tables exist and have returned 2xx.
• Extensions: column POSTs to an existing table are also serial — same lock applies.

Step 5a — Pre-flight collision check (per table, before each POST)

Step 4 listed known custom tables you intend to reuse. Step 5a probes for unknown problems on a per-create basis: name-prefix collisions from stale solutions, soft-deleted tombstones, and reserved system names. Skipping this check costs ~1 minute per failed POST (Dataverse takes its time returning the conflict error) and can leave Tier 0 partially created when a Tier 1 lookup fails on a phantom parent.

For every Create entry, before its POST, probe the target logical name:

node "${CLAUDE_SKILL_DIR}/../../scripts/dataverse-request.js" <envUrl> GET \
  "EntityDefinitions(LogicalName='<prefix>_<table>')?\$select=MetadataId,LogicalName,IsCustomEntity"

Branch on the response:

Status / body	Meaning	Action
404 NotFound	Name is free	Proceed with POST.
200 OK + IsCustomEntity: true + matches memory-bank