agent-workflow-kit-cli 1.3.2 → 1.3.4

package/templates/nestjs/rules/validation-errors.md

@@ -1,39 +1,39 @@
-# Xác Thực Dữ Liệu & Quản Lý Lỗi Tập Trung
+# Data Validation & Unified Exception Handling
 
-Tài liệu này quy định việc sử dụng Class Validator, thiết lập ValidationPipe toàn cục và xử lý lỗi tập trung qua Exceptions Filters trong NestJS.
+This document specifies conventions for using Class Validator, configuring the global ValidationPipe, and handling errors centrally via Exception Filters in NestJS.
 
 ---
 
-## 🛡️ Kiểm Thử Dữ Liệu Đầu Vào (Validation & Transformation)
-- **Định hình DTO nghiêm ngặt:** Toàn bộ dữ liệu đầu vào của HTTP Request (`@Body()`, `@Query()`, `@Param()`) phải được đặc tả qua các lớp DTO sử dụng decorator từ `class-validator` (như `@IsString()`, `@IsEmail()`, `@IsInt()`).
-- **Kích hoạt ống lọc toàn cục (Global Validation Pipe):** Khai báo tại file `main.ts` để tự động lọc bỏ các thuộc tính không nằm trong danh sách trắng (whitelist) và tự động ép kiểu dữ liệu (transform).
+## 🛡️ Input Validation & Transformation
+- **Strict DTO Mapping:** All incoming HTTP request data (`@Body()`, `@Query()`, `@Param()`) must be mapped using DTO classes decorated with rules from `class-validator` (such as `@IsString()`, `@IsEmail()`, `@IsInt()`).
+- **Global Validation Pipe:** Configure the global `ValidationPipe` inside `main.ts` to automatically strip properties not declared in the DTO (whitelist) and transform inputs into their corresponding types.
 
   ```typescript
-  // Trong file main.ts
+  // Inside main.ts
   app.useGlobalPipes(
     new ValidationPipe({
-      whitelist: true,            // Tự động loại bỏ các thuộc tính không khai báo trong DTO
-      forbidNonWhitelisted: true, // Ném lỗi 400 nếu client gửi thuộc tính thừa
-      transform: true,            // Tự động chuyển đổi kiểu dữ liệu (string sang number, object sang DTO class)
+      whitelist: true,            // Auto-strips properties not declared in DTO
+      forbidNonWhitelisted: true, // Throws HTTP 400 if client sends extra fields
+      transform: true,            // Auto-casts types (e.g. string to number, object to class instance)
     }),
   );
   ```
 
 ---
 
-## 🚨 Quản Lý Ngoại Lệ Toàn Cục (Unified Exception Handling)
-- **Cấm trả về lỗi hệ thống thô:** Tuyệt đối không để lộ lỗi thô (chẳng hạn như lỗi từ DB, lỗi kết nối dịch vụ) ra ngoài client với mã lỗi 500.
-- **Sử dụng HttpExceptions tích hợp:** Bắt buộc phải bắt lỗi (try/catch) ở tầng Service và ánh xạ sang các Http Exception tường minh của NestJS (`NotFoundException`, `BadRequestException`, `ForbiddenException`, v.v.).
+## 🚨 Unified Exception Handling
+- **No Raw System Errors:** Never expose raw database or execution exceptions directly to clients with HTTP 500 errors.
+- **Built-in HttpExceptions:** Implement try/catch blocks within Services and map failures to explicit NestJS HttpExceptions (e.g., `NotFoundException`, `BadRequestException`, `ForbiddenException`).
   
   ```typescript
   try {
     return await this.courseRepo.findOneOrFail(id);
   } catch (error) {
-    throw new NotFoundException("Khóa học không tồn tại trên hệ thống.");
+    throw new NotFoundException("The requested course does not exist.");
   }
   ```
 
