agent-workflow-kit-cli 1.3.1 → 1.3.2

package/templates/express/AGENTS.md.hbs

@@ -0,0 +1,41 @@
+## 🗺️ Hướng Dẫn Phát Triển Express.js (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ụ Express.js theo quy trình 5 bước sau:
+1. **Thiết kế & Lập trình:** Phân tách mã nguồn theo cấu trúc 3 lớp rõ ràng (3-Tier Architecture). Tuyệt đối cấm viết mã nguồn lộn xộn (Spaghetti Code).
+2. **Kiểm thử Toàn diện:** Viết unit test cho các Service sử dụng Jest và kiểm thử tích hợp API 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}}`.
+
+---
+
+### 🏗️ 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ã sạch, định nghĩa kiểu dữ liệu tường minh bằng TypeScript trong môi trường Express: `@express-style.md`
+- Phân định ranh giới trách nhiệm: Router nhận diện đường dẫn $\rightarrow$ Controller điều phối $\rightarrow$ Service xử lý core logic: `@router-controller.md`
+- Chiến lược xử lý lỗi bất đồng bộ (Async Error Catching) và cơ chế vận hành Middleware xử lý lỗi tập trung: `@error-handling.md`
+- Workflow chuẩn hóa giúp sinh mới một cụm API Endpoint an toàn, đầy đủ từ Router, Controller đến Validator: `@SKILL.md`
+
+---
+
+### 🏛️ Quy Tắc Phát Triển Nghiêm Ngặt
+
+#### 1. Phân Tách Lớp Tuyệt Đối (Strict Layer Separation)
+Tác nhân phải tuân thủ nghiêm ngặt chuỗi truyền dẫn dữ liệu:
+$$\text{Client} \longrightarrow \text{Router} \longrightarrow \text{Middleware} \longrightarrow \text{Controller} \longrightarrow \text{Service} \longrightarrow \text{Model/Database}$$
+- **Router:** Tuyệt đối không chứa logic xử lý, chỉ ánh xạ HTTP Method + Path và liên kết middleware xác thực/kiểm duyệt.
+- **Controller:** Chỉ bóc tách dữ liệu từ `req` (req.body, req.query, req.params), gọi lớp Service xử lý, nhận kết quả và trả về thông qua `res.status().json()`. Không làm việc trực tiếp với cơ sở dữ liệu.
+- **Service:** Nơi chứa logic nghiệp vụ, tính toán thuật toán, tương tác với lớp DB Model. Tuyệt đối không được tiếp xúc hay phụ thuộc vào các đối tượng `req` hay `res` của Express để đảm bảo tính độc lập khi viết Unit Test.
+
+#### 2. Bẫy Lỗi Bất Đồng Bộ (Async Error Handling)
+- **Không dùng try/catch thủ công tại Controller:** Việc viết try/catch ở mọi hàm trong tất cả các controller gây loãng mã nguồn.
+- **Sử dụng Wrapper Tự động:** Toàn bộ các hàm controller bất đồng bộ phải được bọc bằng một hàm tiện ích tự động bắt lỗi (như `express-async-handler`) để tự động chuyển tiếp tất cả các ngoại lệ phát sinh sang cấu phần `next()`.
+- **Middleware xử lý lỗi tập trung (Global Error Handler):** Bắt buộc phải khai báo middleware xử lý lỗi có đủ 4 tham số ở cuối tệp cấu hình server (sau khi khai báo tất cả các routes) để định dạng lại toàn bộ phản hồi lỗi.
+
+#### 3. Kiểm Thử Dữ Liệu Tự Động Với Zod Middleware
+- **Cấm Validate thủ công bằng câu lệnh điều kiện:** Không viết các đoạn code `if (!req.body.email)`.
+- **Xây dựng Middleware Validate Schema:** Phát triển một middleware dùng chung nhận vào một Schema của Zod để tự động kiểm duyệt toàn bộ dữ liệu đầu vào (body, query, params) trước khi cho phép dữ liệu đi sâu vào tầng Controller.

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

@@ -0,0 +1,88 @@
+# Bẫy Lỗi Bất Đồng Bộ & Xác Thực Dữ Liệu Tự Động (Zod Middleware)
+
+Tài liệu này quy định chiến lược xử lý lỗi bất đồng bộ (Async Error Catching), cấu hình Middleware xử lý lỗi tập trung, và tự động kiểm tra dữ liệu bằng Zod.
+
+---
+
+## 🚨 Bẫy Lỗi Bất Đồng Bộ (Async Error Handling Architecture)
+- **Không dùng try/catch thủ công tại Controller:** Việc viết try/catch ở mọi hàm trong tất cả các controller gây loãng mã nguồn.
+- **Sử dụng Wrapper Tự động:** Toàn bộ các hàm controller bất đồng bộ phải được bọc bằng một hàm tiện ích tự động bắt lỗi (như `asyncHandler`) để tự động chuyển tiếp tất cả các ngoại lệ phát sinh sang cấu phần `next()`.
+
+  ```typescript
+  import { Request, Response, NextFunction } from 'express';
+
+  // Hàm Wrapper bắt lỗi bất đồng bộ tự động
+  export const asyncHandler = (fn: Function) => (req: Request, res: Response, next: NextFunction) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+
+  // Cách triển khai thực tế tại Controller
+  export const getUserProfile = asyncHandler(async (req: Request, res: Response) => {
+    const userId = req.user.id;
+    const profile = await userService.getProfile(userId); // Nếu ném lỗi bên trong service, asyncHandler sẽ tự catch
+    return res.status(200).json({ success: true, data: profile });
+  });
+  ```
+
+---
+
+## 🔌 Middleware Xử Lý Lỗi Tập Trung (Global Error Handler)
+- **Khai báo bộ lọc:** Bắt buộc phải khai báo một middleware xử lý lỗi có đủ 4 tham số ở cuối tệp cấu hình server (sau khi khai báo tất cả các routes) để định dạng lại toàn bộ phản hồi lỗi trước khi trả về cho Client.
+
+  ```typescript
+  // Trong file app.ts hoặc server.ts
+  app.use((err: any, req: Request, res: Response, next: NextFunction) => {
+    const statusCode = err.statusCode || 500;
+    const message = err.message || 'Internal Server Error';
+
+    res.status(statusCode).json({
+      success: false,
+      status: statusCode,
+      message: message,
+      stack: process.env.NODE_ENV === 'development' ? err.stack : undefined,
+    });
+  });
+  ```
+
+---
+
+## 🛡️ Kiểm Thử Dữ Liệu Tự Động Với Zod Middleware
+- **Cấm Validate thủ công bằng câu lệnh điều kiện:** Không viết các đoạn code `if (!req.body.email)`.
+- **Xây dựng Middleware Validate Schema:** Phát triển một middleware dùng chung nhận vào một Schema của Zod để tự động kiểm duyệt toàn bộ dữ liệu đầu vào (`body`, `query`, `params`) trước khi cho phép dữ liệu đi sâu vào tầng Controller.
+
+  ```typescript
+  import { AnyZodObject, ZodError } from 'zod';
+  import { Request, Response, NextFunction } from 'express';
+
+  export const validateSchema = (schema: AnyZodObject) => {
+    return async (req: Request, res: Response, next: NextFunction): Promise<any> => {
+      try {
+        // Xác thực đồng thời cả body, query, và params thông qua cấu trúc schema của Zod
+        const parsed = await schema.parseAsync({
+          body: req.body,
+          query: req.query,
+          params: req.params,
+        });
+        
+        // Gán lại dữ liệu đã được parse sạch (và ép kiểu nếu có) vào hệ thống request
+        req.body = parsed.body;
+        req.query = parsed.query;
+        req.params = parsed.params;
+        
+        return next();
+      } catch (error) {
+        if (error instanceof ZodError) {
+          return res.status(400).json({
+            success: false,
+            message: 'Dữ liệu đầu vào không hợp lệ',
+            errors: error.errors.map((err) => ({
+              field: err.path.join('.'),
+              message: err.message,
+            })),
+          });
+        }
+        return next(error);
+      }
+    };
+  };
+  ```

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

@@ -0,0 +1,39 @@
+# Quy Ước Đặt Tên & Coding Style cho Express.js
+
+Tài liệu này hướng dẫn coding style sạch, định nghĩa kiểu dữ liệu tường minh bằng TypeScript trong môi trường Express.js.
+
+---
+
+## 🏷️ Quy Ước Đặt Tên (Naming Conventions)
+
+### Thư mục Phân lớp (Architecture Folders)
+Mã nguồn phải được tách biệt hoàn toàn theo kiến trúc 3 lớp (3-Tier Architecture):
+```bash
+src/
+├── config/             # Cấu hình biến môi trường, kết nối Database
+├── middlewares/        # Các hàm Middleware (Auth, Log, Validation)
+├── models/             # Schema cơ sở dữ liệu (Mongoose, Sequelize ORM, Prisma)
+├── routes/             # Định tuyến HTTP, cấu hình gắn kết middleware đầu vào
+├── controllers/        # Điều phối Request, định dạng Response đầu ra
+├── services/           # Chứa 100% logic nghiệp vụ xử lý dữ liệu và tính toán
+├── utils/              # Các hàm bổ trợ dùng chung
+└── app.ts              # File khởi tạo cấu hình Express App
+```
+
+### Quy ước Tên Tệp tin (File Naming)
+- **Tính đồng nhất:** Toàn bộ dự án phải chọn và tuân thủ duy nhất định dạng `kebab-case.ts`.
+- **Hậu tố định danh:** Tên file phải đi kèm vai trò kiến trúc của nó làm hậu tố:
+  - Controller: `user-controller.ts`
+  - Service: `user-service.ts`
+  - Route: `user-route.ts`
+  - Middleware: `auth-middleware.ts`, `validate-middleware.ts`
+  - Model: `user-model.ts`
+
+---
+
+## 📦 Định Nghĩa Kiểu Dữ Liệu & Quy Chuẩn TypeScript
+- **Khai báo kiểu dữ liệu tường minh:** Không dùng kiểu ngầm định. Luôn định nghĩa rõ ràng kiểu cho tham số `req`, `res`, và `next` lấy từ thư viện `express`:
+  ```typescript
+  import { Request, Response, NextFunction } from 'express';
+  ```
+- **Không lạm dụng `any`:** Định nghĩa đầy đủ các interface hoặc type cho các cấu trúc dữ liệu gửi lên và trả về cho Client.

package/templates/express/rules/router-controller.md

@@ -0,0 +1,27 @@
+# Phân Tách Lớp Trách Nhiệm (Router vs Controller vs Service)
+
+Tài liệu này đặc tả ranh giới trách nhiệm giữa các lớp trong Express.js: Router nhận diện đường dẫn $\rightarrow$ Controller điều phối $\rightarrow$ Service xử lý core logic.
+
+---
+
+## 🏛️ Chuỗi Truyền Dẫn Dữ Liệu
+Mã nguồn dự án phải tuân thủ nghiêm ngặt mô hình luồng dữ liệu 3 lớp:
+$$\text{Client} \longrightarrow \text{Router} \longrightarrow \text{Middleware} \longrightarrow \text{Controller} \longrightarrow \text{Service} \longrightarrow \text{Model/Database}$$
+
+---
+
+## 🚦 Trách Nhiệm Chi Tiết Của Từng Lớp
+
+### 1. Lớp Định Tuyến (Router Layer - `routes/`)
+- **Vai trò:** Chỉ làm nhiệm vụ map HTTP Method + Path, liên kết các middleware xác thực (Auth) hoặc kiểm duyệt định dạng đầu vào (Zod validate schema).
+- **Quy tắc:** Tuyệt đối không chứa bất kỳ logic xử lý nghiệp vụ hay điều phối dữ liệu nào. Chỉ định hướng luồng sang Controller tương ứng.
+
+### 2. Lớp Điều Phối (Controller Layer - `controllers/`)
+- **Vai trò:** Làm nhiệm vụ bóc tách dữ liệu đầu vào từ đối tượng `req` (req.body, req.query, req.params, req.user), chuyển tiếp các tham số đó sang tầng Service, nhận kết quả và trả về cho Client bằng lệnh `res.status().json()`.
+- **Quy tắc:**
+  - Không truy vấn cơ sở dữ liệu hoặc làm việc trực tiếp với ORM Models trong Controller.
+  - Không bắt lỗi try/catch thủ công (sử dụng asyncHandler để ủy thác cho bộ bắt lỗi toàn cục).
+
+### 3. Lớp Nghiệp Vụ (Service Layer - `services/`)
+- **Vai trò:** Chứa 100% logic nghiệp vụ xử lý dữ liệu, thực hiện tính toán thuật toán, tương tác với Database thông qua ORM Models.
+- **Quy tắc:** Tuyệt đối không được tiếp xúc hay phụ thuộc vào các đối tượng `req`, `res`, hay `next` của Express. Lớp Service phải độc lập hoàn toàn với framework để dễ dàng viết các bài kiểm thử Unit Test.

package/templates/express/skills/express-endpoint/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: express-endpoint
+description: Sinh hoặc mở rộng một API Endpoint Express.js + TypeScript an toàn, đầy đủ từ Router, Controller đến Validator
+---
+
+Tuân thủ quy trình này để tạo mới một API Endpoint Express.js hoặc mở rộng tuyến định tuyến hiện có.
+
+Đầu vào (Inputs):
+- endpointName: Tên của API Endpoint cần tạo (ví dụ: `user-profile`)
+- routePath: Đường dẫn tuyến HTTP của API (ví dụ: `/api/v1/users/profile`)
+- httpMethod: Phương thức HTTP (GET, POST, PUT, DELETE)
+- targetPath: Thư mục gốc chứa mã nguồn của mô-đun để đặt tệp tin
+
+Các bước thực hiện (Steps):
+1. Định nghĩa Zod Validation Schema dưới thư mục `middlewares/` hoặc bên cạnh controller để kiểm duyệt các trường dữ liệu đầu vào.
+2. Xây dựng hàm Service tương ứng bên dưới thư mục `services/` để đảm nhiệm 100% logic xử lý nghiệp vụ, truy vấn dữ liệu ORM.
+3. Triển khai Controller điều phối trong thư mục `controllers/` sử dụng tiện ích bọc `asyncHandler` để giải phóng việc try/catch thủ công, nhận tham số từ request và gửi phản hồi dạng JSON sạch.
+4. Đăng ký Controller và gắn middleware `validateSchema(zodSchema)` vào file định tuyến Route tương ứng bên dưới thư mục `routes/`.
+5. Bổ sung các test suite kiểm thử đơn vị cho Service và kiểm thử tích hợp (E2E) qua Supertest.
+6. Chạy kiểm tra lỗi cục bộ:
+   - `{{runCommand}} lint`
+   - `{{runCommand}} typecheck`
+   - `{{runCommand}} test`
+   - `{{runCommand}} build`

package/templates/nestjs/AGENTS.md.hbs

@@ -0,0 +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}}`.
+
+---
+
+### 🏗️ 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`
+
+---
+
+### 🏛️ Quy Tắc Phát Triển Nghiêm Ngặt
+
+#### 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`.
+
+#### 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).
+
+#### 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.

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

