agent-workflow-kit-cli 1.3.2 → 1.3.4

package/templates/fastapi/AGENTS.md.hbs

@@ -1,11 +1,19 @@
 ## 🐍 Python FastAPI Guidelines
 
+### 🔄 End-to-End Agent Development Lifecycle
+AI Agents must execute all Python FastAPI tasks following this structured 5-stage lifecycle:
+1. **Design & Code:** Implement layers following the structure guidelines below. Keep routes thin and business logic inside Services/CRUD.
+2. **Comprehensive Testing:** Write API test cases using pytest and `httpx.AsyncClient`. Mock all external dependencies. Review the testing guidelines in `@api-testing.md`.
+3. **Troubleshooting & Debugging:** When debugging database or connection errors, follow async context managers and mock session structures.
+4. **Code Quality & Review:** Perform self-review using `@python-style.md` to check type hinting, Pydantic validations, and parameter annotations.
+5. **Database Integrity:** Ensure all structural changes have matching Alembic migrations. Conform to async session guidelines in `@database-async.md`.
+
 ### 🏗️ Architecture & Router-Service-Repository Conventions
-Follow a clean layering architecture. Separate HTTP routing, business logic, and database operations:
+Follow a feature-first or modular layered architecture. Separate HTTP routing, business logic, and database operations:
 
 ```text
 app/
-  core/           # Config, database setup
+  core/           # Config, database setup, exceptions
   models/         # SQLAlchemy or SQLModel entities
   schemas/        # Pydantic validation models
   crud/           # Database repositories/CRUD operations
@@ -16,10 +24,24 @@ app/
 ```
 
 ### ⚙️ Coding Guidelines
-- **Dependency Injection:** Use FastAPI's `Depends` explicitly for injecting database sessions, security credentials, and custom services.
+- **Dependency Injection:** Use FastAPI's `Depends` explicitly for injecting database sessions, security credentials, and custom services. Avoid manual imports of DB connections.
 - **Strict Typing:** Always annotate function arguments and return types. Use Pydantic's `response_model` or type hints to enforce validation.
 - **Asynchronous Handlers:** Prefer `async def` for I/O bound endpoints.
 
+### 🏛️ Strict Development Rules
+
+#### 1. Input/Output Validation with Pydantic
+- Validate all incoming request payloads using Pydantic models.
+- Design distinct schemas for read, create, and update actions (e.g. `UserRead`, `UserCreate`, `UserUpdate`) to prevent exposing sensitive fields or auto-incrementing ID fields.
+
+#### 2. Async Database Session Lifecycle
+- Always use `AsyncSession` from `sqlalchemy.ext.asyncio` for operations.
+- Bind the database session lifetime using dependency yield. Review the rules in `@database-async.md`.
+
+#### 3. Error Handling
+- Never throw raw python exceptions directly from routers.
+- Map business logic errors (e.g., entity not found, duplicate emails) to FastAPI's built-in `HTTPException` class with specific status codes (e.g., `404 Not Found`, `400 Bad Request`).
+
 ### 🧪 Testing & Verification
 Before completing a task, run the following verification pipeline locally:
 ```bash

package/templates/fastapi/rules/api-testing.md

@@ -0,0 +1,24 @@
+# API Testing Rules (FastAPI & Pytest)
+
+Testing guidelines for endpoints, services, and mocks:
+
+## Test Setup and Client
+- Use `pytest` for running test suites.
+- Use `httpx.AsyncClient` or `FastAPI.testclient.TestClient` for HTTP testing. If endpoints are asynchronous (`async def`), prefer `httpx.AsyncClient` with `pytest-asyncio` markers:
+  ```python
+  @pytest.mark.asyncio
+  async def test_read_items(client: AsyncClient):
+      response = await client.get("/items/")
+      assert response.status_code == 200
+  ```
+
+## Fixtures and DB Mocking
+- **Database isolation:** Create a clean database session for each test run. Do not use the production database; use an in-memory SQLite (`sqlite+aiosqlite:///:memory:`) or a dedicated PostgreSQL test container/database.
+- **Fixture overrides:** Override the `get_db` dependency in the app:
+  ```python
+  app.dependency_overrides[get_db] = override_get_db
+  ```
+
+## Mocking External Dependencies
+- Use `pytest-mock` (via the `mocker` fixture) to intercept external HTTP calls (such as third-party APIs or email dispatch services).
+- Never make actual outbound network calls during tests.