-- **Tập trung hóa bằng Exception Filter:** Xây dựng một Filter toàn cục để cấu trúc lại định dạng JSON trả về cho Client một cách đồng nhất. Phản hồi lỗi hệ thống mong muốn phải có cấu trúc:
+- **Global Exception Filter:** Implement a global Exception Filter to structure JSON error responses uniformly. The standardized error payload must follow this structure:
 
   ```json
   {
@@ -41,6 +41,6 @@ Tài liệu này quy định việc sử dụng Class Validator, thiết lập V
     "statusCode": 404,
     "timestamp": "2026-06-13T06:48:24.000Z",
     "path": "/api/v1/courses/999",
-    "message": "Khóa học không tồn tại trên hệ thống."
+    "message": "The requested course does not exist."
   }
   ```

package/templates/nestjs/skills/nestjs-module/SKILL.md

@@ -1,24 +1,24 @@
 ---
 name: nestjs-module
-description: Tự động sinh trọn bộ cấu phần gồm Module, Controller, Service, DTO, Entity theo đúng chuẩn hệ thống NestJS
+description: Automatically scaffold a complete NestJS Module including Controller, Service, DTO, and Entity according to standard conventions
 ---
 
-Tuân thủ quy trình này để tạo mới một Module NestJS hoặc mở rộng một mô-đun hiện có.
+Follow this process to generate a new NestJS Module or extend an existing one.
 
-Đầu vào (Inputs):
-- moduleName: Tên của mô-đun cần tạo (ví dụ: `products`)
-- targetPath: Thư mục đích đặt mã nguồn bên dưới `src/`
-- functionality: Tóm tắt yêu cầu nghiệp vụ và các endpoints cần cung cấp
+Inputs:
+- moduleName: Name of the module to create (e.g., `products`)
+- targetPath: The destination path inside `src/` to place the code
+- functionality: Summary of the business requirements and endpoints to expose
 
-Các bước thực hiện (Steps):
-1. Tạo thư mục mô-đun `<moduleName>/` bên dưới thư mục `src/` (ví dụ: `src/products`).
-2. Định nghĩa Entity model trong thư mục `<moduleName>/entities/`.
-3. Định nghĩa các Request/Response DTO trong thư mục `<moduleName>/dto/`. Thêm các decorator validation tương ứng.
-4. Xây dựng lớp Service trong `<moduleName>/` kế thừa DI của NestJS. Đặt toàn bộ business logic và bắt lỗi để ném ra các HttpException tường minh ở đây.
-5. Xây dựng Controller trong `<moduleName>/` để ánh xạ các yêu cầu HTTP, kiểm tra phân quyền (Guards) và trả về kết quả JSON phù hợp.
-6. Đăng ký Controller và Service vào file định nghĩa mô-đun `<moduleName>.module.ts`, export Service nếu các module khác cần sử dụng.
-7. Viết unit test cho Service (`.spec.ts`) và cấu hình kịch bản kiểm thử tích hợp (E2E) sử dụng Supertest.
-8. Chạy kiểm tra lỗi cục bộ:
+Steps:
+1. Create a module directory `<moduleName>/` under the `src/` directory (e.g., `src/products`).
+2. Define the Entity model in the `<moduleName>/entities/` folder.
+3. Define the Request/Response DTO classes in the `<moduleName>/dto/` folder. Apply appropriate validation decorators.
+4. Implement the Service class in `<moduleName>/` using NestJS Dependency Injection. Write 100% of the business logic here, handle exceptions, and throw explicit HttpExceptions.
+5. Implement the Controller class in `<moduleName>/` to map HTTP requests, configure permission checks (Guards), and return the JSON response.
+6. Register the Controller and Service inside the module definition file `<moduleName>.module.ts`. Export the Service if other modules need to consume it.
+7. Write unit tests for the Service (`.spec.ts`) and create E2E integration test scripts using Supertest.
+8. Execute local validation:
    - `{{runCommand}} lint`
    - `{{runCommand}} typecheck`
    - `{{runCommand}} test`

package/templates/next-js/AGENTS.md.hbs

