fix(kyberforge): resolve second round of PR #91 review findings
Two review passes on PR #91 (correctness + simplification) found the
prior fixup commit (d6fd9b6) left the deprecation notice it added
half-applied, cited a nonexistent ADR, and introduced/compounded a
few duplicate restatements of the same facts across apm-workflow's
skill files and apm-orchestrate's Hard rules.
- plugin-author/SKILL.md cited ADR-0016 (doesn't exist) instead of
ADR-0006 for the version-parity invariant.
- The deprecation banner on plugin-author/marketplace-author wasn't
reflected in their routing `description:` frontmatter, forge's
routing table, either kyberforge README skill table, or CONTEXT.md
— now propagated consistently; routing behavior is unchanged since
issue #90 (repo-wide apm conversion) hasn't landed yet.
- apm-orchestrate's `configure` operation only covered scaffolding a
new package, not editing an existing apm.yml (e.g. removing a
marketplace.packages[] entry, which has no dedicated `apm` CLI verb
and is just a manifest edit). Added `edit-config`, intentionally
ungated — a local file edit isn't the same class of irreversible
action as `apm publish`, and normal review already gates the commit.
- Deduplicated facts restated 3-4x across SKILL.md/references/ADR
boundaries (audit semantics, reserved name prefixes, marketplace-add
direction, registries precondition), and trimmed configure.md's
~55-line apm.yml schema dump — copied near-verbatim from the
research doc — down to a compact key list with a pointer, matching
install.md's existing terse cross-referencing style.
Deliberately left as-is: apm-orchestrate's parallel/sequential
fan-out logic stays inline rather than extracted to a shared
reference, since neither git-orchestrate nor gitea-orchestrate need
it yet — premature extraction for a single caller.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0186ERbyACLRuRxPRnqwpa4m
This commit is contained in:
@@ -14,7 +14,7 @@ apm audit --ci # CI gate: lockfile consistency + drift replay + pol
|
||||
apm audit --file <path> # standalone: scan an arbitrary file
|
||||
```
|
||||
|
||||
`apm audit --ci` runs baseline lockfile checks, install-replay drift detection (does a clean `apm install` reproduce what's on disk), and org policy checks. Exit code `0` on success, `1` on any violation — composes as a normal CI gate step. It covers AI agent configuration integrity, hidden-content scanning, lockfile verification, and policy enforcement — it does not replace general lint/test/security-scan CI steps, it sits alongside them.
|
||||
Exit code `0` on success, `1` on any violation — composes as a normal CI gate step. It does not replace general lint/test/security-scan CI steps, it sits alongside them.
|
||||
|
||||
## Policy checks
|
||||
|
||||
|
||||
@@ -21,73 +21,21 @@ name: my-pkg
|
||||
version: 1.0.0
|
||||
```
|
||||
|
||||
## `apm.yml` — full schema
|
||||
## `apm.yml` — top-level keys
|
||||
|
||||
```yaml
|
||||
name: my-pkg
|
||||
version: 1.0.0
|
||||
description: Code review skills for Python services
|
||||
author: Jane Doe # plain string, or {name, email?, url?} object
|
||||
license: MIT
|
||||
homepage: https://example.com/my-pkg
|
||||
repository: https://github.com/org/my-pkg
|
||||
keywords: [ai, review, python]
|
||||
- `name`, `version` — required (see above)
|
||||
- `description`, `author`, `license`, `homepage`, `repository`, `keywords` — standard package metadata
|
||||
- `type` — `instructions | skill | hybrid | prompts`; constrains `.apm/` contents
|
||||
- `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, or list explicit repo paths
|
||||
- `dependencies`/`devDependencies` — `apm`/`mcp`/`lsp` entries; `devDependencies` share the same shape but are excluded from the shipped artifact
|
||||
- `scripts` — named commands runnable via `apm run <name>`
|
||||
- `compilation` — target/strategy/exclude/placement controls for `apm compile`/`apm pack`
|
||||
- `policy` — e.g. `fetch_failure_default`
|
||||
- `registries` — named registry endpoints for shorthand dependency resolution
|
||||
- `marketplace` — owner + packages list; see `references/marketplace.md` for the full marketplace workflow
|
||||
|
||||
type: skill # instructions | skill | hybrid | prompts — constrains .apm/ contents
|
||||
|
||||
targets: # which harnesses this package compiles to; prefer plural list form — legacy singular `target: copilot,claude` CSV form is still accepted
|
||||
- copilot
|
||||
- claude
|
||||
|
||||
includes: auto # "auto" = publish the authoritative local layout; or list explicit repo paths
|
||||
|
||||
dependencies:
|
||||
apm:
|
||||
- microsoft/apm-sample-package#v1.0.0 # pinned to a tag
|
||||
- github/awesome-copilot/skills/review-and-refactor # single primitive
|
||||
mcp:
|
||||
- microsoft/azure-devops-mcp # MCP server dependency
|
||||
lsp:
|
||||
- name: pyright
|
||||
command: pyright-langserver
|
||||
args: ["--stdio"]
|
||||
extensionToLanguage:
|
||||
".py": python
|
||||
|
||||
devDependencies: # same shape as dependencies, excluded from the shipped artifact
|
||||
apm:
|
||||
- my-org/internal-test-skills
|
||||
|
||||
scripts: # named commands runnable via `apm run <name>`
|
||||
start: "copilot -p 'README.prompt.md'"
|
||||
review: "copilot -p 'code-review.prompt.md'"
|
||||
|
||||
compilation:
|
||||
target: all
|
||||
strategy: distributed
|
||||
exclude:
|
||||
- "apm_modules/**"
|
||||
placement:
|
||||
min_instructions_per_file: 1
|
||||
|
||||
policy:
|
||||
fetch_failure_default: warn
|
||||
|
||||
registries:
|
||||
public-apm:
|
||||
url: https://registry.example.com/api/public-apm
|
||||
default: public-apm
|
||||
|
||||
marketplace: # see references/marketplace.md for the full marketplace workflow
|
||||
owner:
|
||||
name: contoso
|
||||
url: https://github.com/contoso
|
||||
packages:
|
||||
- name: code-review
|
||||
source: contoso/code-review
|
||||
version: "^1.0.0"
|
||||
tags: [review, quality]
|
||||
```
|
||||
See `docs/research/docs/microsoft-apm/configuration.md` for the complete annotated schema.
|
||||
|
||||
## Dependency reference forms
|
||||
|
||||
@@ -95,23 +43,7 @@ marketplace: # see references/marketplace.md for the full market
|
||||
|
||||
## MCP server secrets
|
||||
|
||||
Use `${VAR}` indirection for headers/env vars — never a literal secret value in `apm.yml`:
|
||||
|
||||
```yaml
|
||||
mcp:
|
||||
- name: linear
|
||||
registry: false
|
||||
transport: http
|
||||
url: https://mcp.linear.app/sse
|
||||
headers:
|
||||
Authorization: "Bearer ${LINEAR_TOKEN}"
|
||||
- name: my-internal
|
||||
registry: false
|
||||
transport: stdio
|
||||
command: my-server
|
||||
env:
|
||||
API_TOKEN: "${MY_API_TOKEN}"
|
||||
```
|
||||
`${VAR}` indirection is required for MCP server secrets in `apm.yml` — see SKILL.md Gotchas.
|
||||
|
||||
## Registries (config-level, not `apm.yml`)
|
||||
|
||||
|
||||
@@ -67,5 +67,5 @@ Without this block, the default versioning strategy ties every listed package to
|
||||
|
||||
## Gotchas
|
||||
|
||||
- A package/plugin `name` compiling to the `claude` target must avoid Claude Code's reserved prefixes — `anthropic-*`, `claude-*`, `agent-skills`, `official-claude-plugins` — otherwise the compiled `.claude-plugin/marketplace.json` is rejected by Claude Code's validator. This is a Claude Code platform constraint, independent of how the manifest gets authored.
|
||||
- Removing a package from `marketplace.packages[]` in `apm.yml` and re-packing changes the public/consumed catalog. Whoever/whatever is driving this skill (human or agent) should confirm before proceeding, the same way `apm publish` is treated — see `apm-orchestrate.md`'s "Hard rules" section for the existing precedent on `publish`.
|
||||
- A package/plugin `name` compiling to the `claude` target must avoid Claude Code's reserved name prefixes (see `plugin-author/SKILL.md` Gotchas for the current list) — otherwise the compiled `.claude-plugin/marketplace.json` is rejected by Claude Code's validator. This is a Claude Code platform constraint, independent of how the manifest gets authored.
|
||||
- Removing a package from `marketplace.packages[]` in `apm.yml` and re-packing changes the public/consumed catalog. Confirm with the user in conversation before removing the entry and running `apm pack` — this is a normal `apm.yml` edit (not a distinct apm-orchestrate operation with its own gate), so the confirmation is conversational, the same as any other consequential manifest edit.
|
||||
|
||||
Reference in New Issue
Block a user