rootstrap · amaury901130 · Jun 3, 2026 · Jun 3, 2026 · fernandatoledo · Jun 3, 2026
@@ -1,6 +1,6 @@
 ---
 name: pr-description
-description: Draft a concise pull request description for this React Native Expo template. Use when the user asks to write, generate, update, or prepare a PR description, PR body, pull request summary, or GitHub pull request text from the current branch changes.
+description: Generates a structured PR description from the current branch diff, following the repository's pull request template exactly. Use when the user asks to "write a PR description", "generate a PR description", "create a pull request description", "update the PR description", "prepare a PR body", "draft a pull request summary", or "write GitHub pull request text" from the current branch changes.
 ---
 
 # PR Description

@@ -0,0 +1,83 @@
+---
+name: pr-description
+description: Generates a structured PR description from the current branch diff, following the repository's pull request template exactly. Use when the user asks to "write a PR description", "generate a PR description", "create a pull request description", "update the PR description", "prepare a PR body", "draft a pull request summary", or "write GitHub pull request text" from the current branch changes.
+---
+
+# PR Description
+
+## Purpose
+
+Create a brief, reviewer-friendly PR description from the current branch diff. The output must follow the repository's pull request template exactly, preserving every heading and keeping placeholders where content is unknown.
+
+## Style Rules
+
+- Use plain language. Avoid filler like "this PR aims to", "in order to", and "leverages".
+- Be concrete. Name the screens, components, flows, commands, or files that changed.
+- Keep it short. Each prose section should usually be 1-3 sentences.
+- Avoid bullet soup. If a section needs more than 6 bullets, group related items.
+- Skip obvious filler such as import cleanup or lint-only noise unless that is the point of the PR.
+- Do not invent Jira tickets, screenshots, devices tested, or implementation details not supported by the diff.
+
+## Workflow
+
+1. Read the repository instructions first:
+   - `AGENTS.md`
+   - `REVIEW.md` when present, because this repo requires it for review-related work.
+2. Find the PR template:
+   - Prefer `.github/PULL_REQUEST_TEMPLATE.md`.
+   - Fall back to `PULL_REQUEST_TEMPLATE.md` at the repo root only if the GitHub template is absent.
+3. Refresh and inspect the branch:
+   - Run `git fetch origin master`.
+   - Run `git log origin/master..HEAD --oneline`.
+   - Run `git diff origin/master...HEAD --stat`.
+   - Run `git diff origin/master...HEAD`.
+4. Draft the PR description using the exact headings and order from the template.
+5. Save it as `PR_DESCRIPTION.md` at the repo root, overwriting any existing file.
+6. Ensure `PR_DESCRIPTION.md` is ignored by git. If it is missing from `.gitignore`, append it under:
+
+```gitignore
+# PR description scratchpad (agents)
+PR_DESCRIPTION.md
+```
+
+7. Report back with the relative path only, unless the user asks to see the content.
+
+## Section Guidance For This Repository
+
+The current template is `.github/PULL_REQUEST_TEMPLATE.md`. Keep the warning comment and separators from the template if they are present.
+
+### Jira board reference:
+
+Leave the example placeholder or replace it only if a real Jira ticket is present in the branch name, commits, or user request. Do not invent ticket IDs.
+
+### What does this do?
+
+Write 2-4 concise sentences describing what changed. Focus on user-facing behavior, developer workflow changes, or the concrete problem fixed.
+
+### Why did you do this?
+
+Write 1-3 concise sentences explaining the reason for the change. Tie it to the bug, product need, maintainability concern, or template behavior visible in the diff.
+
+### Who/what does this impact?
+
+Name affected screens, flows, platforms, users, modules, or developer workflows. Use a short sentence or compact bullets. If impact is unclear, leave a placeholder comment instead of guessing.
+
+### How did you test this?
+
+List commands run and manual checks performed. Keep the existing checklist from the template and check only items that are supported by evidence or explicitly provided by the user.
+
+### Notes:
+
+Include caveats, follow-ups, migration notes, or review hints. If there are none, leave the template placeholder.
+
+### Screenshots / Previews
+
+Keep the screenshot/Figma/device placeholders unless real images or recordings are available. Remove irrelevant bug before/after tables only when the template structure still remains clear.
+
+## Final Response
+
+After writing the file, say where it was saved, for example:
+
+`Done: PR_DESCRIPTION.md`
+
+Do not paste the full PR description unless the user asks.
@@ -0,0 +1,71 @@
+---
+name: review-changes
+description: Reviews the current branch diff against this project's architecture, conventions, and code review checklist. Use when the user asks to "review my changes", "review the diff", "check my code", "run a code review", or "review this branch".
+allowed-tools: Bash(git:*), Read
+---
+
+# Review Changes
+
+## Purpose
+
+Perform a code review of the current branch diff against the project's architecture rules, coding conventions, and the REVIEW.md checklist. Report findings grouped by category, with file and line references where possible.
+
+## Workflow
+
+1. Read the project rules:
+   - `AGENTS.md` — critical constraints and glossary
+   - `REVIEW.md` — the review checklist; this is the primary source of truth for what to flag
+   - `agent_docs/architecture.md` — layer diagram, routing conventions, dual auth system
+   - `agent_docs/conventions.md` — API hooks, styling, forms, i18n, anti-patterns
+
+2. Inspect the branch diff:
+   - Run `git fetch origin master`.
+   - Run `git log origin/master..HEAD --oneline` to understand the commit scope.
+   - Run `git diff origin/master...HEAD --stat` to see which files changed.
+   - Run `git diff origin/master...HEAD` to read the full diff.
+
+3. If a changed file needs more context to review correctly (e.g. to check imports, types, or hook usage), use Read to open it.
+
+4. Review the diff against every category in REVIEW.md:
+   - API & Query layer
+   - Auth & security
+   - Type safety
+   - i18n
+   - Styling
+   - Testing
+   - Performance
+
+5. Also check for violations of the critical constraints in `AGENTS.md`:
+   - Package manager (`pnpm` only)
+   - Env values via `Env` from `@/lib/env`
+   - No auth logic in screen components
+   - No manual camelCase↔snake_case conversion
+   - No direct MMKV access in components
+   - All strings through `useTranslation()`
+   - `createMutation` / `createQuery` from `react-query-kit`
+   - `createQueryKeys` in `src/api/query-factory.ts`
+   - `@shopify/flash-list` for growable lists
+   - `expo-crypto` for random IDs
+   - `react-hook-form` + `zod` for forms
+   - `moti` or `react-native-reanimated` for animations (no `Animated` from RN directly)
+
+6. Check layer boundaries from `agent_docs/architecture.md`:
+   - Data flows down: `app/ → components/ → api/ → lib/`
+   - Route guards belong only in `src/app/_layout.tsx`, never in screen files
+   - Auth state management belongs only in `src/components/providers/auth.tsx` and `src/lib/auth/index.tsx`
+
+## Output Format
+
+Group findings by REVIEW.md category. For each finding:
+
+```
+**[Category]** `path/to/file.ts` — short description of the issue and what the correct approach is.
+```
+
+If a category has no issues, skip it.
+
+End the report with one of:
+- **No issues found** — if the diff is clean across all categories.
+- **X issue(s) found** — a one-line summary count.
+
+Do not suggest stylistic preferences not grounded in REVIEW.md, AGENTS.md, or agent_docs/. Do not flag things that are already handled automatically by the interceptors or tooling (e.g. case conversion, token injection).
@@ -22,6 +22,8 @@ When reviewing code, read and apply the rules in ./REVIEW.md
 | `queryFactory`     | Merged query key registry built with `@lukemorales/query-key-factory` — defined in `src/api/query-factory.ts`                                                |
 | `createMutation`   | Factory from `react-query-kit` for creating typed mutation hooks — required pattern for all mutations                                                        |
 | `createQuery`      | Factory from `react-query-kit` for creating typed query hooks — required pattern for all queries                                                             |
