diff --git a/plugins/kyberforge/.apm/agents/apm-orchestrate.agent.md b/plugins/kyberforge/.apm/agents/apm-orchestrate.agent.md index 0e048c9..ad736b7 100644 --- a/plugins/kyberforge/.apm/agents/apm-orchestrate.agent.md +++ b/plugins/kyberforge/.apm/agents/apm-orchestrate.agent.md @@ -20,7 +20,7 @@ You resolve the package root once per dispatched operation (the directory contai These are non-negotiable regardless of `confirm` or any skill-local override: - `apm publish` claims a version on a registry — treat it as irreversible. Refuse without explicit `confirm: true`; always dispatch with `--dry-run -v` first and surface that output to the caller before the real publish, even when `confirm: true` was given. - Never guess the marketplace-add direction from context — resolve strictly from the operation name (`add-package` vs `add-marketplace`); see apm-workflow/references/marketplace.md Gotchas for why the two are easy to conflate. -- `apm.yml`'s `type:` field constrains what `.apm/` may contain — when scaffolding (`init-package`), set `type:` before any primitive content is added; do not defer it. +- `apm.yml`'s `type:` field routes processing (native skill install vs AGENTS.md compilation); it never validates `.apm/` content, and a mismatch is silent rather than an error. When scaffolding (`init-package`), set `type:` to cover every primitive the package will ship, and report the deployed output rather than the exit code — see apm-workflow/references/configure.md Gotchas. - A clean plain `apm audit` is not a CI-equivalent pass — if the caller's intent is a CI gate, dispatch `audit-ci`, not `audit`. - Check the `apm experimental enable registries` precondition before dispatching any operation that depends on a named registry, and fail with a clear diagnostic rather than silently no-op'ing like apm itself does — see apm-workflow/references/configure.md Gotchas for the underlying constraint (summarised in its SKILL.md Gotchas). - You are read-only against the working tree. Never create, edit, or delete a file — not an `apm.yml`, not a `.apm/` primitive, not compiled output, not a scratch note. `edit-config` is an operation you *route* to `apm-workflow`, never one you perform: dispatching it is allowed only when the caller asked for that edit, never as your own repair of something you noticed. diff --git a/plugins/kyberforge/.apm/skills/apm-workflow/references/configure.md b/plugins/kyberforge/.apm/skills/apm-workflow/references/configure.md index e99cc0e..6b7021f 100644 --- a/plugins/kyberforge/.apm/skills/apm-workflow/references/configure.md +++ b/plugins/kyberforge/.apm/skills/apm-workflow/references/configure.md @@ -25,7 +25,7 @@ version: 1.0.0 - `name`, `version` — required (see above) - `description`, `author`, `license`, `homepage`, `repository`, `keywords` — standard package metadata -- `type` — `instructions | skill | hybrid | prompts`; constrains what `.apm/` may contain, so set it before scaffolding content (see Gotchas) +- `type` — `instructions | skill | hybrid | prompts`; selects how the package is processed at install/compile time. It is a routing selector, not a constraint on what `.apm/` may contain (see Gotchas) - `targets` — which harnesses this package compiles to (plural list form preferred; legacy singular `target: copilot,claude` CSV form still accepted) - `includes` — `auto` publishes the authoritative local layout as-is; it is not scoped down to what's relevant, so anything narrower needs an explicit repo-path list. Note: `auto` also does not sweep generic root-level passthrough files (README.md, docs/, sources.md, config files) into the `apm pack` distribution bundle — see `references/compile.md` - `dependencies`/`devDependencies` — `apm`/`mcp`/`lsp` entries; `devDependencies` share the same shape but are excluded from the shipped artifact @@ -85,6 +85,6 @@ apm config set registry.corp-main.default true ## Gotchas -- `apm.yml`'s `type:` field constrains what `.apm/` may contain — set it before scaffolding content, not after. Changing it later does not retroactively validate what is already on disk. +- `apm.yml`'s `type:` field validates nothing about `.apm/`. It selects processing: `instructions` compiles to AGENTS.md only, `skill` installs a native skill only, `prompts` emits commands only, `hybrid` does both (see `apm_cli/models/validation.py`, `PackageContentType`). apm checks only that the value parses to one of those four strings; no check anywhere compares it against the primitives actually on disk, and no mismatch diagnostic exists. A package declaring `type: instructions` while shipping `.apm/skills/` therefore raises no error — the mismatch resolves silently, either by omitting that primitive from the install/compile output or, in apm 0.28.0 where `get_effective_type()` routes off the on-disk layout and never reads the declared field, by ignoring the declared value outright. Both directions are silent: `apm install` and `apm compile` can exit 0 having shipped none of the primitives you expected. Set `type:` to cover every primitive the package ships, and confirm the deployed output rather than the exit code. - `apm experimental enable registries` must run before any `registry.*` config takes effect. Declaring a `registries:` block or running `apm config set registry.*` without it silently does nothing — no error, no warning. - `apm plugin init ` run with a positional name argument, from inside a directory already named ``, creates a wrongly-nested `//` subdirectory — it treats the positional arg as "create a new project directory named X," not "confirm the current directory is X." Fix: omit the positional argument entirely when already cd'd into the target package directory — run `apm plugin init --yes --target claude,copilot` instead. diff --git a/plugins/kyberforge/.apm/skills/skill-audit/references/body-discipline.md b/plugins/kyberforge/.apm/skills/skill-audit/references/body-discipline.md index d4a7945..e271508 100644 --- a/plugins/kyberforge/.apm/skills/skill-audit/references/body-discipline.md +++ b/plugins/kyberforge/.apm/skills/skill-audit/references/body-discipline.md @@ -81,7 +81,7 @@ table** plus the gates common to every branch, and each flow lives in its own se invocation then pays for every branch it did not take. The reference shape in this repo is `apm-workflow`: a **237-word body** dispatching to roughly -3,200 words of references across five mutually exclusive invocations. Its whole-file count is 304 +3,400 words of references across five mutually exclusive invocations. Its whole-file count is 304 words — cite 237 when calibrating a body, or the conflation this section warns against reappears in the finding itself. diff --git a/plugins/kyberforge/.apm/skills/skill-author/references/contract.md b/plugins/kyberforge/.apm/skills/skill-author/references/contract.md index 70723ef..15bbab4 100644 --- a/plugins/kyberforge/.apm/skills/skill-author/references/contract.md +++ b/plugins/kyberforge/.apm/skills/skill-author/references/contract.md @@ -120,7 +120,7 @@ A generic pointer ("see references/ for details") is a Vale error — the agent **Dispatch is mandatory at two or more mutually exclusive flows.** The body carries the dispatch table and the gates common to every branch; each flow gets its own self-contained `references/` -file. Exemplar: the `apm-workflow` skill — a **237-word body** dispatching to 3,222 words of +file. Exemplar: the `apm-workflow` skill — a **237-word body** dispatching to 3,416 words of references. Calibrate against 237: that file's whole-file count is 304 words, and aiming at that number instead overshoots the body budget by ~30%. diff --git a/plugins/kyberforge/agents/apm-orchestrate.agent.md b/plugins/kyberforge/agents/apm-orchestrate.agent.md index 0e048c9..ad736b7 100644 --- a/plugins/kyberforge/agents/apm-orchestrate.agent.md +++ b/plugins/kyberforge/agents/apm-orchestrate.agent.md @@ -20,7 +20,7 @@ You resolve the package root once per dispatched operation (the directory contai These are non-negotiable regardless of `confirm` or any skill-local override: - `apm publish` claims a version on a registry — treat it as irreversible. Refuse without explicit `confirm: true`; always dispatch with `--dry-run -v` first and surface that output to the caller before the real publish, even when `confirm: true` was given. - Never guess the marketplace-add direction from context — resolve strictly from the operation name (`add-package` vs `add-marketplace`); see apm-workflow/references/marketplace.md Gotchas for why the two are easy to conflate. -- `apm.yml`'s `type:` field constrains what `.apm/` may contain — when scaffolding (`init-package`), set `type:` before any primitive content is added; do not defer it. +- `apm.yml`'s `type:` field routes processing (native skill install vs AGENTS.md compilation); it never validates `.apm/` content, and a mismatch is silent rather than an error. When scaffolding (`init-package`), set `type:` to cover every primitive the package will ship, and report the deployed output rather than the exit code — see apm-workflow/references/configure.md Gotchas. - A clean plain `apm audit` is not a CI-equivalent pass — if the caller's intent is a CI gate, dispatch `audit-ci`, not `audit`. - Check the `apm experimental enable registries` precondition before dispatching any operation that depends on a named registry, and fail with a clear diagnostic rather than silently no-op'ing like apm itself does — see apm-workflow/references/configure.md Gotchas for the underlying constraint (summarised in its SKILL.md Gotchas). - You are read-only against the working tree. Never create, edit, or delete a file — not an `apm.yml`, not a `.apm/` primitive, not compiled output, not a scratch note. `edit-config` is an operation you *route* to `apm-workflow`, never one you perform: dispatching it is allowed only when the caller asked for that edit, never as your own repair of something you noticed. diff --git a/plugins/kyberforge/skills/apm-workflow/references/configure.md b/plugins/kyberforge/skills/apm-workflow/references/configure.md index e99cc0e..6b7021f 100644 --- a/plugins/kyberforge/skills/apm-workflow/references/configure.md +++ b/plugins/kyberforge/skills/apm-workflow/references/configure.md @@ -25,7 +25,7 @@ version: 1.0.0 - `name`, `version` — required (see above) - `description`, `author`, `license`, `homepage`, `repository`, `keywords` — standard package metadata -- `type` — `instructions | skill | hybrid | prompts`; constrains what `.apm/` may contain, so set it before scaffolding content (see Gotchas) +- `type` — `instructions | skill | hybrid | prompts`; selects how the package is processed at install/compile time. It is a routing selector, not a constraint on what `.apm/` may contain (see Gotchas) - `targets` — which harnesses this package compiles to (plural list form preferred; legacy singular `target: copilot,claude` CSV form still accepted) - `includes` — `auto` publishes the authoritative local layout as-is; it is not scoped down to what's relevant, so anything narrower needs an explicit repo-path list. Note: `auto` also does not sweep generic root-level passthrough files (README.md, docs/, sources.md, config files) into the `apm pack` distribution bundle — see `references/compile.md` - `dependencies`/`devDependencies` — `apm`/`mcp`/`lsp` entries; `devDependencies` share the same shape but are excluded from the shipped artifact @@ -85,6 +85,6 @@ apm config set registry.corp-main.default true ## Gotchas -- `apm.yml`'s `type:` field constrains what `.apm/` may contain — set it before scaffolding content, not after. Changing it later does not retroactively validate what is already on disk. +- `apm.yml`'s `type:` field validates nothing about `.apm/`. It selects processing: `instructions` compiles to AGENTS.md only, `skill` installs a native skill only, `prompts` emits commands only, `hybrid` does both (see `apm_cli/models/validation.py`, `PackageContentType`). apm checks only that the value parses to one of those four strings; no check anywhere compares it against the primitives actually on disk, and no mismatch diagnostic exists. A package declaring `type: instructions` while shipping `.apm/skills/` therefore raises no error — the mismatch resolves silently, either by omitting that primitive from the install/compile output or, in apm 0.28.0 where `get_effective_type()` routes off the on-disk layout and never reads the declared field, by ignoring the declared value outright. Both directions are silent: `apm install` and `apm compile` can exit 0 having shipped none of the primitives you expected. Set `type:` to cover every primitive the package ships, and confirm the deployed output rather than the exit code. - `apm experimental enable registries` must run before any `registry.*` config takes effect. Declaring a `registries:` block or running `apm config set registry.*` without it silently does nothing — no error, no warning. - `apm plugin init ` run with a positional name argument, from inside a directory already named ``, creates a wrongly-nested `//` subdirectory — it treats the positional arg as "create a new project directory named X," not "confirm the current directory is X." Fix: omit the positional argument entirely when already cd'd into the target package directory — run `apm plugin init --yes --target claude,copilot` instead. diff --git a/plugins/kyberforge/skills/skill-audit/references/body-discipline.md b/plugins/kyberforge/skills/skill-audit/references/body-discipline.md index d4a7945..e271508 100644 --- a/plugins/kyberforge/skills/skill-audit/references/body-discipline.md +++ b/plugins/kyberforge/skills/skill-audit/references/body-discipline.md @@ -81,7 +81,7 @@ table** plus the gates common to every branch, and each flow lives in its own se invocation then pays for every branch it did not take. The reference shape in this repo is `apm-workflow`: a **237-word body** dispatching to roughly -3,200 words of references across five mutually exclusive invocations. Its whole-file count is 304 +3,400 words of references across five mutually exclusive invocations. Its whole-file count is 304 words — cite 237 when calibrating a body, or the conflation this section warns against reappears in the finding itself. diff --git a/plugins/kyberforge/skills/skill-author/references/contract.md b/plugins/kyberforge/skills/skill-author/references/contract.md index 70723ef..15bbab4 100644 --- a/plugins/kyberforge/skills/skill-author/references/contract.md +++ b/plugins/kyberforge/skills/skill-author/references/contract.md @@ -120,7 +120,7 @@ A generic pointer ("see references/ for details") is a Vale error — the agent **Dispatch is mandatory at two or more mutually exclusive flows.** The body carries the dispatch table and the gates common to every branch; each flow gets its own self-contained `references/` -file. Exemplar: the `apm-workflow` skill — a **237-word body** dispatching to 3,222 words of +file. Exemplar: the `apm-workflow` skill — a **237-word body** dispatching to 3,416 words of references. Calibrate against 237: that file's whole-file count is 304 words, and aiming at that number instead overshoots the body budget by ~30%.