agent-workflow-kit-cli 1.3.2 → 1.3.3

package/templates/nestjs/AGENTS.md.hbs

@@ -1,38 +1,38 @@
-## 🗺️ Hướng Dẫn Phát Triển NestJS (Node.js Backend)
-
-### 🔄 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ụ NestJS theo quy trình 5 bước sau:
-1. **Thiết kế & Lập trình:** Triển khai các lớp nghiệp vụ tuân thủ cấu trúc Module-driven. Giữ Controller mỏng, đặt 100% logic nghiệp vụ trong Service.
-2. **Kiểm thử Toàn diện:** Viết unit test cho các Service sử dụng Jest Mocking (`.spec.ts`) và viết kiểm thử tích hợp đầu cuối (E2E) sử dụng Supertest.
-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}}`.
+## 🗺️ NestJS Development Guide (Node.js Backend)
+
+### 🔄 Agent Development Lifecycle
+The AI Agent must execute all NestJS tasks following this 5-step workflow:
+1. **Design & Implementation:** Implement business logic adhering to the Module-driven architecture. Keep Controllers thin; place 100% of business logic within Services.
+2. **Comprehensive Testing:** Write unit tests for Services using Jest Mocking (`.spec.ts`) and end-to-end (E2E) integration tests using Supertest.
+3. **Code Quality & Type Safety:** Run syntax check and type check commands:
+   - Linting: `{{runCommand}} lint`
+   - Type Checking: `{{runCommand}} typecheck`
+   - Testing: `{{runCommand}} test` (or `{{runCommand}} test -- --run` for CI/CD environments)
+   - Build Validation: `{{runCommand}} build`
+4. **Dependency Management:** Install new libraries using `{{packageManager}} add [library_name]`. Never modify the lockfile `{{lockFile}}` manually.
 
 ---
 
-### 🏗️ 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:
-- Hướng dẫn coding style chuẩn TypeScript, quy tắc căn lề, sắp xếp decorator và tổ chức mã nguồn sạch: `@nestjs-style.md`
-- Quy định chặt chẽ về ranh giới Module, cơ chế cô lập mã nguồn, Encapsulation và chia sẻ tài nguyên: `@module-architecture.md`
-- Cấu hình Class Validator, chuyển đổi dữ liệu thông qua ValidationPipe và xử lý lỗi tập trung bằng Exceptions Filters: `@validation-errors.md`
-- Quy trình tự động sinh trọn bộ cấu phần gồm Module, Controller, Service, DTO, Entity theo đúng chuẩn hệ thống: `@SKILL.md`
+### 🏗️ Template Blueprint
+Refer to the detailed rules below:
+- TypeScript coding style, indentation, decorator sorting, and clean code conventions: `@nestjs-style.md`
+- Strict module boundaries, encapsulation, and resource sharing rules: `@module-architecture.md`
+- Class Validator setups, ValidationPipe data transformations, and Exception Filters: `@validation-errors.md`
+- Process to scaffold modular components (Module, Controller, Service, DTO, Entity): `@SKILL.md`
 
 ---
 
-### 🏛️ Quy Tắc Phát Triển Nghiêm Ngặt
+### 🏛️ Strict Development Rules
 
-#### 1. Tiêm Phụ Thuộc (Dependency Injection)
-- **Cấm tiêm thuộc tính (Property Injection):** Tuyệt đối không dùng `@Inject()` trực tiếp trên thuộc tính của Class trừ trường hợp tiêm các token tùy biến (Custom Tokens).
-- **Bắt buộc tiêm qua Hàm Khởi Tạo (Constructor Injection):** Sử dụng cơ chế tự động phân giải phụ thuộc của NestJS qua từ khóa `private readonly`.
+#### 1. Dependency Injection (DI)
+- **No Property Injection:** Never use the `@Inject()` decorator directly on class properties unless injecting Custom Tokens. Property injection limits test mocking capabilities.
+- **Constructor Injection Required:** Leverage NestJS's auto-dependency resolution via constructor parameters using `private readonly`.
 
-#### 2. 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`.
-- **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).
+#### 2. Input Validation & Transformation
+- **Strict DTO Definitions:** All incoming HTTP request parameters (`@Body()`, `@Query()`, `@Param()`) must be mapped to DTO classes decorated with `class-validator` rules.
+- **Global Validation Pipe:** Configure a global `ValidationPipe` in `main.ts` to strip non-whitelisted properties and automatically transform types.
 
