@relipa/ai-flow-kit 0.2.0 → 0.2.2-beta.0

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.
@@ -474,9 +475,10 @@ Pre-flight checks (stop and report if any fail):
    - If Y: read and update `~/.claude/settings.json` by merging the playwright entry into `mcpServers`, then instruct TESTER to **restart Claude Code** before retrying. Stop here.
    - If n: show manual install instructions (add `playwright` to `mcpServers` in `~/.claude/settings.json`). Stop here.
 1. TC file is parseable — Section 3 has at least one TC row
-2. `ak-test/{repo}/` directory exists (or offer to scaffold it)
+2. `AK-Docs/03.Testing/` subfolders exist (`04.Evidence/`, `05.Scripts/`, `02.Reports/`, `06.Bugs/` — auto-create if missing)
 3. `BASE_URL` env var is set
-4. `ak-test/{repo}/playwright.config.ts` exists (or offer to create from template)
+4. `AK-Docs/03.Testing/05.Scripts/{repo}/playwright.config.ts` exists (or auto-scaffold the Playwright project inside AK-Docs — package.json, node_modules gitignored — see `execute-flow` SKILL.md "Scaffold Playwright Project")
+5. `.gitignore` (repo root containing AK-Docs) ignores `03.Testing/04.Evidence/` (binary evidence, never committed even though it lives inside AK-Docs) and `03.Testing/05.Scripts/**/{node_modules,test-results,playwright-report,blob-report}/` — auto-append if missing
 
 Then display work plan:
 
@@ -515,7 +517,7 @@ Hash-based TC↔script sync — for each TC in the file:
 - **Unchanged TC** (hash matches): skip — do not touch.
 - **Manual/Blocked TC**: mark `⏭️ Untest` / `⏳ Pending` — no script generated.
 
-Output: `ak-test/{repo}/scripts/{screenId}/{ScreenID}.spec.ts` (1 file per screen, all TCs inside)
+Output: `AK-Docs/03.Testing/05.Scripts/{repo}/{featureDir}/{ScreenID}.spec.ts` (1 file per screen, all TCs inside). Every TC Step that changes UI must call `captureStepEvidence()` from `Shared/evidence-helper.ts` (waits for loading to finish, opens popups/modals via click before capturing, scrolls to the confirm area, red-outline highlights the item to confirm) and every assertion must check the actual Expected Result content — not just element presence. See `script-sync` SKILL.md "Assertion Rules" / "Evidence Capture per Step".
 
 - **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-2-[ticket-id].md`
 - Display gate pause message from `gate-review` skill — wait for **APPROVED**
@@ -543,17 +545,22 @@ Chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đ
 
 **Step 3.1 — Determine run number**
 
-Check `ak-test/{repo}/results/{screenId}/` — next run is `run-{N+1}`.
+Check `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/` — next run is `run-{N+1}`.
 
-**Step 3.2 — Execute Playwright**
+**Step 3.2 — Execute Playwright** (script and evidence both live inside AK-Docs; evidence stays out of Git via `.gitignore`, not via a separate working dir):
 
 ```bash
-BASE_URL=<url> npx playwright test scripts/{screenId}/{ScreenID}.spec.ts
+cd AK-Docs/03.Testing/05.Scripts
+EVIDENCE_DIR="$(pwd)/../04.Evidence/{repo}/{featureDir}/run-{N}" \
+BASE_URL=<url> \
+npx playwright test --config={repo}/playwright.config.ts {repo}/{featureDir}/{ScreenID}.spec.ts
 ```
 
-**Step 3.3 — Organize evidence** into `ak-test/{repo}/results/{screenId}/run-{N}/`:
-- Per-TC folder `{TC_ID}-{scenario}/` with `step-NN-{desc}.png`, `trace.zip`, `result.md`
-- Auto-draft `bugs/BUG-NNN-{slug}.md` for failed TCs
+**Step 3.3 — Organize evidence + report:**
+- Evidence (already written directly to `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/{TC_ID}-{scenario}/`, gitignored): `step-NN-{desc}.png` per Step, `trace.zip`
+- Report (`AK-Docs/03.Testing/02.Reports/{repo}/{featureDir}/run-{N}/{TC_ID}-{scenario}/result.md`) — text only, links back to the `04.Evidence/` path
+- Before recording PASS/FAIL, re-check that the assertion actually matches the TC's Expected Result content (not just "did not throw") — see `execute-flow` SKILL.md "DOM Verification Rules"
+- Auto-draft `AK-Docs/03.Testing/06.Bugs/{repo}/{featureDir}/run-{N}/BUG-NNN-{slug}.md` for failed TCs
 
 **Step 3.4 — Update TC file** R1/R2 columns:
 - `✅ Pass` · `❌ Fail` · `⏭️ Untest` · `⏳ Pending`
@@ -592,7 +599,7 @@ Only runs after Gate 3 APPROVED.
 
 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.
 
-**Step 4.1** — Generate `ak-test/{repo}/results/{screenId}/run-{N}/testreport.md`:
+**Step 4.1** — Generate `AK-Docs/03.Testing/02.Reports/{repo}/{featureDir}/run-{N}/testreport.md`:
 - Per-module rows with Pass/Fail/Untest/Pending counts, R1/R2 columns, % completion
 - Go/No-Go: 0 unresolved Critical = Go
 
@@ -608,7 +615,7 @@ Wait for reply before moving to next bug.
 ⏸️ GATE 4: REPORT READY
 Decision: [GO / NO-GO]
 Bugs logged: [N] | Skipped: [N]
-→ Review: [ak-test/{repo}/results/{screenId}/run-{N}/testreport.md](ak-test/{repo}/results/{screenId}/run-{N}/testreport.md)
+→ Review: [AK-Docs/03.Testing/02.Reports/{repo}/{featureDir}/run-{N}/testreport.md](AK-Docs/03.Testing/02.Reports/{repo}/{featureDir}/run-{N}/testreport.md)
 → Type APPROVED to sign off
 ```
 

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.