From 7910b8b12cf23105775308a00eb86a8224d0b991 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Thu, 13 Aug 2026 07:50:56 +0000 Subject: [PATCH] docs(kyberforge): fix path drift and content gaps from apm conversion The apm conversion (5e23250) moved skills/agents to plugins//.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 --- CONTEXT.md | 6 +++--- LESSONS.md | 2 +- .../adr/0014-vale-prefilter-ships-from-the-plugin.md | 12 ++++++------ ...0015-apm-replaces-plugin-marketplace-authoring.md | 7 ++++--- .../agent-author/references/deployment-modes.md | 2 +- .../.apm/skills/agent-author/tests/README.md | 2 +- .../skills/apm-workflow/references/marketplace.md | 2 +- .../.apm/skills/skill-audit/tests/README.md | 2 +- 8 files changed, 18 insertions(+), 17 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index b6c824c..b915214 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -24,7 +24,7 @@ Before answering any design or architecture question, check for existing decisio A separate product (separate repo) for browsing, editing, and configuring AI development configs through a proper product UI. Git is the persistence layer, invisible to the user. The app is repo-agnostic — it works with any git repo that follows these conventions. This repo is the canonical default content (the official starter). See `docs/VISION.md` for the phased roadmap. ### Skills -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. +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//.apm/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. In this repo, plugins live under `plugins//`, each with its own `apm.yml` + `.apm/{skills,agents,hooks,...}` — this is the authoring source of truth for the plugin's content (ADR-0015). `.claude-plugin/plugin.json` (Claude Code) and `.github/plugin/plugin.json` (Copilot CLI) are **compiled output** of `apm pack`/`apm compile`, generated from `apm.yml` + `.apm/` — they are not hand-edited. Plugins are copied to a cache on install — they cannot reference files outside their own directory. Install a plugin with `claude plugin install @`. @@ -49,7 +49,7 @@ The provider-agnostic always-on instruction entry point. Two files: Contains always-on rules in plain markdown with no provider-specific syntax (no `@import`). Provider-specific files (`CLAUDE.md`) are thin adapters that import the relevant `AGENTS.md` and add only Claude Code-specific syntax. This pattern means a single source of truth can serve multiple providers without duplication. See ADR-0003. ### Skill composition -A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology; `forge` calls `grill-with-docs` to refine intent, classifies the target artifact type (skill / agent / plugin / marketplace entry), then routes to the matching `*-author` skill — which owns its own create/improve logic and, where applicable, its own inline audit closeout (`skill-author` runs `/skill-audit`, `agent-author` runs `kyberforge:agent-audit`, both in the same context as the authoring work). Reserve `forge` for genuinely undecided "which artifact type is this" questions — an already-fully-specified corrective edit (exact file, line, and fix already known) should call the target author skill directly instead (`skill-author`, `plugin-author`, `agentsmd-author`, etc.); routing a known fix through `forge`'s grill-and-classify layer adds unnecessary indirection and, in practice, has been observed to lose track of hard constraints handed down the chain (e.g. "don't commit yet," "edit in this worktree") because each hop re-derives instructions from a shorter brief. `forge` additionally runs its own independent recheck after a skill/agent route finishes: a clean-context subagent (not forked, no inherited context) re-runs the same audit skill against the finished artifact, as a distinct verification layer from the author skill's inline audit — the two can share blind spots since the inline audit runs in the same context as the work it checks. If the clean audit surfaces any unresolved finding, `forge` loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved; only then is the route done. `plugin-author` and `marketplace-author` have no audit counterpart and get no recheck; their terminal check is `claude plugin validate`. Both are deprecated per ADR-0015, superseded by `apm-workflow`, pending issue #90 (not yet changed). +A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology; `forge` calls `grill-with-docs` to refine intent, classifies the target artifact type (skill / agent / plugin / marketplace entry), then routes to the matching `*-author` skill — which owns its own create/improve logic and, where applicable, its own inline audit closeout (`skill-author` runs `/skill-audit`, `agent-author` runs `kyberforge:agent-audit`, both in the same context as the authoring work). Reserve `forge` for genuinely undecided "which artifact type is this" questions — an already-fully-specified corrective edit (exact file, line, and fix already known) should call the target author skill directly instead (`skill-author`, `plugin-author`, `agentsmd-author`, etc.); routing a known fix through `forge`'s grill-and-classify layer adds unnecessary indirection and, in practice, has been observed to lose track of hard constraints handed down the chain (e.g. "don't commit yet," "edit in this worktree") because each hop re-derives instructions from a shorter brief. `forge` additionally runs its own independent recheck after a skill/agent route finishes: a clean-context subagent (not forked, no inherited context) re-runs the same audit skill against the finished artifact, as a distinct verification layer from the author skill's inline audit — the two can share blind spots since the inline audit runs in the same context as the work it checks. If the clean audit surfaces any unresolved finding, `forge` loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved; only then is the route done. `plugin-author` and `marketplace-author` had no audit counterpart and got no recheck; their terminal check was `claude plugin validate`. Both were deprecated per ADR-0015, superseded by `apm-workflow`, and deleted entirely once issue #90 landed. ### Provider-agnostic issue tracker Skills and workflows reference "linked issue" generically rather than a specific provider. Gitea is the canonical issue tracker for this repo (see ADR-0017). "Issue" is the cross-provider term (GitHub, GitLab, Gitea all use it). @@ -70,7 +70,7 @@ A companion skill (`core` plugin) that detects a target repo's provider-specific A standalone, repo-agnostic plugin (`plugins/lint/`) for configuring and running linters — not scoped to kyberforge's own meta-tooling. First linter is Vale (prose style linting), split into two skills per the git/gitea per-concern pattern: `vale-config` (setup — `.vale.ini`, `StylesPath`, styles) and `vale-run` (invoke Vale, interpret/report findings). A `lint-runner` agent composes these for isolated-context lint sweeps; it is report-only (no `Edit` tool) — it flags findings, it does not rewrite prose. Vale's research docs (`docs/research/docs/vale/`) moved from `plugins/kyberforge/` to `plugins/lint/` to keep the provenance chain same-plugin. ### Vale audit prefilter (skill-audit / agent-audit) -Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so it doesn't live in `plugins/lint/` — but per ADR-0014 it also doesn't live at the repo root anymore. Two copies live inside `plugins/kyberforge/`, one per skill, since a plugin's cache-install only copies each skill's own files (no cross-skill sharing): `plugins/kyberforge/skills/agent-audit/assets/vale/` is canonical (`.vale.ini` plus a custom `Kyberforge` style covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check), and `plugins/kyberforge/skills/skill-audit/assets/vale/` is a smaller duplicate (`Kyberforge` only, scoped to `SKILL.md`) kept in sync by `scripts/check-vale-style-sync.sh` (pre-push). A root-level `.pre-commit-hooks.yaml` exposes both copies (plus `skill-size-check`) so any external repo can enforce the same rules via `repo: , rev: ` in its own `.pre-commit-config.yaml` — pre-commit clones the pinned rev into its own cache, independent of whether Claude Code or the `kyberforge` plugin is installed at all, and the same mechanism covers CI (`pre-commit run --all-files`). This repo's own `vale-audit-prefilter-skill`/`-agent` pre-commit hooks consume the identical plugin-bundled copies via `repo: local` (not a third root copy, and not a pinned self-reference — a pinned self-reference would lint working-tree edits against the last tagged release rather than the change being made). Every rule is `level: error` and every alert is a FAIL — no ignorable tier, same as shellcheck, the test suite, and conventional-pre-commit. Graded severities do not work here: Vale's exit code keys on `error` alerts alone, so `warning`/`suggestion` rules exit 0 and pre-commit swallows the output of a passing hook, leaving them invisible and blocking nothing. `MinAlertLevel` and `--minAlertLevel` are correspondingly absent from `.vale.ini` and the hook, being no-ops under this model. Vale covers the pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) plus, per ADR-0013, one body-wide prose-pattern check ("There is/are" sentence openers) — everything else about body discipline (defaults-vs-menus, why-rationale, non-pattern-matchable judgment calls), near-miss exclusion strength, and control calibration stays LLM judgment. +Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so it doesn't live in `plugins/lint/` — but per ADR-0014 it also doesn't live at the repo root anymore. Two copies live inside `plugins/kyberforge/`, one per skill, since a plugin's cache-install only copies each skill's own files (no cross-skill sharing): `plugins/kyberforge/.apm/skills/agent-audit/assets/vale/` is canonical (`.vale.ini` plus a custom `Kyberforge` style covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check), and `plugins/kyberforge/.apm/skills/skill-audit/assets/vale/` is a smaller duplicate (`Kyberforge` only, scoped to `SKILL.md`) kept in sync by `scripts/check-vale-style-sync.sh` (pre-push). A root-level `.pre-commit-hooks.yaml` exposes both copies (plus `skill-size-check`) so any external repo can enforce the same rules via `repo: , rev: ` in its own `.pre-commit-config.yaml` — pre-commit clones the pinned rev into its own cache, independent of whether Claude Code or the `kyberforge` plugin is installed at all, and the same mechanism covers CI (`pre-commit run --all-files`). This repo's own `vale-audit-prefilter-skill`/`-agent` pre-commit hooks consume the identical plugin-bundled copies via `repo: local` (not a third root copy, and not a pinned self-reference — a pinned self-reference would lint working-tree edits against the last tagged release rather than the change being made). Every rule is `level: error` and every alert is a FAIL — no ignorable tier, same as shellcheck, the test suite, and conventional-pre-commit. Graded severities do not work here: Vale's exit code keys on `error` alerts alone, so `warning`/`suggestion` rules exit 0 and pre-commit swallows the output of a passing hook, leaving them invisible and blocking nothing. `MinAlertLevel` and `--minAlertLevel` are correspondingly absent from `.vale.ini` and the hook, being no-ops under this model. Vale covers the pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) plus, per ADR-0013, one body-wide prose-pattern check ("There is/are" sentence openers) — everything else about body discipline (defaults-vs-menus, why-rationale, non-pattern-matchable judgment calls), near-miss exclusion strength, and control calibration stays LLM judgment. Both skills' Step 1, and the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks, call each copy's own `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching on most — not all — multi-line descriptions. Verified by reproduction, not assumed: `>` folded scalars, plain (unquoted) continuation lines, and single- or double-quoted multi-line scalars all yield 0 alerts and exit 0 on a deliberately-bad fixture, while a `|` literal block spanning the same 2+ lines lints normally (alerts fire, exit 1). The wrapper flattens those three broken forms to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; `|` literal blocks and single-line descriptions pass through untouched, already linting correctly. The plain and quoted forms previously passed silently — unflattened and unmatched — so a bad description in either sailed through the prefilter. Handed no `--config` at all, the wrapper falls back to its own sibling `assets/vale/.vale.ini`, located from `${BASH_SOURCE[0]}` rather than from the cwd — which is why both manifests' `entry:` is now the bare script path with no argument after it. pre-commit prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]), *cmd[1:])`), so every later argument resolves against the *consuming* repo's root: a `--config` in `.pre-commit-hooks.yaml` pointed at a path no consumer has and hard-failed every external run with `E100 [--config] Runtime error`. `.pre-commit-config.yaml` drops the argument too, deliberately keeping the two entries identical — the local `repo: local` hook resolved its `--config` correctly only because the consuming repo *was* this repo, and that divergence is why three review rounds exercised a path no external consumer takes and missed the defect. An explicit `--config` still wins, in all three argv forms (`--config X`, `--config=/abs`, `--config=rel`), and a relative one still resolves against the caller's cwd, matching bare `vale`, not the repo root. Both audit skills' Step 1 now passes no `--config` either: it resolves the script relative to the skill's own directory so the call works from an installed plugin cache, but a relative `--config` alongside it would still resolve against the cwd, yielding `E100 Runtime error ... does not exist` and exit 2 — which both skills' fallback misreads as "vale unavailable" and silently downgrades to full LLM judgment. `tests/test-vale-wrap.sh` regression-tests this against skill-audit's copy specifically (its fixtures are all `SKILL.md`-shaped, and only skill-audit's `.vale.ini` has that glob section). Each `.vale.ini`'s section globs are path-agnostic (`[**/SKILL.md]` for skill-audit's copy; `[**/agents/*.md]`/`[**/*.agent.md]` for agent-audit's) and do no scoping on their own: Vale's `*` crosses `/`. Scoping comes from each pre-commit hook's own `files:` regex and from the audit skills passing one explicit file per invocation. The two manifests scope differently on purpose: this repo's `.pre-commit-config.yaml` pins its own layout — `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` for `-skill`, `^plugins/[^/]+/agents/[^/]+\.md$` for `-agent` — while the shipped `.pre-commit-hooks.yaml` stays layout-agnostic for external consumers whose skills live anywhere, using `(^|/)SKILL\.md$` and `(^|/)agents/[^/]+\.md$|\.agent\.md$`. Both manifests split the prefilter into two hooks precisely because one combined hook pointed at only one copy would silently 0-file-skip the other file type. A `SKILL.md` outside `plugins/` (e.g. project-scope `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and gets linted normally — the globs constrain filename shape, not location. Vale reports 0 files only when the path it is handed matches no glob section at all: a differently-named file, or a directory argument holding nothing that matches. That run prints `✔ 0 errors ... in 0 files.` and exits 0, indistinguishable from a clean pass, so both audits treat a 0-file Vale run as NOT RUN and fall back to full LLM judgment. diff --git a/LESSONS.md b/LESSONS.md index 835a386..570f05f 100644 --- a/LESSONS.md +++ b/LESSONS.md @@ -124,7 +124,7 @@ Two forks independently fixed `references/sources.md` with different approaches ## 2026-06-28 — Implementation agents must invoke /skill-author, not write skill files directly -When briefing an agent to implement a new skill, the instinct is to tell it to write the SKILL.md and supporting files directly. This bypasses Step 5 of the skill-author process (provenance), which requires reading all research `sources.md` files and recording every `extracted` slug in META.md. The `validate-provenance.sh` script catches the gap — but only after the commit, requiring a fix round. This pattern recurred twice in one session (plugin-author and marketplace-author initial implementation, then again in the first round of fix agents). Fix: briefs for implementation agents must explicitly say "invoke `/skill-author` (read and follow `plugins/kyberforge/skills/skill-author/SKILL.md`)" — not "write the skill files." Invoking the skill is the only reliable way to ensure all process gates, including provenance, run. +When briefing an agent to implement a new skill, the instinct is to tell it to write the SKILL.md and supporting files directly. This bypasses Step 5 of the skill-author process (provenance), which requires reading all research `sources.md` files and recording every `extracted` slug in META.md. The `validate-provenance.sh` script catches the gap — but only after the commit, requiring a fix round. This pattern recurred twice in one session (plugin-author and marketplace-author initial implementation, then again in the first round of fix agents). Fix: briefs for implementation agents must explicitly say "invoke `/skill-author` (read and follow `plugins/kyberforge/.apm/skills/skill-author/SKILL.md`)" — not "write the skill files." Invoking the skill is the only reliable way to ensure all process gates, including provenance, run. ## 2026-07-05 — Repo root is a bare checkout; work happens in worktrees only diff --git a/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md b/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md index 91a6e91..07c5416 100644 --- a/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md +++ b/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md @@ -18,9 +18,9 @@ full LLM judgment every time outside this repo — the exact gap ADR-0013 named the plugin itself, following the no-cross-skill-path rule already established in `skill-author/references/deployment-modes.md` (a plugin's cache-install only copies each skill's own files; there is no plugin-level shared directory). `agent-audit` needs both `Kyberforge` and -`KyberforgeCopilot` (it lints `.agent.md` files), so `plugins/kyberforge/skills/agent-audit/assets/vale/` +`KyberforgeCopilot` (it lints `.agent.md` files), so `plugins/kyberforge/.apm/skills/agent-audit/assets/vale/` is the canonical, superset copy. `skill-audit` needs a second, smaller copy -(`plugins/kyberforge/skills/skill-audit/assets/vale/`, `Kyberforge` only) since it cannot +(`plugins/kyberforge/.apm/skills/skill-audit/assets/vale/`, `Kyberforge` only) since it cannot reference agent-audit's copy across the skill boundary. Both skills' Step 1 now resolve `scripts/vale-wrap.sh`/`assets/vale/.vale.ini` relative to their own directory, the same way `scripts/validate.sh ` already does — no new resolution mechanism, just applying the @@ -38,7 +38,7 @@ and gets all three, fully decoupled from Claude Code. CI is the identical `pre-c **This repo's own dev-time gate** consumes the same plugin-bundled copies instead of a third root-level copy — per explicit instruction, this repo should be set up like any other consumer would be, not dogfood a special root-only path. The existing `repo: local` hook is retargeted -(not removed): `entry:` now points at `plugins/kyberforge/skills/{skill-audit,agent-audit}/scripts/vale-wrap.sh`. +(not removed): `entry:` now points at `plugins/kyberforge/.apm/skills/{skill-audit,agent-audit}/scripts/vale-wrap.sh`. `repo: local` is kept rather than switching to a pinned self-reference (`repo: , rev: `) — a pinned self-reference would lint working-tree edits against the *last tagged release*, not the change actually being made, which is wrong for the repo that @@ -58,7 +58,7 @@ single hook at agent-audit's copy silently scanned 0 SKILL.md files.) **The hook `entry:` is the wrapper alone; the wrapper self-locates its config.** pre-commit prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]), *cmd[1:])`); every later argument is handed to the process untouched and so resolves against the *consuming* -repo's root. A `--config plugins/kyberforge/skills/…/assets/vale/.vale.ini` in +repo's root. A `--config plugins/kyberforge/.apm/skills/…/assets/vale/.vale.ini` in `.pre-commit-hooks.yaml` therefore named a path no consumer has, and every external run died with `E100 [--config] Runtime error`. The external-consumer contract this ADR exists to establish cannot be expressed as a `--config` argument at all — the config path has to be derived inside @@ -105,8 +105,8 @@ doesn't wonder if it was overlooked. ## Consequences - Root `.vale.ini`, `styles/`, `scripts/vale-wrap.sh` are deleted. Two copies remain: - `plugins/kyberforge/skills/agent-audit/assets/vale/` (canonical, superset) and - `plugins/kyberforge/skills/skill-audit/assets/vale/` (subset, `Kyberforge` only). + `plugins/kyberforge/.apm/skills/agent-audit/assets/vale/` (canonical, superset) and + `plugins/kyberforge/.apm/skills/skill-audit/assets/vale/` (subset, `Kyberforge` only). - `plugins/kyberforge`'s `plugin.json` and `.claude-plugin/plugin.json` both patch-bump for every shipped content change (per ADR-0006's version-parity invariant): `1.2.5` for the relocation itself, `1.2.6` for the self-locating `vale-wrap.sh` that followed. diff --git a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md index ac3a42b..99695a3 100644 --- a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md +++ b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md @@ -107,9 +107,10 @@ correction) sorted what they document into three buckets: living at `plugins//.apm/agents/*.agent.md` — the directory path changed; the pre-existing `.agent.md` extension convention (ADR-0005/ADR-0010) and project/user scope are unaffected, per ADR-0016. -- ADR-0014 (Vale prefilter ships from the plugin) had its hardcoded path regexes - (`plugins//skills/...`/`plugins//agents/...`) updated for the `.apm/` nesting as part - of issue #90's execution. +- ADR-0014 (Vale prefilter ships from the plugin) had its hardcoded `plugins//skills/...` + paths (the Vale prefilter is skill-scoped only; ADR-0014 never referenced a + `plugins//agents/...` path) updated for the `.apm/` nesting as part of issue #90's + execution. - `kyberforge` gained three new artifacts (issue #88) before any conversion of existing content happened, then lost two (`plugin-author`/`marketplace-author`, deleted once issue #90 verified parity) — net version bump 1.3.1 → 1.4.0. The root marketplace catalog bumped 0.3.1 → 0.3.2 to diff --git a/plugins/kyberforge/.apm/skills/agent-author/references/deployment-modes.md b/plugins/kyberforge/.apm/skills/agent-author/references/deployment-modes.md index aefeb91..f4ee5d9 100644 --- a/plugins/kyberforge/.apm/skills/agent-author/references/deployment-modes.md +++ b/plugins/kyberforge/.apm/skills/agent-author/references/deployment-modes.md @@ -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. diff --git a/plugins/kyberforge/.apm/skills/agent-author/tests/README.md b/plugins/kyberforge/.apm/skills/agent-author/tests/README.md index 5b2cd41..057ac7e 100644 --- a/plugins/kyberforge/.apm/skills/agent-author/tests/README.md +++ b/plugins/kyberforge/.apm/skills/agent-author/tests/README.md @@ -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 diff --git a/plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md b/plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md index c79f4dc..c65ee5e 100644 --- a/plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md +++ b/plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md @@ -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. diff --git a/plugins/kyberforge/.apm/skills/skill-audit/tests/README.md b/plugins/kyberforge/.apm/skills/skill-audit/tests/README.md index e8d2466..00f7db5 100644 --- a/plugins/kyberforge/.apm/skills/skill-audit/tests/README.md +++ b/plugins/kyberforge/.apm/skills/skill-audit/tests/README.md @@ -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