feat(kyberforge): retarget agent-author to plugin-scope .apm/agents/

Plugin scope now authors a single vendor-neutral .apm/agents/<name>.agent.md
file (name/description/model/body only) instead of a Claude Code + Copilot
CLI pair, per ADR-0016: apm compile has no per-target field integrator, so
tools: and all Claude-only fields (isolation/maxTurns/effort/memory/
permissionMode) are omitted entirely rather than shipping a value that's
guaranteed wrong on one harness. Scope detection switches from a flat
plugin.json check to the same apm.yml+type: walk-up agent-audit's
validate.sh already uses. Project scope and user scope are unaffected —
both keep the existing dual-file pair model.

Refs: #89

plugins/kyberforge/skills/agent-author/references/deployment-modes.md

@@ -18,22 +18,15 @@ Agent definitions deploy at three scopes and behave differently at each. The sco
 |---|---|---|---|
 | User | `~/.claude/agents/` | `~/.copilot/agents/` | All sessions for this user |
 | Project | `.claude/agents/` | `.github/agents/` or `.copilot/agents/` | This repo only |
-| Plugin | `<plugin>/agents/` | `<plugin>/agents/` | Sessions with the plugin installed |
+| Plugin/APM | `<package-root>/.apm/agents/<name>.agent.md` — single vendor-neutral file, `apm compile` emits it to both targets | *(same file)* | Sessions with the plugin/package installed |
 
 When the same agent `name` appears at multiple scopes, **user scope wins over project scope wins over plugin scope** in Claude Code. In Copilot CLI, repo-level agents override enterprise and org-level; home-directory (user) agents override repo-level on name collision.
 
 ## Plugin scope restrictions
 
-Plugin agents (agents shipped inside a plugin's `agents/` directory) have fewer capabilities than project or user agents:
+Plugin/APM agents (`.apm/agents/<name>.agent.md`) carry only `name`, `description`, and optionally `model` in frontmatter — full stop (see ADR-0016). `apm compile` copies this frontmatter verbatim to both the Claude Code and Copilot CLI compile targets with no per-target integrator: Claude's `tools:` (space-separated string) and Copilot's `tools:` (alias list) are incompatible vocabularies, and Claude-only fields have no Copilot equivalent, so any harness-specific value is guaranteed wrong on at least one target.
 
-**Claude Code — silently ignored for plugin agents:**
-- `hooks` — per-agent event handlers; copy the agent to `.claude/agents/` to use these
-- `mcpServers` — inline MCP server definitions; not available in plugin context
-- `permissionMode` — silently ignored; the parent session's permission mode applies
-
-**Copilot CLI — unsupported or ignored:**
-- `mcp-servers` — cloud agents only; ignored in VS Code and most IDEs
-- `metadata` — key-value annotations; ignored in VS Code
+This makes the old "silently ignored at plugin scope" framing moot. It's not that `hooks`, `mcpServers`, `permissionMode`, `tools`, `isolation`, `maxTurns`, `effort`, `memory`, `disallowedTools`, `skills`, `color`, `initialPrompt`, or `background` are merely ignored at this scope — they are never written to the file at all. Copy the agent to `.claude/agents/` (project scope) or `~/.claude/agents/` (user scope) to use any of them.
 
 ## Scoped identifiers (Claude Code plugin agents only)
 
@@ -59,6 +52,6 @@ Agents at project or user scope are read directly from disk; cache isolation doe
 |---|---|---|
 | User | `~/.copilot/agents/<name>.agent.md` | Home directory |
 | Project | `.github/agents/<name>.agent.md` | Standard; also `.copilot/agents/` |
-| Plugin | `<plugin>/agents/<name>.agent.md` | Inside plugin root |
+| Plugin/APM | `<package-root>/.apm/agents/<name>.agent.md` | Not a Copilot-only file — this is the single vendor-neutral source `apm compile` reads for the Copilot CLI target |
 
-The `.agent.md` extension is **mandatory** — Copilot CLI does not pick up plain `.md` files in the `agents/` directory.
+The `.agent.md` extension is **mandatory** for real Copilot CLI files (project/user scope) — Copilot CLI does not pick up plain `.md` files in the `agents/` directory. The plugin/APM source file also uses `.agent.md` by convention, since it compiles to Copilot CLI too, but it is not itself a Copilot file.

plugins/kyberforge/skills/agent-author/references/scripts.md

@@ -24,7 +24,7 @@ Do not add additional substitution tokens unless you update both the template fi
 
 ## File placement
 
-The script creates files at paths determined by scope detection (plugin / project / user). Scope is detected from the presence of `plugin.json`, `.claude-plugin/plugin.json`, `.plugin/plugin.json`, or `.github/plugin/plugin.json` in the root directory. If scope detection logic changes, update the `new-agent.sh` usage comment and `SKILL.md` Step 1 scope detection table in the same pass.
+The script creates files at paths determined by scope detection (plugin/APM / project / user). Scope is resolved by walking up from the root directory: a `type:`-bearing `apm.yml` at or above the root marks the package root (plugin/APM scope, single file); an `apm.yml` without a `type:` field is a marketplace-only manifest and is skipped, the walk continues upward. If no such `apm.yml` is found, the root resolving to exactly `$HOME` is user scope; anything else is project scope. If scope detection logic changes, update the `new-agent.sh` usage comment and `SKILL.md` Step 1 scope detection description in the same pass.
 
 ## Error messages