agent-workflow-kit-cli 1.3.2 → 1.3.3

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,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}}`.
+## 🗺️ Express.js Development Guide (Node.js Backend)
+
+### 🔄 Agent Development Lifecycle
+The AI Agent must execute all Express.js tasks following this 5-step workflow:
+1. **Design & Implementation:** Organize code according to a clean 3-tier architecture. Spaghetti code is strictly prohibited.
+2. **Comprehensive Testing:** Write unit tests for Services using Jest, and test API integrations 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:
-- 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: `@SKILL.md`
 
 ---
 
-### 🏛️ 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.

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`

package/templates/golang/AGENTS.md.hbs

@@ -0,0 +1,36 @@
+## 🗺️ Golang Development Guide (Go Backend)
+
+### 🔄 Agent Development Lifecycle
+The AI Agent must execute all Golang tasks following this 4-step workflow:
+1. **Design & Implementation:** Implement business logic adhering to the Standard Go Project Layout. Keep entrypoints in `cmd/`, core business logic in `internal/`, and standalone shared libraries in `pkg/`.
+2. **Comprehensive Testing:** Write unit tests using the table-driven testing pattern and Go's built-in `testing` library. Run tests with: `go test ./...`.
+3. **Code Quality & Formatting:** Ensure code compiles and meets formatting/linting rules:
+   - Formatting: `gofmt -w .`
+   - Linting: `golangci-lint run`
+   - Build Validation: `go build ./...`
+4. **Dependency Management:** Add new external libraries using `go get [library_name]`. Never manually edit the `go.sum` file.
+
+---
+
+### 🏗️ Template Blueprint
+Refer to the detailed rules below:
+- Go coding style, interface design, and naming conventions: `@golang-style.md`
+- Directory organization and manual dependency injection: `@project-layout.md`
+- Explicit error handling, wrapping, and custom API errors: `@error-handling.md`
+- Concurrency, goroutine/channel lifecycle, and escape analysis: `@concurrency.md`
+
+---
+
+### 🏛️ Strict Development Rules
+
+#### 1. Package Boundaries & Encapsulation
+- **No Circular Dependencies:** Design packages around domains/components rather than tech layers (e.g., separate folders for `course`, `billing` instead of `controllers`, `models`) to avoid circular imports.
+- **Internal Directory:** Keep 100% of core application logic inside `/internal` to enforce encapsulation and leverage Go compiler protections.
+
+#### 2. Explicit Error Handling
+- **Check Every Error:** Never ignore returned errors. Write `if err != nil` checks immediately after calling fallible functions.
+- **Wrap Errors:** Use `fmt.Errorf("failed to...: %w", err)` when propagating errors to preserve runtime context.
+
+#### 3. Safe Concurrency
+- **Context Propagation:** Pass `ctx context.Context` as the first argument to all functions executing I/O.
+- **Prevent Race Conditions:** Protect shared memory access across goroutines using `sync.Mutex` or `sync/atomic`.

package/templates/golang/rules/concurrency.md

@@ -0,0 +1,71 @@
+# Golang Concurrency & Memory Allocation
+
+This document outlines standard guidelines for goroutines, context propagation, race conditions, and heap allocation optimizations.
+
+---
+
+## 🧠 Escape Analysis & Allocations
+The Go compiler determines if a variable should live on the Stack (fast, auto-allocated/deallocated) or Heap (garbage-collected).
+- **Pointer Rule (*):** Return pointers only for large structs where value copying is expensive, or when you must modify the receiver's state directly.
+- **Value Types for Small Structs:** For small configuration values or short-lived structs (under 64-128 bytes), return value types to keep allocations on the Stack.
+```go
+// ❌ Forces heap allocation (Bad)
+func NewConfig() *Config {
+    return &Config{Timeout: 30}
+}
+
+// ✔️ Keeps allocation on the Stack (Good)
+func NewConfig() Config {
+    return Config{Timeout: 30}
+}
+```
+- **sync.Pool Usage:** For high-frequency, repetitive operations like JSON encoding/decoding or byte buffer allocation (`[]byte`), use `sync.Pool` to reuse memory, minimizing GC pressure.
+```go
+var bufferPool = sync.Pool{
+    New: func() any {
+        return make([]byte, 1024)
+    },
+}
+```
+
+---
+
+## 🚦 Prevent Goroutine Leaks
+- **Rule:** When writing data to a channel inside an independent goroutine, ensure the channel has a buffer or is monitored with timeouts/contexts to prevent permanent blocking.
+```go
+// ❌ Leaks goroutine if no reader reads from ch (Bad)
+func FetchData() string {
+    ch := make(chan string) // Unbuffered channel
+    go func() {
+        ch <- doHeavyWork() // Blocks indefinitely if parent exits early
+    }()
+    return <-ch
+}
+
+// ✔️ Safe with Buffer and Context (Good)
+func FetchData(ctx context.Context) (string, error) {
+    ch := make(chan string, 1) // Buffered channel avoids blocking
+    go func() {
+        ch <- doHeavyWork()
+    }()
+    
+    select {
+    case res := <-ch:
+        return res, nil
+    case <-ctx.Done():
+        return "", ctx.Err() // Exits safely on timeout/cancel
+    }
+}
+```
+
+---
+
+## 🧭 Context Propagation
+- Pass `ctx context.Context` as the first argument to any functions handling network or filesystem operations.
+- Never store Context inside a struct; pass it explicitly down the call chain.
+
+---
+
+## ⚡ Prevent Race Conditions
+Protect shared variables accessed concurrently across multiple goroutines using `sync.Mutex`, `sync.RWMutex`, or `sync/atomic`.
+- Run race detection during testing: `go test -race ./...`.

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

