Files

Defame1297 4a5c3c0cff feat(kyberforge): enforce the ADR-0020 context contract for skills and agents

Skill name+description pairs are preloaded into every session, costing
~6,200 tokens across 39 skills before any skill is invoked. The authoring
rules mandated that growth: skill-author:104 and description-quality.md:21
both required padding, while skill-author:102 (the deflating rule) had no
FAIL condition behind it.

Gates (blocking, no baseline file):
- description 250 chars SUGGESTION / 400 FAIL, measured on the folded
  YAML value
- body-only 600 words SUGGESTION / 900 FAIL, independent of the unchanged
  whole-file 2770-word / 500-line spec backstop
- every boundary-clause routing target must resolve to a real skill or
  agent; catches skill-improve, neuledge-context and gitea-labels
- agents take the description gates but deliberately no body gate; a test
  pins that absence

Vale: DescriptionOpener widened to ^This\b, new CompositionNote rule
banning architecture notes from descriptions. 10 hits, 0 false positives.

Kyberforge's own four skills retrofitted: descriptions 3,364 -> 938 chars
(-72%), bodies 8,306 -> 2,487 words (-70%), all via the apm-workflow
dispatch pattern. Fixes the skill-improve dangling route and the
agent-author misroute to manual review.

Also fixes a pre-existing false positive where any line-initial 'read '
was flagged as interactive input, which had already caused two scripts to
be rewritten around it.

Refs: ADR-0020

2026-08-14 21:13:13 +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 / user-invocable, 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