agent-workflow-kit-cli 1.3.1 → 1.3.3

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/nestjs/AGENTS.md.hbs

@@ -0,0 +1,38 @@
+## 🗺️ NestJS Development Guide (Node.js Backend)
+
+### 🔄 Agent Development Lifecycle
+The AI Agent must execute all NestJS tasks following this 5-step workflow:
+1. **Design & Implementation:** Implement business logic adhering to the Module-driven architecture. Keep Controllers thin; place 100% of business logic within Services.
+2. **Comprehensive Testing:** Write unit tests for Services using Jest Mocking (`.spec.ts`) and end-to-end (E2E) integration tests 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:
+- 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): `@SKILL.md`
+
+---
+
+### 🏛️ 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`.
+
+#### 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.
+
+#### 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.

package/templates/nestjs/rules/module-architecture.md

@@ -0,0 +1,35 @@
+# Modular Architecture & Dependency Injection (DI)
+
+This document defines module boundaries, code isolation (encapsulation), and dependency injection standards in NestJS.
+
+---
+
+## 💉 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.
+
+  * **Invalid (❌ Prohibited):**
+    ```typescript
+    @Injectable()
+    export class AuthService {
+      @Inject(UsersService)
+      private readonly usersService: UsersService;
+    }
+    ```
+  * **Valid (✔️ Recommended):**
+    ```typescript
+    @Injectable()
+    export class AuthService {
+      constructor(private readonly usersService: UsersService) {}
+    }
+    ```
+
+---
+
+## 🏗️ 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

@@ -0,0 +1,41 @@
+# NestJS Naming Conventions & Coding Style
+
+This document outlines standard guidelines for TypeScript coding styles, filename notations, and class naming conventions in NestJS.
+
+---
+
+## 🏷️ Naming Conventions
+
+### Filename Notation (Dot Notation)
+All filenames in NestJS must strictly comply with the following format: `<name>.<type>.ts`.
+
+```bash
+# Module directories should use consistent singular or plural names (e.g., auth, users, products)
+src/users/
+├── users.module.ts
+├── users.controller.ts
+├── users.service.ts
+├── dto/
+│   ├── create-user-request.dto.ts
+│   └── update-user-response.dto.ts
+├── entities/
+│   └── user.entity.ts
+├── guards/
+│   └── roles.guard.ts
+└── interceptors/
+    └── logging.interceptor.ts
+```
+
+### 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 {}`
+- **DTO:** `src/auth/dto/login.dto.ts` $\rightarrow$ `export class LoginRequestDto {}`
+
+---
+
+## 📦 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.

package/templates/nestjs/rules/validation-errors.md

@@ -0,0 +1,46 @@
+# Data Validation & Unified Exception Handling
+
+This document specifies conventions for using Class Validator, configuring the global ValidationPipe, and handling errors centrally via Exception Filters in NestJS.
+
+---
+
+## 🛡️ Input Validation & Transformation
+- **Strict DTO Mapping:** All incoming HTTP request data (`@Body()`, `@Query()`, `@Param()`) must be mapped using DTO classes decorated with rules from `class-validator` (such as `@IsString()`, `@IsEmail()`, `@IsInt()`).
+- **Global Validation Pipe:** Configure the global `ValidationPipe` inside `main.ts` to automatically strip properties not declared in the DTO (whitelist) and transform inputs into their corresponding types.
+
+  ```typescript
+  // Inside main.ts
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,            // Auto-strips properties not declared in DTO
+      forbidNonWhitelisted: true, // Throws HTTP 400 if client sends extra fields
+      transform: true,            // Auto-casts types (e.g. string to number, object to class instance)
+    }),
+  );
+  ```
+
+---
+
+## 🚨 Unified Exception Handling
+- **No Raw System Errors:** Never expose raw database or execution exceptions directly to clients with HTTP 500 errors.
+- **Built-in HttpExceptions:** Implement try/catch blocks within Services and map failures to explicit NestJS HttpExceptions (e.g., `NotFoundException`, `BadRequestException`, `ForbiddenException`).
+  
+  ```typescript
+  try {
+    return await this.courseRepo.findOneOrFail(id);
+  } catch (error) {
+    throw new NotFoundException("The requested course does not exist.");
+  }
+  ```
+
+- **Global Exception Filter:** Implement a global Exception Filter to structure JSON error responses uniformly. The standardized error payload must follow this structure:
+
+  ```json
+  {
+    "success": false,
+    "statusCode": 404,
+    "timestamp": "2026-06-13T06:48:24.000Z",
+    "path": "/api/v1/courses/999",
+    "message": "The requested course does not exist."
+  }
+  ```

