agent-workflow-kit-cli 1.3.1 → 1.3.3

package/templates/react-ts/rules/data-fetching.md

@@ -0,0 +1,45 @@
+# Asynchronous Server-State & API Call Rules
+
+This ruleset governs network communication, caching, server-state syncing, and component integration logic to guarantee high performance, security, and clean separation of concerns.
+
+---
+
+## 🚫 No Raw useEffect Fetching
+- **Forbidden**: Do not write raw `useEffect` blocks to fetch remote data inside UI components. Raw effects are prone to memory leaks, state sync race conditions, lack of cache validation, and component bloatedness.
+
+---
+
+## 🔌 Centralized API Client
+- **Single Instance**: Route all HTTP/HTTPS outgoing traffic through a unified API client instance (e.g. located at `src/lib/api-client.ts`).
+- **Responsibility**:
+  - Configure core variables (e.g. `baseURL`, `timeout`).
+  - Attach authorization tokens dynamically via request interceptors.
+  - Implement unified global error handling (e.g. intercepting `401 Unauthorized` for token refresh, `403 Forbidden`, `500 Server Error`).
+
+---
+
+## 🔄 Server-State Management
+- **Library Selection**: Use **TanStack Query (React Query)** or **SWR** to manage asynchronous server-state (fetching, caching, caching invalidation, background updates).
+- **Separation of Concerns**: UI components must never deal with query functions or endpoints. Components only request custom query hooks and render the layout based on:
+  - `isLoading`: displays placeholder/Skeleton UI.
+  - `isError`: displays recovery panel/notification.
+  - `data`: displays final UI.
+- **Hook Encapsulation**: Declare data fetching inside specialized feature-local 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, // consider data fresh for 5 minutes
+      gcTime: 10 * 60 * 1000,    // keep in cache for 10 minutes before garbage collection
+    });
+  };
+  ```

package/templates/react-ts/rules/forms-validation.md

@@ -0,0 +1,55 @@
+# Form Management & Schema Validation Rules
+
+This ruleset governs the design and implementation of input fields, submissions, validations, and custom component bindings inside React forms.
+
+---
+
+## ⚡ Form Performance (React Hook Form)
+- **High Performance**: Use **React Hook Form (RHF)** to handle form state through uncontrolled inputs. This isolates rendering, preventing expensive keypress lag or component bottlenecks on large forms.
+- **Controlled Integration**: For custom/third-party UI controls that cannot be controlled natively (such as Rich Text Editors, custom Select dropdowns, calendar selectors), wrap them within RHF's `<Controller>` component to synchronize state efficiently.
+
+---
+
+## 🛡️ Schema-Driven Validation (Zod)
+- **No manual checking**: Never use complex if/else blocks or custom validation scripts inside submit handlers to check forms.
+- **Zod Resolving**: Use **Zod** to declare form schemas. Bind them to React Hook Form using `zodResolver` to automatically map validator rules and throw clean, localized error messages:
+
+  ```tsx
+  // Example feature form implementation
+  import { useForm } from "react-hook-form";
+  import { zodResolver } from "@hookform/resolvers/zod";
+  import * as z from "zod";
+  import { cn } from "@/utils/cn";
+
+  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"),
+  });
+
+  type LoginFields = z.infer<typeof loginSchema>;
+
+  export const LoginForm = () => {
+    const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm<LoginFields>({
+      resolver: zodResolver(loginSchema),
+    });
+
+    const onSubmit = async (data: LoginFields) => {
+      // Execute authentication pipeline
+    };
+
+    return (
+      <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
+        <div>
+          <input 
+            {...register("email")} 
+            className={cn("border px-3 py-2 rounded", errors.email && "border-red-500")} 
+          />
+          {errors.email && <p className="text-red-500 text-sm mt-1">{errors.email.message}</p>}
+        </div>
+        <button type="submit" disabled={isSubmitting} className="px-4 py-2 bg-primary text-white rounded">
+          {isSubmitting ? "Processing..." : "Login"}
+        </button>
+      </form>
+    );
+  };
+  ```

package/templates/react-ts/rules/premium-ui.md

@@ -0,0 +1,45 @@
+# Aesthetics, Styling & Premium UI Rules
+
+This ruleset outlines strict requirements for styling, responsiveness, and micro-animations to ensure premium visual excellence and high UX fidelity.
+
+---
+
+## 🎨 Tailwind CSS Guidelines
+- **No inline custom CSS**: All interface elements must be constructed using Tailwind utility classes. Do not write inline custom CSS (e.g. style properties or stylesheet files containing static layouts) unless standard utility classes are insufficient.
+- **Dynamic Classes handling**: Never use string interpolation or string addition (e.g. `isActive ? 'bg-blue-500' : 'bg-gray-500'`) to concatenate dynamic class names. This causes CSS specificity issues and classes override failure.
+- **Helper cn() usage**: Always use the custom `cn()` helper utility that integrates `clsx` and `tailwind-merge` for combining dynamic class values:
+  
+  ```typescript
+  // src/utils/cn.ts
+  import { ClassValue, clsx } from "clsx";
+  import { twMerge } from "tailwind-merge";
+
+  export function cn(...inputs: ClassValue[]) {
+    return twMerge(clsx(inputs));
+  }
+  ```
+
+  * **Incorrect (❌ Forbidden)**:
+    ```tsx
+    <button className={`px-4 py-2 text-white ${isActive ? 'bg-blue-500' : 'bg-gray-500'} ${customClass}`}>
+    ```
+  * **Correct (✔️ Required)**:
+    ```tsx
+    <button className={cn("px-4 py-2 text-white transition-all", isActive ? "bg-blue-500" : "bg-gray-500", customClass)}>
+    ```
+
+---
+
+## 📱 Mobile-First Responsiveness
+- **Default Styles**: Apply classes for the smallest screen size (mobile viewport) by default.
+- **Breakpoint Overrides**: Use breakpoints (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`) to introduce or change styling parameters for larger viewports.
+- **Layout Checking**: Always verify flex direction (`flex-col` vs `flex-row`), grid layout templates (`grid-cols-1` vs `md:grid-cols-3`), padding, margin, and typography scales on both small and large viewports to avoid layout issues.
+
+---
+
+## ⚡ Micro-animations & Motion
+- **Libraries**: Use `framer-motion` (or the core `motion` package) for micro-animations and physical state changes.
+- **Natural Transitions**:
+  - Keep animations fast and responsive: transition duration must range between `0.2s` and `0.3s`.
+  - Use natural, fluid easing curves (like `easeOut` or `easeInOut`) or spring-based models for buttons, toggles, hover states, and modals.
+- **Unmounting Transitions**: When components unmount or disappear from the DOM, they must be wrapped within the `<AnimatePresence>` component to ensure exit animations complete smoothly without sudden visual disappearance.

