devhive 0.1.23__tar.gz → 0.1.25__tar.gz

{devhive-0.1.23 → devhive-0.1.25}/MANIFEST.in

@@ -1,2 +1,4 @@
 recursive-include skills *
 recursive-include community_skills *
+recursive-include templates *
+

{devhive-0.1.23/devhive.egg-info → devhive-0.1.25}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: devhive
-Version: 0.1.23
+Version: 0.1.25
 Summary: CLI to manage DevHive skills and autonomous AI agents for OpenCode.
 Home-page: https://github.com/ramBlanco/devhive
 Author: ramBlanco
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
+Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click>=8.0.0
@@ -65,6 +65,12 @@ devhive install
 
 # Update your existing skills to the latest versions
 devhive update-skill
+
+# Initialize a modern Next.js/React frontend AI guidelines file in your current project
+devhive init-frontend
+
+# Initialize a Hexagonal Architecture backend AI guidelines file (Interactive Prompt)
+devhive init-backend
 ```
 
 ## Usage (The `@devhive` Agent)

{devhive-0.1.23 → devhive-0.1.25}/README.md

@@ -42,6 +42,12 @@ devhive install
 
 # Update your existing skills to the latest versions
 devhive update-skill
+
+# Initialize a modern Next.js/React frontend AI guidelines file in your current project
+devhive init-frontend
+
+# Initialize a Hexagonal Architecture backend AI guidelines file (Interactive Prompt)
+devhive init-backend
 ```
 
 ## Usage (The `@devhive` Agent)

{devhive-0.1.23 → devhive-0.1.25/devhive.egg-info}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: devhive
-Version: 0.1.23
+Version: 0.1.25
 Summary: CLI to manage DevHive skills and autonomous AI agents for OpenCode.
 Home-page: https://github.com/ramBlanco/devhive
 Author: ramBlanco
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
+Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click>=8.0.0
@@ -65,6 +65,12 @@ devhive install
 
 # Update your existing skills to the latest versions
 devhive update-skill
