Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Adapt skill-author/skill-audit/agent-author/agent-audit to author/audit APM-native (.apm/) content #89

New Issue
Closed
opened 2026-08-10 17:41:07 +00:00 by Claude · 0 comments
Claude commented 2026-08-10 17:41:07 +00:00
Collaborator
Copy Link

Retargets four kyberforge skills — skill-author, skill-audit, agent-author, agent-audit — so they author/audit APM-native .apm/ content for target packages, now that #88's apm-install/apm-workflow/apm-orchestrate artifacts have landed (merged via PR #91).

This issue does not touch this repo's own plugins. Per ADR-0015 and this repo's CONTEXT.md Plugin glossary entry, this repo's plugin.json/marketplace.json manifests stay hand-authored, unconverted, until #90 executes. #89 only changes where the four skills above point when authoring/auditing a target package — which, until #90 lands, is never this repo's own plugins.

Scope

In scope:

  • skill-author — authors into .apm/skills/<name>/ instead of plugins/<name>/skills/<name>/.
  • skill-audit — validates .apm/skills/ content; one prose change (see below).
  • agent-author — plugin scope only: authors a single vendor-neutral .apm/agents/<name>.agent.md instead of a Claude Code .md + Copilot .agent.md pair. Project scope (.claude/agents/ + .github/agents/) and user scope (~/.claude/agents/ + ~/.copilot/agents/) are unaffected — both keep today's dual-file pair model per ADR-0005/ADR-0008, unsuperseded outside plugin scope.
  • agent-audit — plugin-scope validation restructured to match (see below). Project/user scope unaffected.
  • forge.md Step 4 (plugin-version-bump detection) — narrow fix only: detection swaps from plugin.json to apm.yml, handoff swaps from plugin-author to apm-workflow. No other change to forge.md's routing/grilling logic.

Explicitly out of scope:

  • plugin-author/marketplace-author — fully superseded, deleted as part of #90 (see #90).
  • forge's Step 1–3 (grill/classify/route) — untouched.
  • Converting this repo's own plugins to .apm/ — that's #90.
  • ADR-0010 (agent sources relocated outside agents/) and ADR-0014 (Vale prefilter path regexes) — both flagged by ADR-0015 as needing revisiting, both confirmed during grilling to be #90's job, not #89's: neither concerns content authored for a target package, only this repo's own plugin layout, which doesn't change under #89.

Design decisions (resolved via grilling, 2026-08-11)

  • Detection: walk up from the destination path to the nearest ancestor apm.yml that declares a type: field (instructions/skill/hybrid/prompts) — that directory is the package root, and .apm/skills/<name>/ (or .apm/agents/<name>.agent.md) is written relative to that root. A type:-less apm.yml doesn't count as a match: per APM's monorepo-hybrid shape (docs/research/docs/microsoft-apm/monorepo-and-repo-shapes.md), a repo-root apm.yml carrying only a marketplace: block (listing sibling packages by local path, e.g. ./packages/plugin-a) is a marketplace listing, not a package — it has no .apm/ tree of its own. Walking past it to find a real package-level apm.yml (or falling through to the "missing, scaffold first" precondition below when none exists) prevents a not-yet-scaffolded package in a monorepo from being misattributed to the repo root. Full switch, no dual-mode/fallback to plugin.json detection — #90 is the immediate next step, so no transitional dual-mode logic is built for a window that closes almost immediately.
  • apm.yml scaffolding is not skill-author/agent-author's job. If no ancestor directory has a type:-bearing apm.yml (per Detection above), stop and point the user to apm-workflow/apm-orchestrate to scaffold the package first (apm plugin init, run from inside the intended package directory — e.g. packages/<name>/ in a monorepo, not the repo root). Clean responsibility line: apm-workflow owns package-shape decisions (type:, targets:, compilation:); the author skills only author into an already-scaffolded package.
  • apm.yml's includes: list, if not auto, is skill-author/agent-author's job to update — append the new primitive's path themselves after authoring it, relative to the package root resolved above. Unlike scaffolding, this is a mechanical one-line fixup on a file already known to exist, not a package-shape decision — same spirit as skill-author already owning its own SKILL.md version bump.
  • Agent primitive tools: field and all Claude-only fields (isolation, maxTurns, effort, memory, permissionMode) are omitted entirely from plugin-scope .apm/agents/<name>.agent.md — only name/description/model/body. Root cause: APM's agent primitive has no per-target compile integrator (confirmed via APM source) — apm compile verbatim-copies the whole frontmatter to both Claude Code and Copilot CLI, and their tools: vocabularies are incompatible (space-separated string vs. alias list), so a value correct for one harness is wrong for the other. Omitting is the only option that never ships a wrong value to a real harness. Tracked in ADR-0016 (new), which partially supersedes ADR-0005 and ADR-0008's plugin-scope clauses — project/user scope keeps the dual-file model those ADRs already describe, unchanged.
  • agent-audit restructures for plugin scope: drops the ### Pair consistency dimension (nothing to pair — one file); repurposes ### Provider safety from a CC-vs-Copilot field-leakage check into a vendor-neutral-field allowlist check (FAIL on any field beyond name/description/model); adds a new SUGGESTION finding when an agent's description/body implies a tool restriction or Claude-only behavior the frontmatter can no longer express — visibility into the ADR-0016 limitation without pretending the schema can do something it can't. references/field-inventory.md's mechanism (external, source_keys-tracked reference file — ADR-0009) is unchanged; its content gains a plugin-scope allowlist shape alongside the existing project/user-scope two-blocklist shape. Project/user-scope agent-audit behavior is otherwise unchanged.
  • skill-audit change is a single prose edit: the File structure dimension's cross-plugin path check (currently flags plugins/<plugin>/skills/<other-skill>/-shaped references) gets a second recognized shape, .apm/skills/<other-skill>/. No script changes — validate.sh/validate-provenance.sh have no path assumptions to update.