package/templates/nestjs/skills/nestjs-module/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: nestjs-module
+description: Automatically scaffold a complete NestJS Module including Controller, Service, DTO, and Entity according to standard conventions
+---
+
+Follow this process to generate a new NestJS Module or extend an existing one.
+
+Inputs:
+- moduleName: Name of the module to create (e.g., `products`)
+- targetPath: The destination path inside `src/` to place the code
+- functionality: Summary of the business requirements and endpoints to expose
+
+Steps:
+1. Create a module directory `<moduleName>/` under the `src/` directory (e.g., `src/products`).
+2. Define the Entity model in the `<moduleName>/entities/` folder.
+3. Define the Request/Response DTO classes in the `<moduleName>/dto/` folder. Apply appropriate validation decorators.
+4. Implement the Service class in `<moduleName>/` using NestJS Dependency Injection. Write 100% of the business logic here, handle exceptions, and throw explicit HttpExceptions.
+5. Implement the Controller class in `<moduleName>/` to map HTTP requests, configure permission checks (Guards), and return the JSON response.
+6. Register the Controller and Service inside the module definition file `<moduleName>.module.ts`. Export the Service if other modules need to consume it.
+7. Write unit tests for the Service (`.spec.ts`) and create E2E integration test scripts using Supertest.
+8. Execute local validation:
+   - `{{runCommand}} lint`
+   - `{{runCommand}} typecheck`
+   - `{{runCommand}} test`
+   - `{{runCommand}} build`

package/templates/next-js/AGENTS.md.hbs

@@ -0,0 +1,41 @@
+## 🗺️ Next.js Development Guide (App Router)
+
+### 🔄 Agent Development Lifecycle
+The AI Agent must execute all Next.js tasks following this 5-step workflow:
+1. **Design & Implementation:** Build pages and components adhering to the App Router conventions. Default to React Server Components (RSC).
+2. **Comprehensive Testing:** Write unit tests for business utilities and component behavior using Jest/Vitest.
+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:
+- Coding conventions, formatting, import sorting, and directory structure: `@next-style.md`
+- Architectural boundaries between React Server Components (RSC) and React Client Components (RCC): `@server-client-components.md`
+- Server-side data fetching, caching, revalidation, and secure Server Actions: `@data-fetching-mutations.md`
+- Semantic HTML5 standards and Dynamic Metadata API configurations: `@seo-metadata.md`
+- Step-by-step process to generate new Pages or Routes cleanly: `@SKILL.md`
+
+---
+
+### 🏛️ Strict Development Rules
+
+#### 1. Rendering Paradigm
+- **Server Components by Default:** All components within the `app/` directory must default to React Server Components (RSC).
+- **Isolate Client Components (RCC):** Declare `"use client"` only at leaf components that require interactivity (e.g., Form submissions, click handlers, `useState`, `useEffect`, or browser APIs).
+
+#### 2. Data Fetching & Server Actions
+- **Fetch at the Source:** Execute `fetch()` directly inside async Server Components to optimize request caching and protect API tokens/secrets.
+- **Cache Management:** Never use raw fetch without specifying caching/revalidation parameters.
+- **Mutations via Server Actions:** Handle POST, PUT, and DELETE mutations using Server Actions (marked with `"use server"`).
+- **Fluid UX:** Use the `useActionState` (or `useFormState`) hook to manage server response states and wrap mutation triggers in `useTransition` to keep the UI responsive.
+
+#### 3. Performance & SEO Optimizations
+- **Image Optimization:** Never use raw `<img>` tags. Use `next/image`'s `<Image />` with appropriate `sizes` attributes, and set `priority` for above-the-fold images.
+- **Navigation:** Use `<Link />` from `next/link` to enable background pre-fetching when links enter the viewport.
+- **Dynamic Metadata:** Export a `generateMetadata` function in dynamic routes to optimize search engine crawling.

package/templates/next-js/rules/data-fetching-mutations.md