@@ -1,41 +1,45 @@
-## 🗺️ Hướng Dẫn Phát Triển Next.js (App Router)
-
-### 🔄 Vòng Đời Phát Triển Tác Nhân (Agent Development Lifecycle)
-Tác nhân AI phải thực hiện tất cả các nhiệm vụ Next.js theo quy trình 5 bước sau:
-1. **Thiết kế & Lập trình:** Xây dựng page và component tuân thủ cấu trúc App Router. Mặc định sử dụng React Server Components (RSC).
-2. **Kiểm thử Toàn diện:** Viết unit test cho các tiện ích xử lý nghiệp vụ và kiểm thử hành vi giao diện bằng Jest/Vitest.
-3. **Chất lượng Mã nguồn:** Chạy các lệnh kiểm tra lỗi cú pháp và kiểu dữ liệu:
-   - Kiểm tra Lint: `{{runCommand}} lint`
-   - Kiểm tra Kiểu dữ liệu: `{{runCommand}} typecheck`
-   - Chạy Kiểm thử: `{{runCommand}} test` (hoặc `{{runCommand}} test -- --run` cho môi trường CI/CD)
-   - Chạy Build thử nghiệm: `{{runCommand}} build`
-4. **Quản lý Thư viện:** Cài đặt các thư viện mới bằng lệnh: `{{packageManager}} add [tên_thư_viện]`. Tuyệt đối cấm sửa thủ công file lock `{{lockFile}}`.
+## 🗺️ Next.js Development Guide (App Router)
 
----
-
-### 🏗️ Kiến Trúc Hệ Thống Bản Mẫu (Template Blueprint)
-Vui lòng tham khảo các tài liệu quy tắc chi tiết dưới đây:
-- Quy ước viết mã, định dạng file, cấu trúc import tự động và quy tắc tổ chức folder: `@next-style.md`
-- Phân định ranh giới kiến trúc giữa React Server Components (RSC) và React Client Components (RCC): `@server-client-components.md`
-- Tiêu chuẩn hóa việc gọi API tại tầng Server, quản lý cơ chế Caching, Revalidation và triển khai Server Actions bảo mật: `@data-fetching-mutations.md`
-- Quy định bắt buộc về Semantic HTML5 và tích hợp Dynamic Metadata API: `@seo-metadata.md`
-- Quy trình từng bước giúp khởi tạo một Page hoặc Route mới không lỗi: `@SKILL.md`
+### 🔄 Agent Development Lifecycle
+The AI Agent must execute all Next.js tasks following this structured 5-stage lifecycle:
+1. **Design & Code:** Build pages and components adhering to the App Router conventions. Default to React Server Components (RSC) as described in `@server-client-components.md`.
+2. **Comprehensive Testing:** Write unit tests for business utilities and component behavior using Jest/Vitest.
+3. **Troubleshooting & Debugging:** When debugging data loading or hydration mismatch issues, isolate Server and Client component scopes.
+4. **Code Quality & Review:** Perform self-review using `@data-fetching-mutations.md` (for Server Actions and query caching parameters) and `@seo-metadata.md`. Check styling rules in `@next-style.md`.
+5. **Production Readiness:** Verify compilation, type checks, and next builds compile warning-free before committing.
 
 ---
 
-### 🏛️ Quy Tắc Phát Triển Nghiêm Ngặt
+### 🏗️ Template Blueprint
+Refer to the detailed rules below:
+- Coding conventions, formatting, import sorting, and directory structure: `@next-style.md`
+- Architectural boundaries between React Server Components (RSC) and React Client Components (RCC): `@server-client-components.md`
+- Server-side data fetching, caching, revalidation, and secure Server Actions: `@data-fetching-mutations.md`
+- Semantic HTML5 standards and Dynamic Metadata API configurations: `@seo-metadata.md`
+- Step-by-step process to generate new Pages or Routes cleanly: `@next-feature`
 
