Copilot Managed Runtime Plugin — Development Guidelines

This file provides instructions for assistants working on the Copilot Managed Runtime plugin itself (not for end-users of the plugin).

Overview

The Copilot Managed Runtime plugin wraps @microsoft/cmr-cli (binary ms) to scaffold, develop, and ship apps on Copilot Managed Runtime end-to-end. It provides skills for:

• Creating a new app (/create-app) — global install of the CLI, scaffold, local dev loop.
• Iterating locally (/dev) — ms app dev, hot reload against the App Player.
• Lifecycle ops (/deploy, /share, /delete-app, /list-apps).
• Defining an app backend database (/add-backend) — entities and a typed runtime client.
• Binding data sources (/add-dataverse, /add-sharepoint, etc.) — generates typed TypeScript services under src/.

Memory Bank System

This plugin uses a memory bank (memory-bank.md) to persist state across sessions.

• Location: <PROJECT_ROOT>/memory-bank.md (in the user's project, not the plugin).
• Instructions: See shared/memory-bank.md for the full schema.
• Skills read the memory bank at start and update it after major steps. The schema records the environment id the CLI resolved for reference only (e.g. reconstructing the App Player URL); it is not used to re-target ms app create, which resolves an environment automatically each run.

Shared Resources

Adding new shared instructions

1. Create the file in shared/ (e.g., new-policy.md).
2. Add a section to shared/shared-instructions.md referencing it.
3. No changes needed to individual SKILL.md files — they already link to shared-instructions.md.

Skills

Stage 1: scaffold

Stage 2: lifecycle

Stage 3: data sources

App backend database

Setup: /add-backend scaffolds backend configuration and code with ms app add backend --provider rayfin; scaffolding does not provision the database. Its local references use the installed SDK docs for API guidance.

Select it only for an explicit app backend database request (including /add-backend or Rayfin).

All Rayfin work requires the Rayfin feature gate.

Workflow

/create-app
   └── /dev (default loop)
   └── /add-backend (when explicitly requested)
   └── /add-data-source (or a specific connector skill)
   └── /deploy (explicit, requires confirmation)
   └── /share, /delete-app (explicit, require confirmation)

Skill structure

skills/<skill-name>/
├── SKILL.md                  # Workflow
└── references/               # Optional deep-dive docs
    └── <topic>-reference.md

Skill header

---
name: kebab-case-name
description: Short, action-oriented sentence the model uses for retrieval. Mention `ms` CLI verbs explicitly.
allowed-tools: Read Edit Write Grep Glob Bash AskUserQuestion
---

**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns.

Use only Agent Skills frontmatter fields. Keep one skill set for all clients. Do not add model or user-invocable. Skills inherit the client's selected model. Claude's default keeps skills user-invocable. Resolve resource links relative to the containing Markdown file, not the user's project.

Agent

Testing changes

After modifying this plugin:

1. Update the canonical plugin.json at this plugin's root, including its version.
2. Copy its metadata to .claude-plugin/plugin.json, excluding only $schema. Keep both files as regular JSON files, never symlinks.
3. Update the matching version and description in the repo-root .claude-plugin/marketplace.json. Preserve its marketplace name, plugin name, and source path.
4. Keep the repo-root .agents/plugins/marketplace.json entry pointed at this same plugin directory.
5. Run node scripts/validate-plugin-compatibility.mjs from the repository root.
6. Run node --test scripts/validate-plugin-compatibility.test.mjs from the repository root.
7. Install validation dependencies with python -m pip install -r scripts/requirements-plugin-validation.txt in a virtual environment.
8. Run python scripts/validate_plugin_skills.py.
9. Run python -m unittest discover -s scripts -p "*_test.py".
10. Run node --test scripts/plugin-hooks.test.mjs.
11. Follow the client test matrix in README.md before claiming runtime compatibility.
12. Verify any new allowed-tools entries are minimal — request only what the skill needs.

Keep agents/microsoft-apps-architect.md as the source for the architect. Copy it to com.github.copilot/agents/microsoft-apps-architect.agent.md after each edit. Change its ../shared/ links to ../../shared/ and ../skills/ links to ../../skills/ in the copy. The validator rejects any other difference.

Keep executable hooks in hooks/. Do not copy their scripts. Claude and legacy Copilot discover hooks/hooks.json. Agent Plugins Copilot discovers com.github.copilot/hooks/hooks.json. The latter uses native Copilot events, ${PLUGIN_ROOT}, and the same scripts. Validation checks both configurations for equivalent scripts, matchers, and timeouts. Only the native Copilot entry point passes --github-copilot / -GitHubCopilot to report MS_PLUGIN_REPORT_AGENT=github-copilot. Shared hooks must remove inherited reports. Do not detect the host from environment markers or shell type. Keep the agent report independent of MS_CLI_ORIGIN=plugin and user-provided origin overrides. Keep both hook payload contracts when editing a script.

The canonical manifest follows Agent Plugins 1.0.0. That version requires root plugin.json, not the older .plugin/plugin.json layout. The generic PR pipeline workflow in .github/workflows/pr.yml contains one job: plugin compatibility. This job checks manifests, component compatibility, resource links, skill validity, and hooks on Windows and Ubuntu. The Python dependency is the Agent Skills reference validator, pinned to a Git commit. Add future PR checks as separate jobs in this workflow. Client installation, updates, shared-resource resolution, and hook behavior still need host-level checks before claiming support for a new client.