agent-workflow-kit-cli 1.3.0 → 1.3.2

package/templates/next-js/rules/next-style.md

@@ -0,0 +1,32 @@
+# Quy Ước Đặt Tên & Coding Style cho Next.js (App Router)
+
+Tài liệu này đặc tả quy ước đặt tên file, thư mục, cấu trúc import và tổ chức folder trong các dự án Next.js App Router.
+
+---
+
+## 🏷️ Quy Ước Đặt Tên (Naming Conventions)
+
+| Đối Tượng | Quy Chuẩn Đặt Tên | Ví Dụ Minh Họa |
+| :--- | :--- | :--- |
+| **Thư mục Route (`app/`)** | lowercase hoặc kebab-case | `app/dashboard/`, `app/user-profile/` |
+| **Route Nhóm (Route Groups)** | Bọc trong dấu ngoặc đơn `(group-name)` | `app/(auth)/login/`, `app/(dashboard)/layout.tsx` |
+| **Route Động (Dynamic Routes)** | Bọc trong dấu ngoặc vuông `[paramName]` | `app/blog/[id]/page.tsx`, `app/shop/[...slug]/page.tsx` |
+| **Tệp Giao Diện Đặc Trưng** | Định dạng chuẩn Next.js (lowercase.tsx) | `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx` |
+| **Route Handlers** | Định dạng file API endpoint của Next.js | `route.ts` |
+| **Component UI Phụ Trợ** | PascalCase.tsx | `Button.tsx`, `ProductCard.tsx`, `SidebarSkeleton.tsx` |
+| **Custom Hooks** | camelCase bắt đầu bằng tiền tố `use` | `useAuth.ts`, `useLocalStorage.ts` |
+
+---
+
+## 📦 Imports & Aliasing
+- **Absolute Imports:** Luôn luôn sử dụng absolute imports với alias `@/` trỏ tới thư mục `src/` hoặc root (ví dụ: `import { Button } from "@/components/ui/Button"`). Nghiêm cấm sử dụng relative imports với nhiều tầng nhảy thư mục sâu (ví dụ: `../../../../Button`).
+- **CSS / Styles Imports:** Đặt các styles toàn cục trong một file duy nhất (như `globals.css` hoặc `index.css`) được import trong file `layout.tsx` gốc. Không import file CSS tùy tiện trong các component con.
+
+---
+
+## 📁 Tổ Chức Thư Mục (Folder Organization)
+- Giữ các thư mục bên trong `app/` dành riêng cho việc khai báo routing và giao diện trang tương ứng.
+- Đặt các component nghiệp vụ, hook, service và type bên trong thư mục `src/features/` hoặc `src/components/` bên ngoài thư mục `app/`. Mỗi feature (ví dụ: `billing`) nên đóng gói các tài nguyên liên quan:
+  - `src/features/billing/components/BillingForm.tsx`
+  - `src/features/billing/hooks/useBilling.ts`
+- Xuất bản public APIs của feature qua một file `index.ts` sạch sẽ.

package/templates/next-js/rules/seo-metadata.md

