AGENTS.md Contract

# AGENTS.md – AI Interaction & Execution Guide (Human contributors: see CONTRIBUTING.md & docs/)

This file is intentionally scoped **only** for AI assistants (Cursor, Copilot Chat, PR automation bots).
Humans: read CONTRIBUTING.md and the documents under docs/.

## 1. Authoritative References (Never Reproduce Content Here)

| Topic | Source of Truth |
|-------|-----------------|
| Project architecture | docs/PROJECT_STRUCTURE.md |
| Component patterns | docs/COMPONENT_GUIDELINES.md |
| Performance guidance | docs/PERFORMANCE.md |
| State management approach | docs/STATE_MANAGEMENT.md |
| Styling + design system | docs/STYLING.md |
| Testing strategy | docs/TESTING.md |
| Accessibility notes | docs/ACCESSIBILITY.md |

## 2. Operating Principles (AI Perspective)

- Documentation-first
- Reuse-before-build
- Type safety always (no unvetted any)
- Deterministic, incremental changes
- Explicit assumption logging

## 3. AI Execution Protocol (React Feature Work)

When asked to add/modify UI logic:
1. Locate relevant feature folder (src/features/*) or propose new if justified
2. Read related docs/* referenced above
3. Prefer extending existing component patterns
4. Show proposed file tree + diff plan BEFORE writing code
5. After code: list follow-up validation steps (lint, type check, test)

## 4. Guardrails (Must Enforce)

- Do NOT fabricate file paths, component APIs, or library versions
- Do NOT remove existing accessibility props (aria-*, alt, role) without replacement rationale
- Do NOT introduce global mutable singletons for state—prefer documented patterns
- ALWAYS flag large dependency additions (>1 lib) for human confirmation
- ALWAYS surface potential performance regressions (unmemoized large lists, heavy renders)

## 5. Component Creation Checklist

- Typed props interface exported
- Meaningful name + colocated index.ts re-export (if pattern exists)
- Accessibility reviewed (labels, semantics)
- Story / example or usage snippet considered
- Test file added or explicitly deferred with reason

## 6. When the AI Should Ask or Refuse

Ask for clarification if: feature scope unclear, conflicting patterns, missing target directory.
Refuse if: asked to bypass validation, remove type safety, duplicate existing documented component.

## 7. Post-Change Assistant Report

Return a bullet summary:
- Files touched (concise)
- New dependencies (if any)
- Type/lint status
- Suggested manual QA steps
- Deferred items (tests, docs)

---
Maintained automatically by create-awesome-node-app React template provisioning.
Humans: stop reading—go to CONTRIBUTING.md + docs/.