rn-agent-kit 0.0.0-stage → 0.2.1
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 +291 -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 +66 -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,247 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: rn-typescript-react
|
|
3
|
+
description: >-
|
|
4
|
+
Strict TypeScript and React Native UI patterns: no any, discriminated unions,
|
|
5
|
+
zod validation, hooks rules, memoization guidance, FlatList/FlashList,
|
|
6
|
+
re-renders, naming, Jest + RNTL, ESLint. Use when writing or reviewing TS/TSX,
|
|
7
|
+
fixing type errors, optimizing lists, adding tests, or configuring eslint/tsconfig.
|
|
8
|
+
globs: "**/*.{ts,tsx}"
|
|
9
|
+
alwaysApply: false
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# rn-typescript-react
|
|
13
|
+
|
|
14
|
+
Target **TypeScript strict mode**, **React 18+ / RN New Architecture–ready** patterns, and current **Jest** + **React Native Testing Library** APIs. Cite **TypeScript Handbook**, **React docs**, **React Native docs**, **Zod**, **TanStack Query**, and **Testing Library — React Native**.
|
|
15
|
+
|
|
16
|
+
## Strict tsconfig
|
|
17
|
+
|
|
18
|
+
```json
|
|
19
|
+
{
|
|
20
|
+
"extends": "expo/tsconfig.base",
|
|
21
|
+
"compilerOptions": {
|
|
22
|
+
"strict": true,
|
|
23
|
+
"noUncheckedIndexedAccess": true,
|
|
24
|
+
"noImplicitOverride": true,
|
|
25
|
+
"exactOptionalPropertyTypes": true,
|
|
26
|
+
"noFallthroughCasesInSwitch": true,
|
|
27
|
+
"skipLibCheck": true
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Enable path aliases (`@/*`) in both `tsconfig` and Babel (`babel-plugin-module-resolver` or Expo defaults).
|
|
33
|
+
|
|
34
|
+
## No `any`
|
|
35
|
+
|
|
36
|
+
- Prefer `unknown` + narrowing, generics, or `zod` inference.
|
|
37
|
+
- ESLint: `@typescript-eslint/no-explicit-any`: `error`.
|
|
38
|
+
- Avoid `as any`; use `satisfies`, type guards, or schema parse.
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
// ✅ Good
|
|
42
|
+
function parseUser(input: unknown): User {
|
|
43
|
+
return userSchema.parse(input);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
// ❌ Bad
|
|
47
|
+
function parseUser(input: any) {
|
|
48
|
+
return input as User;
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Discriminated unions
|
|
53
|
+
|
|
54
|
+
Model UI and domain states as unions with a `type` / `status` tag.
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
// ✅ Good
|
|
58
|
+
type LoadState<T> =
|
|
59
|
+
| { status: "idle" }
|
|
60
|
+
| { status: "loading" }
|
|
61
|
+
| { status: "success"; data: T }
|
|
62
|
+
| { status: "error"; error: Error };
|
|
63
|
+
|
|
64
|
+
function View({ state }: { state: LoadState<Product> }) {
|
|
65
|
+
switch (state.status) {
|
|
66
|
+
case "idle":
|
|
67
|
+
case "loading":
|
|
68
|
+
return <Spinner />;
|
|
69
|
+
case "success":
|
|
70
|
+
return <ProductCard product={state.data} />;
|
|
71
|
+
case "error":
|
|
72
|
+
return <ErrorText message={state.error.message} />;
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
// ❌ Bad — optional fields that lie
|
|
77
|
+
type LoadState = { loading: boolean; data?: Product; error?: string };
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Zod for runtime validation
|
|
81
|
+
|
|
82
|
+
Validate **boundaries**: API JSON, route params, SecureStore, form payloads.
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
import { z } from "zod";
|
|
86
|
+
|
|
87
|
+
export const productSchema = z.object({
|
|
88
|
+
id: z.string().min(1),
|
|
89
|
+
title: z.string(),
|
|
90
|
+
priceCents: z.number().int().nonnegative(),
|
|
91
|
+
});
|
|
92
|
+
export type Product = z.infer<typeof productSchema>;
|
|
93
|
+
|
|
94
|
+
// ✅ Good — parse at the edge
|
|
95
|
+
export async function getProduct(id: string): Promise<Product> {
|
|
96
|
+
const json: unknown = await api.get(`/products/${id}`);
|
|
97
|
+
return productSchema.parse(json);
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
// ❌ Bad — trust network shapes
|
|
101
|
+
export async function getProduct(id: string): Promise<Product> {
|
|
102
|
+
return api.get(`/products/${id}`);
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Hooks rules
|
|
107
|
+
|
|
108
|
+
- Only call hooks at top level of React functions (see **Rules of Hooks**).
|
|
109
|
+
- Custom hooks: `use*` prefix; return stable tuples/objects intentionally.
|
|
110
|
+
- Put side effects in `useEffect` with correct deps; prefer Query/Mutation over manual effects for server I/O.
|
|
111
|
+
- Don’t conditionally define components inside parents (remounts + hook resets).
|
|
112
|
+
|
|
113
|
+
```tsx
|
|
114
|
+
// ❌ Bad
|
|
115
|
+
function Screen({ items }) {
|
|
116
|
+
if (!items) return null;
|
|
117
|
+
const [x, setX] = useState(0); // conditional hook
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Memoization — when NOT to use it
|
|
122
|
+
|
|
123
|
+
**Do not** default to `useMemo` / `useCallback` / `React.memo`.
|
|
124
|
+
|
|
125
|
+
Use them only when:
|
|
126
|
+
|
|
127
|
+
1. Referential equality is required by a child that is expensive **and** memoized, or
|
|
128
|
+
2. A dependency array would otherwise change every render and trigger expensive work, or
|
|
129
|
+
3. Profiling shows a real cost.
|
|
130
|
+
|
|
131
|
+
```tsx
|
|
132
|
+
// ✅ Good — plain handler; child is a light View
|
|
133
|
+
<Button onPress={() => submit(id)} />;
|
|
134
|
+
|
|
135
|
+
// ❌ Bad — cargo-cult memo
|
|
136
|
+
const onPress = useCallback(() => submit(id), [id]);
|
|
137
|
+
const title = useMemo(() => "Save", []);
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Prefer **state colocation**, **narrow Zustand selectors**, and **Query select** over memo wrappers.
|
|
141
|
+
|
|
142
|
+
## FlatList / FlashList performance
|
|
143
|
+
|
|
144
|
+
Prefer **`@shopify/flash-list`** for long lists (see **FlashList docs**). Otherwise optimize FlatList:
|
|
145
|
+
|
|
146
|
+
- `keyExtractor` stable and unique
|
|
147
|
+
- `getItemType` / `overrideItemLayout` when using FlashList
|
|
148
|
+
- Avoid inline `renderItem` props that close over changing objects when the row is memoized—pass `item` only
|
|
149
|
+
- `estimatedItemSize` (FlashList) required
|
|
150
|
+
- Don’t put heavy work in `renderItem`; precompute in data layer
|
|
151
|
+
|
|
152
|
+
```tsx
|
|
153
|
+
// ✅ Good
|
|
154
|
+
const renderItem = useCallback(({ item }: { item: Product }) => <ProductRow product={item} />, []);
|
|
155
|
+
<FlashList data={products} renderItem={renderItem} estimatedItemSize={72} />;
|
|
156
|
+
|
|
157
|
+
// ❌ Bad
|
|
158
|
+
<FlatList
|
|
159
|
+
data={products}
|
|
160
|
+
renderItem={({ item }) => (
|
|
161
|
+
<ProductRow product={item} style={{ margin: Math.random() }} extra={entireStore} />
|
|
162
|
+
)}
|
|
163
|
+
/>;
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
## Avoiding re-renders
|
|
167
|
+
|
|
168
|
+
- Split components so list rows don’t subscribe to whole-app state.
|
|
169
|
+
- Zustand: `useStore(s => s.count)` not `useStore()`.
|
|
170
|
+
- Context: split state/dispatch contexts; don’t put frequently changing values in a giant provider.
|
|
171
|
+
- Pass `id` + selectors instead of fat objects when possible.
|
|
172
|
+
- Images: known size; avoid animating layout thrash on every frame without `useNativeDriver` / Reanimated.
|
|
173
|
+
|
|
174
|
+
## Naming conventions
|
|
175
|
+
|
|
176
|
+
| Kind | Pattern | Example |
|
|
177
|
+
| ------------------ | ----------------- | ------------------------ |
|
|
178
|
+
| Component | PascalCase | `ProductCard` |
|
|
179
|
+
| Hook | `use` + camelCase | `useProduct` |
|
|
180
|
+
| Screen | `*Screen` | `ProductScreen` |
|
|
181
|
+
| Service fn | verb + noun | `fetchProduct` |
|
|
182
|
+
| Zustand store | `use*Store` | `useSettingsStore` |
|
|
183
|
+
| Types | PascalCase | `Product` |
|
|
184
|
+
| Zod schema | `*Schema` | `productSchema` |
|
|
185
|
+
| Query key | factory | `productKeys.detail(id)` |
|
|
186
|
+
| Boolean | `is`/`has`/`can` | `isLoading` |
|
|
187
|
+
| Event handler prop | `on*` | `onSubmit` |
|
|
188
|
+
| Local handler | `handle*` | `handleSubmit` |
|
|
189
|
+
|
|
190
|
+
Files: `ProductCard.tsx`, `useProduct.ts`, `productSchema.ts`. Avoid `index.tsx` for non-barrel screens when it hurts searchability.
|
|
191
|
+
|
|
192
|
+
## Testing (Jest + RNTL)
|
|
193
|
+
|
|
194
|
+
Cite **React Native Testing Library** queries (`getByRole`, `getByText`, `getByLabelText`). Prefer user-centric assertions.
|
|
195
|
+
|
|
196
|
+
```tsx
|
|
197
|
+
import { render, screen, userEvent } from "@testing-library/react-native";
|
|
198
|
+
|
|
199
|
+
it("submits email", async () => {
|
|
200
|
+
const user = userEvent.setup();
|
|
201
|
+
const onSubmit = jest.fn();
|
|
202
|
+
render(<LoginForm onSubmit={onSubmit} />);
|
|
203
|
+
await user.type(screen.getByLabelText("Email"), "a@b.com");
|
|
204
|
+
await user.press(screen.getByRole("button", { name: "Sign in" }));
|
|
205
|
+
expect(onSubmit).toHaveBeenCalledWith({ email: "a@b.com" });
|
|
206
|
+
});
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
- Mock network at the service boundary or MSW; don’t assert on implementation details of hooks.
|
|
210
|
+
- Use `@testing-library/react-native` async utilities; avoid manual `act` unless required.
|
|
211
|
+
- Snapshot sparingly—prefer behavior tests.
|
|
212
|
+
|
|
213
|
+
## ESLint (baseline)
|
|
214
|
+
|
|
215
|
+
```js
|
|
216
|
+
// eslint.config.js — sketch; adapt to flat config + RN
|
|
217
|
+
{
|
|
218
|
+
extends: [
|
|
219
|
+
"eslint:recommended",
|
|
220
|
+
"plugin:@typescript-eslint/recommended-type-checked",
|
|
221
|
+
"plugin:react/recommended",
|
|
222
|
+
"plugin:react-hooks/recommended",
|
|
223
|
+
"plugin:react-native/all",
|
|
224
|
+
],
|
|
225
|
+
rules: {
|
|
226
|
+
"@typescript-eslint/no-explicit-any": "error",
|
|
227
|
+
"@typescript-eslint/consistent-type-imports": "error",
|
|
228
|
+
"react/react-in-jsx-scope": "off",
|
|
229
|
+
"react-hooks/exhaustive-deps": "error",
|
|
230
|
+
},
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Pair with **Prettier**; don’t fight formatting in ESLint.
|
|
235
|
+
|
|
236
|
+
## Common mistakes
|
|
237
|
+
|
|
238
|
+
1. Disabling `strict` or sprinkling `any` / `@ts-ignore` to “save time”.
|
|
239
|
+
2. Optional-field state machines instead of discriminated unions.
|
|
240
|
+
3. Trusting API JSON without **Zod** (or similar) at the boundary.
|
|
241
|
+
4. Wrapping everything in `useCallback`/`memo` without a measured need.
|
|
242
|
+
5. Anonymous `renderItem` with unstable props → row thrashing.
|
|
243
|
+
6. Selecting entire Zustand store → render storms.
|
|
244
|
+
7. Testing implementation (`useState` calls) instead of UI behavior.
|
|
245
|
+
8. `console.log` debugging left in list `renderItem`.
|
|
246
|
+
9. Incorrect hook dependency arrays silencing `exhaustive-deps`.
|
|
247
|
+
10. Using outdated Testing Library APIs (`getByTestId` as first choice, shallow enzyme).
|
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ticket-to-code
|
|
3
|
+
description: >-
|
|
4
|
+
Implement a Jira Story (or Epic stories sequentially) with a strict
|
|
5
|
+
red-green workflow: read ticket+Figma, branch, failing Maestro/unit tests
|
|
6
|
+
first, then code with theme tokens and ticket testIDs, green CI, PR + Jira
|
|
7
|
+
"In Review". Use when the user says "Implement APP-123", "work this ticket",
|
|
8
|
+
or hands a Jira/Epic key after prd-to-jira. Never write feature code before
|
|
9
|
+
failing tests are committed.
|
|
10
|
+
globs: "**/*.{ts,tsx,js,jsx,yaml,yml}"
|
|
11
|
+
alwaysApply: false
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# ticket-to-code
|
|
15
|
+
|
|
16
|
+
Turn a **Jira Story** into a PR using TDD with Maestro. Depends on **prd-to-jira**, **maestro-e2e**, **rn-architecture**, **rn-typescript-react**, **figma-to-tokens**, and Atlassian + Figma MCP.
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
Jira key (Story or Epic)
|
|
20
|
+
│
|
|
21
|
+
▼
|
|
22
|
+
Read ticket + epic + siblings + Figma node
|
|
23
|
+
│
|
|
24
|
+
▼
|
|
25
|
+
Branch feature/<KEY>-slug · status → In Progress
|
|
26
|
+
│
|
|
27
|
+
▼
|
|
28
|
+
STEP A Failing Maestro + unit stubs → commit test(<KEY>): …
|
|
29
|
+
│
|
|
30
|
+
▼
|
|
31
|
+
STEP B Implement (theme tokens, architecture, exact testIDs)
|
|
32
|
+
│
|
|
33
|
+
▼
|
|
34
|
+
STEP C tsc · eslint · jest · Maestro (≤5 fix loops)
|
|
35
|
+
│
|
|
36
|
+
▼
|
|
37
|
+
PR + Jira comment + status → In Review
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Hard rules (strict order — do not skip or reorder)
|
|
41
|
+
|
|
42
|
+
1. **No feature code before STEP A is committed.** Writing screens/hooks before the red tests exist is a process failure — stop and revert if you did.
|
|
43
|
+
2. **Never edit a test only to make it pass.** If the flow disagrees with the product, either fix the code or **update the Jira AC / TC first**, then change the test to match the new AC.
|
|
44
|
+
3. **Use exact `testIDs` from the ticket.** Do not invent parallel IDs.
|
|
45
|
+
4. **UI uses theme tokens only** (`useTheme()` / generated `tokens.ts`). No hardcoded colors/spacing/fonts (see ESLint `no-hardcoded-design-values`).
|
|
46
|
+
5. **Follow `rn-architecture`** (feature folders, layers, Query/Zustand rules).
|
|
47
|
+
6. **Max 5 fix iterations** in STEP C. If still red, comment findings on the Jira ticket and **stop** (do not open a “greenwashed” PR).
|
|
48
|
+
7. **One PR per Story.** If given an **Epic** key, process stories **sequentially** (map order or rank), finishing each Story’s PR before starting the next.
|
|
49
|
+
8. Commit messages and PR title include the Jira key (`APP-123`).
|
|
50
|
+
|
|
51
|
+
## Step 0 — Intake
|
|
52
|
+
|
|
53
|
+
1. Parse the key from the user (`Implement APP-123` / Epic `APP-100`).
|
|
54
|
+
2. Via **Atlassian MCP**: fetch the issue, **parent Epic**, and **sibling** stories/sub-tasks (for context; do not implement siblings in the same PR unless asked).
|
|
55
|
+
3. Extract: summary, Gherkin AC, testIDs, TC-IDs, Figma URL / node, API contracts, states, DoD.
|
|
56
|
+
4. Via **Figma MCP**: open the linked node (`get_design_context` / screenshot) — implement to that frame + `design/tokens.json`.
|
|
57
|
+
5. Read `.agent/jira-map.json` if present for related keys.
|
|
58
|
+
|
|
59
|
+
If AC / testIDs / Figma link are missing, run **jira-validate** expectations mentally and **comment on Jira** asking for fixes — do not invent AC.
|
|
60
|
+
|
|
61
|
+
## Step 1 — Branch + In Progress
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
git fetch origin
|
|
65
|
+
git checkout -b feature/APP-123-login-screen # feature/<JIRA-KEY>-<slug>
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
- Transition the **Story** to **In Progress** (Atlassian MCP / transition tool).
|
|
69
|
+
- Sub-tasks: move the relevant ones (UI / API / E2E / a11y) as you enter each phase; at minimum the Story is In Progress before STEP A commit.
|
|
70
|
+
|
|
71
|
+
## STEP A — Tests first (must go red)
|
|
72
|
+
|
|
73
|
+
Create:
|
|
74
|
+
|
|
75
|
+
1. **Maestro** flows per TC ID — follow **maestro-e2e**:
|
|
76
|
+
- `maestro/flows/<feature>/TC-….yaml`
|
|
77
|
+
- Selectors = ticket testIDs only
|
|
78
|
+
2. **Unit / component stubs** (Jest + RNTL) that assert critical behavior from AC (at least one failing test per Story).
|
|
79
|
+
|
|
80
|
+
Run:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
npm test -- <path-to-new-tests> # expect FAIL
|
|
84
|
+
maestro test maestro/flows/<feature>/TC-….yaml # expect FAIL (missing UI / ids)
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
**Confirm they fail (red).** If they pass, the tests are wrong (asserting nothing) — fix the tests, not the app.
|
|
88
|
+
|
|
89
|
+
Commit **only** tests (and empty stubs if required by the test runner):
|
|
90
|
+
|
|
91
|
+
```text
|
|
92
|
+
test(APP-123): add failing e2e tests
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Do **not** include production feature implementation in this commit.
|
|
96
|
+
|
|
97
|
+
## STEP B — Code
|
|
98
|
+
|
|
99
|
+
Only after STEP A commit exists on the branch:
|
|
100
|
+
|
|
101
|
+
1. Implement UI in `src/features/<feature>/…` per architecture skill.
|
|
102
|
+
2. Wire `testID`s **exactly** as listed on the ticket.
|
|
103
|
+
3. Use `useTheme()` / tokens; match Figma within token system.
|
|
104
|
+
4. Implement loading / empty / error states from the ticket.
|
|
105
|
+
5. API via services + zod; TanStack Query for server state.
|
|
106
|
+
6. Add Maestro-facing screens to navigation only as needed for the Story.
|
|
107
|
+
|
|
108
|
+
## STEP C — Make green (≤ 5 iterations)
|
|
109
|
+
|
|
110
|
+
Run in order; fix failures; re-run:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
npx tsc --noEmit
|
|
114
|
+
npm run lint
|
|
115
|
+
npm test
|
|
116
|
+
maestro test maestro/flows/<feature>/TC-….yaml
|
|
117
|
+
# or: maestro test --include-tags smoke …
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
| Iteration | Action |
|
|
121
|
+
| --------- | ---------------------------------------------------------------------------: |
|
|
122
|
+
| 1–5 | Fix **product code** (or test bugs that violate AC — rare). Re-run full set. |
|
|
123
|
+
| After 5 | Comment on Jira with logs, failing TC IDs, hypothesis; **stop**. |
|
|
124
|
+
|
|
125
|
+
Never “skip” a Maestro assertion to go green.
|
|
126
|
+
|
|
127
|
+
## Step 4 — PR + Jira
|
|
128
|
+
|
|
129
|
+
When green:
|
|
130
|
+
|
|
131
|
+
1. Push branch; open PR:
|
|
132
|
+
- Title: `APP-123: <short summary>`
|
|
133
|
+
- Body: AC checklist, test plan, screenshots or Maestro recording, link to Figma node, note tokens used
|
|
134
|
+
2. Comment on Jira with PR URL + test results summary.
|
|
135
|
+
3. Transition Story → **In Review** (or team equivalent).
|
|
136
|
+
|
|
137
|
+
## Epic mode
|
|
138
|
+
|
|
139
|
+
If the key is an Epic:
|
|
140
|
+
|
|
141
|
+
1. List child Stories (from Jira + `.agent/jira-map.json`).
|
|
142
|
+
2. For **each** Story, run this skill end-to-end (branch → A → B → C → PR).
|
|
143
|
+
3. Do not combine multiple Stories in one PR.
|
|
144
|
+
4. After each PR, move on to the next Story.
|
|
145
|
+
|
|
146
|
+
## Mapping to sub-tasks
|
|
147
|
+
|
|
148
|
+
| Sub-task (from prd-to-jira) | When |
|
|
149
|
+
| --------------------------- | ------------------------------------------------------- |
|
|
150
|
+
| E2E test (Maestro) | STEP A (+ keep green in C) |
|
|
151
|
+
| UI build | STEP B |
|
|
152
|
+
| State / API | STEP B |
|
|
153
|
+
| Accessibility | STEP B/C — labels, roles; assert key a11y ids if listed |
|
|
154
|
+
|
|
155
|
+
## GOOD / BAD
|
|
156
|
+
|
|
157
|
+
```tsx
|
|
158
|
+
// ✅ GOOD — ticket testID + theme
|
|
159
|
+
const { colors, spacing } = useTheme();
|
|
160
|
+
<TextInput testID="login-email" style={{ color: colors.text.primary, margin: spacing.md }} />
|
|
161
|
+
|
|
162
|
+
// ❌ BAD — before STEP A commit, or invented id / hardcoded color
|
|
163
|
+
<TextInput testID="emailField" style={{ color: "#111", margin: 16 }} />
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
```yaml
|
|
167
|
+
# ✅ GOOD — TC file, id selectors
|
|
168
|
+
- tapOn: { id: login-submit }
|
|
169
|
+
|
|
170
|
+
# ❌ BAD — weakened test to match buggy UI
|
|
171
|
+
- tapOn: "Submit" # or optional: true on a required assert
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
## Common mistakes
|
|
175
|
+
|
|
176
|
+
1. Implementing UI, then writing tests that mirror bugs.
|
|
177
|
+
2. Changing Maestro flows instead of fixing missing `testID`s.
|
|
178
|
+
3. One PR for the whole Epic.
|
|
179
|
+
4. Forgetting to move Jira status / leave a PR comment.
|
|
180
|
+
5. Hardcoding design values despite tokens.
|
|
181
|
+
6. Claiming green without running Maestro locally.
|
|
182
|
+
7. Quietly exceeding 5 fix loops without commenting on Jira.
|
|
183
|
+
|
|
184
|
+
## Done checklist
|
|
185
|
+
|
|
186
|
+
- [ ] Ticket + Epic + Figma node read
|
|
187
|
+
- [ ] Branch `feature/<KEY>-slug` · In Progress
|
|
188
|
+
- [ ] STEP A committed red: `test(<KEY>): add failing e2e tests`
|
|
189
|
+
- [ ] STEP B used theme + architecture + exact testIDs
|
|
190
|
+
- [ ] STEP C: tsc, eslint, jest, Maestro green (or stopped ≤5 with Jira comment)
|
|
191
|
+
- [ ] PR opened · Jira commented · In Review
|
|
192
|
+
- [ ] Epic: one Story at a time
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
// Add to your project's eslint.config.mjs (init copies the rule file to tools/eslint/).
|
|
2
|
+
import { createRequire } from "node:module";
|
|
3
|
+
const require = createRequire(import.meta.url);
|
|
4
|
+
const rnAgentKit = require("./tools/eslint/rn-agent-kit-rules.cjs");
|
|
5
|
+
|
|
6
|
+
export default [
|
|
7
|
+
{ ignores: ["src/shared/theme/tokens.ts"] }, // generated
|
|
8
|
+
{
|
|
9
|
+
files: ["src/**/*.{ts,tsx}"],
|
|
10
|
+
plugins: { "rn-agent-kit": rnAgentKit },
|
|
11
|
+
rules: {
|
|
12
|
+
// Existing project with lots of legacy styles? start with { checkDimensions: false } and tighten later.
|
|
13
|
+
"rn-agent-kit/no-hardcoded-design-values": ["error", {}],
|
|
14
|
+
},
|
|
15
|
+
},
|
|
16
|
+
];
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* ESLint plugin: rn-agent-kit/no-hardcoded-design-values
|
|
4
|
+
* Components must read colors, fonts and spacing from the generated theme (useTheme()), never literals.
|
|
5
|
+
*/
|
|
6
|
+
const COLOR_RE =
|
|
7
|
+
/^\s*(#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})|(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklch)\([^)]*\))\s*$/i;
|
|
8
|
+
const NAMED_COLORS = new Set([
|
|
9
|
+
"white",
|
|
10
|
+
"black",
|
|
11
|
+
"red",
|
|
12
|
+
"green",
|
|
13
|
+
"blue",
|
|
14
|
+
"yellow",
|
|
15
|
+
"orange",
|
|
16
|
+
"purple",
|
|
17
|
+
"pink",
|
|
18
|
+
"gray",
|
|
19
|
+
"grey",
|
|
20
|
+
"brown",
|
|
21
|
+
"cyan",
|
|
22
|
+
"magenta",
|
|
23
|
+
"teal",
|
|
24
|
+
"navy",
|
|
25
|
+
"silver",
|
|
26
|
+
"gold",
|
|
27
|
+
]);
|
|
28
|
+
const COLOR_PROP = /colou?r$/i;
|
|
29
|
+
const FONT_PROP = /^fontFamily$/;
|
|
30
|
+
const SPACING_PROP =
|
|
31
|
+
/^(margin|padding)(Top|Bottom|Left|Right|Horizontal|Vertical|Start|End)?$|^(gap|rowGap|columnGap)$|^border(Top|Bottom)?(Left|Right|Start|End)?Radius$/;
|
|
32
|
+
const TYPE_SIZE_PROP = /^(fontSize|lineHeight|letterSpacing)$/;
|
|
33
|
+
const DEFAULT_ALLOWED_PATHS = [
|
|
34
|
+
"/shared/theme/",
|
|
35
|
+
"/design/",
|
|
36
|
+
".test.",
|
|
37
|
+
".spec.",
|
|
38
|
+
"__tests__",
|
|
39
|
+
".config.",
|
|
40
|
+
];
|
|
41
|
+
|
|
42
|
+
const rule = {
|
|
43
|
+
meta: {
|
|
44
|
+
type: "problem",
|
|
45
|
+
docs: {
|
|
46
|
+
description: "Disallow hardcoded colors, font families and spacing; use theme tokens.",
|
|
47
|
+
},
|
|
48
|
+
schema: [
|
|
49
|
+
{
|
|
50
|
+
type: "object",
|
|
51
|
+
properties: {
|
|
52
|
+
allowedPaths: { type: "array", items: { type: "string" } },
|
|
53
|
+
allowedValues: { type: "array", items: { type: "string" } },
|
|
54
|
+
allowedNumbers: { type: "array", items: { type: "number" } },
|
|
55
|
+
checkColors: { type: "boolean" },
|
|
56
|
+
checkFonts: { type: "boolean" },
|
|
57
|
+
checkDimensions: { type: "boolean" },
|
|
58
|
+
},
|
|
59
|
+
additionalProperties: false,
|
|
60
|
+
},
|
|
61
|
+
],
|
|
62
|
+
messages: {
|
|
63
|
+
hardcodedColor:
|
|
64
|
+
'Hardcoded color "{{value}}". Use a theme token, e.g. theme.colors.<group>.<name> from useTheme().',
|
|
65
|
+
hardcodedFont:
|
|
66
|
+
'Hardcoded fontFamily "{{value}}". Use theme.typography.* or theme.fontFamilies.*.',
|
|
67
|
+
hardcodedDimension:
|
|
68
|
+
"Hardcoded {{prop}}: {{value}}. Use theme.spacing.* / theme.radius.* / theme.typography.*.",
|
|
69
|
+
},
|
|
70
|
+
},
|
|
71
|
+
create(context) {
|
|
72
|
+
const opts = context.options[0] || {};
|
|
73
|
+
const file = String(context.filename || context.getFilename()).replace(/\\/g, "/");
|
|
74
|
+
if ((opts.allowedPaths || DEFAULT_ALLOWED_PATHS).some((p) => file.includes(p))) return {};
|
|
75
|
+
const allowedValues = new Set(
|
|
76
|
+
(opts.allowedValues || ["transparent", "currentcolor", "inherit"]).map((v) =>
|
|
77
|
+
v.toLowerCase(),
|
|
78
|
+
),
|
|
79
|
+
);
|
|
80
|
+
const allowedNumbers = new Set(opts.allowedNumbers || [0]);
|
|
81
|
+
const checkColors = opts.checkColors !== false;
|
|
82
|
+
const checkFonts = opts.checkFonts !== false;
|
|
83
|
+
const checkDimensions = opts.checkDimensions !== false;
|
|
84
|
+
|
|
85
|
+
const keyName = (prop) => {
|
|
86
|
+
if (prop.computed) return null;
|
|
87
|
+
if (prop.key.type === "Identifier") return prop.key.name;
|
|
88
|
+
if (prop.key.type === "Literal") return String(prop.key.value);
|
|
89
|
+
return null;
|
|
90
|
+
};
|
|
91
|
+
const reportColor = (node, value) => {
|
|
92
|
+
if (!allowedValues.has(String(value).trim().toLowerCase()))
|
|
93
|
+
context.report({ node, messageId: "hardcodedColor", data: { value } });
|
|
94
|
+
};
|
|
95
|
+
|
|
96
|
+
return {
|
|
97
|
+
Literal(node) {
|
|
98
|
+
if (checkColors && typeof node.value === "string" && COLOR_RE.test(node.value))
|
|
99
|
+
reportColor(node, node.value);
|
|
100
|
+
},
|
|
101
|
+
TemplateLiteral(node) {
|
|
102
|
+
if (!checkColors || node.expressions.length) return;
|
|
103
|
+
const text = node.quasis[0] && node.quasis[0].value.cooked;
|
|
104
|
+
if (text && COLOR_RE.test(text)) reportColor(node, text);
|
|
105
|
+
},
|
|
106
|
+
Property(node) {
|
|
107
|
+
const name = keyName(node);
|
|
108
|
+
if (!name || node.value.type !== "Literal") return;
|
|
109
|
+
const v = node.value.value;
|
|
110
|
+
if (
|
|
111
|
+
checkColors &&
|
|
112
|
+
COLOR_PROP.test(name) &&
|
|
113
|
+
typeof v === "string" &&
|
|
114
|
+
!COLOR_RE.test(v) &&
|
|
115
|
+
NAMED_COLORS.has(v.toLowerCase())
|
|
116
|
+
) {
|
|
117
|
+
reportColor(node.value, v);
|
|
118
|
+
} else if (checkFonts && FONT_PROP.test(name) && typeof v === "string") {
|
|
119
|
+
context.report({ node: node.value, messageId: "hardcodedFont", data: { value: v } });
|
|
120
|
+
} else if (
|
|
121
|
+
checkDimensions &&
|
|
122
|
+
(SPACING_PROP.test(name) || TYPE_SIZE_PROP.test(name)) &&
|
|
123
|
+
typeof v === "number" &&
|
|
124
|
+
!allowedNumbers.has(v)
|
|
125
|
+
) {
|
|
126
|
+
context.report({
|
|
127
|
+
node: node.value,
|
|
128
|
+
messageId: "hardcodedDimension",
|
|
129
|
+
data: { prop: name, value: String(v) },
|
|
130
|
+
});
|
|
131
|
+
}
|
|
132
|
+
},
|
|
133
|
+
};
|
|
134
|
+
},
|
|
135
|
+
};
|
|
136
|
+
|
|
137
|
+
module.exports = { meta: { name: "rn-agent-kit" }, rules: { "no-hardcoded-design-values": rule } };
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# {{SUMMARY}}
|
|
2
|
+
|
|
3
|
+
> Type: `{{TYPE}}` · Parent: `{{PARENT_KEY}}` · Project: `{{PROJECT_KEY}}`
|
|
4
|
+
|
|
5
|
+
## Figma
|
|
6
|
+
|
|
7
|
+
- **Screen:** {{SCREEN_NAME}}
|
|
8
|
+
- **Node ID:** `{{FIGMA_NODE_ID}}`
|
|
9
|
+
- **Link:** {{FIGMA_URL}}
|
|
10
|
+
|
|
11
|
+
<!-- Use NEEDS_FIGMA (and explain the gap) when the PRD feature has no matching frame. -->
|
|
12
|
+
|
|
13
|
+
## Acceptance Criteria (Gherkin)
|
|
14
|
+
|
|
15
|
+
```gherkin
|
|
16
|
+
Feature: {{FEATURE_NAME}}
|
|
17
|
+
|
|
18
|
+
Scenario: Happy path
|
|
19
|
+
Given {{GIVEN_HAPPY}}
|
|
20
|
+
When {{WHEN_HAPPY}}
|
|
21
|
+
Then {{THEN_HAPPY}}
|
|
22
|
+
|
|
23
|
+
Scenario: Error / empty path
|
|
24
|
+
Given {{GIVEN_ERROR}}
|
|
25
|
+
When {{WHEN_ERROR}}
|
|
26
|
+
Then {{THEN_ERROR}}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## testIDs
|
|
30
|
+
|
|
31
|
+
Key elements that must exist in the UI (and Maestro / RNTL selectors):
|
|
32
|
+
|
|
33
|
+
- `{{TEST_ID_1}}`
|
|
34
|
+
- `{{TEST_ID_2}}`
|
|
35
|
+
- `{{TEST_ID_3}}`
|
|
36
|
+
|
|
37
|
+
## API contracts
|
|
38
|
+
|
|
39
|
+
{{API_CONTRACTS}}
|
|
40
|
+
|
|
41
|
+
<!-- Example:
|
|
42
|
+
- POST /v1/auth/login
|
|
43
|
+
- body: { email: string, password: string }
|
|
44
|
+
- 200: { accessToken: string, user: { id, email } }
|
|
45
|
+
- 401: { error: "invalid_credentials" }
|
|
46
|
+
Or write: none
|
|
47
|
+
-->
|
|
48
|
+
|
|
49
|
+
## States
|
|
50
|
+
|
|
51
|
+
| State | UX / copy |
|
|
52
|
+
| ------- | ----------------- |
|
|
53
|
+
| loading | {{STATE_LOADING}} |
|
|
54
|
+
| empty | {{STATE_EMPTY}} |
|
|
55
|
+
| error | {{STATE_ERROR}} |
|
|
56
|
+
| success | {{STATE_SUCCESS}} |
|
|
57
|
+
|
|
58
|
+
## Test cases
|
|
59
|
+
|
|
60
|
+
| ID | Title | Maps to |
|
|
61
|
+
| ----------------------- | --------------- | ---------- |
|
|
62
|
+
| `TC-{{PROJECT_KEY}}-01` | {{TC_01_TITLE}} | Happy path |
|
|
63
|
+
| `TC-{{PROJECT_KEY}}-02` | {{TC_02_TITLE}} | Error path |
|
|
64
|
+
|
|
65
|
+
## Definition of Done
|
|
66
|
+
|
|
67
|
+
- [ ] Matches Figma node (spacing/type/color from `design/tokens.json` / theme)
|
|
68
|
+
- [ ] All listed `testIDs` present and stable
|
|
69
|
+
- [ ] Loading / empty / error states implemented
|
|
70
|
+
- [ ] Unit or component tests for core logic (where applicable)
|
|
71
|
+
- [ ] Maestro E2E covers happy path (`maestro/`)
|
|
72
|
+
- [ ] Accessibility: labels, roles, hit targets ≥ 44pt
|
|
73
|
+
- [ ] No hardcoded design values (ESLint `no-hardcoded-design-values`)
|
|
74
|
+
- [ ] Linked PR / CI green
|
|
75
|
+
|
|
76
|
+
## Notes
|
|
77
|
+
|
|
78
|
+
{{NOTES}}
|