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