@@ -0,0 +1,42 @@
+# Golang Error Handling Standards
+
+This document defines strict guidelines for error checking, error wrapping, and structuring standard API errors.
+
+---
+
+## 🔄 Error Wrapping
+- **Rule:** When passing errors up the stack (e.g., from Repository to UseCase), never return the raw error or create a new error that discards the trace.
+- **Solution:** Use `%w` in `fmt.Errorf` to wrap the underlying error with contextual information:
+```go
+if err != nil {
+    return fmt.Errorf("failed to fetch user from db (id: %d): %w", id, err)
+}
+```
+- **Checking Errors:** Use `errors.Is()` for comparing sentinel errors and `errors.As()` to extract custom error structures:
+```go
+if errors.Is(err, sql.ErrNoRows) {
+    // Handle record not found
+}
+```
+
+---
+
+## 🏛️ Standard Custom Errors
+To return uniform error responses to Frontend clients or API Gateways, define a standard struct:
+```go
+type AppError struct {
+    Code    string            `json:"code"`
+    Message string            `json:"message"`
+    Details map[string]string `json:"details,omitempty"`
+}
+
+func (e *AppError) Error() string {
+    return fmt.Sprintf("[%s] %s", e.Code, e.Message)
+}
+```
+
+---
+
+## 🚫 Avoid Panics
+- **Strict Rule:** Never use `panic` and `recover` for normal business flow control or expected failures.
+- **Exception:** Only use `panic` during application startup if a fatal dependency fails (e.g., cannot connect to the primary database, or port is already in use).

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

@@ -0,0 +1,24 @@
+# Golang Coding Style Rules
+
+This document defines naming conventions, interface designs, and code style rules for Golang projects.
+
+---
+
+## 🏷️ Naming Conventions
+- **Package Names:** Must be short, single-word, lowercase names (e.g., `user`, `config`, `db`, `auth`). Never use `camelCase`, `snake_case`, or hyphens.
+- **Private Symbols (Variables & Functions):** Use `camelCase` (e.g., `userID`, `fetchData`).
+- **Public Symbols (Exported):** Use `PascalCase` to export variables, functions, and structs (e.g., `UserID`, `FetchData`).
+- **Acronyms:** Keep acronyms consistent in casing (e.g., `userID` instead of `userId`, `httpServer` instead of `httpServer`).
+
+---
+
+## 🔌 Interface Design
+- **Rule:** *"Accept interfaces, return structs"*. This optimizes escape analysis and maintains clean API boundaries.
+- **Minimality:** Design interfaces to be small, ideally declaring only 1 or 2 methods (e.g., `io.Reader`, `io.Writer`).
+- **Naming:** End interface names with the `-er` suffix if they declare a single method (e.g., `Reader`, `Writer`, `Validator`).
+
+---
+
+## 🚫 Avoid Global Variables
+- **No Global Mutable State:** Do not instantiate global variables for connections, logs, or caches.
+- **Solution:** Pass dependencies explicitly through struct constructors (Dependency Injection) instead of accessing global instances.

package/templates/golang/rules/project-layout.md

@@ -0,0 +1,39 @@
+# Golang Project Architecture & Layout
+
+This document defines the Standard Go Project Layout and Clean Architecture conventions.
+
+---
+
+## 🏗️ Standard Directory Structure
+Adhere to the following layout guidelines:
+- **/cmd:** Contains only the entrypoints of the application (e.g., `cmd/api/main.go`). Code here must only parse configs, initialize the DI container, and start the server. Do not write business logic here.
+- **/internal:** Contains all core application code. The Go compiler enforces that external packages cannot import code from this directory. Write 100% of business logic here.
+- **/pkg:** Contains standalone utility libraries that can be shared with other projects (e.g., `pkg/logger`, `pkg/crypto`). Code in `/pkg` must never import packages from `/internal`.
+- **/api:** Contains API contract definitions (OpenAPI/Swagger schemas, gRPC proto files).
+
+---
+
+## 🏛️ Clean Architecture Layers
+Organize code inside `/internal/app` or `/internal/<domain>` into 3 distinct layers:
+1. **Entities (Domain Models):** Pure Go structs and core business rules. They must be free of external dependencies.
+2. **Use Cases (Services):** Coordinates business logic. Interacts only with interfaces representing external components.
+3. **Adapters (Controllers / Repositories):** Manages external communications (e.g., database operations using GORM, API routes using Fiber/Echo, gRPC handlers).
+
+---
+
+## 💉 Manual Dependency Injection (DI)
+- **Constructor Injection:** Pass dependencies to structs (UseCases or Repositories) via `New[StructName]` constructors. Dependencies must be passed as interfaces.
+- **Example:**
+```go
+type UserRepository interface {
+    GetByID(ctx context.Context, id int64) (*domain.User, error)
+}
+
+type UserUseCase struct {
+    repo UserRepository // Access via interface
+}
+
+func NewUserUseCase(r UserRepository) *UserUseCase {
+    return &UserUseCase{repo: r}
+}
+```