agent-workflow-kit-cli 1.3.2 → 1.3.3

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

@@ -1,27 +1,27 @@
 # React Server Components (RSC) vs React Client Components (RCC)
 
-Tài liệu này quy định ranh giới kiến trúc và quy tắc phân loại component trong ứng dụng Next.js sử dụng App Router.
+This document establishes architectural boundaries and classification rules for components in Next.js App Router projects.
 
 ---
 
 ## 🏛️ React Server Components (RSC)
-- **Mặc định:** Tất cả các page, layout và component được tạo bên trong thư mục routing `app/` mặc định phải là React Server Components (RSC).
-- **Lợi ích của RSC:**
-  - Gọi dữ liệu (data fetching) trực tiếp sử dụng async/await.
-  - Sử dụng an toàn các thư viện phía server (truy vấn DB, đọc file, import khóa bảo mật).
-  - Giảm dung lượng bundle size gửi xuống client do mã nguồn RSC chỉ biên dịch và chạy trên server.
-- **Quy tắc:**
-  - Thực hiện toàn bộ việc nạp dữ liệu và cấu trúc khung trang bên trong các RSC.
-  - Không thêm `"use client"` vào các layout hoặc page entry points trừ khi bắt buộc.
+- **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)
-- **Định nghĩa:** Các component chạy trên trình duyệt để hỗ trợ tương tác và cập nhật trạng thái động từ người dùng.
-- **Dấu hiệu nhận biết RCC:** Chỉ gắn directive `"use client"` ở lớp component lá (Leaf Components) khi component:
-  - Sử dụng các Hook vòng đời và trạng thái của React (`useState`, `useReducer`, `useEffect`, `useLayoutEffect`).
-  - Gọi các API đặc trưng của trình duyệt (`window`, `localStorage`, custom viewport hooks).
-  - Đăng ký các callback lắng nghe sự kiện DOM (như `onClick`, `onChange`, `onSubmit`).
-- **Phân tách ranh giới RCC:**
-  - Giữ RCC ở cấp lá (Leaf Components) cuối cùng của cây dựng hình để tối ưu hiệu năng.
-  - *Ví dụ:* Nếu trang danh sách sản phẩm (RSC) có thanh tìm kiếm (RCC), hãy tách thanh tìm kiếm thành một component riêng (`<SearchBar />` có `"use client"`) và import vào trang cha chạy ở phía server.
+- **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

@@ -1,25 +1,25 @@
 ---
 name: next-feature
-description: Sinh hoặc mở rộng một page hoặc route handler Next.js + TypeScript mới kèm caching và metadata
+description: Generate or extend a new Next.js + TypeScript page or route handler with caching and metadata
 ---
 
-Tuân thủ quy trình này để tạo một page, layout hoặc API route handler mới trong Next.js.
+Follow this process to generate a new page, layout, or API route handler in Next.js.
 
-Đầu vào (Inputs):
-- featureName: Tên của route hoặc trang (ví dụ: `dashboard`)
-- targetPath: Thư mục chứa route bên trong `app/` để triển khai
-- userFlow: Mô tả tóm tắt hành vi và bố cục giao diện của trang
+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
 
