agent-workflow-kit-cli 1.3.2 → 1.3.4

package/templates/dotnet/rules/csharp-style.md

@@ -1,27 +1,27 @@
-# Quy Ước Viết Mã C# (C# Coding Style & Conventions)
+# C# Coding Style & Conventions
 
-Tài liệu này đặc tả quy chuẩn coding style, đặt tên biến, tên lớp và cách tổ chức file mã nguồn trong dự án .NET.
+This document specifies standard coding styles, naming patterns, and source file organization conventions in .NET projects.
 
 ---
 
-## 🏷️ Quy Ước Đặt Tên (Naming Conventions)
+## 🏷️ Naming Conventions
 
-### Quy tắc đặt tên Lớp và Thành phần
-- **PascalCase:** Áp dụng cho Class, Struct, Record, Enum, Interface, Method, và Public Properties.
-  - *Ví dụ:* `UserService`, `GetActiveUsers()`, `CreatedDate`.
-- **Interface Prefix:** Tên Interface bắt buộc phải bắt đầu bằng chữ cái `I`.
-  - *Ví dụ:* `IUserService`, `IUserRepository`.
-- **camelCase:** Áp dụng cho tham số đầu vào của hàm (method arguments) và các biến cục bộ (local variables).
-  - *Ví dụ:* `userId`, `requestPayload`.
-- **Private Fields Prefix:** Các trường dữ liệu private trong Class phải viết bằng camelCase và bắt đầu bằng dấu gạch dưới `_`.
-  - *Ví dụ:* `private readonly IUserRepository _userRepository;`.
+### Class & Component Naming Rules
+- **PascalCase:** Use for Classes, Structs, Records, Enums, Interfaces, Methods, and Public Properties.
+  - *Examples:* `UserService`, `GetActiveUsers()`, `CreatedDate`.
+- **Interface Prefix:** Interface names must start with the uppercase letter `I`.
+  - *Examples:* `IUserService`, `IUserRepository`.
+- **camelCase:** Use for method arguments and local variables.
+  - *Examples:* `userId`, `requestPayload`.
+- **Private Fields Prefix:** Private fields inside classes must use `camelCase` and start with an underscore `_`.
+  - *Example:* `private readonly IUserRepository _userRepository;`.
 
 ---
 
-## 📦 Tổ Chức Mã Nguồn & Định Dạng
-- **Namespaces:** Đặt namespace phản ánh cấu trúc thư mục của dự án để đảm bảo tính dễ tìm kiếm.
-  - *Ví dụ:* `ProjectName.Application.Services`.
-- **File Scoped Namespaces:** Sử dụng cú pháp namespace phạm vi file (File-scoped namespace) của C# 10+ để giảm cấp thụt lề thụt dòng không cần thiết:
+## 📦 File Structure & Formatting
+- **Namespaces:** Match namespaces with the physical directory structure to ensure easy discovery.
+  - *Example:* `ProjectName.Application.Services`.
+- **File-Scoped Namespaces:** Use C# 10+ file-scoped namespaces to reduce unnecessary indentation levels:
   ```csharp
   namespace ProjectName.Application.Services;
 
@@ -30,4 +30,4 @@ Tài liệu này đặc tả quy chuẩn coding style, đặt tên biến, tên
       // ...
   }
   ```
-- **Sắp xếp Usings:** Đặt các chỉ thị `using` hệ thống (`System.*`) lên trước, tiếp theo là các thư viện bên thứ ba, và cuối cùng là các dự án nội bộ.
+- **Sorting Usings:** Organize `using` directives by placing system namespaces (`System.*`) first, followed by third-party packages, and internal project dependencies last.

package/templates/dotnet/rules/dependency-injection.md

@@ -1,14 +1,14 @@
-# Đăng Ký & Sử Dụng Dependency Injection (DI)
+# Dependency Injection (DI) Configurations
 
-Tài liệu này hướng dẫn cách cấu hình và tiêm phụ thuộc trong các ứng dụng .NET Core.
+This document details guidelines for configuring and consuming dependency injection in .NET Core applications.
 
 ---
 
