agent-workflow-kit-cli 1.3.1 → 1.3.3

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

@@ -0,0 +1,43 @@
+# Presentation Layer Structure (API Controllers)
+
+This document defines the structure and responsibilities of API Controllers inside the Presentation layer of a .NET application.
+
+---
+
+## 🏛️ 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`).
+
+---
+
+## 🚦 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]")]
+  public class CoursesController : ControllerBase
+  {
+      private readonly ICourseService _courseService;
+
+      public CoursesController(ICourseService courseService)
+      {
+          _courseService = courseService;
+      }
+
+      [HttpGet("{id}")]
+      public async Task<IActionResult> GetById(Guid id)
+      {
+          var course = await _courseService.GetByIdAsync(id);
+          if (course == null) return NotFound();
+          return Ok(course);
+      }
+  }
+  ```

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

@@ -0,0 +1,33 @@
+# C# Coding Style & Conventions
+
+This document specifies standard coding styles, naming patterns, and source file organization conventions in .NET projects.
+
+---
+
+## 🏷️ Naming Conventions
+
+### 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;`.
+
+---
+
+## 📦 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;
+
+  public class UserService : IUserService
+  {
+      // ...
+  }
+  ```
+- **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

@@ -0,0 +1,54 @@
+# Dependency Injection (DI) Configurations
+
+This document details guidelines for configuring and consuming dependency injection in .NET Core applications.
+
+---
+
+## 💉 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).
+
+  * **Invalid (❌ Prohibited):**
+    ```csharp
+    public class OrderService
+    {
+        private readonly IServiceProvider _serviceProvider;
+        
+        public OrderService(IServiceProvider serviceProvider)
+        {
+            _serviceProvider = serviceProvider;
+        }
+
+        public void Process()
+        {
+            var repo = _serviceProvider.GetService<IOrderRepository>();
+            // ...
+        }
+    }
+    ```
+  * **Valid (✔️ Recommended):**
+    ```csharp
+    public class OrderService : IOrderService
+    {
+        private readonly IOrderRepository _orderRepository;
+
+        public OrderService(IOrderRepository orderRepository)
+        {
+            _orderRepository = orderRepository;
+        }
+
+        public void Process()
+        {
+            var orders = _orderRepository.GetAll();
+            // ...
+        }
+    }
+    ```
+
+---
+
+## ⚙️ 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

@@ -0,0 +1,86 @@
+# Unified Exception Handling & Automated Validation (FluentValidation)
+
+This document defines configurations for centralized exception handling using Middleware and incoming request validation using the FluentValidation library in .NET applications.
+
+---
+
+## 🛡️ 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
+  // Example of a Validator class
+  using FluentValidation;
+
+  public class CreateCourseRequestValidator : AbstractValidator<CreateCourseRequestDto>
+  {
+      public CreateCourseRequestValidator()
+      {
+          RuleFor(x => x.Title)
+              .NotEmpty().WithMessage("Course title cannot be empty.")
+              .MaximumLength(150).WithMessage("Title must not exceed 150 characters.");
+
+          RuleFor(x => x.Price)
+              .GreaterThanOrEqualTo(0).WithMessage("Course price cannot be less than 0.");
+      }
+  }
+  ```
+
+---
+
+## 🚨 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": "An internal server error occurred. Please contact the administrator."
+  }
+  ```
+
+  ```csharp
+  // Standard Global Exception Handling Middleware
+  public class ExceptionHandlingMiddleware
+  {
+      private readonly RequestDelegate _next;
+      private readonly ILogger<ExceptionHandlingMiddleware> _logger;
+
+      public ExceptionHandlingMiddleware(RequestDelegate next, ILogger<ExceptionHandlingMiddleware> logger)
+      {
+          _next = next;
+          _logger = logger;
+      }
+
+      public async Task InvokeAsync(HttpContext context)
+      {
+          try
+          {
+              await _next(context);
+          }
+          catch (Exception ex)
+          {
+              _logger.LogError(ex, "An unhandled exception has occurred.");
+              await HandleExceptionAsync(context, ex);
+          }
+      }
+
+      private static Task HandleExceptionAsync(HttpContext context, Exception exception)
+      {
+          context.Response.ContentType = "application/json";
+          context.Response.StatusCode = StatusCodes.Status500InternalServerError;
+
+          var response = new
+          {
+              success = false,
+              statusCode = context.Response.StatusCode,
+              timestamp = DateTime.UtcNow,
+              message = "An internal server error occurred. Please contact the administrator."
+          };
+
+          return context.Response.WriteAsJsonAsync(response);
+      }
+  }
+  ```

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

@@ -0,0 +1,24 @@
+---
+name: dotnet-controller
+description: Scaffold or extend an ASP.NET Core API Controller with corresponding DTOs, FluentValidation, and Service interfaces
+---
+
+Follow this process to generate a new API Endpoint or Controller in .NET (C#).
+
+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
+
+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

@@ -0,0 +1,41 @@
+## 🗺️ 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.
+
+---
+
+### 🏗️ 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`
+
+---
+
+### 🏛️ Strict Development Rules
+
+#### 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:** 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

