Defame1297
5e232503c4
Why: ADR-0015 established that Microsoft APM (apm.yml + .apm/) should replace this repo's hand-authored plugin.json/marketplace.json model, with those files becoming compiled output of `apm pack` instead of files edited by hand via the (now-retired) plugin-author/marketplace-author skills. Issue #90 was the deferred execution of that decision, gated on #88 (apm tooling) and #89 (apm-native agent-author/skill-author routing). Implementation notes: - All six plugins (bin, core, git, gitea, kyberforge, lint) now carry apm.yml + .apm/{skills,agents,hooks} as their authoring source. Skills moved with a plain git mv (content-identical across targets). Agents were re-authored, not moved: per ADR-0016, .apm/agents/*.agent.md compiles verbatim to both Claude and Copilot, so plugin-scope agents now carry only name/description/model/source_keys -- no tools: field, no Claude-only knobs (isolation, maxTurns, effort, memory, permissionMode). - Root apm.yml registers all 7 marketplace packages (6 local plus mattpocock-skills as a remote entry) under versioning: per_package, matching this repo's existing independent-plugin-versioning practice. - .claude-plugin/marketplace.json and every plugin's plugin.json are now apm-pack-compiled output, verified against the prior hand-maintained content: same names/descriptions/versions/licenses/authors, only cosmetic serialization differences (JSON key order, owner email vs. url, Unicode escaping). - plugin-author and marketplace-author are retired now that apm-based authoring fully replaces their job; kyberforge bumped 1.3.1 -> 1.4.0 for that removal, and the root marketplace catalog bumped 0.3.1 -> 0.3.2 to match, per the version-bump convention now documented in apm-workflow's reference docs instead of a dedicated script (apm has no native version-bump automation). - Fixed hardcoded pre-.apm/ path assumptions across .pre-commit-config.yaml, .pre-commit-hooks.yaml, scripts/check-scope-walkup-sync.sh, scripts/sync-vale-styles.sh, scripts/check-vale-style-sync.sh, six plugins' root plugin.json (stale skills/hooks/agents pointer fields that check-manifests.sh validates), and several tests/*.bats and tests/*.sh fixtures -- including a bats REPO_ROOT relative-path depth bug (10 files, one extra .apm/ directory level to walk up) and a vale probe-path isolation regression introduced mid-fix. - Corrected empirically-wrong assumptions surfaced this session in apm-workflow/apm-install's own reference docs: `apm marketplace package add` does not accept local paths (only owner/repo remote shorthand -- local packages are registered by editing apm.yml's marketplace.packages[] directly); `apm compile` is a consumer-side AGENTS.md/CLAUDE.md generator, not the plugin.json producer, and hard-fails on skill/agent-only packages without --clean; `apm plugin init <name>` nests a stray subdirectory when run with a positional name arg from inside a same-named directory; no native Copilot marketplace output profile exists; .mcp.json is merged into the compiled plugin.json content-aware and target-scoped, with no dependencies.mcp entry needed for simple passthrough; pipx is the correct pip fallback on externally-managed Python environments. - Renamed agent-author's copilot.agent.md template asset to copilot.agent.md.template so apm compile's recursive *.agent.md glob stops misparsing the placeholder template as a real agent primitive. Impact: plugin.json and marketplace.json are compiled artifacts from here on -- editing them by hand is no longer the workflow; edit apm.yml/.apm/ and run apm pack. CONTEXT.md's Plugin/Plugin marketplace glossary entries reflect this. ADR-0001 is marked superseded, ADR-0006 moot, and ADR-0010 updated for the new .apm/agents/ path (project/user scope unaffected, per ADR-0016). Full local verification: claude plugin validate --strict on all 6 plugins, apm audit --ci, apm marketplace check, check-manifests.sh, and the full test suite (165/165 bats, 13/13 shell scripts) all pass clean. Fixes: #90 Refs: #88, #89 ADR: 0015 ADR: 0016 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ub96PyaSRD9BHPktotj1pC
58 lines
3.6 KiB
Markdown
58 lines
3.6 KiB
Markdown
# agent-audit
|
|
|
|
Audits an agent definition for correctness and quality — a single vendor-neutral file at
|
|
plugin/APM scope, or a Claude Code and Copilot file pair at project/user scope.
|
|
|
|
## What it does
|
|
|
|
At **plugin/APM scope**, accepts the single `.apm/agents/<name>.agent.md` file — there is no
|
|
counterpart. Structural checks via `validate.sh` hard-`FAIL` any frontmatter field outside the
|
|
vendor-neutral allowlist (`name`, `description`, `model`, `source_keys` — the last for
|
|
provenance tracking, checked separately by `validate-provenance.sh` against `sources.md`; see
|
|
ADR-0016), since `apm compile`
|
|
copies frontmatter verbatim to both harnesses and an unsafe field can't be silently dropped for
|
|
just one of them.
|
|
|
|
At **project/user scope**, accepts either file in a CC `.md` / Copilot `.agent.md` pair, derives
|
|
the counterpart automatically, and validates both. Runs structural checks via `validate.sh`
|
|
(required fields, kebab-case name, no placeholders, no CC-only fields in the Copilot file, no
|
|
Copilot-only fields in the CC file), provenance chain validation via `validate-provenance.sh`
|
|
(checks `source_keys` against `sources.md` at the plugin root — plugin/APM scope only), then
|
|
qualitative checks on description phrasing and system prompt quality. Step 1 also runs a
|
|
Vale-based prose sub-check via `vale-wrap.sh` against both files of the pair, using the
|
|
`Kyberforge` style (both files) and `KyberforgeCopilot` style (Copilot file only) — every alert
|
|
is a `FAIL`, cited by rule ID — falling back to Step 2 judgment when the `vale` binary is
|
|
unavailable or reports `0 files` scanned. Produces a compact findings report in the same format
|
|
as `skill-audit`.
|
|
|
|
## Usage
|
|
|
|
```
|
|
/agent-audit
|
|
```
|
|
|
|
Pass the path to either agent file as the argument.
|
|
|
|
## Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `SKILL.md` | Skill instructions for agents |
|
|
| `assets/vale/.vale.ini` | Vale config: scopes `Kyberforge` to `**/agents/*.md`, `Kyberforge`+`KyberforgeCopilot` to `**/*.agent.md` |
|
|
| `assets/vale/styles/Kyberforge/DescriptionOpener.yml` | Flags descriptions opening with "This skill/agent" instead of an imperative "Use when..." |
|
|
| `assets/vale/styles/Kyberforge/PaddingPhrase.yml` | Flags generic "see references/ for info" pointers instead of specific file references |
|
|
| `assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml` | Flags sentences opening with "There is/are" instead of naming the subject directly |
|
|
| `assets/vale/styles/Kyberforge/VagueWording.yml` | Flags vague capability wording ("helps with", "utilize", "assists with", "used for") in descriptions |
|
|
| `assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml` | Flags CC-specific "Use proactively" phrasing with no effect in Copilot descriptions |
|
|
| `references/README.md` | Directory documentation for references/ |
|
|
| `references/description-quality.md` | Qualitative guide for borderline description findings |
|
|
| `references/field-inventory.md` | Authoritative list of valid CC and Copilot agent fields |
|
|
| `references/sources.md` | Research provenance for skill content |
|
|
| `scripts/README.md` | Directory documentation for scripts/ |
|
|
| `scripts/validate.sh` | Structural validation script for agent file pairs |
|
|
| `scripts/validate-provenance.sh` | Provenance chain validation script for agent pairs against `sources.md` (plugin root) |
|
|
| `scripts/vale-wrap.sh` | Drop-in `vale` wrapper that works around a frontmatter-description NLP scope limitation |
|
|
| `tests/README.md` | Bats test dependency and run instructions |
|
|
| `tests/validate.bats` | Bats tests for validate.sh |
|
|
| `tests/validate-provenance.bats` | Bats tests for validate-provenance.sh |
|