@@ -0,0 +1,36 @@
+# Data Fetching & Mutations
+
+This document defines standard conventions for calling APIs, managing caching, and performing data mutations using Next.js Server Actions.
+
+---
+
+## 🔌 Data Fetching at the Source
+- **Execute inside RSCs:** Call `fetch()` directly inside async Server Components (`RSC`). This secures API endpoints, protects authentication tokens, and minimizes network latency by co-locating fetching and rendering.
+- **Rule:** Do not use client-side fetch wrappers inside server pages. Use standard async/await syntax.
+
+---
+
+## 💾 Caching & Revalidation
+- **No Raw Fetch:** Using raw `fetch()` without specifying caching or revalidation strategies is prohibited.
+  
+  * **Invalid (❌ Prohibited):**
+    ```typescript
+    // Fetches static data indefinitely without any revalidation strategy
+    const res = await fetch('https://api.skillverse.vn/v1/courses');
+    ```
+  * **Valid (✔️ Recommended):**
+    ```typescript
+    // Configure ISR (Incremental Static Regeneration) with an explicit cache tag
+    const res = await fetch('https://api.skillverse.vn/v1/courses', { 
+      next: { revalidate: 3600, tags: ['courses'] } 
+    });
+    ```
+- **Cache Refreshing:** Call `revalidatePath` or `revalidateTag` inside Server Actions to purge stale cache entries and force Next.js to pull fresh data.
+
+---
+
+## ⚡ Mutations via Server Actions
+- **Use Server Actions:** All POST, PUT, DELETE, and PATCH mutations must be processed through Server Actions marked with the `"use server"` directive at the top of the function or file.
+- **Fluid User Experience:**
+  - Use the `useActionState` (or `useFormState` in React versions prior to 19) hook to manage server response states and track the `isPending` state.
+  - Wrap mutation executions inside `useTransition` to keep the user interface responsive and prevent freezing during background mutations.

package/templates/next-js/rules/next-style.md

@@ -0,0 +1,32 @@
+# Next.js Naming Conventions & Coding Style
+
+This document defines conventions for directory structures, naming patterns, imports, and feature organization inside Next.js App Router projects.
+
+---
+
+## 🏷️ Naming Conventions
+
+| Element | Naming Convention | Example |
+| :--- | :--- | :--- |
+| **Route Folders (`app/`)** | lowercase or kebab-case | `app/dashboard/`, `app/user-profile/` |
+| **Route Groups** | Wrapped in parentheses `(group-name)` | `app/(auth)/login/`, `app/(dashboard)/layout.tsx` |
+| **Dynamic Routes** | Wrapped in brackets `[paramName]` | `app/blog/[id]/page.tsx`, `app/shop/[...slug]/page.tsx` |
+| **Special Routing Files** | Next.js standard filenames (lowercase) | `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx` |
+| **Route Handlers** | Next.js API endpoint filenames | `route.ts` |
+| **UI Components** | PascalCase.tsx | `Button.tsx`, `ProductCard.tsx`, `SidebarSkeleton.tsx` |
+| **Custom Hooks** | camelCase starting with the `use` prefix | `useAuth.ts`, `useLocalStorage.ts` |
+
+---
+
+## 📦 Imports & Aliasing
+- **Absolute Imports:** Always use absolute imports with the `@/` alias pointing to the root or `src/` directory (e.g., `import { Button } from "@/components/ui/Button"`). Do not use relative imports with deep directory nesting (e.g., `../../../../Button`).
+- **CSS / Styles Imports:** Import global styles only in the root `layout.tsx` file (e.g., via `globals.css` or `index.css`). Do not import raw CSS files inside individual components.
+
+---
+
+## 📁 Directory Organization
+- Keep directories within the `app/` folder focused strictly on routing and layout definitions.
+- Locate business components, custom hooks, services, and types inside `src/features/` or `src/components/` outside the `app/` folder. Every feature (e.g., `billing`) should encapsulate its related resources:
+  - `src/features/billing/components/BillingForm.tsx`
+  - `src/features/billing/hooks/useBilling.ts`
+- Expose the public API of each feature via a clean entrypoint file: `index.ts`.

package/templates/next-js/rules/seo-metadata.md