@@ -0,0 +1,50 @@
+# Tối Ưu Hóa SEO & Cấu Trúc Semantic HTML
+
+Tài liệu này quy định việc sử dụng cấu trúc thẻ Semantic, tối ưu hóa điều hướng hình ảnh và tích hợp Metadata API của Next.js để đạt thứ hạng SEO tốt nhất.
+
+---
+
+## 🔍 Tích Hợp Metadata API Của Next.js
+- **Metadata Tĩnh:** Khai báo đối tượng `metadata` tĩnh trong các layouts hoặc pages không có biến số động:
+  ```typescript
+  export const metadata = {
+    title: 'Dashboard | Skillverse Platform',
+    description: 'Trang tổng quan quản lý khóa học',
+  };
+  ```
+- **Metadata Động:** Đối với các route động (như trang chi tiết bài viết, khóa học), khai báo cấu hình SEO thông qua hàm `generateMetadata` đối với các route động để tối ưu hóa SEO tối đa cho hệ thống tìm kiếm:
+  
+  ```typescript
+  import { Metadata } from 'next';
+
+  type Props = { params: Promise<{ id: string }> };
+
+  export async function generateMetadata({ params }: Props): Promise<Metadata> {
+    const id = (await params).id;
+    const course = await getCourseDetail(id);
+    
+    return {
+      title: `${course.title} | Skillverse Platform`,
+      description: course.shortDescription,
+      openGraph: { images: [course.thumbnailUrl] }
+    };
+  }
+  ```
+
+---
+
+## 🎨 Cấu Trúc Semantic HTML5
+- **Thẻ cấu trúc:** Bắt buộc xây dựng bố cục trang bằng các thẻ HTML5 ngữ nghĩa thay vì lạm dụng các thẻ `<div>` vô nghĩa:
+  - `<header>`: Thanh tiêu đề hoặc thanh đầu trang chính.
+  - `<nav>`: Danh mục liên kết điều hướng cốt lõi.
+  - `<main>`: Bao bọc duy nhất phần nội dung cốt lõi của trang.
+  - `<section>`: Phân đoạn chủ đề nội dung tổng quát.
+  - `<article>`: Các thành phần độc lập (bài viết blog, phần tử thẻ card sản phẩm).
+  - `<footer>`: Chứa thông tin bản quyền và liên kết chân trang.
+- **Tiêu đề h-tags:** Đảm bảo thứ tự logic của các thẻ tiêu đề (từ `<h1>` đến `<h6>`). Đảm bảo có duy nhất một thẻ `<h1>` trên mỗi trang.
+
+---
+
+## ⚡ Tối Ưu Hóa Hình Ảnh & Điều Hướng
+- **Tối ưu hình ảnh:** Tuyệt đối không dùng thẻ `<img>` thô. Bắt buộc sử dụng `<Image />` từ `next/image` với đầy đủ thuộc tính `sizes` và cấu hình `priority` cho các hình ảnh xuất hiện ở nấc màn hình đầu tiên (Above the fold).
+- **Tối ưu điều hướng:** Dùng `<Link />` từ `next/link` để kích hoạt cơ chế pre-fetching tài nguyên ngầm khi link xuất hiện trong viewport, giúp chuyển trang tức thì.

package/templates/next-js/rules/server-client-components.md

@@ -0,0 +1,27 @@
+# React Server Components (RSC) vs React Client Components (RCC)
+
+Tài liệu này quy định ranh giới kiến trúc và quy tắc phân loại component trong ứng dụng Next.js sử dụng App Router.
+
+---
+
+## 🏛️ React Server Components (RSC)
+- **Mặc định:** Tất cả các page, layout và component được tạo bên trong thư mục routing `app/` mặc định phải là React Server Components (RSC).
+- **Lợi ích của RSC:**
+  - Gọi dữ liệu (data fetching) trực tiếp sử dụng async/await.
+  - Sử dụng an toàn các thư viện phía server (truy vấn DB, đọc file, import khóa bảo mật).
+  - Giảm dung lượng bundle size gửi xuống client do mã nguồn RSC chỉ biên dịch và chạy trên server.
+- **Quy tắc:**
+  - Thực hiện toàn bộ việc nạp dữ liệu và cấu trúc khung trang bên trong các RSC.
+  - Không thêm `"use client"` vào các layout hoặc page entry points trừ khi bắt buộc.
+
+---
+
+## 💻 React Client Components (RCC)
+- **Định nghĩa:** Các component chạy trên trình duyệt để hỗ trợ tương tác và cập nhật trạng thái động từ người dùng.
+- **Dấu hiệu nhận biết RCC:** Chỉ gắn directive `"use client"` ở lớp component lá (Leaf Components) khi component:
+  - Sử dụng các Hook vòng đời và trạng thái của React (`useState`, `useReducer`, `useEffect`, `useLayoutEffect`).
+  - Gọi các API đặc trưng của trình duyệt (`window`, `localStorage`, custom viewport hooks).
+  - Đăng ký các callback lắng nghe sự kiện DOM (như `onClick`, `onChange`, `onSubmit`).
+- **Phân tách ranh giới RCC:**
+  - Giữ RCC ở cấp lá (Leaf Components) cuối cùng của cây dựng hình để tối ưu hiệu năng.
+  - *Ví dụ:* Nếu trang danh sách sản phẩm (RSC) có thanh tìm kiếm (RCC), hãy tách thanh tìm kiếm thành một component riêng (`<SearchBar />` có `"use client"`) và import vào trang cha chạy ở phía server.

