# Agent matrix

What agentify-project knows about each agent. Deliberately not a pre-researched database: only the
Claude row ships verified. Any other agent's facts are researched **at runtime** against that
agent's current official docs, only when the agent is detected (or named by the user) and a
selected area needs its specifics. Confirm research findings with the user before use;
inconclusive research means ask — never guess. Persist recipes that matter to teammates in the
project's onboarding doc.

## Columns

| Column | Content |
| --- | --- |
| Agent | Name |
| Detection traces | Files/dirs that indicate the agent is used in this repo |
| Entry file(s) | e.g. CLAUDE.md, GEMINI.md, `.github/copilot-instructions.md` |
| Include syntax | The pointer mechanism, or "none → duplicate content" |
| Project skills dir | e.g. `.claude/skills/`; or "reads `.agents/skills` natively → no link" |
| Gitignore entries | Agent-specific artifact dirs/files worth ignoring |

## Verified rows

| Agent | Detection traces | Entry file(s) | Include syntax | Project skills dir | Gitignore entries |
| --- | --- | --- | --- | --- | --- |
| Claude Code | `CLAUDE.md`, `.claude/` | `CLAUDE.md` (reads it, **not** AGENTS.md) | `@AGENTS.md` import; Claude-specific lines may follow it | `.claude/skills/` | `.claude/plans/**`, `.claude/worktrees/**`, `.claude/settings.local.json`, `.claude/__pycache__`, `CLAUDE.local.md` |

Claude notes (verified against the official memory docs, 2026-08):

- `@` imports load at launch — recursive, max 4 hops, relative to the containing file — and do
  **not** reduce context; hence AGENTS.md references docs with plain links, never imports. Only
  `@`-prefixed paths import; backticked paths do not.
- Windows symlinks need admin/Developer Mode, so the `@AGENTS.md` import beats a symlink as the
  default CLAUDE.md pointer.
- `.claude/rules/` (path-scoped via `paths:` frontmatter) and nested CLAUDE.md files are
  Claude-specific progressive disclosure — rules content is candidate material for governing docs.

## Detection traces to scan for

Well-known traces of agents commonly met — indicative starting points, not a research checklist:

| Agent | Traces |
| --- | --- |
| GitHub Copilot | `.github/copilot-instructions.md` |
| Cursor | `.cursorrules`, `.cursor/` |
| Gemini CLI | `GEMINI.md`, `.gemini/` |
| Windsurf | `.windsurfrules`, `.windsurf/` |
| Cline | `.clinerules` |
| OpenCode | `opencode.json`, `.opencode/` |

Codex, Kimi Code, Amp and others may leave no unique project trace (several agents read the
neutral AGENTS.md natively); when the user names one, research it like any detected agent.
AGENTS.md itself is agent-neutral — never treat it as a trace.

# Target structure

The converged end state agentify-project measures against and converges toward. The audit detects
each area's state; the menu offers the gaps.

## 1. AGENTS.md — canonical lean index

At repo root (plural, per the agents.md convention). Maximally lean — only the irreducible
minimum: project one-liner, universal build/test/run commands, hard structural constraints
(layout, module boundaries), the linked docs index, and the planning-dir convention.
Keep-vs-extract test per block: *part of that minimum?* Everything else — even generic categories
nearly every session reads (testing, conventions, architecture, …) — gets its own governing doc:
often-loaded linked docs are fine, a fat entry file is not. Reference docs as **plain markdown
links with a one-line "read when…" hook each**. Guiding reference for leanness:
https://www.aihero.dev/a-complete-guide-to-agents-md

Never reference docs with `@import` syntax: some agents load `@` imports at launch, recursively,
which would silently defeat progressive disclosure (see the Claude row in
[agent-matrix.md](agent-matrix.md)). Only `@`-prefixed paths are imports — plain paths and
markdown links never import; to mention an `@path` literally, wrap it in backticks.

## 2. CLAUDE.md — pointer

Contains `@AGENTS.md`. Mandatory, not transitional, and never detection-gated (Claude carve-out):
Claude Code reads CLAUDE.md, **not** AGENTS.md, and its official docs recommend exactly this
pointer. Genuinely Claude-only instructions may legitimately stay below the import (official
pattern) — preserve them there instead of force-moving. A CLAUDE.md→AGENTS.md symlink also works
but needs Developer Mode on Windows and forbids Claude-specific additions, so the import is the
default.

## 3. Other agents' entry files — detect and convert only

GEMINI.md, `.github/copilot-instructions.md`, `.cursorrules`, `.cursor/rules`, …: convert files
already present in the repo into pointers to AGENTS.md using that agent's include syntax, or
duplicated content where includes are unsupported (per matrix). Never scaffold an entry file for
an agent with no traces in the repo.

## 4. Governing docs

New agent-facing docs default to `.agents/docs/`; the location is always confirmed with the user.
Content-driven — a doc exists only when content exists for it (blocks extracted from entry files,
or relocated later via `/memory-doctor`). During extraction, propose a standard taxonomy as
candidate homes (architecture, conventions, testing, workflow, …) but **never create an empty
stub**. Existing docs elsewhere (`docs/architecture.md`, `CONTRIBUTING.md`, …) are never moved
silently: ask, showing all options — reference in place / consolidate into `.agents/docs/` — with
a recommendation; referencing in place is the usual one, progressive disclosure does not care
about the path.

## 5. Skills

Canonical dirs at `.agents/skills/<name>/`, plus committed **relative symlinks, one per skill**
(per-skill choice; Claude-only skills can coexist):

- `.claude/skills/<name>` → always (Claude carve-out).
- Other agents' project-level skills dirs → only for detected agents, per matrix; agents that
  read `.agents/skills` natively need no link.
- Existing real skill dirs under `.claude/skills/` move to `.agents/skills/` and are replaced by
  symlinks. Symlinks pointing **outside** the repo (personal installs, e.g. into `~/.agents`) are
  left alone and merely reported.

The Windows symlink caveat is documented once, in the onboarding doc (§8).

## 6. .gitignore

Agent-neutral baseline (`.agents/plans/**`) plus per-agent artifact entries from the matrix —
Claude's always (carve-out), other agents' only when detected. Always presented as a diff for
approval.

## 7. Planning directory

`.agents/plans/`, gitignored, with AGENTS.md stating the convention so every teammate's agent
saves plans to the same place. Converged = gitignore entry + AGENTS.md convention line, **not**
directory existence: an empty gitignored dir never reaches teammates' clones, so create the dir
opportunistically when missing.

## 8. Team onboarding doc

In the governing-docs dir: the layout explained; hookup recipes for the agents wired so far
(accumulated from the skill's runtime research); a generic recipe for any other agent — point it
at AGENTS.md via its entry-file mechanism, or re-run `/agentify-project` to research and wire it —
which keeps detect-only from becoming a chicken-and-egg trap for agents with no repo traces yet;
and the Windows symlink caveat (git `core.symlinks` + Developer Mode).

## 9. README pointer

A two-line section in README.md linking to the onboarding/layout doc, so humans who never open
hidden dirs can discover the structure.

## Claude-only variant

A team may deliberately stay Claude-only; the selected areas then apply within that layout:
CLAUDE.md stays the canonical index (same slimming rules and plain-link references), the skills
area is not applicable (real dirs stay under `.claude/skills/`), the planning dir defaults to
`.claude/plans/`, and doc locations are confirmed with the user with a Claude-conventional
default (e.g. `docs/` or `.claude/docs/`).