Power Platform — Non-Negotiable Standards

These rules are always active. They apply to every skill, every interaction.

Three-Layer Architecture (Code Apps)

src/components/  → Presentation only. Props in, callbacks out. Zero service calls.
src/hooks/       → Business logic. The ONLY layer that calls generated services.
src/generated/   → Auto-generated by PAC CLI. NEVER manually edit.

Hard Rules

• Always use PAC CLI-generated services — never raw fetch/axios
• Always use $select on every Dataverse query — never fetch all columns
• Always handle loading, error, and empty states in every component
• Always use TypeScript strict mode — no any types
• Never hardcode environment URLs, GUIDs, or secrets
• Never embed secrets in source code (published Code Apps are publicly accessible)
• Router basename must be normalized for Power Apps hosting
• Provider stack order: ThemeProvider → SonnerProvider → QueryProvider → RouterProvider

Accessibility (WCAG 2.2 AA — Mandatory)

• Semantic HTML first (<button>, <nav>, <main>) — ARIA is a last resort
• Every form input has a label, every icon button has aria-label
• Visible :focus-visible on all interactive elements
• Skip-to-main-content link, aria-live regions for dynamic content
• 4.5:1 text contrast, 3:1 for UI elements, never color alone for information
• Content reflows at 320px and 200% zoom without horizontal scroll
• Accessibility is part of EVERY code review, not a separate pass

ALM (Always — From Day One)

• Solution-aware from the start
• Environment variables for all environment-specific values
• Managed solutions for test/prod — never import unmanaged to production
• Connection references for all flow connections
• Version increment on every deployment

Agent Team

You have access to 6 agent skills and 33 domain skills for Power Platform development. For agent selection, workflows, and skill loading guidance, use the /power-platform-team skill.

Naming Conventions

Publisher & Solution

Dataverse Schema

Components

Code Apps (React/TypeScript)

Canvas Apps

Web API-First Development Workflow

When building Power Platform solutions from Claude Code, the primary workflow is:

1. Authenticate via Azure CLI
2. Create publisher + solution (if not exists)
3. Build schema via Web API HTTP calls (tables → columns → relationships → views → forms → app)
4. Components land in the solution in real-time (via MSCRM.SolutionUniqueName header)
5. Publish customizations
6. Verify in the maker portal

When to Use Each Approach

Authentication

# Azure CLI (interactive — for development)
az account get-access-token \
  --resource "https://[org].crm6.dynamics.com/" \
  --tenant "[tenant-id]" \
  --query accessToken -o tsv

# Service Principal (CI/CD — for automation)
TOKEN=$(curl -s -X POST "https://login.microsoftonline.com/${TENANT_ID}/oauth2/v2.0/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=https://${ORG}.crm.dynamics.com/.default" \
  | jq -r '.access_token')

Critical Web API Rules

• ALWAYS include MSCRM.SolutionUniqueName header on component creation
• ALWAYS include @odata.type on attribute/column creation payloads
• ALWAYS create publisher + solution FIRST
• ALWAYS publish after form/view/sitemap changes
• On Windows, use PowerShell .ps1 scripts (bash mangles OData params)
• Some decisions are PERMANENT: table logical name, column data type, ownership type

Documentation Standards

Architecture Decision Records (ADR)

Every significant design decision must be documented as an ADR:

• File naming: docs/adr/ADR-NNN-description.md
• ADRs are never deleted — superseded ADRs are marked as such

Entity Relationship Diagrams

• Use Mermaid erDiagram syntax
• Include: PK/FK markers, data types, relationship cardinality
• Separate diagrams for: core domain, security model, integration points

Project README

Every Power Platform project should include:

• Solution overview and business context
• Environment URLs (dev/test/prod)
• Service principal details (client IDs, not secrets)
• Deployment instructions
• Required environment variables and connection references
• Known limitations and technical debt

Deployment Runbook

For production deployments:

• Pre-deployment checklist (backups, approvals, change window)
• Step-by-step deployment process
• Post-deployment verification steps
• Rollback procedure
• Emergency contacts