Research

plugins/kyberforge/docs/research/docs/microsoft-apm/ — all five APM primitive schemas documented (skills, agents, prompts, instructions, hooks), including source-code-verified per-target compile behavior, plus monorepo-and-repo-shapes.md (package-vs-marketplace apm.yml shapes, used above to fix the Detection design decision against a monorepo layout).

Depends on #88 (merged).

Retargets four `kyberforge` skills — `skill-author`, `skill-audit`, `agent-author`, `agent-audit` — so they author/audit APM-native `.apm/` content for target packages, now that #88's `apm-install`/`apm-workflow`/`apm-orchestrate` artifacts have landed (merged via PR #91). **This issue does not touch this repo's own plugins.** Per ADR-0015 and this repo's `CONTEXT.md` Plugin glossary entry, this repo's `plugin.json`/`marketplace.json` manifests stay hand-authored, unconverted, until #90 executes. #89 only changes where the four skills above point *when authoring/auditing a target package* — which, until #90 lands, is never this repo's own plugins. ## Scope **In scope:** - `skill-author` — authors into `.apm/skills/<name>/` instead of `plugins/<name>/skills/<name>/`. - `skill-audit` — validates `.apm/skills/` content; one prose change (see below). - `agent-author` — **plugin scope only**: authors a single vendor-neutral `.apm/agents/<name>.agent.md` instead of a Claude Code `.md` + Copilot `.agent.md` pair. **Project scope** (`.claude/agents/` + `.github/agents/`) and **user scope** (`~/.claude/agents/` + `~/.copilot/agents/`) are unaffected — both keep today's dual-file pair model per ADR-0005/ADR-0008, unsuperseded outside plugin scope. - `agent-audit` — plugin-scope validation restructured to match (see below). Project/user scope unaffected. - `forge.md` Step 4 (plugin-version-bump detection) — narrow fix only: detection swaps from `plugin.json` to `apm.yml`, handoff swaps from `plugin-author` to `apm-workflow`. No other change to `forge.md`'s routing/grilling logic. **Explicitly out of scope:** - `plugin-author`/`marketplace-author` — fully superseded, **deleted** as part of #90 (see #90). - `forge`'s Step 1–3 (grill/classify/route) — untouched. - Converting this repo's own plugins to `.apm/` — that's #90. - ADR-0010 (agent sources relocated outside `agents/`) and ADR-0014 (Vale prefilter path regexes) — both flagged by ADR-0015 as needing revisiting, both confirmed during grilling to be **#90's job, not #89's**: neither concerns content authored *for* a target package, only this repo's own plugin layout, which doesn't change under #89. ## Design decisions (resolved via grilling, 2026-08-11) - **Detection**: walk up from the destination path to the nearest ancestor `apm.yml` that declares a `type:` field (`instructions`/`skill`/`hybrid`/`prompts`) — that directory is the package root, and `.apm/skills/<name>/` (or `.apm/agents/<name>.agent.md`) is written relative to *that* root. A `type:`-less `apm.yml` doesn't count as a match: per APM's monorepo-hybrid shape (`docs/research/docs/microsoft-apm/monorepo-and-repo-shapes.md`), a repo-root `apm.yml` carrying only a `marketplace:` block (listing sibling packages by local path, e.g. `./packages/plugin-a`) is a marketplace listing, not a package — it has no `.apm/` tree of its own. Walking past it to find a real package-level `apm.yml` (or falling through to the "missing, scaffold first" precondition below when none exists) prevents a not-yet-scaffolded package in a monorepo from being misattributed to the repo root. Full switch, no dual-mode/fallback to `plugin.json` detection — #90 is the immediate next step, so no transitional dual-mode logic is built for a window that closes almost immediately. - **`apm.yml` scaffolding is not `skill-author`/`agent-author`'s job.** If no ancestor directory has a `type:`-bearing `apm.yml` (per Detection above), stop and point the user to `apm-workflow`/`apm-orchestrate` to scaffold the package first (`apm plugin init`, run from inside the intended package directory — e.g. `packages/<name>/` in a monorepo, not the repo root). Clean responsibility line: `apm-workflow` owns package-shape decisions (`type:`, `targets:`, `compilation:`); the author skills only author *into* an already-scaffolded package. - **`apm.yml`'s `includes:` list, if not `auto`, is `skill-author`/`agent-author`'s job to update** — append the new primitive's path themselves after authoring it, relative to the package root resolved above. Unlike scaffolding, this is a mechanical one-line fixup on a file already known to exist, not a package-shape decision — same spirit as `skill-author` already owning its own `SKILL.md` version bump. - **Agent primitive `tools:` field and all Claude-only fields (`isolation`, `maxTurns`, `effort`, `memory`, `permissionMode`) are omitted entirely** from plugin-scope `.apm/agents/<name>.agent.md` — only `name`/`description`/`model`/body. Root cause: APM's agent primitive has no per-target compile integrator (confirmed via APM source) — `apm compile` verbatim-copies the whole frontmatter to both Claude Code and Copilot CLI, and their `tools:` vocabularies are incompatible (space-separated string vs. alias list), so a value correct for one harness is wrong for the other. Omitting is the only option that never ships a wrong value to a real harness. Tracked in **ADR-0016** (new), which partially supersedes ADR-0005 and ADR-0008's plugin-scope clauses — project/user scope keeps the dual-file model those ADRs already describe, unchanged. - **`agent-audit` restructures for plugin scope**: drops the `### Pair consistency` dimension (nothing to pair — one file); repurposes `### Provider safety` from a CC-vs-Copilot field-leakage check into a vendor-neutral-field allowlist check (FAIL on any field beyond `name`/`description`/`model`); adds a new SUGGESTION finding when an agent's description/body implies a tool restriction or Claude-only behavior the frontmatter can no longer express — visibility into the ADR-0016 limitation without pretending the schema can do something it can't. `references/field-inventory.md`'s *mechanism* (external, `source_keys`-tracked reference file — ADR-0009) is unchanged; its *content* gains a plugin-scope allowlist shape alongside the existing project/user-scope two-blocklist shape. Project/user-scope `agent-audit` behavior is otherwise unchanged. - **`skill-audit` change is a single prose edit**: the File structure dimension's cross-plugin path check (currently flags `plugins/<plugin>/skills/<other-skill>/`-shaped references) gets a second recognized shape, `.apm/skills/<other-skill>/`. No script changes — `validate.sh`/`validate-provenance.sh` have no path assumptions to update. ## Research `plugins/kyberforge/docs/research/docs/microsoft-apm/` — all five APM primitive schemas documented (skills, agents, prompts, instructions, hooks), including source-code-verified per-target compile behavior, plus `monorepo-and-repo-shapes.md` (package-vs-marketplace `apm.yml` shapes, used above to fix the Detection design decision against a monorepo layout). Depends on #88 (merged).
Claude added this to the Kyberforge basics milestone 2026-08-10 17:41:07 +00:00
Claude added the Kind/Feature label 2026-08-10 17:41:07 +00:00
Claude changed title from Adapt plugin-author/marketplace-author/skill-author/agent-author/forge to author APM-native (.apm/) content to Adapt skill-author/agent-author to author APM-native (.apm/) content 2026-08-11 12:10:11 +00:00
Claude changed title from Adapt skill-author/agent-author to author APM-native (.apm/) content to Adapt skill-author/skill-audit/agent-author/agent-audit to author/audit APM-native (.apm/) content 2026-08-11 17:15:59 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
No Label Kind/Feature
Milestone
No items
No Milestone Kyberforge basics
Projects
Clear projects
No project
Assignees
Clear assignees
Claude renovate-bot Defame1297
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Defame1297/holocron#89
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?