Two review passes on PR #91 (correctness + simplification) found the
prior fixup commit (d6fd9b6) left the deprecation notice it added
half-applied, cited a nonexistent ADR, and introduced/compounded a
few duplicate restatements of the same facts across apm-workflow's
skill files and apm-orchestrate's Hard rules.
- plugin-author/SKILL.md cited ADR-0016 (doesn't exist) instead of
ADR-0006 for the version-parity invariant.
- The deprecation banner on plugin-author/marketplace-author wasn't
reflected in their routing `description:` frontmatter, forge's
routing table, either kyberforge README skill table, or CONTEXT.md
— now propagated consistently; routing behavior is unchanged since
issue #90 (repo-wide apm conversion) hasn't landed yet.
- apm-orchestrate's `configure` operation only covered scaffolding a
new package, not editing an existing apm.yml (e.g. removing a
marketplace.packages[] entry, which has no dedicated `apm` CLI verb
and is just a manifest edit). Added `edit-config`, intentionally
ungated — a local file edit isn't the same class of irreversible
action as `apm publish`, and normal review already gates the commit.
- Deduplicated facts restated 3-4x across SKILL.md/references/ADR
boundaries (audit semantics, reserved name prefixes, marketplace-add
direction, registries precondition), and trimmed configure.md's
~55-line apm.yml schema dump — copied near-verbatim from the
research doc — down to a compact key list with a pointer, matching
install.md's existing terse cross-referencing style.
Deliberately left as-is: apm-orchestrate's parallel/sequential
fan-out logic stays inline rather than extracted to a shared
reference, since neither git-orchestrate nor gitea-orchestrate need
it yet — premature extraction for a single caller.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0186ERbyACLRuRxPRnqwpa4m
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
## Why
The skill had no instruction to bump the catalog version after ADD, REMOVE, or UPDATE operations. Clients cache the marketplace catalog and use the version field to detect changes — without a bump, the new state is invisible until a forced refresh.
## Implementation Notes
Added a Gotcha explaining the rule and semver convention (ADD/REMOVE → minor, UPDATE → patch). Added a dedicated "Bump catalog version" step to each mutating flow. Updated README to match.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
Several small quality issues accumulated across plugin-author and
marketplace-author: the plugin-author description was ambiguous about
scope, the ADD flow asked an unnecessary clarifying question when local
path is the obvious default, VALIDATE had redundant wording already
captured inline, the keywords field was missing from the validation
checklist, and tests/README.md was a placeholder with nothing to test.
## Implementation Notes
- plugin-author: tightened description scope to "inside those
directories"; added `keywords` identical-in-both-manifests check to
VALIDATE checklist.
- marketplace-author: moved reserved-prefix constraint from gotchas
into the ADD checklist item; replaced the four-option prompt with a
default+escape-hatch ("I'll treat this as local path — is that right?");
folded the validate-from-root note inline and removed trailing padding;
deleted tests/README.md — no scripts/ directory exists, so the
placeholder was noise.
- README.md: removed the tests/README.md row from the file table.
## Why
The manifest-fields tables in both skills used imprecise labels ("CC-only",
"Copilot-only") that conflated two distinct reasons a field appears in only
one manifest: platform constraint (the other tool does not support the field
at all) versus repo convention (both tools support it, but the scaffold places
it in one manifest by design). This caused agents to treat convention
boundaries as hard platform constraints, producing unnecessary errors when
updating manifests for dual-tool repos.
Provenance was also incomplete: sources.md files were missing entries for
sources that had been consulted and were already contributing to SKILL.md
and manifest-fields.md content, making the evidence chain unverifiable.
## Implementation Notes
Field classification now uses three explicit categories — shared, platform
(one tool does not support the field), and convention (both tools support it;
scaffold places it in one manifest by design). The distinction matters because
convention fields may legitimately appear in the other manifest when there is
a deliberate reason; platform fields may not.
New gotchas added to plugin-author: agent files silently ignore hooks,
mcpServers, and permissionMode frontmatter; claude plugin tag --push requires
a clean working tree; --dry-run preview before tagging; --strict flag on
validate. New gotchas in marketplace-author: metadata object as Copilot CLI
canonical location for top-level fields; strict: false for dual-tool plugins;
sha takes precedence over ref for pinning; --strict flag on validate.
tests/ removed from plugin-author because new-plugin.sh has no branching
logic warranting a bats suite at this stage.
## Impact
Skill prompt changes only — no runtime code affected. Agents using these
skills will now correctly distinguish convention from constraint when deciding
which manifest to update for a given field.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
Plugin and marketplace management had no governed authoring path. Creating or
updating a plugin required knowing the dual-manifest convention, version parity
rules, and directory skeleton by memory — nothing enforced consistency or guided
the process.
`/plugin-author` closes that gap by owning the full plugin scaffold lifecycle:
create, update, rename, and release. `/marketplace-author` handles the
marketplace-facing side: register, deregister, and update plugin entries in
`marketplace.json`.
ADR-0016 codifies the version parity convention (identical `version` in both
`plugin.json` and `.claude-plugin/plugin.json`) that `/plugin-author` now
enforces. The two plugin.json files in this repo are backfilled to comply
(keys also sorted to pass the pretty-format-json hook). CONTEXT.md gains
glossary entries for "plugin scaffold" and "version parity" so future agents
have shared vocabulary for these concepts.
## Implementation Notes
`/plugin-author` ships a `scripts/new-plugin.sh` scaffold script that generates
the directory skeleton and both manifests in one shot; the skill calls the script
rather than generating files ad hoc so the scaffold is reviewable and repeatable.
Version parity is an invariant, not a suggestion — the skill will fail loudly
on create/update if the two versions would diverge.
ADR: docs/adr/0016-plugin-version-parity.md