-#### 1. Kiến Trúc Thành Phần (Rendering Paradigm)
-- **Mặc định là Server Components:** Tất cả các component trong thư mục `app/` mặc định phải là React Server Components (RSC).
-- **Cách ly Client Components (RCC):** Chỉ gắn directive `"use client"` ở lớp component lá (Leaf Components) cần tương tác (như xử lý Form, Nút bấm bắt sự kiện onClick, sử dụng useState, useEffect, hoặc các Hook trình duyệt).
-
-#### 2. Fetching Dữ Liệu & Server Actions
-- **Gọi dữ liệu tại gốc:** Thực hiện `fetch()` trực tiếp bên trong các async Server Components để tận dụng tối đa cơ chế tối ưu hóa request và bảo mật mã nguồn API token tại Server.
-- **Quản lý bộ nhớ đệm (Caching & Revalidation):** Nghiêm cấm sử dụng fetch thô không có cấu hình kiểm soát vòng đời dữ liệu.
-- **Đột biến dữ liệu (Mutations via Server Actions):** Toàn bộ các tương tác POST, PUT, DELETE phải qua Server Actions (`"use server"`).
-- **Trải nghiệm người dùng mượt mà:** Sử dụng hook `useActionState` (hoặc `useFormState`) để quản lý trạng thái phản hồi của form từ server và bọc các tác vụ mutate trong `useTransition` nhằm duy trì giao diện không bị đóng băng.
+---
 
-#### 3. Tối Ưu Hóa Hiệu Năng & SEO
-- **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.
-- **Cấu hình Metadata động:** 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.
+### 🏛️ Strict Development Rules
+
+#### 1. Rendering Paradigm
+- **Server Components by Default:** All components within the `app/` directory must default to React Server Components (RSC).
+- **Isolate Client Components (RCC):** Declare `"use client"` only at leaf components that require interactivity (e.g., Form submissions, click handlers, `useState`, `useEffect`, or browser APIs).
+
+#### 2. Data Fetching & Server Actions
+- **Fetch at the Source:** Execute `fetch()` directly inside async Server Components to optimize request caching and protect API tokens/secrets.
+- **Cache Management:** Never use raw fetch without specifying caching/revalidation parameters.
+- **Mutations via Server Actions:** Handle POST, PUT, and DELETE mutations using Server Actions (marked with `"use server"`).
+- **Fluid UX:** Use the `useActionState` (or `useFormState`) hook to manage server response states and wrap mutation triggers in `useTransition` to keep the UI responsive.
+
+#### 3. Performance & SEO Optimizations
+- **Image Optimization:** Never use raw `<img>` tags. Use `next/image`'s `<Image />` with appropriate `sizes` attributes, and set `priority` for above-the-fold images.
+- **Navigation:** Use `<Link />` from `next/link` to enable background pre-fetching when links enter the viewport.
+- **Dynamic Metadata:** Export a `generateMetadata` function in dynamic routes to optimize search engine crawling.
+
+### 🧪 Verification & Testing
+Before completing a task, run the following verification pipeline:
+- **Linting:** `{{runCommand}} lint`
+- **Type Checking:** `{{runCommand}} typecheck`
+- **Testing:** `{{runCommand}} test`
+- **Build Validation:** `{{runCommand}} build`

package/templates/next-js/rules/data-fetching-mutations.md

@@ -1,36 +1,36 @@
-# Gọi Dữ Liệu & Đột Biến Dữ Liệu (Data Fetching & Mutations)
+# Data Fetching & Mutations
 
-Tài liệu này quy định tiêu chuẩn gọi API, quản lý bộ nhớ đệm (caching) và thay đổi dữ liệu sử dụng Next.js Server Actions.
+This document defines standard conventions for calling APIs, managing caching, and performing data mutations using Next.js Server Actions.
 
 ---
 
