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
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
Defame1297 marked this conversation as resolved Outdated
Claude commented 2026-08-11 05:36:35 +00:00
Outdated
Review
Copy Link

ADR-0015 states "CONTEXT.md's Plugin/Skill/Plugin-marketplace glossary entries remain accurate as written until issue #90 actually executes — this ADR does not update them," but this same PR's fix commit (e16c3dc) edited CONTEXT.md's Plugin and Plugin marketplace entries to add an ADR-0015 forward-pointer sentence.

Failure scenario: A reader trusts the ADR's own claim about its change boundary and skips re-checking CONTEXT.md, or a future auditor treats the ADR as the authoritative record of what this PR touched and gets it wrong — the document contradicts the diff it ships alongside.

ADR-0015 states "CONTEXT.md's Plugin/Skill/Plugin-marketplace glossary entries remain accurate as written until issue #90 actually executes — this ADR does not update them," but this same PR's fix commit (e16c3dc) edited CONTEXT.md's Plugin and Plugin marketplace entries to add an ADR-0015 forward-pointer sentence. **Failure scenario:** A reader trusts the ADR's own claim about its change boundary and skips re-checking CONTEXT.md, or a future auditor treats the ADR as the authoritative record of what this PR touched and gets it wrong — the document contradicts the diff it ships alongside.
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

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

@@ -8,5 +8,5 @@
"keywords": [],
"license": "MIT",
"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.
**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/<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:
- 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

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.
**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/<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:
- 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)
Defame1297 marked this conversation as resolved Outdated
Claude commented 2026-08-10 18:33:10 +00:00
Outdated
Review
Copy Link

The compile-manifest-check operation has no corresponding apm CLI command anywhere in apm-workflow's references or the shipped microsoft-apm research docs (verified by grep across both). An executing agent dispatched this operation has to invent behavior since nothing documents what to actually run.

The `compile-manifest-check` operation has no corresponding apm CLI command anywhere in apm-workflow's references or the shipped microsoft-apm research docs (verified by grep across both). An executing agent dispatched this operation has to invent behavior since nothing documents what to actually run.
- install: install (→ `apm install [PACKAGE_REF]` — resolve/fetch dependencies declared in `apm.yml` against `apm.lock.yaml`; no arguments re-resolves everything)
Defame1297 marked this conversation as resolved Outdated
Claude commented 2026-08-10 18:33:10 +00:00
Outdated
Review
Copy Link

add-package and add-marketplace are never mapped to their underlying apm marketplace package add / apm marketplace add commands anywhere in this file, despite this same file's Hard Rule insisting these two directions must 'never guess from context alone.' An executing agent has no explicit mapping table and could plausibly invert them — exactly the mix-up the adjacent rule was written to prevent.

`add-package` and `add-marketplace` are never mapped to their underlying `apm marketplace package add` / `apm marketplace add` commands anywhere in this file, despite this same file's Hard Rule insisting these two directions must 'never guess from context alone.' An executing agent has no explicit mapping table and could plausibly invert them — exactly the mix-up the adjacent rule was written to prevent.
- 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
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
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

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
- **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

2
plugins/kyberforge/plugin.json
View File

@@ -13,5 +13,5 @@
"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:
- 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`.
Defame1297 marked this conversation as resolved Outdated
Claude commented 2026-08-11 05:36:35 +00:00
Outdated
Review
Copy Link

The "custom install directory" example APM_INSTALL_DIR=$HOME/.local/bin sh omits the curl -sSL https://aka.ms/apm-unix | ... pipe entirely, so copying it literally just runs a bare sh with no install script.

Failure scenario: A user or agent follows the escape hatch verbatim, runs APM_INSTALL_DIR=$HOME/.local/bin sh, gets an empty/hanging shell (or an immediate no-op non-interactively) instead of an apm install, with no error to indicate anything went wrong.

Identical issue at plugins/kyberforge/docs/research/docs/microsoft-apm/installation.md:20.

The "custom install directory" example `APM_INSTALL_DIR=$HOME/.local/bin sh` omits the `curl -sSL https://aka.ms/apm-unix | ...` pipe entirely, so copying it literally just runs a bare `sh` with no install script. **Failure scenario:** A user or agent follows the escape hatch verbatim, runs `APM_INSTALL_DIR=$HOME/.local/bin sh`, gets an empty/hanging shell (or an immediate no-op non-interactively) instead of an apm install, with no error to indicate anything went wrong. Identical issue at `plugins/kyberforge/docs/research/docs/microsoft-apm/installation.md:20`.
- 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`.

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

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

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

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
Defame1297 marked this conversation as resolved Outdated
Claude commented 2026-08-11 05:36:35 +00:00
Outdated
Review
Copy Link

This apm.yml schema block omits the "legacy singular target: CSV form is still accepted" caveat that the sibling research doc (docs/research/docs/microsoft-apm/configuration.md:32) documents for the same targets: field.

Failure scenario: An agent following only this file — the one its own SKILL.md dispatch table points to — encounters an existing apm.yml using target: copilot,claude and flags or "corrects" it as invalid, when apm actually still accepts that legacy form.

This apm.yml schema block omits the "legacy singular `target:` CSV form is still accepted" caveat that the sibling research doc (`docs/research/docs/microsoft-apm/configuration.md:32`) documents for the same `targets:` field. **Failure scenario:** An agent following only this file — the one its own SKILL.md dispatch table points to — encounters an existing apm.yml using `target: copilot,claude` and flags or "corrects" it as invalid, when apm actually still accepts that legacy form.
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

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
- **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`