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.3 KiB

Raw Blame History

source_keys

references/

create.md

The create flow, loaded from SKILL.md Step 1 when no agent file exists at the target path. Covers: prerequisites, the scaffold script and its scope walk-up, what to fill in at every scope, and populating or deleting the package-root sources.md.

improve.md

The improve flow, loaded from SKILL.md Step 1 when a file exists and at least one improvement signal is present. Covers: signal verification, partial-pair recovery, root-cause grouping, generalizing rather than patching, delegation over growth, and the ADR-0020 retrofit rule.

contract.md

The description and body contract, loaded from SKILL.md Step 3 before any description is written or any body restructured. Covers: the three-part description shape, banned description content, boundary-target resolution, the 250/400 length tiers, the body role-instruction pattern, the delegation rule that replaces a body word gate, and the invocation axis.

plugin-scope.md

Field rules and the pre-audit checklist for the single vendor-neutral .apm/agents/<name>.agent.md file. Loaded from SKILL.md Step 2 when the scaffold resolves plugin/APM scope.

project-user-scope.md

Field rules and the pre-audit checklist for the Claude Code .md + Copilot .agent.md pair, including the two distinct Copilot formats. Loaded from SKILL.md Step 2 when the scaffold resolves project or user scope.

deployment-modes.md

Scope hierarchy and precedence, scoped identifiers for plugin subdirectory agents, cache isolation behaviour, and Copilot CLI path conventions. Loaded from SKILL.md Step 2 when precedence, paths or cache isolation matter to the run.

scripts.md

Conventions for the new-agent.sh scaffold script, the templates it copies, and any future script in this skill. Loaded from create.md Step 1 when the script or a template has to change. Covers: the no-interactive-prompts rule, structured output, idempotency, template variables, file placement, error messages, and the no-restated-field-roster rule that tests/new-agent.bats enforces.

sources.md

Research provenance record for this skill. Lists the upstream research sources (claude-code-plugins and github-copilot-plugins research docs) that informed SKILL.md and the reference files. Used by skill-audit to validate the provenance chain.

2.3 KiB Raw Blame History