-Các bước thực hiện (Steps):
-1. Quét các thư mục lân cận trong `app/` để tham chiếu các layout chung và ranh giới xử lý lỗi (`error.tsx`).
-2. Thiết lập cấu trúc thư mục route theo chuẩn Next.js (ví dụ: `app/(dashboard)/billing`).
-3. Khai báo interface cho route params và query parameters.
-4. Triển khai cấu trúc trang hoặc layout dưới dạng **React Server Component (RSC)**.
-5. Nếu có tương tác người dùng hoặc form, hãy tách thành các component con cấp lá (RCC) được đánh dấu `"use client"` rồi import vào RSC.
-6. Thiết lập cơ chế cache rõ ràng cho toàn bộ các thao tác gọi dữ liệu `fetch()`.
-7. Cấu hình metadata tĩnh hoặc động thông qua hàm `generateMetadata`.
-8. Định nghĩa file xử lý lỗi cục bộ (`error.tsx`) tại thư mục route gần nhất để bắt lỗi runtime.
-9. Thực hiện kiểm tra lỗi cục bộ:
+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`

package/templates/rust/AGENTS.md.hbs

@@ -0,0 +1,34 @@
+## 🗺️ Rust Development Guide
+
+### 🔄 Agent Development Lifecycle
+The AI Agent must execute all Rust tasks following this 4-step workflow:
+1. **Design & Implementation:** Implement business logic adhering to Rust conventions. Enforce structural separation: `main.rs` (for binary application setup) and `lib.rs` (for core business logic that can be reused and tested).
+2. **Comprehensive Testing:** Write unit tests inside internal test modules and integration tests in the `/tests` directory. Run tests with: `cargo test`.
+3. **Code Quality & Linting:** Run check tools regularly to ensure a warning-free state:
+   - Formatting: `cargo fmt`
+   - Linting: `cargo clippy --all-targets -- -D warnings`
+   - Build Validation: `cargo build`
+4. **Dependency Management:** Add external libraries using `cargo add [library_name]`. Never manually edit the `Cargo.lock` file.
+
+---
+
+### 🏗️ Template Blueprint
+Refer to the detailed rules below:
+- Idiomatic Rust, clippy lints, and cloning optimizations: `@rust-style.md`
+- Crate modules, Cargo Workspaces, and Trait-based Dependency Injection: `@project-layout.md`
+- Failures management, Result/Option, `thiserror`, and `anyhow`: `@error-handling.md`
+- Lifetimes `'a`, Smart Pointers, and async Tokio safety: `@memory-concurrency.md`
+
+---
+
+### 🏛️ Strict Development Rules
+
+#### 1. Ownership & Borrowing
+- **Avoid Over-Cloning:** Call `.clone()` on Heap types only when you must own an independent copy. Otherwise, design functions to receive read references `&T` or write references `&mut T`.
+- **Exclusive Mutable Borrow:** Ensure only one mutable reference `&mut T` exists at a time, and never let it coexist with any read references `&T` in the same scope.
+
+#### 2. Safe Error Handling
+- **No Unwraps:** Never use `.unwrap()` or `.expect()` in production code (except in tests). Propagate errors using `Result<T, E>` or `Option<T>` to ensure system reliability.
+
+#### 3. Async Concurrency (Tokio)
+- **CPU-Bound Tasks:** Never run heavy CPU operations (e.g., encryption, intensive loops) directly inside async contexts. Offload them using `tokio::task::spawn_blocking`.

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

@@ -0,0 +1,36 @@
+# Error Handling & Fault Control in Rust
+
+This document defines strict rules for handling, wrapping, and propagating failures using idiomatic Rust patterns.
+
+---
+
+## 🚫 Avoid Panics in Production
+- **Strict Rule:** Never use `panic!`, `.unwrap()`, or `.expect()` in production application code. Doing so triggers process termination, resulting in service interruption.
+- **Exceptions:** Only use panics in:
+  - Unit and Integration Tests.
+  - Initial bootstrapping (e.g., parsing critical files at startup) when missing items make recovery impossible.
+  - Invariants where the logic guarantees a failure is impossible.
+
+---
+
+## 🔄 Result Propagation with the `?` Operator
+- All fallible business logic operations must return `Result<T, E>` or `Option<T>`.
+- Use the `?` operator to propagate errors up the call stack, maintaining a clean syntax.
+
+---
+
+## 📚 Error Libraries: `thiserror` vs `anyhow`
+Never mix these libraries arbitrarily. Comply with the following separation:
+- **Use `thiserror` for Library Crates / Domain Modules:** Creates strongly-typed, detailed error definitions with custom display messages.
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum DatabaseError {
+    #[error("User not found with ID {0}")]
+    UserNotFound(i64),
+    #[error("Database connection failure: {0}")]
+    ConnectionFailed(String),
+}
+```
+- **Use `anyhow` for Application Entrypoints (API Gateway / CLI main):** Ideal for general error grouping and stack propagation without complex type mapping.

package/templates/rust/rules/memory-concurrency.md

@@ -0,0 +1,47 @@
+# Memory Management & Concurrency in Rust
+
+This document details conventions for lifetimes, smart pointer usage, and async Tokio runtime operations.
+
+---
+
+## ⏳ Lifetime Annotations ('a)
+- When a struct or function references a borrowing context, annotate lifetimes explicitly to guarantee spatial memory safety:
+```rust
+pub struct TokenValidator<'a> {
+    pub secret_key: &'a str,
+}
+```
+- Avoid bypassing the borrow checker with unnecessary `.clone()` calls or `'static` lifetime modifiers if the scope can be expressed with valid lifetime relationships.
+
+---
+
+## 🧠 Smart Pointer Matrix
+Select the correct smart pointer types according to the allocation scope:
+
+| Smart Pointer | Environment | Memory Allocation Characteristics | Application Use Case |
+| :--- | :--- | :--- | :--- |
+| **`Box<T>`** | Single / Multi-thread | Allocates large types on the Heap | Flattens recursive data structures (Sized types) |
+| **`Rc<T>`** | Single-thread Only | Reference count without thread safety | Shares immutable data across a single-threaded runtime |
+| **`Arc<T>`** | Multi-thread | Thread-safe Reference Count (Atomic) | Shares immutable resources across thread pools (e.g., Web Server) |
+| **`RefCell<T>`** | Single-thread Only | Interior Mutability (Checked at Runtime) | Mutates fields inside an immutable single-threaded struct |
+| **`Mutex<T>`** | Multi-thread | Thread safety via OS or runtime lock | Protects mutable resources shared across multiple threads |
+
+---
+
+## 🚦 Async Runtime (Tokio) CPU vs I/O Bound Tasks
+Blocking the executor threads in an async environment will starve the thread pool, degrading throughput.
+- **I/O Bound Tasks:** (DB Queries, Async file read/write, HTTP calls). Use standard `async/await` syntax.
+- **CPU Bound Tasks:** (Password hashing, image processing, complex computations). Never run these directly in the async thread pool. Use `tokio::task::spawn_blocking`:
+```rust
+let hashed_password = tokio::task::spawn_blocking(move || {
+    bcrypt::hash(password, bcrypt::DEFAULT_COST)
+})
+.await
+.unwrap()?;
+```
+
+---
+
+## 🔒 Send + Sync Traits & MutexGuard Safety
+- Shared items sent across task boundaries (`tokio::spawn`) must implement `Send` and `Sync`.
+- **MutexGuard across Await:** Never hold a non-thread-safe guard (like `std::sync::MutexGuard`) across `.await` points. Doing so will lead to compilation errors or runtime deadlocks. If a lock must span an await point, use `tokio::sync::Mutex`.

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