+
+# Initialize a modern Next.js/React frontend AI guidelines file in your current project
+devhive init-frontend
+
+# Initialize a Hexagonal Architecture backend AI guidelines file (Interactive Prompt)
+devhive init-backend
 ```
 
 ## Usage (The `@devhive` Agent)

{devhive-0.1.23 → devhive-0.1.25}/devhive.egg-info/SOURCES.txt

@@ -29,6 +29,7 @@ devhive.egg-info/requires.txt
 devhive.egg-info/top_level.txt
 devhive_cli/__init__.py
 devhive_cli/main.py
+devhive_cli/templates_backend.py
 skills/devhive_workflow.md
 skills/devhive_architect/SKILL.md
 skills/devhive_auditor/SKILL.md
@@ -45,4 +46,5 @@ skills/devhive_qa/SKILL.md
 skills/devhive_releaser/SKILL.md
 skills/devhive_sast/SKILL.md
 skills/devhive_taskplanner/SKILL.md
-skills/devhive_techwriter/SKILL.md
+skills/devhive_techwriter/SKILL.md
+templates/AGENTS.frontend.md

{devhive-0.1.23 → devhive-0.1.25}/devhive_cli/main.py

@@ -3,12 +3,14 @@ import shutil
 import subprocess
 from pathlib import Path
 import click
+from devhive_cli.templates_backend import generate_backend_agents_md
 
 # Paths configuration
 CLI_DIR = Path(__file__).resolve().parent
 ROOT_DIR = CLI_DIR.parent
 LOCAL_SKILLS_DIR = ROOT_DIR / "skills"
 COMMUNITY_SKILLS_DIR = ROOT_DIR / "community_skills"
+TEMPLATES_DIR = ROOT_DIR / "templates"
 TARGET_DIR = Path.home() / ".config" / "opencode" / "skills"
 
 @click.group()
@@ -75,5 +77,50 @@ def update_skill():
     install_remote_skills()
     click.secho("\nUpdate Complete! 🚀", fg="green", bold=True)
 
+@cli.command()
+def init_frontend():
+    """Initialize a modern frontend AGENTS.md template in the current directory."""
+    template_path = TEMPLATES_DIR / "AGENTS.frontend.md"
+    dest_path = Path.cwd() / "AGENTS.md"
+    
+    if not template_path.exists():
+        click.secho("Error: Frontend template not found in the devhive package.", fg="red")
+        return
+        
+    if dest_path.exists():
+        click.secho("AGENTS.md already exists in this directory. Aborting to prevent overwrite.", fg="yellow")
+        return
+        
+    shutil.copy2(template_path, dest_path)
+    click.secho("✅ Successfully created AGENTS.md with modern Next.js/React frontend guidelines!", fg="green", bold=True)
+
+@cli.command()
+def init_backend():
+    """Initialize a modern backend AGENTS.md template with Hexagonal Architecture."""
+    dest_path = Path.cwd() / "AGENTS.md"
+    
+    if dest_path.exists():
+        click.secho("AGENTS.md already exists in this directory. Aborting to prevent overwrite.", fg="yellow")
+        return
+
+    language = click.prompt("Which backend language?", type=click.Choice(['python', 'node']))
+    
+    use_di = False
+    if language == 'python':
+        framework = click.prompt("Which framework?", type=click.Choice(['fastapi', 'django', 'none']))
+    else:
+        framework = click.prompt("Which framework?", type=click.Choice(['express', 'nestjs', 'none']))
+        if framework != 'nestjs':
+            use_di = click.confirm("Do you want to use InversifyJS for Dependency Injection?")
+    
+    iac = click.prompt("Which IaC tool are you using?", type=click.Choice(['cdk', 'terraform', 'serverless']))
+    
+    md_content = generate_backend_agents_md(language, framework, iac, use_di)
+    
+    with open(dest_path, "w", encoding="utf-8") as f:
+        f.write(md_content)
+        
+    click.secho("✅ Successfully created AGENTS.md with Hexagonal Architecture guidelines!", fg="green", bold=True)
+
 if __name__ == "__main__":
     cli()

devhive-0.1.25/devhive_cli/templates_backend.py

@@ -0,0 +1,424 @@
+def generate_backend_agents_md(language: str, framework: str, iac: str, use_di: bool) -> str:
+    stack_list = []
+    if language == 'python':
+        stack_list.append("- **Language**: Python 3.10+ (Strict Type Hinting)")
+        if framework == 'fastapi':
+            stack_list.append("- **Framework**: FastAPI")
+        elif framework == 'django':
+            stack_list.append("- **Framework**: Django")
+        else:
+            stack_list.append("- **Framework**: None (Pure Python / Lambdas)")
+    else:
+        stack_list.append("- **Language**: Node.js + TypeScript (Strict Mode)")
+        if framework == 'express':
+            stack_list.append("- **Framework**: Express")
+        elif framework == 'nestjs':
+            stack_list.append("- **Framework**: NestJS (Built-in DI)")
+            use_di = False # NestJS has its own DI
+        else:
+            stack_list.append("- **Framework**: None (Pure Node.js / Lambdas)")
+        
+        if use_di:
+            stack_list.append("- **Dependency Injection**: InversifyJS")
+
+    if iac == 'cdk':
+        stack_list.append("- **Infrastructure as Code**: AWS CDK")
+    elif iac == 'terraform':
+        stack_list.append("- **Infrastructure as Code**: Terraform")
+    else:
+        stack_list.append("- **Infrastructure as Code**: Serverless Framework")
+
+    stack_section = "\n".join(stack_list)
+
+    # Base structure
+    md = f"""# Backend Architecture & AI Agent Guidelines
+
+This `AGENTS.md` (or `GUIDELINES.md`) file serves as the strict instruction manual for OpenCode and DevHive agents. It defines the technical stack, architectural patterns, and coding conventions for this backend project.
+
+## 🛠️ 1. Tech Stack
+{stack_section}
+
+## 🧠 2. OpenCode Skills to Load
+Agents **MUST** load the following specialized skills before executing tasks:
+- `architecture-patterns`: For maintaining clean separation of concerns and Hexagonal Architecture.
+- `backend-architect`: For scalable API design and domain modeling.
+- `backend-security-coder`: For secure coding practices, input validation, and auth.
+- `devhive-devops`: For {iac.upper()} infrastructure setup.
+
+## 📂 3. Project Structure (Hexagonal Architecture)
+For maximum scalability, testability, and maintainability, the project MUST strictly follow Hexagonal Architecture (Ports & Adapters).
+
+```text
+src/
+├── domain/             # ENTERPRISE BUSINESS RULES (No external dependencies)
+│   ├── entities/       # Pure domain models
+│   └── exceptions/     # Domain-specific errors
+├── application/        # APPLICATION BUSINESS RULES (Use Cases & Ports)
+│   ├── use_cases/      # Orchestrates domain logic
+│   └── ports/          # Interfaces for outbound communication (Repositories, External APIs)
+├── infrastructure/     # ADAPTERS (Database, External Services, Third-party libs)
+│   ├── database/       # Concrete implementation of repository ports
+│   └── di/             # Dependency Injection container/setup
+└── presentation/       # ENTRY POINTS (Controllers, REST APIs, GraphQL, Lambdas)
+    └── controllers/    # Parses HTTP requests and calls use cases
+
+infrastructure/         # IaC DEFINITIONS (Outside src/)
+└── # {iac.upper()} configurations
+```
+
+## 📐 4. Architectural Rules & Clean Code (CRITICAL)
+
+1. **The Dependency Rule**: Source code dependencies MUST only point inward, toward the `domain/`. 
+   - `domain/` knows nothing about anything else.
+   - `application/` depends only on `domain/`.
+   - `infrastructure/` and `presentation/` depend on `application/` and `domain/`.
+   - **Never import an infrastructure detail (like a DB model) into a use case.**
+
+2. **Ports and Adapters**:
+   - Outbound communication (like DB queries) MUST be defined as an interface (Port) in the `application/` layer.
+   - The actual database logic MUST be implemented as an Adapter in the `infrastructure/` layer.
+
+3. **Dependency Injection**:
+   - Use Cases must receive their dependencies (Ports) via constructor injection.
+   - The Presentation layer resolves these dependencies and passes them to the Use Cases.
+"""
+
+    if language == 'node' and use_di:
+        md += """
+4. **InversifyJS Usage**:
+   - Decorate concrete adapters in `infrastructure/` with `@injectable()`.
+   - Bind interfaces to symbols in an `inversify.config.ts` container file.
+   - Use the container in the `presentation/` layer to resolve use cases.
+"""
+
+    md += "\n## 💻 5. Code Examples\n\n"
+
+    if language == 'python':
+        if framework == 'fastapi':
+            md += """### Example: FastAPI + Hexagonal Architecture
+
+**1. Port (Application Layer)**
+*File: `src/application/ports/user_repository.py`*
+```python
+from typing import Protocol
+from src.domain.entities.user import User
+
+class UserRepository(Protocol):
+    def get_by_id(self, user_id: str) -> User | None:
+        ...
+```
+
+**2. Adapter (Infrastructure Layer)**
+*File: `src/infrastructure/database/postgres_user_repository.py`*
+```python
+from src.application.ports.user_repository import UserRepository
+from src.domain.entities.user import User
+
+class PostgresUserRepository:
+    def __init__(self, db_session):
+        self.db = db_session
+
+    def get_by_id(self, user_id: str) -> User | None:
+        # DB logic here returning Domain Entity
+        return User(id=user_id, name="Alice")
+```
+
+**3. Use Case (Application Layer)**
+*File: `src/application/use_cases/get_user.py`*
+```python
+from src.application.ports.user_repository import UserRepository
+from src.domain.entities.user import User
+from src.domain.exceptions import UserNotFoundError
+
+class GetUserUseCase:
+    def __init__(self, user_repo: UserRepository):
+        self.user_repo = user_repo
+
+    def execute(self, user_id: str) -> User:
+        user = self.user_repo.get_by_id(user_id)
+        if not user:
+            raise UserNotFoundError(f"User {user_id} not found")
+        return user
+```
+
+**4. Controller (Presentation Layer)**
+*File: `src/presentation/controllers/user_controller.py`*
+```python
+from fastapi import APIRouter, Depends, HTTPException
+from src.application.use_cases.get_user import GetUserUseCase
+from src.infrastructure.database.postgres_user_repository import PostgresUserRepository
+from src.domain.exceptions import UserNotFoundError
+
+router = APIRouter()
+
+# Poor man's DI for FastAPI
+def get_user_use_case() -> GetUserUseCase:
+    repo = PostgresUserRepository(db_session=None)
+    return GetUserUseCase(user_repo=repo)
+
+@router.get("/users/{user_id}")
+def get_user(user_id: str, use_case: GetUserUseCase = Depends(get_user_use_case)):
+    try:
+        return use_case.execute(user_id)
+    except UserNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+```
+"""
+        elif framework == 'django':
+            md += """### Example: Django + Hexagonal Architecture
+
+**Note on Django**: Do NOT put business logic in Django Views or Models. Use Django ONLY as the `infrastructure/` and `presentation/` layers.
+
+**1. Port (Application Layer)**
+*File: `src/application/ports/user_repository.py`*
+```python
+import abc
+from src.domain.entities.user import User
+
+class UserRepository(abc.ABC):
+    @abc.abstractmethod
+    def get_by_id(self, user_id: str) -> User | None:
+        pass
+```
+
+**2. Adapter (Infrastructure Layer)**
+*File: `src/infrastructure/database/django_user_repository.py`*
+```python
+from src.application.ports.user_repository import UserRepository
+from src.domain.entities.user import User
+from myapp.models import DjangoUserModel # Django ORM Model
+
+class DjangoUserRepository(UserRepository):
+    def get_by_id(self, user_id: str) -> User | None:
+        try:
+            orm_user = DjangoUserModel.objects.get(id=user_id)
+            return User(id=str(orm_user.id), name=orm_user.name) # Map ORM to Domain
+        except DjangoUserModel.DoesNotExist:
+            return None
+```
+
+**3. Controller (Presentation Layer)**
+*File: `src/presentation/views/user_views.py`*
+```python
+from django.http import JsonResponse
+from src.application.use_cases.get_user import GetUserUseCase
+from src.infrastructure.database.django_user_repository import DjangoUserRepository
+from src.domain.exceptions import UserNotFoundError
+
+def get_user_view(request, user_id: str):
+    repo = DjangoUserRepository()
+    use_case = GetUserUseCase(user_repo=repo)
+    
+    try:
+        user = use_case.execute(user_id)
+        return JsonResponse({"id": user.id, "name": user.name})
+    except UserNotFoundError as e:
+        return JsonResponse({"error": str(e)}, status=404)
+```
+"""
+        else:
+            md += """### Example: Pure Python + Hexagonal Architecture
+
+**1. Port (Application Layer)**
+*File: `src/application/ports/user_repository.py`*
+```python
+from typing import Protocol
+from src.domain.entities.user import User
+
+class UserRepository(Protocol):
+    def get_by_id(self, user_id: str) -> User | None:
+        ...
+```
+
+**2. Use Case (Application Layer)**
+*File: `src/application/use_cases/get_user.py`*
+```python
+from src.application.ports.user_repository import UserRepository
+from src.domain.entities.user import User
+
+class GetUserUseCase:
+    def __init__(self, user_repo: UserRepository):
+        self.user_repo = user_repo
+
+    def execute(self, user_id: str) -> User:
+        return self.user_repo.get_by_id(user_id)
+```
+
+**3. Handler (Presentation Layer - Lambda)**
+*File: `src/presentation/handlers/user_handler.py`*
+```python
+from src.application.use_cases.get_user import GetUserUseCase
+from src.infrastructure.database.dynamo_user_repository import DynamoUserRepository
+
+# Initialize dependencies at the module level for Lambda cold starts
+repo = DynamoUserRepository()
+use_case = GetUserUseCase(user_repo=repo)
+
+def lambda_handler(event, context):
+    user_id = event.get('pathParameters', {}).get('userId')
+    user = use_case.execute(user_id)
+    return {"statusCode": 200, "body": user.to_json()}
+```
+"""
+    else: # Node.js
+        if use_di:
+            md += """### Example: Node.js + TypeScript + InversifyJS
+
+**1. Port (Application Layer)**
+*File: `src/application/ports/IUserRepository.ts`*
+```typescript
+import { User } from "../../domain/entities/User";
+
+export const TYPES = {
+    IUserRepository: Symbol.for("IUserRepository"),
+    GetUserUseCase: Symbol.for("GetUserUseCase"),
+};
+
+export interface IUserRepository {
+    getById(userId: string): Promise<User | null>;
+}
+```
+
+**2. Adapter (Infrastructure Layer)**
+*File: `src/infrastructure/database/PostgresUserRepository.ts`*
+```typescript
+import { injectable } from "inversify";
+import "reflect-metadata";
+import { IUserRepository } from "../../application/ports/IUserRepository";
+import { User } from "../../domain/entities/User";
+
+@injectable()
+export class PostgresUserRepository implements IUserRepository {
+    async getById(userId: string): Promise<User | null> {
+        // DB Logic returning Domain Entity
+        return new User(userId, "Alice");
+    }
+}
+```
+
+**3. Use Case (Application Layer)**
+*File: `src/application/useCases/GetUserUseCase.ts`*
+```typescript
+import { inject, injectable } from "inversify";
+import "reflect-metadata";
+import { IUserRepository, TYPES } from "../ports/IUserRepository";
+import { User } from "../../domain/entities/User";
+
+@injectable()
+export class GetUserUseCase {
+    constructor(
+        @inject(TYPES.IUserRepository) private userRepository: IUserRepository
+    ) {}
+
+    async execute(userId: string): Promise<User> {
+        const user = await this.userRepository.getById(userId);
+        if (!user) throw new Error("User not found");
+        return user;
+    }
+}
+```
+
+**4. DI Container Setup (Infrastructure Layer)**
+*File: `src/infrastructure/di/container.ts`*
+```typescript
+import { Container } from "inversify";
+import { TYPES, IUserRepository } from "../../application/ports/IUserRepository";
+import { PostgresUserRepository } from "../database/PostgresUserRepository";
+import { GetUserUseCase } from "../../application/useCases/GetUserUseCase";
+
+const container = new Container();
+
+container.bind<IUserRepository>(TYPES.IUserRepository).to(PostgresUserRepository);
+container.bind<GetUserUseCase>(TYPES.GetUserUseCase).to(GetUserUseCase);
+
+export { container };
+```
+
+**5. Controller (Presentation Layer)**
+*File: `src/presentation/controllers/UserController.ts`*
+```typescript
+import { Request, Response } from "express";
+import { container } from "../../infrastructure/di/container";
+import { TYPES } from "../../application/ports/IUserRepository";
+import { GetUserUseCase } from "../../application/useCases/GetUserUseCase";
+
+export class UserController {
+    async getUser(req: Request, res: Response) {
+        const useCase = container.get<GetUserUseCase>(TYPES.GetUserUseCase);
+        try {
+            const user = await useCase.execute(req.params.id);
+            res.json(user);
+        } catch (error) {
+            res.status(404).json({ error: error.message });
+        }
+    }
+}
+```
+"""
+        else:
+            md += """### Example: Node.js + TypeScript (Manual DI)
+
+**1. Port (Application Layer)**
+*File: `src/application/ports/IUserRepository.ts`*
+```typescript
+import { User } from "../../domain/entities/User";
+
+export interface IUserRepository {
+    getById(userId: string): Promise<User | null>;
+}
+```
+
+**2. Adapter (Infrastructure Layer)**
+*File: `src/infrastructure/database/PostgresUserRepository.ts`*
+```typescript
+import { IUserRepository } from "../../application/ports/IUserRepository";
+import { User } from "../../domain/entities/User";
+
+export class PostgresUserRepository implements IUserRepository {
+    async getById(userId: string): Promise<User | null> {
+        // DB Logic returning Domain Entity
+        return new User(userId, "Alice");
+    }
+}
+```
+
+**3. Use Case (Application Layer)**
+*File: `src/application/useCases/GetUserUseCase.ts`*
+```typescript
+import { IUserRepository } from "../ports/IUserRepository";
+import { User } from "../../domain/entities/User";
+
+export class GetUserUseCase {
+    constructor(private userRepository: IUserRepository) {}
+
+    async execute(userId: string): Promise<User> {
+        const user = await this.userRepository.getById(userId);
+        if (!user) throw new Error("User not found");
+        return user;
+    }
+}
+```
+
+**4. Controller (Presentation Layer)**
+*File: `src/presentation/controllers/UserController.ts`*
+```typescript
+import { Request, Response } from "express";
+import { GetUserUseCase } from "../../application/useCases/GetUserUseCase";
+import { PostgresUserRepository } from "../../infrastructure/database/PostgresUserRepository";
+
+export class UserController {
+    async getUser(req: Request, res: Response) {
+        const repo = new PostgresUserRepository();
+        const useCase = new GetUserUseCase(repo);
+        try {
+            const user = await useCase.execute(req.params.id);
+            res.json(user);
+        } catch (error) {
+            res.status(404).json({ error: error.message });
+        }
+    }
+}
+```
+"""
+
+    return md

{devhive-0.1.23 → devhive-0.1.25}/setup.py

@@ -8,7 +8,7 @@ with open(os.path.join(this_directory, 'README.md'), encoding='utf-8') as f:
 
 setup(
     name="devhive",
-    version="0.1.23",  # Bumping from the last deployed version 0.1.21
+    version="0.1.25",
     packages=find_packages(),
     include_package_data=True,
     install_requires=[
@@ -29,5 +29,5 @@ setup(
         "License :: OSI Approved :: MIT License",
         "Operating System :: OS Independent",
     ],
-    python_requires='>=3.8',
+    python_requires='>=3.7',
 )

devhive-0.1.25/templates/AGENTS.frontend.md

@@ -0,0 +1,160 @@
+# Frontend Architecture & AI Agent Guidelines
+
+This `AGENTS.md` (or `GUIDELINES.md`) file serves as the strict instruction manual for OpenCode and DevHive agents. It defines the technical stack, architectural patterns, and coding conventions for this frontend project.
+
+## 🛠️ 1. Tech Stack
+- **Framework**: Next.js 15 (App Router)
+- **Library**: React 19
+- **Language**: TypeScript (Strict Mode)
+- **Styling**: Tailwind CSS v3/v4 + `clsx` + `tailwind-merge`
+- **Components**: shadcn/ui (Radix UI primitives)
+- **Icons**: Lucide React
+- **Data Fetching**: React Server Components (RSC) & Server Actions
+
+## 🧠 2. OpenCode Skills to Load
+Agents **MUST** load the following specialized skills before executing tasks:
+- `frontend-developer`: For modern React 19 / Next.js 15 patterns.
+- `frontend-design`: For high-quality, non-generic UI aesthetics.
+- `shadcn`: For proper installation and composition of shadcn/ui components.
+- `theme-factory`: For applying cohesive color palettes and typography.
+- `architecture-patterns`: For maintaining clean separation of concerns.
+
+## 📂 3. Project Structure (Feature-Based Architecture)
+For maximum scalability and maintainability, the project follows a feature-based architecture within the `src/` directory. 
+
+```text
+src/
+├── app/                  # Next.js App Router (Pages, Layouts, API Routes)
+│   ├── (auth)/           # Route groups for logical separation
+│   ├── dashboard/        # Dashboard routes
+│   └── layout.tsx        # Root layout (Providers, Fonts, Metadata)
+├── components/           
+│   ├── ui/               # Pure shadcn/ui components (DO NOT EDIT DIRECTLY unless styling)
+│   └── shared/           # Reusable global components (Navbar, Footer, etc.)
+├── features/             # Feature-based modules (THE CORE OF THE APP)
+│   ├── users/            # "Users" feature module
+│   │   ├── actions.ts    # Server Actions for this feature
+│   │   ├── components/   # Feature-specific React components
+│   │   └── types.ts      # Feature-specific TypeScript interfaces
+│   └── products/         # "Products" feature module
+├── lib/                  # Utility functions (utils.ts, formatting, constants)
+└── hooks/                # Global custom React hooks
+```
+
+## 📐 4. Architectural Rules & Best Practices
+
+1. **Default to Server Components (RSC)**: 
+   - All components inside `app/` and `features/` MUST be Server Components by default to optimize bundle size and SEO.
+   - ONLY add the `"use client"` directive at the very top of a file if the component requires interactivity (`useState`, `useEffect`, `onClick`, browser APIs).
+   - Keep Client Components as low in the tree (leaf nodes) as possible.
+
+2. **Server Actions for Mutations**:
+   - Do NOT build traditional API routes (`route.ts`) for internal app data mutations.
+   - Use Next.js Server Actions (`"use server"`) placed in `src/features/[name]/actions.ts`.
+   - Always validate inputs inside Server Actions (using Zod or similar) before mutating data.
+
+3. **Shadcn/ui Usage**:
+   - Use the OpenCode CLI or `npx shadcn@latest add [component]` to install components.
+   - Combine UI components to build complex blocks (e.g., combining `Card`, `Button`, and `Input` to make a LoginForm).
+
+4. **Type Safety**:
+   - Avoid `any`. Define interfaces/types in `types.ts` files.
+   - Export types and reuse them across Server Actions and Client Components.
+
+## 💻 5. Code Examples
+
+### Example A: Data Fetching in a Server Component (RSC)
+*File: `src/app/dashboard/page.tsx`*
+```tsx
+import { Suspense } from "react";
+import { getUserProfile } from "@/features/users/actions";
+import { UserProfileCard } from "@/features/users/components/user-profile-card";
+import { Skeleton } from "@/components/ui/skeleton";
+
+// This is a Server Component (no "use client")
+export default async function DashboardPage() {
+  // Fetch data directly on the server
+  const user = await getUserProfile();
+
+  return (
+    <main className="container mx-auto p-6">
+      <h1 className="text-3xl font-bold mb-6">Dashboard</h1>
+      <Suspense fallback={<Skeleton className="h-[200px] w-full rounded-xl" />}>
+        <UserProfileCard user={user} />
+      </Suspense>
+    </main>
+  );
+}
+```
+
+### Example B: Server Action for Data Mutation
+*File: `src/features/users/actions.ts`*
+```typescript
+"use server";
+
+import { revalidatePath } from "next/cache";
+
+export type UpdateUserResponse = {
+  success: boolean;
+  message: string;
+};
+
+export async function updateUserName(formData: FormData): Promise<UpdateUserResponse> {
+  const newName = formData.get("name") as string;
+  
+  if (!newName || newName.length < 3) {
+    return { success: false, message: "Name must be at least 3 characters." };
+  }
+
+  // Perform database mutation here...
+  // await db.user.update(...)
+
+  // Revalidate the cache so the UI updates instantly
+  revalidatePath("/dashboard");
+
+  return { success: true, message: "Profile updated successfully." };
+}
+```
+
+### Example C: Client Component using Shadcn/ui & Server Actions
+*File: `src/features/users/components/edit-name-form.tsx`*
+```tsx
+"use client";
+
+import { useState, useTransition } from "react";
+import { updateUserName } from "@/features/users/actions";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { toast } from "@/components/ui/use-toast"; // shadcn toast
+
+export function EditNameForm() {
+  const [isPending, startTransition] = useTransition();
+
+  const handleSubmit = (formData: FormData) => {
+    startTransition(async () => {
+      const result = await updateUserName(formData);
+      
+      if (result.success) {
+        toast({ title: "Success", description: result.message });
+      } else {
+        toast({ title: "Error", description: result.message, variant: "destructive" });
+      }
+    });
+  };
+
+  return (
+    <form action={handleSubmit} className="flex gap-4 items-center">
+      <Input 
+        name="name" 
+        placeholder="Enter new name" 
+        required 
+        disabled={isPending} 
+        className="max-w-sm"
+      />
+      <Button type="submit" disabled={isPending}>
+        {isPending ? "Saving..." : "Save Name"}
+      </Button>
+    </form>
+  );
+}
+```