# AGENTS.md — Power Apps Plugin

This file provides guidance to AI Agents when working with the **power-apps** plugin.

## What This Plugin Is

A plugin for building and deploying Power Apps code apps using React + Vite + TypeScript, connected to Power Platform via connectors (Dataverse, SharePoint, Teams, Azure DevOps, OneDrive, Excel, Office 365, and more). Apps are deployed via the Power Apps NPX CLI (`pa app push`).

## Local Development

Test this plugin locally:

```bash
claude --plugin-dir /path/to/plugins/power-apps
```

## Architecture

```
.plugin/plugin.json               <- Open Plugins metadata (name, version, keywords)
AGENTS.md                         <- Plugin guidance for AI agents (this file)
agents/
  code-app-architect.md           <- Agent persona for architecture decisions
shared/
  shared-instructions.md          <- Cross-cutting concerns (Windows CLI, safety, planning, memory bank)
  connector-reference.md          <- Connector patterns and generated service usage
  development-standards.md        <- Versioning, theme, build workflow, TypeScript strict mode
  memory-bank.md                  <- Memory bank format and usage
  planning-policy.md              <- Plan mode policy
  preferred-environment.md        <- Environment selection priority
  version-check.md                <- Version check instructions
skills/
  create-code-app/
    SKILL.md                      <- Scaffold, init, build, and deploy a new code app
    references/
      prerequisites-reference.md  <- Node, pac, git requirements
      troubleshooting.md          <- Common issues and fixes
  deploy/
    SKILL.md                      <- Build and deploy an existing code app
  list-connections/
    SKILL.md                      <- List Power Platform connections to get connection IDs
  add-datasource/
    SKILL.md                      <- Router: asks what you need and picks the right add-* skill
  add-connector/
    SKILL.md                      <- Generic fallback for any connector not covered by a specific skill
  add-dataverse/
    SKILL.md                      <- Add Dataverse tables with generated models and services
    references/                   <- Dataverse-specific reference docs
  add-sharepoint/
    SKILL.md                      <- Add SharePoint Online connector
    references/                   <- SharePoint-specific reference docs
  add-azuredevops/
    SKILL.md                      <- Add Azure DevOps connector
  add-teams/
    SKILL.md                      <- Add Microsoft Teams connector
  add-excel/
    SKILL.md                      <- Add Excel Online (Business) connector
  add-onedrive/
    SKILL.md                      <- Add OneDrive for Business connector
  add-office365/
    SKILL.md                      <- Add Office 365 Outlook connector
  add-mcscopilot/
    SKILL.md                      <- Add Copilot Studio agent connector
```

## Skills

| Skill | Description |
|-------|-------------|
| `/create-code-app` | Scaffold, configure, and deploy a new Power Apps code app |
| `/deploy` | Build and deploy an existing code app |
| `/list-connections` | List Power Platform connections to find connection IDs |
| `/add-datasource` | Add a data source (routes to the appropriate add-* skill) |
| `/add-dataverse` | Add Dataverse tables with generated TypeScript models and services |
| `/add-sharepoint` | Add SharePoint Online connector |
| `/add-azuredevops` | Add Azure DevOps connector |
| `/add-teams` | Add Microsoft Teams connector |
| `/add-excel` | Add Excel Online (Business) connector |
| `/add-onedrive` | Add OneDrive for Business connector |
| `/add-office365` | Add Office 365 Outlook connector |
| `/add-mcscopilot` | Add Copilot Studio agent connector |
| `/add-connector` | Add any other Power Platform connector |

## Key Concepts

### Connector-First Principle

Power Apps code apps run in a sandbox — direct HTTP calls (`fetch`, `axios`, Graph API, etc.) do not work at runtime. **All external data access must go through Power Platform connectors.**

### Generated Services

`pa app add data-source` generates typed TypeScript services in `src/generated/`:
- `src/generated/models/{Name}Model.ts` — TypeScript interfaces
- `src/generated/services/{Name}Service.ts` — CRUD methods

Always use generated services for data access.

### CLI

The Power Apps CLI (`@microsoft/power-apps-cli`) is installed locally via `npm install` as part of the app template. It ships two binaries — grouped **`pa`** (preferred) and flat **`power-apps`** (fallback). **Resolve which one the project has via [shared/cli-binary.md](./shared/cli-binary.md) first**, then invoke it with `npx --no-install <pa|power-apps>` from the project directory — runs natively in bash on all platforms, no PowerShell wrapper needed. Commands below use the canonical grouped `pa` form:

```bash
pa app push                   # Deploy app
pa app add data-source --connector ... # Add connector
pa connection list       # List connections
```

### Scaffolding

Always use `npx degit` to create new projects — never `git clone` or manual file creation:

```bash
npx degit microsoft/PowerAppsCodeApps/templates/vite {folder} --force
```

## Testing Changes

After modifying this plugin:

1. Run `claude --debug` to see plugin loading details
2. Test skill invocation with `/create-code-app`
3. Verify connector-first guardrails are enforced
4. Test CLI commands (`pa app push`, `pa app add data-source`, etc.)