---
paths: ".claude/agents/**/references/**/*.md, src/claude/agents/**/references/**/*.md"
---

# Agent Reference File Frontmatter Convention

**Purpose:** Prevent reference files under `agents/{agent}/references/` from accidentally registering as standalone peer agents in the Claude Code agent registry.

**Reference:** BA-001 in `docs/Optimization/agents/backend-architect/optimization-recommendations.md`

---

## The Defect

Per Anthropic's sub-agent documentation (https://code.claude.com/docs/en/sub-agents), Claude Code discovers sub-agents at session start by scanning YAML frontmatter of `.md` files in the agent-discoverable tree. **Any `.md` file with a `name:` field in its frontmatter registers as a peer agent**, regardless of where it sits in the directory structure.

This means a file at `.claude/agents/backend-architect/references/treelint-patterns.md` containing:

```yaml
---
name: backend-architect-treelint-patterns
description: Treelint AST-aware code search patterns for backend-architect subagent
---
```

…registers as a standalone peer agent named `backend-architect-treelint-patterns` even though the file's actual role is a **reference file** loaded on-demand by `backend-architect` via `Read()`. The peer-agent registration is unused (no `Task(subagent_type="backend-architect-treelint-patterns", ...)` call sites exist in the framework) but it pollutes the system prompt agent listing and confuses contributors.

---

## The Rule

Reference files under `agents/{agent-name}/references/` directories MUST NOT have a `name:` field in their YAML frontmatter.

### Required Frontmatter Fields

```yaml
---
description: <one-line description of the reference's purpose>
version: "<semver>"
type: reference
---
```

### Optional Frontmatter Fields

- `requires:` — runtime dependencies (e.g., `treelint v0.12.0+`)
- `status:` — lifecycle state (e.g., `LOCKED (ADR-XXX)`, `DRAFT`, `STABLE`)
- `story:` — originating story ID (e.g., `STORY-365`)

### Forbidden Field

- `name:` — including this field registers the file as a peer agent (defect)

The explicit `type: reference` line documents the file's role, making future contributors less likely to add `name:` "to make it discoverable."

---

## Scope

This rule applies to ALL `.md` files matching the pattern:

```
.claude/agents/*/references/*.md
src/claude/agents/*/references/*.md
```

It does NOT apply to:

- `.claude/agents/*.md` — these ARE peer agents and require `name:`
- `.claude/skills/*/SKILL.md` — these use `name:` per skill convention
- `.claude/rules/**/*.md` — these have no frontmatter or paths-only frontmatter

---

## Verification

To audit compliance:

```bash
grep -l "^name:" .claude/agents/*/references/*.md
grep -l "^name:" src/claude/agents/*/references/*.md
```

Both commands MUST return zero matches. Any match is a defect requiring removal of the `name:` field.

---

## HALT Trigger

If a contributor proposes adding `name:` to a reference file frontmatter to "make it loadable," HALT and explain:

- Reference files are loaded via `Read(file_path="...")` from the parent agent's prompt
- `name:` registration is an unrelated mechanism (peer-agent discovery)
- Adding `name:` does NOT make the file easier to load; it ONLY adds noise to the agent registry

If the contributor wants the reference file to BE a peer agent (e.g., callable via `Task()`), they should:
1. Move the file to `.claude/agents/<new-agent-name>.md` (top level of agents/)
2. Add full agent frontmatter (`name`, `description`, `tools`, `model`, etc.)
3. Document the new agent's purpose, scope, and invocation pattern
4. Update the parent agent to invoke the new peer via `Task()` instead of `Read()`

---

## Background

The defect was identified during the backend-architect optimization audit (2026-04-19). Two reference files were affected:

- `.claude/agents/backend-architect/references/treelint-patterns.md` (frontmatter `name: backend-architect-treelint-patterns`)
- `.claude/agents/coverage-analyzer/references/treelint-patterns.md` (frontmatter `name: coverage-analyzer-treelint-patterns`)

Both registered as phantom peer agents with zero call sites. Resolution: BA-001 removed both `name:` fields and added `type: reference`. This rule documents the convention going forward.

---

**Version:** 1.0 | **Created:** 2026-04-19 | **Source:** BA-001 (backend-architect optimization audit)
