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.
- package/LICENSE +21 -0
- package/README.md +176 -2
- package/dist/cli.js +2916 -0
- package/dist/cli.js.map +1 -0
- package/dist/scripts/figma-tokens.js +1284 -0
- package/dist/scripts/figma-tokens.js.map +1 -0
- package/dist/scripts/validate-jira-tickets.js +169 -0
- package/dist/scripts/validate-jira-tickets.js.map +1 -0
- package/package.json +64 -4
- package/skills/expo-cli/SKILL.md +213 -0
- package/skills/figma-to-tokens/SKILL.md +288 -0
- package/skills/github-actions-ci/SKILL.md +124 -0
- package/skills/maestro-e2e/SKILL.md +256 -0
- package/skills/prd-to-jira/SKILL.md +237 -0
- package/skills/rn-architecture/SKILL.md +207 -0
- package/skills/rn-native-android-ios/SKILL.md +195 -0
- package/skills/rn-sdk-integrations/SKILL.md +274 -0
- package/skills/rn-typescript-react/SKILL.md +247 -0
- package/skills/ticket-to-code/SKILL.md +192 -0
- package/templates/config/rn-agent-kit.json +4 -0
- package/templates/eslint/eslint.config.snippet.mjs +16 -0
- package/templates/eslint/rn-agent-kit-rules.cjs +137 -0
- package/templates/jira-ticket.md +78 -0
- package/templates/maestro/smoke.yaml +4 -0
- package/templates/scaffold/.husky/commit-msg +4 -0
- package/templates/scaffold/.husky/pre-commit +4 -0
- package/templates/scaffold/.prettierignore +6 -0
- package/templates/scaffold/.prettierrc +6 -0
- package/templates/scaffold/commitlint.config.cjs +4 -0
- package/templates/scaffold/eslint.config.js +22 -0
- package/templates/scaffold/jest.config.cjs +9 -0
- package/templates/scaffold/tsconfig.json +13 -0
- package/templates/workflows/ci.yml +120 -0
- package/templates/workflows/e2e-android.yml +158 -0
- package/templates/workflows/e2e-ios.yml +134 -0
- 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.
|