Write minimal AGENTS.md and thin CLAUDE.md indexing canonical reference files

[justin808]

Context

The strategic plan calls for AGENTS.md as the index pointing AI agents at canonical reference files (which already wear REFERENCE PATTERN: markers). At launch we don't need the full teaching artifact — just enough to signal "we care about AI tooling" (the 2026 vibe) and to give agents a starting map.

Acceptance criteria

• AGENTS.md at repo root, ~100–200 lines:
  • Brief project orientation (1 paragraph)
  • File layout tree (30 lines) — where TanStack routes, React components, controllers, models, factories, specs, mailers each live
  • Section: "Canonical reference files" — list of files wearing REFERENCE PATTERN: markers with a one-line description of what each demonstrates
  • Section: "Key concepts" — minimal: CSRF + TanStack Query, RSC vs SSR vs client component (mirrors monorepo's existing decision tree, short version)
  • Section: "Testing conventions" — decision table (RSpec for backend, Playwright for cross-stack, Vitest if/when added)
  • Section: "Common commands" — bin/setup, bin/dev, bin/test, bundle exec rspec, pnpm test, with one-line purpose each
  • Closing: link to docs/, link to strategic + implementation planning docs in the monorepo
• CLAUDE.md at repo root, ~5 lines: brief pointer to AGENTS.md as the canonical agent documentation
• No dead links; every REFERENCE PATTERN: file mentioned actually exists
• Density target: match the monorepo's existing AGENTS.md — concrete commands, exact file paths

Files likely touched

• AGENTS.md (new)
• CLAUDE.md (new)

Notes / gotchas

• This is launch-day signal, not the final form. The full pattern-by-pattern teaching artifact is post-launch.
• Avoid over-claiming. If a section would be 2 lines because the kit doesn't have many examples yet, ship the 2 lines.
• Cross-reference the existing REFERENCE PATTERN: markers (4 files at last count) and pick up any new ones added in the marker-expansion issue

Wave + dependencies

• Wave: 3
• Owner mode: parallel-safe
• Blocked by: nothing (but coordinate with the REFERENCE PATTERN marker expansion issue so the file list is current)
• Blocks: nothing

---

Part of the 2026-06-03 HN launch — see internal/planning/3357-react-on-rails-starter-launch.md.