package/templates/next-js/skills/next-feature/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: next-feature
+description: Sinh hoặc mở rộng một page hoặc route handler Next.js + TypeScript mới kèm caching và metadata
+---
+
+Tuân thủ quy trình này để tạo một page, layout hoặc API route handler mới trong Next.js.
+
+Đầu vào (Inputs):
+- featureName: Tên của route hoặc trang (ví dụ: `dashboard`)
+- targetPath: Thư mục chứa route bên trong `app/` để triển khai
+- userFlow: Mô tả tóm tắt hành vi và bố cục giao diện của trang
+
+Các bước thực hiện (Steps):
+1. Quét các thư mục lân cận trong `app/` để tham chiếu các layout chung và ranh giới xử lý lỗi (`error.tsx`).
+2. Thiết lập cấu trúc thư mục route theo chuẩn Next.js (ví dụ: `app/(dashboard)/billing`).
+3. Khai báo interface cho route params và query parameters.
+4. Triển khai cấu trúc trang hoặc layout dưới dạng **React Server Component (RSC)**.
+5. Nếu có tương tác người dùng hoặc form, hãy tách thành các component con cấp lá (RCC) được đánh dấu `"use client"` rồi import vào RSC.
+6. Thiết lập cơ chế cache rõ ràng cho toàn bộ các thao tác gọi dữ liệu `fetch()`.
+7. Cấu hình metadata tĩnh hoặc động thông qua hàm `generateMetadata`.
+8. Định nghĩa file xử lý lỗi cục bộ (`error.tsx`) tại thư mục route gần nhất để bắt lỗi runtime.
+9. Thực hiện kiểm tra lỗi cục bộ:
+   - `{{runCommand}} lint`
+   - `{{runCommand}} typecheck`
+   - `{{runCommand}} test`
+   - `{{runCommand}} build`

package/templates/react-ts/AGENTS.md.hbs

@@ -1,47 +1,124 @@
 ## React + TypeScript Guidelines
 
-### Architecture & Feature Conventions
-Use a feature-first structure. Keep route wiring thin, and place feature UI, hooks, data clients, and types together:
+### 🔄 End-to-End Agent Development Lifecycle
+AI Agents must execute all React + TypeScript tasks following this structured 5-stage lifecycle:
+1. **Design & Code:** Implement components and logic following the guidelines below. Keep logic inside Custom Hooks.
+2. **Comprehensive Testing:** Write component tests using React Testing Library and hook tests for complex behavior.
+3. **Code Quality & Validation:** Perform self-review and execute dynamic linter, type checks, and tests:
+   - Linting check: `{{runCommand}} lint`
+   - Type checking: `{{runCommand}} typecheck`
+   - Unit tests: `{{runCommand}} test` (or `{{runCommand}} test -- --run` in CI/CD)
+   - Production build: `{{runCommand}} build`
+4. **Dependency Management:** Install new packages using `{{packageManager}} add [package_name]` (or `npm install [package_name]` if using npm). Never manually modify the lock file `{{lockFile}}`.
+
+---
+
+### 🏗️ Architecture & Feature Conventions
+Use a strict **feature-first** modular packaging layout. Keep routing modules thin, and place feature UI, custom hooks, services, types, and tests together within the feature module:
 
 ```text
 src/
-  app/                  # App shell, router, providers
+  app/                  # App shell, router, context providers
   features/
     billing/
-      components/
+      components/       # Feature-specific components
         BillingPanel.tsx
-      hooks/
+      hooks/            # Feature-specific custom hooks (queries, state)
         useBilling.ts
-      services/
+      services/         # API clients and data transformers
         billingClient.ts
-      types.ts
-      index.ts
-  shared/
+      types/            # Feature type definitions
+        billing.ts
+      __tests__/        # Component and hook unit tests
+        BillingPanel.test.tsx
+      index.ts          # Public API for this feature
+  shared/               # Core shared assets, hooks, components, utils
     components/
     hooks/
     utils/
 ```
 