package/templates/react-ts/rules/react-style.md

@@ -1,29 +1,41 @@
 # React + TypeScript Style Rules
 
-## Naming
-- Components: PascalCase (`Navbar.tsx`, `InstallSection.tsx`).
-- Custom hooks: camelCase starting with `use` (`useAuth.ts`).
-- Helpers & variables: camelCase (`formatCurrency`).
-- Types & interfaces: PascalCase (`ButtonProps`).
-
-## Imports
-- Use `@/` absolute alias paths. Avoid relative parent paths (`../../`).
-- Use `import type` for types.
-- Keep feature internals private; expose via `index.ts` only when needed.
-
-## React & JSX
-- Components must focus on UI/composition.
-- Move side effects (fetching, subscriptions, timers) to custom hooks.
-- Use shorthand for boolean props: `<Input disabled />`.
-- Handle async UI states: loading, error, empty, success.
-
-## State Management
-- Prefer local component state.
-- Use Context API for stable app-level state (auth, theme).
-- Use Zustand for frequent, cross-feature state updates.
-
-## Testing
-- Test user behavior via React Testing Library.
-- Test hooks with complex branching/cleanup.
-- Avoid snapshot testing unless output is small & stable.
+This ruleset outlines base conventions for React + TypeScript projects. Detail guidelines are split into specialized modules which the agent MUST follow:
+- Styling & Aesthetics: See `@premium-ui.md`
+- Data Fetching & Server-State: See `@data-fetching.md`
+- Form Handling & Zod Validation: See `@forms-validation.md`
+- Code Splitting & Routing: See `@routing-splitting.md`
+- SEO & Accessibility (a11y): See `@seo-accessibility.md`
 
+---
+
+## 🏷️ Naming Conventions
+- **Components**: PascalCase (e.g. `Navbar.tsx`, `InstallSection.tsx`).
+- **Custom hooks**: camelCase starting with `use` (e.g. `useAuth.ts`, `useCustomers.ts`).
+- **Helpers & variables**: camelCase (e.g. `formatCurrency`, `customerData`).
+- **Types & interfaces**: PascalCase (e.g. `ButtonProps`, `CustomerData`).
+- **Routes**: `<name>.route.tsx` (e.g. `customers.route.tsx`).
+- **Feature Folders**: kebab-case or lowercase (e.g. `billing`, `user-profile`).
+
+---
+
+## 📦 Imports
+- **Absolute imports**: Always use absolute alias paths starting with `@/` (e.g. `import { Button } from "@/shared/components"`). Avoid deep relative parent imports (e.g. `../../components`).
+- **Type imports**: Always use `import type` when importing types or interfaces to optimize bundle compilation.
+- **Encapsulation**: Keep feature-internal files private. Only export public features via the module `index.ts`.
+
+---
+
+## ⚙️ React & JSX Guidelines
+- **UI Composition**: Components must focus solely on rendering UI/composition and delegating logic.
+- **Logic Delegation**: Keep side effects (fetching, subscriptions, timers, complex state transitions) inside custom hooks.
+- **Shorthand Props**: Prefer shorthand for boolean flags (e.g. `<Input disabled />` instead of `<Input disabled={true} />`).
+- **Async UI States**: Always explicitly handle async UI transitions (e.g. loading, error, empty, success).
+
+---
+
+## 💾 State Management
+- **Local State**: Prefer component-local state (`useState`, `useReducer`) for isolated UI interactions.
+- **Context API**: Use the Context API only for low-frequency global values (e.g. theme, locale, user session credentials).
+- **Zustand**: Use Zustand for frequent, cross-feature state updates or complex frontend state orchestration.
+- **Locality**: Keep state as close to the components consuming it as possible before lifting it up.

