agent-workflow-kit-cli 1.3.2 → 1.3.3

package/dist/cli/commands/add.js

@@ -11,7 +11,7 @@ import { analyzeModule } from "../../core/analyzer.js";
 import { updateGitignore } from "./init.js";
 export async function runAdd(stack, options) {
     const targetStack = stack.toLowerCase();
-    const validStacks = ["spring-boot", "react-ts", "next-js", "nestjs", "express", "fastapi", "python-ai", "dotnet"];
+    const validStacks = ["spring-boot", "react-ts", "next-js", "nestjs", "express", "fastapi", "python-ai", "dotnet", "golang", "rust"];
     if (!validStacks.includes(targetStack)) {
         console.error(chalk.red(`Error: Invalid stack '${stack}'. Supported stacks are: ${validStacks.join(", ")}`));
         process.exit(1);
@@ -40,7 +40,9 @@ export async function runAdd(stack, options) {
     // 3. Write or Update AGENTS.md and/or GEMINI.md in the target directory
     const geminiPath = path.join(targetDir, "GEMINI.md");
     const agentsPath = path.join(targetDir, "AGENTS.md");
+    const globalRules = await readStaticTemplateFile("common/GLOBAL_RULES.md").catch(() => "");
     const moduleAgentsContent = await renderTemplate("common/AGENTS.md.hbs", {
+        globalRules,
         stackContent,
     });
     if (options.agent === "antigravity" || options.agent === "both") {

package/dist/cli/commands/init.js

@@ -183,7 +183,9 @@ export async function runInit(options) {
     }
     if (modules.length === 0) {
         console.log(chalk.yellow("No standard stacks detected automatically. Creating general agent guidelines at root."));
+        const globalRules = await readStaticTemplateFile("common/GLOBAL_RULES.md").catch(() => "");
         const finalAgentsContent = await renderTemplate("common/AGENTS.md.hbs", {
+            globalRules,
             stackContent: "",
         });
         if (options.agent === "antigravity" || options.agent === "both") {
@@ -219,7 +221,9 @@ export async function runInit(options) {
             const targetFileName = isAntigravity ? "GEMINI.md" : "AGENTS.md";
             monorepoContent += `- **${mod.name}** (${mod.stacks.join(", ")}): Stack rules and guidelines are located at [${mod.name}/${targetFileName}](file:///${mod.dir.replace(/\\/g, "/")}/${targetFileName})\n`;
         }
+        const globalRules = await readStaticTemplateFile("common/GLOBAL_RULES.md").catch(() => "");
         const rootAgentsContent = await renderTemplate("common/AGENTS.md.hbs", {
+            globalRules,
             stackContent: monorepoContent.trim(),
         });
         const rootGeminiPath = path.join(cwd, "GEMINI.md");
@@ -276,7 +280,9 @@ export async function runInit(options) {
         // Render agent files for this module
         const geminiPath = path.join(mod.dir, "GEMINI.md");
         const agentsPath = path.join(mod.dir, "AGENTS.md");
+        const globalRules = await readStaticTemplateFile("common/GLOBAL_RULES.md").catch(() => "");
         const moduleAgentsContent = await renderTemplate("common/AGENTS.md.hbs", {
+            globalRules,
             stackContent,
         });
         if (options.agent === "antigravity" || options.agent === "both") {

package/dist/core/analyzer.js

@@ -519,6 +519,12 @@ export async function analyzeModule(dir, stacks) {
         else if (stack === "dotnet") {
             context["dotnet"] = await analyzeDotnet(dir);
         }
+        else if (stack === "golang") {
+            context["golang"] = await analyzeGolang(dir);
+        }
+        else if (stack === "rust") {
+            context["rust"] = await analyzeRust(dir);
+        }
     }
     return context;
 }
@@ -605,3 +611,67 @@ async function findCsprojFiles(dir) {
     await traverse(dir);
     return files;
 }
+async function analyzeGolang(dir) {
+    let goVersion = "1.22";
+    let moduleName = path.basename(dir);
+    try {
+        const goModPath = path.join(dir, "go.mod");
+        const content = await fs.readFile(goModPath, "utf8");
+        const lines = content.split("\n");
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith("module ")) {
+                moduleName = trimmed.replace("module ", "").trim();
+            }
+            else if (trimmed.startsWith("go ")) {
+                goVersion = trimmed.replace("go ", "").trim();
+            }
+        }
+    }
+    catch {
+        // Keep default
+    }
+    return { goVersion, moduleName };
+}
+async function analyzeRust(dir) {
+    let projectName = path.basename(dir);
+    let rustEdition = "2021";
+    let isWorkspace = false;
+    try {
+        const cargoTomlPath = path.join(dir, "Cargo.toml");
+        const content = await fs.readFile(cargoTomlPath, "utf8");
+        if (content.includes("[workspace]")) {
+            isWorkspace = true;
+        }
+        // Very basic parsing for name and edition
+        const lines = content.split("\n");
+        let inPackageSection = false;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith("[package]")) {
+                inPackageSection = true;
+            }
+            else if (trimmed.startsWith("[")) {
+                inPackageSection = false;
+            }
+            if (inPackageSection) {
+                if (trimmed.startsWith("name")) {
+                    const match = trimmed.match(/name\s*=\s*"(.*)"/);
+                    if (match && match[1]) {
+                        projectName = match[1];
+                    }
+                }
+                else if (trimmed.startsWith("edition")) {
+                    const match = trimmed.match(/edition\s*=\s*"(.*)"/);
+                    if (match && match[1]) {
+                        rustEdition = match[1];
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // Keep default
+    }
+    return { projectName, rustEdition, isWorkspace };
+}

package/dist/core/detector.js

@@ -130,6 +130,28 @@ async function detectProjectStackDirect(cwd) {
     catch {
         // Ignore
     }
+    // 5. Detect Golang (go.mod)
+    try {
+        const goModPath = path.join(cwd, "go.mod");
+        const stat = await fs.stat(goModPath);
+        if (stat.isFile()) {
+            stacks.push("golang");
+        }
+    }
+    catch {
+        // Ignore
+    }
+    // 6. Detect Rust (Cargo.toml)
+    try {
+        const cargoTomlPath = path.join(cwd, "Cargo.toml");
+        const stat = await fs.stat(cargoTomlPath);
+        if (stat.isFile()) {
+            stacks.push("rust");
+        }
+    }
+    catch {
+        // Ignore
+    }
     return stacks;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-workflow-kit-cli",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "AI-Ready Repository Workflow Generator & Guideline Optimizer for Codex and Antigravity",
   "type": "module",
   "main": "./dist/index.js",

package/templates/common/AGENTS.md.hbs

@@ -1,3 +1,7 @@
+{{{globalRules}}}
+
+---
+
 # Repository Agent Guidelines
 
 This repository implements the `agent-workflow-kit-cli` standards.

package/templates/common/GLOBAL_RULES.md

@@ -0,0 +1,101 @@
+# UNIVERSAL GLOBAL RULES (GLOBAL_RULES.md)
+
+NOTICE TO AI AGENT: All source code generated in this project – regardless of language, framework, or architecture (Frontend, Backend, AI Agent) – must strictly adhere to the following 4 pillars of engineering rules. Any violations will result in code rejection.
+
+---
+
+## 🏛️ PILLAR 1: DATABASE & MIGRATION GOVERNANCE
+The main goal is to protect data integrity, prevent data loss in Production environments, and optimize core query performance.
+
+### 1.1 Strict No Auto-Sync in Production
+- **Rule:** Never use properties or commands that automatically synchronize schema changes directly to the database in a Production environment (e.g., `synchronize: true` in TypeORM/Hibernate, `prisma db push`, `sequelize.sync()`, or GORM's `db.AutoMigrate()` running automatically at startup).
+- **Mandatory Solution:** All structural changes (adding columns, modifying types, dropping tables, creating indices) must be written in independent, timestamped migration files (e.g., `YYYYMMDDHHMMSS_migration_name`).
+- **Workflow:** Migration files must be verified locally and executed only via the ORM/Driver CLI tool prior to production deployment.
+
+### 1.2 Strict Indexing Strategy
+- **Prerequisite:** Any column frequently appearing in `WHERE` clauses, `JOIN` conditions, or `ORDER BY` statements in large-scale growing tables (e.g., `user_id`, `status`, `created_at`) must be indexed.
+- **Write Prevention:** Avoid indexing columns indiscriminately. For columns with high-frequency updates (`INSERT`/`UPDATE`/`DELETE`), redundant indices will severely degrade write performance.
+- **Unique Constraints:** Identity fields requiring uniqueness (e.g., `email`, `username`, `phone_number`) must be configured with a `UNIQUE` index at the Database level, not just validated in the Application code.
+
+### 1.3 Eliminate N+1 Query Issues
+- **Issue:** Never query child relations inside loops (`for`, `while`, `forEach`) for a list of records (e.g., fetching 100 courses and looping 100 times to execute SQL to get the instructor for each course).
+- **Solution:** Use Eager Loading (direct SQL `JOIN`s, or pre-fetching methods like `.Include()` in EF Core, `Preload` in GORM, `select_related` / `prefetch_related` in Python) to retrieve all relational data in a single query.
+
+### 1.4 Connection Pool Management
+- All database connections must go through a Connection Pool. The AI Agent must not manually open/close connections per request.
+- You must configure explicit limits: `max_connections` (maximum connections), `idle_timeout` (unused connection release time), and `max_lifetime` to prevent database server resource exhaustion.
+
+---
+
+## 🛡️ PILLAR 2: SECURITY & AUTH HARDENING
+Ensure the system is immune to vulnerabilities listed in the OWASP Top 10.
+
+### 2.1 Zero Hardcoded Secrets
+- **Strict Prohibition:** Never write database connection strings, third-party API Keys (e.g., OpenAI, Stripe), JWT secrets, or system passwords directly into the codebase.
+- **Implementation:** All sensitive values must be loaded into the application via Environment Variables or System Env.
+- **Documentation:** Every project must include a `.env.example` file listing all required environment keys with empty values, guiding others on how to configure the project.
+
+### 2.2 JWT Lifecycle & Storage Standards (JSON Web Token)
+- **Access Token:** Configure a short lifespan (minimum 15 minutes, maximum 1 hour) to reduce the window of vulnerability if the token is compromised.
+- **Refresh Token:** Must have a longer expiration (7 days to 30 days) and must be stored in an `HttpOnly`, `Secure`, `SameSite=Strict` cookie on the client side. Storing Refresh Tokens in `localStorage` or `sessionStorage` is strictly prohibited to prevent account takeover via XSS.
+
+### 2.3 Input Validation & Injection Defense
+- **Mass Assignment Defense (Overposting):** Never map client request objects (e.g., `req.body`) directly to database update statements without filtering. Data must be validated and filtered using DTOs (Data Transfer Objects), Pydantic Schemas, or Struct validations.
+- **SQL Injection Defense:** All database queries must use Parameterized Queries (Prepared Statements). String concatenation to construct dynamic SQL/NoSQL queries is strictly prohibited.
+
+### 2.4 CORS & Rate Limiting
+- **CORS:** Using `Origin: '*'` is strictly prohibited in Production. A whitelist of permitted frontend domains must be explicitly defined.
+- **Rate Limiting:** Sensitive or resource-intensive endpoints (e.g., Login, Register, Forgot Password, Send OTP, LLM AI generation APIs) must be protected by rate-limiting middleware (e.g., maximum 5 requests/minute/IP) to defend against DoS and brute-force attacks.
+
+---
+
+## 🚦 PILLAR 3: OBSERVABILITY & STRUCTURED LOGS
+Transition the system from blind debugging to proactive monitoring using structured log data.
+
+### 3.1 Structured Logging Standards
+- Printing raw text directly to the console (e.g., `console.log()`, `fmt.Println()`, `print()`, or `println!()`) is prohibited in Production.
+- **Mandatory Format:** All logs written to stdout/stderr must use JSON format so that Log Aggregators (ELK Stack, Grafana Loki, Datadog) can automatically parse and index them.
+- **Required fields in every JSON log line:**
+```json
+{
+  "timestamp": "2026-06-13T16:00:00.000Z",
+  "level": "ERROR",
+  "trace_id": "c4b37d89-9821-47d3-b12a-7e61a4b9812f",
+  "context": "PaymentService",
+  "message": "Failed to connect to Stripe payment gateway",
+  "error_details": {
+    "code": "STRIPE_TIMEOUT",
+    "stack": "Error: Timeout after 5000ms at StripeClient.request..."
+  }
+}
+```
+
+### 3.2 Strict Log Levels
+The AI Agent must select the appropriate log level for every event:
+- **DEBUG:** Detailed execution flow tracing during development (must be automatically disabled or hidden in Production).
+- **INFO:** Normal but important system events (e.g., Server started on port 8080, cache cleanup completed).
+- **WARN:** Abnormal situations that do not fail the request (e.g., user entered incorrect password, third-party API responded slowly but succeeded).
+- **ERROR:** Severe errors that terminate request execution and require developer intervention (e.g., database connection loss, invoice file write failure, logic errors).
+
+### 3.3 Masking PII (Personally Identifiable Information)
+- Never print sensitive PII into public log systems.
+- Fields containing passwords, credit card numbers, national IDs/passports, and access/refresh tokens must be masked (e.g., converted to `*`) or omitted from the logged objects.
+
+---
+
+## 📦 PILLAR 4: CONTAINER & CI/CD GUARDRAILS
+Ensure applications can be deployed automatically onto Cloud environments (Kubernetes, AWS, Docker Swarm) efficiently and securely.
+
+### 4.1 Mandatory Multi-Stage Builds
+Every Dockerfile must consist of at least 2 stages:
+- **Stage 1 (Build Stage):** Use a base image containing all necessary tools (SDKs, Compilers, devDependencies) to compile the source code and install packages.
+- **Stage 2 (Production Runtime Stage):** Copy only compiled assets and production dependencies (e.g., `dist` folder, compiled binary, node production modules) from Stage 1. This final image must not contain raw source code or development utilities, minimizing bundle size.
+
+### 4.2 Principle of Least Privilege
+- **No Root User:** Never run container processes using the default `root` user. Running containers as root introduces severe security risks in case of container escape vulnerabilities.
+- **Solution:** Initialize a non-privileged user in the Dockerfile (e.g., `USER node` in Node.js, or `useradd -u 1001 appuser` in Go/Rust) and grant appropriate execution permissions to this user.
+
+### 4.3 Health Check API
+- All backend services must expose a dedicated health check endpoint (e.g., `GET /health` or `GET /ready`).
+- This endpoint must check downstream connectivity (e.g., Database, Redis) and return HTTP Status `503 Service Unavailable` if unhealthy.
+- Use the `HEALTHCHECK` directive in the Dockerfile so orchestrators like Kubernetes can detect failures and automatically restart unhealthy containers (Self-healing).

package/templates/dotnet/AGENTS.md.hbs

@@ -1,53 +1,53 @@
-## 🗺️ Hướng Dẫn Phát Triển .NET (C#)
+## 🗺️ .NET (C#) Development Guide
 
-Dự án này là một ứng dụng .NET (C#), được tổ chức và cấu hình như sau:
-- **Tên Solution:** `{{solutionName}}`
-- **Phiên bản .NET:** `net{{dotnetVersion}}`
-- **Các dự án thành phần:** 
+This project is a .NET (C#) application configured as follows:
+- **Solution Name:** `{{solutionName}}`
+- **.NET Version:** `net{{dotnetVersion}}`
+- **Application Projects:** 
   {{#each projectNames}}
   - `{{this}}`
   {{/each}}
-- **Các dự án kiểm thử (Test Projects):**
+- **Test Projects:**
   {{#each testProjects}}
   - `{{this}}`
   {{/each}}
 
 ---
 
-### 🔄 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ụ .NET 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 Clean Architecture / Onion Architecture. Đặt Core Logic trong Application/Domain layer độc lập.
-2. **Kiểm thử Toàn diện:** Viết unit test cho các Service sử dụng xUnit và Moq.
-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:
-   - Chạy Build kiểm tra: `dotnet build`
-   - Chạy Kiểm thử: `dotnet test`
-4. **Quản lý Thư viện:** Thêm các gói NuGet mới qua lệnh: `dotnet add package [tên_gói]`.
+### 🔄 Agent Development Lifecycle
+The AI Agent must execute all .NET tasks following this 5-step workflow:
+1. **Design & Implementation:** Implement business logic adhering to Clean Architecture / Onion Architecture principles. Maintain Core Logic in decoupled Application/Domain layers.
+2. **Comprehensive Testing:** Write unit tests for Services using xUnit and Moq.
+3. **Code Quality & Verification:** Run build and test execution commands:
+   - Build Check: `dotnet build`
+   - Test Execution: `dotnet test`
+4. **Package Management:** Add new NuGet dependencies using the command: `dotnet add package [package_name]`.
 
 ---
 
-### 🏗️ 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 coding style chuẩn C#, PascalCase, camelCase và tiền tố Interface: `@csharp-style.md`
-- Quy định đăng ký và sử dụng Dependency Injection (Transient, Scoped, Singleton): `@dependency-injection.md`
-- Phân định trách nhiệm API Controller và điều phối luồng xử lý: `@api-structure.md`
-- Cấu hình FluentValidation và middleware xử lý ngoại lệ tập trung: `@error-handling-validation.md`
-- Quy trình từng bước sinh mới API Controller, DTO, Request Validator: `@SKILL.md`
+### 🏗️ Template Blueprint
+Refer to the detailed rules below:
+- C# coding style, PascalCase, camelCase, and Interface prefixes: `@csharp-style.md`
+- Dependency Injection lifetimes (Transient, Scoped, Singleton) registration: `@dependency-injection.md`
+- API Controller responsibilities and execution dispatch: `@api-structure.md`
+- FluentValidation setups and centralized exception handling middleware: `@error-handling-validation.md`
+- Scaffolding a new API Controller, DTO, and Request Validator: `@SKILL.md`
 
 ---
 
-### 🏛️ Quy Tắc Phát Triển Nghiêm Ngặt
+### 🏛️ Strict Development Rules
 
-#### 1. Kiến Trúc Sạch (Clean Architecture)
-Phân tách rõ ràng các tầng trách nhiệm:
-- **Domain:** Chứa Entities, Value Objects, Domain Logic. Tuyệt đối không phụ thuộc vào bất kỳ thư viện ngoài nào.
-- **Application:** Chứa Interfaces, DTOs, Use Cases (Services/Queries/Commands). Chỉ phụ thuộc vào Domain layer.
-- **Infrastructure:** Chứa Data Access (EF Core), External Services. Phụ thuộc vào Application layer.
-- **Presentation (API):** Chứa Controllers, Middlewares. Điểm khởi chạy của ứng dụng.
+#### 1. Clean Architecture Layers
+Strictly separate concerns across application boundaries:
+- **Domain:** Houses Entities, Value Objects, and core Domain Logic. Must remain free of external package references.
+- **Application:** Houses Interfaces, DTOs, and Use Cases (Services/Queries/Commands). Depends only on the Domain layer.
+- **Infrastructure:** Houses Data Access (EF Core DbContext) and External Integrations. Depends on the Application layer.
+- **Presentation (API):** Houses Controllers, Filters, and Middlewares. The entrypoint of the execution runtime.
 
-#### 2. Đăng Ký Dependency Injection (DI)
-- Sử dụng constructor injection để tiêm các dịch vụ cần thiết qua các interface.
-- Tuyệt đối cấm sử dụng Service Locator pattern (ví dụ: giải quyết dependencies thủ công qua `IServiceProvider` trong runtime).
+#### 2. Dependency Injection (DI) Registration
+- Inject all downstream services using constructor parameters via interfaces.
+- Never use the Service Locator pattern (e.g., manually resolving dependencies at runtime using `IServiceProvider`).
 
-#### 3. Kiểm Thử Dữ Liệu Tự Động Với FluentValidation
-- Toàn bộ dữ liệu đầu vào của API Request phải được kiểm duyệt tự động thông qua các class Validator thừa kế từ `AbstractValidator<T>` của thư viện FluentValidation.
-- Không viết code validate thủ công bằng các câu lệnh `if` rải rác trong Controller.
+#### 3. Validation with FluentValidation
+- Validate all incoming request DTOs using validators inheriting from FluentValidation's `AbstractValidator<T>`.
+- Do not write manual validation statements scattered across Controller methods.

package/templates/dotnet/rules/api-structure.md

@@ -1,25 +1,25 @@
-# Cấu Trúc Lớp Presentation (API Controllers)
+# Presentation Layer Structure (API Controllers)
 
-Tài liệu này quy định cấu trúc và trách nhiệm của API Controllers trong tầng Presentation của ứng dụng .NET.
+This document defines the structure and responsibilities of API Controllers inside the Presentation layer of a .NET application.
 
 ---
 
-## 🏛️ Trách Nhiệm Của API Controller
-API Controller chịu trách nhiệm:
-1. Nhận yêu cầu HTTP (HTTP Requests) từ client.
-2. Ánh xạ các tham số URL, Query String, hoặc Request Body vào các DTO tương ứng.
-3. Chuyển giao các tham số đó sang tầng Application (Services/Queries/Commands).
-4. Nhận lại kết quả và phản hồi Client thông qua các mã trạng thái HTTP phù hợp (200 OK, 201 Created, 400 Bad Request, 404 Not Found, v.v.).
+## 🏛️ API Controller Responsibilities
+An API Controller is responsible for:
+1. Receiving incoming HTTP requests from clients.
+2. Mapping URL parameters, query strings, or request bodies into target request DTOs.
+3. Delegating request processing to the Application layer (Services/Queries/Commands).
+4. Receiving results and responding to the client using appropriate HTTP status codes (e.g., `200 OK`, `201 Created`, `400 Bad Request`, `404 Not Found`).
 
 ---
 
-## 🚦 Quy Tắc Phát Triển
-- **Controller mỏng (Thin Controllers):** Controllers không chứa bất kỳ logic nghiệp vụ, tính toán thuật toán, hay truy vấn DB trực tiếp. 100% logic đó phải nằm dưới Application layer.
-- **Không tiêm DbContext vào Controller:** DbContext phải được che giấu dưới Infrastructure / Repository layer. Tầng Presentation tuyệt đối không gọi DbContext.
-- **Sử dụng DTO thay vì Entity trực tiếp:**
-  - Không nhận trực tiếp Domain Entities làm đầu vào của Controller.
-  - Không trả trực tiếp Domain Entities về cho Client để tránh lộ cấu trúc DB hoặc lỗi cyclic references. Luôn ánh xạ qua các lớp DTO (Data Transfer Objects).
-- **Cấu hình định tuyến Route rõ ràng:** Sử dụng attribute routing để khai báo rõ ràng phương thức HTTP và endpoint:
+## 🚦 Development Rules
+- **Thin Controllers:** Controllers must not contain business logic, algorithmic calculations, or direct database queries. 100% of this logic must reside in the Application layer.
+- **Do Not Inject DbContext into Controllers:** Keep `DbContext` encapsulated within the Infrastructure / Repository layers. The Presentation layer must never access `DbContext` directly.
+- **Use DTOs Instead of Domain Entities:**
+  - Never accept raw Domain Entities as Controller input parameters.
+  - Never return raw Domain Entities directly to the client to prevent exposing the database schema or triggering cyclic reference errors. Always map records to DTO (Data Transfer Object) classes.
+- **Explicit Route Declarations:** Use attribute routing to clearly declare HTTP methods and endpoints:
   ```csharp
   [ApiController]
   [Route("api/v1/[controller]")]

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);