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

5.3 KiB

Raw Blame History

source_keys

claude-code-subagents-docs

context7-github-en-copilot

github-custom-agents-configuration

github-cli-plugin-reference

Project and user scope — the Claude Code / Copilot pair

Two files per agent, written in one pass and kept in step: a Claude Code .md and a Copilot CLI .agent.md. The system prompt body is the same in both — the agent's task does not change with the provider. The frontmatter is not.

Scope	Claude Code	Copilot CLI
Project	`.claude/agents/<name>.md`	`.github/agents/<name>.agent.md`
User	`~/.claude/agents/<name>.md`	`~/.copilot/agents/<name>.agent.md`

Claude Code file

name — lowercase letters and hyphens only, unique within the scope. Claude Code discards a duplicate silently.

description — write it against references/contract.md. It is the primary signal for autonomous delegation.

tools — an allowlist; omit it to inherit every tool from the parent. Use Agent(type1,type2) to restrict which subagent types this agent may spawn, and omit Agent entirely to stop it spawning any. Five tools reach no subagent whatever this field says — AskUserQuestion, EnterPlanMode, ExitPlanMode, ScheduleWakeup and WaitForMcpServers — so listing one buys nothing. The single exception is ExitPlanMode, available when the parent session runs permissionMode: plan.

disallowedTools — a denylist, applied before tools and taking precedence over it. Supports mcp__<server>, mcp__<server>__* and mcp__* globs. Both a YAML list and a delimited string are accepted; this repo writes the comma-separated string form (disallowedTools: Edit, Write, NotebookEdit) — match it.

model — set it when the agent needs a different capability tier (haiku for fast lookups, opus for deep reasoning). Resolution order is CLAUDE_CODE_SUBAGENT_MODEL → the per-invocation parameter → this field → the main session model, so the frontmatter value is a low-priority default rather than a guarantee.

Optional fields worth considering, none of which exist at plugin/APM scope:

maxTurns — cap agentic turns on a bounded task, to stop a runaway
effort — low for a single lookup, high or above for multi-file analysis; 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
skills — skill names preloaded at agent startup; unrelated to the source_keys metadata field
color — the UI tile colour (red, blue, green, yellow, purple, orange, pink, cyan)
background — true forces background execution
initialPrompt — auto-submitted as the first turn when the agent activates as the main session thread; set it only for a main-thread agent, never for a subagent

hooks, mcpServers and permissionMode are honoured at these two scopes and nowhere else — a plugin agent carrying them is ignored silently.

A subdirectory under agents/ does not affect the agent's name at these scopes; it does at plugin scope, which is one reason references/deployment-modes.md recommends keeping agents flat.

Copilot file

Two Copilot formats exist, with different paths and different field sets. Pick one:

CLI format — what the scaffold writes.

Path: .github/agents/<name>.agent.md (project) or ~/.copilot/agents/<name>.agent.md (user)
The .agent.md extension is mandatory: Copilot CLI does not pick up a plain .md file in agents/, and fails silently rather than reporting it
Fields: name (required, must equal the filename stem), description (required), tools (optional)
tools uses Copilot aliases, not Claude tool names: execute (shell), read, edit, search, agent, web; MCP tools as server-name/tool-name or server-name/*

Cloud/IDE format — for Copilot Chat in VS Code or on GitHub.com.

Path: .github/copilot/agents/<name>.md — a plain .md, in a different directory
Adds target (vscode, github-copilot, or omit for both), user-invocable, disable-model-invocation and mcp-servers (processed by the cloud runtime, ignored in VS Code). These four are inert in the CLI format — do not write them there
This is the only format that can express the invocation axis in frontmatter; see the Invocation axis section of references/contract.md

Both formats truncate a body past 30,000 characters silently.

Copilot has no permissionMode, maxTurns, isolation, memory, effort, hooks or mcpServers. Never let those cross over from the Claude Code file.

Before invoking `agent-audit`

Both files:

name present and kebab-case; description written to references/contract.md
System prompt body present, non-empty and equivalent across the pair
Body covers all four required elements: inputs expected, process steps, output format, error handling — what the agent does on malformed, missing or contradictory input
No FILL IN: placeholder and no  template comment left

Copilot file only:

Extension is .agent.md (CLI format), and name matches the filename stem
No Claude Code-only field present
Body under 30,000 characters

Then return to the flow reference you came from.

5.3 KiB Raw Blame History

Project and user scope — the Claude Code / Copilot pair

Claude Code file

Copilot file

Before invoking agent-audit

5.3 KiB

Raw Blame History

Before invoking `agent-audit`