+| `APIProvider`      | Wraps the Axios client instance via React context — defined in `src/api/common/api-provider.tsx`; must be present in the provider tree above any API hook    |
+| `authStorage`      | Dedicated MMKV instance for auth tokens, created inside `src/components/providers/auth.tsx` — never access it directly; use `storeTokens`, `getTokenDetails`, `clearTokens` |
 
 ---
 
@@ -37,14 +39,35 @@ When reviewing code, read and apply the rules in ./REVIEW.md
 - **Query keys**: Every new query domain must be registered in `src/api/query-factory.ts` using `createQueryKeys` from `@lukemorales/query-key-factory`.
 - **Lists**: Use `@shopify/flash-list` for any list that can grow. Never use `FlatList` for feed-style content.
 - **Crypto/IDs**: Use `expo-crypto` for random IDs. Never use `Math.random()` or `Date.now()` as identifiers.
+- **Forms**: Always use `react-hook-form` + `zod` + `@hookform/resolvers`. Never use `useState` for form state or uncontrolled inputs.
+- **Animations**: Never use `Animated` from React Native directly. Use `moti` for declarative animations or `react-native-reanimated` for gesture-driven ones.
+- **Token refresh**: Token refresh is **not implemented** — there is a `TODO` in `src/components/providers/auth.tsx`. Do not add refresh logic without a deliberate design decision; adding partial refresh code will conflict with the existing 401 handling.
 - **New dependencies**: Before installing any library, verify the latest version compatible with this stack — React Native 0.81, Expo SDK 54, and React 19. Check compatibility via `npx expo install <package>` (which resolves the Expo-blessed version) or the package's peer dependencies. Do not install the latest npm version blindly — it may not support this SDK version.
 
 ---
 
+## Provider hierarchy
+
+Providers must wrap the app in this order (outermost → innermost):
+
+```
+GestureHandlerRootView
+  └── KeyboardProvider
+        └── ThemeProvider
+              └── APIProvider
+                    └── AuthProvider
+                          └── BottomSheetModalProvider
+```
+
+Never add a new provider outside `APIProvider` if it requires API access, or outside `AuthProvider` if it requires auth state.
+
+---
+
 ## Table of contents
 
 | File                         | Description                                                                      |
 | ---------------------------- | -------------------------------------------------------------------------------- |
+| `REVIEW.md`                  | Code review checklist — apply to every change you make                           |
 | `agent_docs/architecture.md` | Layer diagram, folder structure, routing conventions, dual auth system explained |
 | `agent_docs/conventions.md`  | API hook patterns, styling, forms, i18n, anti-patterns                           |
 | `agent_docs/commands.md`     | All pnpm commands for dev, test, lint, build, and setup                          |

@@ -1 +1,10 @@
 Strictly follow the rules in ./AGENTS.md
+
+## Before starting any non-trivial task
+
+Read these files to understand the codebase before writing code:
+
+1. `agent_docs/architecture.md` — layer diagram, folder structure, routing conventions, dual auth system
+2. `agent_docs/conventions.md` — API hook patterns, styling, forms, i18n, anti-patterns
+3. `agent_docs/commands.md` — all pnpm commands for dev, test, lint, build
+4. `REVIEW.md` — code review checklist; apply it to every change you make