Files

Defame1297 3811f5481b fix(kyberforge): unblock the scaffold and finish the #125 and ADR-0022 edits

Three related half-applied changes from #130, each leaving the corpus in a state its own
documentation contradicts.

Why:
- `assets/templates/SKILL.md` shipped `metadata:` fully commented out, and `new-skill.sh` only
substitutes SKILL_NAME. Every scaffolded skill therefore lacked the `metadata.version` ADR-0022
made mandatory and was blocked at first commit by the very hook this PR added. The commented
example also read `"1.0"` — neither the `0.1.0` new-skill seed nor valid semver.
- `agent-audit/references/scope-project-user.md` still joined `disable-model-invocation` and
`user-invocable` with a slash — #125's defect verbatim — while pointing the reader at the file
this PR had just corrected to say the opposite.
- ADR-0022 required the "when present" bump conditional dropped and `metadata.version` moved into
create.md's required list. It was dropped from SKILL.md but left in README.md, and the field was
edited in place under a heading that still authorises removing it entirely.

Implementation notes:
- The template emits `metadata: version: "0.1.0"` live, captioned as required, with the optional
keys left commented. `new-skill.bats` gains a case asserting a live key and three-part semver, so
this cannot regress.
- `description-quality.md` now asserts only what the vendored Copilot research supports: two fields
with opposite defaults, and the retired `infer` replaced by the pair rather than by either alone.
The unsupported negative it previously stated as fact is gone.
- The `1.0.0` retrofit seed is stated in improve.md and retrofit.md, which the retrofit flow
actually reads — create.md, where it lived, is unreachable from that path. The compression item
moved out of the file-churn checklist, whose preamble excluded the wording-only change it covers.
- Executable git commands in these three skills now carry the ADR-0023 rtk prefix.

Refs: #125, #127
ADR: 0022, 0023
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP

2026-09-09 05:15:23 +00:00

2.9 KiB

Raw Blame History

source_keys

context7-websites-code-claude

claude-code-subagents-docs

context7-github-en-copilot

github-custom-agents-configuration

Project and User Scope Contract

Read this when the agent file is not under .apm/agents/ — a Claude Code .md and Copilot CLI .agent.md pair, at project scope (<repo>/.claude/agents/ and <repo>/.github/agents/) or user scope (~/.claude/agents/ and ~/.copilot/agents/). validate.sh derives the counterpart from whichever half it was handed; audit both.

The pair is a house convention

Neither platform requires a counterpart file. The pair is a kyberforge convention (ADR-0005), so a missing counterpart is a FAIL against this repo's convention and must be labelled that way in the finding, not presented as a platform spec failure.

Dimension routing

validate.sh findings land as follows at these scopes:

Finding	Dimension
a Claude-Code-only field in the Copilot file, a Copilot-only field in the CC file, a tool the runtime withholds from subagents, body over the 30,000-character Copilot limit	Provider safety
counterpart file not found	Pair consistency
everything else — missing or malformed field, name format, empty body, absent frontmatter, description length	Structure

The two field lists are the claude-code-only-fields and copilot-only-fields sections of references/field-inventory.md. Read them from there rather than from memory; validate.sh parses those same sections, so any restatement is a copy that can disagree with the check (ADR-0009).

Field and naming rules that differ by provider

name must match the filename stem in a Copilot CLI .agent.md. Claude Code imposes no such rule, so a CC file whose name differs from its filename is not a finding.
A Copilot cloud/IDE agent — one under .github/copilot/agents/ — may omit name entirely. If it carries one, it still has to be kebab-case.
Use proactively is meaningful in a CC description and steers the runtime to offer the agent unprompted. In a Copilot description it does nothing; KyberforgeCopilot.ProactivePhrase flags it. The Copilot equivalent is disable-model-invocation, which changes the description contract entirely — see references/description-quality.md, Step 0.

Pair consistency

Check that:

Both files exist.
Both system prompt bodies are non-empty (validate.sh covers this; do it by hand only when the script could not run).
The two files describe the same job. Divergent capability claims across the pair mean one half was edited and the other was not, which is the defect this dimension exists to catch.
Descriptions may legitimately differ in shape when the Copilot half is hand-invoked — that is the Step 0 case in references/description-quality.md, not a pair-consistency finding.

Keep pair-consistency in the Step 4 coverage line at these scopes.

2.9 KiB Raw Blame History