rn-agent-kit 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +176 -2
  3. package/dist/cli.js +2916 -0
  4. package/dist/cli.js.map +1 -0
  5. package/dist/scripts/figma-tokens.js +1284 -0
  6. package/dist/scripts/figma-tokens.js.map +1 -0
  7. package/dist/scripts/validate-jira-tickets.js +169 -0
  8. package/dist/scripts/validate-jira-tickets.js.map +1 -0
  9. package/package.json +64 -4
  10. package/skills/expo-cli/SKILL.md +213 -0
  11. package/skills/figma-to-tokens/SKILL.md +288 -0
  12. package/skills/github-actions-ci/SKILL.md +124 -0
  13. package/skills/maestro-e2e/SKILL.md +256 -0
  14. package/skills/prd-to-jira/SKILL.md +237 -0
  15. package/skills/rn-architecture/SKILL.md +207 -0
  16. package/skills/rn-native-android-ios/SKILL.md +195 -0
  17. package/skills/rn-sdk-integrations/SKILL.md +274 -0
  18. package/skills/rn-typescript-react/SKILL.md +247 -0
  19. package/skills/ticket-to-code/SKILL.md +192 -0
  20. package/templates/config/rn-agent-kit.json +4 -0
  21. package/templates/eslint/eslint.config.snippet.mjs +16 -0
  22. package/templates/eslint/rn-agent-kit-rules.cjs +137 -0
  23. package/templates/jira-ticket.md +78 -0
  24. package/templates/maestro/smoke.yaml +4 -0
  25. package/templates/scaffold/.husky/commit-msg +4 -0
  26. package/templates/scaffold/.husky/pre-commit +4 -0
  27. package/templates/scaffold/.prettierignore +6 -0
  28. package/templates/scaffold/.prettierrc +6 -0
  29. package/templates/scaffold/commitlint.config.cjs +4 -0
  30. package/templates/scaffold/eslint.config.js +22 -0
  31. package/templates/scaffold/jest.config.cjs +9 -0
  32. package/templates/scaffold/tsconfig.json +13 -0
  33. package/templates/workflows/ci.yml +120 -0
  34. package/templates/workflows/e2e-android.yml +158 -0
  35. package/templates/workflows/e2e-ios.yml +134 -0
  36. package/templates/workflows/eas-build.yml +94 -0