-### Component, Hook, and State Rules
-- Components render UI and delegate fetching, subscriptions, timers, and other side effects to custom hooks.
-- Custom hooks own reusable stateful logic and must start with `use`.
-- Prefer local component state for isolated interactions.
-- Use Context API for low-frequency cross-tree state such as theme, auth session, or app configuration.
-- Use Zustand only for shared state with frequent updates or cross-feature coordination.
-- Keep feature state close to the feature before moving it to `shared/`.
-
-### TypeScript Standards
-- Use strict TypeScript. Avoid `any`; prefer explicit domain types and discriminated unions.
-- Define feature-local interfaces and types near the code that owns them.
-- Export from feature `index.ts` files only when another module needs the API.
-- Use absolute imports from `@/`; do not add deep relative imports like `../../`.
-
-### Testing & Verification
-Before completing a React + TypeScript change, run the project validation pipeline:
-
-```bash
-npm run lint
-npm run typecheck
-npm run test -- --run
-npm run build
-```
+---
+
+### 🎨 Aesthetics, Styling & Premium UI
+The UI must feel premium, modern, and cohesive.
+- **Strict Tailwind CSS usage**: Never write inline custom CSS. Build the interface entirely using Tailwind Utility Classes.
+- **Dynamic Classes helper**: Never use string interpolation to join dynamic classNames. Always use the `cn()` helper (combining `clsx` and `tailwind-merge`):
+  ```typescript
+  // src/utils/cn.ts
+  import { ClassValue, clsx } from "clsx";
+  import { twMerge } from "tailwind-merge";
+
+  export function cn(...inputs: ClassValue[]) {
+    return twMerge(clsx(inputs));
+  }
+  ```
+  Usage:
+  `className={cn("px-4 py-2 text-white transition-all", isActive ? "bg-blue-500" : "bg-gray-500", customClass)}`
+- **Mobile-First Design**: Design layouts for mobile by default. Use breakpoints (`sm:`, `md:`, `lg:`, `xl:`) only to add or modify responsive styles as viewport size increases.
+- **Micro-animations & Motion**: Use `framer-motion` (or equivalent core transition library) for physical state changes:
+  - Transition duration should be short (between `0.2s` and `0.3s`).
+  - Use natural easing curves (`easeOut`, `easeInOut`) or spring physics for buttons/modals.
+  - Wrap conditional components in `<AnimatePresence>` to execute smooth exit animations.
+
+---
+
+### 🌐 Asynchronous Server-State & API Call Conventions
+- **No raw useEffect Fetching**: Never fetch data using raw `useEffect` blocks.
+- **Centralized API Client**: Route all outgoing requests through a unified client instance (e.g. `src/lib/api-client.ts`) that manages baseURL, interceptors, auth token inclusion, and global error mappings.
+- **Asynchronous Server-State**: Manage all server state using **TanStack Query (React Query)** or **SWR**.
+- **Separation of Concerns**: UI components must only call custom query hooks and render UI based on three states (`isLoading`, `isError`, and `data`). All fetching, caching, and mutation logic must be kept inside custom hooks:
+  ```typescript
+  // src/features/roadmap/api/use-roadmap.ts
+  import { useQuery } from "@tanstack/react-query";
+  import { apiClient } from "@/lib/api-client";
+
+  export const useRoadmap = (roadmapId: string) => {
+    return useQuery({
+      queryKey: ["roadmaps", roadmapId],
+      queryFn: async () => {
+        const response = await apiClient.get(`/roadmaps/${roadmapId}`);
+        return response.data;
+      },
+      staleTime: 5 * 60 * 1000,
+      gcTime: 10 * 60 * 1000,
+    });
+  };
+  ```
+
+---
+
+### 📝 Forms & Schema Validation
+Forms must remain performant and prevent rendering bottleneck.
+- **React Hook Form**: Manage form states with React Hook Form to isolate re-rendering and ensure smooth typing.
+- **Controller integration**: For complex third-party elements (Rich Text Editors, selectors, etc.), wrap them in the RHF `<Controller>` component.
+- **Schema-Driven Validation**: Avoid raw if/else statements for input validation. Use **Zod** to declare data schemas and automatically resolve validator rules:
+  ```typescript
+  import { useForm } from "react-hook-form";
+  import { zodResolver } from "@hookform/resolvers/zod";
+  import * as z from "zod";
+
+  const loginSchema = z.object({
+    email: z.string().min(1, "Email cannot be empty").email("Invalid email format"),
+    password: z.string().min(8, "Password must contain at least 8 characters"),
+  });
+  ```
+
+---
+
+### ⚡ Routing & Code Splitting
+Optimizing bundle loading performance is mandatory.
+- **Code Splitting**: Do not statically import Page Components. Use `React.lazy()` to segment routes into separate chunks loaded only when the route is visited.
+- **Premium Loading**: Wrap all lazy-loaded route elements inside a `<Suspense>` boundary containing a premium Shimmer Skeleton loader or spinner.
+- **Centralized Data Routers**: Configure routes using `createBrowserRouter` (React Router v6+) instead of JSX tags.
+- **Loaders & Actions**: Fetch data parallel to route transitions using router Loaders, and manage data mutations via router Actions.
+- **Route Error Boundaries**: Specify an `errorElement` on all primary route branches to isolate crashes and show a dedicated recovery panel instead of freezing the entire application.
+
+---
+
+### 🔍 SEO & Accessibility (a11y)
+- **Dynamic SEO Metadata**: Update document metadata (`title`, `description`, Open Graph tags) on route changes using `react-helmet-async`.
+- **Semantic HTML5 Structure**: Restructure elements using semantic tags: `<header>`, `<nav>`, `<main>`, `<section>`, `<article>`, `<footer>`. Ensure heading tags (`<h1>` to `<h6>`) follow logical hierarchy.
+- **Accessible Images**: All `<img>` tags must possess an `alt` attribute. Provide descriptive alt text for informative images; write `alt=""` for purely decorative images so screen readers skip them.
+- **Icon-Only Controls**: Buttons or links containing only SVG icons (e.g. close buttons, like buttons) must have an explicit `aria-label` or `aria-labelledby` attribute.
+- **Visual Keyboard Focus**: Do not disable the browser focus outline without adding a custom indicator. Interactable elements must display a distinct ring when navigated via keyboard (`:focus-visible`, e.g. `focus-visible:ring-2 focus-visible:ring-primary focus-visible:outline-none`).

