Compare commits
5 Commits
v1.0.0
...
0aa66fe65d
| Author | SHA1 | Date | |
|---|---|---|---|
| 0aa66fe65d | |||
| fc69553ba7 | |||
| c48c9f5490 | |||
| 0e421acdbb | |||
| 1d07d1a76b |
74
docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md
Normal file
74
docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md
Normal file
@@ -0,0 +1,74 @@
|
|||||||
|
# Microsoft APM replaces the hand-authored plugin/marketplace model as this repo's authoring source of truth
|
||||||
|
|
||||||
|
This repo replaces its hand-maintained Claude Code plugin/marketplace authoring model
|
||||||
|
(`.claude-plugin/marketplace.json` + per-plugin `plugin.json`) with Microsoft APM (`apm.yml` +
|
||||||
|
`.apm/`) as the authoring source of truth — an outright replacement of the authoring layer, not an
|
||||||
|
additive overlay. This ADR records the decision from a `grill-with-docs` session on issue #88.
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
Every plugin under `plugins/<name>/` currently ships two hand-maintained manifests
|
||||||
|
(`.claude-plugin/plugin.json` for Claude Code, root `plugin.json` for Copilot CLI) plus a
|
||||||
|
hand-maintained root `.claude-plugin/marketplace.json` listing all plugins. Adding a provider means
|
||||||
|
hand-authoring a third manifest shape; keeping the two existing ones in parity is itself a tracked
|
||||||
|
concern (ADR-0006).
|
||||||
|
|
||||||
|
Research on Microsoft APM (`plugins/kyberforge/docs/research/docs/microsoft-apm/`) found that its
|
||||||
|
documented "monorepo-hybrid" repo shape maps directly onto this repo's existing `plugins/<name>/`
|
||||||
|
layout: each plugin becomes its own `apm.yml` + `.apm/{skills,agents,hooks,prompts,instructions}/`
|
||||||
|
package, listed from a root `apm.yml`'s `marketplace:` block. `apm compile`/`apm pack` generate
|
||||||
|
per-target output — including a `.claude-plugin/marketplace.json` — from that vendor-neutral
|
||||||
|
`.apm/` tree, so provider manifests become compiled artifacts instead of hand-authored files, and
|
||||||
|
new providers (Copilot, Gemini, Codex — all supported by `apm runtime setup`) no longer require a
|
||||||
|
new hand-maintained manifest format.
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
- **The `plugins/<name>/` monorepo-hybrid directory layout survives.** `.claude-plugin/marketplace.json`
|
||||||
|
and per-provider `plugin.json` files become **compiled output** via `apm compile`/`apm pack`,
|
||||||
|
generated from `apm.yml` + `.apm/` per plugin, extensible to other `apm runtime`-supported
|
||||||
|
providers without hand-maintaining a separate manifest per provider.
|
||||||
|
- **This directly supersedes ADR-0001** ("Skills are distributed via plugins... each plugin
|
||||||
|
contains its own `skills/` directory"). Once the real conversion executes, skills and agents
|
||||||
|
physically move to `plugins/<name>/.apm/skills/` and `plugins/<name>/.apm/agents/*.agent.md`.
|
||||||
|
- New operational tooling — `apm-install` (skill), `apm-workflow` (skill), `apm-orchestrate`
|
||||||
|
(agent) — lands in `kyberforge`, tracked in issue #88
|
||||||
|
(https://git.dev.rkdr.net/Defame1297/holocron/issues/88).
|
||||||
|
- Adapting `plugin-author`/`marketplace-author`/`skill-author`/`agent-author`/`forge`'s routing to
|
||||||
|
author `.apm/`-native content is deferred to issue #89
|
||||||
|
(https://git.dev.rkdr.net/Defame1297/holocron/issues/89).
|
||||||
|
- Actually translating the existing plugins into `apm.yml` + `.apm/` and running the real
|
||||||
|
conversion is deferred to issue #90
|
||||||
|
(https://git.dev.rkdr.net/Defame1297/holocron/issues/90).
|
||||||
|
- `CONTEXT.md`'s "Plugin"/"Skill"/"Plugin marketplace" glossary entries remain accurate as
|
||||||
|
written until issue #90 actually executes — this ADR does not update them.
|
||||||
|
|
||||||
|
## Considered options
|
||||||
|
|
||||||
|
**Additive/compile-layer only, no `apm.yml` (rejected).** Keep `plugin.json`/`marketplace.json`
|
||||||
|
hand-authored and bolt APM on top as an optional extra. Rejected: doesn't achieve the multi-provider
|
||||||
|
compile-reuse goal APM's package model provides, and leaves the existing dual-manifest hand
|
||||||
|
maintenance in place unchanged.
|
||||||
|
|
||||||
|
**New standalone `plugins/apm/` plugin (rejected).** `plugins/lint/` was split out of `kyberforge`
|
||||||
|
specifically because Vale tooling is generic and repo-agnostic, not holocron-marketplace-specific
|
||||||
|
(see `CONTEXT.md`'s "lint plugin" entry) — the same argument applies to a generic `apm` CLI
|
||||||
|
wrapper. Rejected anyway, in favor of `kyberforge`, because this tooling's scope is specifically
|
||||||
|
converting *this* repo's marketplace, not standing up a reusable generic apm toolkit for other
|
||||||
|
repos. Accepted as an explicit tradeoff (same pattern as ADR-0011's `gitea-workflow` naming
|
||||||
|
tradeoff) — worth revisiting if this tooling is ever reused outside holocron's own conversion.
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
- ADR-0001 is superseded once issue #90 executes.
|
||||||
|
- ADR-0006 (plugin-version-parity) will need a third file, `apm.yml`, folded into its parity
|
||||||
|
check once #90 lands — not resolved by this ADR.
|
||||||
|
- ADR-0010 (agent sources relocated outside agents dir) needs revisiting once agents move under
|
||||||
|
`.apm/agents/` with the `.agent.md` extension — not resolved by this ADR.
|
||||||
|
- ADR-0014 (Vale prefilter ships from the plugin) has hardcoded path regexes assuming
|
||||||
|
`plugins/<name>/skills/...`/`plugins/<name>/agents/...`; these will need updating once paths
|
||||||
|
move under `.apm/` — not resolved by this ADR.
|
||||||
|
- `kyberforge` gains three new artifacts (issue #88) before any conversion of existing content
|
||||||
|
happens.
|
||||||
|
- Two follow-up issues (#89, #90) track the deferred authoring-tooling adaptation and the actual
|
||||||
|
repo conversion, respectively.
|
||||||
@@ -8,5 +8,5 @@
|
|||||||
"keywords": [],
|
"keywords": [],
|
||||||
"license": "MIT",
|
"license": "MIT",
|
||||||
"name": "kyberforge",
|
"name": "kyberforge",
|
||||||
"version": "1.2.8"
|
"version": "1.3.0"
|
||||||
}
|
}
|
||||||
|
|||||||
63
plugins/kyberforge/agents/apm-orchestrate.agent.md
Normal file
63
plugins/kyberforge/agents/apm-orchestrate.agent.md
Normal file
@@ -0,0 +1,63 @@
|
|||||||
|
---
|
||||||
|
name: apm-orchestrate
|
||||||
|
|
||||||
|
description: Orchestrates apm package/marketplace operations for other agents. Invoke when a caller needs a multi-step apm operation (scaffold a package, register it into a marketplace, compile/pack/publish, audit) coordinated across the apm-workflow skill with safety gates, session context, and structured results — especially fanning the same operation out across multiple packages in a monorepo.
|
||||||
|
|
||||||
|
tools: ["execute", "read"]
|
||||||
|
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
You are the orchestrator for apm package/marketplace operations — a composable workflow dispatcher designed for other agents to invoke multi-step `apm` operations reliably, especially the same operation repeated across several packages in a monorepo-hybrid layout. Your one job is routing and safety-gating: you do not decide manifest content yourself, you delegate to `apm-workflow` and enforce confirmation on irreversible operations.
|
||||||
|
|
||||||
|
You resolve the package root once per dispatched operation (the directory containing that package's `apm.yml`) and carry it forward as session context rather than making every call re-resolve it.
|
||||||
|
|
||||||
|
**Scope:** this orchestrator routes `apm-workflow`'s four concerns only — configure/scaffold, marketplace, compile/pack/publish, audit. It does not route `apm-install` (binary install, agent-runtime setup) — that's a one-time machine bootstrap, not a per-package, fan-out-able operation, and has no orchestrator counterpart. Confirm `apm --version` succeeds before dispatching any operation; if it fails, tell the caller to run `apm-install` first rather than attempting recovery here.
|
||||||
|
|
||||||
|
## Hard rules
|
||||||
|
|
||||||
|
These are non-negotiable regardless of `confirm` or any skill-local override:
|
||||||
|
- `apm publish` claims a version on a registry — treat it as irreversible. Refuse without explicit `confirm: true`; always dispatch with `--dry-run -v` first and surface that output to the caller before the real publish, even when `confirm: true` was given.
|
||||||
|
- MCP server secrets in any `apm.yml` content this orchestrator writes or edits must use `${VAR}` indirection — never a literal value.
|
||||||
|
- `apm marketplace add` (registering a marketplace as a consumer) and `apm marketplace package add` (registering a local package into a marketplace being built) are opposite directions — resolve which one the caller means from the operation name, never guess from context alone.
|
||||||
|
- `apm.yml`'s `type:` field constrains what `.apm/` may contain — when scaffolding (`init-package`), set `type:` before any primitive content is added; do not defer it.
|
||||||
|
- A clean plain `apm audit` is not a CI-equivalent pass — if the caller's intent is a CI gate, dispatch `audit-ci`, not `audit`.
|
||||||
|
- `apm experimental enable registries` must have already run before any `registry.*` config takes effect — check this precondition before dispatching an operation that depends on a named registry, and fail with a clear diagnostic rather than silently no-op'ing like apm itself does.
|
||||||
|
|
||||||
|
When invoked, you:
|
||||||
|
1. Parse the incoming workflow request (operation type, parameters, target package(s), context overrides)
|
||||||
|
2. Check safety gates: if the operation is `publish` and the request lacks explicit `confirm: true`, fail immediately with "requires explicit confirmation"
|
||||||
|
3. Route to `apm-workflow` with the resolved action (`configure`, `marketplace`, `compile`, `audit`)
|
||||||
|
4. Manage session context: carry forward each package's root directory and any registry/marketplace config already resolved this session
|
||||||
|
5. Handle error recovery: for recoverable failures (a stale lockfile, a marketplace ref that doesn't resolve yet because a dependency package hasn't been scaffolded), retry after the caller confirms the dependency now exists; for unrecoverable failures, fail gracefully with actionable diagnostics
|
||||||
|
6. When fanning an operation across multiple packages (e.g. `init-package` for every `plugins/<name>/` directory in a monorepo-hybrid conversion), dispatch one package at a time and continue past a single package's failure rather than aborting the whole batch — collect all failures and report them together at the end
|
||||||
|
7. Aggregate results and return structured JSON output suitable for agent chaining
|
||||||
|
|
||||||
|
## Inputs
|
||||||
|
|
||||||
|
- **operation:** string, one of:
|
||||||
|
- configure: init-package, compile-manifest-check (does `apm.yml` parse and match `type:`)
|
||||||
|
- marketplace: init-marketplace, check-marketplace, add-package, add-marketplace
|
||||||
|
- compile: compile, pack, publish, run-script
|
||||||
|
- audit: audit, audit-ci
|
||||||
|
- **package_root:** string, path to the directory containing the target `apm.yml` (required for every operation except `init-marketplace` when scaffolding the repo root)
|
||||||
|
- **parameters:** object, operation-specific arguments (package name for `add-package`, script name for `run-script`, registry name, etc.)
|
||||||
|
- **context:** object (optional), session state to carry forward (resolved registry config, marketplace root)
|
||||||
|
- **confirm:** boolean (optional), explicit confirmation required for `publish`
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
1. Validate the request structure and check if `operation` is known
|
||||||
|
2. Check the request against the Hard rules above (publish confirmation, secret indirection, marketplace-add direction, `type:` ordering, audit-vs-audit-ci, registries precondition) — refuse outright on violation, independent of `confirm`
|
||||||
|
3. If `operation` is `publish`: require `confirm: true`, dispatch `--dry-run -v` first regardless, surface that output, else fail with structured "requires explicit confirmation" error
|
||||||
|
4. Verify `apm --version` succeeds; if not, fail with a diagnostic pointing to `apm-install`
|
||||||
|
5. Invoke `apm-workflow` with the resolved action, `package_root`, and parameters
|
||||||
|
6. If fanning across multiple packages, loop package-by-package, collecting per-package results and failures rather than aborting on the first failure
|
||||||
|
7. Catch and handle apm errors: retry once for a dependency-not-yet-scaffolded failure after the caller confirms the dependency exists; otherwise return error structure with diagnostics
|
||||||
|
8. Aggregate all outputs and return as structured JSON
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Returns structured JSON with operation status, result (output — or a list of per-package results when fanned out — plus resolved package-root/registry context), and optional error details with recovery suggestions.
|
||||||
78
plugins/kyberforge/agents/apm-orchestrate.md
Normal file
78
plugins/kyberforge/agents/apm-orchestrate.md
Normal file
@@ -0,0 +1,78 @@
|
|||||||
|
---
|
||||||
|
name: apm-orchestrate
|
||||||
|
|
||||||
|
description: Orchestrates apm package/marketplace operations for other agents. Invoke when a caller needs a multi-step apm operation (scaffold a package, register it into a marketplace, compile/pack/publish, audit) coordinated across the apm-workflow skill with safety gates, session context, and structured results — especially fanning the same operation out across multiple packages in a monorepo.
|
||||||
|
|
||||||
|
tools: Bash, Read
|
||||||
|
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
You are the orchestrator for apm package/marketplace operations — a composable workflow dispatcher designed for other agents to invoke multi-step `apm` operations reliably, especially the same operation repeated across several packages in a monorepo-hybrid layout. Your one job is routing and safety-gating: you do not decide manifest content yourself, you delegate to `apm-workflow` and enforce confirmation on irreversible operations.
|
||||||
|
|
||||||
|
You resolve the package root once per dispatched operation (the directory containing that package's `apm.yml`) and carry it forward as session context rather than making every call re-resolve it.
|
||||||
|
|
||||||
|
**Scope:** this orchestrator routes `apm-workflow`'s four concerns only — configure/scaffold, marketplace, compile/pack/publish, audit. It does not route `apm-install` (binary install, agent-runtime setup) — that's a one-time machine bootstrap, not a per-package, fan-out-able operation, and has no orchestrator counterpart. Confirm `apm --version` succeeds before dispatching any operation; if it fails, tell the caller to run `apm-install` first rather than attempting recovery here.
|
||||||
|
|
||||||
|
## Hard rules
|
||||||
|
|
||||||
|
These are non-negotiable regardless of `confirm` or any skill-local override:
|
||||||
|
- `apm publish` claims a version on a registry — treat it as irreversible. Refuse without explicit `confirm: true`; always dispatch with `--dry-run -v` first and surface that output to the caller before the real publish, even when `confirm: true` was given.
|
||||||
|
- MCP server secrets in any `apm.yml` content this orchestrator writes or edits must use `${VAR}` indirection — never a literal value.
|
||||||
|
- `apm marketplace add` (registering a marketplace as a consumer) and `apm marketplace package add` (registering a local package into a marketplace being built) are opposite directions — resolve which one the caller means from the operation name, never guess from context alone.
|
||||||
|
- `apm.yml`'s `type:` field constrains what `.apm/` may contain — when scaffolding (`init-package`), set `type:` before any primitive content is added; do not defer it.
|
||||||
|
- A clean plain `apm audit` is not a CI-equivalent pass — if the caller's intent is a CI gate, dispatch `audit-ci`, not `audit`.
|
||||||
|
- `apm experimental enable registries` must have already run before any `registry.*` config takes effect — check this precondition before dispatching an operation that depends on a named registry, and fail with a clear diagnostic rather than silently no-op'ing like apm itself does.
|
||||||
|
|
||||||
|
When invoked, you:
|
||||||
|
1. Parse the incoming workflow request (operation type, parameters, target package(s), context overrides)
|
||||||
|
2. Check safety gates: if the operation is `publish` and the request lacks explicit `confirm: true`, fail immediately with "requires explicit confirmation"
|
||||||
|
3. Route to `apm-workflow` with the resolved action (`configure`, `marketplace`, `compile`, `audit`)
|
||||||
|
4. Manage session context: carry forward each package's root directory and any registry/marketplace config already resolved this session
|
||||||
|
5. Handle error recovery: for recoverable failures (a stale lockfile, a marketplace ref that doesn't resolve yet because a dependency package hasn't been scaffolded), retry after the caller confirms the dependency now exists; for unrecoverable failures, fail gracefully with actionable diagnostics
|
||||||
|
6. When fanning an operation across multiple packages (e.g. `init-package` for every `plugins/<name>/` directory in a monorepo-hybrid conversion), dispatch one package at a time and continue past a single package's failure rather than aborting the whole batch — collect all failures and report them together at the end
|
||||||
|
7. Aggregate results and return structured JSON output suitable for agent chaining
|
||||||
|
|
||||||
|
## Inputs
|
||||||
|
|
||||||
|
- **operation:** string, one of:
|
||||||
|
- configure: init-package, compile-manifest-check (does `apm.yml` parse and match `type:`)
|
||||||
|
- marketplace: init-marketplace, check-marketplace, add-package, add-marketplace
|
||||||
|
- compile: compile, pack, publish, run-script
|
||||||
|
- audit: audit, audit-ci
|
||||||
|
- **package_root:** string, path to the directory containing the target `apm.yml` (required for every operation except `init-marketplace` when scaffolding the repo root)
|
||||||
|
- **parameters:** object, operation-specific arguments (package name for `add-package`, script name for `run-script`, registry name, etc.)
|
||||||
|
- **context:** object (optional), session state to carry forward (resolved registry config, marketplace root)
|
||||||
|
- **confirm:** boolean (optional), explicit confirmation required for `publish`
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
1. Validate the request structure and check if `operation` is known
|
||||||
|
2. Check the request against the Hard rules above (publish confirmation, secret indirection, marketplace-add direction, `type:` ordering, audit-vs-audit-ci, registries precondition) — refuse outright on violation, independent of `confirm`
|
||||||
|
3. If `operation` is `publish`: require `confirm: true`, dispatch `--dry-run -v` first regardless, surface that output, else fail with structured "requires explicit confirmation" error
|
||||||
|
4. Verify `apm --version` succeeds; if not, fail with a diagnostic pointing to `apm-install`
|
||||||
|
5. Invoke `apm-workflow` via `Skill` with the resolved action, `package_root`, and parameters
|
||||||
|
6. If fanning across multiple packages, loop package-by-package, collecting per-package results and failures rather than aborting on the first failure
|
||||||
|
7. Catch and handle apm errors: retry once for a dependency-not-yet-scaffolded failure after the caller confirms the dependency exists; otherwise return error structure with diagnostics
|
||||||
|
8. Aggregate all outputs and return as structured JSON
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "success" | "error" | "partial",
|
||||||
|
"operation": "<operation_name>",
|
||||||
|
"result": {
|
||||||
|
"output": "<apm-workflow output or result, or a list of per-package results when fanned out>",
|
||||||
|
"context": { "package_root": "...", "resolved_registry": "..." }
|
||||||
|
},
|
||||||
|
"error": {
|
||||||
|
"message": "<human-readable error>",
|
||||||
|
"code": "<error type: not_confirmed | apm_unavailable | manifest_invalid | dependency_unresolved | publish_failed>",
|
||||||
|
"recovery_attempted": true | false,
|
||||||
|
"suggestions": ["<suggestion1>", "<suggestion2>"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
@@ -0,0 +1,99 @@
|
|||||||
|
---
|
||||||
|
topic: cli-reference
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
---
|
||||||
|
|
||||||
|
## Install
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm install [PACKAGE_REF...] [OPTIONS]
|
||||||
|
```
|
||||||
|
|
||||||
|
With no arguments, resolves and installs everything declared in `apm.yml` against `apm.lock.yaml`. Explicit `PACKAGE_REF` arguments (e.g. `acme/internal-tools#^1.0.0`) install and add that dependency. `apm install --update` re-resolves and accepts new upstream content even when it doesn't match the recorded lockfile hash (see troubleshooting). `apm install --target agent-skills` generates a vendor-neutral output directory for IDE-agnostic tool support instead of a harness-specific one.
|
||||||
|
|
||||||
|
## Compile
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm compile
|
||||||
|
```
|
||||||
|
|
||||||
|
Generates per-target output (Claude, Copilot, etc.) from the vendor-neutral `.apm/` primitive source tree, per the `compilation:` block in `apm.yml`.
|
||||||
|
|
||||||
|
## Pack
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm pack --dry-run # resolve and print; do not write
|
||||||
|
apm pack --offline # cached refs only
|
||||||
|
apm pack --include-prerelease # allow pre-release tags
|
||||||
|
apm pack -v # per-entry resolution detail
|
||||||
|
apm pack --marketplace=claude --json # JSON output for CI pipelines
|
||||||
|
```
|
||||||
|
|
||||||
|
Bundles a producer package into a distributable artifact.
|
||||||
|
|
||||||
|
## Publish
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm publish --package acme/my-skill --dry-run -v
|
||||||
|
apm publish --package acme/my-skill
|
||||||
|
```
|
||||||
|
|
||||||
|
Publishes a producer package (root containing `apm.yml`, `.apm/`, and optionally a `registries:` block) to a registry. Always dry-run with `-v` first to see resolution detail before publishing for real.
|
||||||
|
|
||||||
|
## Runtime management
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm runtime setup copilot # install with APM defaults
|
||||||
|
apm runtime setup codex --version 0.20.0 # pinned version
|
||||||
|
apm runtime setup llm --vanilla # skip APM-managed config
|
||||||
|
apm runtime list # what's installed
|
||||||
|
apm runtime status # which runtime `apm run` will pick
|
||||||
|
apm runtime remove gemini -y # uninstall without prompting
|
||||||
|
```
|
||||||
|
|
||||||
|
## Run
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm run <script> [--param key=value]
|
||||||
|
```
|
||||||
|
|
||||||
|
Executes a named script defined under `scripts:` in `apm.yml`, with `--param` substituting values into the script's parameters (used, for example, when the script wraps a Gemini CLI invocation).
|
||||||
|
|
||||||
|
## Audit (validation)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm audit # local: scan deployed files for hidden Unicode
|
||||||
|
apm audit --ci # CI gate: lockfile consistency + drift replay + policy
|
||||||
|
apm audit --file <path> # standalone: scan an arbitrary file
|
||||||
|
```
|
||||||
|
|
||||||
|
See `testing-and-validation.md` for CI wiring and exit-code behavior.
|
||||||
|
|
||||||
|
## Marketplace
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm marketplace init # add the marketplace: block to apm.yml
|
||||||
|
apm marketplace check # validate every listed package ref resolves
|
||||||
|
apm marketplace package add <path> --name <n> # register a local package into the marketplace
|
||||||
|
apm marketplace add <source> [--name <n>] # register a marketplace as a consumer (see marketplace-and-registries.md for source forms)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Plugin scaffolding
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm plugin init <name> --yes
|
||||||
|
```
|
||||||
|
|
||||||
|
Scaffolds a new package's `apm.yml` + `.apm/` skeleton in the current directory.
|
||||||
|
|
||||||
|
## Config
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm config set <key> <value>
|
||||||
|
apm config get <key>
|
||||||
|
apm config unset <key>
|
||||||
|
apm experimental enable registries # required before registry.* config takes effect
|
||||||
|
```
|
||||||
|
|
||||||
|
Used for workstation-level settings such as private registry URLs/tokens (see `marketplace-and-registries.md`).
|
||||||
@@ -0,0 +1,118 @@
|
|||||||
|
---
|
||||||
|
topic: configuration
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
---
|
||||||
|
|
||||||
|
## The `apm.yml` manifest
|
||||||
|
|
||||||
|
Every APM package — producer or consumer — is rooted in an `apm.yml` file. The only required fields are `name` and `version` (SemVer):
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
name: my-pkg
|
||||||
|
version: 1.0.0
|
||||||
|
```
|
||||||
|
|
||||||
|
## Full schema
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
name: my-pkg
|
||||||
|
version: 1.0.0
|
||||||
|
description: Code review skills for Python services
|
||||||
|
author: Jane Doe # plain string, or {name, email?, url?} object
|
||||||
|
license: MIT
|
||||||
|
homepage: https://example.com/my-pkg
|
||||||
|
repository: https://github.com/org/my-pkg
|
||||||
|
keywords: [ai, review, python]
|
||||||
|
|
||||||
|
# Constrains what .apm/ may contain: instructions, skill, hybrid, or prompts
|
||||||
|
type: skill
|
||||||
|
|
||||||
|
# Pins which harnesses this package compiles to. Prefer the plural `targets:`
|
||||||
|
# list form; the legacy singular `target:` CSV form is still accepted.
|
||||||
|
targets:
|
||||||
|
- copilot
|
||||||
|
- claude
|
||||||
|
|
||||||
|
# "auto" publishes the authoritative local source layout, or list explicit
|
||||||
|
# repo paths to define the complete publication set.
|
||||||
|
includes: auto
|
||||||
|
|
||||||
|
dependencies:
|
||||||
|
apm:
|
||||||
|
- microsoft/apm-sample-package#v1.0.0 # pinned to a tag
|
||||||
|
- github/awesome-copilot/skills/review-and-refactor # single primitive
|
||||||
|
mcp:
|
||||||
|
- microsoft/azure-devops-mcp # MCP server dependency
|
||||||
|
lsp:
|
||||||
|
- name: pyright
|
||||||
|
command: pyright-langserver
|
||||||
|
args: ["--stdio"]
|
||||||
|
extensionToLanguage:
|
||||||
|
".py": python
|
||||||
|
|
||||||
|
# Same shape as dependencies, but excluded from the shipped artifact —
|
||||||
|
# for dev-only tooling and tests.
|
||||||
|
devDependencies:
|
||||||
|
apm:
|
||||||
|
- my-org/internal-test-skills
|
||||||
|
|
||||||
|
# Named commands runnable via `apm run <name>`
|
||||||
|
scripts:
|
||||||
|
start: "copilot -p 'README.prompt.md'"
|
||||||
|
review: "copilot -p 'code-review.prompt.md'"
|
||||||
|
|
||||||
|
compilation:
|
||||||
|
target: all
|
||||||
|
strategy: distributed
|
||||||
|
exclude:
|
||||||
|
- "apm_modules/**"
|
||||||
|
placement:
|
||||||
|
min_instructions_per_file: 1
|
||||||
|
|
||||||
|
policy:
|
||||||
|
fetch_failure_default: warn
|
||||||
|
|
||||||
|
registries:
|
||||||
|
public-apm:
|
||||||
|
url: https://registry.example.com/api/public-apm
|
||||||
|
default: public-apm
|
||||||
|
|
||||||
|
marketplace:
|
||||||
|
owner:
|
||||||
|
name: contoso
|
||||||
|
url: https://github.com/contoso
|
||||||
|
packages:
|
||||||
|
- name: code-review
|
||||||
|
source: contoso/code-review
|
||||||
|
version: "^1.0.0"
|
||||||
|
tags: [review, quality]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Dependency reference forms
|
||||||
|
|
||||||
|
`dependencies.apm` entries accept several forms: a pinned tag (`owner/repo#tag`), a plain repo (uses default branch), a single primitive path within a repo, a raw git URL, a `git:`/`path:`/`ref:` object for finer control, or a local relative path (`./packages/my-shared-skills`).
|
||||||
|
|
||||||
|
## MCP server secrets
|
||||||
|
|
||||||
|
Secrets for MCP server config (headers, env vars) should use `${VAR}` indirection rather than literal values, so they're resolved by APM or the host harness at install/runtime and never committed to the manifest:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
mcp:
|
||||||
|
- name: linear
|
||||||
|
registry: false
|
||||||
|
transport: http
|
||||||
|
url: https://mcp.linear.app/sse
|
||||||
|
headers:
|
||||||
|
Authorization: "Bearer ${LINEAR_TOKEN}"
|
||||||
|
- name: my-internal
|
||||||
|
registry: false
|
||||||
|
transport: stdio
|
||||||
|
command: my-server
|
||||||
|
env:
|
||||||
|
API_TOKEN: "${MY_API_TOKEN}"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Registries
|
||||||
|
|
||||||
|
Registries are optional — any git repo is a valid package source by default — but a project can declare named registries and pick a `default:` for shorthand dependency resolution, useful for teams centralizing internal packages.
|
||||||
@@ -0,0 +1,80 @@
|
|||||||
|
---
|
||||||
|
topic: examples
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
---
|
||||||
|
|
||||||
|
## Producer quickstart
|
||||||
|
|
||||||
|
A minimal consumer flow: install a package by owner/name, then compile it to the active harness's format.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm install your-org/your-project
|
||||||
|
apm compile
|
||||||
|
```
|
||||||
|
|
||||||
|
## Authoring an agent primitive
|
||||||
|
|
||||||
|
Agents are markdown files with YAML frontmatter defining metadata, model constraints, and tool permissions, followed by a prose system-instructions body:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
name: security-review
|
||||||
|
description: Reviews diffs for OWASP top-10 issues and missing input validation.
|
||||||
|
model: gpt-5
|
||||||
|
tools:
|
||||||
|
Read: true
|
||||||
|
Grep: true
|
||||||
|
---
|
||||||
|
|
||||||
|
You are a security reviewer. Your job is to inspect the working diff
|
||||||
|
for...
|
||||||
|
```
|
||||||
|
|
||||||
|
## On-disk package layout
|
||||||
|
|
||||||
|
```text
|
||||||
|
.apm/
|
||||||
|
skills/
|
||||||
|
my-skill/
|
||||||
|
SKILL.md
|
||||||
|
scripts/
|
||||||
|
references/
|
||||||
|
assets/
|
||||||
|
prompts/
|
||||||
|
review.prompt.md
|
||||||
|
instructions/
|
||||||
|
style.instructions.md
|
||||||
|
agents/
|
||||||
|
cli-logging-expert.agent.md
|
||||||
|
hooks/
|
||||||
|
pre-commit.json
|
||||||
|
```
|
||||||
|
|
||||||
|
## Publish → install round trip
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Producer: package root with apm.yml, .apm/, and (optionally) a registries: block
|
||||||
|
apm publish --package acme/my-skill --dry-run -v
|
||||||
|
apm publish --package acme/my-skill
|
||||||
|
|
||||||
|
# Consumer: another repo
|
||||||
|
apm install acme/internal-tools#^1.0.0
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cross-tool / IDE-agnostic install
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm install --target agent-skills
|
||||||
|
```
|
||||||
|
|
||||||
|
Generates a vendor-neutral skills directory usable across IDEs rather than a single harness-specific output.
|
||||||
|
|
||||||
|
## Running a script with parameters (Gemini CLI example)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run a script from apm.yml, substituting a parameter
|
||||||
|
apm run start --param service_name=api-gateway
|
||||||
|
```
|
||||||
|
|
||||||
|
Once a runtime like Gemini CLI is installed via `apm runtime setup gemini`, it can also be invoked directly for interactive mode (`gemini`), sandboxed/isolated execution (`gemini -s`), or with an explicit model (`gemini -m gemini-2.5-pro-preview`).
|
||||||
@@ -0,0 +1,39 @@
|
|||||||
|
---
|
||||||
|
topic: installation
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick install (recommended)
|
||||||
|
|
||||||
|
A one-line install script auto-detects the platform, downloads the latest binary, and configures the system `PATH`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -sSL https://aka.ms/apm-unix | sh
|
||||||
|
```
|
||||||
|
|
||||||
|
On Windows, the installer adds both the current directory and the bin directory to `PATH`, so it works from native shells, Git Bash, and process APIs alike.
|
||||||
|
|
||||||
|
## Customizing the install
|
||||||
|
|
||||||
|
- **Pin a specific version**: append `@vX.Y.Z` to the piped script arguments, e.g. `curl -sSL https://aka.ms/apm-unix | sh -s -- @v1.2.3`.
|
||||||
|
- **Custom install directory**: set `APM_INSTALL_DIR` before running the script, e.g. `APM_INSTALL_DIR=$HOME/.local/bin sh`.
|
||||||
|
- **Air-gapped / GitHub Enterprise mirror**: set `GITHUB_URL` and `VERSION` env vars against a local `install.sh`, e.g. `GITHUB_URL=https://github.corp.com VERSION=v1.2.3 sh install.sh`.
|
||||||
|
|
||||||
|
## Alternative install methods
|
||||||
|
|
||||||
|
- **pip**: `pip install apm-cli` — requires Python 3.10 or higher.
|
||||||
|
- **Manual binary**: download the platform-specific archive from the GitHub releases page, extract it, move the binary to a permanent directory, and add that directory to `PATH`.
|
||||||
|
|
||||||
|
## Installing agent runtimes
|
||||||
|
|
||||||
|
APM itself doesn't execute agents, but it can install and manage the runtimes that do, via `apm runtime setup <name>`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm runtime setup copilot # recommended default
|
||||||
|
apm runtime setup codex
|
||||||
|
apm runtime setup gemini
|
||||||
|
apm runtime setup llm
|
||||||
|
```
|
||||||
|
|
||||||
|
Installing GitHub Copilot CLI through APM pulls it from the public npm registry and requires Node.js v22+ and npm v10+; no authentication is needed for the install step itself. Use `apm runtime list` to see which runtimes are currently installed and which one `apm run` will pick by default.
|
||||||
@@ -0,0 +1,76 @@
|
|||||||
|
---
|
||||||
|
topic: marketplace-and-registries
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
---
|
||||||
|
|
||||||
|
## Building a marketplace from a producer repo
|
||||||
|
|
||||||
|
Standard sequence to turn a repo into an APM marketplace (a curated set of packages other consumers can point at):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm marketplace init # 1. add the marketplace: block to apm.yml
|
||||||
|
$EDITOR apm.yml # 2. describe each package
|
||||||
|
apm marketplace check # 3. validate refs resolve
|
||||||
|
apm pack # 4. build marketplace artifacts
|
||||||
|
git add apm.yml .claude-plugin/marketplace.json
|
||||||
|
git commit -m "Release v1.0.0" && git tag v1.0.0 && git push --tags
|
||||||
|
```
|
||||||
|
|
||||||
|
Note the build step emits a `.claude-plugin/marketplace.json` artifact alongside `apm.yml` — APM's `apm pack` generates the Claude Code-native marketplace manifest as one of its per-target compile outputs, so an APM-based marketplace can still be consumed by Claude Code's existing marketplace mechanism without a separate hand-maintained file.
|
||||||
|
|
||||||
|
## Registering a marketplace as a consumer
|
||||||
|
|
||||||
|
`apm marketplace add` accepts many source shapes — this is the distribution/consumption side:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# GitHub shorthand
|
||||||
|
apm marketplace add my-org/awesome-agents
|
||||||
|
|
||||||
|
# GitLab via host shorthand
|
||||||
|
apm marketplace add gitlab.com/my-org/awesome-agents --host gitlab.com
|
||||||
|
|
||||||
|
# Azure DevOps Services / Server, Gitea, Bitbucket Server — any self-hosted git, pinned with #ref
|
||||||
|
apm marketplace add https://gitea.example.com/org/repo.git#v1.0.0 --name custom
|
||||||
|
|
||||||
|
# Hosted marketplace.json URL
|
||||||
|
apm marketplace add https://catalog.example.com/marketplace.json --name catalog
|
||||||
|
|
||||||
|
# SSH
|
||||||
|
apm marketplace add git@gitea.example.com:org/repo.git --name custom
|
||||||
|
|
||||||
|
# Local filesystem (bare repo, working directory, or marketplace.json file directly) — no server needed
|
||||||
|
apm marketplace add /srv/marketplaces/agent-forge.git --name agent-forge
|
||||||
|
apm marketplace add ./vendor/marketplace.json --name vendor
|
||||||
|
apm marketplace add file:///srv/marketplaces/agent-forge.git --name agent-forge
|
||||||
|
```
|
||||||
|
|
||||||
|
The local-filesystem and `file://` forms mean a fully local, offline marketplace — pointing `apm marketplace add` at a path or bare repo on disk — needs no hosted registry or network access at all. This is the direct fit for an internal/homelab setup that wants package discovery without standing up infrastructure.
|
||||||
|
|
||||||
|
## Private / self-hosted registries (experimental)
|
||||||
|
|
||||||
|
Distinct from `marketplace add` (which points at a *catalog* of packages), registries are a REST endpoint for hosting the packages themselves (e.g., Artifactory, JFrog, or any endpoint implementing the standard Registry HTTP API). This is opt-in and currently experimental:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm experimental enable registries
|
||||||
|
|
||||||
|
# Project-level: apm.yml has a registries: block and registry-routed deps
|
||||||
|
apm install
|
||||||
|
|
||||||
|
# Workstation-level config only (no registries: block committed to apm.yml)
|
||||||
|
apm config set registry.corp-main.url https://artifactory.corp.example.com/apm
|
||||||
|
apm config set registry.corp-main.token eyJ...
|
||||||
|
apm config set registry.corp-main.default true
|
||||||
|
apm install
|
||||||
|
|
||||||
|
# CI: pass the token via env var, never commit it
|
||||||
|
APM_REGISTRY_TOKEN_CORP_MAIN=eyJ... apm install --frozen
|
||||||
|
```
|
||||||
|
|
||||||
|
`apm config get`/`apm config unset` manage individual keys the same way. Public registries need no authentication; private ones need a token configured per the above.
|
||||||
|
|
||||||
|
## Which mechanism to use
|
||||||
|
|
||||||
|
- **Local packages, no distribution needed yet**: local-path dependencies in `apm.yml` (`./packages/my-shared-skills`) — no marketplace or registry involved at all.
|
||||||
|
- **Internal catalog, still git-based, no server**: `apm marketplace add` against a local path, bare repo, or `file://` URI, or a plain git host (Gitea, GitHub, etc.) — this is the natural fit if this repo's own git remote should double as the marketplace source.
|
||||||
|
- **Package-level hosting at scale / access control**: registries (Artifactory-style REST endpoint) — more infrastructure, only worth it once package count or access-control needs outgrow git-based discovery.
|
||||||
@@ -0,0 +1,71 @@
|
|||||||
|
---
|
||||||
|
topic: monorepo-and-repo-shapes
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
---
|
||||||
|
|
||||||
|
## Repo shapes
|
||||||
|
|
||||||
|
APM documents named patterns for how a repo can host multiple packages. Two are directly relevant to converting an existing multi-plugin repo:
|
||||||
|
|
||||||
|
### Monorepo
|
||||||
|
|
||||||
|
Multiple independent plugins under one repo, each with its own manifest and `.apm/` tree, plus a root `apm.yml` that lists them as local-path packages:
|
||||||
|
|
||||||
|
```text
|
||||||
|
my-monorepo/
|
||||||
|
apm.yml # marketplace + local-path packages
|
||||||
|
packages/
|
||||||
|
plugin-a/
|
||||||
|
apm.yml # plugin-a's manifest
|
||||||
|
.apm/
|
||||||
|
agents/
|
||||||
|
expert.agent.md
|
||||||
|
instructions/
|
||||||
|
style.instructions.md
|
||||||
|
skills/
|
||||||
|
my-skill/
|
||||||
|
SKILL.md
|
||||||
|
plugin-b/
|
||||||
|
apm.yml
|
||||||
|
.apm/
|
||||||
|
prompts/
|
||||||
|
review.prompt.md
|
||||||
|
hooks/
|
||||||
|
pre-tool.json
|
||||||
|
```
|
||||||
|
|
||||||
|
### Monorepo-hybrid
|
||||||
|
|
||||||
|
The variant for a repo that both ships its own plugins *and* curates/re-lists others: multiple plugins live under a packages directory, each with its own manifest for independent compilation and testing, while a single root marketplace lists them all as local-path entries. This is the closest documented match to this repo's current `plugins/<name>/` layout (each plugin already self-contained with its own skills/agents/hooks).
|
||||||
|
|
||||||
|
## Scaffolding a monorepo
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm plugin init plugin-a --yes # run from inside packages/plugin-a
|
||||||
|
apm plugin init plugin-b --yes # run from inside packages/plugin-b
|
||||||
|
cd ../..
|
||||||
|
apm marketplace init --owner acme-org --name acme-monorepo
|
||||||
|
apm marketplace package add ./packages/plugin-a --name plugin-a
|
||||||
|
apm marketplace package add ./packages/plugin-b --name plugin-b
|
||||||
|
```
|
||||||
|
|
||||||
|
`apm plugin init` scaffolds a single package's `apm.yml` + `.apm/` skeleton; `apm marketplace package add` registers an already-existing local package path into the root marketplace listing without re-scaffolding it — this is the command to point at each of this repo's existing `plugins/*` directories once each has its own `apm.yml`.
|
||||||
|
|
||||||
|
## Per-package versioning
|
||||||
|
|
||||||
|
Plugins in a monorepo don't have to share a version with the root or each other:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
marketplace:
|
||||||
|
versioning: { strategy: per_package }
|
||||||
|
packages:
|
||||||
|
- { name: plugin-a, source: ./packages/plugin-a, version: 2.0.0 }
|
||||||
|
- { name: plugin-b, source: ./packages/plugin-b, version: 0.1.0 }
|
||||||
|
```
|
||||||
|
|
||||||
|
Without this, the default versioning strategy ties all listed packages to the marketplace/root version — worth checking explicitly, since this repo's plugins (git, gitea, kyberforge, lint, core, bin) currently version independently (see the patch-bump-per-plugin pattern already in this repo's commit history).
|
||||||
|
|
||||||
|
## What's still a manual translation, not an APM feature
|
||||||
|
|
||||||
|
Nothing in the docs describes an automated converter from an existing `.claude-plugin/marketplace.json` + `plugin.json` pair into `apm.yml`. The shapes are compatible (`apm pack` emits `.claude-plugin/marketplace.json` as a compile target), but populating each plugin's `apm.yml` metadata, `type:`, `targets:`, and `dependencies:` from the current manifests is manual per-package work, not a single migration command.
|
||||||
@@ -0,0 +1,37 @@
|
|||||||
|
---
|
||||||
|
topic: overview
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
---
|
||||||
|
|
||||||
|
## What APM is
|
||||||
|
|
||||||
|
APM (Agent Package Manager) applies a standard package-management model — declare, lock, install, audit — to AI agent configuration. It manages the skills, prompts, instructions, agents, and tools an AI coding assistant needs, so that configuration is version-controlled, peer-reviewed, and reproducible across developer machines and CI pipelines, the same way a dependency manager keeps application code reproducible.
|
||||||
|
|
||||||
|
## Scope: install and integrity plane only
|
||||||
|
|
||||||
|
APM is deliberately narrow. It governs what reaches disk and enforces policy conformance on that install — nothing more. It is explicitly **not**:
|
||||||
|
- A runtime for executing agents
|
||||||
|
- An LLM gateway or model-call proxy
|
||||||
|
- A fine-tuning tool
|
||||||
|
- A marketplace requiring a specific distribution platform
|
||||||
|
|
||||||
|
It also does not manage agent permissions or version model weights. Any git repository can serve as a valid APM package — there's no mandated central registry, though named registries are supported for teams that want one.
|
||||||
|
|
||||||
|
## Producer / consumer model
|
||||||
|
|
||||||
|
- A **producer** package is a directory containing an `apm.yml` manifest, primitives under `.apm/`, and a `README.md`.
|
||||||
|
- A **consumer** project declares dependencies on producer packages in its own `apm.yml` and installs them with `apm install`.
|
||||||
|
- `apm compile` generates per-target output (e.g., Claude-specific or Copilot-specific files) from the vendor-neutral `.apm/` source tree.
|
||||||
|
- `apm pack` bundles a producer package into a distributable artifact.
|
||||||
|
|
||||||
|
## Package anatomy
|
||||||
|
|
||||||
|
APM packages organize content into subdirectories under `.apm/` by primitive type:
|
||||||
|
- `skills/` — multi-file capabilities (each with its own `SKILL.md`, plus optional `scripts/`, `references/`, `assets/`)
|
||||||
|
- `prompts/` — reusable prompt templates (`*.prompt.md`)
|
||||||
|
- `instructions/` — always-on rules (`*.instructions.md`)
|
||||||
|
- `agents/` — model and tool configuration for a named agent (`*.agent.md`)
|
||||||
|
- `hooks/` — host-harness lifecycle event bindings
|
||||||
|
|
||||||
|
This mirrors how the vendor-neutral primitives compile down to provider-specific formats (Claude, Copilot, etc.) via `apm compile`.
|
||||||
@@ -0,0 +1,8 @@
|
|||||||
|
# Sources
|
||||||
|
|
||||||
|
## context7-microsoft-apm
|
||||||
|
|
||||||
|
- **URL:** context7:/microsoft/apm
|
||||||
|
- **Description:** Microsoft APM (Agent Package Manager) — open-source dependency manager for AI agent configuration (skills, prompts, instructions, agents, hooks, MCP/LSP deps), applying a declare/lock/install/audit workflow.
|
||||||
|
- **Contributing files:** overview.md, installation.md, configuration.md, cli-reference.md, examples.md, troubleshooting.md, testing-and-validation.md, marketplace-and-registries.md, monorepo-and-repo-shapes.md
|
||||||
|
- **Status:** `extracted`
|
||||||
@@ -0,0 +1,51 @@
|
|||||||
|
---
|
||||||
|
topic: testing-and-validation
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
---
|
||||||
|
|
||||||
|
## `apm audit`
|
||||||
|
|
||||||
|
APM's built-in validation/integrity tool, usable both locally and as a CI gate:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm audit # local: scan deployed files for hidden Unicode
|
||||||
|
apm audit --ci # CI gate: lockfile consistency + drift replay
|
||||||
|
apm audit --file <path> # standalone: scan an arbitrary file
|
||||||
|
```
|
||||||
|
|
||||||
|
`apm audit --ci` runs baseline lockfile checks, install-replay drift detection (does a clean `apm install` reproduce what's on disk), and org policy checks. It returns exit code `0` on success and `1` on any violation, so it composes as a normal CI gate step. It's meant to sit alongside — not replace — existing lint/test/security-scan CI steps: it specifically covers AI agent configuration integrity, hidden-content scanning, lockfile verification, and policy enforcement, not general code correctness.
|
||||||
|
|
||||||
|
## Policy checks
|
||||||
|
|
||||||
|
`apm audit --ci` auto-discovers an org policy from the git remote if `--policy`/`--policy-source` isn't given explicitly; `--no-policy` skips policy discovery for a single invocation. This lets an org centrally define required checks (e.g., which primitive types are allowed, required metadata fields) without every package repo repeating the config.
|
||||||
|
|
||||||
|
## Marketplace ref validation
|
||||||
|
|
||||||
|
Separately from `apm audit`, `apm marketplace check` validates that every package reference declared in a marketplace's `apm.yml` actually resolves (correct path/ref, manifest present) before you build or publish — this is the step that catches a typo'd local path or a stale pinned tag before it ships.
|
||||||
|
|
||||||
|
## CI integration example (GitHub Actions)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
jobs:
|
||||||
|
apm-audit:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
permissions:
|
||||||
|
contents: read
|
||||||
|
security-events: write
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v4
|
||||||
|
- uses: actions/setup-python@v5
|
||||||
|
with: { python-version: "3.12" }
|
||||||
|
- run: pip install apm-cli==X.Y.Z # pin to the version you standardize on
|
||||||
|
- run: apm install
|
||||||
|
- run: apm audit --ci -f sarif --output apm-audit.sarif
|
||||||
|
- uses: github/codeql-action/upload-sarif@v3
|
||||||
|
with: { sarif_file: apm-audit.sarif }
|
||||||
|
```
|
||||||
|
|
||||||
|
`-f sarif --output <file>` emits SARIF, which GitHub Code Scanning can ingest directly for inline annotations on PRs — useful if this repo's CI already surfaces findings that way.
|
||||||
|
|
||||||
|
## Frozen installs
|
||||||
|
|
||||||
|
`apm install --frozen` (seen in the private-registry install flow) fails instead of silently re-resolving if the lockfile is out of date — the CI equivalent of `npm ci` vs `npm install`. Worth using in any CI job that shouldn't be allowed to drift the lockfile.
|
||||||
@@ -0,0 +1,52 @@
|
|||||||
|
---
|
||||||
|
topic: troubleshooting
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
---
|
||||||
|
|
||||||
|
## Manifest / lockfile ref mismatch
|
||||||
|
|
||||||
|
Happens when the version or ref declared in `apm.yml` no longer matches what's recorded in the stale `apm.lock.yaml`:
|
||||||
|
|
||||||
|
```text
|
||||||
|
<owner>/<repo>: manifest ref 'v2' != lockfile ref 'v1'
|
||||||
|
N ref mismatch(es) -- run 'apm install' to update lockfile
|
||||||
|
```
|
||||||
|
|
||||||
|
Fix: run `apm install` to reconcile the lockfile with the manifest.
|
||||||
|
|
||||||
|
## Missing lockfile
|
||||||
|
|
||||||
|
Occurs when a command that needs a resolved dependency graph runs before the first install:
|
||||||
|
|
||||||
|
```text
|
||||||
|
lockfile not found at apm.lock.yaml; run 'apm install' to generate it
|
||||||
|
```
|
||||||
|
|
||||||
|
## Lockfile version mismatch
|
||||||
|
|
||||||
|
The installed `apm` binary is older than the lockfile format it's being asked to read:
|
||||||
|
|
||||||
|
```text
|
||||||
|
[x] apm.lock.yaml uses lockfile_version "2", this binary supports "1"
|
||||||
|
[>] Upgrade APM: see https://...
|
||||||
|
```
|
||||||
|
|
||||||
|
Fix: upgrade the APM binary to a version that supports the newer lockfile schema.
|
||||||
|
|
||||||
|
## Content hash mismatch (possible supply-chain issue)
|
||||||
|
|
||||||
|
Raised when downloaded dependency bytes don't match the hash recorded in the lockfile:
|
||||||
|
|
||||||
|
```text
|
||||||
|
[x] Content hash mismatch for <owner>/<repo>: expected <sha>, got <sha>.
|
||||||
|
The downloaded content differs from the lockfile record. This may
|
||||||
|
indicate a supply-chain attack. Use 'apm install --update' to accept
|
||||||
|
new content and update the lockfile.
|
||||||
|
```
|
||||||
|
|
||||||
|
This is a fail-closed integrity check — treat an unexpected occurrence as a security signal, not just a stale-cache annoyance. Only use `apm install --update` once you've confirmed the new upstream content is legitimate (e.g., a real re-tag), since it deliberately overwrites the recorded hash.
|
||||||
|
|
||||||
|
## Dependency version conflicts
|
||||||
|
|
||||||
|
Direct and transitive dependency constraints are resolved by intersecting version ranges. Example: a manifest directly depends on `acme/foo#^1.2.0`, and a transitive dependency (`acme/bar`) pulls in `acme/foo#^1.5.0`. The effective constraint is the intersection, `[>=1.5.0, <2.0.0)`, and APM picks the highest tag in that range. If the two constraints don't overlap at all (e.g. `^1.2.0` vs. `^2.0.0`), resolution fails closed rather than silently picking one side — install errors out instead of guessing.
|
||||||
@@ -13,5 +13,5 @@
|
|||||||
"skills": [
|
"skills": [
|
||||||
"skills/"
|
"skills/"
|
||||||
],
|
],
|
||||||
"version": "1.2.8"
|
"version": "1.3.0"
|
||||||
}
|
}
|
||||||
|
|||||||
22
plugins/kyberforge/skills/apm-install/README.md
Normal file
22
plugins/kyberforge/skills/apm-install/README.md
Normal file
@@ -0,0 +1,22 @@
|
|||||||
|
# apm-install
|
||||||
|
|
||||||
|
Installs and configures the `apm` (Agent Package Manager) CLI and the agent runtimes it manages.
|
||||||
|
|
||||||
|
## What it does
|
||||||
|
|
||||||
|
Covers the two provisioning steps for working with apm: installing the `apm` binary itself (quick-install script, pinned version, air-gapped mirror, or pip), and installing/managing an agent runtime apm drives (`apm runtime setup copilot|codex|gemini|llm`, listing installed runtimes, checking which one `apm run` defaults to).
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
```
|
||||||
|
/apm-install
|
||||||
|
```
|
||||||
|
|
||||||
|
Once `apm` and a runtime are in place, use `apm-workflow` for authoring `apm.yml`, scaffolding packages/marketplaces, compiling, packing, publishing, and auditing.
|
||||||
|
|
||||||
|
## Files
|
||||||
|
|
||||||
|
| File | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `SKILL.md` | Skill instructions for agents |
|
||||||
|
| `references/sources.md` | Provenance chain — research sources that informed this skill |
|
||||||
53
plugins/kyberforge/skills/apm-install/SKILL.md
Normal file
53
plugins/kyberforge/skills/apm-install/SKILL.md
Normal file
@@ -0,0 +1,53 @@
|
|||||||
|
---
|
||||||
|
name: apm-install
|
||||||
|
description: >
|
||||||
|
Use when the user wants to install the apm (Agent Package Manager) CLI
|
||||||
|
itself, pin or upgrade its version, set up an air-gapped/enterprise mirror
|
||||||
|
install, or install and manage an agent runtime that apm drives (Copilot
|
||||||
|
CLI, Codex, Gemini, generic llm) — "install apm", "set up apm", "pin apm to
|
||||||
|
a version", "apm runtime setup", "which runtime will apm run pick". Do not
|
||||||
|
use for authoring apm.yml, scaffolding a package/marketplace, compiling,
|
||||||
|
packing, publishing, or running apm audit — use apm-workflow for those.
|
||||||
|
metadata:
|
||||||
|
category: apm
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
---
|
||||||
|
|
||||||
|
## Gotchas
|
||||||
|
|
||||||
|
- apm does not execute agents itself — it only installs and manages the runtimes that do. "Install apm" and "install a runtime apm manages" are two separate steps; don't conflate them or skip the second when the user actually wants a working agent CLI, not just the package manager.
|
||||||
|
- The air-gapped/enterprise mirror path needs `GITHUB_URL` and `VERSION` set together against a downloaded `install.sh` — it does not work through the piped one-liner form.
|
||||||
|
- `pip install apm-cli` requires Python 3.10+; the quick-install script has no such prerequisite. Prefer the quick-install script unless the environment is pip-first.
|
||||||
|
- Installing the Copilot CLI runtime through `apm runtime setup copilot` requires Node.js v22+ and npm v10+ already present — apm does not install Node/npm for you.
|
||||||
|
|
||||||
|
## Install apm
|
||||||
|
|
||||||
|
Default:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -sSL https://aka.ms/apm-unix | sh
|
||||||
|
```
|
||||||
|
|
||||||
|
Escape hatches — combine as needed:
|
||||||
|
- Pin a version: append `@vX.Y.Z` to the piped script's arguments, e.g. `curl -sSL https://aka.ms/apm-unix | sh -s -- @v1.2.3`.
|
||||||
|
- Custom install directory: set `APM_INSTALL_DIR` before running, e.g. `APM_INSTALL_DIR=$HOME/.local/bin sh`.
|
||||||
|
- Air-gapped / GitHub Enterprise mirror: download `install.sh` first, then run it with `GITHUB_URL` and `VERSION` set, e.g. `GITHUB_URL=https://github.corp.com VERSION=v1.2.3 sh install.sh`.
|
||||||
|
- pip (Python 3.10+ environments): `pip install apm-cli`.
|
||||||
|
- Manual: download the platform archive from the GitHub releases page, extract, place the binary on `PATH`.
|
||||||
|
|
||||||
|
Verify with `apm --version`.
|
||||||
|
|
||||||
|
## Install or manage an agent runtime
|
||||||
|
|
||||||
|
Default:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm runtime setup copilot
|
||||||
|
```
|
||||||
|
|
||||||
|
Other targets: `apm runtime setup codex`, `apm runtime setup gemini`, `apm runtime setup llm`.
|
||||||
|
|
||||||
|
- `apm runtime list` — show installed runtimes.
|
||||||
|
- `apm runtime status` — show which runtime `apm run` will pick by default.
|
||||||
|
- `apm runtime remove <name> -y` — uninstall without an interactive prompt.
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
# Sources
|
||||||
|
|
||||||
|
## context7-microsoft-apm
|
||||||
|
|
||||||
|
- **URL:** context7:/microsoft/apm
|
||||||
|
- **Description:** Microsoft APM (Agent Package Manager) — open-source dependency manager for AI agent configuration (skills, prompts, instructions, agents, hooks, MCP/LSP deps), applying a declare/lock/install/audit workflow.
|
||||||
|
- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
|
||||||
|
- **Contributing files:** SKILL.md
|
||||||
|
- **Status:** `extracted`
|
||||||
31
plugins/kyberforge/skills/apm-workflow/README.md
Normal file
31
plugins/kyberforge/skills/apm-workflow/README.md
Normal file
@@ -0,0 +1,31 @@
|
|||||||
|
# apm-workflow
|
||||||
|
|
||||||
|
Authors, scaffolds, compiles, and audits apm packages and marketplaces.
|
||||||
|
|
||||||
|
## What it does
|
||||||
|
|
||||||
|
Covers the apm.yml lifecycle a session moves through repeatedly: configuring/scaffolding a package manifest, building or registering a marketplace, compiling/packing/publishing a distributable, and validating integrity via apm audit. Dispatches by requested action to one of four reference files, each self-contained for its concern.
|
||||||
|
|
||||||
|
## Before you start
|
||||||
|
|
||||||
|
Requires the `apm` binary and (for runtime-driven scripts) an agent runtime already installed — use `apm-install` first if either is missing.
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
```
|
||||||
|
/apm-workflow configure
|
||||||
|
/apm-workflow marketplace
|
||||||
|
/apm-workflow compile
|
||||||
|
/apm-workflow audit
|
||||||
|
```
|
||||||
|
|
||||||
|
## Files
|
||||||
|
|
||||||
|
| File | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `SKILL.md` | Dispatch table and cross-cutting gotchas |
|
||||||
|
| `references/configure.md` | apm.yml schema, apm plugin init, dependency forms, MCP secrets, registries |
|
||||||
|
| `references/marketplace.md` | Building/registering a marketplace, package registration, versioning |
|
||||||
|
| `references/compile.md` | apm compile / pack / publish / run |
|
||||||
|
| `references/audit.md` | apm audit, apm audit --ci, apm marketplace check, CI wiring, frozen installs |
|
||||||
|
| `references/sources.md` | Provenance chain — research sources that informed this skill |
|
||||||
43
plugins/kyberforge/skills/apm-workflow/SKILL.md
Normal file
43
plugins/kyberforge/skills/apm-workflow/SKILL.md
Normal file
@@ -0,0 +1,43 @@
|
|||||||
|
---
|
||||||
|
name: apm-workflow
|
||||||
|
description: >
|
||||||
|
Use when the user wants to author or edit an apm.yml manifest
|
||||||
|
(dependencies, scripts, compilation, policy, registries), scaffold a new
|
||||||
|
apm package or marketplace (apm plugin init, apm marketplace init/package
|
||||||
|
add), register a marketplace as a consumer, compile/pack/publish an apm
|
||||||
|
package for distribution, or validate/audit apm.yml and installed content
|
||||||
|
(apm audit, apm marketplace check) — even if the user doesn't say "apm"
|
||||||
|
explicitly, e.g. "set up the package manifest", "scaffold this as an apm
|
||||||
|
package", "build the distributable", "check this passes CI". Do not use
|
||||||
|
for installing the apm binary itself or setting up an agent runtime — use
|
||||||
|
apm-install for those.
|
||||||
|
metadata:
|
||||||
|
category: apm
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
---
|
||||||
|
|
||||||
|
## Gotchas
|
||||||
|
|
||||||
|
- `apm.yml`'s `type:` field (`instructions`, `skill`, `hybrid`, `prompts`) constrains what `.apm/` may contain — set it before scaffolding content, not after. Changing it later doesn't retroactively validate what's already on disk.
|
||||||
|
- `includes: auto` publishes the authoritative local layout as-is. Anything narrower needs an explicit repo-path list — don't assume `auto` means "scoped down to what's relevant."
|
||||||
|
- `apm marketplace add` (registering a marketplace as a *consumer*, pointing at someone else's catalog) and `apm marketplace package add` (registering a local package *into* a marketplace you're building) are opposite directions of the same command family — don't conflate them.
|
||||||
|
- `apm pack` is the same command that both bundles a distributable artifact *and* emits `.claude-plugin/marketplace.json` as one of its compile targets — regenerating the Claude Code-native manifest isn't a separate step from packing.
|
||||||
|
- MCP server secrets (headers, env vars) inside `apm.yml` must use `${VAR}` indirection, never literal values, so they're resolved at install/runtime and never committed to the manifest.
|
||||||
|
- `apm experimental enable registries` must run before any `registry.*` config takes effect. Declaring a `registries:` block or running `apm config set registry.*` without it silently does nothing — no error, no warning.
|
||||||
|
- Plain `apm audit` and `apm audit --ci` check different things: plain `apm audit` scans deployed files for hidden Unicode only; `--ci` additionally runs lockfile-consistency checks, install-replay drift detection, and org policy checks. A clean plain `apm audit` is not a CI-equivalent pass.
|
||||||
|
|
||||||
|
## Step 1 — Dispatch
|
||||||
|
|
||||||
|
| Invocation | Action | Reference |
|
||||||
|
|---|---|---|
|
||||||
|
| `/apm-workflow configure` | Author/edit `apm.yml`; scaffold a new package (`apm plugin init`) | `references/configure.md` |
|
||||||
|
| `/apm-workflow marketplace` | Build a marketplace, register packages into it, or register a marketplace as a consumer (`apm marketplace init/check/package add/add`) | `references/marketplace.md` |
|
||||||
|
| `/apm-workflow compile` | Generate per-target output, bundle, or publish (`apm compile`, `apm pack`, `apm publish`) | `references/compile.md` |
|
||||||
|
| `/apm-workflow audit` | Validate integrity/policy, wire a CI gate, or check marketplace refs resolve (`apm audit`, `apm audit --ci`, `apm marketplace check`) | `references/audit.md` |
|
||||||
|
|
||||||
|
Read only the reference file matching the requested action — each is self-contained for its concern.
|
||||||
|
|
||||||
|
## Step 2 — Execute
|
||||||
|
|
||||||
|
Follow the matched reference file's instructions. Report back which `apm` command(s) were run (or drafted, if the user asked for a plan rather than execution) and their outcome.
|
||||||
49
plugins/kyberforge/skills/apm-workflow/references/audit.md
Normal file
49
plugins/kyberforge/skills/apm-workflow/references/audit.md
Normal file
@@ -0,0 +1,49 @@
|
|||||||
|
---
|
||||||
|
topic: audit
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
---
|
||||||
|
|
||||||
|
## `apm audit`
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm audit # local: scan deployed files for hidden Unicode
|
||||||
|
apm audit --ci # CI gate: lockfile consistency + drift replay + policy
|
||||||
|
apm audit --file <path> # standalone: scan an arbitrary file
|
||||||
|
```
|
||||||
|
|
||||||
|
`apm audit --ci` runs baseline lockfile checks, install-replay drift detection (does a clean `apm install` reproduce what's on disk), and org policy checks. Exit code `0` on success, `1` on any violation — composes as a normal CI gate step. It covers AI agent configuration integrity, hidden-content scanning, lockfile verification, and policy enforcement — it does not replace general lint/test/security-scan CI steps, it sits alongside them.
|
||||||
|
|
||||||
|
## Policy checks
|
||||||
|
|
||||||
|
`apm audit --ci` auto-discovers an org policy from the git remote if `--policy`/`--policy-source` isn't given explicitly; `--no-policy` skips policy discovery for a single invocation.
|
||||||
|
|
||||||
|
## Marketplace ref validation
|
||||||
|
|
||||||
|
Separate from `apm audit`: `apm marketplace check` validates that every package reference declared in a marketplace's `apm.yml` actually resolves (correct path/ref, manifest present) — run before `apm pack`/publish, to catch a typo'd local path or stale pinned tag before it ships.
|
||||||
|
|
||||||
|
## CI integration example (GitHub Actions)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
jobs:
|
||||||
|
apm-audit:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
permissions:
|
||||||
|
contents: read
|
||||||
|
security-events: write
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v4
|
||||||
|
- uses: actions/setup-python@v5
|
||||||
|
with: { python-version: "3.12" }
|
||||||
|
- run: pip install apm-cli==X.Y.Z # pin to the version standardized on
|
||||||
|
- run: apm install
|
||||||
|
- run: apm audit --ci -f sarif --output apm-audit.sarif
|
||||||
|
- uses: github/codeql-action/upload-sarif@v3
|
||||||
|
with: { sarif_file: apm-audit.sarif }
|
||||||
|
```
|
||||||
|
|
||||||
|
`-f sarif --output <file>` emits SARIF for GitHub Code Scanning's inline PR annotations.
|
||||||
|
|
||||||
|
## Frozen installs
|
||||||
|
|
||||||
|
`apm install --frozen` fails instead of silently re-resolving if the lockfile is out of date — the CI equivalent of `npm ci` vs `npm install`. Use in any CI job that must not be allowed to drift the lockfile.
|
||||||
42
plugins/kyberforge/skills/apm-workflow/references/compile.md
Normal file
42
plugins/kyberforge/skills/apm-workflow/references/compile.md
Normal file
@@ -0,0 +1,42 @@
|
|||||||
|
---
|
||||||
|
topic: compile
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compile
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm compile
|
||||||
|
```
|
||||||
|
|
||||||
|
Generates per-target output (Claude, Copilot, etc.) from the vendor-neutral `.apm/` primitive source tree, per the `compilation:` block in `apm.yml`. Run this after any change to `.apm/` content or to `compilation:`/`targets:` in `apm.yml`.
|
||||||
|
|
||||||
|
## Pack
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm pack --dry-run # resolve and print; do not write
|
||||||
|
apm pack --offline # cached refs only
|
||||||
|
apm pack --include-prerelease # allow pre-release tags
|
||||||
|
apm pack -v # per-entry resolution detail
|
||||||
|
apm pack --marketplace=claude --json # JSON output for CI pipelines
|
||||||
|
```
|
||||||
|
|
||||||
|
Bundles a producer package into a distributable artifact. Default to `--dry-run -v` first when packing something for the first time or after a dependency change — resolution errors surface before anything is written.
|
||||||
|
|
||||||
|
## Publish
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm publish --package acme/my-skill --dry-run -v
|
||||||
|
apm publish --package acme/my-skill
|
||||||
|
```
|
||||||
|
|
||||||
|
Publishes a producer package (root containing `apm.yml`, `.apm/`, and optionally a `registries:` block) to a registry. Always dry-run with `-v` first — publishing is not trivially reversible once a version tag is claimed on a registry.
|
||||||
|
|
||||||
|
## Run
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm run <script> [--param key=value]
|
||||||
|
```
|
||||||
|
|
||||||
|
Executes a named script defined under `scripts:` in `apm.yml`, with `--param` substituting values into the script's parameters.
|
||||||
127
plugins/kyberforge/skills/apm-workflow/references/configure.md
Normal file
127
plugins/kyberforge/skills/apm-workflow/references/configure.md
Normal file
@@ -0,0 +1,127 @@
|
|||||||
|
---
|
||||||
|
topic: configure
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
---
|
||||||
|
|
||||||
|
## Scaffolding a new package
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm plugin init <name> --yes
|
||||||
|
```
|
||||||
|
|
||||||
|
Scaffolds `apm.yml` + a `.apm/` skeleton in the current directory. Run this once per package (e.g. once per `plugins/<name>/` directory in a monorepo-hybrid layout), not once for the whole repo.
|
||||||
|
|
||||||
|
## `apm.yml` — required fields
|
||||||
|
|
||||||
|
Only `name` and `version` (SemVer) are required:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
name: my-pkg
|
||||||
|
version: 1.0.0
|
||||||
|
```
|
||||||
|
|
||||||
|
## `apm.yml` — full schema
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
name: my-pkg
|
||||||
|
version: 1.0.0
|
||||||
|
description: Code review skills for Python services
|
||||||
|
author: Jane Doe # plain string, or {name, email?, url?} object
|
||||||
|
license: MIT
|
||||||
|
homepage: https://example.com/my-pkg
|
||||||
|
repository: https://github.com/org/my-pkg
|
||||||
|
keywords: [ai, review, python]
|
||||||
|
|
||||||
|
type: skill # instructions | skill | hybrid | prompts — constrains .apm/ contents
|
||||||
|
|
||||||
|
targets: # which harnesses this package compiles to; prefer plural list form
|
||||||
|
- copilot
|
||||||
|
- claude
|
||||||
|
|
||||||
|
includes: auto # "auto" = publish the authoritative local layout; or list explicit repo paths
|
||||||
|
|
||||||
|
dependencies:
|
||||||
|
apm:
|
||||||
|
- microsoft/apm-sample-package#v1.0.0 # pinned to a tag
|
||||||
|
- github/awesome-copilot/skills/review-and-refactor # single primitive
|
||||||
|
mcp:
|
||||||
|
- microsoft/azure-devops-mcp # MCP server dependency
|
||||||
|
lsp:
|
||||||
|
- name: pyright
|
||||||
|
command: pyright-langserver
|
||||||
|
args: ["--stdio"]
|
||||||
|
extensionToLanguage:
|
||||||
|
".py": python
|
||||||
|
|
||||||
|
devDependencies: # same shape as dependencies, excluded from the shipped artifact
|
||||||
|
apm:
|
||||||
|
- my-org/internal-test-skills
|
||||||
|
|
||||||
|
scripts: # named commands runnable via `apm run <name>`
|
||||||
|
start: "copilot -p 'README.prompt.md'"
|
||||||
|
review: "copilot -p 'code-review.prompt.md'"
|
||||||
|
|
||||||
|
compilation:
|
||||||
|
target: all
|
||||||
|
strategy: distributed
|
||||||
|
exclude:
|
||||||
|
- "apm_modules/**"
|
||||||
|
placement:
|
||||||
|
min_instructions_per_file: 1
|
||||||
|
|
||||||
|
policy:
|
||||||
|
fetch_failure_default: warn
|
||||||
|
|
||||||
|
registries:
|
||||||
|
public-apm:
|
||||||
|
url: https://registry.example.com/api/public-apm
|
||||||
|
default: public-apm
|
||||||
|
|
||||||
|
marketplace: # see references/marketplace.md for the full marketplace workflow
|
||||||
|
owner:
|
||||||
|
name: contoso
|
||||||
|
url: https://github.com/contoso
|
||||||
|
packages:
|
||||||
|
- name: code-review
|
||||||
|
source: contoso/code-review
|
||||||
|
version: "^1.0.0"
|
||||||
|
tags: [review, quality]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Dependency reference forms
|
||||||
|
|
||||||
|
`dependencies.apm` entries accept: a pinned tag (`owner/repo#tag`), a plain repo (uses default branch), a single primitive path within a repo, a raw git URL, a `git:`/`path:`/`ref:` object for finer control, or a local relative path (`./packages/my-shared-skills`).
|
||||||
|
|
||||||
|
## MCP server secrets
|
||||||
|
|
||||||
|
Use `${VAR}` indirection for headers/env vars — never a literal secret value in `apm.yml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
mcp:
|
||||||
|
- name: linear
|
||||||
|
registry: false
|
||||||
|
transport: http
|
||||||
|
url: https://mcp.linear.app/sse
|
||||||
|
headers:
|
||||||
|
Authorization: "Bearer ${LINEAR_TOKEN}"
|
||||||
|
- name: my-internal
|
||||||
|
registry: false
|
||||||
|
transport: stdio
|
||||||
|
command: my-server
|
||||||
|
env:
|
||||||
|
API_TOKEN: "${MY_API_TOKEN}"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Registries (config-level, not `apm.yml`)
|
||||||
|
|
||||||
|
Any git repo is a valid package source by default — no registry required. To declare named registries for shorthand dependency resolution:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm experimental enable registries # required first — see SKILL.md Gotchas
|
||||||
|
apm config set registry.corp-main.url https://artifactory.corp.example.com/apm
|
||||||
|
apm config set registry.corp-main.token eyJ...
|
||||||
|
apm config set registry.corp-main.default true
|
||||||
|
```
|
||||||
|
|
||||||
|
`apm config get`/`apm config unset` manage individual keys the same way.
|
||||||
@@ -0,0 +1,61 @@
|
|||||||
|
---
|
||||||
|
topic: marketplace
|
||||||
|
source_keys:
|
||||||
|
- context7-microsoft-apm
|
||||||
|
---
|
||||||
|
|
||||||
|
## Building a marketplace from a producer repo
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm marketplace init # 1. add the marketplace: block to apm.yml
|
||||||
|
$EDITOR apm.yml # 2. describe each package
|
||||||
|
apm marketplace check # 3. validate refs resolve
|
||||||
|
apm pack # 4. build marketplace artifacts
|
||||||
|
git add apm.yml .claude-plugin/marketplace.json
|
||||||
|
git commit -m "Release v1.0.0" && git tag v1.0.0 && git push --tags
|
||||||
|
```
|
||||||
|
|
||||||
|
`apm pack` emits `.claude-plugin/marketplace.json` as one of its compile targets — an APM-based marketplace stays consumable by Claude Code's existing marketplace mechanism without a separately hand-maintained file.
|
||||||
|
|
||||||
|
## Registering a package into a marketplace you're building
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm marketplace package add ./packages/plugin-a --name plugin-a
|
||||||
|
```
|
||||||
|
|
||||||
|
Registers an already-existing local package path into the root marketplace listing without re-scaffolding it — this is the monorepo-hybrid command: point it at each existing `plugins/<name>/` directory once that directory has its own `apm.yml`.
|
||||||
|
|
||||||
|
## Registering a marketplace as a consumer
|
||||||
|
|
||||||
|
`apm marketplace add` accepts many source shapes:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apm marketplace add my-org/awesome-agents # GitHub shorthand
|
||||||
|
apm marketplace add gitlab.com/my-org/awesome-agents --host gitlab.com # GitLab
|
||||||
|
apm marketplace add https://gitea.example.com/org/repo.git#v1.0.0 --name custom # self-hosted git, pinned
|
||||||
|
apm marketplace add https://catalog.example.com/marketplace.json --name catalog # hosted marketplace.json
|
||||||
|
apm marketplace add git@gitea.example.com:org/repo.git --name custom # SSH
|
||||||
|
apm marketplace add /srv/marketplaces/agent-forge.git --name agent-forge # local bare repo/working dir
|
||||||
|
apm marketplace add ./vendor/marketplace.json --name vendor # local marketplace.json file
|
||||||
|
apm marketplace add file:///srv/marketplaces/agent-forge.git --name agent-forge # file:// form
|
||||||
|
```
|
||||||
|
|
||||||
|
The local-filesystem and `file://` forms need no hosted registry or network access — the fit for an internal/homelab setup.
|
||||||
|
|
||||||
|
## Per-package versioning
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
marketplace:
|
||||||
|
versioning: { strategy: per_package }
|
||||||
|
packages:
|
||||||
|
- { name: plugin-a, source: ./packages/plugin-a, version: 2.0.0 }
|
||||||
|
- { name: plugin-b, source: ./packages/plugin-b, version: 0.1.0 }
|
||||||
|
```
|
||||||
|
|
||||||
|
Without this block, the default versioning strategy ties every listed package to the marketplace/root version.
|
||||||
|
|
||||||
|
## Which mechanism to use
|
||||||
|
|
||||||
|
- **Local packages, no distribution needed yet** — local-path dependencies in `apm.yml` (`./packages/my-shared-skills`); no marketplace or registry involved.
|
||||||
|
- **Internal catalog, still git-based, no server** — `apm marketplace add` against a local path, bare repo, `file://` URI, or a plain git host.
|
||||||
|
- **Package-level hosting at scale / access control** — registries (Artifactory-style REST endpoint); more infrastructure, only worth it once package count or access-control needs outgrow git-based discovery.
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
# Sources
|
||||||
|
|
||||||
|
## context7-microsoft-apm
|
||||||
|
|
||||||
|
- **URL:** context7:/microsoft/apm
|
||||||
|
- **Description:** Microsoft APM (Agent Package Manager) — open-source dependency manager for AI agent configuration (skills, prompts, instructions, agents, hooks, MCP/LSP deps), applying a declare/lock/install/audit workflow.
|
||||||
|
- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
|
||||||
|
- **Contributing files:** SKILL.md, references/configure.md, references/marketplace.md, references/compile.md, references/audit.md
|
||||||
|
- **Status:** `extracted`
|
||||||
9
plugins/kyberforge/sources.md
Normal file
9
plugins/kyberforge/sources.md
Normal file
@@ -0,0 +1,9 @@
|
|||||||
|
# Sources
|
||||||
|
|
||||||
|
## context7-microsoft-apm
|
||||||
|
|
||||||
|
- **URL:** context7:/microsoft/apm
|
||||||
|
- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
|
||||||
|
- **Description:** Microsoft APM (Agent Package Manager) — open-source dependency manager for AI agent configuration (skills, prompts, instructions, agents, hooks, MCP/LSP deps), applying a declare/lock/install/audit workflow.
|
||||||
|
- **Contributing files:** agents/apm-orchestrate.md, agents/apm-orchestrate.agent.md
|
||||||
|
- **Status:** `extracted`
|
||||||
Reference in New Issue
Block a user