docs(kyberforge): fix remaining PR #91 review findings, add apm install routing
Re-review (comment 24) of fix commit e16c3dc found six new issues, mostly
introduced by that fix commit itself: a dangling reference to a Hard Rule
bullet the same commit deleted (apm-orchestrate.md/.agent.md Process step
2 still named "secret indirection"), and an ADR-0015 Decision bullet that
claimed "this ADR does not update CONTEXT.md" while the same commit had
just added a forward-pointer sentence to CONTEXT.md's Plugin/Plugin
marketplace entries. Both reworded to match what actually happened.
apm-install's APM_INSTALL_DIR escape-hatch example dropped the curl pipe
entirely (`APM_INSTALL_DIR=... sh` with nothing piped into it) — fixed in
both apm-install/SKILL.md and the installation.md research doc, verified
against the upstream Microsoft APM docs via Context7.
Neither apm-workflow nor apm-orchestrate routed to plain `apm install
[PACKAGE_REF]`, the CLI command that actually resolves/fetches
dependencies declared in apm.yml — apm-install only bootstraps the apm
binary/runtime, not per-package deps. Added a 5th "install" dispatch
action to apm-workflow (new references/install.md, SKILL.md table row,
README usage/files sync, sources.md provenance entry) and a matching
"install" operation group on apm-orchestrate so it can route there.
configure.md's apm.yml schema block was also missing the "legacy singular
`target:` CSV form is still accepted" caveat its sibling research doc
documents for the same field — added for consistency.
The sixth finding (paired .md/.agent.md Output-contract disagreement) was
checked against git-orchestrate and gitea-orchestrate's existing pairs and
found to match established repo convention (JSON schema in .md, prose
summary without the enum in .agent.md) — left unchanged as a false
positive rather than "fixed."
kyberforge bumped 1.3.0 -> 1.3.1 via agent-author's normal improve flow.
Refs: #91
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0186ERbyACLRuRxPRnqwpa4m
This commit is contained in:
@@ -8,5 +8,5 @@
|
||||
"keywords": [],
|
||||
"license": "MIT",
|
||||
"name": "kyberforge",
|
||||
"version": "1.3.0"
|
||||
"version": "1.3.1"
|
||||
}
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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` via `Skill` with the resolved action, `package_root`, and parameters
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -13,5 +13,5 @@
|
||||
"skills": [
|
||||
"skills/"
|
||||
],
|
||||
"version": "1.3.0"
|
||||
"version": "1.3.1"
|
||||
}
|
||||
|
||||
@@ -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`.
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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` |
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
20
plugins/kyberforge/skills/apm-workflow/references/install.md
Normal file
20
plugins/kyberforge/skills/apm-workflow/references/install.md
Normal 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.
|
||||
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user