Contributing — AGENTS.md files

DevSnips uses AGENTS.md-style files at three distinct scopes. They are not a precedence hierarchy; each file exists for a different reader doing a different job. This page defines what each one is, who owns it, and what belongs in it.

The three scopes

File	Reader	Scope	Owner
AGENTS.md (repository root)	Agents working on the DevSnips repository	Repo map, routing table into deep docs, safety rules, QA expectations	Maintainers
<template>/AGENTS.md (resource-level)	Agents or developers working with one template	That template's structure, pages, and constraints	Contributors (validated)
devsnips/AGENTS.md (user project)	Agents working with installed resources in a consuming project	Adaptation rules and quality checks for that project	Created by the CLI, then user-owned

1. Repository root AGENTS.md

The AI-agent entry point to the repository. It states the purpose, the repository map, the source-of-truth hierarchy, a routing table that points agents to exactly one deep doc for their task, required agent behavior (inspect real files, never invent paths/counts, minimal changes, regenerate generated files), safety rules, and QA expectations.

What belongs here: navigation and rules of engagement for repository work. What does not: resource-level detail (that lives in agents/resources/), counts (never quoted), or consume-side workflow (that lives in the skill).

2. Resource-level AGENTS.md (templates only)

Every template — in all three technologies — must carry an AGENTS.md at its root. Enforced by scripts/tooling/validators/validate.py (existence + non-empty) and mirrored by the index generator. Components and sections do not carry one.

What it should contain:

• what the template is and how it is organized (pages, sections, shared assets);
• how to run/preview it (toolchain commands for React templates; open preview.html or pages/ for static ones);
• its design-token conventions and theming behavior (light/dark, no-flash handling);
• constraints and intentional choices — what must not be broken during adaptation (e.g. "navigation must remain keyboard operable", "single h1 per page", "off-brand styles are banned by the token spec");
• where the shared code lives (pages/, src/, css/, js/, assets/).

What it should not contain: metadata duplicated from metadata.json, marketing description, or instructions about DevSnips generally.

Note: the CLI installs a template's AGENTS.md alongside its source files, so this file ships with the template into user projects.

3. Project-level devsnips/AGENTS.md

Created by the CLI (init or first add) in a consuming project; never overwritten by the CLI afterward (asserted by cli/test/agents.test.js and cli/test/context.test.js). Users may edit it to add project-specific instructions.

Default content (generated by cli/src/devsnips/agents.js):

• General rules — inspect the project first; preserve its design language; reuse patterns; no unnecessary dependencies; keep UI responsive and accessible.
• Resource adaptation — resources are starting points; inspect README + source; adapt to project conventions; preserve intended functionality; reuse existing tokens/utilities/components.
• Quality checks — responsive, accessibility, keyboard, focus, hover, contrast, typography, spacing, overflow, semantics, no dead code/dependencies.
• Important — config.json is CLI-managed; the file itself must not be auto-modified; project instructions may be appended below.

What goes in AGENTS.md vs metadata vs docs

Kind of information	Home
Per-resource structured facts (type, tags, features, capabilities)	metadata.json
Per-resource usage explanation	README.md
Per-template operational instructions for agents	<template>/AGENTS.md
Per-project adaptation rules	devsnips/AGENTS.md
Repository navigation and modification rules	root AGENTS.md
System explanation and contracts	docs/ (this tree) and agents/resources/

Rules for contributors

• Add an AGENTS.md only where the architecture has one: templates. Do not add READMEs or AGENTS.md files to components/sections beyond the file contract.
• Keep template AGENTS.md non-empty and accurate — an empty file fails validation.
• Never write tooling that rewrites a user's devsnips/AGENTS.md.