From bd2bf667c5e326f7bcebc85a3caa6bc5930fed1b Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 10:10:55 +0000 Subject: [PATCH] docs: restore two guard-rails the trim dropped MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Why: 1929ffd and b9c7762 preserved every constant, hook ID and error string, but two don't-re-litigate notes were lost. Both were guard-rails — they fired from preloaded context, before the mistake. Restoring the sentence to an on-demand spec doc restores the text without restoring the function, since an on-demand file is opened after a plan is formed, not before. Implementation notes: placed by when each note must fire, not by what it is about. - "Do not expect `apm pack` to refresh the .github/plugin/marketplace.json mirror" now lives in the DRIFT failure message of the script and hook that already catch that exact mistake. It costs no preloaded tokens, fires at the moment of the error, and cannot be missed. No test asserts on that message; --check and shellcheck both pass. - Plugin self-containment has no gate that fires on it, so it goes in architecture.md's Plugin model beside "self-contained plugin units", stated as the constraint it is rather than a description, with the two consequences that make it load-bearing: the duplicated Vale styles (ADR-0014) and ADR-0020's constants copied into three validators. Impact: the every-session set is unchanged — neither note returns to AGENTS.md. --- docs/spec/architecture.md | 2 +- scripts/sync-marketplace-mirror.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/spec/architecture.md b/docs/spec/architecture.md index 137ad93..dc21323 100644 --- a/docs/spec/architecture.md +++ b/docs/spec/architecture.md @@ -25,7 +25,7 @@ Skills are **not** deployed by `install.sh`. They are distributed as plugins and ## Plugin model -Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`, installed independently — via `apm install` here, or `claude plugin install @holocron` for a host consuming the marketplace natively (ADR-0018). Each plugin is an **apm package**: `plugins//apm.yml` plus a hand-authored `plugins//.apm/{skills,agents,hooks,commands,instructions,extensions}/` tree (ADR-0015). There is no hand-maintained `plugin.json` — every manifest and every host-visible content directory is compiled from that source. +Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`, installed independently — via `apm install` here, or `claude plugin install @holocron` for a host consuming the marketplace natively (ADR-0018). Self-contained is a hard constraint, not a description: a plugin is copied to a cache on install, so nothing inside it may reference a file outside its own directory. That is why the Vale styles are duplicated across two skills rather than shared (ADR-0014), and why ADR-0020's constants are copied into three validators rather than sourced from one. Each plugin is an **apm package**: `plugins//apm.yml` plus a hand-authored `plugins//.apm/{skills,agents,hooks,commands,instructions,extensions}/` tree (ADR-0015). There is no hand-maintained `plugin.json` — every manifest and every host-visible content directory is compiled from that source. Which plugin a new skill belongs in follows from what each one is scoped to. The boundary that matters most in practice is `core` vs `kyberforge`: `core` is the home for cross-cutting, repo-agnostic utility skills that a consumer would want against *their* repo, while `kyberforge` is meta-tooling for the holocron marketplace itself. A skill that authors a target repo's `AGENTS.md` is `core`; a skill that audits a `SKILL.md` against this marketplace's contract is `kyberforge`. diff --git a/scripts/sync-marketplace-mirror.sh b/scripts/sync-marketplace-mirror.sh index 1af7882..ffdb066 100755 --- a/scripts/sync-marketplace-mirror.sh +++ b/scripts/sync-marketplace-mirror.sh @@ -60,7 +60,7 @@ fi if [[ "$CHECK" -eq 1 ]]; then if [[ ! -f "$DST" ]] || ! diff -q "$SRC" "$DST" >/dev/null 2>&1; then echo "DRIFT $DST: out of sync with .claude-plugin/marketplace.json" >&2 - echo "Fix: bash scripts/sync-marketplace-mirror.sh" >&2 + echo "Fix: bash scripts/sync-marketplace-mirror.sh -- apm ships no output profile targeting this path, so \`apm pack\` does not refresh it. Expecting it to is exactly the drift this script and its pre-push hook exist to prevent." >&2 exit 1 fi exit 0