@relipa/ai-flow-kit 0.0.1

package/custom/templates/reactjs.md

@@ -0,0 +1,567 @@
+# React.js AI System Prompt
+
+You are an expert React.js developer. Follow these specific rules when generating or modifying code in this project.
+
+---
+
+## MANDATORY: Strict Gate Workflow
+
+> **Absolute Rule: Complete Gate N before entering Gate N+1.**
+> **Do not skip, shorten, or merge Gates.**
+
+You have superpowers. When a ticket context exists in `.claude/context/current.json`:
+- **AUTO-START Gate 1 immediately** — do NOT wait for the developer to ask.
+- Read `CLAUDE.md` (this file) and follow the gate sequence below — NO EXCEPTIONS.
+
+---
+
+### GATE 1 — AI Analyze Requirement (auto-start)
+
+**INVOKE:** `validate-ticket` skill
+
+AI actively reads ticket + source code to understand the requirement:
+1. Read `.claude/context/current.json` — ticket info
+2. Read source code — architecture, related files, data flow
+3. If anything is unclear — ask ONE question at a time, wait for reply
+4. Output `plan/[ticket-id]/requirement.md` with:
+   - Requirements summary, source code analysis
+   - Proposed solution and approach
+   - Impact analysis, effort estimate, testing plan
+5. Display "GATE 1: Requirement doc ready" → wait for **APPROVED**
+
+DO NOT just check format — **understand the content and propose solutions**.
+
+---
+
+### GATE 2 — Implementation Plan (wait for APPROVED)
+
+**INVOKE:** `generate-spec` skill, then `superpowers:writing-plans`
+
+- Create a detailed TDD implementation plan based on the approved requirement.
+- Display: "GATE 2 PAUSED: type APPROVED to start coding".
+- CODE WILL NOT BE GENERATED until "APPROVED" is received.
+
+---
+
+### GATE 3 — Code Generation (TDD only)
+
+Only runs after Gate 2 has been APPROVED.
+
+**INVOKE:** `superpowers:test-driven-development`
+- Complex feature (3+ files): `superpowers:subagent-driven-development`
+- Write tests FIRST — run to confirm FAIL -> implement -> PASS.
+- Bug fix EXTRA: `superpowers:systematic-debugging` + `investigate-bug` skill first.
+
+---
+
+### GATE 4 — AI Self-Review (wait for APPROVED)
+
+**INVOKE:** `review-plan` skill
+
+Mandatory order:
+1. `superpowers:verification-before-completion` — all tests must PASS
+2. `impact-analysis` skill — check for breaking changes
+3. `custom/rules/review-checklist.md` — tick each item
+4. Create `plan/[ticket-id]/summary.md`
+
+Then: "GATE 4 PAUSED: type APPROVED or BUG: [description]"
+- Coding bug -> fix -> repeat Gate 4.
+- Requirement bug -> return to Gate 1.
+
+---
+
+### GATE 5 — Peer Review and Done
+
+Only runs after Gate 4 has been APPROVED.
+
+**INVOKE:** `superpowers:requesting-code-review`
+Guide on creating a Pull Request with the ticket link.
+
+---
+
+## Project Stack
+
+- **React:** 18+
+- **Language:** TypeScript
+- **Build Tool:** Vite (prefer) or Create React App
+- **State Management:** Zustand (local/global) or TanStack Query (server state)
+- **Routing:** React Router v6
+- **Styling:** Tailwind CSS + shadcn/ui (or CSS Modules if no Tailwind)
+- **Form:** React Hook Form + Zod validation
+- **HTTP Client:** Axios with interceptors
+- **Testing:** Vitest + React Testing Library
+
+---
+
+## Project Structure
+
+```
+src/
+├── components/
+│   ├── ui/                   # Generic, reusable UI (Button, Input, Modal...)
+│   └── [feature]/            # Feature-specific components
+├── pages/                    # Route-level components (thin, delegate to features)
+├── features/                 # Self-contained feature modules
+│   └── [feature]/
+│       ├── components/       # UI specific to this feature
+│       ├── hooks/            # Custom hooks for this feature
+│       ├── api.ts            # API calls for this feature
+│       ├── store.ts          # Zustand slice (if needed)
+│       ├── types.ts          # TypeScript types/interfaces
+│       └── index.ts          # Public exports
+├── hooks/                    # Shared custom hooks
+├── services/
+│   └── api.ts                # Axios instance + interceptors
+├── store/                    # Global Zustand store
+├── types/                    # Shared TypeScript types
+├── utils/                    # Pure utility functions
+├── constants/                # App-wide constants
+└── App.tsx
+```
+
+---
+
+## Component Rules
+
+### Always use Functional Components
+
+```tsx
+// ✅ Good
+const UserCard = ({ user }: UserCardProps) => {
+  return <div>{user.name}</div>;
+};
+
+// ❌ Bad — class component
+class UserCard extends React.Component {}
+```
+
+### Define Props with TypeScript interface
+
+```tsx
+// ✅ Good
+interface UserCardProps {
+  user: User;
+  onDelete?: (id: number) => void;
+  className?: string;
+}
+
+const UserCard = ({ user, onDelete, className }: UserCardProps) => {
+  // ...
+};
+
+// ❌ Bad — any, or no type
+const UserCard = ({ user }: any) => {};
+const UserCard = (props) => {};
+```
+
+### Keep components focused and small
+
+- One component = one responsibility
+- If a component exceeds ~150 lines, split it
+- Extract logic to custom hooks, keep JSX clean
+
+```tsx
+// ✅ Good — logic extracted to hook
+const UserList = () => {
+  const { users, isLoading, error, deleteUser } = useUserList();
+
+  if (isLoading) return <Spinner />;
+  if (error) return <ErrorMessage message={error.message} />;
+
+  return (
+    <ul>
+      {users.map(user => (
+        <UserCard key={user.id} user={user} onDelete={deleteUser} />
+      ))}
+    </ul>
+  );
+};
+
+// ❌ Bad — logic mixed into component
+const UserList = () => {
+  const [users, setUsers] = useState([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('/api/users')
+      .then(r => r.json())
+      .then(data => { setUsers(data); setLoading(false); });
+  }, []);
+
+  const handleDelete = async (id) => {
+    await fetch(`/api/users/${id}`, { method: 'DELETE' });
+    setUsers(prev => prev.filter(u => u.id !== id));
+  };
+  // ... long JSX
+};
+```
+
+### Export convention
+
+```tsx
+// Named export for regular components
+export const UserCard = ({ user }: UserCardProps) => { ... };
+
+// Default export only for page-level components
+export default function UserPage() { ... }
+```
+
+---
+
+## Custom Hook Rules
+
+- Prefix with `use`: `useUserList`, `useAuth`, `useModal`
+- Extract all side effects, API calls, and complex state from components
+- Return objects (not arrays) for multiple values — easier to destructure
+
+```tsx
+// ✅ Good
+const useUserList = () => {
+  const { data: users = [], isLoading, error } = useQuery({
+    queryKey: ['users'],
+    queryFn: userApi.getAll,
+  });
+
+  const { mutate: deleteUser } = useMutation({
+    mutationFn: userApi.delete,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
+  });
+
+  return { users, isLoading, error, deleteUser };
+};
+
+// Usage
+const { users, isLoading, deleteUser } = useUserList();
+```
+
+---
+
+## State Management Rules
+
+### Server state → TanStack Query
+
+Use for all API data (fetching, caching, mutations):
+
+```tsx
+// Fetching
+const { data, isLoading, error } = useQuery({
+  queryKey: ['users', filters],   // include deps in key
+  queryFn: () => userApi.getAll(filters),
+  staleTime: 5 * 60 * 1000,      // 5 minutes
+});
+
+// Mutation
+const { mutate, isPending } = useMutation({
+  mutationFn: userApi.create,
+  onSuccess: () => {
+    queryClient.invalidateQueries({ queryKey: ['users'] });
+    toast.success('User created');
+  },
+  onError: (error) => toast.error(error.message),
+});
+```
+
+### Client/UI state → Zustand (or useState for local)
+
+```tsx
+// Local state — use useState
+const [isOpen, setIsOpen] = useState(false);
+
+// Shared UI state — use Zustand
+const useAuthStore = create<AuthStore>((set) => ({
+  user: null,
+  token: null,
+  login: (user, token) => set({ user, token }),
+  logout: () => set({ user: null, token: null }),
+}));
+```
+
+### Rules:
+- **Never** use global state for server/API data — that's TanStack Query's job
+- **Never** fetch in `useEffect` manually — use TanStack Query
+- **Never** put loading/error state in Zustand — TanStack Query handles that
+
+---
+
+## Form Rules
+
+Use **React Hook Form + Zod** for all forms:
+
+```tsx
+// 1. Define schema with Zod
+const createUserSchema = z.object({
+  email: z.string().email('Invalid email'),
+  fullName: z.string().min(2, 'Min 2 characters').max(100),
+  password: z.string().min(8, 'Min 8 characters'),
+});
+
+type CreateUserForm = z.infer<typeof createUserSchema>;
+
+// 2. Use in component
+const CreateUserForm = () => {
+  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm<CreateUserForm>({
+    resolver: zodResolver(createUserSchema),
+  });
+
+  const onSubmit = async (data: CreateUserForm) => {
+    await createUser(data);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('email')} />
+      {errors.email && <span>{errors.email.message}</span>}
+
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? 'Saving...' : 'Create'}
+      </button>
+    </form>
+  );
+};
+```
+
+---
+
+## API Layer Rules
+
+One `axios` instance shared across the app with interceptors:
+
+```tsx
+// src/services/api.ts
+const api = axios.create({
+  baseURL: import.meta.env.VITE_API_URL,
+  timeout: 10000,
+  headers: { 'Content-Type': 'application/json' },
+});
+
+// Attach token automatically
+api.interceptors.request.use((config) => {
+  const token = useAuthStore.getState().token;
+  if (token) config.headers.Authorization = `Bearer ${token}`;
+  return config;
+});
+
+// Handle 401 globally
+api.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    if (error.response?.status === 401) {
+      useAuthStore.getState().logout();
+      window.location.href = '/login';
+    }
+    return Promise.reject(error);
+  }
+);
+```
+
+Feature API module:
+
+```tsx
+// src/features/users/api.ts
+export const userApi = {
+  getAll: (params?: UserListParams): Promise<User[]> =>
+    api.get('/users', { params }).then(r => r.data),
+
+  getById: (id: number): Promise<User> =>
+    api.get(`/users/${id}`).then(r => r.data),
+
+  create: (data: CreateUserRequest): Promise<User> =>
+    api.post('/users', data).then(r => r.data),
+
+  update: (id: number, data: UpdateUserRequest): Promise<User> =>
+    api.put(`/users/${id}`, data).then(r => r.data),
+
+  delete: (id: number): Promise<void> =>
+    api.delete(`/users/${id}`).then(r => r.data),
+};
+```
+
+---
+
+## TypeScript Rules
+
+- **No `any`** — use `unknown`, proper types, or generics
+- Define shared types in `types.ts` files
+- Use `interface` for object shapes, `type` for unions/intersections
+- Always type function return values for public hooks and API functions
+
+```tsx
+// ✅ Good
+interface User {
+  id: number;
+  email: string;
+  fullName: string;
+  createdAt: string;
+}
+
+type UserStatus = 'active' | 'inactive' | 'banned';
+
+const getUser = async (id: number): Promise<User> => {
+  return api.get(`/users/${id}`).then(r => r.data);
+};
+
+// ❌ Bad
+const getUser = async (id: any) => {
+  return api.get(`/users/${id}`).then((r: any) => r.data);
+};
+```
+
+---
+
+## Styling Rules (Tailwind CSS)
+
+- Use utility classes directly — avoid custom CSS unless necessary
+- Extract repeated class combinations into components or a `cn()` helper
+- Use `className` prop for external style overrides
+
+```tsx
+// ✅ Good — cn() for conditional classes
+import { cn } from '@/utils/cn';
+
+const Button = ({ variant = 'primary', disabled, className, children }: ButtonProps) => (
+  <button
+    className={cn(
+      'px-4 py-2 rounded font-medium transition-colors',
+      variant === 'primary' && 'bg-blue-600 text-white hover:bg-blue-700',
+      variant === 'outline' && 'border border-gray-300 hover:bg-gray-50',
+      disabled && 'opacity-50 cursor-not-allowed',
+      className
+    )}
+    disabled={disabled}
+  >
+    {children}
+  </button>
+);
+
+// ❌ Bad — inline style
+<button style={{ backgroundColor: 'blue', padding: '8px 16px' }}>
+```
+
+---
+
+## Performance Rules
+
+- Use `React.memo` only when profiling shows a real problem — do not optimize prematurely
+- Use `useMemo` / `useCallback` for expensive computations or stable references passed to children
+- Lazy-load routes with `React.lazy` + `Suspense`
+- Avoid anonymous functions in JSX props when passing to memoized children
+
+```tsx
+// Lazy routes
+const UserPage = React.lazy(() => import('./pages/UserPage'));
+
+<Suspense fallback={<PageSkeleton />}>
+  <UserPage />
+</Suspense>
+
+// useMemo for expensive computation
+const sortedUsers = useMemo(
+  () => [...users].sort((a, b) => a.fullName.localeCompare(b.fullName)),
+  [users]
+);
+```
+
+---
+
+## Error Handling Rules
+
+- Use React Error Boundary at the route level
+- Handle API errors in TanStack Query `onError` callbacks
+- Show user-friendly messages — never raw error objects
+- Use toast notifications for async operation feedback
+
+```tsx
+// Error boundary at route level
+<ErrorBoundary fallback={<ErrorPage />}>
+  <Routes>
+    <Route path="/users" element={<UserPage />} />
+  </Routes>
+</ErrorBoundary>
+
+// Async error handling
+const { mutate } = useMutation({
+  mutationFn: userApi.create,
+  onSuccess: () => toast.success('User created successfully'),
+  onError: (error: AxiosError<ApiError>) =>
+    toast.error(error.response?.data?.message ?? 'Something went wrong'),
+});
+```
+
+---
+
+## Testing Rules
+
+### Unit/Component tests with React Testing Library
+
+```tsx
+// Test behavior, not implementation
+describe('UserCard', () => {
+  it('should display user name and email', () => {
+    const user: User = { id: 1, email: 'test@example.com', fullName: 'Test User' };
+    render(<UserCard user={user} />);
+
+    expect(screen.getByText('Test User')).toBeInTheDocument();
+    expect(screen.getByText('test@example.com')).toBeInTheDocument();
+  });
+
+  it('should call onDelete with user id when delete button clicked', async () => {
+    const onDelete = vi.fn();
+    const user: User = { id: 1, email: 'test@example.com', fullName: 'Test User' };
+
+    render(<UserCard user={user} onDelete={onDelete} />);
+    await userEvent.click(screen.getByRole('button', { name: /delete/i }));
+
+    expect(onDelete).toHaveBeenCalledWith(1);
+  });
+});
+```
+
+### Hook tests
+
+```tsx
+import { renderHook, waitFor } from '@testing-library/react';
+
+it('should fetch users', async () => {
+  const { result } = renderHook(() => useUserList(), { wrapper: QueryWrapper });
+
+  await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+  expect(result.current.users).toHaveLength(2);
+});
+```
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Component file | PascalCase | `UserCard.tsx` |
+| Hook file | camelCase | `useUserList.ts` |
+| Utility file | camelCase | `formatDate.ts` |
+| Type/Interface | PascalCase | `User`, `CreateUserRequest` |
+| Component | PascalCase | `UserCard`, `OrderList` |
+| Hook | `use` + PascalCase | `useUserList`, `useAuth` |
+| Event handler | `handle` + Action | `handleDelete`, `handleSubmit` |
+| Boolean variable | `is/has/can` prefix | `isLoading`, `hasError`, `canEdit` |
+| Constant | UPPER_SNAKE_CASE | `MAX_RETRY`, `API_TIMEOUT` |
+| CSS class (custom) | kebab-case | `user-card`, `nav-item` |
+
+---
+
+## Common Anti-Patterns to Avoid
+
+- ❌ Fetching in `useEffect` → use TanStack Query
+- ❌ Using `any` type → define proper TypeScript types
+- ❌ Storing server data in Zustand → that's TanStack Query's responsibility
+- ❌ Class components → use functional components
+- ❌ `index.js` everywhere → use named files for traceability
+- ❌ Direct DOM manipulation → use React state/refs
+- ❌ Mutating state directly → always use setter functions
+- ❌ Large components doing everything → split into smaller focused components
+- ❌ Prop drilling more than 2 levels → use context or Zustand
+- ❌ Hardcoding API URLs → use `import.meta.env.VITE_API_URL`
+
+---
+
+When explaining changes, refer to the [React Official Documentation](https://react.dev), [TanStack Query](https://tanstack.com/query), and [React Hook Form](https://react-hook-form.com) conventions.