package/templates/fastapi/rules/database-async.md

@@ -0,0 +1,26 @@
+# Async Database Rules (FastAPI & SQLAlchemy)
+
+Guidelines for database access, connection pooling, and async operations:
+
+## Async Sessions and Depends
+- **Async Database Connection:** Always use `AsyncSession` from `sqlalchemy.ext.asyncio`.
+- **Session Lifecycle:** Inject the database session using `Depends(get_db)`. Ensure the dependency closes the session cleanly using a context manager or yield:
+  ```python
+  async def get_db() -> AsyncIterator[AsyncSession]:
+      async with AsyncSessionLocal() as session:
+          yield session
+  ```
+
+## Querying and Transactions
+- **Async Queries:** Never use synchronous execution APIs. Always execute queries asynchronously using `session.execute(select(...))` or similar.
+- **Explicit Transactions:** Use `async with session.begin():` blocks for operations modifying multiple entities to ensure atomic commits and rollbacks.
+- **Relationship Loading:** Avoid implicit lazy loading since it raises errors in async contexts. Explicitly specify loading strategies like `selectinload` or `joinedload`:
+  ```python
+  stmt = select(User).options(selectinload(User.items))
+  ```
+
+## Migrations (Alembic)
+- Every schema change must have a corresponding Alembic migration.
+- Auto-generate migrations using:
+  `alembic revision --autogenerate -m "description"`
+- Always inspect the generated migration script for accuracy before applying.

package/templates/golang/AGENTS.md.hbs