-#### 3. 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) 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`).
-- **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.
+#### 3. Unified Exception Handling
+- **No Raw Server Errors:** Never expose raw database or system exceptions (HTTP 500) to clients.
+- **Built-in HttpExceptions:** Handle try/catch flows inside Services and map errors to explicit NestJS HttpExceptions (e.g., `NotFoundException`, `BadRequestException`, `ForbiddenException`).
+- **Global Exception Filter:** Expose a global Exception Filter to format all error responses consistently in JSON format.

package/templates/nestjs/rules/module-architecture.md

@@ -1,14 +1,14 @@
-# Kiến Trúc Mô-đun & Cơ Chế Tiêm Phụ Thuộc (DI)
+# Modular Architecture & Dependency Injection (DI)
 
-Tài liệu này quy định ranh giới Module, cơ chế cô lập mã nguồn, Encapsulation và cách tiêm phụ thuộc chuẩn trong NestJS.
+This document defines module boundaries, code isolation (encapsulation), and dependency injection standards in NestJS.
 
 ---
 
-## 💉 Tiêm Phụ Thuộc (Dependency Injection)
-- **Cấm tiêm thuộc tính (Property Injection):** Tuyệt đối không dùng `@Inject()` trực tiếp trên thuộc tính của Class trừ trường hợp tiêm các token tùy biến (Custom Tokens). Việc tiêm thuộc tính làm giảm khả năng kiểm thử (mocking) và làm loãng mã nguồn.
-- **Bắt buộc tiêm qua Hàm Khởi Tạo (Constructor Injection):** Sử dụng cơ chế tự động phân giải phụ thuộc của NestJS qua từ khóa `private readonly` trong constructor.
+## 💉 Dependency Injection (DI)
+- **No Property Injection:** Never use the `@Inject()` decorator directly on class properties unless injecting Custom Tokens. Property injection degrades mock testing and litters class definitions.
+- **Constructor Injection Required:** Use constructor parameter injection with the `private readonly` modifier to leverage NestJS's dependency resolution.
 
-  * **Không hợp lệ (❌ Cấm viết):**
+  * **Invalid (❌ Prohibited):**
     ```typescript
     @Injectable()
     export class AuthService {
@@ -16,7 +16,7 @@ Tài liệu này quy định ranh giới Module, cơ chế cô lập mã nguồn
       private readonly usersService: UsersService;
     }
     ```
-  * **Hợp lệ (✔️ Khuyến khích):**
+  * **Valid (✔️ Recommended):**
     ```typescript
     @Injectable()
     export class AuthService {
@@ -26,10 +26,10 @@ Tài liệu này quy định ranh giới Module, cơ chế cô lập mã nguồn
 
 ---
 
-## 🏗️ Ranh Giới Mô-đun & Encapsulation
-- **Cô lập theo mặc định (Encapsulation by Default):** Các Provider (Services, Repositories) bên trong một Module mặc định là private. Các module khác không thể truy cập nếu không được export công khai.
-- **Chia sẻ tài nguyên qua Module:** Khi Module B muốn sử dụng Service của Module A:
-  1. Thêm Service đó vào mảng `exports` trong `@Module()` của Module A.
-  2. Import Module A vào mảng `imports` của Module B.
-  * Nghiêm cấm import trực tiếp Service của Module A vào danh sách `providers` của Module B.
-- **Mô-đun Toàn cục (Global Modules):** Hạn chế sử dụng `@Global()` ngoại trừ các mô-đun hạ tầng chung cực kỳ ổn định (như cơ sở dữ liệu hoặc cấu hình hệ thống).
+## 🏗️ Module Boundaries & Encapsulation
+- **Encapsulated by Default:** Providers (Services, Repositories) inside a Module are private by default. Other modules cannot access them unless they are explicitly exported.
+- **Sharing Resources:** When Module B needs to use a Service declared in Module A:
+  1. Add that Service to the `exports` array in Module A's `@Module()` decorator.
+  2. Add Module A to the `imports` array in Module B's `@Module()` decorator.
+  * **Strict Rule:** Never import a Service of Module A directly into the `providers` array of Module B.
+- **Global Modules:** Avoid using `@Global()` unless configuring highly stable infrastructure modules (e.g., Database connections or Config systems).

package/templates/nestjs/rules/nestjs-style.md

@@ -1,16 +1,16 @@
-# Quy Ước Đặt Tên & Coding Style cho NestJS
+# NestJS Naming Conventions & Coding Style
 
-Tài liệu này hướng dẫn coding style chuẩn TypeScript, quy tắc đặt tên tệp tin và lớp trong NestJS.
+This document outlines standard guidelines for TypeScript coding styles, filename notations, and class naming conventions in NestJS.
 
 ---
 
-## 🏷️ Quy Ước Đặt Tên (Naming Conventions)
+## 🏷️ Naming Conventions
 
-### Kỹ thuật Đặt Tên Tệp (Dot Notation)
-Tất cả các tệp tin trong NestJS phải tuân thủ nghiêm ngặt định dạng cấu trúc: `<tên-đối-tượng>.<loại-cấu-phần>.ts`.
+### Filename Notation (Dot Notation)
+All filenames in NestJS must strictly comply with the following format: `<name>.<type>.ts`.
 
 ```bash