@@ -0,0 +1,256 @@
1
+ ---
2
+ name: maestro-e2e
3
+ description: >-
4
+ Maestro E2E conventions for React Native: YAML flows under
5
+ maestro/flows/<feature>/<TC-ID>.yaml, testID-only selectors, reusable
6
+ subflows, env vars, clearState, tags (smoke, regression). Use when writing
7
+ or fixing Maestro flows, mapping Jira TC-IDs to e2e, or before ticket-to-code
8
+ STEP A. Cite Maestro docs; never select by visible text alone.
9
+ globs: "**/maestro/**/*.{yaml,yml}"
10
+ alwaysApply: false
11
+ ---
12
+
13
+ # maestro-e2e
14
+
15
+ E2E for this kit uses **Maestro** (see **Maestro Flow docs** / cheat sheet). Flows are the executable form of Jira **TC-\*** IDs from `prd-to-jira` / `ticket-to-code`.
16
+
17
+ ## Hard rules
18
+
19
+ 1. **testID selectors only** for assertions and taps that target product UI: `id: "…"`. Do **not** use visible copy (`tapOn: "Login"`) for primary steps — copy changes break CI.
20
+ 2. Path: `maestro/flows/<feature>/<TC-ID>.yaml` (example: `maestro/flows/login/TC-APP-01.yaml`).
21
+ 3. One flow file **per** test case ID. Name the flow with `name:` matching the TC title when helpful.
22
+ 4. Prefer **reusable subflows** under `maestro/flows/_shared/` via `runFlow:`.
23
+ 5. Always start with a clean slate: `launchApp` + `clearState: true` (unless a later TC intentionally continues state — document why).
24
+ 6. Tags: every flow has `tags:` including at least one of `smoke` | `regression` (and optional `login`, `android`, `ios`).
25
+ 7. No secrets in YAML — use `env:` + CI secrets / `.env` injected at runtime.
26
+ 8. Match `appId` to the real bundle id / applicationId from `app.config` / native projects.
27
+
28
+ ## Layout
29
+
30
+ ```text
31
+ maestro/
32
+ flows/
33
+ _shared/
34
+ launch-clean.yaml
35
+ login-as-user.yaml
36
+ login/
37
+ TC-APP-01.yaml # happy path
38
+ TC-APP-02.yaml # invalid credentials
39
+ catalog/
40
+ TC-APP-10.yaml
41
+ smoke.yaml # optional suite entry (runFlow list) — keep thin
42
+ ```
43
+
44
+ ## Anatomy of a flow
45
+
46
+ ```yaml
47
+ appId: com.example.myapp
48
+ name: "TC-APP-01 Login happy path"
49
+ tags:
50
+ - smoke
51
+ - login
52
+ env:
53
+ E2E_EMAIL: ${E2E_EMAIL}
54
+ E2E_PASSWORD: ${E2E_PASSWORD}
55
+ ---
56
+ - runFlow:
57
+ file: ../_shared/launch-clean.yaml
58
+ - tapOn:
59
+ id: login-email
60
+ - inputText: ${E2E_EMAIL}
61
+ - tapOn:
62
+ id: login-password
63
+ - inputText: ${E2E_PASSWORD}
64
+ - tapOn:
65
+ id: login-submit
66
+ - assertVisible:
67
+ id: home-root
68
+ - assertNotVisible:
69
+ id: login-error
70
+ ```
71
+
72
+ ### Shared launch (clearState + permissions)
73
+
74
+ ```yaml
75
+ # maestro/flows/_shared/launch-clean.yaml
76
+ appId: com.example.myapp
77
+ ---
78
+ - launchApp:
79
+ clearState: true
80
+ clearKeychain: true
81
+ permissions:
82
+ notifications: deny
83
+ all: deny
84
+ ```
85
+
86
+ Grant only what the TC needs (`camera: allow`, etc.). Prefer denying by default to catch missing permission UX.
87
+
88
+ ## Selector conventions
89
+
90
+ | Do | Don't |
91
+ | ----------------------------------------------------------- | ------------------------------- |
92
+ | `tapOn: { id: "login-submit" }` | `tapOn: "Sign in"` |
93
+ | `assertVisible: { id: "home-root" }` | `assertVisible: "Welcome back"` |
94
+ | `scrollUntilVisible: { element: { id: "product-row-42" } }` | Scroll blindly then tap text |
95
+ | `inputText` after focusing via `tapOn: { id }` | Assume keyboard focus |
96
+
97
+ RN: set `testID` on components (Android `resource-id` / iOS accessibility id — Maestro `id:` maps to these). Keep IDs stable; never reuse across unrelated screens.
98
+
99
+ ## Commands to prefer
100
+
101
+ - `assertVisible` / `assertNotVisible` with `id:`
102
+ - `tapOn: { id: }`
103
+ - `inputText` (after tap on field)
104
+ - `scrollUntilVisible` with `element: { id: }`
105
+ - `extendedWaitUntil` for slow network (prefer fixing loading `testID`s over huge sleeps)
106
+ - `waitForAnimationToEnd` after navigations
107
+ - `runFlow` for login/setup subflows
108
+ - `eraseText` when re-typing in the same field
109
+
110
+ Avoid AI assert helpers in CI-critical smoke paths unless optional.
111
+
112
+ ## Tags
113
+
114
+ | Tag | Meaning |
115
+ | ------------ | ------------------------------------- |
116
+ | `smoke` | Must pass on every PR / main build |
117
+ | `regression` | Broader suite (nightly / pre-release) |
118
+ | feature tags | `login`, `checkout`, … |
119
+
120
+ ```bash
121
+ maestro test maestro/flows/login/TC-APP-01.yaml
122
+ maestro test --include-tags smoke maestro/flows
123
+ ```
124
+
125
+ ## Examples
126
+
127
+ ### Login (happy path) — `maestro/flows/login/TC-APP-01.yaml`
128
+
129
+ ```yaml
130
+ appId: com.example.myapp
131
+ name: "TC-APP-01 Login success"
132
+ tags: [smoke, login]
133
+ env:
134
+ E2E_EMAIL: ${E2E_EMAIL}
135
+ E2E_PASSWORD: ${E2E_PASSWORD}
136
+ ---
137
+ - runFlow: { file: ../_shared/launch-clean.yaml }
138
+ - assertVisible: { id: login-root }
139
+ - tapOn: { id: login-email }
140
+ - inputText: ${E2E_EMAIL}
141
+ - tapOn: { id: login-password }
142
+ - inputText: ${E2E_PASSWORD}
143
+ - tapOn: { id: login-submit }
144
+ - assertVisible: { id: home-root }
145
+ - assertNotVisible: { id: login-error }
146
+ ```
147
+
148
+ ### Login error — `TC-APP-02.yaml`
149
+
150
+ ```yaml
151
+ appId: com.example.myapp
152
+ name: "TC-APP-02 Login invalid credentials"
153
+ tags: [regression, login]
154
+ ---
155
+ - runFlow: { file: ../_shared/launch-clean.yaml }
156
+ - tapOn: { id: login-email }
157
+ - inputText: "bad@example.com"
158
+ - tapOn: { id: login-password }
159
+ - inputText: "not-the-password"
160
+ - tapOn: { id: login-submit }
161
+ - assertVisible: { id: login-error }
162
+ - assertVisible: { id: login-root }
163
+ - assertNotVisible: { id: home-root }
164
+ ```
165
+
166
+ ### List + scroll — `maestro/flows/catalog/TC-APP-10.yaml`
167
+
168
+ ```yaml
169
+ appId: com.example.myapp
170
+ name: "TC-APP-10 Open product from list"
171
+ tags: [regression, catalog]
172
+ ---
173
+ - runFlow: { file: ../_shared/login-as-user.yaml }
174
+ - assertVisible: { id: catalog-list }
175
+ - scrollUntilVisible:
176
+ element:
177
+ id: product-row-premium
178
+ direction: DOWN
179
+ timeout: 15000
180
+ - tapOn: { id: product-row-premium }
181
+ - assertVisible: { id: product-detail-root }
182
+ ```
183
+
184
+ ### Form validation — `maestro/flows/profile/TC-APP-20.yaml`
185
+
186
+ ```yaml
187
+ appId: com.example.myapp
188
+ name: "TC-APP-20 Profile email validation"
189
+ tags: [regression, profile]
190
+ ---
191
+ - runFlow: { file: ../_shared/login-as-user.yaml }
192
+ - tapOn: { id: tab-profile }
193
+ - tapOn: { id: profile-email }
194
+ - eraseText
195
+ - inputText: "not-an-email"
196
+ - tapOn: { id: profile-save }
197
+ - assertVisible: { id: profile-email-error }
198
+ - assertNotVisible: { id: profile-save-success }
199
+ ```
200
+
201
+ ### Error / empty state — `maestro/flows/catalog/TC-APP-11.yaml`
202
+
203
+ ```yaml
204
+ appId: com.example.myapp
205
+ name: "TC-APP-11 Catalog empty state"
206
+ tags: [regression, catalog]
207
+ env:
208
+ E2E_FORCE_EMPTY_CATALOG: "1"
209
+ ---
210
+ - runFlow: { file: ../_shared/launch-clean.yaml }
211
+ # App reads launch arg / env via detox-less stub or mock server — document in ticket
212
+ - assertVisible: { id: catalog-empty }
213
+ - assertNotVisible: { id: catalog-list }
214
+ - assertVisible: { id: catalog-retry }
215
+ ```
216
+
217
+ ## Permissions
218
+
219
+ ```yaml
220
+ - launchApp:
221
+ clearState: true
222
+ permissions:
223
+ notifications: allow
224
+ camera: deny
225
+ location: unset
226
+ ```
227
+
228
+ After a deny, assert the in-app fallback (`id: permission-denied-banner`), not the OS dialog text.
229
+
230
+ ## Naming
231
+
232
+ | Artifact | Pattern |
233
+ | -------------- | ------------------------------------------------- |
234
+ | Feature folder | `kebab-case` matching Jira story slug / feature |
235
+ | Flow file | `TC-<PROJECT>-<nn>.yaml` exact ticket TC id |
236
+ | testIDs | `screen-element` kebab (same as Jira ticket list) |
237
+ | Subflows | `_shared/<verb>-<noun>.yaml` |
238
+
239
+ ## Common mistakes
240
+
241
+ 1. Selecting by visible string → flakes on copy/i18n.
242
+ 2. Missing `clearState` → order-dependent passes.
243
+ 3. One YAML covering many TC-IDs → impossible to map to Jira.
244
+ 4. Hardcoding passwords in the repo.
245
+ 5. Asserting too early without waiting for `id: *-loading` to disappear.
246
+ 6. Editing the flow to match buggy UI instead of fixing the app (**ticket-to-code** forbids this unless AC changed).
247
+
248
+ ## Done checklist
249
+
250
+ - [ ] Path `maestro/flows/<feature>/<TC-ID>.yaml`
251
+ - [ ] `tags` include smoke and/or regression
252
+ - [ ] Only `id:` selectors for product UI
253
+ - [ ] `clearState` (or documented exception)
254
+ - [ ] Subflows used for login/setup
255
+ - [ ] Env vars for credentials
256
+ - [ ] Matches testIDs listed on the Jira ticket
@@ -0,0 +1,237 @@
1
+ ---
2
+ name: prd-to-jira
3
+ description: >-
4
+ Turn a PRD + Figma link into a Jira Epic/Stories/Sub-tasks tree with Gherkin AC,
5
+ testIDs, Figma node links, and a durable .agent/jira-map.json. Use when the user
6
+ provides a PRD (text/file/link) and a Figma URL, asks to "create Jira tickets",
7
+ "break down the PRD", "plan the epic", or after figma-to-tokens is ready.
8
+ Requires Atlassian + Figma MCP.
9
+ globs: "**/{.agent/**,design/**,*.md,prd/**}"
10
+ alwaysApply: false
11
+ ---
12
+
13
+ # prd-to-jira
14
+
15
+ Convert a **PRD + Figma file** into a structured Jira backlog the coding agent can implement later via `ticket-to-code`.
16
+
17
+ ```
18
+ PRD + Figma URL
19
+ │ (1) figma-to-tokens if design/tokens.json missing
20
+ │ (2) Figma MCP → screen inventory (node IDs + deep links)
21
+ │ (3) optional human confirm when .agent/config.json has confirm: true
22
+ ▼
23
+ Atlassian MCP → Epic → Stories → Sub-tasks
24
+ │
25
+ ▼
26
+ .agent/jira-map.json (nodeId ↔ Jira key; reruns UPDATE, never duplicate)
27
+ ```
28
+
29
+ Cite **Atlassian MCP / Jira Cloud REST**, **Figma MCP**, and this kit’s `figma-to-tokens` skill.
30
+
31
+ ## Hard rules
32
+
33
+ 1. **Never invent screens** that are not in the PRD or Figma. If a PRD feature has no frame, mark it `needs-design` in the plan and still create the Story with a clear gap note — do not fake a Figma link.
34
+ 2. **Never invent tokens.** If `design/tokens.json` is missing, run **figma-to-tokens** first and stop if that skill reports errors.
35
+ 3. **Every Story and Sub-task** must include: Figma node deep link (or explicit `NEEDS_FIGMA`), Gherkin Acceptance Criteria, `testIDs` list, states (loading/empty/error), `TC-<KEY>-##` IDs, Definition of Done. Use `templates/jira-ticket.md`.
36
+ 4. **Idempotent mapping.** Always read/write `.agent/jira-map.json`. If a nodeId (or story slug) already maps to a Jira key, **update** that issue — do not create a duplicate.
37
+ 5. **No secrets** in tickets or map files (no API tokens, no `.env` values).
38
+ 6. **Confirm gate:** present the epic→stories plan for user approval **only if** `.agent/config.json` has `"confirm": true` (or `jira.confirm: true`). Otherwise proceed after printing a short summary.
39
+ 7. After creating tickets, run the validator: `npx rn-agent-kit jira-validate` (or `npx tsx src/scripts/validate-jira-tickets.ts`). Fix failures before finishing.
40
+
41
+ ## Pre-flight
42
+
43
+ 1. Read `.agent/config.json` if present:
44
+ - `jira.siteUrl`, `jira.projectKey`
45
+ - `figma.fileUrl`
46
+ - `confirm` / `jira.confirm` (boolean)
47
+ 2. Confirm Atlassian MCP + Figma MCP are available. If not, stop and tell the user to run `rn-agent-kit init --sdlc` / `doctor`.
48
+ 3. Collect inputs from the user message:
49
+ - PRD (inline text, file path, or URL — fetch/read it)
50
+ - Figma file URL (override config if provided)
51
+ 4. If `design/tokens.json` is **missing**, run the **figma-to-tokens** skill end-to-end, then continue. If it exists, note the path and link it from the Epic.
52
+
53
+ ## Step 1 — Design tokens gate
54
+
55
+ ```bash
56
+ test -f design/tokens.json || npx rn-agent-kit tokens build
57
+ ```
58
+
59
+ - On token **errors**, stop and hand the report to the user.
60
+ - Epic description must link to `design/tokens.json` (repo-relative) and the Figma file URL.
61
+
62
+ ## Step 2 — Inventory Figma screens
63
+
64
+ Using Figma MCP (`get_metadata`, `get_design_context`, or equivalent):
65
+
66
+ 1. List top-level **pages** and **frames** that represent screens / major flows.
67
+ 2. For each screen record:
68
+ - `name` (human title)
69
+ - `nodeId` (e.g. `12:34`)
70
+ - `deepLink`: `https://www.figma.com/design/<FILE_KEY>/<NAME>?node-id=<encoded>`
71
+ (encode `:` → `-` in `node-id` query, e.g. `12-34`)
72
+ 3. Print a markdown table to the user:
73
+
74
+ | Screen | Node ID | Figma link |
75
+ | ------ | ------- | -------------------------------------------- |
76
+ | Login | 12:34 | https://www.figma.com/design/…?node-id=12-34 |
77
+
78
+ 4. Map PRD features → these screens. One Story ≈ one feature/screen flow.
79
+
80
+ ## Step 3 — Plan (Epic → Stories → Sub-tasks)
81
+
82
+ Draft:
83
+
84
+ ```text
85
+ Epic: <Product / PRD title>
86
+ Story: <Feature / screen flow> # 1 per screen or cohesive flow
87
+ Sub-task: UI build
88
+ Sub-task: State / API
89
+ Sub-task: E2E test (Maestro)
90
+ Sub-task: Accessibility
91
+ ```
92
+
93
+ **Confirm gate**
94
+
95
+ ```ts
96
+ const cfg = readJson(".agent/config.json");
97
+ const needsConfirm = cfg.confirm === true || cfg.jira?.confirm === true;
98
+ ```
99
+
100
+ - If `needsConfirm`: show the plan and **wait** for explicit user approval before calling Atlassian MCP.
101
+ - Else: print a one-paragraph summary and proceed.
102
+
103
+ ## Step 4 — Create / update Jira via Atlassian MCP
104
+
105
+ Use the project key from config (e.g. `APP`). Prefer MCP issue create/update tools; fall back to documented Jira REST if MCP exposes it.
106
+
107
+ ### Epic (exactly one per PRD run / map entry `epic`)
108
+
109
+ Fields / description sections:
110
+
111
+ - **Title:** `[PRD] <short name>`
112
+ - **Goal**
113
+ - **In scope / Out of scope**
114
+ - **PRD link** (path or URL)
115
+ - **Design tokens:** `design/tokens.json` + Figma file URL
116
+ - **Screen inventory** (table from Step 2)
117
+
118
+ ### Story (one per feature/screen flow)
119
+
120
+ Fill **every** section from `templates/jira-ticket.md`:
121
+
122
+ - Figma node deep link for **that** screen
123
+ - Gherkin AC
124
+ - `testIDs` (stable, kebab or camel — match app conventions)
125
+ - API contracts (OpenAPI-ish bullets or “none”)
126
+ - States: loading / empty / error / success
127
+ - Test case IDs: `TC-<PROJECTKEY>-01`, `TC-…-02`, … (unique within the epic)
128
+ - Definition of Done checklist
129
+
130
+ ### Sub-tasks (under each Story)
131
+
132
+ | Sub-task | Focus |
133
+ | ------------------ | -------------------------------------------------- |
134
+ | UI build | Layout, theme tokens, navigation, testIDs wired |
135
+ | State / API | Query/mutation, zod contracts, error/empty/loading |
136
+ | E2E test (Maestro) | Flow YAML under `maestro/`, assert testIDs |
137
+ | Accessibility | Labels, roles, contrast, dynamic type / font scale |
138
+
139
+ Each sub-task still includes Figma link (same screen), AC subset, testIDs, TC IDs, DoD — trimmed but **not empty**.
140
+
141
+ ## Step 5 — `.agent/jira-map.json` (required)
142
+
143
+ Create or update (sorted keys, trailing newline):
144
+
145
+ ```jsonc
146
+ {
147
+ "version": 1,
148
+ "projectKey": "APP",
149
+ "prd": { "title": "…", "source": "docs/prd.md" },
150
+ "figmaFileUrl": "https://www.figma.com/design/AbC123/App",
151
+ "tokensPath": "design/tokens.json",
152
+ "epic": { "key": "APP-100", "summary": "[PRD] …" },
153
+ "stories": {
154
+ "login": {
155
+ "key": "APP-101",
156
+ "summary": "Login",
157
+ "figmaNodeId": "12:34",
158
+ "figmaUrl": "https://www.figma.com/design/AbC123/App?node-id=12-34",
159
+ "subtasks": {
160
+ "ui": { "key": "APP-102" },
161
+ "state-api": { "key": "APP-103" },
162
+ "e2e": { "key": "APP-104" },
163
+ "a11y": { "key": "APP-105" },
164
+ },
165
+ },
166
+ },
167
+ }
168
+ ```
169
+
170
+ **Rerun behavior**
171
+
172
+ 1. Load map if present.
173
+ 2. Match stories by `figmaNodeId` first, else by slug.
174
+ 3. Existing key → MCP **update**; missing → **create** and write key into map.
175
+ 4. Never delete Jira issues automatically; mark removed screens under `"retired": []` in the map if needed.
176
+
177
+ ## Step 6 — Validate
178
+
179
+ ```bash
180
+ npx rn-agent-kit jira-validate --map .agent/jira-map.json
181
+ # or: npx tsx src/scripts/validate-jira-tickets.ts --map .agent/jira-map.json --fixtures .agent/jira-tickets/
182
+ ```
183
+
184
+ The validator fails (exit 1) if any ticket body is missing:
185
+
186
+ - Figma link (`figma.com` URL **or** explicit `NEEDS_FIGMA`)
187
+ - Acceptance Criteria / Gherkin (`Given`/`When`/`Then` or `Acceptance Criteria` heading)
188
+ - `testIDs` list (bullet/code list under a testIDs heading)
189
+
190
+ Optional: dump issue descriptions to `.agent/jira-tickets/<KEY>.md` before validate for offline CI.
191
+
192
+ ## Step 7 — Finish
193
+
194
+ Print:
195
+
196
+ ```text
197
+ Epic: APP-100
198
+ URL: https://<site>.atlassian.net/browse/APP-100
199
+ Map: .agent/jira-map.json
200
+
201
+ Suggested next command:
202
+ Implement APP-100
203
+ ```
204
+
205
+ (or `Implement <EPIC-KEY>` using the real key). Point the user at **ticket-to-code** / Maestro skills for implementation.
206
+
207
+ ## Ticket content checklist (per Story)
208
+
209
+ - [ ] Figma deep link for exact screen
210
+ - [ ] Gherkin AC (happy path + 1 error path minimum)
211
+ - [ ] testIDs for primary controls
212
+ - [ ] API contracts or “none”
213
+ - [ ] loading / empty / error states described
214
+ - [ ] TC-IDs assigned
215
+ - [ ] DoD checklist present
216
+ - [ ] Four sub-tasks created and mapped
217
+
218
+ ## Common mistakes
219
+
220
+ 1. Creating tickets before tokens exist → UI will hardcode values.
221
+ 2. One mega-Story for the whole app → impossible to implement/test.
222
+ 3. Figma link to the **file** root instead of the **frame** node.
223
+ 4. Duplicating issues on rerun because the map was skipped.
224
+ 5. AC written as vague prose (“should work”) instead of Gherkin.
225
+ 6. Missing testIDs → Maestro / RNTL cannot target elements.
226
+ 7. Waiting for approval when `confirm` is false (or the inverse).
227
+ 8. Putting Jira API tokens into ticket descriptions.
228
+
229
+ ## Done
230
+
231
+ - [ ] Tokens present and linked from Epic
232
+ - [ ] Screen inventory table shown
233
+ - [ ] Confirm gate respected
234
+ - [ ] Epic + Stories + 4 sub-tasks each in Jira
235
+ - [ ] `.agent/jira-map.json` written
236
+ - [ ] Validator passes
237
+ - [ ] User saw Epic key + `Implement <EPIC-KEY>`
@@ -0,0 +1,207 @@
1
+ ---
2
+ name: rn-architecture
3
+ description: >-
4
+ Feature-based React Native architecture: folders, layers, navigation, Zustand +
5
+ TanStack Query, dependency rules, error boundaries, env config, scalability.
6
+ Use when structuring a new RN/Expo app, adding a feature module, choosing state
7
+ libraries, wiring navigation, or reviewing folder/layer boundaries.
8
+ globs: "**/*.{ts,tsx,js,jsx}"
9
+ alwaysApply: false
10
+ ---
11
+
12
+ # rn-architecture
13
+
14
+ Prefer **feature-based** structure over type-based dumping grounds (`components/`, `hooks/` at root). Cite **React Native docs**, **Expo Router docs**, **React Navigation docs**, **Zustand**, and **TanStack Query** for APIs.
15
+
16
+ ## Folder structure
17
+
18
+ ```text
19
+ src/
20
+ app/ # Expo Router routes only (or navigation/ for RN CLI)
21
+ features/
22
+ auth/
23
+ components/
24
+ hooks/
25
+ services/
26
+ store/
27
+ types/
28
+ index.ts # public API of the feature
29
+ home/
30
+ ...
31
+ shared/
32
+ components/ # truly cross-feature UI
33
+ hooks/
34
+ lib/ # http client, storage, logger
35
+ theme/
36
+ types/
37
+ config/ # env, feature flags
38
+ ```
39
+
40
+ **Rule:** A feature may import `shared/*` and its own folders. Features must **not** import another feature’s internals—only that feature’s `index.ts` (or a dedicated `api.ts`).
41
+
42
+ ```ts
43
+ // ✅ Good — consume public API
44
+ import { useSession } from "@/features/auth";
45
+
46
+ // ❌ Bad — reach into another feature
47
+ import { sessionStore } from "@/features/auth/store/sessionStore";
48
+ ```
49
+
50
+ ## Layers (UI / domain / data)
51
+
52
+ | Layer | Lives in | May call |
53
+ | ---------- | --------------------------------- | -------------------------------------- |
54
+ | **UI** | `components/`, screens/routes | hooks, shared UI |
55
+ | **Domain** | `hooks/`, `store/`, pure `types/` | services, other domain in same feature |
56
+ | **Data** | `services/` | HTTP, SecureStore, native SDKs |
57
+
58
+ ```ts
59
+ // ✅ Good — screen is thin
60
+ export function LoginScreen() {
61
+ const { mutate, isPending, error } = useLogin();
62
+ return <LoginForm onSubmit={mutate} loading={isPending} error={error} />;
63
+ }
64
+
65
+ // ❌ Bad — UI talks to network + parses JSON
66
+ export function LoginScreen() {
67
+ const onSubmit = async (email: string) => {
68
+ const res = await fetch("/login", { method: "POST", body: JSON.stringify({ email }) });
69
+ const data = await res.json();
70
+ setUser(data.user);
71
+ };
72
+ }
73
+ ```
74
+
75
+ Keep **domain logic** out of JSX. Keep **transport details** (URLs, headers) out of hooks when a `services/` function can own them.
76
+
77
+ ## Navigation
78
+
79
+ ### Expo Router (preferred for Expo)
80
+
81
+ - Routes under `app/` (or `src/app/`). Screens stay dumb; data in feature hooks.
82
+ - Typed routes via Expo Router typed routes (see **Expo Router — Typed routes**).
83
+ - Prefer route groups `(auth)`, `(tabs)` over deep relative `../../` imports.
84
+
85
+ ```tsx
86
+ // ✅ Good — href + params typed / validated at boundary
87
+ import { Link } from "expo-router";
88
+ <Link href={{ pathname: "/product/[id]", params: { id } }} />;
89
+
90
+ // ❌ Bad — string soup with no feature ownership
91
+ navigation.navigate("Product" as any, { id });
92
+ ```
93
+
94
+ ### React Navigation (RN CLI / bare)
95
+
96
+ - One root navigator; feature stacks registered from `features/*/navigation`.
97
+ - Define a single `RootParamList`; pass it to `NativeStackScreenProps`.
98
+ - Cite **React Navigation — TypeScript**.
99
+
100
+ ```ts
101
+ // ✅ Good
102
+ export type RootParamList = {
103
+ Home: undefined;
104
+ Product: { id: string };
105
+ };
106
+
107
+ // ❌ Bad
108
+ navigation.navigate("Product", { id: 123 as any });
109
+ ```
110
+
111
+ ## State: Zustand + TanStack Query
112
+
113
+ | Concern | Tool |
114
+ | ----------------------- | ----------------------------------------------- |
115
+ | Server/async cache | **TanStack Query** (`useQuery` / `useMutation`) |
116
+ | Client UI/session prefs | **Zustand** |
117
+ | Form ephemeral state | Local `useState` / React Hook Form |
118
+
119
+ ```ts
120
+ // ✅ Good — server state in Query
121
+ const { data } = useQuery({ queryKey: ["products", id], queryFn: () => productsApi.get(id) });
122
+
123
+ // ✅ Good — client flags in Zustand
124
+ const theme = useSettingsStore((s) => s.theme);
125
+
126
+ // ❌ Bad — mirror server lists into Zustand
127
+ const setProducts = useCatalogStore((s) => s.setProducts);
128
+ useEffect(() => {
129
+ productsApi.list().then(setProducts);
130
+ }, []);
131
+ ```
132
+
133
+ **Dependency rules for stores**
134
+
135
+ - Selectors must be narrow: `useStore(s => s.user.id)` not `useStore(s => s)`.
136
+ - No importing React components into store modules.
137
+ - Persist only intentional slices (see **Zustand — Persist middleware**).
138
+
139
+ ## Dependency rules (enforce in review)
140
+
141
+ 1. `app/` / screens → features + shared (not services directly if a hook exists).
142
+ 2. `features/x/components` → same-feature hooks/types; not sibling features.
143
+ 3. `services` → `shared/lib`, never UI.
144
+ 4. No circular imports; break cycles via `types/` or `index.ts` re-exports.
145
+ 5. Native modules and SDKs only behind `services/` or `shared/lib`.
146
+
147
+ ## Error boundaries
148
+
149
+ - Wrap each root tab / stack with an error boundary.
150
+ - Use `react-native-error-boundary` or a small class boundary; log to Sentry/Crashlytics in `onError`.
151
+ - Failed Query states stay in the feature UI; boundaries catch render crashes.
152
+
153
+ ```tsx
154
+ // ✅ Good
155
+ <ErrorBoundary fallback={<CrashScreen />} onError={reportError}>
156
+ <FeatureRoot />
157
+ </ErrorBoundary>
158
+
159
+ // ❌ Bad — uncaught render throw kills the whole app with no recovery
160
+ ```
161
+
162
+ ## Env config
163
+
164
+ - Use **Expo** `app.config.ts` + `expo-constants` / `expo-env`, or `react-native-config` for bare.
165
+ - Never import secrets into client bundles that are not meant to be public.
166
+ - Gate with a typed config module:
167
+
168
+ ```ts
169
+ // src/config/env.ts
170
+ import Constants from "expo-constants";
171
+
172
+ const extra = Constants.expoConfig?.extra ?? {};
173
+
174
+ export const env = {
175
+ apiUrl: String(extra.apiUrl ?? ""),
176
+ appEnv: (extra.appEnv ?? "development") as "development" | "staging" | "production",
177
+ };
178
+
179
+ if (!env.apiUrl) throw new Error("Missing extra.apiUrl");
180
+ ```
181
+
182
+ ```ts
183
+ // ❌ Bad
184
+ const API = process.env.API_URL; // untyped, often undefined in RN without a plugin
185
+ ```
186
+
187
+ ## Scalability rules
188
+
189
+ - New product area → new `features/<name>` with its own `index.ts`.
190
+ - Cap shared UI: if only one feature uses it, move it into that feature.
191
+ - Prefer FlashList for long lists; virtualize by default.
192
+ - Code-split heavy screens with lazy routes / `React.lazy` where the bundler supports it.
193
+ - Feature flags live in `config/`, not scattered magic booleans.
194
+ - Keep `shared/types` for cross-cutting DTOs only; feature-specific types stay local.
195
+
196
+ ## Common mistakes
197
+
198
+ 1. **Type-based folders at scale** — `src/components/Button123.tsx` with no owner.
199
+ 2. **God store** — one Zustand store for server + UI + navigation.
200
+ 3. **Fetching in `useEffect` + `useState`** instead of TanStack Query.
201
+ 4. **Cross-feature deep imports** that break encapsulation.
202
+ 5. **Business logic in screen files** (hard to test, hard to reuse).
203
+ 6. **Untyped navigation params** and `as any` casts.
204
+ 7. **Shipping `.env` secrets** that belong only on the server.
205
+ 8. **No error boundary** around navigators → white screen of death.
206
+ 9. **Circular feature imports** via barrel files that re-export everything.
207
+ 10. **Ignoring official patterns** — reinvent routing instead of Expo Router / React Navigation docs.