-## 💉 Constructor Injection (Tiêm qua Hàm khởi tạo)
-- **Quy tắc bắt buộc:** Luôn luôn giải quyết các phụ thuộc của Class thông qua Constructor. Gán chúng vào các trường private readonly có tiền tố gạch dưới `_`.
-- Tuyệt đối không dùng Service Locator (không gọi `app.Services.GetService<T>()` hay tiêm `IServiceProvider` để lấy service động tại runtime).
+## 💉 Constructor Injection
+- **Mandatory Rule:** Always resolve class dependencies using constructor parameters. Assign them to private readonly fields prefixed with an underscore `_`.
+- Never use the Service Locator pattern (do not call `app.Services.GetService<T>()` or inject `IServiceProvider` to dynamically resolve services at runtime).
 
-  * **Không hợp lệ (❌ Nghiêm cấm):**
+  * **Invalid (❌ Prohibited):**
     ```csharp
     public class OrderService
     {
@@ -26,7 +26,7 @@ Tài liệu này hướng dẫn cách cấu hình và tiêm phụ thuộc trong
         }
     }
     ```
-  * **Hợp lệ (✔️ Khuyến khích):**
+  * **Valid (✔️ Recommended):**
     ```csharp
     public class OrderService : IOrderService
     {
@@ -47,8 +47,8 @@ Tài liệu này hướng dẫn cách cấu hình và tiêm phụ thuộc trong
 
 ---
 
-## ⚙️ Đăng Ký Vòng Đời Dịch Vụ (Service Lifetimes)
-Lựa chọn đúng vòng đời khi đăng ký dịch vụ trong `Program.cs`:
-1. **Transient (`AddTransient<I, T>()`):** Tạo mới mỗi khi được yêu cầu. Dành cho các dịch vụ nhẹ, không lưu trạng thái (Stateless Services).
-2. **Scoped (`AddScoped<I, T>()`):** Tạo mới một lần cho mỗi HTTP Request. Thích hợp cho Repository, Database Context (`DbContext`), và các dịch vụ nghiệp vụ.
-3. **Singleton (`AddSingleton<I, T>()`):** Tạo một lần duy nhất cho toàn bộ vòng đời ứng dụng. Dành cho caching in-memory, cấu hình hệ thống, helper dùng chung.
+## ⚙️ Service Lifetimes Registration
+Register dependencies with the appropriate lifetime scopes inside `Program.cs`:
+1. **Transient (`AddTransient<I, T>()`):** Instantiated every time they are requested. Use for lightweight, stateless services.
+2. **Scoped (`AddScoped<I, T>()`):** Instantiated once per HTTP request context. Recommended for repositories, database contexts (`DbContext`), and business services.
+3. **Singleton (`AddSingleton<I, T>()`):** Instantiated once and shared across the entire application lifetime. Use for in-memory caching, system configurations, and thread-safe helper services.

package/templates/dotnet/rules/error-handling-validation.md

@@ -1,15 +1,15 @@
-# Xử Lý Ngoại Lệ Tập Trung & Xác Thực Tự Động (FluentValidation)
+# Unified Exception Handling & Automated Validation (FluentValidation)
 
-Tài liệu này quy định cấu hình xử lý ngoại lệ tập trung qua Middleware và xác thực dữ liệu đầu vào bằng thư viện FluentValidation trong ứng dụng .NET.
+This document defines configurations for centralized exception handling using Middleware and incoming request validation using the FluentValidation library in .NET applications.
 
 ---
 
-## 🛡️ Xác Thực Dữ Liệu Tự Động Với FluentValidation
-- **Quy tắc:** Mọi API Request nhận dữ liệu phức tạp phải đi kèm một Validator kế thừa từ `AbstractValidator<T>` để định nghĩa các ràng buộc dữ liệu.
-- Cấu hình FluentValidation để tự động kiểm duyệt và trả về lỗi 400 Bad Request cho Client nếu dữ liệu không khớp, tránh viết các câu lệnh `if` lặp lại.
+## 🛡️ Automated Validation with FluentValidation
+- **Rule:** Every API request representing complex input data payloads must have a corresponding validator class inheriting from `AbstractValidator<T>` to declare validation rules.
+- Configure FluentValidation to automatically intercept invalid requests and return an HTTP `400 Bad Request` payload to the client, preventing repetitive manual validation checks inside Controllers.
 
   ```csharp