@@ -0,0 +1,88 @@
+# Async Error Handling & Automated Validation (Zod Middleware)
+
+This document defines standard practices for asynchronous error catching, centralized global error handling middleware, and automated schema validations using Zod.
+
+---
+
+## 🚨 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';
+
+  // Automated async error catcher wrapper
+  const asyncHandler = (fn: Function) => (req: Request, res: Response, next: NextFunction) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+
+  // Controller usage example
+  export const getUserProfile = asyncHandler(async (req: Request, res: Response) => {
+    const userId = req.user.id;
+    const profile = await userService.getProfile(userId); // Errors thrown inside the service are automatically caught
+    return res.status(200).json({ success: true, data: profile });
+  });
+  ```
+
+---
+
+## 🔌 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
+  // 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';
+
+    res.status(statusCode).json({
+      success: false,
+      status: statusCode,
+      message: message,
+      stack: process.env.NODE_ENV === 'development' ? err.stack : undefined,
+    });
+  });
+  ```
+
+---
+
+## 🛡️ 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';
+  import { Request, Response, NextFunction } from 'express';
+
+  export const validateSchema = (schema: AnyZodObject) => {
+    return async (req: Request, res: Response, next: NextFunction): Promise<any> => {
+      try {
+        // Validate incoming request segments concurrently
+        const parsed = await schema.parseAsync({
+          body: req.body,
+          query: req.query,
+          params: req.params,
+        });
+        
+        // Re-assign parsed and sanitized payloads
+        req.body = parsed.body;
+        req.query = parsed.query;
+        req.params = parsed.params;
+        
+        return next();
+      } catch (error) {
+        if (error instanceof ZodError) {
+          return res.status(400).json({
+            success: false,
+            message: 'Invalid input payload parameters',
+            errors: error.errors.map((err) => ({
+              field: err.path.join('.'),
+              message: err.message,
+            })),
+          });
+        }
+        return next(error);
+      }
+    };
+  };
+  ```

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

@@ -0,0 +1,39 @@
+# Express.js Naming Conventions & Coding Style
+
+This document defines coding conventions, directory layout, and TypeScript configurations for Express.js applications.
+
+---
+
+## 🏷️ Naming Conventions
+
+### Directory Layout (3-Tier Architecture)
+The codebase must be structured cleanly according to a 3-tier architecture layout:
+```bash
+src/
+├── 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
+```
+
+### 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`
+  - Middleware: `auth-middleware.ts`, `validate-middleware.ts`
+  - Model: `user-model.ts`
+
+---
+
+## 📦 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';
+  ```
+- **Strictly Ban the `any` Keyword:** Declare interfaces or types for all request bodies and API response structures.

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

@@ -0,0 +1,27 @@
+# Architectural Boundaries (Router vs Controller vs Service)
+
+This document establishes boundaries and responsibilities for routers, controllers, and services in Express.js projects.
+
+---
+
+## 🏛️ 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}$$
+
+---
+
+## 🚦 Layer Responsibilities
+
+### 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. 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. 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

@@ -0,0 +1,24 @@
+---
+name: express-endpoint
+description: Scaffold or extend a secure Express.js + TypeScript API endpoint including Router, Controller, and Validator
+---
+
+Follow this process to generate a new Express.js API Endpoint or extend an existing route.
+
+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
+
+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`
+   - `{{runCommand}} build`

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.