-# Thư mục module luôn dùng số nhiều hoặc số ít đồng nhất (Ví dụ: auth, users, products)
+# Module directories should use consistent singular or plural names (e.g., auth, users, products)
 src/users/
 ├── users.module.ts
 ├── users.controller.ts
@@ -26,8 +26,8 @@ src/users/
     └── logging.interceptor.ts
 ```
 
-### Quy ước đặt tên Lớp (Class Naming)
-Tên lớp phải được viết theo định dạng PascalCase và kết thúc bằng tên cụ thể của loại cấu phần đó:
+### Class Naming
+Class names must use `PascalCase` and end with the specific component suffix representing their role:
 - **Controller:** `src/auth/auth.controller.ts` $\rightarrow$ `export class AuthController {}`
 - **Service:** `src/auth/auth.service.ts` $\rightarrow$ `export class AuthService {}`
 - **Module:** `src/auth/auth.module.ts` $\rightarrow$ `export class AuthModule {}`
@@ -35,7 +35,7 @@ Tên lớp phải được viết theo định dạng PascalCase và kết thúc
 
 ---
 
-## 📦 TypeScript & Sắp Xếp Decorator
-- **Sắp xếp Decorator:** Nhóm và sắp xếp các decorator một cách khoa học. Các decorator định nghĩa phương thức HTTP (`@Get()`, `@Post()`) nằm trên cùng, tiếp theo là cấu hình bảo mật hoặc kiểm duyệt đầu vào (`@UseGuards()`, `@UseInterceptors()`).
-- **Kiểu trả về tường minh:** Khai báo kiểu trả về rõ ràng cho tất cả các phương thức trong Controller và Service để bảo đảm tính chặt chẽ của kiểu dữ liệu.
-- **Nghiêm cấm kiểu dữ liệu `any`:** Luôn khai báo class hoặc interface tương ứng cho các tham số và kết quả xử lý.
+## 📦 TypeScript & Decorator Sorting
+- **Decorator Sorting:** Group and organize decorator annotations systematically. Place HTTP methods (`@Get()`, `@Post()`) on top, followed by guards or interceptors (`@UseGuards()`, `@UseInterceptors()`).
+- **Explicit Return Types:** Always define clear return types for all Controller and Service methods to guarantee type safety.
+- **Strictly Ban the `any` Type:** Avoid generic `any` keywords. Create proper classes, interfaces, or types for all arguments and responses.

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,41 @@
-## 🗺️ 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)
+
+### 🔄 Agent Development Lifecycle
+The AI Agent must execute all Next.js tasks following this 5-step workflow:
+1. **Design & Implementation:** Build pages and components adhering to the App Router conventions. Default to React Server Components (RSC).
+2. **Comprehensive Testing:** Write unit tests for business utilities and component behavior using Jest/Vitest.
+3. **Code Quality & Type Safety:** Run syntax check and type check commands:
+   - Linting: `{{runCommand}} lint`
+   - Type Checking: `{{runCommand}} typecheck`
+   - Testing: `{{runCommand}} test` (or `{{runCommand}} test -- --run` for CI/CD environments)
+   - Build Validation: `{{runCommand}} build`
+4. **Dependency Management:** Install new libraries using `{{packageManager}} add [library_name]`. Never modify the lockfile `{{lockFile}}` manually.
 
 ---
 
-### 🏗️ 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`
+### 🏗️ 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: `@SKILL.md`
 
 ---
 
-### 🏛️ Quy Tắc Phát Triển Nghiêm Ngặt
+### 🏛️ Strict Development Rules
 
-#### 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).
+#### 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. 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.
+#### 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. 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.
+#### 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.

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.