@@ -0,0 +1,50 @@
+# SEO Optimization & Semantic HTML
+
+This document specifies conventions for using HTML5 Semantic tags, optimizing image delivery, and integrating Next.js Metadata APIs to achieve high SEO performance.
+
+---
+
+## 🔍 Next.js Metadata API
+- **Static Metadata:** Declare a static `metadata` object in layouts or pages that do not require dynamic route parameters:
+  ```typescript
+  export const metadata = {
+    title: 'Dashboard | Skillverse Platform',
+    description: 'Course management overview dashboard',
+  };
+  ```
+- **Dynamic Metadata:** For dynamic routes (e.g., article details, course views), define metadata through the exported `generateMetadata` function to optimize search engine indexing:
+  
+  ```typescript
+  import { Metadata } from 'next';
+
+  type Props = { params: Promise<{ id: string }> };
+
+  export async function generateMetadata({ params }: Props): Promise<Metadata> {
+    const id = (await params).id;
+    const course = await getCourseDetail(id);
+    
+    return {
+      title: `${course.title} | Skillverse Platform`,
+      description: course.shortDescription,
+      openGraph: { images: [course.thumbnailUrl] }
+    };
+  }
+  ```
+
+---
+
+## 🎨 Semantic HTML5 Structure
+- **Structural Tags:** Build layouts using semantic HTML5 tags instead of nesting generic `<div>` containers:
+  - `<header>`: Main navigation bar or header sections.
+  - `<nav>`: Primary navigation links.
+  - `<main>`: Wraps the unique primary content of the page.
+  - `<section>`: General thematic groupings of content.
+  - `<article>`: Independent self-contained items (e.g., blog posts, product cards).
+  - `<footer>`: Copyright and footer link sections.
+- **Header Hierarchy:** Follow a strict heading hierarchy (from `<h1>` down to `<h6>`). Ensure there is only one `<h1>` tag per page.
+
+---
+
+## ⚡ Image & Link Optimizations
+- **Image Optimization:** Never use raw `<img>` tags. Use Next.js `<Image />` from `next/image` with appropriate `sizes` attributes, and set `priority` for above-the-fold images.
+- **Navigation Optimization:** Use `<Link />` from `next/link` to automatically trigger resource pre-fetching when links enter the viewport, enabling instant transition.

package/templates/next-js/rules/server-client-components.md

@@ -0,0 +1,27 @@
+# React Server Components (RSC) vs React Client Components (RCC)
+
+This document establishes architectural boundaries and classification rules for components in Next.js App Router projects.
+
+---
+
+## 🏛️ React Server Components (RSC)
+- **Default Behavior:** All pages, layouts, and components created within the `app/` routing directory must default to React Server Components (RSC).
+- **RSC Benefits:**
+  - Fetch data directly using async/await syntax at the server level.
+  - Securely utilize server-side libraries and APIs (e.g., database queries, file reading, private tokens).
+  - Decrease client-side bundle sizes because RSC code remains on the server and is not sent to the browser.
+- **Rules:**
+  - Perform all data fetching and layout structure setups within RSCs.
+  - Never add the `"use client"` directive to layout or page entrypoint files unless absolutely necessary.
+
+---
+
+## 💻 React Client Components (RCC)
+- **Definition:** Components that execute on the browser to support dynamic user interactions and state updates.
+- **Identifying RCCs:** Attach the `"use client"` directive only at leaf component levels when they:
+  - Use React hooks (`useState`, `useReducer`, `useEffect`, `useLayoutEffect`).
+  - Use browser-specific APIs (e.g., `window`, `localStorage`, custom viewport hooks).
+  - Bind DOM event listeners (e.g., `onClick`, `onChange`, `onSubmit`).
+- **RCC Isolation Guidelines:**
+  - Keep RCCs at the absolute leaf level of the rendering tree to optimize loading speed.
+  - *Example:* If a product list page (RSC) includes a search input (RCC), encapsulate the search input in its own component (e.g., `<SearchBar />` marked with `"use client"`) and import it into the server-rendered parent page.

package/templates/next-js/skills/next-feature/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: next-feature
+description: Generate or extend a new Next.js + TypeScript page or route handler with caching and metadata
+---
+
+Follow this process to generate a new page, layout, or API route handler in Next.js.
+
+Inputs:
+- featureName: Name of the route or page (e.g., `dashboard`)
+- targetPath: The directory inside the `app/` folder to implement the route
+- userFlow: Brief description of the page behavior and layout
+
+Steps:
+1. Scan neighboring directories in the `app/` folder to check for shared layouts and error boundaries (`error.tsx`).
+2. Set up the route directory structure according to Next.js standards (e.g., `app/(dashboard)/billing`).
+3. Declare TypeScript interfaces for route parameters and query parameters.
+4. Implement the page or layout structure as a **React Server Component (RSC)**.
+5. If user interaction or form handling is needed, isolate it in a leaf Client Component (RCC) marked with `"use client"` and import it into the parent RSC.
+6. Configure explicit caching parameters for all data fetching `fetch()` calls.
+7. Set up static or dynamic SEO metadata using the `generateMetadata` function.
+8. Define a local error handler file (`error.tsx`) in the route directory to catch runtime exceptions.
+9. Execute local validation:
+   - `{{runCommand}} lint`
+   - `{{runCommand}} typecheck`
+   - `{{runCommand}} test`
+   - `{{runCommand}} build`

