Files

Defame1297 311e7cd22c fix(kyberforge): reconcile the authoring rules the ADR-0020 trim left disagreeing

Six defects, each one a place where two files that an author reads in the same
sitting told them different things — or where the trim dropped a rule and nothing
noticed because no gate covers prose.

**"Use proactively" contradicted itself across the pair.** All three agent
templates said to add it where the runtime should delegate unprompted, while
`agent-audit`'s `KyberforgeCopilot.ProactivePhrase` rule grades it a hard FAIL in
any `*.agent.md` — which is the Copilot half of every project/user pair *and* the
vendor-neutral plugin-scope file, since that compiles to a real Copilot agent
downstream. Following the template produced a file the repo's own gate rejects.
The phrase is now permitted in exactly one place, the Claude Code `.md`, and
`references/contract.md` carries the per-file table plus the consequence authors
ask about next: a pair whose CC half has it and whose Copilot half does not is
correct, because `agent-audit` checks that both halves describe the same job, not
that they match word for word.

**The output-schema rule contradicted itself inside one file.** `contract.md`
said any content only one branch reaches moves to `references/`, and then offered
an "Output format template" body pattern with no qualification. Stated once now,
so it is not re-litigated: an output schema stays in the body only when every flow
produces it and it is roughly 50 words or less. No third option.

**Gotchas tiers disagreed with the script.** `validate.sh` emits the entry count
through `suggest()` and exits 0, while `skill-author` and `skill-audit` both
called more than five entries a FAIL. Whether a given gotcha earns its place is
judgment, so the prose moves to the script's tier rather than the reverse. The
paraphrase rule stays a FAIL and is explicitly marked as the auditor's call — no
script detects it.

**The dispatch exemplar was cited at the wrong number.** `apm-workflow`'s body is
421 words; 554 is its whole-file count. Both `contract.md` and `body-discipline.md`
cited 554 while describing a body budget, so an author calibrating against the
exemplar overshot by ~30% — the exact whole-file/body-only conflation those two
sections exist to warn against, reproduced inside the warning.

**"Error handling" came back as a required body element.** It was one of four and
is the one that gets dropped, and dropping it is not neutral: an agent handed
malformed input with no instruction invents a recovery, and a subagent's invented
recovery is invisible to its caller until the output is wrong. Restored in
`agent-audit`'s rubric as a SUGGESTION, in `agent-author`'s contract and both
scope checklists as a required element, and as an `## Errors` section in all three
templates.

**`skill-author` Step 4 gains the one check the audit misses.** An empty body
reports `PASS SKILL.md body word count 0` — a word gate cannot tell "concise"
from "absent". Step 4 now hand-checks for a non-empty section, and its commit
verification is conditioned on actually being inside a git worktree, which a skill
under `~/.claude/skills/` is not.

Also here: absolute repo paths removed from `skill-author`'s SKILL.md and
contract.md in favour of naming the skill (`zoom-out`'s description is quoted
inline instead of pointed at), the boundary-target universe documented to match
the resolver, a two-hops-from-SKILL.md limit on reference chains, and
`new-agent.sh`'s next-steps output naming the description budget and the
deliberate absence of an agent body gate.

Refs: ADR-0020

2026-08-16 16:40:51 +00:00

assets/vale

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

2026-08-14 21:13:13 +00:00

references

fix(kyberforge): reconcile the authoring rules the ADR-0020 trim left disagreeing

2026-08-16 16:40:51 +00:00

scripts

fix(kyberforge): close the vacuous-pass paths in the ADR-0020 gate scripts

2026-08-16 16:39:29 +00:00

README.md

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

2026-08-14 21:13:13 +00:00

SKILL.md

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

2026-08-14 21:13:13 +00:00

README.md

agent-audit

Audits an agent definition for correctness and quality against the Claude Code and Copilot agent references and the house context-budget contract (ADR-0020) — a single vendor-neutral file at plugin/APM scope, or a Claude Code and Copilot file pair at project/user scope.