-## 🔌 Gọi Dữ Liệu Tại Gốc (Data Fetching at the Source)
-- **Thực hiện trong RSC:** Gọi dữ liệu `fetch()` trực tiếp bên trong các async Server Components (`RSC`). Điều này giúp bảo mật API endpoint, token xác thực và giảm thiểu độ trễ mạng bằng cách gộp xử lý trên server.
-- **Quy tắc:** Không sử dụng các client-side fetch wrapper tùy tiện trong các server pages. Hãy sử dụng cú pháp async/await tiêu chuẩn.
+## 🔌 Data Fetching at the Source
+- **Execute inside RSCs:** Call `fetch()` directly inside async Server Components (`RSC`). This secures API endpoints, protects authentication tokens, and minimizes network latency by co-locating fetching and rendering.
+- **Rule:** Do not use client-side fetch wrappers inside server pages. Use standard async/await syntax.
 
 ---
 
-## 💾 Quản Lý Bộ Nhớ Đệm (Caching & Revalidation)
-- **Cấm Fetch Thô:** Nghiêm cấm sử dụng fetch() thô mà không có cấu hình kiểm soát vòng đời dữ liệu hoặc chiến lược revalidate rõ ràng.
+## 💾 Caching & Revalidation
+- **No Raw Fetch:** Using raw `fetch()` without specifying caching or revalidation strategies is prohibited.
   
-  * **Không hợp lệ (❌ Nghiêm cấm):**
+  * **Invalid (❌ Prohibited):**
     ```typescript
-    // Fetch dữ liệu tĩnh vô thời hạn mà không có chiến lược revalidate rõ ràng
+    // Fetches static data indefinitely without any revalidation strategy
     const res = await fetch('https://api.skillverse.vn/v1/courses');
     ```
-  * **Hợp lệ (✔️ Khuyến khích):**
+  * **Valid (✔️ Recommended):**
     ```typescript
-    // Cấu hình ISR (Incremental Static Regeneration) rõ ràng với cache tag
+    // Configure ISR (Incremental Static Regeneration) with an explicit cache tag
     const res = await fetch('https://api.skillverse.vn/v1/courses', { 
       next: { revalidate: 3600, tags: ['courses'] } 
     });
     ```
-- **Làm mới bộ nhớ đệm:** Sử dụng `revalidatePath` hoặc `revalidateTag` bên trong các Server Actions để xóa các bản ghi cũ trong cache và bắt buộc Next.js cập nhật lại dữ liệu mới.
+- **Cache Refreshing:** Call `revalidatePath` or `revalidateTag` inside Server Actions to purge stale cache entries and force Next.js to pull fresh data.
 
 ---
 
-## ⚡ Đột Biến Dữ Liệu (Mutations via Server Actions)
-- **Sử dụng Server Actions:** Toàn bộ các tương tác POST, PUT, DELETE, PATCH phải qua Server Actions được đánh dấu bằng directive `"use server"` ở đầu hàm hoặc đầu file chứa hành động.
-- **Trải nghiệm người dùng mượt mà:**
-  - Sử dụng hook `useActionState` (hoặc `useFormState` trong các phiên bản trước React 19) để quản lý trạng thái phản hồi của form từ server và kiểm soát trạng thái đang xử lý (`isPending`).
-  - Bọc các tác vụ mutate trong `useTransition` nhằm duy trì giao diện người dùng mượt mà, không bị đóng băng trong quá trình xử lý ngầm.
+## ⚡ Mutations via Server Actions
+- **Use Server Actions:** All POST, PUT, DELETE, and PATCH mutations must be processed through Server Actions marked with the `"use server"` directive at the top of the function or file.
+- **Fluid User Experience:**
+  - Use the `useActionState` (or `useFormState` in React versions prior to 19) hook to manage server response states and track the `isPending` state.
+  - Wrap mutation executions inside `useTransition` to keep the user interface responsive and prevent freezing during background mutations.

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

@@ -1,32 +1,32 @@
-# Quy Ước Đặt Tên & Coding Style cho Next.js (App Router)
+# Next.js Naming Conventions & Coding Style
 
-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.
+This document defines conventions for directory structures, naming patterns, imports, and feature organization inside Next.js App Router projects.
 
 ---
 
