docs: correct claims the apm conversion left false
Documentation asserted things the code no longer did, which is how several of this round's defects survived three review passes. - `docs/spec/architecture.md` still described the pre-APM model — "each plugin has a `plugin.json` manifest" — when no such file exists. AGENTS.md routes agents here for the current structure, so it was live drift, not archive. Also cited ADR-0012 where ADR-0003 is meant. - AGENTS.md never said `.apm/` is the sole hand-edited source, while the generated mirror is byte-identical with no marker — an agent reading only AGENTS.md would edit the mirror and find out at pre-push. It also omitted that `apm` and `jq` are now required to push, unlike the `vale` bullet that exists for exactly that reason, and understated the pre-push gate. `apm marketplace check` hard-fails offline and `--offline` does not help, so the `SKIP=` escape hatch is documented rather than new machinery built. - ADR-0017 carried hardcoded line numbers that drifted twice within one PR, and said `mcpServers` reinjection was real-syncs-only where the script's own header says both modes. Line numbers dropped rather than corrected. - ADR-0015 asserted issue #90 was closed. It is open. Reworded to defer to the issue's own state rather than depend on someone remembering to close it. - ADR-0014 said both audit skills pass `--config`; both SKILL.md files say pass none, and passing one fails with E100. The ADR was wrong. - ADR-0007 cross-referenced an archived ADR-0011 whose number was later reused. Disambiguated with a note — renumbering a published ADR rewrites an immutable record and breaks every existing citation. - CONTEXT.md claimed `lint-runner` is report-only via a missing `Edit` tool. Plugin-scope APM agents cannot express `tools:` (ADR-0016), so it is report-only by instruction now; ADR-0016 accepted that regression but CONTEXT.md was not updated. - Recorded two undocumented consequences of the conversion: `displayName` dropped from all six compiled manifests and `owner.email` from the marketplace, and `mattpocock-skills` silently version-pinned and manually maintained. - Wrote the version-bump policy issue #90 specified but never delivered. Its previous carrier, `marketplace-author`, was deleted in this PR, leaving the per-package rule documented nowhere. - README fixes: kyberforge listed skills belonging to the `git` plugin and a deleted hooks path, `bin` advertised an agents directory it never had, and the docs index listed files that do not exist. Refs: #90 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
This commit is contained in:
@@ -30,10 +30,12 @@ copilot plugin install ./plugins/bin
|
||||
|
||||
## Contents
|
||||
|
||||
| Component | Path | Description |
|
||||
| -------------| ------------------------------------------------------| ---------------------------------------------------------------|
|
||||
| Skills | `skills/` | Slash commands available after install |
|
||||
| Agents | `agents/` | Role-based agents (`.md` for Claude, `.agent.md` for Copilot) |
|
||||
| Component | Path | Description |
|
||||
|---|---|---|
|
||||
| Skills | `.apm/skills/` → `skills/` | Slash commands available after install |
|
||||
| MCP servers | `.mcp.json` | The `obsidian` server (`npx @bitbonsai/mcpvault@latest docs/`), hand-authored at the plugin root and reinjected into both compiled `plugin.json` manifests |
|
||||
|
||||
`.apm/` is the authoring source; `skills/` is the generated mirror plugin hosts scan (ADR-0017). This plugin ships no agents. It is the only plugin here with a non-empty `.mcp.json`, which is why its compiled manifests are the only ones carrying an `mcpServers` block.
|
||||
|
||||
## Author
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# core
|
||||
|
||||
Cross-cutting utility skills for everyday AI-assisted coding — triage, diagnosis, architecture review, and session navigation.
|
||||
Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.
|
||||
|
||||
## Install
|
||||
|
||||
@@ -32,7 +32,9 @@ copilot plugin install ./plugins/core
|
||||
|
||||
| Component | Path | Description |
|
||||
|---|---|---|
|
||||
| Skills | `skills/` | Slash commands available after install |
|
||||
| Skills | `.apm/skills/` → `skills/` | Slash commands available after install |
|
||||
|
||||
`.apm/` is the authoring source; `skills/` is the generated mirror plugin hosts scan (ADR-0017).
|
||||
|
||||
## Skills
|
||||
|
||||
|
||||
@@ -7,3 +7,11 @@
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
|
||||
- **Contributing files:** SKILL.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## apm-github-repo
|
||||
|
||||
- **URL:** https://github.com/microsoft/apm
|
||||
- **Description:** APM's own Python source (`src/apm_cli/`), read directly for schema and compile-mapping ground truth where Context7's doc snippets were thin. Informed the research doc's primitive-schema and releasing pages; nothing in this skill's install/runtime guidance derives from it.
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
|
||||
- **Contributing files:** (none)
|
||||
- **Status:** `referenced`
|
||||
|
||||
@@ -37,6 +37,31 @@ version: 1.0.0
|
||||
|
||||
See `docs/research/docs/microsoft-apm/configuration.md` for the complete annotated schema.
|
||||
|
||||
## Bumping a package's own version (repo policy)
|
||||
|
||||
apm ships no version-bump command, so `version:` in a package's own `apm.yml` is a hand edit.
|
||||
Policy: **bump a package's own `apm.yml` `version:` whenever anything that reaches its compiled
|
||||
output changes.** Two triggers, not one:
|
||||
|
||||
- **Its `.apm/` content** — a new or removed skill/agent/hook, or a substantive edit to an
|
||||
existing one.
|
||||
- **Its own `apm.yml` manifest metadata** — `description`, `keywords`, `author`, `license`,
|
||||
`homepage`, `repository`. These are compiled verbatim into `.claude-plugin/plugin.json` and
|
||||
`.github/plugin/plugin.json`, so editing them republishes the package's public description
|
||||
under an unchanged version number, which is the same defect as shipping changed content
|
||||
silently. Purely local edits that reach no compiled output — a `README.md`, a `docs/` page —
|
||||
do not require a bump on their own.
|
||||
|
||||
The version belongs to the package, not to the repo: editing `plugins/foo/.apm/` never bumps
|
||||
`plugins/bar/apm.yml`.
|
||||
|
||||
Under a `per_package` strategy the same number is also carried in the catalog's
|
||||
`marketplace.packages[]` entry, so both copies move together in the same commit. The catalog's own
|
||||
version follows a separate rule — see `references/marketplace.md`. `apm pack --check-versions`
|
||||
fails the push when a package's version disagrees with the configured strategy, so a bump applied
|
||||
in only one of the two places is caught, but a bump skipped in both is not: nothing infers intent
|
||||
from a content diff.
|
||||
|
||||
## 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`).
|
||||
|
||||
@@ -4,6 +4,7 @@ source_keys:
|
||||
- context7-microsoft-apm
|
||||
- context7-websites-code-claude
|
||||
- claude-code-plugins-docs
|
||||
- apm-github-repo
|
||||
---
|
||||
|
||||
## Building a marketplace from a producer repo
|
||||
@@ -68,6 +69,33 @@ marketplace:
|
||||
|
||||
Without this block, the default versioning strategy ties every listed package to the marketplace/root version.
|
||||
|
||||
## Bumping the catalog's own version (repo policy)
|
||||
|
||||
The section above is apm's *mechanic* — how per-package versions are declared and how
|
||||
`marketplace.versioning.strategy` resolves them. This section is *policy*: apm has no version-bump
|
||||
automation, so the one number apm will never pick for you is the catalog's own
|
||||
`marketplace.version` in the root `apm.yml`. Bump it by hand, in the same commit as the change that
|
||||
earned it:
|
||||
|
||||
- **Minor** when a `marketplace.packages[]` entry is added or removed. The catalog's contents
|
||||
changed — a consumer resolving it now gets a different set of installable packages.
|
||||
- **Patch** when only `marketplace:`-block fields change and the set of packages is unchanged: the
|
||||
catalog description, owner, `build:`/`outputs:` config, or an existing entry's `version:`,
|
||||
description, or category. The catalog describes the same packages; only its metadata moved. An
|
||||
entry's `version:` is the most frequent of these by far — under `per_package` it moves here every
|
||||
time any package bumps (see `references/configure.md`), and that alone earns the catalog patch.
|
||||
|
||||
Keep the root `apm.yml`'s top-level `version:` in step with `marketplace.version`. They are separate
|
||||
keys — the top-level one is not inherited into the compiled `marketplace.json`, but `apm audit`
|
||||
reads it — so letting them diverge produces two different answers to "what version is this catalog".
|
||||
|
||||
Editing a package's *own* `.apm/` content is a different bump against a different number — see
|
||||
`references/configure.md`. Note what the tooling does and does not catch: `apm pack --check-clean`
|
||||
regenerates every marketplace output and diffs it against what is on disk, so a bump made in
|
||||
`apm.yml` but never re-packed fails the gate. A bump you never made at all fails nothing — no apm
|
||||
flag infers a required version change from a content diff, which is why this is policy and not a
|
||||
hook.
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -8,6 +8,14 @@
|
||||
- **Contributing files:** SKILL.md, references/configure.md, references/install.md, references/marketplace.md, references/compile.md, references/audit.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## apm-github-repo
|
||||
|
||||
- **URL:** https://github.com/microsoft/apm
|
||||
- **Description:** APM's own Python source (`src/apm_cli/`), read directly for schema and compile-mapping ground truth where Context7's doc snippets were thin. Backs the marketplace output-profile claim (`apm_cli/marketplace/output_profiles.py` — only `claude` and `codex` profiles exist, so there is no native Copilot marketplace output) and the `apm pack --check-clean`/`--check-versions` semantics.
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
|
||||
- **Contributing files:** references/marketplace.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## context7-websites-code-claude
|
||||
|
||||
- **URL:** context7:/websites/code_claude
|
||||
|
||||
@@ -30,25 +30,31 @@ copilot plugin install ./plugins/kyberforge
|
||||
|
||||
## Contents
|
||||
|
||||
Authoring source lives in `.apm/`. The `skills/`, `agents/`, and `hooks/hooks.json` paths below are the generated mirror that plugin hosts actually scan — produced by `scripts/sync-plugin-content.sh`, never hand-edited (ADR-0017).
|
||||
|
||||
| Component | Path | Description |
|
||||
|---|---|---|
|
||||
| Skills | `skills/` | Slash commands available after install |
|
||||
| Agents | `agents/` | Role-based agents (`.md` for Claude, `.agent.md` for Copilot) |
|
||||
| Hooks | `hooks/hooks.json` (Claude) / `hooks.json` (Copilot) | Event-triggered automation |
|
||||
| MCP servers | `.mcp.json` | Model Context Protocol server definitions |
|
||||
| Skills | `.apm/skills/` → `skills/` | Slash commands available after install |
|
||||
| Agents | `.apm/agents/*.agent.md` → `agents/` | Role-based agents; one vendor-neutral `.agent.md` per agent, copied verbatim to both targets (ADR-0016) |
|
||||
| Hooks | `.apm/hooks/` → `hooks/hooks.json` | Event-triggered automation — read by Claude Code only, see below |
|
||||
| MCP servers | `.mcp.json` | Model Context Protocol server definitions (hand-authored at the plugin root) |
|
||||
|
||||
**Hooks are Claude Code-only in practice.** Claude Code convention-scans `hooks/hooks.json` at the plugin root, so that file is live. Copilot CLI has no default hooks path — `agents` and `skills` default to `agents/` and `skills/`, but `hooks` defaults to nothing (`docs/research/docs/github-copilot-plugins/configuration.md:47`), so Copilot reads hooks only via an explicit `"hooks": "hooks.json"` pointer in `plugin.json` (`docs/research/docs/github-copilot-plugins/examples.md:49`). apm's manifest compiler strips pointer fields from every manifest it generates, so neither `.claude-plugin/plugin.json` nor `.github/plugin/plugin.json` carries one, and re-injecting it is the option ADR-0017 explicitly rejected. Copilot therefore loads no hooks from this plugin — and did not load them from the old root-level `hooks.json` either. The Copilot half of this row is aspirational, not current behaviour.
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | Description |
|
||||
|---|---|
|
||||
| `forge` | Grill an unclassified "I want to add something" request, decide whether it's a skill, agent, plugin, or marketplace entry, then route to the matching author skill |
|
||||
| `skill-author` | Create or improve a skill from scratch, audit findings, or inline feedback |
|
||||
| `skill-audit` | Audit a skill directory against the agentskills.io spec and produce a findings report |
|
||||
| `agent-author` | Author an agent definition file |
|
||||
| `pc-author` | Create, add, remove, and configure `.pre-commit-config.yaml` |
|
||||
| `pc-run` | Install, run, autoupdate, and maintain the pre-commit setup |
|
||||
| `agent-audit` | Audit an agent definition across structure, provider safety, description and body quality, and provenance; produces a findings report |
|
||||
| `apm-install` | Install or upgrade the apm CLI and set up the agent runtimes it drives (Copilot CLI, Codex, Gemini, generic llm) |
|
||||
| `apm-workflow` | Author apm.yml, scaffold an apm package/marketplace, install dependencies, and compile/pack/publish/audit apm content |
|
||||
|
||||
Pre-commit tooling (`pc-author`, `pc-run`) lives in the `git` plugin, not here.
|
||||
|
||||
## Author
|
||||
|
||||
Defame1297
|
||||
|
||||
@@ -2,12 +2,7 @@
|
||||
|
||||
Plugin documentation. Not read automatically by Claude Code or GitHub Copilot CLI — reference specific files from skill bodies or agent prompts as needed.
|
||||
|
||||
## Files
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `plugin-marketplace-architecture.md` | Claude Code vs Copilot CLI divergence, two-manifest pattern, plugin constraints, cross-tool compatibility |
|
||||
| `adding-agents.md` | How to add agent definitions to the kyberforge plugin |
|
||||
This directory currently holds no standalone documents of its own — everything under it is research material.
|
||||
|
||||
## research/
|
||||
|
||||
@@ -16,5 +11,9 @@ Upstream reference material gathered during skill authoring. Not shipped with th
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `research/docs/agentskillsio/` | agentskills.io spec, skill authoring, description optimization, eval design, scripts |
|
||||
| `research/docs/agentsmd/` | agents.md format spec and cross-tool configuration reference |
|
||||
| `research/examples/skill-write/` | Upstream skill examples reviewed when authoring skill-write and skill-audit |
|
||||
| `research/docs/claude-code-plugins/` | Claude Code plugin and marketplace manifests, plugin directory layout, agent definition format, `claude plugin validate` behaviour |
|
||||
| `research/docs/github-copilot-plugins/` | Copilot CLI plugin manifest and marketplace format, agent definition format, Copilot extensions and SDK |
|
||||
| `research/docs/microsoft-apm/` | apm CLI reference, `apm.yml` schema, primitive schemas (agent, prompt, instructions, hooks), monorepo repo shapes, marketplace/registries, packing and releasing |
|
||||
| `research/examples/skill-write/` | Upstream skill examples reviewed when authoring skill-author and skill-audit |
|
||||
|
||||
AGENTS.md research moved to `plugins/core/docs/research/docs/agentsmd/` when the AGENTS.md skills landed in the `core` plugin (ADR-0012) — it is no longer part of kyberforge's provenance chain.
|
||||
|
||||
@@ -7,3 +7,11 @@
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
|
||||
- **Contributing files:** SKILL.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## apm-github-repo
|
||||
|
||||
- **URL:** https://github.com/microsoft/apm
|
||||
- **Description:** APM's own Python source (`src/apm_cli/`), read directly for schema and compile-mapping ground truth where Context7's doc snippets were thin. Informed the research doc's primitive-schema and releasing pages; nothing in this skill's install/runtime guidance derives from it.
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
|
||||
- **Contributing files:** (none)
|
||||
- **Status:** `referenced`
|
||||
|
||||
@@ -37,6 +37,31 @@ version: 1.0.0
|
||||
|
||||
See `docs/research/docs/microsoft-apm/configuration.md` for the complete annotated schema.
|
||||
|
||||
## Bumping a package's own version (repo policy)
|
||||
|
||||
apm ships no version-bump command, so `version:` in a package's own `apm.yml` is a hand edit.
|
||||
Policy: **bump a package's own `apm.yml` `version:` whenever anything that reaches its compiled
|
||||
output changes.** Two triggers, not one:
|
||||
|
||||
- **Its `.apm/` content** — a new or removed skill/agent/hook, or a substantive edit to an
|
||||
existing one.
|
||||
- **Its own `apm.yml` manifest metadata** — `description`, `keywords`, `author`, `license`,
|
||||
`homepage`, `repository`. These are compiled verbatim into `.claude-plugin/plugin.json` and
|
||||
`.github/plugin/plugin.json`, so editing them republishes the package's public description
|
||||
under an unchanged version number, which is the same defect as shipping changed content
|
||||
silently. Purely local edits that reach no compiled output — a `README.md`, a `docs/` page —
|
||||
do not require a bump on their own.
|
||||
|
||||
The version belongs to the package, not to the repo: editing `plugins/foo/.apm/` never bumps
|
||||
`plugins/bar/apm.yml`.
|
||||
|
||||
Under a `per_package` strategy the same number is also carried in the catalog's
|
||||
`marketplace.packages[]` entry, so both copies move together in the same commit. The catalog's own
|
||||
version follows a separate rule — see `references/marketplace.md`. `apm pack --check-versions`
|
||||
fails the push when a package's version disagrees with the configured strategy, so a bump applied
|
||||
in only one of the two places is caught, but a bump skipped in both is not: nothing infers intent
|
||||
from a content diff.
|
||||
|
||||
## 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`).
|
||||
|
||||
@@ -4,6 +4,7 @@ source_keys:
|
||||
- context7-microsoft-apm
|
||||
- context7-websites-code-claude
|
||||
- claude-code-plugins-docs
|
||||
- apm-github-repo
|
||||
---
|
||||
|
||||
## Building a marketplace from a producer repo
|
||||
@@ -68,6 +69,33 @@ marketplace:
|
||||
|
||||
Without this block, the default versioning strategy ties every listed package to the marketplace/root version.
|
||||
|
||||
## Bumping the catalog's own version (repo policy)
|
||||
|
||||
The section above is apm's *mechanic* — how per-package versions are declared and how
|
||||
`marketplace.versioning.strategy` resolves them. This section is *policy*: apm has no version-bump
|
||||
automation, so the one number apm will never pick for you is the catalog's own
|
||||
`marketplace.version` in the root `apm.yml`. Bump it by hand, in the same commit as the change that
|
||||
earned it:
|
||||
|
||||
- **Minor** when a `marketplace.packages[]` entry is added or removed. The catalog's contents
|
||||
changed — a consumer resolving it now gets a different set of installable packages.
|
||||
- **Patch** when only `marketplace:`-block fields change and the set of packages is unchanged: the
|
||||
catalog description, owner, `build:`/`outputs:` config, or an existing entry's `version:`,
|
||||
description, or category. The catalog describes the same packages; only its metadata moved. An
|
||||
entry's `version:` is the most frequent of these by far — under `per_package` it moves here every
|
||||
time any package bumps (see `references/configure.md`), and that alone earns the catalog patch.
|
||||
|
||||
Keep the root `apm.yml`'s top-level `version:` in step with `marketplace.version`. They are separate
|
||||
keys — the top-level one is not inherited into the compiled `marketplace.json`, but `apm audit`
|
||||
reads it — so letting them diverge produces two different answers to "what version is this catalog".
|
||||
|
||||
Editing a package's *own* `.apm/` content is a different bump against a different number — see
|
||||
`references/configure.md`. Note what the tooling does and does not catch: `apm pack --check-clean`
|
||||
regenerates every marketplace output and diffs it against what is on disk, so a bump made in
|
||||
`apm.yml` but never re-packed fails the gate. A bump you never made at all fails nothing — no apm
|
||||
flag infers a required version change from a content diff, which is why this is policy and not a
|
||||
hook.
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -8,6 +8,14 @@
|
||||
- **Contributing files:** SKILL.md, references/configure.md, references/install.md, references/marketplace.md, references/compile.md, references/audit.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## apm-github-repo
|
||||
|
||||
- **URL:** https://github.com/microsoft/apm
|
||||
- **Description:** APM's own Python source (`src/apm_cli/`), read directly for schema and compile-mapping ground truth where Context7's doc snippets were thin. Backs the marketplace output-profile claim (`apm_cli/marketplace/output_profiles.py` — only `claude` and `codex` profiles exist, so there is no native Copilot marketplace output) and the `apm pack --check-clean`/`--check-versions` semantics.
|
||||
- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
|
||||
- **Contributing files:** references/marketplace.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## context7-websites-code-claude
|
||||
|
||||
- **URL:** context7:/websites/code_claude
|
||||
|
||||
Reference in New Issue
Block a user