package/templates/react-ts/AGENTS.md.hbs

@@ -1,47 +1,124 @@
 ## React + TypeScript Guidelines
 
-### Architecture & Feature Conventions
-Use a feature-first structure. Keep route wiring thin, and place feature UI, hooks, data clients, and types together:
+### 🔄 End-to-End Agent Development Lifecycle
+AI Agents must execute all React + TypeScript tasks following this structured 5-stage lifecycle:
+1. **Design & Code:** Implement components and logic following the guidelines below. Keep logic inside Custom Hooks.
+2. **Comprehensive Testing:** Write component tests using React Testing Library and hook tests for complex behavior.
+3. **Code Quality & Validation:** Perform self-review and execute dynamic linter, type checks, and tests:
+   - Linting check: `{{runCommand}} lint`
+   - Type checking: `{{runCommand}} typecheck`
+   - Unit tests: `{{runCommand}} test` (or `{{runCommand}} test -- --run` in CI/CD)
+   - Production build: `{{runCommand}} build`
+4. **Dependency Management:** Install new packages using `{{packageManager}} add [package_name]` (or `npm install [package_name]` if using npm). Never manually modify the lock file `{{lockFile}}`.
+
+---
+
+### 🏗️ Architecture & Feature Conventions
+Use a strict **feature-first** modular packaging layout. Keep routing modules thin, and place feature UI, custom hooks, services, types, and tests together within the feature module:
 
 ```text
 src/
-  app/                  # App shell, router, providers
+  app/                  # App shell, router, context providers
   features/
     billing/
-      components/
+      components/       # Feature-specific components
         BillingPanel.tsx
-      hooks/
+      hooks/            # Feature-specific custom hooks (queries, state)
         useBilling.ts
-      services/
+      services/         # API clients and data transformers
         billingClient.ts
-      types.ts
-      index.ts
-  shared/
+      types/            # Feature type definitions
+        billing.ts
+      __tests__/        # Component and hook unit tests
+        BillingPanel.test.tsx
+      index.ts          # Public API for this feature
+  shared/               # Core shared assets, hooks, components, utils
     components/
     hooks/
     utils/
 ```
 
