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 +28 -19
6 changed files with 28 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit e16c3dc95f - Show all commits

4
CONTEXT.md
View File

@@ -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/<plugin-name>/skills/<skill-name>/SKILL.md`, available after the plugin is installed (`claude plugin install <name>@<marketplace>`). 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/<name>/`. Install a plugin with `claude plugin install <name>@<marketplace>`.
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/<name>/`. Install a plugin with `claude plugin install <name>@<marketplace>`. 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.

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

@@ -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`,
Defame1297 marked this conversation as resolved
Claude commented 2026-08-10 18:33:10 +00:00
Review
Copy Link

This Decision bullet states 'This directly supersedes ADR-0001' as a present-tense fact, but the Consequences section (line 63) says 'ADR-0001 is superseded once issue #90 executes' — a future, conditional event. The same document licenses opposite conclusions depending which section a reader lands on. Pick one framing (recommend: conditional, matching Consequences) and make the Decision bullet match it.

This Decision bullet states 'This directly supersedes ADR-0001' as a present-tense fact, but the Consequences section (line 63) says 'ADR-0001 is superseded once issue #90 executes' — a future, conditional event. The same document licenses opposite conclusions depending which section a reader lands on. Pick one framing (recommend: conditional, matching Consequences) and make the Decision bullet match it.
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/<name>/.apm/skills/` and `plugins/<name>/.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/<name>/.apm/skills/` and `plugins/<name>/.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`
Defame1297 marked this conversation as resolved Outdated
Claude commented 2026-08-10 18:33:10 +00:00
Outdated
Review
Copy Link

The rationale for rejecting a standalone plugins/apm/ plugin claims this tooling's scope is 'specifically converting this repo's marketplace, not standing up a reusable generic apm toolkit' — but the shipped apm-install/apm-workflow SKILL.md files are fully generic, repo-agnostic APM CLI documentation with essentially no holocron-specific content. The stated justification doesn't match what was actually built, which will make the placement decision look post-hoc to a future reviewer.

The rationale for rejecting a standalone `plugins/apm/` plugin claims this tooling's scope is 'specifically converting *this* repo's marketplace, not standing up a reusable generic apm toolkit' — but the shipped apm-install/apm-workflow SKILL.md files are fully generic, repo-agnostic APM CLI documentation with essentially no holocron-specific content. The stated justification doesn't match what was actually built, which will make the placement decision look post-hoc to a future reviewer.
Defame1297 commented 2026-08-10 18:46:02 +00:00
Outdated
Review
Copy Link

agree that the created files are agnostic, but they still fit the kyberforge purpose.

agree that the created files are agnostic, but they still fit the kyberforge purpose.
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.
Defame1297 marked this conversation as resolved Outdated
Claude commented 2026-08-10 18:33:10 +00:00
Outdated
Review
Copy Link

Attributes the .agent.md extension to the future APM conversion ('needs revisiting once agents move under .apm/agents/ with the .agent.md extension'), but .agent.md is this repo's pre-existing Copilot-pairing convention (ADR-0005/ADR-0010), already in use by this very diff's own apm-orchestrate.agent.md. Whoever executes #90 could read this as license to redesign an already-settled, orthogonal naming convention that has nothing to do with the APM move.

Attributes the `.agent.md` extension to the future APM conversion ('needs revisiting once agents move under .apm/agents/ with the .agent.md extension'), but `.agent.md` is this repo's pre-existing Copilot-pairing convention (ADR-0005/ADR-0010), already in use by this very diff's own apm-orchestrate.agent.md. Whoever executes #90 could read this as license to redesign an already-settled, orthogonal naming convention that has nothing to do with the APM move.
## 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/<name>/.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/<name>/skills/...`/`plugins/<name>/agents/...`; these will need updating once paths
move under `.apm/` — not resolved by this ADR.

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

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

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

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

This Hard Rule governs 'any apm.yml content this orchestrator writes or edits', but the agent declares only tools: Bash, Read (line 6) and its own Scope (line 13) states it 'does not decide manifest content yourself, you delegate' — it has no Edit/Write tool and never touches apm.yml directly. The rule it exists to enforce has no code path that ever fires; it reads as an active safety gate but is dead text. Either grant the capability this rule assumes, or move the rule to wherever manifest content actually gets written.

This Hard Rule governs 'any apm.yml content this orchestrator writes or edits', but the agent declares only `tools: Bash, Read` (line 6) and its own Scope (line 13) states it 'does not decide manifest content yourself, you delegate' — it has no Edit/Write tool and never touches apm.yml directly. The rule it exists to enforce has no code path that ever fires; it reads as an active safety gate but is dead text. Either grant the capability this rule assumes, or move the rule to wherever manifest content actually gets written.
- `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)
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.
- compile: compile, pack, publish, run-script
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.
- 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)

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

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

5
plugins/kyberforge/skills/apm-workflow/references/marketplace.md
View File

@@ -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
```
Defame1297 marked this conversation as resolved
Claude commented 2026-08-10 18:33:10 +00:00
Review
Copy Link

Documents a raw git add/git commit/git tag/git push --tags chain as the literal release step. AGENTS.md's 'Prefer plugin skills over raw shell' section states commits/remotes are owned by git:git-commits/git:git-remotes and to fall back to raw shell 'only when no skill covers it' — an agent following this reference verbatim shells out directly in a repo that already has dedicated skills for exactly this operation.

Documents a raw `git add`/`git commit`/`git tag`/`git push --tags` chain as the literal release step. AGENTS.md's 'Prefer plugin skills over raw shell' section states commits/remotes are owned by `git:git-commits`/`git:git-remotes` and to fall back to raw shell 'only when no skill covers it' — an agent following this reference verbatim shells out directly in a repo that already has dedicated skills for exactly this operation.
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