package/templates/react-ts/rules/data-fetching.md

@@ -0,0 +1,45 @@
+# Asynchronous Server-State & API Call Rules
+
+This ruleset governs network communication, caching, server-state syncing, and component integration logic to guarantee high performance, security, and clean separation of concerns.
+
+---
+
+## 🚫 No Raw useEffect Fetching
+- **Forbidden**: Do not write raw `useEffect` blocks to fetch remote data inside UI components. Raw effects are prone to memory leaks, state sync race conditions, lack of cache validation, and component bloatedness.
+
+---
+
+## 🔌 Centralized API Client
+- **Single Instance**: Route all HTTP/HTTPS outgoing traffic through a unified API client instance (e.g. located at `src/lib/api-client.ts`).
+- **Responsibility**:
+  - Configure core variables (e.g. `baseURL`, `timeout`).
+  - Attach authorization tokens dynamically via request interceptors.
+  - Implement unified global error handling (e.g. intercepting `401 Unauthorized` for token refresh, `403 Forbidden`, `500 Server Error`).
+
+---
+
+## 🔄 Server-State Management
+- **Library Selection**: Use **TanStack Query (React Query)** or **SWR** to manage asynchronous server-state (fetching, caching, caching invalidation, background updates).
+- **Separation of Concerns**: UI components must never deal with query functions or endpoints. Components only request custom query hooks and render the layout based on:
+  - `isLoading`: displays placeholder/Skeleton UI.
+  - `isError`: displays recovery panel/notification.
+  - `data`: displays final UI.
+- **Hook Encapsulation**: Declare data fetching inside specialized feature-local custom hooks:
+
+  ```typescript
+  // src/features/roadmap/api/use-roadmap.ts
+  import { useQuery } from "@tanstack/react-query";
+  import { apiClient } from "@/lib/api-client";
+
+  export const useRoadmap = (roadmapId: string) => {
+    return useQuery({
+      queryKey: ["roadmaps", roadmapId],
+      queryFn: async () => {
+        const response = await apiClient.get(`/roadmaps/${roadmapId}`);
+        return response.data;
+      },
+      staleTime: 5 * 60 * 1000, // consider data fresh for 5 minutes
+      gcTime: 10 * 60 * 1000,    // keep in cache for 10 minutes before garbage collection
+    });
+  };
+  ```

package/templates/react-ts/rules/forms-validation.md

