Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

feat(kyberforge): add apm-install/apm-workflow/apm-orchestrate, ADR-0015 #91

Merged
Claude merged 11 commits from feat/88-marketplace-apm-conversion into main 2026-08-11 16:05:56 +00:00
Conversation 11 Commits 11 Files Changed 36 +41 -15
12 changed files with 41 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 394052ff66 - Show all commits

5
docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md
View File

@@ -44,8 +44,9 @@ new hand-maintained manifest format.
- Actually translating the existing plugins into `apm.yml` + `.apm/` and running the real - Actually translating the existing plugins into `apm.yml` + `.apm/` and running the real
conversion is deferred to issue #90 conversion is deferred to issue #90
(https://git.dev.rkdr.net/Defame1297/holocron/issues/90). (https://git.dev.rkdr.net/Defame1297/holocron/issues/90).
- `CONTEXT.md`'s "Plugin"/"Skill"/"Plugin marketplace" glossary entries remain accurate as - `CONTEXT.md`'s "Plugin"/"Plugin marketplace" glossary entries get a forward-pointer to this
written until issue #90 actually executes — this ADR does not update them. 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 ## Considered options

2
plugins/kyberforge/.claude-plugin/plugin.json
View File

@@ -8,5 +8,5 @@
"keywords": [], "keywords": [],
"license": "MIT", "license": "MIT",
"name": "kyberforge", "name": "kyberforge",
"version": "1.3.0" "version": "1.3.1"
} }

7
plugins/kyberforge/agents/apm-orchestrate.agent.md
View File

@@ -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. 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 ## Hard rules
@@ -28,7 +28,7 @@ These are non-negotiable regardless of `confirm` or any skill-local override:
When invoked, you: When invoked, you:
1. Parse the incoming workflow request (operation type, parameters, target package(s), context overrides) 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" 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 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 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 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
@@ -39,6 +39,7 @@ When invoked, you:
- **operation:** string, one of: - **operation:** string, one of:
- configure: init-package - 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) - 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 - compile: compile, pack, publish, run-script
- audit: audit, audit-ci - 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) - **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 ## Process
1. Validate the request structure and check if `operation` is known 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 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` 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 5. Invoke `apm-workflow` with the resolved action, `package_root`, and parameters

7
plugins/kyberforge/agents/apm-orchestrate.md
View File

@@ -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. 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 ## Hard rules
@@ -28,7 +28,7 @@ These are non-negotiable regardless of `confirm` or any skill-local override:
When invoked, you: When invoked, you:
1. Parse the incoming workflow request (operation type, parameters, target package(s), context overrides) 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" 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 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 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 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
@@ -39,6 +39,7 @@ When invoked, you:
- **operation:** string, one of: - **operation:** string, one of:
- configure: init-package - 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) - 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 - compile: compile, pack, publish, run-script
- audit: audit, audit-ci - 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) - **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 ## Process
1. Validate the request structure and check if `operation` is known 1. Validate the request structure and check if `operation` is known
Defame1297 marked this conversation as resolved
Claude commented 2026-08-11 05:36:35 +00:00
Review
Copy Link

Process step 2 still tells the orchestrator to check the Hard rules for "secret indirection," but that Hard Rule bullet was deleted from the Hard rules section in this same PR's fix commit (e16c3dc), leaving a dangling reference to a rule that no longer exists.

Failure scenario: An executing agent reads Process step 2, tries to locate and enforce the named "secret indirection" Hard Rule, and finds nothing in the Hard rules list — it either hallucinates a check to satisfy the reference or silently skips it while the text implies the gate still exists.

Identical issue at plugins/kyberforge/agents/apm-orchestrate.agent.md:52.

Process step 2 still tells the orchestrator to check the Hard rules for "secret indirection," but that Hard Rule bullet was deleted from the Hard rules section in this same PR's fix commit (e16c3dc), leaving a dangling reference to a rule that no longer exists. **Failure scenario:** An executing agent reads Process step 2, tries to locate and enforce the named "secret indirection" Hard Rule, and finds nothing in the Hard rules list — it either hallucinates a check to satisfy the reference or silently skips it while the text implies the gate still exists. Identical issue at `plugins/kyberforge/agents/apm-orchestrate.agent.md:52`.
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 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` 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 5. Invoke `apm-workflow` via `Skill` with the resolved action, `package_root`, and parameters

2
plugins/kyberforge/docs/research/docs/microsoft-apm/installation.md
View File

@@ -17,7 +17,7 @@ On Windows, the installer adds both the current directory and the bin directory
## Customizing the install ## 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`. - **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`. - **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 ## Alternative install methods

2
plugins/kyberforge/plugin.json
View File

@@ -13,5 +13,5 @@
"skills": [ "skills": [
"skills/" "skills/"
], ],
"version": "1.3.0" "version": "1.3.1"
} }

2
plugins/kyberforge/skills/apm-install/SKILL.md
View File

@@ -31,7 +31,7 @@ curl -sSL https://aka.ms/apm-unix | sh
Escape hatches — combine as needed: 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`. - 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`. - 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`. - 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`. - Manual: download the platform archive from the GitHub releases page, extract, place the binary on `PATH`.

4
plugins/kyberforge/skills/apm-workflow/README.md
View File

@@ -4,7 +4,7 @@ Authors, scaffolds, compiles, and audits apm packages and marketplaces.
## What it does ## 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 ## 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 configure
/apm-workflow install
/apm-workflow marketplace /apm-workflow marketplace
/apm-workflow compile /apm-workflow compile
/apm-workflow audit /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 | | `SKILL.md` | Dispatch table and cross-cutting gotchas |
| `references/configure.md` | apm.yml schema, apm plugin init, dependency forms, MCP secrets, registries | | `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/marketplace.md` | Building/registering a marketplace, package registration, versioning |
| `references/compile.md` | apm compile / pack / publish / run | | `references/compile.md` | apm compile / pack / publish / run |
| `references/audit.md` | apm audit, apm audit --ci, apm marketplace check, CI wiring, frozen installs | | `references/audit.md` | apm audit, apm audit --ci, apm marketplace check, CI wiring, frozen installs |

1
plugins/kyberforge/skills/apm-workflow/SKILL.md
View File

@@ -32,6 +32,7 @@ metadata:
| Invocation | Action | Reference | | Invocation | Action | Reference |
|---|---|---| |---|---|---|
| `/apm-workflow configure` | Author/edit `apm.yml`; scaffold a new package (`apm plugin init`) | `references/configure.md` | | `/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 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 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` | | `/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` |

2
plugins/kyberforge/skills/apm-workflow/references/configure.md
View File

@@ -35,7 +35,7 @@ keywords: [ai, review, python]
type: skill # instructions | skill | hybrid | prompts — constrains .apm/ contents 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 - copilot
- claude - claude

20
plugins/kyberforge/skills/apm-workflow/references/install.md Normal file
View File

@@ -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.

2
plugins/kyberforge/skills/apm-workflow/references/sources.md
View File

@@ -5,5 +5,5 @@
- **URL:** 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. - **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 - **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` - **Status:** `extracted`