@relipa/ai-flow-kit 0.2.0 → 0.2.1

package/custom/templates/python.md

@@ -1,79 +1,5 @@
-# Python AI System Prompt
-
-You are an expert Python developer. Follow these rules to produce clean, idiomatic, and maintainable Python code without a specific framework.
-
----
-
-## Project Structure
-
-```
-project/
-├── main.py              # Entry point
-├── src/
-│   ├── service/         # Business logic
-│   ├── repository/      # Data access layer
-│   ├── model/           # Data classes / domain models
-│   └── util/            # Pure helper functions
-├── tests/               # Pytest suite
-├── requirements.txt
-└── pyproject.toml
-```
-
----
-
-## Python Rules
-
-- Use **type hints** on all function signatures and return types.
-- Follow **PEP 8** and keep functions small and single-purpose.
-- Use **dataclasses** or **NamedTuple** for value objects; avoid plain dicts for structured data.
-- Prefer **pathlib** over `os.path`; prefer `with` statements for file/resource handling.
-- Raise specific exceptions — never `raise Exception("message")`.
-
-```python
-# ✅ Good
-from dataclasses import dataclass
-
-@dataclass
-class UserRequest:
-    email: str
-    full_name: str
-
-def create_user(request: UserRequest) -> UserResponse:
-    if not request.email:
-        raise ValueError("email is required")
-    ...
-```
-
----
-
-## Testing Rules
-
-- Use **Pytest** for all tests.
-- Name test functions `test_<what>_<expected_outcome>`.
-- Use `pytest.raises` to assert exceptions.
-
-```python
-def test_create_user_raises_when_email_is_empty():
-    with pytest.raises(ValueError, match="email is required"):
-        create_user(UserRequest(email="", full_name="Test"))
-```
-
----
-
-## Naming Conventions
-
-| Element | Convention | Example |
-|---------|-----------|---------|
-| Module/package | snake_case | `user_service.py` |
-| Class | PascalCase | `UserService` |
-| Function/variable | snake_case | `find_by_id`, `user_id` |
-| Constant | UPPER_SNAKE_CASE | `MAX_RETRY` |
-
----
-
-## Common Anti-Patterns to Avoid
-
-- ❌ Bare `except:` — always catch a specific exception type
-- ❌ Mutable default arguments (`def f(x=[])`) — use `None` sentinel instead
-- ❌ Global state — pass dependencies explicitly
-- ❌ Returning `None` implicitly on error paths — raise or return a typed result
+# Python AI System Prompt
+
+You are an expert Python developer. Follow these rules to produce clean, idiomatic, and maintainable Python code without a specific framework.
+
+> **Rules & code examples:** Read `.rules/python/python-rules.md` (structure, rules, naming, anti-patterns) and `.rules/python/python-examples.md` (code samples per rule area) **in full** before writing or modifying any Python code in this project.

package/custom/templates/reactjs.md

@@ -1,492 +1,5 @@
-# React.js AI System Prompt
-
-You are an expert React.js developer. Follow these specific rules when generating or modifying code in this project.
-
----
-
-## 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.
+# React.js AI System Prompt
+
+You are an expert React.js developer. Follow these specific rules when generating or modifying code in this project.
+
+> **Rules & code examples:** Read `.rules/javascript/reactjs-rules.md` (structure, per-area rules, naming, anti-patterns) and `.rules/javascript/reactjs-examples.md` (code samples per rule area) **in full** before writing or modifying any React code in this project.

package/custom/templates/shared/gate-workflow.md

@@ -162,6 +162,7 @@ Only runs after Gate 2 has been APPROVED.
 
 **INVOKE:** `superpowers:test-driven-development`
 - **Pre-flight (bắt buộc):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.
+- **Framework rules (bắt buộc, đọc trước dòng code đầu tiên):** nếu chưa đọc trong session này, đọc đầy đủ file(s) được trỏ ở dòng "> **Rules & code examples:**" đầu CLAUDE.md/AGENTS.md (`.rules/<lang>/<framework>-rules.md` + `-examples.md`). Áp dụng cho MỌI lần sửa code trong Gate này, không chỉ lần đầu.
 - 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.

package/custom/templates/shared/ml-gate-workflow.md

@@ -59,6 +59,7 @@ DO NOT just check format — **understand the data and propose solutions**.
 Only runs after Gate 2 has been APPROVED.
 
 **INVOKE:** `train-model` skill
+- **Framework rules (bắt buộc, đọc trước dòng code đầu tiên):** nếu chưa đọc trong session này, đọc đầy đủ file(s) được trỏ ở dòng "> **Rules & code examples:**" đầu CLAUDE.md/AGENTS.md (`.rules/<lang>/<framework>-rules.md` + `-examples.md`). Áp dụng cho MỌI lần sửa code trong Gate này, không chỉ lần đầu.
 - For algorithm-optimization tickets EXTRA: `improve-algorithm` skill
 
 **Eval-harness-first rule:** Write the metric/eval harness and establish a reproducible baseline BEFORE iterating on the model. Confirm the baseline runs and is logged — then proceed with tracked experiments.