diff --git a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md index 012858e..a2c9901 100644 --- a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md +++ b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md @@ -44,8 +44,9 @@ new hand-maintained manifest format. - 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. +- `CONTEXT.md`'s "Plugin"/"Plugin marketplace" glossary entries get a forward-pointer to this + ADR so a session-start read surfaces the pending change; their substantive definitions remain + accurate until issue #90's conversion actually executes — this ADR does not rewrite them. ## Considered options diff --git a/plugins/kyberforge/.claude-plugin/plugin.json b/plugins/kyberforge/.claude-plugin/plugin.json index 53c4ce3..38a4a31 100644 --- a/plugins/kyberforge/.claude-plugin/plugin.json +++ b/plugins/kyberforge/.claude-plugin/plugin.json @@ -8,5 +8,5 @@ "keywords": [], "license": "MIT", "name": "kyberforge", - "version": "1.3.0" + "version": "1.3.1" } diff --git a/plugins/kyberforge/agents/apm-orchestrate.agent.md b/plugins/kyberforge/agents/apm-orchestrate.agent.md index 5ea8be9..eacd220 100644 --- a/plugins/kyberforge/agents/apm-orchestrate.agent.md +++ b/plugins/kyberforge/agents/apm-orchestrate.agent.md @@ -14,7 +14,7 @@ You are the orchestrator for apm package/marketplace operations — a composable 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. +**Scope:** this orchestrator routes `apm-workflow`'s five concerns only — configure/scaffold, marketplace, install, 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 @@ -28,7 +28,7 @@ These are non-negotiable regardless of `confirm` or any skill-local override: 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`) +3. Route to `apm-workflow` with the resolved action (`configure`, `marketplace`, `install`, `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//` 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 @@ -39,6 +39,7 @@ When invoked, you: - **operation:** string, one of: - configure: init-package - marketplace: init-marketplace, check-marketplace, add-package (→ `apm marketplace package add` — register a local package into a marketplace being built), add-marketplace (→ `apm marketplace add` — register a marketplace as a consumer) + - install: install (→ `apm install [PACKAGE_REF]` — resolve/fetch dependencies declared in `apm.yml` against `apm.lock.yaml`; no arguments re-resolves everything) - 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) @@ -49,7 +50,7 @@ When invoked, you: ## 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` +2. Check the request against the Hard rules above (publish confirmation, 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 diff --git a/plugins/kyberforge/agents/apm-orchestrate.md b/plugins/kyberforge/agents/apm-orchestrate.md index 56dd67e..ca67dcf 100644 --- a/plugins/kyberforge/agents/apm-orchestrate.md +++ b/plugins/kyberforge/agents/apm-orchestrate.md @@ -14,7 +14,7 @@ You are the orchestrator for apm package/marketplace operations — a composable 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. +**Scope:** this orchestrator routes `apm-workflow`'s five concerns only — configure/scaffold, marketplace, install, 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 @@ -28,7 +28,7 @@ These are non-negotiable regardless of `confirm` or any skill-local override: 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`) +3. Route to `apm-workflow` with the resolved action (`configure`, `marketplace`, `install`, `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//` 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 @@ -39,6 +39,7 @@ When invoked, you: - **operation:** string, one of: - configure: init-package - marketplace: init-marketplace, check-marketplace, add-package (→ `apm marketplace package add` — register a local package into a marketplace being built), add-marketplace (→ `apm marketplace add` — register a marketplace as a consumer) + - install: install (→ `apm install [PACKAGE_REF]` — resolve/fetch dependencies declared in `apm.yml` against `apm.lock.yaml`; no arguments re-resolves everything) - 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) @@ -49,7 +50,7 @@ When invoked, you: ## 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` +2. Check the request against the Hard rules above (publish confirmation, 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 diff --git a/plugins/kyberforge/docs/research/docs/microsoft-apm/installation.md b/plugins/kyberforge/docs/research/docs/microsoft-apm/installation.md index c617e2f..e254c66 100644 --- a/plugins/kyberforge/docs/research/docs/microsoft-apm/installation.md +++ b/plugins/kyberforge/docs/research/docs/microsoft-apm/installation.md @@ -17,7 +17,7 @@ On Windows, the installer adds both the current directory and the bin directory ## 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`. +- **Custom install directory**: set `APM_INSTALL_DIR` on the piped script's command, e.g. `curl -sSL https://aka.ms/apm-unix | 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 diff --git a/plugins/kyberforge/plugin.json b/plugins/kyberforge/plugin.json index a8e907f..4f7f8b0 100644 --- a/plugins/kyberforge/plugin.json +++ b/plugins/kyberforge/plugin.json @@ -13,5 +13,5 @@ "skills": [ "skills/" ], - "version": "1.3.0" + "version": "1.3.1" } diff --git a/plugins/kyberforge/skills/apm-install/SKILL.md b/plugins/kyberforge/skills/apm-install/SKILL.md index 318f0b3..4c8f07f 100644 --- a/plugins/kyberforge/skills/apm-install/SKILL.md +++ b/plugins/kyberforge/skills/apm-install/SKILL.md @@ -31,7 +31,7 @@ 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`. +- Custom install directory: set `APM_INSTALL_DIR` on the piped script's command, e.g. `curl -sSL https://aka.ms/apm-unix | 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`. diff --git a/plugins/kyberforge/skills/apm-workflow/README.md b/plugins/kyberforge/skills/apm-workflow/README.md index b813436..9c88640 100644 --- a/plugins/kyberforge/skills/apm-workflow/README.md +++ b/plugins/kyberforge/skills/apm-workflow/README.md @@ -4,7 +4,7 @@ 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. +Covers the apm.yml lifecycle a session moves through repeatedly: configuring/scaffolding a package manifest, resolving/fetching its declared dependencies, building or registering a marketplace, compiling/packing/publishing a distributable, and validating integrity via apm audit. Dispatches by requested action to one of five reference files, each self-contained for its concern. ## Before you start @@ -14,6 +14,7 @@ Requires the `apm` binary and (for runtime-driven scripts) an agent runtime alre ``` /apm-workflow configure +/apm-workflow install /apm-workflow marketplace /apm-workflow compile /apm-workflow audit @@ -25,6 +26,7 @@ Requires the `apm` binary and (for runtime-driven scripts) an agent runtime alre |------|---------| | `SKILL.md` | Dispatch table and cross-cutting gotchas | | `references/configure.md` | apm.yml schema, apm plugin init, dependency forms, MCP secrets, registries | +| `references/install.md` | apm install, apm install [PACKAGE_REF], --update, --target agent-skills | | `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 | diff --git a/plugins/kyberforge/skills/apm-workflow/SKILL.md b/plugins/kyberforge/skills/apm-workflow/SKILL.md index c2f1b2d..01b5b62 100644 --- a/plugins/kyberforge/skills/apm-workflow/SKILL.md +++ b/plugins/kyberforge/skills/apm-workflow/SKILL.md @@ -32,6 +32,7 @@ metadata: | Invocation | Action | Reference | |---|---|---| | `/apm-workflow configure` | Author/edit `apm.yml`; scaffold a new package (`apm plugin init`) | `references/configure.md` | +| `/apm-workflow install` | Resolve/fetch dependencies declared in `apm.yml` (`apm install`, `apm install [PACKAGE_REF]`) | `references/install.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` | diff --git a/plugins/kyberforge/skills/apm-workflow/references/configure.md b/plugins/kyberforge/skills/apm-workflow/references/configure.md index ae6d304..7647909 100644 --- a/plugins/kyberforge/skills/apm-workflow/references/configure.md +++ b/plugins/kyberforge/skills/apm-workflow/references/configure.md @@ -35,7 +35,7 @@ keywords: [ai, review, python] type: skill # instructions | skill | hybrid | prompts — constrains .apm/ contents -targets: # which harnesses this package compiles to; prefer plural list form +targets: # which harnesses this package compiles to; prefer plural list form — legacy singular `target: copilot,claude` CSV form is still accepted - copilot - claude diff --git a/plugins/kyberforge/skills/apm-workflow/references/install.md b/plugins/kyberforge/skills/apm-workflow/references/install.md new file mode 100644 index 0000000..760c44e --- /dev/null +++ b/plugins/kyberforge/skills/apm-workflow/references/install.md @@ -0,0 +1,20 @@ +--- +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. diff --git a/plugins/kyberforge/skills/apm-workflow/references/sources.md b/plugins/kyberforge/skills/apm-workflow/references/sources.md index ab4a6c5..3d257ea 100644 --- a/plugins/kyberforge/skills/apm-workflow/references/sources.md +++ b/plugins/kyberforge/skills/apm-workflow/references/sources.md @@ -5,5 +5,5 @@ - **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 +- **Contributing files:** SKILL.md, references/configure.md, references/install.md, references/marketplace.md, references/compile.md, references/audit.md - **Status:** `extracted`