@@ -0,0 +1,35 @@
+# Kiến Trúc Mô-đun & Cơ Chế Tiêm Phụ Thuộc (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.
+
+---
+
+## 💉 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.
+
+  * **Không hợp lệ (❌ Cấm viết):**
+    ```typescript
+    @Injectable()
+    export class AuthService {
+      @Inject(UsersService)
+      private readonly usersService: UsersService;
+    }
+    ```
+  * **Hợp lệ (✔️ Khuyến khích):**
+    ```typescript
+    @Injectable()
+    export class AuthService {
+      constructor(private readonly usersService: UsersService) {}
+    }
+    ```
+
+---
+
+## 🏗️ 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).

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

@@ -0,0 +1,41 @@
+# Quy Ước Đặt Tên & Coding Style cho NestJS
+
+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.
+
+---
+
+## 🏷️ Quy Ước Đặt Tên (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`.
+
+```bash
+# Thư mục module luôn dùng số nhiều hoặc số ít đồng nhất (Ví dụ: auth, users, products)
+src/users/
+├── users.module.ts
+├── users.controller.ts
+├── users.service.ts
+├── dto/
+│   ├── create-user-request.dto.ts
+│   └── update-user-response.dto.ts
+├── entities/
+│   └── user.entity.ts
+├── guards/
+│   └── roles.guard.ts
+└── interceptors/
+    └── 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 đó:
+- **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 {}`
+- **DTO:** `src/auth/dto/login.dto.ts` $\rightarrow$ `export class LoginRequestDto {}`
+
+---
+
+## 📦 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ý.

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