@@ -0,0 +1,55 @@
+# Form Management & Schema Validation Rules
+
+This ruleset governs the design and implementation of input fields, submissions, validations, and custom component bindings inside React forms.
+
+---
+
+## ⚡ Form Performance (React Hook Form)
+- **High Performance**: Use **React Hook Form (RHF)** to handle form state through uncontrolled inputs. This isolates rendering, preventing expensive keypress lag or component bottlenecks on large forms.
+- **Controlled Integration**: For custom/third-party UI controls that cannot be controlled natively (such as Rich Text Editors, custom Select dropdowns, calendar selectors), wrap them within RHF's `<Controller>` component to synchronize state efficiently.
+
+---
+
+## 🛡️ Schema-Driven Validation (Zod)
+- **No manual checking**: Never use complex if/else blocks or custom validation scripts inside submit handlers to check forms.
+- **Zod Resolving**: Use **Zod** to declare form schemas. Bind them to React Hook Form using `zodResolver` to automatically map validator rules and throw clean, localized error messages:
+
+  ```tsx
+  // Example feature form implementation
+  import { useForm } from "react-hook-form";
+  import { zodResolver } from "@hookform/resolvers/zod";
+  import * as z from "zod";
+  import { cn } from "@/utils/cn";
+
+  const loginSchema = z.object({
+    email: z.string().min(1, "Email cannot be empty").email("Invalid email format"),
+    password: z.string().min(8, "Password must contain at least 8 characters"),
+  });
+
+  type LoginFields = z.infer<typeof loginSchema>;
+
+  export const LoginForm = () => {
+    const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm<LoginFields>({
+      resolver: zodResolver(loginSchema),
+    });
+
+    const onSubmit = async (data: LoginFields) => {
+      // Execute authentication pipeline
+    };
+
+    return (
+      <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
+        <div>
+          <input 
+            {...register("email")} 
+            className={cn("border px-3 py-2 rounded", errors.email && "border-red-500")} 
+          />
+          {errors.email && <p className="text-red-500 text-sm mt-1">{errors.email.message}</p>}
+        </div>
+        <button type="submit" disabled={isSubmitting} className="px-4 py-2 bg-primary text-white rounded">
+          {isSubmitting ? "Processing..." : "Login"}
+        </button>
+      </form>
+    );
+  };
+  ```

package/templates/react-ts/rules/premium-ui.md