-### Component, Hook, and State Rules
-- Components render UI and delegate fetching, subscriptions, timers, and other side effects to custom hooks.
-- Custom hooks own reusable stateful logic and must start with `use`.
-- Prefer local component state for isolated interactions.
-- Use Context API for low-frequency cross-tree state such as theme, auth session, or app configuration.
-- Use Zustand only for shared state with frequent updates or cross-feature coordination.
-- Keep feature state close to the feature before moving it to `shared/`.
-
-### TypeScript Standards
-- Use strict TypeScript. Avoid `any`; prefer explicit domain types and discriminated unions.
-- Define feature-local interfaces and types near the code that owns them.
-- Export from feature `index.ts` files only when another module needs the API.
-- Use absolute imports from `@/`; do not add deep relative imports like `../../`.
-
-### Testing & Verification
-Before completing a React + TypeScript change, run the project validation pipeline:
-
-```bash
-npm run lint
-npm run typecheck
-npm run test -- --run
-npm run build
-```
+---
+
+### 🎨 Aesthetics, Styling & Premium UI
+The UI must feel premium, modern, and cohesive.
+- **Strict Tailwind CSS usage**: Never write inline custom CSS. Build the interface entirely using Tailwind Utility Classes.
+- **Dynamic Classes helper**: Never use string interpolation to join dynamic classNames. Always use the `cn()` helper (combining `clsx` and `tailwind-merge`):
+  ```typescript
+  // src/utils/cn.ts
+  import { ClassValue, clsx } from "clsx";
+  import { twMerge } from "tailwind-merge";
+
+  export function cn(...inputs: ClassValue[]) {
+    return twMerge(clsx(inputs));
+  }
+  ```
+  Usage:
+  `className={cn("px-4 py-2 text-white transition-all", isActive ? "bg-blue-500" : "bg-gray-500", customClass)}`
+- **Mobile-First Design**: Design layouts for mobile by default. Use breakpoints (`sm:`, `md:`, `lg:`, `xl:`) only to add or modify responsive styles as viewport size increases.
+- **Micro-animations & Motion**: Use `framer-motion` (or equivalent core transition library) for physical state changes:
+  - Transition duration should be short (between `0.2s` and `0.3s`).
+  - Use natural easing curves (`easeOut`, `easeInOut`) or spring physics for buttons/modals.
+  - Wrap conditional components in `<AnimatePresence>` to execute smooth exit animations.
+
+---
+
+### 🌐 Asynchronous Server-State & API Call Conventions
+- **No raw useEffect Fetching**: Never fetch data using raw `useEffect` blocks.
+- **Centralized API Client**: Route all outgoing requests through a unified client instance (e.g. `src/lib/api-client.ts`) that manages baseURL, interceptors, auth token inclusion, and global error mappings.
+- **Asynchronous Server-State**: Manage all server state using **TanStack Query (React Query)** or **SWR**.
+- **Separation of Concerns**: UI components must only call custom query hooks and render UI based on three states (`isLoading`, `isError`, and `data`). All fetching, caching, and mutation logic must be kept inside custom hooks:
+  ```typescript
+  // src/features/roadmap/api/use-roadmap.ts
+  import { useQuery } from "@tanstack/react-query";
+  import { apiClient } from "@/lib/api-client";
+
+  export const useRoadmap = (roadmapId: string) => {
+    return useQuery({
+      queryKey: ["roadmaps", roadmapId],
+      queryFn: async () => {
+        const response = await apiClient.get(`/roadmaps/${roadmapId}`);
+        return response.data;
+      },
+      staleTime: 5 * 60 * 1000,
+      gcTime: 10 * 60 * 1000,
+    });
+  };
+  ```
+
+---
+
+### 📝 Forms & Schema Validation
+Forms must remain performant and prevent rendering bottleneck.
+- **React Hook Form**: Manage form states with React Hook Form to isolate re-rendering and ensure smooth typing.
+- **Controller integration**: For complex third-party elements (Rich Text Editors, selectors, etc.), wrap them in the RHF `<Controller>` component.
+- **Schema-Driven Validation**: Avoid raw if/else statements for input validation. Use **Zod** to declare data schemas and automatically resolve validator rules:
+  ```typescript
+  import { useForm } from "react-hook-form";
+  import { zodResolver } from "@hookform/resolvers/zod";
+  import * as z from "zod";
+
+  const loginSchema = z.object({
+    email: z.string().min(1, "Email cannot be empty").email("Invalid email format"),
+    password: z.string().min(8, "Password must contain at least 8 characters"),
+  });
+  ```
+
+---
+
+### ⚡ Routing & Code Splitting
+Optimizing bundle loading performance is mandatory.
+- **Code Splitting**: Do not statically import Page Components. Use `React.lazy()` to segment routes into separate chunks loaded only when the route is visited.
+- **Premium Loading**: Wrap all lazy-loaded route elements inside a `<Suspense>` boundary containing a premium Shimmer Skeleton loader or spinner.
+- **Centralized Data Routers**: Configure routes using `createBrowserRouter` (React Router v6+) instead of JSX tags.
+- **Loaders & Actions**: Fetch data parallel to route transitions using router Loaders, and manage data mutations via router Actions.
+- **Route Error Boundaries**: Specify an `errorElement` on all primary route branches to isolate crashes and show a dedicated recovery panel instead of freezing the entire application.
+
+---
+
+### 🔍 SEO & Accessibility (a11y)
+- **Dynamic SEO Metadata**: Update document metadata (`title`, `description`, Open Graph tags) on route changes using `react-helmet-async`.
+- **Semantic HTML5 Structure**: Restructure elements using semantic tags: `<header>`, `<nav>`, `<main>`, `<section>`, `<article>`, `<footer>`. Ensure heading tags (`<h1>` to `<h6>`) follow logical hierarchy.
+- **Accessible Images**: All `<img>` tags must possess an `alt` attribute. Provide descriptive alt text for informative images; write `alt=""` for purely decorative images so screen readers skip them.
+- **Icon-Only Controls**: Buttons or links containing only SVG icons (e.g. close buttons, like buttons) must have an explicit `aria-label` or `aria-labelledby` attribute.
+- **Visual Keyboard Focus**: Do not disable the browser focus outline without adding a custom indicator. Interactable elements must display a distinct ring when navigated via keyboard (`:focus-visible`, e.g. `focus-visible:ring-2 focus-visible:ring-primary focus-visible:outline-none`).