@@ -0,0 +1,46 @@
+# Xác Thực Dữ Liệu & Quản Lý Lỗi Tập Trung
+
+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.
+
+---
+
+## 🛡️ 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).
+
+  ```typescript
+  // Trong file 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)
+    }),
+  );
+  ```
+
+---
+
+## 🚨 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.).
+  
+  ```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.");
+  }
+  ```
+
+- **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:
+
+  ```json
+  {
+    "success": false,
+    "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."
+  }
+  ```

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

@@ -0,0 +1,25 @@
+---
+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
+---
+
+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ó.
+
+Đầ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
+
+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ộ:
+   - `{{runCommand}} lint`
+   - `{{runCommand}} typecheck`
+   - `{{runCommand}} test`
+   - `{{runCommand}} build`

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

@@ -0,0 +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}}`.
+
+---
+
+### 🏗️ 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`
+
+---
+
+### 🏛️ Quy Tắc Phát Triển Nghiêm Ngặt
+
+#### 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.

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

@@ -0,0 +1,36 @@
+# Gọi Dữ Liệu & Đột Biến Dữ Liệu (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.
+
+---
+
+## 🔌 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.
+
+---
+
+## 💾 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.
+  
+  * **Không hợp lệ (❌ Nghiêm cấm):**
+    ```typescript
+    // Fetch dữ liệu tĩnh vô thời hạn mà không có chiến lược revalidate rõ ràng
+    const res = await fetch('https://api.skillverse.vn/v1/courses');
+    ```
+  * **Hợp lệ (✔️ Khuyến khích):**
+    ```typescript
+    // Cấu hình ISR (Incremental Static Regeneration) rõ ràng với 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.
+
+---
+
+## ⚡ Độ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.

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.