@valentia-ai-skills/framework 1.0.0

package/skills/stack/node-backend/tests/test-prompts.md

@@ -0,0 +1,27 @@
+## Test 1: Service Creation
+**Prompt**: "Create a user registration service that validates input, checks for duplicate emails, hashes the password, saves to DB, and sends a welcome email"
+**Expected**:
+- Layered: controller → service → repository
+- Dependencies injected
+- Zod validation at controller level
+- Custom errors (ConflictError for duplicate, ValidationError)
+- Password hashed with bcrypt
+- Service doesn't touch req/res objects
+
+## Test 2: API Setup
+**Prompt**: "Set up an Express API with health checks, error handling, structured logging, and graceful shutdown"
+**Expected**:
+- /health endpoint checking DB and Redis
+- Global error handler middleware
+- Pino or Winston structured logging
+- SIGTERM/SIGINT handlers with timeout
+- Config validated at startup with Zod
+
+## Test 3: Database Repository
+**Prompt**: "Create a repository for an e-commerce orders table with CRUD, pagination, and filtering by status and date range"
+**Expected**:
+- Repository class with injected DB client
+- Typed methods for each operation
+- Pagination following api-design standards
+- Transaction for create (order + order items)
+- No business logic in repository

package/skills/stack/python-backend/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: python-backend-patterns
+description: >
+  Python backend development patterns for FastAPI, Django, and data services.
+  Use this skill whenever writing, reviewing, or designing Python backend code
+  including API endpoints, data pipelines, background tasks, database models,
+  or Python microservices. Triggers on: "FastAPI", "Django", "Flask", "Python API",
+  "Pydantic", "SQLAlchemy", "Alembic", "Celery", "asyncio", "uvicorn",
+  "gunicorn", "Python service", "data pipeline", "ETL", "pandas backend",
+  "Python microservice". Applies to Python backend teams.
+version: "1.0.0"
+scope: stack
+stack: python-backend
+author: Framework Admin
+last_reviewed: 2026-03-19
+---
+
+# Python Backend Patterns
+
+## Overview
+
+Standardized Python backend patterns for API services and data pipelines.
+Assumes FastAPI as the default framework (Django sections noted where applicable).
+
+**Prerequisites**: `global/code-standards`, `global/security-baseline`, and
+`global/api-design` all apply. This skill adds Python-specific conventions.
+
+## 1. Project Structure (FastAPI)
+
+```
+src/
+  app/
+    main.py                # App factory, startup/shutdown
+    config.py              # Settings with Pydantic BaseSettings
+    dependencies.py        # FastAPI dependency injection
+    
+    routers/               # Route definitions
+      __init__.py
+      users.py
+      orders.py
+    
+    services/              # Business logic
+      user_service.py
+      order_service.py
+    
+    repositories/          # Database access
+      user_repository.py
+    
+    models/                # SQLAlchemy models
+      user.py
+      order.py
+    
+    schemas/               # Pydantic request/response schemas
+      user_schemas.py
+      order_schemas.py
+    
+    middleware/             # Custom middleware
+      logging_middleware.py
+    
+    exceptions/            # Custom exception classes
+      base.py
+      handlers.py
+    
+    utils/                 # Shared utilities
+      
+  tests/
+    conftest.py            # Shared fixtures
+    test_users.py
+    test_orders.py
+  
+  alembic/                 # Database migrations
+    versions/
+    env.py
+  
+  pyproject.toml           # Project config + dependencies
+```
+
+### Naming Rules (Python-specific)
+- Files and folders: `snake_case`
+- Classes: `PascalCase`
+- Functions and variables: `snake_case`
+- Constants: `UPPER_SNAKE_CASE`
+- Private methods/attrs: `_single_underscore`
+- Follow PEP 8 — enforced via ruff
+
+## 2. Configuration
+
+```python
+# config.py
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    """Application settings — loaded from environment variables."""
+    
+    app_name: str = "my-service"
+    environment: str = "development"
+    debug: bool = False
+    
+    # Database
+    database_url: str
+    database_pool_size: int = 5
+    
+    # Redis
+    redis_url: str
+    
+    # Auth
+    jwt_secret: str
+    jwt_expiry_minutes: int = 15
+    
+    # External services
+    email_api_key: str = ""
+    
+    class Config:
+        env_file = ".env"
+
+settings = Settings()
+```
+
+### Rules
+- All config through Pydantic `BaseSettings` — validates at startup
+- Never use `os.getenv()` directly in service code
+- Type all settings — Pydantic will fail fast on invalid values
+- Secrets loaded from env vars, never hardcoded
+
+## 3. Request/Response Schemas
+
+```python
+# schemas/user_schemas.py
+from pydantic import BaseModel, EmailStr, Field
+from datetime import datetime
+
+class CreateUserRequest(BaseModel):
+    email: EmailStr
+    name: str = Field(min_length=1, max_length=100)
+    role: str = Field(pattern="^(user|admin|editor)$")
+
+class UserResponse(BaseModel):
+    id: str
+    email: str
+    name: str
+    role: str
+    created_at: datetime
+
+    class Config:
+        from_attributes = True  # allows ORM objects
+
+class UserListResponse(BaseModel):
+    data: list[UserResponse]
+    pagination: PaginationResponse
+```
+
+### Rules
+- Separate schemas for request (input) and response (output)
+- Use Pydantic `Field` for validation rules
+- Response schemas use `from_attributes = True` for ORM compatibility
+- Follow the `data` / `error` envelope from api-design standards
+
+## 4. Dependency Injection (FastAPI)
+
+```python
+# dependencies.py
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session_maker() as session:
+        yield session
+
+async def get_user_service(
+    db: AsyncSession = Depends(get_db),
+) -> UserService:
+    repo = UserRepository(db)
+    return UserService(repo)
+
+# In routers:
+@router.post("/users", status_code=201)
+async def create_user(
+    data: CreateUserRequest,
+    service: UserService = Depends(get_user_service),
+) -> UserResponse:
+    return await service.create_user(data)
+```
+
+### Rules
+- Use FastAPI's `Depends()` for all dependency injection
+- Database sessions via `yield` dependency (ensures cleanup)
+- Services receive repositories through DI — never import directly
+- All dependencies are explicit and testable
+
+## 5. Async/Await Rules
+
+```python
+# ✅ Good: async for I/O operations
+async def get_user(user_id: str) -> User:
+    return await db.execute(select(User).where(User.id == user_id))
+
+# ✅ Good: sync for CPU-bound operations
+def calculate_report(data: list[dict]) -> Report:
+    return Report(totals=sum(d["amount"] for d in data))
+
+# ❌ Bad: blocking I/O in async function
+async def get_user(user_id: str) -> User:
+    return requests.get(f"/api/users/{user_id}")  # blocks the event loop!
+```
+
+### Rules
+- Use `async/await` for all I/O (database, HTTP, file system)
+- Use `httpx` (async) instead of `requests` (sync) for HTTP calls
+- Use `asyncpg` or async SQLAlchemy for database access
+- Never mix sync blocking calls in async code paths
+- For CPU-heavy work in async context, use `asyncio.to_thread()`
+
+## 6. Error Handling
+
+```python
+# exceptions/base.py
+class AppError(Exception):
+    def __init__(self, message: str, status_code: int, code: str, details=None):
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.details = details
+        super().__init__(message)
+
+class NotFoundError(AppError):
+    def __init__(self, resource: str, resource_id: str):
+        super().__init__(
+            message=f"{resource} with id {resource_id} not found",
+            status_code=404,
+            code="NOT_FOUND",
+        )
+
+class ValidationError(AppError):
+    def __init__(self, details: list[dict]):
+        super().__init__(
+            message="Validation failed",
+            status_code=400,
+            code="VALIDATION_ERROR",
+            details=details,
+        )
+
+# exceptions/handlers.py
+@app.exception_handler(AppError)
+async def app_error_handler(request: Request, exc: AppError):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"error": {"code": exc.code, "message": exc.message, "details": exc.details}},
+    )
+```
+
+## 7. Testing (pytest)
+
+```python
+# conftest.py
+import pytest
+from httpx import AsyncClient
+
+@pytest.fixture
+async def db_session():
+    async with test_engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    async with async_test_session() as session:
+        yield session
+    async with test_engine.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+
+@pytest.fixture
+async def client(db_session):
+    app.dependency_overrides[get_db] = lambda: db_session
+    async with AsyncClient(app=app, base_url="http://test") as ac:
+        yield ac
+    app.dependency_overrides.clear()
+
+# test_users.py
+@pytest.mark.asyncio
+async def test_create_user_success(client: AsyncClient):
+    response = await client.post("/api/v1/users", json={
+        "email": "alice@example.com",
+        "name": "Alice",
+        "role": "user",
+    })
+    assert response.status_code == 201
+    assert response.json()["data"]["email"] == "alice@example.com"
+```
+
+### Rules
+- Use `pytest` with `pytest-asyncio` for async tests
+- Override FastAPI dependencies in fixtures (not mocking)
+- Use `httpx.AsyncClient` for integration tests
+- Factory fixtures for test data (see testing-standards skill)
+
+## Checklist
+
+Before finalizing Python backend code:
+- [ ] Layered: routers → services → repositories
+- [ ] Config via Pydantic BaseSettings, validated at startup
+- [ ] Request/response schemas separated (Pydantic)
+- [ ] Dependencies injected via FastAPI Depends()
+- [ ] All I/O is async (httpx, async SQLAlchemy)
+- [ ] Custom error classes with status codes
+- [ ] Global exception handler returns standard error envelope
+- [ ] Migrations via Alembic (not manual SQL)
+- [ ] Tests use dependency override, not mocking
+- [ ] ruff for linting, mypy for type checking

