Skip to content
This repository was archived by the owner on Nov 5, 2026. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions .agents/plugins/marketplace.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
{
"name": "Managed-Apps",
"plugins": [
{
"name": "microsoft-managed-apps",
"source": {
"source": "local",
"path": "./plugins/microsoft-managed-apps"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}
]
}
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
"name": "microsoft-managed-apps",
"source": "./plugins/microsoft-managed-apps",
"description": "[Preview] Create and manage Microsoft Managed Apps using the @microsoft/managed-apps-cli (ms) toolchain.",
"version": "2.1.6"
"version": "2.1.7"
}
]
}
41 changes: 41 additions & 0 deletions .github/workflows/pr.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
name: PR pipeline

on:
pull_request:
push:
branches: [main]
workflow_dispatch:

permissions:
contents: read

jobs:
plugin-compatibility:
name: Plugin compatibility (${{ matrix.os }})
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: actions/setup-node@v7
with:
node-version: '22'
- uses: actions/setup-python@v6
with:
python-version: '3.12'
- name: Install the pinned Agent Skills reference validator
run: python -m pip install -r scripts/requirements-plugin-validation.txt
- name: Validate manifests and marketplace entries
run: node scripts/validate-plugin-compatibility.mjs
- name: Test compatibility validation
run: node --test scripts/validate-plugin-compatibility.test.mjs
- name: Validate every packaged skill
run: python scripts/validate_plugin_skills.py
- name: Test skill validation
run: python -m unittest discover -s scripts -p "*_test.py"
- name: Test attribution hooks
run: node --test scripts/plugin-hooks.test.mjs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "microsoft-managed-apps",
"version": "2.1.6",
"version": "2.1.7",
"description": "[Preview] Create and manage Microsoft Managed Apps using the @microsoft/managed-apps-cli (ms) toolchain.",
"author": {
"name": "Microsoft",
Expand Down
46 changes: 39 additions & 7 deletions plugins/microsoft-managed-apps/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,14 +115,17 @@ skills/<skill-name>/
---
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
allowed-tools: Read Edit Write Grep Glob Bash AskUserQuestion
---

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

Use only [Agent Skills frontmatter fields](https://agentskills.io/specification).
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

| Agent | Purpose |
Expand All @@ -133,6 +136,35 @@ model: sonnet # or opus for design-heavy work

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.
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](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.
Keep both hook payload contracts when editing a script.

The canonical manifest follows [Agent Plugins 1.0.0](https://agent-plugins.org/specification).
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.
168 changes: 168 additions & 0 deletions plugins/microsoft-managed-apps/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,8 @@ The `/create-app` skill handles the global install of `@microsoft/managed-apps-c

## Install the plugin

### Claude Code and GitHub Copilot

1. Open your copilot in any project folder:
```
claude
Expand All @@ -59,6 +61,169 @@ The `/create-app` skill handles the global install of `@microsoft/managed-apps-c
/plugin install microsoft-managed-apps@Managed-Apps
```

### Agent Plugins and Codex discovery

The canonical manifest is `plugins/microsoft-managed-apps/plugin.json`, relative to the repository root.
It declares the [Agent Plugins 1.0.0 schema](https://agent-plugins.org/specification).
The published format uses root `plugin.json`, not `.plugin/plugin.json`.
Compatible clients discover the existing `skills/` directory from this plugin root.
This package does not bundle an MCP server, so it does not need `mcp.json`.

For Codex, the repository includes `.agents/plugins/marketplace.json`, following the
[Codex packaging guide](https://developers.openai.com/plugins/build/plugins).
Its entry points to the same plugin directory as the existing Claude marketplace.

To evaluate a local checkout containing these changes:

1. Add its repository root with `codex plugin marketplace add <checkout-path>`.
2. Open the Plugins Directory in the ChatGPT desktop app with Codex plugin support.
3. Select `Managed-Apps` and install `microsoft-managed-apps`, following the current Codex packaging guide.
4. Start a new session before checking the installed skills.

**Compatibility status:** the portable package does not establish full Codex runtime support.
Skills use document-relative links to shared resources. They do not require `${CLAUDE_PLUGIN_ROOT}`.
The package does not provide a Codex architect agent or Codex hooks.
Shared instructions request `plugin/codex` attribution while preserving an existing `MS_CLI_ORIGIN` value.
This attribution depends on the agent following instructions, not hook enforcement.
Complete the client checks below before using workflows that change resources.

### Compatibility layout and model selection

| Path within the plugin | Consumer and purpose |
| --- | --- |
| `plugin.json` | Canonical Agent Plugins 1.0.0 metadata. |
| `.claude-plugin/plugin.json` | Claude Code and legacy clients. Regular JSON mirror, excluding only `$schema`. |
| `skills/` | One portable skill set for all clients. |
| `agents/microsoft-apps-architect.md` | Claude Code and legacy Copilot architect. |
| `com.github.copilot/agents/microsoft-apps-architect.agent.md` | Architect copy for Copilot's Agent Plugins discovery. Only relative resource paths differ. |
| `hooks/hooks.json` | Claude Code and legacy Copilot hook configuration. |
| `com.github.copilot/hooks/hooks.json` | Native Copilot hook configuration using `${PLUGIN_ROOT}`. |
| `hooks/*.sh` and `hooks/*.ps1` | Shared executable hooks. Both configurations run these same scripts. |

Keep the Claude manifest. Claude still reads it even when a newer Copilot selects the root manifest.
Neither marketplace nor plugin identity changes. All compatibility copies are regular files, not symlinks.

**Intentional behavior change for review:** skills now inherit the model selected in the client.
Version 2.1.4 requested Sonnet or Opus through Claude-specific `model` fields.
The portable skill set removes those overrides instead of duplicating skill definitions.
This can change response quality, speed, and cost for Claude users.
The team must review this exception to issue #34's unchanged-behavior requirement.
The removed `user-invocable: true` field matches Claude's default, so skills remain user-invocable.
The workflow instructions and tool permissions remain, with portable resource links.

Version 2.1.6 includes `/add-backend`, bringing the current package to 22 skills.
The recorded 2.1.4-to-2.1.5 results below cover the earlier 21-skill package.

### Package maintenance and validation

The legacy `.claude-plugin/plugin.json` is a regular JSON mirror of the canonical manifest, excluding only `$schema`.
This preserves the legacy format while the canonical manifest declares the Agent Plugins version.
Do not replace either file with a symlink.
The existing `.claude-plugin/marketplace.json` installation path, marketplace identity, and plugin identity remain unchanged.

From the repository root, run:

```sh
node scripts/validate-plugin-compatibility.mjs
node --test scripts/validate-plugin-compatibility.test.mjs
python -m pip install -r scripts/requirements-plugin-validation.txt
python scripts/validate_plugin_skills.py
python -m unittest discover -s scripts -p "*_test.py"
node --test scripts/plugin-hooks.test.mjs
```

Run the Python commands in a virtual environment with Python 3.11 or later.
Python is a development dependency, not a new requirement for plugin installation.
The existing Bash hooks still require a working Python interpreter.

The generic `PR pipeline` workflow in `.github/workflows/pr.yml` runs plugin compatibility as its first and only job.
This job runs these checks on Windows and Ubuntu. Add future PR checks as separate jobs in the same workflow.
To block merges, require both platform-specific `Plugin compatibility` checks in the repository ruleset.
Validation checks manifests, regular files, metadata equivalence, marketplace identity, architect copies, hook configurations, and local resource links.
The pinned Agent Skills reference library checks every immediate skill directory.
Regression tests reject invalid skill metadata, missing components, and compatibility drift.
Hook tests check both payload formats, command attribution, user overrides, and paths containing spaces.
Windows tests execute PowerShell scripts. Ubuntu tests execute Bash scripts.
Only the canonical `$schema` field is excluded from the manifest comparison.
Object key order and whitespace do not affect the comparison.
Update both manifests and the legacy marketplace version together for each release.

### Client test matrix

Package checks cannot prove client runtime compatibility.
Record the exact client version, OS, source revision, commands, observed components, and results for each row.
Run install and upgrade checks in disposable client profiles, never an existing customer profile.
Do not mark an unexecuted check as passed.

| Client and scenario | Required result | Current evidence |
| --- | --- | --- |
| Claude Code, fresh install | 22 skills, architect, both hooks, resource links, daily version check, selected model, `/create-app`, and one `/add-*`. | Pending. Claude is not installed on the implementation machine. |
| Claude Code, upgrade from 2.1.4 | Same components after update, without reinstalling. Existing marketplace and plugin identities remain. | Pending. |
| Copilot CLI, fresh install on Windows | 22 skills, architect from `com.github.copilot`, both hooks, resource links, daily version check, and user attribution overrides. | Earlier local marketplace installation and discovery passed for 21 skills. Runtime agent and hook loading remain pending. |
| Copilot CLI, upgrade from 2.1.4 on Windows | Same components and identity after update, without reinstalling. | Local marketplace changed from 2.1.4 to 2.1.5 with the same 21 skill names and one `Managed-Apps` registration. Git-backed update and runtime checks remain pending. |
| Codex, fresh install | 22 skills, resolved shared resources, representative CLI attribution, and documented absence of bundled agents/hooks. | Pending. Codex is not installed on the implementation machine. |
| Windows and Linux client flows | Fresh and upgrade results agree across platforms. | Windows local discovery evidence only. Both CI platforms are configured. Linux client flows remain pending. |
| Activation and updates | Disable and enable without reinstalling. No duplicate identity. Malformed or drifted compatibility files fail CI. | Negative package checks pass locally. Activation remains pending because the installed CLI rejects the documented enable/disable subcommands. |

The Windows checks ran on 2026-10-26.
`copilot --version` reported `1.0.102-0.unstable.r40029025960.g5a14a15`.
The local CLI dispatcher supports installation and skill listing but rejects `plugin list --json` and `plugin enable`/`disable`.
These limits prevent a full runtime-support claim.

#### Commands and evidence

For a fresh Copilot check, set `COPILOT_HOME` to an empty disposable directory.
Set `COPILOT_AUTO_UPDATE=false` to prevent unrelated marketplace updates.
Run these commands from a disposable project:

```text
copilot --version
copilot plugin marketplace add <repository-root>
copilot plugin install microsoft-managed-apps@Managed-Apps
copilot plugin list
copilot plugin marketplace list
copilot skill list --json
```

Captured local results: installation reported `Installed 21 skills`.
The plugin list contained one enabled `microsoft-managed-apps@Managed-Apps (v2.1.5)` entry.
The skill list contained all 21 packaged skill names.

For the local upgrade check, export baseline commit `a069a3a2b8702db7f2cff2499b3162d2fee3d539` with `git archive`.
Include `plugins/microsoft-managed-apps` and `.claude-plugin/marketplace.json`.
Extract the archive into a disposable marketplace directory.
Register and install that directory with the fresh-install commands above.
Capture the 2.1.4 plugin and skill lists.
Replace its plugin files and marketplace manifest with the candidate files, without changing its registered path.
Then run:

```text
copilot plugin marketplace update Managed-Apps
copilot plugin update microsoft-managed-apps@Managed-Apps
copilot plugin list
copilot plugin marketplace list
copilot skill list --json
```

Captured local results: version changed from 2.1.4 to 2.1.5, all 21 skill names matched, and one marketplace registration remained.
The CLI reported that the local plugin loads live and needs no copy or reinstall.
This does not prove a Git-backed cache update.

For Git-backed Claude and Copilot upgrades, install baseline 2.1.4 through a disposable marketplace pointing at that revision.
Advance that same source to the candidate revision.
In each client's interactive session, run `/plugin marketplace update Managed-Apps` and `/plugin update microsoft-managed-apps@Managed-Apps`.
Do not uninstall, reinstall, or add another marketplace.
Record `/plugin`, `/skills`, and `/agent` results using the commands supported by that client version.
Run the client's enable/disable actions and confirm that the same components return.

For each supported Claude and Copilot runtime, run `ms --version` through a shell tool.
Capture the rewritten command or CLI attribution evidence.
Repeat with `MS_CLI_ORIGIN=review/custom` already set and confirm that the hook preserves it.
Check session-start guidance and the daily version-check instructions.
Run `/create-app` and a representative `/add-*` only in an authorized test environment.
For Codex, verify the documented instruction-based attribution instead of expecting a hook.
Attach client versions, commands, and sanitized results to the PR before claiming full runtime compatibility.

## Try it

```
Expand All @@ -75,6 +240,9 @@ This plugin sets an attribution tag on the `@microsoft/managed-apps-cli` (`ms`)
- **What it does not do:** it does not run for non-`ms` commands, and it does not transmit anything itself.
- **Opting out:** set `MS_CLI_ORIGIN` yourself (in your shell environment or inline on the command) and the hook leaves your value untouched. You can also disable the hook by removing/editing `hooks/hooks.json`, or refer to the `ms` CLI documentation for its own telemetry controls.

For Agent Plugins Copilot, the hook configuration is `com.github.copilot/hooks/hooks.json`.
Disable hooks in the client's settings rather than editing only the legacy configuration.

## Uninstall

```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ name: microsoft-apps-architect
description: Managed apps Architect specializing in React/Vite architecture, the @microsoft/managed-apps-cli (ms) toolchain, connector and data-source patterns, and local-dev-first iteration. Use when making architecture decisions, designing data models, selecting connectors, or troubleshooting `ms app create` / `ms app dev` / build issues.
---

**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** - Cross-cutting concerns (CLI install, env vars, planning, memory bank, execution style).
**📋 Shared Instructions: [shared-instructions.md](../shared/shared-instructions.md)** - Cross-cutting concerns (CLI install, env vars, planning, memory bank, execution style).

# Managed apps Architect

Expand Down
Loading