fix(kyberforge): resolve PR #91 review findings in apm docs and orchestrators
Addresses 7 verified findings from the /code-review pass on PR #91's APM-conversion changes: - apm-workflow's description omitted install triggers, misrouting "install my apm dependencies" requests to apm-install instead - `apm marketplace check` was listed under both the marketplace and audit dispatch rows, breaking the "one reference file per action" contract; kept under marketplace.md, its real usage-sequence home - ADR-0015 claimed apm-workflow docs are generic/repo-agnostic while marketplace.md cited this repo's AGENTS.md and git-commits/ git-remotes skills by name; stripped the holocron-specific citations (marketplace.md, compile.md) so the claim now holds - plugin-author/marketplace-author are superseded per ADR-0015 with deletion deferred to #90; added deprecation notices pointing to the replacing apm-workflow dispatch actions - apm-orchestrate/gitea-orchestrate/git-orchestrate all instruct dispatch "via Skill" without granting the Skill tool; added it to all three - apm-orchestrate mandated strictly sequential fan-out across independent packages with no shared state; relaxed to permit parallel dispatch, matching this repo's own subagent-parallelization guidance Refs: #91
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -31,7 +31,7 @@ When invoked, you:
|
||||
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
|
||||
6. When fanning an operation across multiple packages (e.g. `init-package` for every `plugins/<name>/` 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
|
||||
@@ -54,7 +54,7 @@ When invoked, you:
|
||||
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, loop package-by-package, collecting per-package results and failures rather than aborting on the first failure
|
||||
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
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ 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
|
||||
tools: Bash, Read, Skill
|
||||
|
||||
source_keys:
|
||||
- context7-microsoft-apm
|
||||
@@ -31,7 +31,7 @@ When invoked, you:
|
||||
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
|
||||
6. When fanning an operation across multiple packages (e.g. `init-package` for every `plugins/<name>/` 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
|
||||
@@ -54,7 +54,7 @@ When invoked, you:
|
||||
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, loop package-by-package, collecting per-package results and failures rather than aborting on the first failure
|
||||
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
|
||||
|
||||
|
||||
@@ -4,13 +4,15 @@ description: >
|
||||
Use when the user wants to author or edit an apm.yml manifest
|
||||
(dependencies, scripts, compilation, policy, registries), scaffold a new
|
||||
apm package or marketplace (apm plugin init, apm marketplace init/package
|
||||
add), register a marketplace as a consumer, compile/pack/publish an apm
|
||||
package for distribution, or validate/audit apm.yml and installed content
|
||||
(apm audit, apm marketplace check) — even if the user doesn't say "apm"
|
||||
explicitly, e.g. "set up the package manifest", "scaffold this as an apm
|
||||
package", "build the distributable", "check this passes CI". Do not use
|
||||
for installing the apm binary itself or setting up an agent runtime — use
|
||||
apm-install for those.
|
||||
add), install or resolve dependencies declared in apm.yml (apm install,
|
||||
apm install [PACKAGE_REF]), register a marketplace as a consumer,
|
||||
compile/pack/publish an apm package for distribution, or validate/audit
|
||||
apm.yml and installed content (apm audit, apm marketplace check) — even if
|
||||
the user doesn't say "apm" explicitly, e.g. "set up the package manifest",
|
||||
"scaffold this as an apm package", "install my apm dependencies", "resolve
|
||||
apm.yml deps", "build the distributable", "check this passes CI". Do not
|
||||
use for installing the apm binary itself or setting up an agent runtime —
|
||||
use apm-install for those.
|
||||
metadata:
|
||||
category: apm
|
||||
source_keys:
|
||||
@@ -35,7 +37,7 @@ metadata:
|
||||
| `/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` |
|
||||
| `/apm-workflow audit` | Validate integrity/policy or wire a CI gate (`apm audit`, `apm audit --ci`) | `references/audit.md` |
|
||||
|
||||
Read only the reference file matching the requested action — each is self-contained for its concern.
|
||||
|
||||
|
||||
@@ -45,4 +45,4 @@ Executes a named script defined under `scripts:` in `apm.yml`, with `--param` su
|
||||
|
||||
## Gotchas
|
||||
|
||||
- `claude plugin validate --strict` auto-scans every `.md` file directly under a compiled plugin's `agents/` directory and treats it as an agent definition requiring frontmatter, independent of any manifest declaration (this repo's own empirically-tested finding — see ADR-0010). A non-agent `.md` file (notes, provenance record, README) that ends up under `.apm/agents/` in the source tree will still fail validation once compiled to the `claude` target. Keep such files outside `.apm/agents/` (e.g. at the package root), regardless of what `apm.yml` declares.
|
||||
- `claude plugin validate --strict` auto-scans every `.md` file directly under a compiled plugin's `agents/` directory and treats it as an agent definition requiring frontmatter, independent of any manifest declaration (an empirically observed Claude Code platform behavior, not an `apm` mechanic). A non-agent `.md` file (notes, provenance record, README) that ends up under `.apm/agents/` in the source tree will still fail validation once compiled to the `claude` target. Keep such files outside `.apm/agents/` (e.g. at the package root), regardless of what `apm.yml` declares.
|
||||
|
||||
@@ -15,8 +15,10 @@ apm marketplace check # 3. validate refs resolve
|
||||
apm pack # 4. build marketplace artifacts
|
||||
```
|
||||
|
||||
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".
|
||||
5. Commit and release — commit the manifest changes, tag the release, and push, following your
|
||||
project's established git tooling/conventions (a dedicated commit/release skill or workflow,
|
||||
commitlint/Conventional Commits rules, required tags) rather than ad hoc raw `git` invocations,
|
||||
if such tooling exists.
|
||||
|
||||
`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.
|
||||
|
||||
|
||||
@@ -22,6 +22,8 @@ metadata:
|
||||
- github-plugins-finding-installing
|
||||
---
|
||||
|
||||
> **Deprecated:** Superseded by `apm-workflow` per ADR-0015 — deletion pending issue #90 (not yet changed). Use `apm-workflow marketplace` (`apm marketplace init`/`package add`/`check`) for CREATE/ADD/REMOVE/UPDATE and `apm-workflow compile` (`apm pack` emits `.claude-plugin/marketplace.json`) instead.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- Both marketplace files must be identical after every operation — never update one without the other in the same edit pass.
|
||||
|
||||
@@ -22,6 +22,8 @@ metadata:
|
||||
- github-plugins-finding-installing
|
||||
---
|
||||
|
||||
> **Deprecated:** Superseded by `apm-workflow` per ADR-0015 — deletion pending issue #90 (not yet changed). Use `apm-workflow configure` (apm.yml authoring, `apm plugin init` scaffolding) for CREATE/UPDATE and `apm-workflow compile` (`apm compile`/`apm pack`/`apm publish`) for RELEASE instead.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- Both manifests must carry identical `version` values — version parity is a hard invariant (ADR-0016). Never update version in one manifest without updating the other in the same edit pass.
|
||||
|
||||
Reference in New Issue
Block a user