diff --git a/CONTEXT.md b/CONTEXT.md index b77c576..eb05cdb 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. diff --git a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md index 446c3bf..012858e 100644 --- a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md +++ b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md @@ -1,5 +1,8 @@ # 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 @@ -28,9 +31,10 @@ new hand-maintained manifest format. 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 directly supersedes ADR-0001** ("Skills are distributed via plugins... each plugin - contains its own `skills/` directory"). Once the real conversion executes, skills and agents - physically move to `plugins//.apm/skills/` and `plugins//.apm/agents/*.agent.md`. +- **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). @@ -53,18 +57,22 @@ 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. Rejected anyway, in favor of `kyberforge`, because this tooling's scope is specifically -converting *this* repo's marketplace, not standing up a reusable generic apm toolkit for other -repos. 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. +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. ## Consequences - ADR-0001 is superseded once issue #90 executes. - ADR-0006 (plugin-version-parity) will need a third file, `apm.yml`, folded into its parity check once #90 lands — not resolved by this ADR. -- ADR-0010 (agent sources relocated outside agents dir) needs revisiting once agents move under - `.apm/agents/` with the `.agent.md` extension — 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. diff --git a/plugins/kyberforge/agents/apm-orchestrate.agent.md b/plugins/kyberforge/agents/apm-orchestrate.agent.md index 75148cf..5ea8be9 100644 --- a/plugins/kyberforge/agents/apm-orchestrate.agent.md +++ b/plugins/kyberforge/agents/apm-orchestrate.agent.md @@ -20,7 +20,6 @@ You resolve the package root once per dispatched operation (the directory contai 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. -- MCP server secrets in any `apm.yml` content this orchestrator writes or edits must use `${VAR}` indirection — never a literal value. - `apm marketplace add` (registering a marketplace as a consumer) and `apm marketplace package add` (registering a local package into a marketplace being built) are opposite directions — resolve which one the caller means from the operation name, never guess from context alone. - `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`. @@ -38,8 +37,8 @@ When invoked, you: ## Inputs - **operation:** string, one of: - - configure: init-package, compile-manifest-check (does `apm.yml` parse and match `type:`) - - marketplace: init-marketplace, check-marketplace, add-package, add-marketplace + - 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) - 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) diff --git a/plugins/kyberforge/agents/apm-orchestrate.md b/plugins/kyberforge/agents/apm-orchestrate.md index 4253c8a..56dd67e 100644 --- a/plugins/kyberforge/agents/apm-orchestrate.md +++ b/plugins/kyberforge/agents/apm-orchestrate.md @@ -20,7 +20,6 @@ You resolve the package root once per dispatched operation (the directory contai 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. -- MCP server secrets in any `apm.yml` content this orchestrator writes or edits must use `${VAR}` indirection — never a literal value. - `apm marketplace add` (registering a marketplace as a consumer) and `apm marketplace package add` (registering a local package into a marketplace being built) are opposite directions — resolve which one the caller means from the operation name, never guess from context alone. - `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`. @@ -38,8 +37,8 @@ When invoked, you: ## Inputs - **operation:** string, one of: - - configure: init-package, compile-manifest-check (does `apm.yml` parse and match `type:`) - - marketplace: init-marketplace, check-marketplace, add-package, add-marketplace + - 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) - 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) diff --git a/plugins/kyberforge/skills/apm-workflow/references/compile.md b/plugins/kyberforge/skills/apm-workflow/references/compile.md index 84e3708..6ea2972 100644 --- a/plugins/kyberforge/skills/apm-workflow/references/compile.md +++ b/plugins/kyberforge/skills/apm-workflow/references/compile.md @@ -24,6 +24,8 @@ apm pack --marketplace=claude --json # JSON output for CI pipelines Bundles a producer package into a distributable artifact. Default to `--dry-run -v` first when packing something for the first time or after a dependency change — resolution errors surface before anything is written. +Run `apm audit` after compile/pack, not before — audit scans deployed/compiled output, not the source `apm.yml` manifest; see `references/audit.md`. + ## Publish ```bash diff --git a/plugins/kyberforge/skills/apm-workflow/references/marketplace.md b/plugins/kyberforge/skills/apm-workflow/references/marketplace.md index 55311ea..239d1d7 100644 --- a/plugins/kyberforge/skills/apm-workflow/references/marketplace.md +++ b/plugins/kyberforge/skills/apm-workflow/references/marketplace.md @@ -11,10 +11,11 @@ apm marketplace init # 1. add the marketplace: block to $EDITOR apm.yml # 2. describe each package apm marketplace check # 3. validate refs resolve apm pack # 4. build marketplace artifacts -git add apm.yml .claude-plugin/marketplace.json -git commit -m "Release v1.0.0" && git tag v1.0.0 && git push --tags ``` +5. Commit and release — via the `git-commits` skill (commit message + tag) and `git-remotes` skill + (push), not raw `git` commands; see this repo's AGENTS.md "Prefer plugin skills over raw shell". + `apm pack` emits `.claude-plugin/marketplace.json` as one of its compile targets — an APM-based marketplace stays consumable by Claude Code's existing marketplace mechanism without a separately hand-maintained file. ## Registering a package into a marketplace you're building