-## 🏷️ Quy Ước Đặt Tên (Naming Conventions)
+## 🏷️ Naming Conventions
 
-| Đối Tượng | Quy Chuẩn Đặt Tên | Ví Dụ Minh Họa |
+| Element | Naming Convention | Example |
 | :--- | :--- | :--- |
-| **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` |
+| **Route Folders (`app/`)** | lowercase or kebab-case | `app/dashboard/`, `app/user-profile/` |
+| **Route Groups** | Wrapped in parentheses `(group-name)` | `app/(auth)/login/`, `app/(dashboard)/layout.tsx` |
+| **Dynamic Routes** | Wrapped in brackets `[paramName]` | `app/blog/[id]/page.tsx`, `app/shop/[...slug]/page.tsx` |
+| **Special Routing Files** | Next.js standard filenames (lowercase) | `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx` |
+| **Route Handlers** | Next.js API endpoint filenames | `route.ts` |
+| **UI Components** | PascalCase.tsx | `Button.tsx`, `ProductCard.tsx`, `SidebarSkeleton.tsx` |
+| **Custom Hooks** | camelCase starting with the `use` prefix | `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.
+- **Absolute Imports:** Always use absolute imports with the `@/` alias pointing to the root or `src/` directory (e.g., `import { Button } from "@/components/ui/Button"`). Do not use relative imports with deep directory nesting (e.g., `../../../../Button`).
+- **CSS / Styles Imports:** Import global styles only in the root `layout.tsx` file (e.g., via `globals.css` or `index.css`). Do not import raw CSS files inside individual components.
 
 ---
 
-## 📁 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:
+## 📁 Directory Organization
+- Keep directories within the `app/` folder focused strictly on routing and layout definitions.
+- Locate business components, custom hooks, services, and types inside `src/features/` or `src/components/` outside the `app/` folder. Every feature (e.g., `billing`) should encapsulate its related resources:
   - `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ẽ.
+- Expose the public API of each feature via a clean entrypoint file: `index.ts`.

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

@@ -1,18 +1,18 @@
-# Tối Ưu Hóa SEO & Cấu Trúc Semantic HTML
+# SEO Optimization & 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.
+This document specifies conventions for using HTML5 Semantic tags, optimizing image delivery, and integrating Next.js Metadata APIs to achieve high SEO performance.
 
 ---
 
-## 🔍 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:
+## 🔍 Next.js Metadata API
+- **Static Metadata:** Declare a static `metadata` object in layouts or pages that do not require dynamic route parameters:
   ```typescript
   export const metadata = {
     title: 'Dashboard | Skillverse Platform',
-    description: 'Trang tổng quan quản lý khóa học',
+    description: 'Course management overview dashboard',
   };
   ```
-- **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:
+- **Dynamic Metadata:** For dynamic routes (e.g., article details, course views), define metadata through the exported `generateMetadata` function to optimize search engine indexing:
   
   ```typescript
   import { Metadata } from 'next';
@@ -33,18 +33,18 @@ Tài liệu này quy định việc sử dụng cấu trúc thẻ Semantic, tố
 
 ---
 
-## 🎨 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.
+## 🎨 Semantic HTML5 Structure
+- **Structural Tags:** Build layouts using semantic HTML5 tags instead of nesting generic `<div>` containers:
+  - `<header>`: Main navigation bar or header sections.
+  - `<nav>`: Primary navigation links.
+  - `<main>`: Wraps the unique primary content of the page.
+  - `<section>`: General thematic groupings of content.
+  - `<article>`: Independent self-contained items (e.g., blog posts, product cards).
+  - `<footer>`: Copyright and footer link sections.
+- **Header Hierarchy:** Follow a strict heading hierarchy (from `<h1>` down to `<h6>`). Ensure there is only one `<h1>` tag per page.
 
 ---
 
-## ⚡ 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ì.
+## ⚡ Image & Link Optimizations
+- **Image Optimization:** Never use raw `<img>` tags. Use Next.js `<Image />` from `next/image` with appropriate `sizes` attributes, and set `priority` for above-the-fold images.
+- **Navigation Optimization:** Use `<Link />` from `next/link` to automatically trigger resource pre-fetching when links enter the viewport, enabling instant transition.

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