@@ -0,0 +1,49 @@
+# Rust Crate Layout & Modular Architecture
+
+This document defines module structures, visibility scopes, Cargo Workspace configurations, and dependency injection in Rust.
+
+---
+
+## 🏗️ Modules & Crate Separation
+- **Separating Binary & Library:**
+  - `src/main.rs`: Entrypoint of the binary application. Responsible only for parsing arguments, reading configuration, and starting the runtime.
+  - `src/lib.rs`: Holds 100% of the core business logic, enabling testability and decoupling.
+- **Visibility Scope Control:** Do not expose symbols using `pub` indiscriminately. Prefer `pub(crate)` to limit access to within the same crate, maintaining strict encapsulation.
+
+---
+
+## 📦 Cargo Workspaces (Multi-Crate Monorepos)
+For large monorepo systems, split the project into a Cargo Workspace containing isolated crates to enable parallel compilation:
+```toml
+# Cargo.toml at the root directory
+[workspace]
+members = [
+    "crates/api-gateway",
+    "crates/user-domain",
+    "crates/core-engine",
+    "crates/shared-utils"
+]
+```
+
+---
+
+## 💉 Trait-Based Dependency Injection (DI)
+Due to Rust's strict lifetimes and borrow checker, decouple dependencies by implementing **Traits** combined with thread-safe smart pointers: `Arc<dyn Trait + Send + Sync>`.
+```rust
+use std::sync::Arc;
+
+pub trait UserRepository: Send + Sync {
+    fn find_by_id(&self, id: i64) -> Result<User, AppError>;
+}
+
+pub struct UserService {
+    // Thread-safe pointer to dynamic trait implementation
+    repo: Arc<dyn UserRepository>,
+}
+
+impl UserService {
+    pub fn new(repo: Arc<dyn UserRepository>) -> Self {
+        Self { repo }
+    }
+}
+```

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

@@ -0,0 +1,26 @@
+# Idiomatic Rust Style & Optimization
+
+This document outlines standard conventions for writing idiomatic Rust code, optimizing borrowing, and complying with Clippy.
+
+---
+
+## 🦀 Idiomatic Rust Conventions
+- **Pattern Matching:** Leverage Pattern Matching (`match`, `if let`, `let-else`) instead of deep nested `if/else` checks to handle control flow safely.
+- **Naming Conventions:**
+  - `snake_case` for functions, methods, variables, and modules.
+  - `PascalCase` for Structs, Enums, Traits, and Unions.
+  - `SCREAMING_SNAKE_CASE` for constants and statics.
+
+---
+
+## 🧠 Borrowing & Cloning Optimizations
+AI models often overuse `.clone()` to satisfy the Rust Borrow Checker, which degrades performance and negates Rust's zero-cost abstraction benefits.
+- **Minimize Cloning:** Use `.clone()` or `.to_string()` on Heap-allocated objects (e.g., `String`, `Vec`) only when you absolutely need independent ownership.
+- **Leverage References:** Pass read references `&T` or write references `&mut T`. For strings, prefer `&str` over `String` parameter types.
+- **Exclusive Write Access:** Restrict code to have only one active mutable reference `&mut T` in a given scope, with no concurrent immutable reference `&T`.
+
+---
+
+## 🛠️ Clippy Specifications
+- Code generated by the AI Agent must strictly follow all optimizations suggested by Clippy.
+- Run validation checks: `cargo clippy -- -D warnings` and guarantee **Zero Warnings** before submitting pull requests.