diff --git a/.claude/settings.json b/.claude/settings.json index 8136bbd..9b97c07 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -4,7 +4,8 @@ "core@holocron": true, "git@holocron": true, "gitea@holocron": true, - "kyberforge@holocron": true + "kyberforge@holocron": true, + "lint@holocron": true }, "hooks": { "PreToolUse": [] diff --git a/CONTEXT.md b/CONTEXT.md index b77c576..ea48c76 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -27,10 +27,10 @@ A separate product (separate repo) for browsing, editing, and configuring AI dev Reusable slash commands for AI coding tools, defined as `SKILL.md` files following the [Agent Skills open standard](https://agentskills.io). Deployed via plugin — `plugins//skills//SKILL.md`, available after the plugin is installed (`claude plugin install @`). Skills are self-contained — they cannot reference files outside the plugin directory after install-time caching. ### Plugin -The deployable unit in the plugin marketplace. A plugin bundles one or more skills, agents, hooks, prompts, MCP servers, and optionally a `bin/` directory into a single installable directory. Each plugin has two manifests: `.claude-plugin/plugin.json` (Claude Code) and `plugin.json` at the plugin root (Copilot CLI). Plugins are copied to a cache on install — they cannot reference files outside their own directory. In this repo, plugins live under `plugins//`. Install a plugin with `claude plugin install @`. +The deployable unit in the plugin marketplace. A plugin bundles one or more skills, agents, hooks, prompts, MCP servers, and optionally a `bin/` directory into a single installable directory. Each plugin has two manifests: `.claude-plugin/plugin.json` (Claude Code) and `plugin.json` at the plugin root (Copilot CLI). Plugins are copied to a cache on install — they cannot reference files outside their own directory. In this repo, plugins live under `plugins//`. Install a plugin with `claude plugin install @`. These manifests are hand-authored today but are slated to become APM-compiled output per ADR-0015, pending issue #90 (not yet changed). ### Plugin marketplace -A Git repository with a `marketplace.json` manifest listing installable plugins. No backend, registry, or SaaS required — the Git repo is the marketplace. This repo is the `holocron` marketplace. The manifest lives at `.claude-plugin/marketplace.json` (read by both Claude Code and Copilot CLI) and is mirrored to `.github/plugin/marketplace.json`. +A Git repository with a `marketplace.json` manifest listing installable plugins. No backend, registry, or SaaS required — the Git repo is the marketplace. This repo is the `holocron` marketplace. The manifest lives at `.claude-plugin/marketplace.json` (read by both Claude Code and Copilot CLI) and is mirrored to `.github/plugin/marketplace.json`. This manifest is hand-authored today but is slated to become APM-compiled output per ADR-0015, pending issue #90 (not yet changed). ### HITL (human-in-the-loop) Agent pauses before a consequential action; human approves before execution. Required for irreversible or high-stakes actions (architecture changes, production deployments, security configuration). The agent drafts the change plan and waits — it does not proceed autonomously. Contrast with HOTL. @@ -49,7 +49,7 @@ The provider-agnostic always-on instruction entry point. Two files: Contains always-on rules in plain markdown with no provider-specific syntax (no `@import`). Provider-specific files (`CLAUDE.md`) are thin adapters that import the relevant `AGENTS.md` and add only Claude Code-specific syntax. This pattern means a single source of truth can serve multiple providers without duplication. See ADR-0003. ### Skill composition -A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology; `forge` calls `grill-with-docs` to refine intent, classifies the target artifact type (skill / agent / plugin / marketplace entry), then routes to the matching `*-author` skill — which owns its own create/improve logic and, where applicable, its own inline audit closeout (`skill-author` runs `/skill-audit`, `agent-author` runs `kyberforge:agent-audit`, both in the same context as the authoring work). Reserve `forge` for genuinely undecided "which artifact type is this" questions — an already-fully-specified corrective edit (exact file, line, and fix already known) should call the target author skill directly instead (`skill-author`, `plugin-author`, `agentsmd-author`, etc.); routing a known fix through `forge`'s grill-and-classify layer adds unnecessary indirection and, in practice, has been observed to lose track of hard constraints handed down the chain (e.g. "don't commit yet," "edit in this worktree") because each hop re-derives instructions from a shorter brief. `forge` additionally runs its own independent recheck after a skill/agent route finishes: a clean-context subagent (not forked, no inherited context) re-runs the same audit skill against the finished artifact, as a distinct verification layer from the author skill's inline audit — the two can share blind spots since the inline audit runs in the same context as the work it checks. If the clean audit surfaces any unresolved finding, `forge` loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved; only then is the route done. `plugin-author` and `marketplace-author` have no audit counterpart and get no recheck; their terminal check is `claude plugin validate`. +A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology; `forge` calls `grill-with-docs` to refine intent, classifies the target artifact type (skill / agent / plugin / marketplace entry), then routes to the matching `*-author` skill — which owns its own create/improve logic and, where applicable, its own inline audit closeout (`skill-author` runs `/skill-audit`, `agent-author` runs `kyberforge:agent-audit`, both in the same context as the authoring work). Reserve `forge` for genuinely undecided "which artifact type is this" questions — an already-fully-specified corrective edit (exact file, line, and fix already known) should call the target author skill directly instead (`skill-author`, `plugin-author`, `agentsmd-author`, etc.); routing a known fix through `forge`'s grill-and-classify layer adds unnecessary indirection and, in practice, has been observed to lose track of hard constraints handed down the chain (e.g. "don't commit yet," "edit in this worktree") because each hop re-derives instructions from a shorter brief. `forge` additionally runs its own independent recheck after a skill/agent route finishes: a clean-context subagent (not forked, no inherited context) re-runs the same audit skill against the finished artifact, as a distinct verification layer from the author skill's inline audit — the two can share blind spots since the inline audit runs in the same context as the work it checks. If the clean audit surfaces any unresolved finding, `forge` loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved; only then is the route done. `plugin-author` and `marketplace-author` have no audit counterpart and get no recheck; their terminal check is `claude plugin validate`. Both are deprecated per ADR-0015, superseded by `apm-workflow`, pending issue #90 (not yet changed). ### Provider-agnostic issue tracker Skills and workflows reference "linked issue" generically rather than a specific provider. Gitea is the canonical issue tracker for this repo (see ADR-0017). "Issue" is the cross-provider term (GitHub, GitLab, Gitea all use it). diff --git a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md new file mode 100644 index 0000000..e64e07d --- /dev/null +++ b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md @@ -0,0 +1,115 @@ +# Microsoft APM replaces the hand-authored plugin/marketplace model as this repo's authoring source of truth + +**Will supersede:** ADR-0001 ("Skills are distributed via plugins... each plugin contains its +own `skills/` directory") — once issue #90's conversion actually executes; not yet in effect. + +This repo replaces its hand-maintained Claude Code plugin/marketplace authoring model +(`.claude-plugin/marketplace.json` + per-plugin `plugin.json`) with Microsoft APM (`apm.yml` + +`.apm/`) as the authoring source of truth — an outright replacement of the authoring layer, not an +additive overlay. This ADR records the decision from a `grill-with-docs` session on issue #88. + +## Context + +Every plugin under `plugins//` currently ships two hand-maintained manifests +(`.claude-plugin/plugin.json` for Claude Code, root `plugin.json` for Copilot CLI) plus a +hand-maintained root `.claude-plugin/marketplace.json` listing all plugins. Adding a provider means +hand-authoring a third manifest shape; keeping the two existing ones in parity is itself a tracked +concern (ADR-0006). + +Research on Microsoft APM (`plugins/kyberforge/docs/research/docs/microsoft-apm/`) found that its +documented "monorepo-hybrid" repo shape maps directly onto this repo's existing `plugins//` +layout: each plugin becomes its own `apm.yml` + `.apm/{skills,agents,hooks,prompts,instructions}/` +package, listed from a root `apm.yml`'s `marketplace:` block. `apm compile`/`apm pack` generate +per-target output — including a `.claude-plugin/marketplace.json` — from that vendor-neutral +`.apm/` tree, so provider manifests become compiled artifacts instead of hand-authored files, and +new providers (Copilot, Gemini, Codex — all supported by `apm runtime setup`) no longer require a +new hand-maintained manifest format. + +## Decision + +- **The `plugins//` monorepo-hybrid directory layout survives.** `.claude-plugin/marketplace.json` + and per-provider `plugin.json` files become **compiled output** via `apm compile`/`apm pack`, + generated from `apm.yml` + `.apm/` per plugin, extensible to other `apm runtime`-supported + providers without hand-maintaining a separate manifest per provider. +- **This will supersede ADR-0001** ("Skills are distributed via plugins... each plugin + contains its own `skills/` directory"), but not yet — supersession is pending on issue #90's + conversion. Once that real conversion executes, skills and agents physically move to + `plugins//.apm/skills/` and `plugins//.apm/agents/*.agent.md`. +- New operational tooling — `apm-install` (skill), `apm-workflow` (skill), `apm-orchestrate` + (agent) — lands in `kyberforge`, tracked in issue #88 + (https://git.dev.rkdr.net/Defame1297/holocron/issues/88). +- Adapting `skill-author`/`agent-author`'s routing to author `.apm/`-native content (retargeting to + `.apm/skills/`, `.apm/agents/` paths — the content these two skills author is still meaningful + post-conversion) is deferred to issue #89 + (https://git.dev.rkdr.net/Defame1297/holocron/issues/89). `forge` is out of scope for #89 — it + stays untouched by this whole conversion effort and keeps routing to whatever the live author + skills are at the time. +- **`plugin-author`/`marketplace-author` are not adapted — they are superseded and deleted.** + Unlike `skill-author`/`agent-author`, nothing in these two skills carries forward as authoring + routing: `apm compile`/`apm pack` will generate `.claude-plugin/marketplace.json` and + per-provider `plugin.json` directly from `apm.yml` + `.apm/`, so `apm-install`/`apm-workflow`/ + `apm-orchestrate` (issue #88, already landed on this branch) fully replace what these two skills + did. Deleting `plugin-author`/`marketplace-author` is part of issue #90's execution, not #89's. +- 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"/"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 + +**Additive/compile-layer only, no `apm.yml` (rejected).** Keep `plugin.json`/`marketplace.json` +hand-authored and bolt APM on top as an optional extra. Rejected: doesn't achieve the multi-provider +compile-reuse goal APM's package model provides, and leaves the existing dual-manifest hand +maintenance in place unchanged. + +**New standalone `plugins/apm/` plugin (rejected).** `plugins/lint/` was split out of `kyberforge` +specifically because Vale tooling is generic and repo-agnostic, not holocron-marketplace-specific +(see `CONTEXT.md`'s "lint plugin" entry) — the same argument applies to a generic `apm` CLI +wrapper. The shipped `apm-install`/`apm-workflow` skills are, in fact, generic, repo-agnostic APM +CLI documentation with no holocron-specific content, so a standalone `plugins/apm/` would have +been a defensible split on artifact content alone. Rejected anyway, in favor of `kyberforge`, +because holocron is currently the only repo that needs this tooling — standing up a separate +plugin for a single consumer isn't worth it yet. Accepted as an explicit tradeoff (same pattern +as ADR-0011's `gitea-workflow` naming tradeoff) — worth revisiting if this tooling is ever reused +outside holocron's own conversion. + +## Content migration out of `plugin-author`/`marketplace-author` + +A content audit of `plugin-author`/`marketplace-author` (same `grill-with-docs` session as this +correction) sorted what they document into three buckets: + +- **Claude Code platform constraints — carried forward.** Facts that stay true regardless of + authoring model (reserved plugin-name prefixes; the `agents/`-directory stray-`.md`-file + validator gotcha, ADR-0010; `claude plugin validate` as a required terminal check) have been + added into `apm-workflow`'s reference docs, since compiled output still has to satisfy these + constraints post-conversion. +- **Dual-manifest artifacts — obsolete, not carried forward.** Conventions that existed only + because of hand-authored dual manifests (ADR-0006's version-parity/patch-bump rule, the + CC-vs-Copilot field-placement split, dual-file mirroring) are obsolete under `apm.yml`'s + single-manifest model and were deliberately dropped. +- **Holocron policy choice — flagged for #90, not resolved here.** `marketplace-author`'s + catalog-version convention (minor bump for package add/remove, patch bump for field-only + updates) isn't an APM mechanic — `apm` doesn't enforce it — but it's still a meaningful holocron + policy worth re-applying to `apm.yml`'s `marketplace.packages[].version` field once #90 wires up + real marketplace authoring. Where/how that gets implemented is #90's decision, not this ADR's. + +## Consequences + +- ADR-0001 is superseded once issue #90 executes. +- ADR-0006 (plugin-version-parity) becomes moot once #90 lands: `plugin.json`/`marketplace.json` + become compiled output of a single `apm.yml`, so there's no second hand-authored file left to + keep in parity, and `plugin-author` — the skill that enforced ADR-0006 — is deleted rather than + adapted (see "Content migration" above). Not resolved by this ADR. +- ADR-0010 (agent sources relocated outside agents dir) needs revisiting once agents move to + `plugins//.apm/agents/` — the directory path changes, not the pre-existing `.agent.md` + extension convention (ADR-0005/ADR-0010, unaffected) — not resolved by this ADR. +- ADR-0014 (Vale prefilter ships from the plugin) has hardcoded path regexes assuming + `plugins//skills/...`/`plugins//agents/...`; these will need updating once paths + move under `.apm/` — not resolved by this ADR. +- `kyberforge` gains three new artifacts (issue #88) before any conversion of existing content + happens. +- Two follow-up issues track the remaining work: #89 (`skill-author`/`agent-author` routing + adaptation) and #90 (the actual repo conversion, which also deletes `plugin-author`/ + `marketplace-author`). diff --git a/plugins/git/agents/git-orchestrate.md b/plugins/git/agents/git-orchestrate.md index 9539666..5a0c777 100644 --- a/plugins/git/agents/git-orchestrate.md +++ b/plugins/git/agents/git-orchestrate.md @@ -3,7 +3,7 @@ name: git-orchestrate description: Orchestrates git workflow operations for other agents. Invoke when a caller needs a multi-step or destructive git operation (rebase, force-push, branch deletion) coordinated across domain skills with safety gates, session context, and structured results. -tools: Bash, Read, Edit +tools: Bash, Read, Edit, Skill source_keys: - context7-git-htmldocs diff --git a/plugins/gitea/agents/gitea-orchestrate.md b/plugins/gitea/agents/gitea-orchestrate.md index bebf398..e2d26cd 100644 --- a/plugins/gitea/agents/gitea-orchestrate.md +++ b/plugins/gitea/agents/gitea-orchestrate.md @@ -3,7 +3,7 @@ name: gitea-orchestrate description: Orchestrates Gitea operations for other agents. Invoke when a caller needs a multi-step or destructive Gitea operation (merge a PR, delete a branch/release/tag/label/milestone, delete a file) coordinated across domain skills with safety gates, session context, and structured results. -tools: Bash, Read +tools: Bash, Read, Skill source_keys: - gitea-mcp-repo diff --git a/plugins/kyberforge/.claude-plugin/plugin.json b/plugins/kyberforge/.claude-plugin/plugin.json index 98049c5..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.2.8" + "version": "1.3.1" } diff --git a/plugins/kyberforge/README.md b/plugins/kyberforge/README.md index 3c21dc1..c4b7b3e 100644 --- a/plugins/kyberforge/README.md +++ b/plugins/kyberforge/README.md @@ -46,8 +46,10 @@ copilot plugin install ./plugins/kyberforge | `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 | -| `plugin-author` | Create, update, and release plugin scaffolds for the holocron marketplace | -| `marketplace-author` | Add, remove, and update plugin entries in the holocron marketplace manifest | +| `plugin-author` | (Deprecated — see apm-workflow) Create, update, and release plugin scaffolds for the holocron marketplace | +| `marketplace-author` | (Deprecated — see apm-workflow) Add, remove, and update plugin entries in the holocron marketplace manifest | +| `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 | ## Author diff --git a/plugins/kyberforge/agents/apm-orchestrate.agent.md b/plugins/kyberforge/agents/apm-orchestrate.agent.md new file mode 100644 index 0000000..f500183 --- /dev/null +++ b/plugins/kyberforge/agents/apm-orchestrate.agent.md @@ -0,0 +1,63 @@ +--- +name: apm-orchestrate + +description: Orchestrates apm package/marketplace operations for other agents. Invoke when a caller needs a multi-step apm operation (scaffold a package, register it into a marketplace, compile/pack/publish, audit) coordinated across the apm-workflow skill with safety gates, session context, and structured results — especially fanning the same operation out across multiple packages in a monorepo. + +tools: ["execute", "read"] + +source_keys: + - context7-microsoft-apm + +--- + +You are the orchestrator for apm package/marketplace operations — a composable workflow dispatcher designed for other agents to invoke multi-step `apm` operations reliably, especially the same operation repeated across several packages in a monorepo-hybrid layout. Your one job is routing and safety-gating: you do not decide manifest content yourself, you delegate to `apm-workflow` and enforce confirmation on irreversible operations. + +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 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 + +These are non-negotiable regardless of `confirm` or any skill-local override: +- `apm publish` claims a version on a registry — treat it as irreversible. Refuse without explicit `confirm: true`; always dispatch with `--dry-run -v` first and surface that output to the caller before the real publish, even when `confirm: true` was given. +- Never guess the marketplace-add direction from context — resolve strictly from the operation name (`add-package` vs `add-marketplace`); see apm-workflow/SKILL.md Gotchas for why the two are easy to conflate. +- `apm.yml`'s `type:` field constrains what `.apm/` may contain — when scaffolding (`init-package`), set `type:` before any primitive content is added; do not defer it. +- A clean plain `apm audit` is not a CI-equivalent pass — if the caller's intent is a CI gate, dispatch `audit-ci`, not `audit`. +- Check the `apm experimental enable registries` precondition before dispatching any operation that depends on a named registry, and fail with a clear diagnostic rather than silently no-op'ing like apm itself does — see apm-workflow/SKILL.md Gotchas for the underlying constraint. + +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`, `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 independent packages in parallel when no shared state or ordering dependency exists between them; keep dispatch strictly sequential only for packages with a real dependency on another package's completion (e.g. a marketplace registration that needs a dependency package scaffolded first). Either way, continue past a single package's failure rather than aborting the whole batch — collect all failures and report them together at the end +7. Aggregate results and return structured JSON output suitable for agent chaining + +## Inputs + +- **operation:** string, one of: + - configure: init-package, edit-config (→ author/edit an existing package's `apm.yml` directly — adding a dependency, script, registries block, or removing a `marketplace.packages[]` entry; not a distinct `apm` CLI verb, just a manifest edit, optionally followed by `compile: pack` if it affects a published marketplace listing) + - 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) +- **parameters:** object, operation-specific arguments (package name for `add-package`, script name for `run-script`, registry name, etc.) +- **context:** object (optional), session state to carry forward (resolved registry config, marketplace root) +- **confirm:** boolean (optional), explicit confirmation required for `publish` + +## Process + +1. Validate the request structure and check if `operation` is known +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 +6. If fanning across multiple packages, dispatch independent packages in parallel when no shared state or ordering dependency exists between them; loop package-by-package (strictly sequential) only for packages with a real dependency on another package's completion. Either way, collect per-package results and failures rather than aborting on the first failure +7. Catch and handle apm errors: retry once for a dependency-not-yet-scaffolded failure after the caller confirms the dependency exists; otherwise return error structure with diagnostics +8. Aggregate all outputs and return as structured JSON + +## Output + +Returns structured JSON with operation status, result (output — or a list of per-package results when fanned out — plus resolved package-root/registry context), and optional error details with recovery suggestions. diff --git a/plugins/kyberforge/agents/apm-orchestrate.md b/plugins/kyberforge/agents/apm-orchestrate.md new file mode 100644 index 0000000..b9df652 --- /dev/null +++ b/plugins/kyberforge/agents/apm-orchestrate.md @@ -0,0 +1,78 @@ +--- +name: apm-orchestrate + +description: Orchestrates apm package/marketplace operations for other agents. Invoke when a caller needs a multi-step apm operation (scaffold a package, register it into a marketplace, compile/pack/publish, audit) coordinated across the apm-workflow skill with safety gates, session context, and structured results — especially fanning the same operation out across multiple packages in a monorepo. + +tools: Bash, Read, Skill + +source_keys: + - context7-microsoft-apm + +--- + +You are the orchestrator for apm package/marketplace operations — a composable workflow dispatcher designed for other agents to invoke multi-step `apm` operations reliably, especially the same operation repeated across several packages in a monorepo-hybrid layout. Your one job is routing and safety-gating: you do not decide manifest content yourself, you delegate to `apm-workflow` and enforce confirmation on irreversible operations. + +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 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 + +These are non-negotiable regardless of `confirm` or any skill-local override: +- `apm publish` claims a version on a registry — treat it as irreversible. Refuse without explicit `confirm: true`; always dispatch with `--dry-run -v` first and surface that output to the caller before the real publish, even when `confirm: true` was given. +- Never guess the marketplace-add direction from context — resolve strictly from the operation name (`add-package` vs `add-marketplace`); see apm-workflow/SKILL.md Gotchas for why the two are easy to conflate. +- `apm.yml`'s `type:` field constrains what `.apm/` may contain — when scaffolding (`init-package`), set `type:` before any primitive content is added; do not defer it. +- A clean plain `apm audit` is not a CI-equivalent pass — if the caller's intent is a CI gate, dispatch `audit-ci`, not `audit`. +- Check the `apm experimental enable registries` precondition before dispatching any operation that depends on a named registry, and fail with a clear diagnostic rather than silently no-op'ing like apm itself does — see apm-workflow/SKILL.md Gotchas for the underlying constraint. + +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`, `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 independent packages in parallel when no shared state or ordering dependency exists between them; keep dispatch strictly sequential only for packages with a real dependency on another package's completion (e.g. a marketplace registration that needs a dependency package scaffolded first). Either way, continue past a single package's failure rather than aborting the whole batch — collect all failures and report them together at the end +7. Aggregate results and return structured JSON output suitable for agent chaining + +## Inputs + +- **operation:** string, one of: + - configure: init-package, edit-config (→ author/edit an existing package's `apm.yml` directly — adding a dependency, script, registries block, or removing a `marketplace.packages[]` entry; not a distinct `apm` CLI verb, just a manifest edit, optionally followed by `compile: pack` if it affects a published marketplace listing) + - 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) +- **parameters:** object, operation-specific arguments (package name for `add-package`, script name for `run-script`, registry name, etc.) +- **context:** object (optional), session state to carry forward (resolved registry config, marketplace root) +- **confirm:** boolean (optional), explicit confirmation required for `publish` + +## Process + +1. Validate the request structure and check if `operation` is known +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 +6. If fanning across multiple packages, dispatch independent packages in parallel when no shared state or ordering dependency exists between them; loop package-by-package (strictly sequential) only for packages with a real dependency on another package's completion. Either way, collect per-package results and failures rather than aborting on the first failure +7. Catch and handle apm errors: retry once for a dependency-not-yet-scaffolded failure after the caller confirms the dependency exists; otherwise return error structure with diagnostics +8. Aggregate all outputs and return as structured JSON + +## Output + +```json +{ + "status": "success" | "error" | "partial", + "operation": "", + "result": { + "output": "", + "context": { "package_root": "...", "resolved_registry": "..." } + }, + "error": { + "message": "", + "code": "", + "recovery_attempted": true | false, + "suggestions": ["", ""] + } +} +``` diff --git a/plugins/kyberforge/docs/research/docs/microsoft-apm/cli-reference.md b/plugins/kyberforge/docs/research/docs/microsoft-apm/cli-reference.md new file mode 100644 index 0000000..0a24d22 --- /dev/null +++ b/plugins/kyberforge/docs/research/docs/microsoft-apm/cli-reference.md @@ -0,0 +1,99 @@ +--- +topic: cli-reference +source_keys: + - context7-microsoft-apm +--- + +## Install + +```bash +apm install [PACKAGE_REF...] [OPTIONS] +``` + +With no arguments, resolves and installs everything declared in `apm.yml` against `apm.lock.yaml`. Explicit `PACKAGE_REF` arguments (e.g. `acme/internal-tools#^1.0.0`) install and add that dependency. `apm install --update` re-resolves and accepts new upstream content even when it doesn't match the recorded lockfile hash (see troubleshooting). `apm install --target agent-skills` generates a vendor-neutral output directory for IDE-agnostic tool support instead of a harness-specific one. + +## Compile + +```bash +apm compile +``` + +Generates per-target output (Claude, Copilot, etc.) from the vendor-neutral `.apm/` primitive source tree, per the `compilation:` block in `apm.yml`. + +## Pack + +```bash +apm pack --dry-run # resolve and print; do not write +apm pack --offline # cached refs only +apm pack --include-prerelease # allow pre-release tags +apm pack -v # per-entry resolution detail +apm pack --marketplace=claude --json # JSON output for CI pipelines +``` + +Bundles a producer package into a distributable artifact. + +## Publish + +```bash +apm publish --package acme/my-skill --dry-run -v +apm publish --package acme/my-skill +``` + +Publishes a producer package (root containing `apm.yml`, `.apm/`, and optionally a `registries:` block) to a registry. Always dry-run with `-v` first to see resolution detail before publishing for real. + +## Runtime management + +```bash +apm runtime setup copilot # install with APM defaults +apm runtime setup codex --version 0.20.0 # pinned version +apm runtime setup llm --vanilla # skip APM-managed config +apm runtime list # what's installed +apm runtime status # which runtime `apm run` will pick +apm runtime remove gemini -y # uninstall without prompting +``` + +## Run + +```bash +apm run