@@ -0,0 +1,42 @@
+## 🗺️ Golang Development Guide (Go Backend)
+
+### 🔄 Agent Development Lifecycle
+The AI Agent must execute all Golang tasks following this structured 5-stage lifecycle:
+1. **Design & Code:** 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. Mock database layers or third-party connections.
+3. **Troubleshooting & Debugging:** When debugging goroutines or database locks, use context cancellation and trace log output.
+4. **Code Quality & Review:** Verify code quality against `@golang-style.md` to check interface boundaries, error wrapping, and naming.
+5. **Acyclic Design:** Ensure there are no circular imports. Encapsulate domain packages cleanly under `@project-layout.md` and manage concurrent access via `@concurrency.md`.
+
+---
+
+### 🏗️ 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`
+- Scaffolding a business feature (Handler, Service interface, tests): `@golang-feature`
+- Scaffolding repository database operations and models: `@golang-db`
+
+---
+
+### 🏛️ 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. Review details in `@error-handling.md`.
+
+#### 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`.
+
+### 🧪 Verification & Testing
+Before completing a task, run the following verification pipeline locally:
+- **Build Validation:** `go build ./...`
+- **Testing:** `go test ./...`
+- **Formatting:** `gofmt -w .`

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}
+}
+```

package/templates/golang/skills/golang-db/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: golang-db
+description: Scaffold a Go database repository layer using SQLx, GORM, or raw SQL queries
+---
+
+Follow this process to add or extend database entities and repository queries.
+
+Inputs:
+- structName: Model entity struct name (e.g., `User`)
+- tableName: Database table name (e.g., `users`)
+- repositoryName: Interface name (e.g., `UserRepository`)
+
+Steps:
+1. Declare the entity model struct with json and db (or gorm) tags:
+   ```go
+   type User struct {
+       ID        int64     `json:"id" db:"id" gorm:"primaryKey"`
+       Email     string    `json:"email" db:"email"`
+       CreatedAt time.Time `json:"created_at" db:"created_at"`
+   }
+   ```
+2. Define the repository interface (e.g., `UserRepository`) containing standard SQL actions (`FindByID`, `Save`).
+3. Implement the interface concrete struct wrapping the database handle (e.g., `*sql.DB`, `*sqlx.DB`, or `*gorm.DB`).
+4. Wire the repository implementation to the service layer using constructor injection.
+5. Create SQL schema files under the `/migrations` or `/db` directories if schema changes are required.
+6. Verify code correctness using:
+   - `go build ./...`

package/templates/golang/skills/golang-feature/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: golang-feature
+description: Scaffold a Go package slice including Handler, Service interfaces, and table-driven unit tests
+---
+
+Follow this process to generate a new Go business feature slice.
+
+Inputs:
+- packageName: Name of the package (e.g., `billing`)
+- structName: Primary model struct name (e.g., `Invoice`)
+- functionality: Summary of the business requirements and API paths
+
+Steps:
+1. Create a directory inside `internal/` named `<packageName>/` (e.g., `internal/billing`).
+2. Declare structs and interfaces in `<packageName>.go` or `types.go` (e.g., `BillingService` interface and `Invoice` struct).
+3. Implement the concrete service class (e.g., `service.go` containing `type service struct { ... }` implementing `BillingService`).
+4. Implement HTTP handlers in `handler.go` wrapping inputs/outputs via JSON bindings.
+5. Register routers/handlers in the application bootloader (e.g., in `cmd/server/main.go`).
+6. Write unit tests in `service_test.go` using table-driven tests:
+   ```go
+   func TestBillingService(t *testing.T) {
+       tests := []struct {
+           name    string
+           input   string
+           wantErr bool
+       }{
+           {
+               name:    "Valid input case",
+               input:   "valid",
+               wantErr: false,
+           },
+       }
+       for _, tt := range tests {
+           t.Run(tt.name, func(t *testing.T) {
+               // Implement test validation
+           })
+       }
+   }
+   ```
+7. Run validation commands:
+   - `go build ./...`
+   - `go test ./...`

package/templates/nestjs/AGENTS.md.hbs

@@ -1,38 +1,42 @@
-## 🗺️ Hướng Dẫn Phát Triển NestJS (Node.js Backend)
-
-### 🔄 Vòng Đời Phát Triển Tác Nhân (Agent Development Lifecycle)
-Tác nhân AI phải thực hiện tất cả các nhiệm vụ NestJS theo quy trình 5 bước sau:
-1. **Thiết kế & Lập trình:** Triển khai các lớp nghiệp vụ tuân thủ cấu trúc Module-driven. Giữ Controller mỏng, đặt 100% logic nghiệp vụ trong Service.
-2. **Kiểm thử Toàn diện:** Viết unit test cho các Service sử dụng Jest Mocking (`.spec.ts`) và viết kiểm thử tích hợp đầu cuối (E2E) sử dụng Supertest.
-3. **Chất lượng Mã nguồn:** Chạy các lệnh kiểm tra lỗi cú pháp và kiểu dữ liệu:
-   - Kiểm tra Lint: `{{runCommand}} lint`
-   - Kiểm tra Kiểu dữ liệu: `{{runCommand}} typecheck`
-   - Chạy Kiểm thử: `{{runCommand}} test` (hoặc `{{runCommand}} test -- --run` cho môi trường CI/CD)
-   - Chạy Build thử nghiệm: `{{runCommand}} build`
-4. **Quản lý Thư viện:** Cài đặt các thư viện mới bằng lệnh: `{{packageManager}} add [tên_thư_viện]`. Tuyệt đối cấm sửa thủ công file lock `{{lockFile}}`.
+## 🗺️ NestJS Development Guide (Node.js Backend)
+
+### 🔄 Agent Development Lifecycle
+The AI Agent must execute all NestJS tasks following this structured 5-stage lifecycle:
+1. **Design & Code:** Implement business logic adhering to the Module-driven architecture. Keep Controllers thin; place 100% of business logic within Services. Encapsulate components cleanly as outlined in `@module-architecture.md`.
+2. **Comprehensive Testing:** Write unit tests for Services using Jest Mocking (`.spec.ts`) and end-to-end (E2E) integration tests using Supertest.
+3. **Troubleshooting & Debugging:** When debugging request validations or database mappings, inspect class-validator metadata and database query logs.
+4. **Code Quality & Review:** Perform self-review using `@validation-errors.md` to ensure constraints are enforced and exceptions are mapped correctly. Check formatting conventions in `@nestjs-style.md`.
+5. **Production Readiness:** Verify compilation and lint errors are resolved before completion.
 
 ---
 
-### 🏗️ Kiến Trúc Hệ Thống Bản Mẫu (Template Blueprint)
-Vui lòng tham khảo các tài liệu quy tắc chi tiết dưới đây:
-- Hướng dẫn coding style chuẩn TypeScript, quy tắc căn lề, sắp xếp decorator và tổ chức mã nguồn sạch: `@nestjs-style.md`
-- Quy định chặt chẽ về ranh giới Module, cơ chế cô lập mã nguồn, Encapsulation và chia sẻ tài nguyên: `@module-architecture.md`
-- Cấu hình Class Validator, chuyển đổi dữ liệu thông qua ValidationPipe và xử lý lỗi tập trung bằng Exceptions Filters: `@validation-errors.md`
-- Quy trình tự động sinh trọn bộ cấu phần gồm Module, Controller, Service, DTO, Entity theo đúng chuẩn hệ thống: `@SKILL.md`
+### 🏗️ Template Blueprint
+Refer to the detailed rules below:
+- TypeScript coding style, indentation, decorator sorting, and clean code conventions: `@nestjs-style.md`
+- Strict module boundaries, encapsulation, and resource sharing rules: `@module-architecture.md`
+- Class Validator setups, ValidationPipe data transformations, and Exception Filters: `@validation-errors.md`
+- Process to scaffold modular components (Module, Controller, Service, DTO, Entity): `@nestjs-module`
 
 ---
 
-### 🏛️ Quy Tắc Phát Triển Nghiêm Ngặt
+### 🏛️ Strict Development Rules
+
+#### 1. Dependency Injection (DI)
+- **No Property Injection:** Never use the `@Inject()` decorator directly on class properties unless injecting Custom Tokens. Property injection limits test mocking capabilities.
+- **Constructor Injection Required:** Leverage NestJS's auto-dependency resolution via constructor parameters using `private readonly`.
 
-#### 1. Tiêm Phụ Thuộc (Dependency Injection)
-- **Cấm tiêm thuộc tính (Property Injection):** Tuyệt đối không dùng `@Inject()` trực tiếp trên thuộc tính của Class trừ trường hợp tiêm các token tùy biến (Custom Tokens).
-- **Bắt buộc tiêm qua Hàm Khởi Tạo (Constructor Injection):** Sử dụng cơ chế tự động phân giải phụ thuộc của NestJS qua từ khóa `private readonly`.
+#### 2. Input Validation & Transformation
+- **Strict DTO Definitions:** All incoming HTTP request parameters (`@Body()`, `@Query()`, `@Param()`) must be mapped to DTO classes decorated with `class-validator` rules.
+- **Global Validation Pipe:** Configure a global `ValidationPipe` in `main.ts` to strip non-whitelisted properties and automatically transform types.
 
-#### 2. Kiểm Thử Dữ Liệu Đầu Vào (Validation & Transformation)
-- **Định hình DTO nghiêm ngặt:** Toàn bộ dữ liệu đầu vào của HTTP Request (`@Body()`, `@Query()`, `@Param()`) phải được đặc tả qua các lớp DTO sử dụng decorator từ `class-validator`.
-- **Kích hoạt ống lọc toàn cục (Global Validation Pipe):** Khai báo tại file `main.ts` để tự động lọc bỏ các thuộc tính không nằm trong danh sách trắng (whitelist) và tự động ép kiểu dữ liệu (transform).
+#### 3. Unified Exception Handling
+- **No Raw Server Errors:** Never expose raw database or system exceptions (HTTP 500) to clients.
+- **Built-in HttpExceptions:** Handle try/catch flows inside Services and map errors to explicit NestJS HttpExceptions (e.g., `NotFoundException`, `BadRequestException`, `ForbiddenException`).
+- **Global Exception Filter:** Expose a global Exception Filter to format all error responses consistently in JSON format.
 
-#### 3. Quản Lý Ngoại Lệ Toàn Cục (Unified Exception Handling)
-- **Cấm trả về lỗi hệ thống thô:** Tuyệt đối không để lộ lỗi thô (chẳng hạn như lỗi từ DB) ra ngoài client với mã lỗi 500.
-- **Sử dụng HttpExceptions tích hợp:** Bắt buộc phải bắt lỗi (try/catch) ở tầng Service và ánh xạ sang các Http Exception tường minh của NestJS (`NotFoundException`, `BadRequestException`, `ForbiddenException`).
-- **Tập trung hóa bằng Exception Filter:** Xây dựng một Filter toàn cục để cấu trúc lại định dạng JSON trả về cho Client một cách đồng nhất.
+### 🧪 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/nestjs/rules/module-architecture.md

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

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

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