@@ -1,27 +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.
+This document establishes architectural boundaries and classification rules for components in Next.js App Router projects.
 
 ---
 
 ## 🏛️ 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.
+- **Default Behavior:** All pages, layouts, and components created within the `app/` routing directory must default to React Server Components (RSC).
+- **RSC Benefits:**
+  - Fetch data directly using async/await syntax at the server level.
+  - Securely utilize server-side libraries and APIs (e.g., database queries, file reading, private tokens).
+  - Decrease client-side bundle sizes because RSC code remains on the server and is not sent to the browser.
+- **Rules:**
+  - Perform all data fetching and layout structure setups within RSCs.
+  - Never add the `"use client"` directive to layout or page entrypoint files unless absolutely necessary.
 
 ---
 
 ## 💻 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.
+- **Definition:** Components that execute on the browser to support dynamic user interactions and state updates.
+- **Identifying RCCs:** Attach the `"use client"` directive only at leaf component levels when they:
+  - Use React hooks (`useState`, `useReducer`, `useEffect`, `useLayoutEffect`).
+  - Use browser-specific APIs (e.g., `window`, `localStorage`, custom viewport hooks).
+  - Bind DOM event listeners (e.g., `onClick`, `onChange`, `onSubmit`).
+- **RCC Isolation Guidelines:**
+  - Keep RCCs at the absolute leaf level of the rendering tree to optimize loading speed.
+  - *Example:* If a product list page (RSC) includes a search input (RCC), encapsulate the search input in its own component (e.g., `<SearchBar />` marked with `"use client"`) and import it into the server-rendered parent page.

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

@@ -1,25 +1,25 @@
 ---
 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
+description: Generate or extend a new Next.js + TypeScript page or route handler with caching and 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.
+Follow this process to generate a new page, layout, or API route handler in 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
+Inputs:
+- featureName: Name of the route or page (e.g., `dashboard`)
+- targetPath: The directory inside the `app/` folder to implement the route
+- userFlow: Brief description of the page behavior and layout
 
-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ộ:
+Steps:
+1. Scan neighboring directories in the `app/` folder to check for shared layouts and error boundaries (`error.tsx`).
+2. Set up the route directory structure according to Next.js standards (e.g., `app/(dashboard)/billing`).
+3. Declare TypeScript interfaces for route parameters and query parameters.
+4. Implement the page or layout structure as a **React Server Component (RSC)**.
+5. If user interaction or form handling is needed, isolate it in a leaf Client Component (RCC) marked with `"use client"` and import it into the parent RSC.
+6. Configure explicit caching parameters for all data fetching `fetch()` calls.
+7. Set up static or dynamic SEO metadata using the `generateMetadata` function.
+8. Define a local error handler file (`error.tsx`) in the route directory to catch runtime exceptions.
+9. Execute local validation:
    - `{{runCommand}} lint`
    - `{{runCommand}} typecheck`
    - `{{runCommand}} test`

package/templates/rust/AGENTS.md.hbs

