Proposal: ship an AGENTS.md with the boilerplate so agents follow Ignite's conventions

## Summary

Ignite ships no `AGENTS.md`, no `CLAUDE.md`, and no agent-facing conventions of any kind — neither at the repo root nor in `boilerplate/`. I'd like to propose adding them, and I'm volunteering to do the work.

This consolidates three existing asks that haven't had a maintainer reply yet:

- #2969 — MCP support in the CLI (Jun 2025)
- #3036 — UI knowledge / usage patterns for AI (Apr 2026)
- #3027 (discussion) — Agent Skills for Ignite (Feb 2026)

I think all three are downstream of one cheaper thing: **Ignite's conventions aren't written down anywhere an agent reads.** Worth fixing that first, before anything protocol-shaped.

## Why Ignite specifically

An AI coding agent is a fast contributor who has read everything and remembers nothing about *your* project. The failure mode isn't bad code — it's *generic* code: idiomatic in the abstract, wrong for this codebase. It hand-rolls a component instead of running the generator. It writes its own `Text` wrapper instead of using yours. It inlines colors instead of going through `useAppTheme()`.

That is exactly the class of mistake an opinionated boilerplate exists to prevent. Ignite already has strong opinions about where things go, a generator for each of them, and `dependency-cruiser` rules enforcing boundaries — but every one of those opinions currently has to be re-derived by the agent, per project, from scratch, in every session. Writing them down once in `boilerplate/AGENTS.md` means every generated app inherits them, and `AGENTS.md` is read natively by Claude Code, Codex, Copilot, Cursor and others — one file, no per-tool duplication.

## Proposal

Phased, so each phase can be accepted or dropped independently.

**1. `boilerplate/AGENTS.md` + `boilerplate/CLAUDE.md`** — the main one. Ships into every generated app. `CLAUDE.md` is a single `@AGENTS.md` import line, so there's one source and no drift. Must be written so it stays true after `--removeDemo` and after the user renames things.

**2. Root `AGENTS.md`** — a different document for a different audience: people contributing to Ignite itself. `boilerplate/` vs `src/` vs `docs/`, pnpm 10.9.0, `pnpm run test` / `format:write` / `lint` before a PR, how `boilerplate/ignite/templates` relates to the generators. Mostly restates `.github/CONTRIBUTING.md` in the place agents actually look.

**3. Skills + a routing table (later, only if 1 lands).** A skill earns its place when a flow has a control path or cross-cutting state that no single file reveals. Most of the boilerplate doesn't qualify. Plausible candidates: theming/light-dark, the generator system, the EAS build + upgrade path, Maestro. I'd rather ship zero speculative skills than four documentation-shaped ones — a routing table pointing at a skill that doesn't earn its keep teaches the agent to stop trusting the table.

**4. MCP (#2969).** Separate, much heavier axis: a server to maintain, versioned against the CLI. Files get most of the benefit at a fraction of the cost, and are strictly additive. I'd suggest revisiting it after 1–3, not instead of them.

Sketch of what boilerplate/AGENTS.md would cover (~100 lines, not more)

- **What this app is** — Expo + React Native, Ignite-generated; a one-liner the user is meant to replace with their own product description.
- **Layer boundaries as a table** — `app/components` (dumb UI), `app/screens`, `app/navigators`, `app/services/api`, `app/context`, `app/theme`, `app/utils`, `app/config`. Each row says what it holds and what it must never contain. This is the highest-value section: it's the part agents get wrong most often, and it's already true of Ignite — it's just not written down.
- **Reach for the generator first** — `npx ignite-cli generate screen|component|navigator` before hand-rolling, so new files match the conventions the rest of the codebase follows and the templates in `ignite/templates` stay the single source of shape.
- **Reuse before you build** — search `app/components` first. `Text`, `Button`, `Card`, `Screen`, `ListItem`, `TextField`, `Icon`, `Toggle`, `EmptyState`, `AutoImage`, `Header` already exist; an agent that doesn't know that writes an eleventh one.
- **Theming** — go through `useAppTheme()` / `theme/colors` / `spacing`; never inline hex or magic numbers, and remember every color has a dark counterpart.
- **`dependency-cruiser` rules are real constraints**, not advice — `pnpm run depcruise` enforces them.
- **House rules with the reason attached** — a rule with a hedge in it gets interpreted; a rule with a reason attached generalizes to the cases you didn't enumerate.
- **Verification is part of the change** — `pnpm run compile`, `pnpm run lint:check`, `pnpm test` green before anything is called done.

## The honest objection

It's another file in `boilerplate/` that can go stale, and a stale conventions file is worse than none — it actively misleads. My answer is to keep it short and structural (boundaries, generators, verification commands) rather than an inventory of every component prop, so an SDK bump rarely touches it. If it grows past ~150 lines it's turning into docs, and the docs already exist and are better.

Also worth saying plainly: I can't prove ROI with a controlled comparison. This is one team's experience, on a much larger Ignite-derived codebase, and it's not an argument for using agents without review.

## Prior art / where this comes from

Two production React Native apps of ours started from Ignite and grew into a monorepo with a shared package. We added a root `AGENTS.md`, a `CLAUDE.md` pointer, and ten skills routed from a table. The generic-code problem largely went away. I extracted the structure — with a fictional app, so it's copyable rather than proprietary:

- Exemplar repo: https://github.com/lvlrSajjad/agent-ready-monorepo
- Write-up: https://lvlrsajjad.github.io/agent-ready-monorepo/

## What I'm asking

Is this something you'd take? If yes:

1. Do you want phase 1 only (`boilerplate/`), or 1 + 2 (root as well)?
2. Any objection to `AGENTS.md` as the filename with `CLAUDE.md` as a one-line pointer, versus some other arrangement?

Happy to open the PR as soon as you point at a direction — and equally happy to hear "not now", which would at least be an answer for the three threads above.

Start by reading .github/CONTRIBUTING.md, the boilerplate structure, and the generator templates under boilerplate/ignite/templates. Confirm with maintainers whether phase 1 or phases 1–2 are wanted, then define the conventions that remain true after --removeDemo and renaming. Done means the agreed AGENTS.md and CLAUDE.md documents are present and the listed verification commands and boundaries are accurate.

Written by the indexing model from the issue text.