# AGENTS.md

**Next.js Initialization**: When starting work on a Next.js project, automatically
call the `init` tool from the next-devtools-mcp server FIRST. This establishes
proper context and ensures all Next.js queries use official documentation.

## Working Style

- Briefly explain your plan before making significant changes.
- State assumptions and uncertainties clearly.
- Keep responses concise and focused.
- Do not invent missing details — ask or flag gaps instead.

---

## Scope & Change Management

- Make the smallest viable change to solve the task.
- Do not refactor unrelated code.
- Do not rename, move, or restructure files unless necessary.
- Prefer modifying existing files over creating new ones.

- Follow existing patterns in the codebase.
- Consistency is more important than introducing new abstractions.

---

## Validation & Verification

- After making changes:
  - Run linting
  - Run type checks (if applicable)

- If you cannot run validation:
  - Clearly state what was not verified
  - Explain potential risks

- Always summarize:
  - What was changed
  - Which checks were run
  - Remaining uncertainties

---

## Dependencies & Safety

- Do not add new dependencies unless absolutely necessary.
- If adding a dependency:
  - Justify why it is needed
  - Prefer existing solutions in the repo

- Never expose or modify secrets (.env, API keys).
- Avoid destructive operations unless explicitly required.

---

## UI / Component Usage (CRITICAL)

- Always prefer existing UI components over writing custom markup.
- Treat the component library as the default UI layer.

- Before creating new UI:
  - Search for existing components (e.g. Button, Card, Modal, Input, Link)
  - Reuse patterns from existing pages

- Never implement common UI primitives (buttons, cards, layout elements) from scratch if a project component exists.

- If an existing component is close but not perfect:
  - Extend it via props
  - Do NOT copy-paste or fork component code

- Only create a new component if:
  - No suitable component exists
  - AND extension is not feasible

- Avoid inline styles unless absolutely necessary.
- Follow the existing design system and styling conventions.

- When introducing new UI:
  - Explain why existing components were not sufficient

---

## Component Discovery

- Always check these locations first:
  - src/components/ui/
  - src/components/

- Look at similar screens/pages before implementing new UI.

---

## Code Style & Conventions

- Follow existing formatting and linting rules.
- Prefer existing utilities and helpers over writing new ones.
- Keep functions small and focused.
- Avoid over-engineering.

---

## Completion Criteria

A task is only complete if:

- The solution works logically
- It follows existing patterns
- It reuses components where possible
- It has been validated (or validation gaps are clearly stated)
- Changes are minimal and scoped