package/templates/react-ts/rules/routing-splitting.md

@@ -0,0 +1,21 @@
+# Code Splitting & Routing Rules
+
+This ruleset outlines expectations for structuring router declarations, loading performance optimization, and runtime boundary protections.
+
+---
+
+## ⚡ Code Splitting (Dynamic Imports)
+- **Dynamic Pages**: Do not statically import full page components at the top level of router files. This bundles the entire application code into a single file and degrades initial page load performance.
+- **Lazy Loading**: Use `React.lazy()` to import page components dynamically, dividing route destinations into separate bundles:
+  ```typescript
+  const DashboardPage = React.lazy(() => import("@/features/dashboard/components/DashboardPage"));
+  ```
+- **Fallback Suspension**: Wrap lazy-loaded components in a `<Suspense>` component. Provide a high-fidelity shimmer skeleton loader or loading indicator as the fallback property to maintain visual continuity.
+
+---
+
+## 🗺️ Centralized Routing Architecture (React Router v6+)
+- **Data Router**: Define routes as data configuration arrays using `createBrowserRouter` instead of JSX-based `<Routes>` declarations.
+- **Data Loaders**: Utilize router Loaders to pre-fetch required data in parallel with route navigation.
+- **Data Actions**: Utilize router Actions to handle data modification (mutations and forms submissions).
+- **Page Crash Isolation**: Define a dedicated `errorElement` on all primary parent route levels. When a page encounters a crash (e.g. invalid API response, parsing failure), the local `ErrorBoundary` will intercept the error and render a recovery screen without crashing the rest of the application.

package/templates/react-ts/rules/seo-accessibility.md

@@ -0,0 +1,34 @@
+# SEO & Accessibility (a11y) Rules
+
+This ruleset governs semantic document structures, title/meta tag updates, and accessibility integrations to ensure excellent indexing and keyboard/screen-reader compatibility.
+
+---
+
+## 🔍 SEO & Semantic HTML
+- **Dynamic SEO Metadata**: Update document headers dynamically (e.g. `document.title`, description tags, and Open Graph tags) on page transitions using `react-helmet-async` (or the routing framework's metadata controller).
+- **Semantic Structure**: Do not use `<div>` tags for all layouts. Utilize HTML5 semantic elements to establish logical document outline sections:
+  - `<header>`: Site or section navigation header.
+  - `<nav>`: Core navigation links.
+  - `<main>`: Singular primary content of the body.
+  - `<section>`: Generic thematic block.
+  - `<article>`: Self-contained composition (posts, articles, cards).
+  - `<footer>`: Copyright, contact, and structural footers.
+- **Heading Hierarchy**: Align heading tags (`<h1>` to `<h6>`) logically. Ensure there is only one `<h1>` per page, and header levels are nested sequentially.
+
+---
+
+## ♿ Accessibility (a11y) Standards
+- **Image alt attributes**:
+  - All `<img>` tags must have an `alt` attribute.
+  - Provide short, descriptive descriptions for informative images.
+  - For decorative images, write `alt=""` so that screen readers skip reading their filenames aloud.
+- **Icon-Only Controls**: Every button, link, or clickable component that wraps only an icon (e.g. SVG close button `X`, favorite button heart, menu hamburger icon) must include a descriptive `aria-label` or `aria-labelledby` attribute.
+- **Visual Keyboard Focus**: Do not strip or disable the browser's default blue focus rings without adding an alternative visual indicator. All interactive inputs, buttons, and links must display a prominent border ring when navigated via keyboard:
+  ```css
+  /* Example utility or class selector */
+  .focus-indicator:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 2px var(--color-primary-offset), 0 0 0 4px var(--color-primary);
+  }
+  ```
+  In Tailwind: `focus-visible:ring-2 focus-visible:ring-primary focus-visible:outline-none`.

package/templates/react-ts/skills/react-feature/SKILL.md

@@ -15,11 +15,11 @@ Steps:
 2. Define feature-local types first, including loading, error, empty, and success state shapes.
 3. Create or update the custom hook that owns fetching, side effects, derived state, and cleanup.
 4. Create or update PascalCase components that render UI and delegate logic to hooks.
-5. Add styles using the project's existing styling approach; do not introduce a new styling system.
+5. Add styles using Tailwind CSS utility classes and Framer Motion for micro-animations; do not write custom inline CSS.
 6. Wire the feature into the route or parent component through the smallest public API needed.
 7. Add tests for component behavior and hook logic when branching, async work, or cleanup is present.
 8. Run validations:
-   - `npm run lint`
-   - `npm run typecheck`
-   - `npm run test -- --run`
-   - `npm run build`
+   - `{{runCommand}} lint`
+   - `{{runCommand}} typecheck`
+   - `{{runCommand}} test`
+   - `{{runCommand}} build`

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.