package/skills/stack/python-backend/tests/test-prompts.md

@@ -0,0 +1,27 @@
+## Test 1: FastAPI Service
+**Prompt**: "Create a FastAPI service for managing a product catalog with CRUD endpoints, Pydantic schemas, and SQLAlchemy models"
+**Expected**:
+- Project structure follows the standard layout
+- Separate request/response schemas
+- Repository pattern for DB access
+- Dependency injection via Depends()
+- Async database operations
+- Custom error handling
+
+## Test 2: Configuration & Startup
+**Prompt**: "Set up the application config, database connection, and health check for a FastAPI service"
+**Expected**:
+- Pydantic BaseSettings for config
+- Async SQLAlchemy session factory
+- /health endpoint checking DB
+- Startup/shutdown lifecycle events
+- Graceful error on missing env vars
+
+## Test 3: Background Task
+**Prompt**: "Create an endpoint that accepts a CSV upload, processes it in the background, and returns the job status"
+**Expected**:
+- Upload endpoint with file validation
+- Background task (Celery or FastAPI BackgroundTasks)
+- Job status tracking
+- Async file processing
+- Error handling for bad CSV data

package/skills/stack/react/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: react-patterns
+description: >
+  React development patterns and conventions for web teams. Use this skill
+  whenever writing, reviewing, or refactoring React components, hooks,
+  state management, context, effects, forms, routing, or any React-specific
+  code. Triggers on: "React", "component", "hook", "useState", "useEffect",
+  "useRef", "useContext", "useMemo", "useCallback", "JSX", "TSX", "props",
+  "state", "context", "reducer", "render", "virtual DOM", "Next.js", "Remix",
+  "React Router", "form handling", "controlled component", "uncontrolled".
+  Applies to all web teams using React.
+version: "1.0.0"
+scope: stack
+stack: react
+author: Framework Admin
+last_reviewed: 2026-03-19
+---
+
+# React Patterns
+
+## Overview
+
+Standardized React patterns ensure consistent component architecture across
+all web teams. These conventions cover component structure, hooks usage,
+state management, and performance patterns.
+
+## 1. Component Structure
+
+### File Template
+Every component file follows this order:
+
+```tsx
+// 1. Imports (follow code-standards import order)
+import { useState, useCallback } from "react";
+import { Button } from "@/components/ui/button";
+import type { User } from "@/types/user";
+
+// 2. Types / Interfaces
+interface UserCardProps {
+  user: User;
+  onEdit: (userId: string) => void;
+  isCompact?: boolean;
+}
+
+// 3. Constants (component-specific)
+const MAX_BIO_LENGTH = 200;
+
+// 4. Component
+export function UserCard({ user, onEdit, isCompact = false }: UserCardProps) {
+  // 4a. Hooks (always at the top, same order every time)
+  const [isExpanded, setIsExpanded] = useState(false);
+
+  // 4b. Derived state (computed from props/state)
+  const displayName = `${user.firstName} ${user.lastName}`;
+  const truncatedBio = user.bio?.slice(0, MAX_BIO_LENGTH);
+
+  // 4c. Handlers
+  const handleEditClick = useCallback(() => {
+    onEdit(user.id);
+  }, [onEdit, user.id]);
+
+  // 4d. Early returns (loading, error, empty states)
+  if (!user) return null;
+
+  // 4e. Render
+  return (
+    <div className={isCompact ? "p-2" : "p-4"}>
+      <h3>{displayName}</h3>
+      <p>{isExpanded ? user.bio : truncatedBio}</p>
+      <Button onClick={handleEditClick}>Edit</Button>
+    </div>
+  );
+}
+```
+
+### Rules
+- One component per file (with small sub-components allowed)
+- Named exports for components (not default, except page-level)
+- Component name matches file name: `user-card.tsx` → `UserCard`
+- Props interface defined above the component
+- All props typed — no `any`
+
+## 2. Hooks
+
+### Hook Order (always consistent)
+```tsx
+function MyComponent() {
+  // 1. External hooks (router, context, etc.)
+  const router = useRouter();
+  const { user } = useAuth();
+  
+  // 2. State hooks
+  const [count, setCount] = useState(0);
+  const [isOpen, setIsOpen] = useState(false);
+  
+  // 3. Refs
+  const inputRef = useRef<HTMLInputElement>(null);
+  
+  // 4. Derived state (useMemo for expensive computations only)
+  const total = useMemo(() => calculateTotal(items), [items]);
+  
+  // 5. Effects
+  useEffect(() => { ... }, [dependency]);
+  
+  // 6. Callbacks
+  const handleSubmit = useCallback(() => { ... }, [deps]);
+}
+```
+
+### Custom Hook Rules
+- Prefix with `use`: `useAuth`, `useDebounce`, `usePagination`
+- Extract when logic is reused across 2+ components
+- Put in `hooks/` directory: `hooks/use-debounce.ts`
+- Always return a typed value
+
+```tsx
+// ✅ Good: Clean custom hook
+function useDebounce<T>(value: T, delayMs: number): T {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedValue(value), delayMs);
+    return () => clearTimeout(timer);
+  }, [value, delayMs]);
+
+  return debouncedValue;
+}
+```
+
+### useEffect Rules
+- Every effect must have a dependency array
+- Empty `[]` only for mount-once effects (and add a comment explaining why)
+- Clean up subscriptions, timers, and listeners in the return function
+- Never lie about dependencies — if ESLint warns, fix the code, don't suppress
+
+✅ Good:
+```tsx
+useEffect(() => {
+  const controller = new AbortController();
+  
+  fetchUser(userId, { signal: controller.signal })
+    .then(setUser)
+    .catch(err => {
+      if (err.name !== "AbortError") setError(err);
+    });
+
+  return () => controller.abort();  // cleanup
+}, [userId]);
+```
+
+❌ Bad:
+```tsx
+useEffect(() => {
+  fetchUser(userId).then(setUser);
+});  // missing dependency array — runs every render
+
+useEffect(() => {
+  fetchUser(userId).then(setUser);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+}, []);  // suppressing the warning instead of fixing
+```
+
+## 3. State Management
+
+### Decision Matrix
+| Scope | Solution |
+|-------|----------|
+| Single component | `useState` |
+| Parent → Children (2-3 levels) | Props drilling (it's fine!) |
+| Deep tree (4+ levels) | React Context |
+| Complex state transitions | `useReducer` |
+| Server state (API data) | TanStack Query / SWR |
+| Global client state | Zustand (preferred) or Redux Toolkit |
+
+### Rules
+- Start simple — don't add Zustand/Redux until you actually need it
+- Server state belongs in TanStack Query, not in global state
+- Context is for slow-changing data (theme, auth, locale) — not for frequently updating state
+- Never put derived state in useState — compute it inline
+
+```tsx
+// ❌ Bad: Storing derived state
+const [fullName, setFullName] = useState(`${first} ${last}`);
+useEffect(() => setFullName(`${first} ${last}`), [first, last]);
+
+// ✅ Good: Compute inline
+const fullName = `${first} ${last}`;
+```
+
+## 4. Event Handling
+
+- Handlers prefixed with `handle`: `handleClick`, `handleSubmit`
+- Callback props prefixed with `on`: `onClick`, `onSubmit`
+- Use `useCallback` only when passing handlers to memoized children
+
+```tsx
+// In parent:
+const handleUserSelect = useCallback((userId: string) => {
+  setSelectedUser(userId);
+}, []);
+
+// In child props:
+<UserList onSelect={handleUserSelect} />
+```
+
+## 5. Conditional Rendering
+
+```tsx
+// Boolean: use &&
+{isLoggedIn && <Dashboard />}
+
+// Binary: use ternary
+{isLoading ? <Spinner /> : <Content />}
+
+// Multiple conditions: use early return or extracted function
+function StatusBadge({ status }: { status: OrderStatus }) {
+  if (status === "pending") return <Badge color="yellow">Pending</Badge>;
+  if (status === "shipped") return <Badge color="blue">Shipped</Badge>;
+  if (status === "delivered") return <Badge color="green">Delivered</Badge>;
+  return null;
+}
+```
+
+### Watch Out
+```tsx
+// ❌ Bug: renders "0" when count is 0
+{count && <Tag>{count}</Tag>}
+
+// ✅ Fix: explicit boolean check
+{count > 0 && <Tag>{count}</Tag>}
+```
+
+## 6. Performance
+
+- Use `React.memo` only for components that re-render with same props frequently
+- Use `useMemo` only for genuinely expensive computations (not simple lookups)
+- Use `useCallback` only when passing to memoized children
+- Profile first, optimize second — don't premature-optimize
+- Lazy load heavy components: `const HeavyChart = React.lazy(() => import("./heavy-chart"))`
+
+## Checklist
+
+Before finalizing React code:
+- [ ] One component per file, named export, props typed
+- [ ] Hooks in consistent order (context → state → refs → memo → effects → callbacks)
+- [ ] All useEffect have dependency arrays and cleanup functions
+- [ ] No derived state in useState — computed inline
+- [ ] Event handlers: handle* (internal) and on* (props)
+- [ ] State management matches scope (don't over-engineer)
+- [ ] No eslint-disable for hook dependency warnings
+- [ ] Loading, error, and empty states handled

package/skills/stack/react/tests/test-prompts.md

@@ -0,0 +1,26 @@
+## Test 1: Component Creation
+**Prompt**: "Build a product card component that shows image, title, price, rating, and an add-to-cart button with quantity selector"
+**Expected**:
+- Props interface with all fields typed
+- Named export
+- Hooks in correct order
+- Handlers prefixed with handle
+- Loading/empty state handled
+
+## Test 2: Data Fetching Component
+**Prompt**: "Create a user profile page that fetches user data from an API, shows loading state, error state, and allows editing the bio field"
+**Expected**:
+- useEffect with proper cleanup (AbortController)
+- Dependency array correct
+- Loading, error, and success states
+- No derived state in useState
+- Form handling with controlled input
+
+## Test 3: State Management Decision
+**Prompt**: "I have a shopping cart that needs to be accessible from the navbar, product pages, and checkout. What state management should I use?"
+**Expected**:
+- Recommends Zustand or Context based on complexity
+- Explains why not just props (too many levels)
+- Server state (product data) in TanStack Query
+- Client state (cart items) in Zustand/Context
+- Shows code example