Microsoft Managed Apps Plugin — Development Guidelines

This file provides instructions for assistants working on the managed apps plugin itself (not for end-users of the plugin).

Overview

The managed apps plugin wraps @microsoft/managed-apps-cli (binary ms) to scaffold, develop, and ship managed apps 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 the app backend database with ms app add backend --provider rayfin. 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 and the Rayfin feature is enabled)
   └── /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.
user-invocable: true
allowed-tools: Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion, ...
model: sonnet  # or opus for design-heavy work
---

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

Agent

Testing changes

After modifying this plugin:

1. Bump the version field in .claude-plugin/plugin.json and the matching plugin entry in the repo-root .claude-plugin/marketplace.json.
2. Test in a fresh project: /create-app end-to-end, then a representative /add-*.
3. Verify any new allowed-tools entries are minimal — request only what the skill needs.