diff --git a/AGENTS.md b/AGENTS.md index 8209bcd..5a4810b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,6 +41,8 @@ Fall back to raw shell only when no skill covers it. - Install the `vale` binary — required by the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks. Their `files:` patterns are `.apm/`-scoped: `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` and `^plugins/[^/]+/\.apm/agents/[^/]+\.agent\.md$`. Only the authoring source triggers them — a `SKILL.md` in the generated mirror matches neither pattern, so prose findings surface only when you edit the file you are supposed to be editing. Without the binary the hooks fail with a bare "command not found" and no install pointer. `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or see https://vale.sh/docs/vale-cli/installation/. No `vale sync` needed — the `Kyberforge` styles are committed under `plugins/kyberforge/.apm/skills/{skill-audit,agent-audit}/assets/vale/styles/`, not downloaded packages (see ADR-0014). - `vale` is also a **pre-push** dependency, not only pre-commit. `check-vale-style-sync` runs six glob-coverage probes by invoking `vale --config` — they are the only assertions in it that catch a `.vale.ini` glob typo, the failure mode where every text-level check stays clean while vale lints zero files. Missing `vale` is therefore a hard failure there. The opt-out is `CHECK_VALE_STYLE_SYNC_ALLOW_MISSING_VALE=1`, and it is **not** `SKIP=`: the hook still runs and still asserts everything verifiable from file text, but the six probes do not, and its summary says so explicitly — `Vale style sync check passed (text-level only, vale unavailable): … 0 glob probe(s) verified`. Use it only on a machine that genuinely cannot install `vale`, and read that summary line as "the glob axis was not checked", not as a pass. - Run `bash tests/run-tests.sh` before considering any change done — it runs every `test-*.sh` script in the repo plus the bats suite (`--bats-only` for just bats). First run auto-initializes the bats submodules; no manual `git submodule update` needed. +- A suite that exits 77 because a dependency is missing is reported as SKIPPED, and does **not** fail an ad-hoc run. The pre-push hook invokes the same script as `--strict` (`RUN_TESTS_STRICT=1` is equivalent), where a skip **does** fail the push: at pre-push a skip means one of the dependencies above is absent on this machine, so the gate would otherwise report success having run fewer suites than it appears to. Without vale, for instance, three suites skip (`test-check-vale-style-sync.sh`, `test-vale-hooks-consumer.sh`, `test-vale-wrap.sh`) and the strict failure names each one and what to install. +- `tests/run-bats.sh` derives the set of `.bats` files it expects from `git ls-files`, so a `.bats` file deleted from the worktree but still tracked in the index fails the run rather than silently shrinking the suite. Remove one with `git rm` (or stage the deletion) when the removal is intentional; an untracked new `.bats` file is picked up and needs no ceremony. - Pushing runs 12 repo-defined pre-push hooks, not just the test suite — `run-tests` and `check-manifests`, plus generated-content drift gates (`check-plugin-content-sync`, `check-marketplace-mirror-sync`, `check-vale-style-sync`, `check-scope-walkup-sync`), apm's own gates (`apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`), host validators (`validate-plugins`, `validate-marketplace`, both needing the `claude` CLI), and `check-release-needed`. Run `pre-commit run --hook-stage pre-push --all-files` locally — one command, the whole gate. That command reports **14**, not 12: pre-commit's own `meta` hooks, `check-hooks-apply` and `check-useless-excludes`, declare no `stages:` and so run at every stage including this one. - **Two** pre-push hooks need the network, for one shared reason: root `apm.yml`'s `marketplace.packages[]` contains exactly one remote entry (`mattpocock-skills`, `source: mattpocock/skills`), and resolving it needs a `git ls-remote`. `apm-marketplace-check` resolves every entry and is `always_run`, so it fails with `No cached refs (offline)`. `apm-pack-check-clean` (`apm pack --check-versions --check-clean --dry-run`) re-resolves the same entry and fails with `Error: Git network timeout during ls-remote`. Pinning the entry to an exact version does **not** remove the call — an exact pin still ls-remotes. `--offline` rescues neither. To push without a network, skip both using pre-commit's own mechanism: `SKIP=apm-marketplace-check,apm-pack-check-clean git push`. Skip those two alone — verified under `unshare -rn`, the other ten pre-push hooks pass offline because they are real local checks, and adding one of them to `SKIP` disarms it silently. - Author commits with `git:git-commits` — it validates Conventional Commits (enforced at `commit-msg`) for you. diff --git a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md index e8f8803..77b8a0e 100644 --- a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md +++ b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md @@ -118,8 +118,10 @@ correction) sorted what they document into three buckets: match. - ADR-0016 (a narrower decision discovered while designing issue #89) turned out to gate how issue #90 had to re-author plugin-scope agents: `.apm/agents/*.agent.md` compiles verbatim to - both Claude and Copilot, so those files carry only `name`/`description`/`model`/`source_keys` — - existing dual-file `.md`+`.agent.md` pairs could not be raw-moved, only re-authored. + both Claude and Copilot, so those files carry only the fields in the `apm-agent-allowlist` section + of `plugins/kyberforge/.apm/skills/agent-audit/references/field-inventory.md` (as amended + 2026-08-14: `name`/`description`/`model`/`source_keys`/`disallowedTools`) — existing dual-file + `.md`+`.agent.md` pairs could not be raw-moved, only re-authored. - Two follow-up issues tracked the remaining work: #89 (`skill-author`/`agent-author` routing adaptation — closed, merged in #93) and #90 (the actual repo conversion, which also deleted `plugin-author`/`marketplace-author` — tracked through to merge; treat #90's own state as the diff --git a/docs/adr/0016-apm-agent-primitive-drops-provider-specific-fields.md b/docs/adr/0016-apm-agent-primitive-drops-provider-specific-fields.md index 711bc90..46ce8c8 100644 --- a/docs/adr/0016-apm-agent-primitive-drops-provider-specific-fields.md +++ b/docs/adr/0016-apm-agent-primitive-drops-provider-specific-fields.md @@ -22,13 +22,17 @@ Code and Copilot CLI targets. This is unlike: Because the agent primitive ships the same frontmatter unchanged to both harnesses, two concrete incompatibilities surface: -1. **`tools:`** — Claude Code expects a space-separated tool-name string; Copilot CLI expects a - list drawn from its own alias vocabulary (`execute`/`read`/`edit`/`search`/`agent`/`web`). A - value correct for one harness is wrong for the other. +1. **`tools:`** — Claude Code expects tool names drawn from its own vocabulary, as a + comma-separated string or a YAML list (`agent-definition.md:37`); Copilot CLI expects a list + drawn from a different alias vocabulary (`execute`/`read`/`edit`/`search`/`agent`/`web`). The + incompatibility is the vocabulary, not the punctuation: a value correct for one harness names + tools the other does not have. 2. **Claude-only knobs with no Copilot equivalent** — `isolation`, `maxTurns`, `effort`, `memory`, `permissionMode`. Writing any of these means Copilot's copy carries frontmatter keys it doesn't recognize at all. Whether Copilot's agent loader ignores unknown keys or - errors on them is unconfirmed by research. + errors on them is unconfirmed by research. *(Still unconfirmed as of the 2026-08-14 amendment + below, which admits `disallowedTools` as an explicitly accepted risk rather than by resolving + this question.)* ## Decision @@ -81,25 +85,61 @@ delimited string of its own tool names, Copilot CLI reads it as a list drawn fro alias vocabulary (`execute`/`read`/`edit`/`search`/`agent`/`web`), so one value is wrong on one harness. That reasoning stands, and `tools:` stays out of every plugin-scope agent. -A **denylist** has no such conflict. +A **denylist** has no such conflict. The evidence for that splits three ways, and this amendment +states which part is which rather than asserting the whole as settled. + +**Confirmed — Claude Code honours it for plugin subagents.** `plugins/kyberforge/docs/research/docs/claude-code-plugins/agent-definition.md:39` documents `disallowedTools` as a "Denylist applied before `tools`… Takes precedence over `tools`", and — the part that matters here — it is **not** in that document's plugin-subagent ignore list. Line 99 names exactly three fields plugin agents silently ignore: `hooks`, `mcpServers`, `permissionMode`. -`disallowedTools` is absent from that list, so it is honoured for plugin agents. On the Copilot -side, the same verbatim-copy behaviour that makes `tools:` dangerous makes `disallowedTools` -harmless: an unrecognised frontmatter key is inert, and unlike a wrong `tools:` value it cannot -grant or misroute anything — the worst case is that the fence is absent on that harness, which is -the status quo the decision above already accepted. +`disallowedTools` is absent from that list. Claude Code is also the harness where the fence is +actually wanted, so the field earns its place on this evidence alone. + +**Inferred — the field is very likely inert on Copilot CLI, but by analogy, not by documentation.** +`plugins/kyberforge/docs/research/docs/github-copilot-plugins/troubleshooting.md:50` and `:53` +record Copilot *silently ignoring* two agent frontmatter fields it does not process (`mcp-servers` +and `metadata` outside the cloud runtime) rather than erroring on them. That is a documented +tolerance for *known-but-unprocessed* keys, which is adjacent to, not identical to, tolerance for +an *unknown* key. No stronger evidence exists: a sweep of the vendored Copilot corpus +(`agent-definition.md`, `api-reference.md`, `troubleshooting.md`, `configuration.md`) documents +unknown-key handling nowhere. + +**Unverified — Copilot's loader behaviour on an unrecognised key.** Context item 2 above says this +is unconfirmed by research and that remains true; nothing found since changes it. An earlier +revision of this amendment claimed "an unrecognised frontmatter key is inert" as settled fact and +attributed it to apm's verbatim-copy behaviour. That attribution was a non-sequitur — verbatim copy +describes what *apm* does at compile time and says nothing about what *Copilot* does at load time — +and the claim contradicted this ADR's own Context section. + +**So this is an accepted risk, stated as one.** Blast radius if the inference is wrong and Copilot +errors on the key: the three affected plugin-scope agents fail to load under Copilot CLI. It is +loud, not silent; it is confined to three agents in three plugins; no other primitive and no Claude +Code path is affected; and the remedy is a one-line frontmatter deletion. What the denylist shape +*does* rule out categorically — independent of loader behaviour — is the failure mode that motivated +dropping `tools:` in the first place: a denied name the other harness does not recognise denies +nothing, so a mis-shaped value can never grant or misroute a capability. The risk is a load failure, +never a silent over-grant. That asymmetry is why the same verbatim copy that makes `tools:` +unshippable makes `disallowedTools` worth shipping. So the read-only orchestrator agents regain their write fence: `gitea-orchestrate`, `apm-orchestrate` and `lint-runner` each carry `disallowedTools: Edit, Write, NotebookEdit` plus explicit prose in the body stating the agent does not edit files. `git-orchestrate` is deliberately excluded — it legitimately declared `edit` before the conversion and still needs to write. -Net position: the allowlist stays dropped for the reason originally given; the specific capability -that mattered (preventing a read-only orchestrator from writing) is restored by the one mechanism -that is portable by construction. The consequence below is narrowed accordingly. +**Residual — the fence is partial, and the prose is doing more of the work than the field is.** +`disallowedTools: Edit, Write, NotebookEdit` denies exactly those three tools. It does not deny +`Bash`, and at plugin scope these agents carry no `tools:` and therefore inherit it, so +`bash -c 'echo … > f'` remains unfenced by frontmatter. Only the body prose covers that path. This +is not a regression introduced here — the pre-conversion `tools:` allowlists also granted `Bash`, +so the shell route was open then too — but the ADR should not credit the mechanism with more than +it delivers. Closing it would need a `disallowedTools` entry for `Bash`, which these agents cannot +take because they legitimately shell out. + +Net position: the allowlist stays dropped for the reason originally given, and the denylist is +admitted as the portable-by-construction half of what was lost. It restores a real, Claude-Code- +confirmed write fence against the tool-call path, not a complete write sandbox. The consequence +below is narrowed accordingly. Enforcement follows the decision: `agent-audit`'s plugin-scope validator reads its allowlist as data from the `apm-agent-allowlist` section of @@ -126,7 +166,9 @@ whether a field is safe under verbatim copy in a single vendor-neutral file. lists from `references/field-inventory.md` rather than hardcoding them, with a `source_keys` provenance chain — survives and is reused. Only the *content shape* changes for plugin scope: `field-inventory.md` shifts from two side-by-side CC-only/Copilot-only blocklists to one - vendor-neutral allowlist (`name`/`description`/`model`/`source_keys` — the last for provenance - tracking, validated separately by `validate-provenance.sh` against `sources.md`, not a - provider-specific field) for plugin-scope agents, while - continuing to serve its original two-blocklist role for project/user-scope validation. + vendor-neutral allowlist for plugin-scope agents, while continuing to serve its original + two-blocklist role for project/user-scope validation. That file's `apm-agent-allowlist` section + is the authoritative list and is read as data by `validate.sh`; as amended on 2026-08-14 it holds + `name`/`description`/`model`/`source_keys`/`disallowedTools` — `source_keys` for provenance + tracking, validated separately by `validate-provenance.sh` against `sources.md` rather than being + a provider-specific field, and `disallowedTools` per the amendment above. diff --git a/plugins/kyberforge/.apm/skills/agent-audit/README.md b/plugins/kyberforge/.apm/skills/agent-audit/README.md index 336e1a9..c0ba507 100644 --- a/plugins/kyberforge/.apm/skills/agent-audit/README.md +++ b/plugins/kyberforge/.apm/skills/agent-audit/README.md @@ -7,11 +7,14 @@ plugin/APM scope, or a Claude Code and Copilot file pair at project/user scope. At **plugin/APM scope**, accepts the single `.apm/agents/.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. +vendor-neutral allowlist, since `apm compile` copies frontmatter verbatim to both harnesses and an +unsafe field can't be silently dropped for just one of them. The allowlist itself lives in the +`apm-agent-allowlist` section of `references/field-inventory.md` and is read from there as data — +consult that section rather than any restatement of it, including this one. As of 2026-08-14 it +admits `name`, `description`, `model`, `source_keys`, and `disallowedTools`; `source_keys` is +provenance metadata checked separately by `validate-provenance.sh` against `sources.md`, and +`disallowedTools` is admitted because a denylist survives verbatim copy where the `tools` allowlist +does not (ADR-0016 and its 2026-08-14 amendment). 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` diff --git a/plugins/kyberforge/.apm/skills/agent-audit/scripts/validate.sh b/plugins/kyberforge/.apm/skills/agent-audit/scripts/validate.sh index 6759140..176cbba 100755 --- a/plugins/kyberforge/.apm/skills/agent-audit/scripts/validate.sh +++ b/plugins/kyberforge/.apm/skills/agent-audit/scripts/validate.sh @@ -8,9 +8,11 @@ Usage: validate.sh Validate an agent definition file against the agent definition spec. At plugin/APM scope, is a single vendor-neutral -.apm/agents/.agent.md file (frontmatter allowlist: name, description, -model — no counterpart file). At project or user scope, is -either half of a Claude Code .md / Copilot .agent.md pair. +.apm/agents/.agent.md file with no counterpart. Its frontmatter allowlist +is not restated here: it is read at load time from the apm-agent-allowlist +section of references/field-inventory.md, which is the authoritative list. +At project or user scope, is either half of a Claude Code .md / +Copilot .agent.md pair. Arguments: agent-file Path to the agent file (or either half of a project/user-scope pair). diff --git a/plugins/kyberforge/.apm/skills/agent-author/SKILL.md b/plugins/kyberforge/.apm/skills/agent-author/SKILL.md index fa9b4bd..f43d4f1 100644 --- a/plugins/kyberforge/.apm/skills/agent-author/SKILL.md +++ b/plugins/kyberforge/.apm/skills/agent-author/SKILL.md @@ -29,7 +29,9 @@ metadata: ## Gotchas - At plugin/APM scope, bump the resolved package's `apm.yml` `version` after every change — minor for a new agent, patch for a fix. Consumers compare this version to detect updates; skipping it hides the change. -- At plugin/APM scope, `tools` and all Claude-only fields (`isolation`, `maxTurns`, `effort`, `memory`, `permissionMode`, `disallowedTools`, `skills`, `color`, `initialPrompt`, `background`, `hooks`, `mcpServers`) are omitted entirely, not merely restricted (ADR-0016: `apm compile` copies frontmatter verbatim to both harnesses with no per-target integrator, so a harness-specific value is wrong on at least one). Only project/user scope supports these fields. +- At plugin/APM scope, `tools` and all Claude-only fields (`isolation`, `maxTurns`, `effort`, `memory`, `permissionMode`, `skills`, `color`, `initialPrompt`, `background`, `hooks`, `mcpServers`) are omitted entirely, not merely restricted (ADR-0016: `apm compile` copies frontmatter verbatim to both harnesses with no per-target integrator, so a harness-specific value is wrong on at least one). Only project/user scope supports these fields. +- `disallowedTools` is the one exception, on **shape**, not favouritism. `tools` is an *allowlist* whose vocabulary differs per harness (Claude tool names vs Copilot's `execute`/`read`/`edit`/`search`/`agent`/`web`), so verbatim copy makes one value wrong on one target. A *denylist* cannot fail that way: an unrecognised name denies nothing, so the worst case is a missing fence, never a wrong grant. Claude Code honours it for plugin subagents — `docs/research/docs/claude-code-plugins/agent-definition.md:99` lists the three fields plugin agents ignore (`hooks`, `mcpServers`, `permissionMode`) and this is not one. Write it on every read-only plugin-scope agent (ADR-0016's 2026-08-14 amendment). +- That fence is partial: it denies only the tools it names. It does not deny `Bash`, which a plugin-scope agent with no `tools` inherits, so a shell redirect still writes. Say the agent is read-only in the body too. - An `apm.yml` with no top-level `type:` field is a marketplace-only manifest, not a package root — the walk-up skips it and keeps going. - `AskUserQuestion`, `EnterPlanMode`, `ExitPlanMode`, `ScheduleWakeup`, and `WaitForMcpServers` are never available to any subagent regardless of the `tools` field. Exception: `ExitPlanMode` is available when the parent session runs in `permissionMode: plan`. - Duplicate `name` values in the same scope: Claude Code silently discards one without warning. Always verify uniqueness before shipping. @@ -90,7 +92,7 @@ The script is file-by-file no-op — it skips any file that already exists. ### Step 2 — Fill in the agent file(s) -**At plugin/APM scope**, there is exactly one file: `/.apm/agents/.agent.md`. Frontmatter carries ONLY `name`, `description`, optionally `model`, and optionally `source_keys` (provenance metadata, not a runtime field — see the template) — never `tools` or the other Claude-only fields listed in Gotchas (ADR-0016). Fill in `name`, `description`, `model`, and the system prompt body per the guidance below; the rest of this step's field-by-field guidance (tools, maxTurns, effort, memory, isolation, disallowedTools, skills, color, initialPrompt, background) is project/user scope only. Skip Step 3 and go to Step 4. +**At plugin/APM scope**, there is exactly one file: `/.apm/agents/.agent.md`. Its frontmatter allowlist is the `apm-agent-allowlist` section of `agent-audit`'s `references/field-inventory.md`, read from there as data: `name`, `description`, `model`, `source_keys` (provenance metadata, not a runtime field — see the template), and `disallowedTools` for a read-only agent. Never `tools` or the other Claude-only fields listed in Gotchas (ADR-0016). Fill those in plus the system prompt body per the guidance below; the rest of this step's field-by-field guidance is project/user scope only. Skip Step 3 and go to Step 4. **At project/user scope**, continue below to fill in both provider files — this step covers the Claude Code file (`.md`); Step 3 covers the Copilot file. @@ -106,13 +108,14 @@ Open the scaffolded Claude Code file. Replace every `FILL IN:` placeholder. **Re **`tools`** (project/user scope only — never at plugin/APM scope) — restrict to what the agent actually needs. Omit to inherit all tools. Use `Agent(type1,type2)` to limit which subagent types this agent can spawn; omit `Agent` entirely to prevent spawning. -**Optional fields worth considering (project/user scope only — never at plugin/APM scope):** +**`disallowedTools`** (all scopes, including plugin/APM) — denylist applied before `tools` and taking precedence over it; supports `mcp__`, `mcp____*`, and `mcp__*` globs. `api-reference.md:40` types it `string / list` and `agent-definition.md:71` types it `string[]`, so a YAML list or a delimited string both work; this repo's plugin-scope agents use the comma-separated string (`disallowedTools: Edit, Write, NotebookEdit`) — match that. + +**Optional fields worth considering (project/user scope only — never at plugin/APM scope, with the exception of `model`, which is allowed at every scope):** - `model`: set when this agent needs a different capability tier (`haiku` for fast tasks, `opus` for deep reasoning) - `maxTurns`: set a cap to prevent runaway agents on bounded tasks - `effort`: set to `low` for single-lookup tasks, `high` or above for deep reasoning or multi-file analysis — overrides session effort level; omit to inherit - `memory`: `user`, `project`, or `local` — only when cross-session state is genuinely needed - `isolation: worktree` — only when the agent modifies files and needs an isolated copy -- `disallowedTools`: space-separated denylist applied before `tools`; supports `mcp__*` glob patterns (e.g. `disallowedTools: mcp__filesystem__*`) - `skills`: list of skill names preloaded at agent startup — different from the `source_keys` metadata field - `color`: UI color for the agent tile (`red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`) - `initialPrompt`: auto-submitted as the first turn when this agent activates as the main session thread; only set when this agent is intended for main-thread activation @@ -152,7 +155,7 @@ Skip this step entirely at plugin/APM scope — there is no separate Copilot fil **`source_keys`** — add the same top-level list as the CC file when research sources were used. Omit when no research was used. -**Remove all template documentation comments from the YAML frontmatter after filling in required fields** — these are marked with `` and must be deleted before shipping. +**Delete the `` template comments from the frontmatter**, as in Step 2. The system prompt body should match the Claude Code version — the agent's task definition is the same across providers. @@ -183,37 +186,32 @@ If no research sources are in context, delete `sources.md`. ### Step 5 — Validate and close -Run this checklist before invoking the audit: +Run this checklist before invoking the audit. + +**Every file, at every scope:** +- [ ] `name` present and kebab-case; `description` present +- [ ] System prompt body present and non-empty +- [ ] No `FILL IN:` placeholders and no `` template comments remain **Plugin/APM scope — single file (`.agent.md`):** -- [ ] `name` field present, kebab-case, unique in scope -- [ ] `description` field present and action-first -- [ ] Frontmatter contains ONLY `name`, `description`, and optionally `model` (plus `source_keys` if research-sourced) — no `tools`, `isolation`, `maxTurns`, `effort`, `memory`, `permissionMode`, `disallowedTools`, `skills`, `color`, `initialPrompt`, `background`, `hooks`, or `mcpServers` -- [ ] System prompt body present and non-empty -- [ ] No `FILL IN:` placeholders remain -- [ ] No `` template comments remain in frontmatter +- [ ] `name` unique in scope; `description` action-first +- [ ] Every frontmatter field is in the `apm-agent-allowlist` section of `agent-audit`'s `references/field-inventory.md` — the single source of truth, read as data by `validate.sh`. As of 2026-08-14: `name`, `description`, `model`, `source_keys`, `disallowedTools`. Nothing else — in particular no `tools` +- [ ] A read-only agent carries `disallowedTools` **and** says so in the body **Project/user scope — Claude Code file (`.md`):** -- [ ] `name` field present, kebab-case, unique in scope -- [ ] `description` field present and action-first -- [ ] System prompt body present and non-empty -- [ ] No `FILL IN:` placeholders remain -- [ ] No `` template comments remain in frontmatter +- [ ] `name` unique in scope; `description` action-first **Project/user scope — Copilot CLI file (`.agent.md`):** - [ ] File extension is `.agent.md` (not `.md`) -- [ ] `name` field matches the filename stem (e.g. `name: my-agent` in `my-agent.agent.md`) -- [ ] `description` field present +- [ ] `name` matches the filename stem (e.g. `name: my-agent` in `my-agent.agent.md`) - [ ] No Claude Code-only fields (`maxTurns`, `isolation`, `memory`, `permissionMode`, `effort`, `hooks`, `mcpServers`) -- [ ] System prompt body present and non-empty - [ ] Body does not exceed 30,000 characters -- [ ] No `` template comments remain in frontmatter At plugin/APM scope, apply a **minor bump** to the resolved package's `apm.yml` `version` (single manifest, e.g. `1.0.4` → `1.1.0`). Invoke `kyberforge:agent-audit` on the created file(s) before closing — validates the pair at project/user scope, the single file at plugin/APM scope. -**Commit verification.** Capture `git log --oneline -1` before Step 1 and keep it. Once the audit is clean, run `git add` and `git commit` for the new agent files — do not stop at staging. Then run `git log --oneline -1` again and confirm the hash changed from the one you captured at the start. A non-empty `git diff --stat` is not sufficient proof of completion: staged-but-uncommitted work isn't part of any commit and can be silently lost if the working tree is cleaned up before a commit lands. Only report the agent as done once the hash has actually changed. +**Commit verification.** Once the audit is clean, run `git add` and `git commit` for the new agent files — do not stop at staging. Then confirm `git log --oneline -1` differs from the hash captured before Step 1. A non-empty `git diff --stat` is not proof of completion: staged-but-uncommitted work is part of no commit and can be silently lost if the working tree is cleaned up. Only report the agent as done once the hash has actually changed. ## Improving an existing agent @@ -223,9 +221,7 @@ Confirm the agent files exist and at least one improvement signal is present in If no signals: "This skill applies existing signals to an agent. For a blind review, examine the files manually or run a grill session first." -Verify `kyberforge:agent-audit` is available — it ships with the kyberforge plugin and is co-installed with this skill. If unavailable, stop and tell the user to install the kyberforge plugin before continuing. - -Capture `git log --oneline -1` now, before making any edits — Step 5 needs it to verify a real commit landed. +Verify `kyberforge:agent-audit` is available, as in the create flow's Prerequisites. Capture `git log --oneline -1` now, before making any edits — Step 5 needs it to verify a real commit landed. **Partial state (project/user scope only)** — if one provider file exists but not the other, scaffold the missing one (`bash scripts/new-agent.sh `, file-by-file no-op) then continue. Doesn't apply at plugin/APM scope — single file, no partial-pair state. @@ -248,7 +244,7 @@ Before editing, state which root causes were identified, what evidence supports ### Step 4 — Apply changes -Edit any file the signals point to. Generalize the fix — find the underlying gap, not the specific example that failed. For every sentence you add, ask: "Would the agent get this wrong without it?" A shorter, focused definition consistently outperforms an exhaustive one. For Copilot files, verify no Claude Code-only fields are introduced. For a plugin/APM-scope single file, verify no field beyond `name`, `description`, `model`, and `source_keys` is introduced. +Edit any file the signals point to. Generalize the fix — find the underlying gap, not the specific example that failed. For every sentence you add, ask: "Would the agent get this wrong without it?" A shorter, focused definition consistently outperforms an exhaustive one. For Copilot files, verify no Claude Code-only fields are introduced. For a plugin/APM-scope single file, verify every field is still in the `apm-agent-allowlist` section of `agent-audit`'s `references/field-inventory.md`, and that an existing `disallowedTools` fence was not dropped by the edit. If the edit adds or removes research-sourced content, update `source_keys` in the edited file(s) and the corresponding entry in `sources.md` per Create flow's Step 4. @@ -260,4 +256,4 @@ At plugin/APM scope, apply a **patch bump** to the resolved package's `apm.yml` Invoke `kyberforge:agent-audit` on the edited file(s) to confirm no regressions — the pair at project/user scope, the single file at plugin/APM scope. -**Commit verification.** Capture `git log --oneline -1` at the start of Step 1 and keep it. Once the audit is clean, run `git add` and `git commit` for the changed files — do not stop at staging. Then run `git log --oneline -1` again and confirm the hash changed from the one you captured at the start. A non-empty `git diff --stat` is not sufficient proof of completion: staged-but-uncommitted work isn't part of any commit and can be silently lost if the working tree is cleaned up before a commit lands. Only report the improvement as done once the hash has actually changed. +**Commit verification.** Exactly as in the create flow's Step 5, against the hash captured at Step 1: commit the changed files once the audit is clean, and only report the improvement as done once `git log --oneline -1` shows a different hash. diff --git a/plugins/kyberforge/.apm/skills/agent-author/assets/README.md b/plugins/kyberforge/.apm/skills/agent-author/assets/README.md index fe53c1b..bf24812 100644 --- a/plugins/kyberforge/.apm/skills/agent-author/assets/README.md +++ b/plugins/kyberforge/.apm/skills/agent-author/assets/README.md @@ -6,4 +6,4 @@ Annotated agent definition templates copied by `scripts/new-agent.sh` when scaff - **`claude-code.md`** — Claude Code agent definition template (project/user scope). Includes all supported frontmatter fields (required and optional) with inline guidance comments and `FILL IN:` placeholders. - **`copilot.agent.md.template`** — Copilot CLI agent definition template (CLI format, project/user scope). Excludes cloud/IDE-only fields (`target`, `user-invocable`, `disable-model-invocation`, `mcp-servers`) and Claude Code-only fields. Uses Copilot tool aliases (`execute`, `read`, `edit`, `search`, `agent`, `web`). -- **`apm-agent.md`** — Vendor-neutral APM agent definition template (plugin/APM scope). Only `name`, `description`, optional `model`, and optional `source_keys` (provenance metadata, not a runtime field) in frontmatter — no `tools` and no Claude-only fields, since `apm compile` copies frontmatter verbatim to both the Claude Code and Copilot CLI targets with no per-target integrator (ADR-0016). +- **`apm-agent.md`** — Vendor-neutral APM agent definition template (plugin/APM scope). Frontmatter is limited to the `apm-agent-allowlist` section of `agent-audit`'s `references/field-inventory.md` — the authoritative list, read from there as data by `agent-audit`'s `validate.sh`; this file deliberately does not restate it. No `tools` and no Claude-only knobs, since `apm compile` copies frontmatter verbatim to both the Claude Code and Copilot CLI targets with no per-target integrator; `disallowedTools` is scaffolded as an opt-in comment because a denylist, unlike the `tools` allowlist, survives that copy (ADR-0016 and its 2026-08-14 amendment). diff --git a/plugins/kyberforge/.apm/skills/agent-author/assets/templates/apm-agent.md b/plugins/kyberforge/.apm/skills/agent-author/assets/templates/apm-agent.md index a56d197..5e8bb8c 100644 --- a/plugins/kyberforge/.apm/skills/agent-author/assets/templates/apm-agent.md +++ b/plugins/kyberforge/.apm/skills/agent-author/assets/templates/apm-agent.md @@ -2,18 +2,25 @@ @@ -30,6 +37,16 @@ description: FILL IN: Action-first description of what this agent does and when Optional. Aliases: sonnet, opus, haiku, fable. Or full model ID. Omit to inherit the runtime default on whichever harness compiles this file. --> + + - - +