docs(kyberforge): fix path drift and content gaps from apm conversion

The apm conversion (5e23250) moved skills/agents to plugins/<name>/.apm/
and deleted plugin-author/marketplace-author, but a review against issue
#90's Definition of Done found several stale pre-conversion references
left behind by straight git-mv's, plus one real content gap:

- ADR-0014 still documented the old flat vale-prefilter paths in 6
  places, despite ADR-0015 claiming it had been updated.
- ADR-0015 also overclaimed: it said ADR-0014 had both a skills/ and an
  agents/ path regex updated, but ADR-0014 never had an agents/ path
  regex to begin with (its one "agents" mention is a Vale glob-section
  identifier, not a filesystem path). Corrected the wording.
- CONTEXT.md's Skill glossary entry, its Vale-prefilter section, and its
  plugin-author/marketplace-author forward-pointer all still described
  the pre-conversion layout or a "pending issue #90" state that has since
  landed.
- LESSONS.md and two skill test READMEs pointed at skill-author/
  skill-audit/agent-author paths without the .apm/ segment.
- apm-workflow/references/marketplace.md cited plugin-author/SKILL.md's
  Gotchas for the Claude Code reserved plugin-name-prefix list, but that
  list was never actually carried into apm-workflow during the
  conversion despite ADR-0015 claiming it was. Recovered the list from
  git history and inlined it directly rather than leaving a dangling
  citation.
- agent-author/references/deployment-modes.md had an example
  contradicting its own stated .apm/agents/ convention two lines above.

Refs: #90
This commit is contained in:
2026-08-13 07:50:56 +00:00
parent 5e232503c4
commit 7910b8b12c
8 changed files with 18 additions and 17 deletions

View File

@@ -33,7 +33,7 @@ This makes the old "silently ignored at plugin scope" framing moot. It's not tha
Plugin agents in **subdirectories** get compound identifiers:
```
plugins/my-plugin/agents/review/security.md → my-plugin:review:security
plugins/my-plugin/.apm/agents/review/security.agent.md → my-plugin:review:security
```
Users must invoke with `@agent-my-plugin:review:security`. **Keep agents flat in `agents/` to avoid this** — subdirectory nesting is rarely worth the UX cost.

View File

@@ -25,7 +25,7 @@ git clone https://github.com/bats-core/bats-assert tests/test_helper/bats-assert
Run all tests for this skill (from the repo root):
```bash
bats plugins/kyberforge/skills/agent-author/tests/
bats plugins/kyberforge/.apm/skills/agent-author/tests/
```
## If no tests are needed

View File

@@ -77,5 +77,5 @@ Without this block, the default versioning strategy ties every listed package to
## Gotchas
- Only `claude` and `codex` marketplace output profiles exist in apm 0.28.0 — confirmed via source (`apm_cli/marketplace/output_profiles.py`: `MARKETPLACE_OUTPUTS = {claude: ..., codex: ...}`, nothing else). There is no native Copilot marketplace output; `apm pack` will not generate one. A repo needing a Copilot-consumable marketplace manifest must maintain it separately by other means.
- A package/plugin `name` compiling to the `claude` target must avoid Claude Code's reserved name prefixes (see `plugin-author/SKILL.md` Gotchas for the current list) — otherwise the compiled `.claude-plugin/marketplace.json` is rejected by Claude Code's validator. This is a Claude Code platform constraint, independent of how the manifest gets authored.
- A package/plugin `name` compiling to the `claude` target must avoid Claude Code's reserved name prefixes/values — `anthropic-*`, `claude-*`, `agent-skills`, `official-claude-plugins` — otherwise the compiled `.claude-plugin/marketplace.json` is rejected by Claude Code's validator. This is a Claude Code platform constraint, independent of how the manifest gets authored.
- Removing a package from `marketplace.packages[]` in `apm.yml` and re-packing changes the public/consumed catalog. Confirm with the user in conversation before removing the entry and running `apm pack` — this is a normal `apm.yml` edit (not a distinct apm-orchestrate operation with its own gate), so the confirmation is conversational, the same as any other consequential manifest edit.

View File

@@ -18,7 +18,7 @@ git clone https://github.com/bats-core/bats-assert tests/test_helper/bats-assert
Run all tests for this skill (from the repo root):
```bash
bats plugins/kyberforge/skills/skill-audit/tests/
bats plugins/kyberforge/.apm/skills/skill-audit/tests/
```
## Files