feat(kyberforge): execute plugin-to-apm marketplace conversion
Why: ADR-0015 established that Microsoft APM (apm.yml + .apm/) should replace this repo's hand-authored plugin.json/marketplace.json model, with those files becoming compiled output of `apm pack` instead of files edited by hand via the (now-retired) plugin-author/marketplace-author skills. Issue #90 was the deferred execution of that decision, gated on #88 (apm tooling) and #89 (apm-native agent-author/skill-author routing). Implementation notes: - All six plugins (bin, core, git, gitea, kyberforge, lint) now carry apm.yml + .apm/{skills,agents,hooks} as their authoring source. Skills moved with a plain git mv (content-identical across targets). Agents were re-authored, not moved: per ADR-0016, .apm/agents/*.agent.md compiles verbatim to both Claude and Copilot, so plugin-scope agents now carry only name/description/model/source_keys -- no tools: field, no Claude-only knobs (isolation, maxTurns, effort, memory, permissionMode). - Root apm.yml registers all 7 marketplace packages (6 local plus mattpocock-skills as a remote entry) under versioning: per_package, matching this repo's existing independent-plugin-versioning practice. - .claude-plugin/marketplace.json and every plugin's plugin.json are now apm-pack-compiled output, verified against the prior hand-maintained content: same names/descriptions/versions/licenses/authors, only cosmetic serialization differences (JSON key order, owner email vs. url, Unicode escaping). - plugin-author and marketplace-author are retired now that apm-based authoring fully replaces their job; kyberforge bumped 1.3.1 -> 1.4.0 for that removal, and the root marketplace catalog bumped 0.3.1 -> 0.3.2 to match, per the version-bump convention now documented in apm-workflow's reference docs instead of a dedicated script (apm has no native version-bump automation). - Fixed hardcoded pre-.apm/ path assumptions across .pre-commit-config.yaml, .pre-commit-hooks.yaml, scripts/check-scope-walkup-sync.sh, scripts/sync-vale-styles.sh, scripts/check-vale-style-sync.sh, six plugins' root plugin.json (stale skills/hooks/agents pointer fields that check-manifests.sh validates), and several tests/*.bats and tests/*.sh fixtures -- including a bats REPO_ROOT relative-path depth bug (10 files, one extra .apm/ directory level to walk up) and a vale probe-path isolation regression introduced mid-fix. - Corrected empirically-wrong assumptions surfaced this session in apm-workflow/apm-install's own reference docs: `apm marketplace package add` does not accept local paths (only owner/repo remote shorthand -- local packages are registered by editing apm.yml's marketplace.packages[] directly); `apm compile` is a consumer-side AGENTS.md/CLAUDE.md generator, not the plugin.json producer, and hard-fails on skill/agent-only packages without --clean; `apm plugin init <name>` nests a stray subdirectory when run with a positional name arg from inside a same-named directory; no native Copilot marketplace output profile exists; .mcp.json is merged into the compiled plugin.json content-aware and target-scoped, with no dependencies.mcp entry needed for simple passthrough; pipx is the correct pip fallback on externally-managed Python environments. - Renamed agent-author's copilot.agent.md template asset to copilot.agent.md.template so apm compile's recursive *.agent.md glob stops misparsing the placeholder template as a real agent primitive. Impact: plugin.json and marketplace.json are compiled artifacts from here on -- editing them by hand is no longer the workflow; edit apm.yml/.apm/ and run apm pack. CONTEXT.md's Plugin/Plugin marketplace glossary entries reflect this. ADR-0001 is marked superseded, ADR-0006 moot, and ADR-0010 updated for the new .apm/agents/ path (project/user scope unaffected, per ADR-0016). Full local verification: claude plugin validate --strict on all 6 plugins, apm audit --ci, apm marketplace check, check-manifests.sh, and the full test suite (165/165 bats, 13/13 shell scripts) all pass clean. Fixes: #90 Refs: #88, #89 ADR: 0015 ADR: 0016 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ub96PyaSRD9BHPktotj1pC
This commit is contained in:
@@ -1,55 +0,0 @@
|
||||
---
|
||||
topic: audit
|
||||
source_keys:
|
||||
- context7-microsoft-apm
|
||||
- context7-websites-code-claude
|
||||
- claude-code-plugins-docs
|
||||
---
|
||||
|
||||
## `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
|
||||
```
|
||||
|
||||
Exit code `0` on success, `1` on any violation — composes as a normal CI gate step. 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.
|
||||
|
||||
## Claude Code validation is a separate terminal check
|
||||
|
||||
For packages compiling to the `claude` target, also run `claude plugin validate [--strict]` against the compiled output as a terminal check. `apm audit`/`apm audit --ci` do not check Claude Code-marketplace-specific schema rules (reserved prefixes, the `agents/` stray-file behavior — see `references/compile.md` — etc.), so they don't substitute for it.
|
||||
@@ -1,48 +0,0 @@
|
||||
---
|
||||
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.
|
||||
|
||||
Run `apm audit` after compile/pack, not before — audit scans deployed/compiled output, not the source `apm.yml` manifest; see `references/audit.md`.
|
||||
|
||||
## 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.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- `claude plugin validate --strict` auto-scans every `.md` file directly under a compiled plugin's `agents/` directory and treats it as an agent definition requiring frontmatter, independent of any manifest declaration (an empirically observed Claude Code platform behavior, not an `apm` mechanic). A non-agent `.md` file (notes, provenance record, README) that ends up under `.apm/agents/` in the source tree will still fail validation once compiled to the `claude` target. Keep such files outside `.apm/agents/` (e.g. at the package root), regardless of what `apm.yml` declares.
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
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` — top-level keys
|
||||
|
||||
- `name`, `version` — required (see above)
|
||||
- `description`, `author`, `license`, `homepage`, `repository`, `keywords` — standard package metadata
|
||||
- `type` — `instructions | skill | hybrid | prompts`; constrains `.apm/` contents
|
||||
- `targets` — which harnesses this package compiles to (plural list form preferred; legacy singular `target: copilot,claude` CSV form still accepted)
|
||||
- `includes` — `auto` publishes the authoritative local layout as-is, or list explicit repo paths
|
||||
- `dependencies`/`devDependencies` — `apm`/`mcp`/`lsp` entries; `devDependencies` share the same shape but are excluded from the shipped artifact
|
||||
- `scripts` — named commands runnable via `apm run <name>`
|
||||
- `compilation` — target/strategy/exclude/placement controls for `apm compile`/`apm pack`
|
||||
- `policy` — e.g. `fetch_failure_default`
|
||||
- `registries` — named registry endpoints for shorthand dependency resolution
|
||||
- `marketplace` — owner + packages list; see `references/marketplace.md` for the full marketplace workflow
|
||||
|
||||
See `docs/research/docs/microsoft-apm/configuration.md` for the complete annotated schema.
|
||||
|
||||
## 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
|
||||
|
||||
`${VAR}` indirection is required for MCP server secrets in `apm.yml` — see SKILL.md Gotchas.
|
||||
|
||||
## 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.
|
||||
@@ -1,20 +0,0 @@
|
||||
---
|
||||
topic: install
|
||||
source_keys:
|
||||
- context7-microsoft-apm
|
||||
---
|
||||
|
||||
## `apm install`
|
||||
|
||||
```bash
|
||||
apm install # resolve/install everything in apm.yml against apm.lock.yaml
|
||||
apm install acme/internal-tools#^1.0.0 # install and add this dependency
|
||||
apm install --update # re-resolve; accept new upstream content even if it doesn't match the lockfile hash
|
||||
apm install --target agent-skills # emit a vendor-neutral output dir instead of a harness-specific one
|
||||
```
|
||||
|
||||
With no arguments, resolves and installs everything declared under `dependencies:`/`devDependencies:` in `apm.yml` against `apm.lock.yaml`. One or more `PACKAGE_REF` arguments (any of the forms in `references/configure.md`'s "Dependency reference forms" — pinned tag, plain repo, single primitive, raw git URL, `git:`/`path:`/`ref:` object, or local relative path) install that dependency and add it to `apm.yml`.
|
||||
|
||||
`--update` is the escape hatch for a lockfile hash mismatch against upstream — normal `apm install` treats that as drift and won't silently accept it; see `references/audit.md` for the CI-side check (`apm install --frozen`) that fails instead of re-resolving.
|
||||
|
||||
`--target agent-skills` generates the vendor-neutral output directory instead of a Claude/Copilot-specific one — for IDE-agnostic tool support.
|
||||
@@ -1,71 +0,0 @@
|
||||
---
|
||||
topic: marketplace
|
||||
source_keys:
|
||||
- context7-microsoft-apm
|
||||
- context7-websites-code-claude
|
||||
- claude-code-plugins-docs
|
||||
---
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
5. Commit and release — commit the manifest changes, tag the release, and push, following your
|
||||
project's established git tooling/conventions (a dedicated commit/release skill or workflow,
|
||||
commitlint/Conventional Commits rules, required tags) rather than ad hoc raw `git` invocations,
|
||||
if such tooling exists.
|
||||
|
||||
`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.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- A package/plugin `name` compiling to the `claude` target must avoid Claude Code's reserved name prefixes (see `plugin-author/SKILL.md` Gotchas for the current list) — otherwise the compiled `.claude-plugin/marketplace.json` is rejected by Claude Code's validator. This is a Claude Code platform constraint, independent of how the manifest gets authored.
|
||||
- Removing a package from `marketplace.packages[]` in `apm.yml` and re-packing changes the public/consumed catalog. Confirm with the user in conversation before removing the entry and running `apm pack` — this is a normal `apm.yml` edit (not a distinct apm-orchestrate operation with its own gate), so the confirmation is conversational, the same as any other consequential manifest edit.
|
||||
@@ -1,33 +0,0 @@
|
||||
# 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/install.md, references/marketplace.md, references/compile.md, references/audit.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## context7-websites-code-claude
|
||||
|
||||
- **URL:** context7:/websites/code_claude
|
||||
- **Description:** Official Claude Code documentation site indexed by Context7 — marketplace manifest schema (reserved name prefixes), `claude plugin validate` command behavior. Claude Code platform facts that hold true independent of how the compiled manifest is authored (APM or hand-authored).
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md
|
||||
- **Contributing files:** references/marketplace.md, references/audit.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## claude-code-plugins-docs
|
||||
|
||||
- **URL:** https://code.claude.com/docs/en/plugins
|
||||
- **Description:** Official Claude Code plugin authoring guide — marketplace submission constraints (reserved name prefixes), `claude plugin validate` behavior and its scope relative to other CI checks.
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md
|
||||
- **Contributing files:** references/marketplace.md, references/audit.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## claude-code-subagents-docs
|
||||
|
||||
- **URL:** https://code.claude.com/docs/en/sub-agents
|
||||
- **Description:** Official Claude Code subagent reference — definition format, all frontmatter fields, scope priority, built-in agents, CLI flags, environment variables, known limitations
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md
|
||||
- **Contributing files:** (none)
|
||||
- **Status:** `referenced`
|
||||
Reference in New Issue
Block a user