-  // Ví dụ về một Validator
+  // Example of a Validator class
   using FluentValidation;
 
   public class CreateCourseRequestValidator : AbstractValidator<CreateCourseRequestDto>
@@ -17,32 +17,32 @@ Tài liệu này quy định cấu hình xử lý ngoại lệ tập trung qua M
       public CreateCourseRequestValidator()
       {
           RuleFor(x => x.Title)
-              .NotEmpty().WithMessage("Tiêu đề khóa học không được để trống.")
-              .MaximumLength(150).WithMessage("Tiêu đề không được vượt quá 150 ký tự.");
+              .NotEmpty().WithMessage("Course title cannot be empty.")
+              .MaximumLength(150).WithMessage("Title must not exceed 150 characters.");
 
           RuleFor(x => x.Price)
-              .GreaterThanOrEqualTo(0).WithMessage("Giá khóa học không được nhỏ hơn 0.");
+              .GreaterThanOrEqualTo(0).WithMessage("Course price cannot be less than 0.");
       }
   }
   ```
 
 ---
 
-## 🚨 Xử Lý Lỗi Tập Trung (Global Exception Middleware)
-- **Quy tắc:** Tuyệt đối không để lộ các ngoại lệ thô của hệ thống (lỗi DB, stack traces) cho Client với mã lỗi 500.
-- Xây dựng một Middleware toàn cục (`ExceptionHandlingMiddleware`) hoặc sử dụng tính năng `IExceptionHandler` trong .NET 8+ để bắt toàn bộ các lỗi xảy ra trong ứng dụng và định dạng lại thành cấu trúc JSON chuẩn:
+## 🚨 Centralized Exception Handling (Global Exception Middleware)
+- **Rule:** Never expose raw system exceptions (such as database faults, file system errors, or stack traces) directly to clients as HTTP 500 errors.
+- Build a global middleware (`ExceptionHandlingMiddleware`) or implement `IExceptionHandler` in .NET 8+ to intercept all unhandled exceptions and format them into a standard JSON payload:
 
   ```json
   {
     "success": false,
     "statusCode": 500,
     "timestamp": "2026-06-13T07:42:00.000Z",
-    "message": "Đã xảy ra lỗi hệ thống. Vui lòng liên hệ quản trị viên."
+    "message": "An internal server error occurred. Please contact the administrator."
   }
   ```
 
   ```csharp
-  // Cấu trúc Exception Handling Middleware tiêu chuẩn
+  // Standard Global Exception Handling Middleware
   public class ExceptionHandlingMiddleware
   {
       private readonly RequestDelegate _next;
@@ -77,7 +77,7 @@ Tài liệu này quy định cấu hình xử lý ngoại lệ tập trung qua M
               success = false,
               statusCode = context.Response.StatusCode,
               timestamp = DateTime.UtcNow,
-              message = "Đã xảy ra lỗi hệ thống. Vui lòng liên hệ quản trị viên."
+              message = "An internal server error occurred. Please contact the administrator."
           };
 
           return context.Response.WriteAsJsonAsync(response);

package/templates/dotnet/skills/dotnet-controller/SKILL.md

@@ -1,24 +1,24 @@
 ---
 name: dotnet-controller
-description: Sinh hoặc mở rộng một API Controller ASP.NET Core mới cùng DTOs, FluentValidation và Service interface tương ứng
+description: Scaffold or extend an ASP.NET Core API Controller with corresponding DTOs, FluentValidation, and Service interfaces
 ---
 
