diff --git a/.agents/skills/pr-description/SKILL.md b/.agents/skills/pr-description/SKILL.md index 31656590..f9b0fac9 100644 --- a/.agents/skills/pr-description/SKILL.md +++ b/.agents/skills/pr-description/SKILL.md @@ -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 diff --git a/.claude/skills/pr-description/SKILL.md b/.claude/skills/pr-description/SKILL.md new file mode 100644 index 00000000..f9b0fac9 --- /dev/null +++ b/.claude/skills/pr-description/SKILL.md @@ -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. diff --git a/.claude/skills/review-changes/SKILL.md b/.claude/skills/review-changes/SKILL.md new file mode 100644 index 00000000..3130a827 --- /dev/null +++ b/.claude/skills/review-changes/SKILL.md @@ -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). diff --git a/AGENTS.md b/AGENTS.md index b7c2e012..bd2be708 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 ` (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 | diff --git a/CLAUDE.md b/CLAUDE.md index 27bd5410..e3512018 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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