What it does

Runs scripts/validate.sh and scripts/validate-provenance.sh for structural and provenance checks, plus scripts/vale-wrap.sh — a Vale prefilter that deterministically flags non-imperative description openers, composition and architecture notes, vague wording, padding phrases, "There is/are" sentence openers, and CC-specific "Use proactively" phrasing in a Copilot or vendor-neutral description
Reads the agent file, and its counterpart when one exists, then loads the contract for its scope
Applies qualitative checks across description, body, delegation and comment discipline, loading one rubric from references/ per group
Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix — and a result block with handoff to agent-author

Two things follow from ADR-0020 and are easy to get backwards. Agents take the same description gates a skill takes — 250 characters SUGGESTION, 400 FAIL, since a name + description is preloaded into every session either way — and no body word gate at all, because an agent body becomes the system prompt of a fresh context rather than competing with the caller's live conversation. Body length is judged through the delegation check instead: an agent body that restates a procedure owned by a skill it can invoke is a FAIL, because a plugin-scope agent has no sibling references/ directory to disclose to and can only delegate.

At plugin/APM scope the audit accepts the single .apm/agents/<name>.agent.md file — there is no counterpart, and pair consistency does not apply. validate.sh hard-FAILs any frontmatter field outside the vendor-neutral allowlist, since apm compile copies frontmatter verbatim to both harnesses and an unsafe field cannot be silently dropped for just one of them. The allowlist lives in the apm-agent-allowlist section of references/field-inventory.md, is read from there as data by the script, and is deliberately not restated anywhere else in this skill (ADR-0009).

At project/user scope the audit accepts either file in a CC .md / Copilot .agent.md pair, derives the counterpart automatically, and validates both, including the field-leakage checks in each direction.

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/CompositionNote.yml`	Flags composition and architecture notes in a description ("cross-cutting", "entry point", "composes", "rather than duplicating") that belong in README.md
`assets/vale/styles/Kyberforge/DescriptionOpener.yml`	Flags descriptions opening with "This..." 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`	Rubric for the description dimension — three-part shape, the 250/400-character budget, the hand-invoked contract, and the internal-mechanics FAIL
`references/body-and-delegation.md`	Rubric for the body, delegation and comment-discipline dimensions — the delegation FAIL and why agents take no body word gate
`references/scope-plugin-apm.md`	Scope contract for a single vendor-neutral APM agent file — allowlist, dimension routing, and the dimensions that do not apply
`references/scope-project-user.md`	Scope contract for a CC / Copilot pair — counterpart derivation, provider field rules, pair consistency
`references/validation-scripts.md`	Loaded only when a Step 1 script fails or cannot run — scope-detection walk-up, manual fallback checks, known script failures
`references/field-inventory.md`	Authoritative field lists read as data by `validate.sh`: valid CC and Copilot agent fields, and the vendor-neutral plugin/APM-scope allowlist
`references/sources.md`	Research provenance for skill content
`scripts/README.md`	Directory documentation for scripts/
`scripts/validate.sh`	Structural validator — required fields, name format, placeholder detection, the ADR-0020 description budget, and the field rules for the detected scope
`scripts/validate-provenance.sh`	Provenance chain validation against `sources.md` at the package root (plugin/APM scope only)
`scripts/vale-wrap.sh`	Drop-in `vale` wrapper that works around a frontmatter-description NLP scope limitation
`tests/README.md`	(source-only) Bats test dependency and run instructions
`tests/validate.bats`	(source-only) Bats tests for validate.sh
`tests/validate-provenance.bats`	(source-only) Bats tests for validate-provenance.sh

Rows marked (source-only) exist in the authoring source (.apm/skills/agent-audit/) but are not present in an installed plugin: scripts/sync-plugin-content.sh strips <category>/<name>/tests when it generates the flat mirror, because these are dev-time fixtures no plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.