-Tuân thủ quy trình này để tạo mới một API Endpoint hoặc Controller trong .NET (C#).
+Follow this process to generate a new API Endpoint or Controller in .NET (C#).
 
-Đầu vào (Inputs):
-- controllerName: Tên của Controller (ví dụ: `CoursesController`)
-- routePath: Tuyến định tuyến HTTP (ví dụ: `api/v1/courses`)
-- requestDtoName: Tên lớp Request DTO (ví dụ: `CreateCourseRequestDto`)
-- functionality: Tóm tắt yêu cầu nghiệp vụ và các phương thức cần xử lý
+Inputs:
+- controllerName: Name of the Controller (e.g., `CoursesController`)
+- routePath: HTTP route mapping (e.g., `api/v1/courses`)
+- requestDtoName: Class name of the request DTO (e.g., `CreateCourseRequestDto`)
+- functionality: Summary of the business requirements and methods to process
 
-Các bước thực hiện (Steps):
-1. Khai báo các lớp Request/Response DTOs tương ứng bên trong tầng Application (hoặc thư mục `DTOs` của dự án).
-2. Xây dựng một lớp Validator kế thừa từ `AbstractValidator<T>` bằng FluentValidation bên dưới Application layer để kiểm tra ràng buộc dữ liệu.
-3. Định nghĩa Service Interface (ví dụ: `ICourseService`) và lớp triển khai cụ thể (`CourseService`) ở tầng Application/Core để xử lý business logic.
-4. Đăng ký Service nghiệp vụ vừa tạo vào Dependency Injection container (Scoped lifetime) trong file `Program.cs`.
-5. Tạo lớp Controller kế thừa từ `ControllerBase` được đánh dấu bằng các attribute `[ApiController]` và `[Route]`.
-6. Sử dụng Constructor Injection để tiêm Service Interface vào Controller và gọi phương thức xử lý thích hợp, ánh xạ kết quả trả về thông qua các `IActionResult` (như `Ok()`, `Created()`, `BadRequest()`).
-7. Viết unit test cho Service và Controller bằng xUnit và Moq.
-8. Chạy kiểm tra lỗi biên dịch cục bộ:
+Steps:
+1. Declare the corresponding Request/Response DTO classes inside the Application layer (or the project's `DTOs` directory).
+2. Create a Validator class inheriting from FluentValidation's `AbstractValidator<T>` in the Application layer to define data constraints.
+3. Define the Service Interface (e.g., `ICourseService`) and its concrete implementation class (`CourseService`) in the Application layer to handle business logic.
+4. Register the new Service in the Dependency Injection container (using Scoped lifetime) inside the `Program.cs` configuration file.
+5. Create the Controller class inheriting from `ControllerBase`, decorated with `[ApiController]` and `[Route]` attributes.
+6. Use Constructor Injection to inject the Service Interface into the Controller, delegate request processing, and map responses to appropriate `IActionResult` objects (e.g., `Ok()`, `Created()`, `BadRequest()`).
+7. Write unit tests for the Service and Controller using xUnit and Moq.
+8. Execute compilation and testing:
    - `dotnet build`
    - `dotnet test`

package/templates/express/AGENTS.md.hbs

@@ -1,41 +1,45 @@
-## 🗺️ 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}}`.
+## 🗺️ Express.js Development Guide (Node.js Backend)
+
+### 🔄 Agent Development Lifecycle
+The AI Agent must execute all Express.js tasks following this structured 5-stage lifecycle:
+1. **Design & Code:** Organize code according to a clean 3-tier architecture as detailed in `@router-controller.md`. Spaghetti code is strictly prohibited.
+2. **Comprehensive Testing:** Write unit tests for Services using Jest, and test API integrations using Supertest.
+3. **Troubleshooting & Debugging:** When debugging async router handlers or validation payloads, verify error forwarding is properly configured.
+4. **Code Quality & Review:** Perform self-review using `@error-handling.md` to ensure errors are captured globally and validation uses Zod schemas. Check style rules in `@express-style.md`.
+5. **Production Readiness:** Verify compilation and static analysis checks pass without errors.
 
 ---
 
-### 🏗️ 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`
+### 🏗️ Template Blueprint
+Refer to the detailed rules below:
+- Clean coding style and type safety using TypeScript in Express: `@express-style.md`
+- Separation of concerns: Router mappings $\rightarrow$ Controller delegation $\rightarrow$ Service execution: `@router-controller.md`
+- Async error catching strategies and centralized global error handling middleware: `@error-handling.md`
+- Process to scaffold new API endpoints cleanly from Routers to Validators: `@express-endpoint`
 
 ---
 
-### 🏛️ Quy Tắc Phát Triển Nghiêm Ngặt
+### 🏛️ Strict Development Rules
 
-#### 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:
+#### 1. Strict Layer Separation
+Strictly comply with the data flow chain:
 $$\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.
+- **Router:** Must not contain processing logic. Only maps HTTP methods + paths and registers auth/validation middlewares.
+- **Controller:** Only extracts inputs from the request object (`req.body`, `req.query`, `req.params`), invokes the target Service, and returns the response using `res.status().json()`. Never execute database queries directly here.
+- **Service:** Houses business logic, calculations, and database model interactions. Must not reference or depend on Express `req` or `res` objects to ensure testability.
+
+#### 2. Async Error Handling
+- **No Manual Try/Catch in Controllers:** Avoid wrapping every controller method in manual try/catch blocks.
+- **Use Async Handlers:** Wrap all async controller functions with an automatic error-catching wrapper (such as `express-async-handler`) to forward exceptions to the `next()` function automatically.
+- **Centralized Global Error Middleware:** Declare a 4-parameter error-handling middleware at the end of the server bootstrap chain (after all route registrations) to format error payloads.
+
+#### 3. Request Validation with Zod Middleware
+- **No Manual Conditional Validation:** Do not write scattered `if` blocks to check input parameters.
+- **Zod Schema Middleware:** Implement a shared validation middleware that accepts a Zod schema to validate request segments (`body`, `query`, `params`) before they reach the Controller.
+
+### 🧪 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/express/rules/error-handling.md

@@ -1,36 +1,36 @@
-# Bẫy Lỗi Bất Đồng Bộ & Xác Thực Dữ Liệu Tự Động (Zod Middleware)
+# Async Error Handling & Automated Validation (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.
+This document defines standard practices for asynchronous error catching, centralized global error handling middleware, and automated schema validations using 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()`.
+## 🚨 Async Error Handling Architecture
+- **No Manual Try/Catch in Controllers:** Wrapping every controller method in manual try/catch blocks is prohibited.
+- **Use Async Handlers:** Wrap all async controller functions with an automatic error-catching wrapper (such as `asyncHandler`) to automatically forward exceptions to Express's `next()` function.
 
   ```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) => {
+  // Automated async error catcher wrapper
+  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
+  // Controller usage example
   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
+    const profile = await userService.getProfile(userId); // Errors thrown inside the service are automatically caught
     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.
+## 🔌 Centralized Global Error Handler Middleware
+- **Register Error Middleware:** You must register a 4-parameter error-handling middleware at the end of the server bootstrap chain (after all route registrations) to parse and return clean error responses.
 
   ```typescript
-  // Trong file app.ts hoặc server.ts
+  // Inside app.ts or server.ts
   app.use((err: any, req: Request, res: Response, next: NextFunction) => {
     const statusCode = err.statusCode || 500;
     const message = err.message || 'Internal Server Error';
@@ -46,9 +46,9 @@ Tài liệu này quy định chiến lược xử lý lỗi bất đồng bộ (
 
 ---
 
-## 🛡️ 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.
+## 🛡️ Automated Validation with Zod Middleware
+- **No Manual Conditional Checks:** Do not write scattered `if (!req.body.email)` conditionals inside controllers.
+- **Zod Schema Middleware:** Implement a shared validation middleware that accepts a Zod schema to validate request segments (`body`, `query`, `params`) before they reach the Controller.
 
   ```typescript
   import { AnyZodObject, ZodError } from 'zod';
@@ -57,14 +57,14 @@ Tài liệu này quy định chiến lược xử lý lỗi bất đồng bộ (
   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
+        // Validate incoming request segments concurrently
         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
+        // Re-assign parsed and sanitized payloads
         req.body = parsed.body;
         req.query = parsed.query;
         req.params = parsed.params;
@@ -74,7 +74,7 @@ Tài liệu này quy định chiến lược xử lý lỗi bất đồng bộ (
         if (error instanceof ZodError) {
           return res.status(400).json({
             success: false,
-            message: 'Dữ liệu đầu vào không hợp lệ',
+            message: 'Invalid input payload parameters',
             errors: error.errors.map((err) => ({
               field: err.path.join('.'),
               message: err.message,

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

@@ -1,28 +1,28 @@
-# Quy Ước Đặt Tên & Coding Style cho Express.js
+# Express.js Naming Conventions & Coding Style
 
-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.
+This document defines coding conventions, directory layout, and TypeScript configurations for Express.js applications.
 
 ---
 
-## 🏷️ Quy Ước Đặt Tên (Naming Conventions)
+## 🏷️ 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):
+### Directory Layout (3-Tier Architecture)
+The codebase must be structured cleanly according to a 3-tier architecture layout:
 ```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
+├── config/             # Environment configurations, DB initializations
+├── middlewares/        # Express middleware functions (Auth, Log, Validation)
+├── models/             # Database Schemas (Mongoose, Sequelize, or Prisma client)
+├── routes/             # HTTP Route definitions and input middleware binding
+├── controllers/        # Request parameter extraction, response formatting
+├── services/           # Houses 100% of business logic and computations
+├── utils/              # Standalone utility helper functions
+└── app.ts              # Express App setup and server bootstrapping
 ```
 
-### 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ố:
+### Filename Notation
+- **Consistency:** Use `kebab-case.ts` across all filenames in the repository.
+- **Suffix Declarations:** Filenames must end with a suffix representing their architectural role:
   - Controller: `user-controller.ts`
   - Service: `user-service.ts`
   - Route: `user-route.ts`
@@ -31,9 +31,9 @@ src/
 
 ---
 
-## 📦 Đị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 & Type Declarations
+- **Explicit Type Declarations:** Avoid implicit type inference. Always define types for `req`, `res`, and `next` parameters imported from `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.
+- **Strictly Ban the `any` Keyword:** Declare interfaces or types for all request bodies and API response structures.

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

@@ -1,27 +1,27 @@
-# Phân Tách Lớp Trách Nhiệm (Router vs Controller vs Service)
+# Architectural Boundaries (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.
+This document establishes boundaries and responsibilities for routers, controllers, and services in Express.js projects.
 
 ---
 
-## 🏛️ 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:
+## 🏛️ Data Flow Chain
+All features in the repository must comply with the standard 3-tier architecture data flow:
 $$\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
+## 🚦 Layer Responsibilities
 
-### 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.
+### 1. Router Layer (`routes/`)
+- **Role:** Exclusively responsible for mapping HTTP methods + paths and binding authentication or payload validation middlewares (e.g., Zod schemas).
+- **Rule:** Under no circumstances should the Router layer house business calculations or database operations. It must only forward requests to the target Controller.
 
-### 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).
+### 2. Controller Layer (`controllers/`)
+- **Role:** Responsible for extracting input payloads from the Express `req` object (`req.body`, `req.query`, `req.params`, `req.user`), forwarding these arguments to the Service layer, receiving outcomes, and responding to the client via `res.status().json()`.
+- **Rules:**
+  - Never query database models or call ORM clients inside the Controller.
+  - Never write manual try/catch blocks (delegate errors to the global error handler using async wrappers).
 
-### 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.
+### 3. Service Layer (`services/`)
+- **Role:** Houses 100% of the core business logic, coordinates data mutations, executes algorithms, and interacts with Database models.
+- **Rule:** Never import, reference, or access Express-specific objects (`req`, `res`, or `next`) inside Services. The Service layer must remain completely decoupled from the web framework to maintain isolated testability.

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

@@ -1,23 +1,23 @@
 ---
 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
+description: Scaffold or extend a secure Express.js + TypeScript API endpoint including Router, Controller, and 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ó.
+Follow this process to generate a new Express.js API Endpoint or extend an existing route.
 
-Đầ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
+Inputs:
+- endpointName: Name of the API Endpoint to create (e.g., `user-profile`)
+- routePath: HTTP route path of the API (e.g., `/api/v1/users/profile`)
+- httpMethod: HTTP method (GET, POST, PUT, DELETE)
+- targetPath: The destination path to place the code files
 
-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ộ:
+Steps:
+1. Define a Zod Validation Schema under the `middlewares/` directory or alongside the controller to validate input payloads.
+2. Implement the corresponding Service function under the `services/` directory to handle 100% of the business logic and ORM queries.
+3. Implement the Controller dispatcher in the `controllers/` directory using the `asyncHandler` wrapper to forward errors automatically, extract inputs, and send JSON responses.
+4. Register the Controller and mount the `validateSchema(zodSchema)` middleware on the target Route file under the `routes/` directory.
+5. Create unit test suites for the Service and integration test suites (E2E) using Supertest.
+6. Execute local validation:
    - `{{runCommand}} lint`
    - `{{runCommand}} typecheck`
    - `{{runCommand}} test`