@@ -0,0 +1,45 @@
+# Aesthetics, Styling & Premium UI Rules
+
+This ruleset outlines strict requirements for styling, responsiveness, and micro-animations to ensure premium visual excellence and high UX fidelity.
+
+---
+
+## 🎨 Tailwind CSS Guidelines
+- **No inline custom CSS**: All interface elements must be constructed using Tailwind utility classes. Do not write inline custom CSS (e.g. style properties or stylesheet files containing static layouts) unless standard utility classes are insufficient.
+- **Dynamic Classes handling**: Never use string interpolation or string addition (e.g. `isActive ? 'bg-blue-500' : 'bg-gray-500'`) to concatenate dynamic class names. This causes CSS specificity issues and classes override failure.
+- **Helper cn() usage**: Always use the custom `cn()` helper utility that integrates `clsx` and `tailwind-merge` for combining dynamic class values:
+  
+  ```typescript
+  // src/utils/cn.ts
+  import { ClassValue, clsx } from "clsx";
+  import { twMerge } from "tailwind-merge";
+
+  export function cn(...inputs: ClassValue[]) {
+    return twMerge(clsx(inputs));
+  }
+  ```
+
+  * **Incorrect (❌ Forbidden)**:
+    ```tsx
+    <button className={`px-4 py-2 text-white ${isActive ? 'bg-blue-500' : 'bg-gray-500'} ${customClass}`}>
+    ```
+  * **Correct (✔️ Required)**:
+    ```tsx
+    <button className={cn("px-4 py-2 text-white transition-all", isActive ? "bg-blue-500" : "bg-gray-500", customClass)}>
+    ```
+
+---
+
+## 📱 Mobile-First Responsiveness
+- **Default Styles**: Apply classes for the smallest screen size (mobile viewport) by default.
+- **Breakpoint Overrides**: Use breakpoints (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`) to introduce or change styling parameters for larger viewports.
+- **Layout Checking**: Always verify flex direction (`flex-col` vs `flex-row`), grid layout templates (`grid-cols-1` vs `md:grid-cols-3`), padding, margin, and typography scales on both small and large viewports to avoid layout issues.
+
+---
+
+## ⚡ Micro-animations & Motion
+- **Libraries**: Use `framer-motion` (or the core `motion` package) for micro-animations and physical state changes.
+- **Natural Transitions**:
+  - Keep animations fast and responsive: transition duration must range between `0.2s` and `0.3s`.
+  - Use natural, fluid easing curves (like `easeOut` or `easeInOut`) or spring-based models for buttons, toggles, hover states, and modals.
+- **Unmounting Transitions**: When components unmount or disappear from the DOM, they must be wrapped within the `<AnimatePresence>` component to ensure exit animations complete smoothly without sudden visual disappearance.

package/templates/react-ts/rules/react-style.md

@@ -1,29 +1,41 @@
 # React + TypeScript Style Rules
 
-## Naming
-- Components: PascalCase (`Navbar.tsx`, `InstallSection.tsx`).
-- Custom hooks: camelCase starting with `use` (`useAuth.ts`).
-- Helpers & variables: camelCase (`formatCurrency`).
-- Types & interfaces: PascalCase (`ButtonProps`).
-
-## Imports
-- Use `@/` absolute alias paths. Avoid relative parent paths (`../../`).
-- Use `import type` for types.
-- Keep feature internals private; expose via `index.ts` only when needed.
-
-## React & JSX
-- Components must focus on UI/composition.
-- Move side effects (fetching, subscriptions, timers) to custom hooks.
-- Use shorthand for boolean props: `<Input disabled />`.
-- Handle async UI states: loading, error, empty, success.
-
-## State Management
-- Prefer local component state.
-- Use Context API for stable app-level state (auth, theme).
-- Use Zustand for frequent, cross-feature state updates.
-
-## Testing
-- Test user behavior via React Testing Library.
-- Test hooks with complex branching/cleanup.
-- Avoid snapshot testing unless output is small & stable.
+This ruleset outlines base conventions for React + TypeScript projects. Detail guidelines are split into specialized modules which the agent MUST follow:
+- Styling & Aesthetics: See `@premium-ui.md`
+- Data Fetching & Server-State: See `@data-fetching.md`
+- Form Handling & Zod Validation: See `@forms-validation.md`
+- Code Splitting & Routing: See `@routing-splitting.md`
+- SEO & Accessibility (a11y): See `@seo-accessibility.md`
 
+---
+
+## 🏷️ Naming Conventions
+- **Components**: PascalCase (e.g. `Navbar.tsx`, `InstallSection.tsx`).
+- **Custom hooks**: camelCase starting with `use` (e.g. `useAuth.ts`, `useCustomers.ts`).
+- **Helpers & variables**: camelCase (e.g. `formatCurrency`, `customerData`).
+- **Types & interfaces**: PascalCase (e.g. `ButtonProps`, `CustomerData`).
+- **Routes**: `<name>.route.tsx` (e.g. `customers.route.tsx`).
+- **Feature Folders**: kebab-case or lowercase (e.g. `billing`, `user-profile`).
+
+---
+
+## 📦 Imports
+- **Absolute imports**: Always use absolute alias paths starting with `@/` (e.g. `import { Button } from "@/shared/components"`). Avoid deep relative parent imports (e.g. `../../components`).
+- **Type imports**: Always use `import type` when importing types or interfaces to optimize bundle compilation.
+- **Encapsulation**: Keep feature-internal files private. Only export public features via the module `index.ts`.
+
+---
+
+## ⚙️ React & JSX Guidelines
+- **UI Composition**: Components must focus solely on rendering UI/composition and delegating logic.
+- **Logic Delegation**: Keep side effects (fetching, subscriptions, timers, complex state transitions) inside custom hooks.
+- **Shorthand Props**: Prefer shorthand for boolean flags (e.g. `<Input disabled />` instead of `<Input disabled={true} />`).
+- **Async UI States**: Always explicitly handle async UI transitions (e.g. loading, error, empty, success).
+
+---
+
+## 💾 State Management
+- **Local State**: Prefer component-local state (`useState`, `useReducer`) for isolated UI interactions.
+- **Context API**: Use the Context API only for low-frequency global values (e.g. theme, locale, user session credentials).
+- **Zustand**: Use Zustand for frequent, cross-feature state updates or complex frontend state orchestration.
+- **Locality**: Keep state as close to the components consuming it as possible before lifting it up.

package/templates/react-ts/rules/routing-splitting.md

@@ -0,0 +1,21 @@
+# Code Splitting & Routing Rules
+
+This ruleset outlines expectations for structuring router declarations, loading performance optimization, and runtime boundary protections.
+
+---
+
+## ⚡ Code Splitting (Dynamic Imports)
+- **Dynamic Pages**: Do not statically import full page components at the top level of router files. This bundles the entire application code into a single file and degrades initial page load performance.
+- **Lazy Loading**: Use `React.lazy()` to import page components dynamically, dividing route destinations into separate bundles:
+  ```typescript
+  const DashboardPage = React.lazy(() => import("@/features/dashboard/components/DashboardPage"));
+  ```
+- **Fallback Suspension**: Wrap lazy-loaded components in a `<Suspense>` component. Provide a high-fidelity shimmer skeleton loader or loading indicator as the fallback property to maintain visual continuity.
+
+---
+
+## 🗺️ Centralized Routing Architecture (React Router v6+)
+- **Data Router**: Define routes as data configuration arrays using `createBrowserRouter` instead of JSX-based `<Routes>` declarations.
+- **Data Loaders**: Utilize router Loaders to pre-fetch required data in parallel with route navigation.
+- **Data Actions**: Utilize router Actions to handle data modification (mutations and forms submissions).
+- **Page Crash Isolation**: Define a dedicated `errorElement` on all primary parent route levels. When a page encounters a crash (e.g. invalid API response, parsing failure), the local `ErrorBoundary` will intercept the error and render a recovery screen without crashing the rest of the application.

package/templates/react-ts/rules/seo-accessibility.md

@@ -0,0 +1,34 @@
+# SEO & Accessibility (a11y) Rules
+
+This ruleset governs semantic document structures, title/meta tag updates, and accessibility integrations to ensure excellent indexing and keyboard/screen-reader compatibility.
+
+---
+
+## 🔍 SEO & Semantic HTML
+- **Dynamic SEO Metadata**: Update document headers dynamically (e.g. `document.title`, description tags, and Open Graph tags) on page transitions using `react-helmet-async` (or the routing framework's metadata controller).
+- **Semantic Structure**: Do not use `<div>` tags for all layouts. Utilize HTML5 semantic elements to establish logical document outline sections:
+  - `<header>`: Site or section navigation header.
+  - `<nav>`: Core navigation links.
+  - `<main>`: Singular primary content of the body.
+  - `<section>`: Generic thematic block.
+  - `<article>`: Self-contained composition (posts, articles, cards).
+  - `<footer>`: Copyright, contact, and structural footers.
+- **Heading Hierarchy**: Align heading tags (`<h1>` to `<h6>`) logically. Ensure there is only one `<h1>` per page, and header levels are nested sequentially.
+
+---
+
+## ♿ Accessibility (a11y) Standards
+- **Image alt attributes**:
+  - All `<img>` tags must have an `alt` attribute.
+  - Provide short, descriptive descriptions for informative images.
+  - For decorative images, write `alt=""` so that screen readers skip reading their filenames aloud.
+- **Icon-Only Controls**: Every button, link, or clickable component that wraps only an icon (e.g. SVG close button `X`, favorite button heart, menu hamburger icon) must include a descriptive `aria-label` or `aria-labelledby` attribute.
+- **Visual Keyboard Focus**: Do not strip or disable the browser's default blue focus rings without adding an alternative visual indicator. All interactive inputs, buttons, and links must display a prominent border ring when navigated via keyboard:
+  ```css
+  /* Example utility or class selector */
+  .focus-indicator:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 2px var(--color-primary-offset), 0 0 0 4px var(--color-primary);
+  }
+  ```
+  In Tailwind: `focus-visible:ring-2 focus-visible:ring-primary focus-visible:outline-none`.

package/templates/react-ts/skills/react-feature/SKILL.md

@@ -15,11 +15,11 @@ Steps:
 2. Define feature-local types first, including loading, error, empty, and success state shapes.
 3. Create or update the custom hook that owns fetching, side effects, derived state, and cleanup.
 4. Create or update PascalCase components that render UI and delegate logic to hooks.
-5. Add styles using the project's existing styling approach; do not introduce a new styling system.
+5. Add styles using Tailwind CSS utility classes and Framer Motion for micro-animations; do not write custom inline CSS.
 6. Wire the feature into the route or parent component through the smallest public API needed.
 7. Add tests for component behavior and hook logic when branching, async work, or cleanup is present.
 8. Run validations:
-   - `npm run lint`
-   - `npm run typecheck`
-   - `npm run test -- --run`
-   - `npm run build`
+   - `{{runCommand}} lint`
+   - `{{runCommand}} typecheck`
+   - `{{runCommand}} test`
+   - `{{runCommand}} build`