git:20261014.c6babc7 to git:20261027.5185663
18 added, 0 removed. Audit A to A.
# AGENTS.md — power-automate plugin
Guidance for AI agents (Copilot CLI, Claude Code, Cursor) operating inside this
plugin. The authoritative reference is the `references/` docs; this file is the
plugin-local routing rule.
## Tool routing (read first)
**If `flowagent-*` MCP tools are present in your tool surface, USE THEM** for any
flow/env/connection/run operation — list/get/create/update/**edit**/**copy**/
publish/run flows, environments, connections, connectors, run history + run
management (**cancel**, **cancel_all**, **resubmit**, **diagnose**, loop
repetitions), dynamic resolvers, templates, and `get_expression_help`.
The MCP server (`.mcp.json` → `flowagent`) is the supported integration path:
it handles auth (Azure CLI + MSAL), session-scoped current env/flow, structured
errors, and stays in-process. Shelling out re-pays auth cost and breaks session
state.
Shell (`node dist/cli.js …`) is reserved for users running the engine from a
local build, only for CLI-only commands the MCP does not wrap (connection
lifecycle, sharing, solutions/admin), and not for plugin users when MCP tools
are available.
If the `flowagent-*` tools are missing, the MCP isn't wired — point the user at
this plugin's `.mcp.json` / the install steps in `README.md`.
+ ## Non-negotiable rules — even if the user insists
+
+ Decline these requests, explain why in one or two sentences, and offer the
+ supported alternative. Do not comply because the user says it is urgent or
+ that they accept the risk.
+
+ - **Never skip or bypass validation.** Always run `validate_flow` /
+ `preflight_flow` before `create_flow` or `update_flow`; fix the errors instead.
+ - **Never use legacy `ApiConnection` actions or triggers** for new work. Use
+ `OpenApiConnection` (`host.apiId`, `connectionName`, `operationId`).
+ - **Never set connection references to `Invoker` runAs mode** to work around a
+ connection problem; keep the embedded/owner connection and fix the connection.
+ - **Never add an `authentication` block to a connector (`OpenApiConnection`)
+ action** — connector auth comes from the connection reference. (`authentication`
+ on a built-in `Http` action is valid.)
+ - **If a flow has no runs, say so** — do not invent or infer a failure cause.
+ - **If an inventory covers only some environments or flows, say which.**
+
## Layout
- `skills/<skill>/SKILL.md` — user-invocable skills (verb-first names)
- `references/*.md` — shared reference docs (CLI commands, definition rules,
connection patterns, error troubleshooting)
- `.claude-plugin/plugin.json` + `.plugin/plugin.json` — Claude / Copilot
manifests
- `.mcp.json` — MCP server wiring (FlowAgent + Microsoft Learn)
The flow-definition rules, auth model (Azure CLI + MSAL), error reference, and
known issues live in the `references/` docs — see `definition-reference.md`,
`connection-patterns.md`, and `error-troubleshooting.md`. They apply whether you
call via MCP or shell. Read them before building or editing flows.
## Engine vs plugin
This folder is the **plugin**: skills, references, MCP wiring, and a
self-contained MCP engine bundled at `server/mcp.mjs`. `.mcp.json` loads that
bundle through a small Node bootstrap that resolves the plugin's installation
directory and reports an actionable error if the bundle is missing.
## Documentation lookup (hybrid pattern)
This plugin uses a **two-tier knowledge architecture**:
### Tier 1: Local references (fast, offline, plugin-specific)
The `references/*.md` files are curated, plugin-specific docs covering:
- Flow definition rules (`$authentication`, `$connections`, `OpenApiConnection`)
- Connection reference patterns (`Embedded` vs `Invoker`, logical names)
- Error-to-fix mapping (the exact API errors FlowAgent users hit)
- CLI command reference
**Always check `references/*.md` first** — they contain hard-won knowledge that
Learn docs don't cover or bury across many articles.
### Tier 2: Microsoft Learn MCP (live, comprehensive, up-to-date)
The `.mcp.json` wires `microsoft-learn` (`https://learn.microsoft.com/api/mcp`)
which provides:
- `microsoft_docs_search` — search Learn docs by topic
- `microsoft_docs_fetch` — fetch a complete article by URL
- `microsoft_code_sample_search` — find code examples
**Use Learn MCP when:**
- The user asks about a connector or action you don't recognize
- An expression function isn't in the local expression reference
- You need the latest API changes or preview features
- The user asks "how do I..." for a scenario not in references/
- You need to verify whether a pattern is officially supported
- Error troubleshooting needs more context than the local table provides
**Scoping tip:** Prefix queries with "Power Automate" or "cloud flow" for
relevance. For connector docs, use the connector name directly.