@@ -0,0 +1,41 @@
+## 🗺️ Rust Development Guide
+
+### 🔄 Agent Development Lifecycle
+The AI Agent must execute all Rust tasks following this structured 5-stage lifecycle:
+1. **Design & Code:** Implement business logic adhering to Rust conventions. Enforce structural separation: `main.rs` (for binary application setup) and `lib.rs` (for core business logic that can be reused and tested).
+2. **Comprehensive Testing:** Write unit tests inside internal test modules and integration tests in the `/tests` directory. Mocks and double components should be declared under `#[cfg(test)]`.
+3. **Troubleshooting & Debugging:** When debugging lifetimes, memory borrow errors, or asynchronous deadlocks, refer to `@memory-concurrency.md` directives.
+4. **Code Quality & Review:** Verify code conforms strictly to `@rust-style.md` check criteria (preventing warnings, formatting code, avoiding over-cloning).
+5. **Crate Architecture:** Organize workspace dependencies using Cargo Workspaces if building multi-crate projects, maintaining encapsulation guidelines in `@project-layout.md`.
+
+---
+
+### 🏗️ Template Blueprint
+Refer to the detailed rules below:
+- Idiomatic Rust, clippy lints, and cloning optimizations: `@rust-style.md`
+- Crate modules, Cargo Workspaces, and Trait-based Dependency Injection: `@project-layout.md`
+- Failures management, Result/Option, `thiserror`, and `anyhow`: `@error-handling.md`
+- Lifetimes `'a`, Smart Pointers, and async Tokio safety: `@memory-concurrency.md`
+- Scaffolding a Rust feature (Struct, traits, implementations, unit tests): `@rust-feature`
+- Scaffolding asynchronous database repositories and models: `@rust-db`
+
+---
+
+### 🏛️ Strict Development Rules
+
+#### 1. Ownership & Borrowing
+- **Avoid Over-Cloning:** Call `.clone()` on Heap types only when you must own an independent copy. Otherwise, design functions to receive read references `&T` or write references `&mut T`.
+- **Exclusive Mutable Borrow:** Ensure only one mutable reference `&mut T` exists at a time, and never let it coexist with any read references `&T` in the same scope.
+
+#### 2. Safe Error Handling
+- **No Unwraps:** Never use `.unwrap()` or `.expect()` in production code (except in tests). Propagate errors using `Result<T, E>` or `Option<T>` to ensure system reliability. Manage library errors with `thiserror` and application errors with `anyhow` as outlined in `@error-handling.md`.
+
+#### 3. Async Concurrency (Tokio)
+- **CPU-Bound Tasks:** Never run heavy CPU operations (e.g., encryption, intensive loops) directly inside async contexts. Offload them using `tokio::task::spawn_blocking`.
+- **Mutex Selection:** Prefer standard `std::sync::Mutex` for synchronizing state across threads if the guard is not held across `.await` points. Use `tokio::sync::Mutex` only when needed to prevent scheduling blocking.
+
+### 🧪 Verification & Testing
+Before completing a task, run the following verification pipeline locally:
+- **Lint check:** `cargo clippy --all-targets -- -D warnings`
+- **Testing:** `cargo test`
+- **Formatting:** `cargo fmt -- --check`

package/templates/rust/rules/error-handling.md

@@ -0,0 +1,36 @@
+# Error Handling & Fault Control in Rust
+
+This document defines strict rules for handling, wrapping, and propagating failures using idiomatic Rust patterns.
+
+---
+
+## 🚫 Avoid Panics in Production
+- **Strict Rule:** Never use `panic!`, `.unwrap()`, or `.expect()` in production application code. Doing so triggers process termination, resulting in service interruption.
+- **Exceptions:** Only use panics in:
+  - Unit and Integration Tests.
+  - Initial bootstrapping (e.g., parsing critical files at startup) when missing items make recovery impossible.
+  - Invariants where the logic guarantees a failure is impossible.
+
+---
+
+## 🔄 Result Propagation with the `?` Operator
+- All fallible business logic operations must return `Result<T, E>` or `Option<T>`.
+- Use the `?` operator to propagate errors up the call stack, maintaining a clean syntax.
+
+---
+
+## 📚 Error Libraries: `thiserror` vs `anyhow`
+Never mix these libraries arbitrarily. Comply with the following separation:
+- **Use `thiserror` for Library Crates / Domain Modules:** Creates strongly-typed, detailed error definitions with custom display messages.
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum DatabaseError {
+    #[error("User not found with ID {0}")]
+    UserNotFound(i64),
+    #[error("Database connection failure: {0}")]
+    ConnectionFailed(String),
+}
+```
+- **Use `anyhow` for Application Entrypoints (API Gateway / CLI main):** Ideal for general error grouping and stack propagation without complex type mapping.