@devmunna/agent-skillkit 0.1.0

package/skills/react-feature-arch/references/forms.md

@@ -0,0 +1,194 @@
+# Forms Reference — React Hook Form v7 + Zod v4
+
+---
+
+## Schema File — {feature}.schema.ts
+
+Define Zod schemas once. Derive TypeScript types with `z.infer<>`. Share types between forms, API calls, and hooks.
+
+```ts
+// features/users/users.schema.ts
+import { z } from 'zod';
+
+export const createUserSchema = z.object({
+  name:  z.string().min(2, 'Name must be at least 2 characters'),
+  email: z.string().email('Invalid email address'),
+  role:  z.enum(['USER', 'ADMIN', 'MANAGER']).default('USER'),
+});
+
+export const updateUserSchema = createUserSchema.partial();
+
+// Types derived from schema — single source of truth
+export type CreateUserDto = z.infer<typeof createUserSchema>;
+export type UpdateUserDto = z.infer<typeof updateUserSchema>;
+export type User = { id: string; createdAt: string } & CreateUserDto;
+```
+
+---
+
+## Create Form
+
+```tsx
+// features/users/components/CreateUserForm.tsx
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { createUserSchema, type CreateUserDto } from '../users.schema';
+import { useCreateUser } from '../users.hooks';
+
+interface Props {
+  onSuccess?: () => void;
+}
+
+export function CreateUserForm({ onSuccess }: Props) {
+  const createUser = useCreateUser();
+
+  const {
+    register,
+    handleSubmit,
+    reset,
+    formState: { errors, isSubmitting },
+  } = useForm<CreateUserDto>({
+    resolver:      zodResolver(createUserSchema),
+    defaultValues: { role: 'USER' },
+  });
+
+  const onSubmit = async (data: CreateUserDto) => {
+    await createUser.mutateAsync(data);
+    reset();
+    onSuccess?.();
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <div>
+        <label>Name</label>
+        <input {...register('name')} placeholder="Full name" />
+        {errors.name && <span className="error">{errors.name.message}</span>}
+      </div>
+
+      <div>
+        <label>Email</label>
+        <input {...register('email')} type="email" placeholder="email@example.com" />
+        {errors.email && <span className="error">{errors.email.message}</span>}
+      </div>
+
+      <div>
+        <label>Role</label>
+        <select {...register('role')}>
+          <option value="USER">User</option>
+          <option value="ADMIN">Admin</option>
+          <option value="MANAGER">Manager</option>
+        </select>
+      </div>
+
+      {createUser.error && (
+        <p className="error">{(createUser.error as any).message}</p>
+      )}
+
+      <button type="submit" disabled={isSubmitting || createUser.isPending}>
+        {createUser.isPending ? 'Creating...' : 'Create User'}
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+## Edit Form (pre-populated)
+
+```tsx
+// features/users/components/EditUserForm.tsx
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { updateUserSchema, type UpdateUserDto, type User } from '../users.schema';
+import { useUpdateUser } from '../users.hooks';
+
+export function EditUserForm({ user, onSuccess }: { user: User; onSuccess?: () => void }) {
+  const updateUser = useUpdateUser();
+
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isDirty, isSubmitting },
+  } = useForm<UpdateUserDto>({
+    resolver:      zodResolver(updateUserSchema),
+    defaultValues: { name: user.name, email: user.email, role: user.role },
+  });
+
+  const onSubmit = async (data: UpdateUserDto) => {
+    await updateUser.mutateAsync({ id: user.id, data });
+    onSuccess?.();
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('name')} />
+      {errors.name && <span>{errors.name.message}</span>}
+
+      <input {...register('email')} type="email" />
+      {errors.email && <span>{errors.email.message}</span>}
+
+      <button type="submit" disabled={!isDirty || isSubmitting || updateUser.isPending}>
+        {updateUser.isPending ? 'Saving...' : 'Save Changes'}
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+## Cross-Field Validation
+
+```ts
+const passwordSchema = z.object({
+  password:        z.string().min(8, 'Password must be at least 8 characters'),
+  confirmPassword: z.string(),
+}).refine((d) => d.password === d.confirmPassword, {
+  message: 'Passwords do not match',
+  path:    ['confirmPassword'],
+});
+```
+
+---
+
+## React 19 useActionState Form (no RHF — simple cases only)
+
+Use RHF for complex forms. Use `useActionState` only for simple forms where progressive enhancement is needed.
+
+```tsx
+import { useActionState } from 'react';
+import { createUserSchema } from '../users.schema';
+import { usersApi } from '../users.api';
+
+async function submitAction(_prev: any, formData: FormData) {
+  const result = createUserSchema.safeParse({
+    name:  formData.get('name'),
+    email: formData.get('email'),
+  });
+  if (!result.success) return { error: result.error.issues[0].message };
+  try {
+    await usersApi.create(result.data);
+    return { success: true };
+  } catch (err: any) {
+    return { error: err.message ?? 'Failed to create user' };
+  }
+}
+
+export function SimpleCreateForm() {
+  const [state, formAction, isPending] = useActionState(submitAction, null);
+
+  return (
+    <form action={formAction}>
+      <input name="name" required />
+      <input name="email" type="email" required />
+      {state?.error   && <p className="error">{state.error}</p>}
+      {state?.success && <p className="success">User created!</p>}
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Saving...' : 'Create'}
+      </button>
+    </form>
+  );
+}
+```

package/skills/react-feature-arch/references/routing.md

@@ -0,0 +1,148 @@
+# Routing Reference — React Router v7
+
+---
+
+## src/app/router.tsx
+
+```tsx
+import { createBrowserRouter, Navigate } from 'react-router';
+import { lazy, Suspense }                from 'react';
+import { RootLayout }     from '@/components/layout/RootLayout';
+import { AuthLayout }     from '@/components/layout/AuthLayout';
+import { DashLayout }     from '@/components/layout/DashLayout';
+import { ProtectedRoute } from '@/components/layout/ProtectedRoute';
+import { PageSpinner }    from '@/components/ui/PageSpinner';
+
+// Lazy-loaded route components — code-split per route
+const LoginPage      = lazy(() => import('@/features/auth/auth.page').then(m => ({ default: m.LoginPage })));
+const RegisterPage   = lazy(() => import('@/features/auth/register.page').then(m => ({ default: m.RegisterPage })));
+const DashboardPage  = lazy(() => import('@/features/dashboard/dashboard.page').then(m => ({ default: m.DashboardPage })));
+const UsersPage      = lazy(() => import('@/features/users/users.page').then(m => ({ default: m.UsersPage })));
+const UserDetailPage = lazy(() => import('@/features/users/user-detail.page').then(m => ({ default: m.UserDetailPage })));
+
+const withSuspense = (Component: React.ComponentType) => (
+  <Suspense fallback={<PageSpinner />}>
+    <Component />
+  </Suspense>
+);
+
+export const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <RootLayout />,
+    children: [
+      { index: true, element: <Navigate to="/dashboard" replace /> },
+
+      // Public routes
+      {
+        path: 'auth',
+        element: <AuthLayout />,
+        children: [
+          { path: 'login',    element: withSuspense(LoginPage) },
+          { path: 'register', element: withSuspense(RegisterPage) },
+        ],
+      },
+
+      // Protected routes
+      {
+        element: <ProtectedRoute />,
+        children: [
+          {
+            element: <DashLayout />,
+            children: [
+              { path: 'dashboard', element: withSuspense(DashboardPage) },
+              { path: 'users',     element: withSuspense(UsersPage) },
+              { path: 'users/:id', element: withSuspense(UserDetailPage) },
+            ],
+          },
+        ],
+      },
+
+      // Role-restricted routes
+      {
+        element: <ProtectedRoute allowedRoles={['ADMIN']} />,
+        children: [
+          { path: 'admin', element: withSuspense(AdminPage) },
+        ],
+      },
+    ],
+  },
+]);
+```
+
+---
+
+## src/app/App.tsx
+
+```tsx
+import { RouterProvider } from 'react-router';
+import { router }         from './router';
+import { Providers }      from './providers';
+
+export default function App() {
+  return (
+    <Providers>
+      <RouterProvider router={router} />
+    </Providers>
+  );
+}
+```
+
+---
+
+## ProtectedRoute Component
+
+```tsx
+// components/layout/ProtectedRoute.tsx
+import { Navigate, Outlet } from 'react-router';
+import { useShallow }       from 'zustand/react/shallow';
+import { useAuthStore }     from '@/store/auth.store';
+
+interface Props {
+  allowedRoles?: string[];
+}
+
+export function ProtectedRoute({ allowedRoles }: Props) {
+  const { isAuthenticated, user } = useAuthStore(
+    useShallow((s) => ({ isAuthenticated: s.isAuthenticated, user: s.user })),
+  );
+
+  if (!isAuthenticated) return <Navigate to="/auth/login" replace />;
+
+  if (allowedRoles && user && !allowedRoles.includes(user.role)) {
+    return <Navigate to="/unauthorized" replace />;
+  }
+
+  return <Outlet />;
+}
+```
+
+---
+
+## Navigation Hooks
+
+```tsx
+import { useNavigate, useParams, useSearchParams, Link, NavLink } from 'react-router';
+
+// Navigate programmatically
+const navigate = useNavigate();
+navigate('/users');
+navigate(`/users/${id}`);
+navigate(-1);                         // go back
+
+// Route params
+const { id } = useParams<{ id: string }>();
+
+// Search params — for filters, pagination, tabs
+const [searchParams, setSearchParams] = useSearchParams();
+const page  = Number(searchParams.get('page') ?? 1);
+const tab   = searchParams.get('tab') ?? 'all';
+
+setSearchParams({ page: String(page + 1), tab });
+
+// Link vs NavLink
+<Link to={`/users/${user.id}`}>{user.name}</Link>
+<NavLink to="/dashboard" className={({ isActive }) => isActive ? 'active' : ''}>
+  Dashboard
+</NavLink>
+```

package/skills/react-feature-arch/references/state-management.md

@@ -0,0 +1,107 @@
+# State Management Reference — Zustand v5
+
+Zustand manages **global UI state only** (auth session, theme, sidebar).
+Server data lives in TanStack Query — never duplicate API responses in Zustand.
+
+---
+
+## Auth Store
+
+```ts
+// src/store/auth.store.ts
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+interface User {
+  id:    string;
+  name:  string;
+  email: string;
+  role:  string;
+}
+
+interface AuthState {
+  user:            User | null;
+  token:           string | null;
+  isAuthenticated: boolean;
+  login:           (user: User, token: string) => void;
+  logout:          () => void;
+}
+
+export const useAuthStore = create<AuthState>()(
+  persist(
+    (set) => ({
+      user:            null,
+      token:           null,
+      isAuthenticated: false,
+      login:  (user, token) => set({ user, token, isAuthenticated: true }),
+      logout: ()             => set({ user: null, token: null, isAuthenticated: false }),
+    }),
+    { name: 'auth-storage' },  // persisted to localStorage
+  ),
+);
+```
+
+---
+
+## UI Store
+
+```ts
+// src/store/ui.store.ts
+import { create } from 'zustand';
+
+interface UIState {
+  sidebarOpen: boolean;
+  theme:        'light' | 'dark';
+  toggleSidebar: () => void;
+  setTheme:     (theme: 'light' | 'dark') => void;
+}
+
+export const useUIStore = create<UIState>()((set) => ({
+  sidebarOpen:   true,
+  theme:         'light',
+  toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),
+  setTheme:      (theme) => set({ theme }),
+}));
+```
+
+---
+
+## Access State Outside React (e.g., axios interceptor)
+
+```ts
+// Zustand v5 — getState() for accessing store outside a React component
+import { useAuthStore } from '@/store/auth.store';
+
+const token  = useAuthStore.getState().token;
+const logout = useAuthStore.getState().logout;
+```
+
+---
+
+## Shallow Comparison (prevent extra re-renders)
+
+```tsx
+import { useShallow } from 'zustand/react/shallow';
+
+// Re-renders only when user OR isAuthenticated changes
+const { user, isAuthenticated } = useAuthStore(
+  useShallow((s) => ({ user: s.user, isAuthenticated: s.isAuthenticated })),
+);
+```
+
+---
+
+## Usage in Components
+
+```tsx
+// Selecting a single value — no shallow needed
+const token = useAuthStore((s) => s.token);
+
+// Selecting an action — always stable, no re-render risk
+const logout = useAuthStore((s) => s.logout);
+
+// Selecting multiple values — use useShallow
+const { user, isAuthenticated } = useAuthStore(
+  useShallow((s) => ({ user: s.user, isAuthenticated: s.isAuthenticated })),
+);
+```

package/skills/tailwind-css/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: tailwind-css
+version: 1.0.0
+description: >
+  Use this skill for any Tailwind CSS task: project setup, design tokens, component styling, responsive design, dark mode, animations, or utility patterns. Triggers: "add Tailwind", "style with Tailwind", "dark mode", "responsive layout", "component variants", "design system", "tailwind v4", "cn helper", "CVA", "container queries", "shadcn".
+stack: [tailwind, css]
+depends: []
+---
+
+# Tailwind CSS v4 — Production Skill
+
+**Version target:** Tailwind CSS v4 · @tailwindcss/vite or @tailwindcss/postcss · TypeScript 5
+
+---
+
+## Tech Stack
+
+| Tool | Package |
+|---|---|
+| Core | tailwindcss v4 |
+| Vite integration | @tailwindcss/vite |
+| Next.js integration | @tailwindcss/postcss |
+| Class merging | clsx + tailwind-merge |
+| Component variants | class-variance-authority (CVA) |
+| Component library | shadcn/ui (optional) |
+| Typography | @tailwindcss/typography |
+
+---
+
+## v4 vs v3 — Critical Differences
+
+| Feature | v3 | v4 |
+|---|---|---|
+| Import | `@tailwind base/components/utilities` | `@import "tailwindcss"` (single line) |
+| Config file | `tailwind.config.js` | CSS `@theme` directive (no JS config needed) |
+| Custom tokens | JS `theme.extend` | `@theme` block in CSS |
+| Custom utilities | Plugin system | `@utility` directive |
+| Custom variants | Plugin `addVariant` | `@custom-variant` directive |
+| Dark mode config | `darkMode: 'class'` in JS | `@custom-variant dark` in CSS |
+| Container queries | External plugin | Built-in (`@container`, `@sm:`, `@md:`) |
+| Gradients | `bg-gradient-to-r` | `bg-linear-to-r` |
+| Content detection | `content: [...]` in config | Automatic — no config needed |
+| Colors | HEX / HSL | HEX / HSL / **OKLCH** (preferred) |
+
+---
+
+## Setup
+
+### Vite + React
+
+```bash
+npm install tailwindcss @tailwindcss/vite
+```
+
+**vite.config.ts:**
+```ts
+import { defineConfig }  from 'vite';
+import react             from '@vitejs/plugin-react';
+import tailwindcss       from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});
+```
+
+**src/index.css:**
+```css
+@import "tailwindcss";
+```
+
+### Next.js 15
+
+```bash
+npm install tailwindcss @tailwindcss/postcss postcss
+```
+
+**postcss.config.mjs:**
+```js
+export default { plugins: { '@tailwindcss/postcss': {} } };
+```
+
+**src/app/globals.css:**
+```css
+@import "tailwindcss";
+```
+
+See `references/setup.md` for full setup including path aliases, typography plugin, and shadcn/ui init.
+
+---
+
+## Design Tokens — @theme
+
+All design tokens live in `@theme` in your global CSS file. Tailwind auto-generates utility classes from them.
+
+```css
+@import "tailwindcss";
+
+@theme {
+  /* Colors — OKLCH preferred for perceptual uniformity */
+  --color-primary:   oklch(0.55 0.25 262);
+  --color-secondary: oklch(0.84 0.16 84);
+  --color-danger:    oklch(0.55 0.25 27);
+
+  /* Fonts */
+  --font-sans: 'Inter', sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+
+  /* Border radius */
+  --radius-card: 0.75rem;
+  --radius-pill: 9999px;
+
+  /* Custom spacing */
+  --spacing-page: 2rem;
+}
+```
+
+Generated utilities: `bg-primary`, `text-secondary`, `border-danger`, `font-sans`, `rounded-card`, `p-page`, etc.
+
+See `references/design-tokens.md` for the full token reference.
+
+---
+
+## Component Patterns
+
+### cn() Helper — Required for all components
+
+```ts
+// src/lib/utils.ts
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge }               from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+```
+
+Allows callers to override classes without CSS conflicts:
+```tsx
+<Button className="w-full" />   // overrides default width cleanly
+```
+
+### CVA — Component Variants
+
+```ts
+import { cva, type VariantProps } from 'class-variance-authority';
+
+const button = cva(
+  'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        default:     'bg-primary text-white hover:bg-primary/90',
+        outline:     'border border-current bg-transparent hover:bg-primary/10',
+        ghost:       'hover:bg-primary/10 hover:text-primary',
+        destructive: 'bg-danger text-white hover:bg-danger/90',
+      },
+      size: {
+        sm:   'h-8  px-3 text-sm',
+        md:   'h-10 px-4',
+        lg:   'h-12 px-6 text-lg',
+        icon: 'h-10 w-10',
+      },
+    },
+    defaultVariants: { variant: 'default', size: 'md' },
+  },
+);
+
+interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof button> {}
+
+export function Button({ className, variant, size, ...props }: ButtonProps) {
+  return (
+    <button className={cn(button({ variant, size }), className)} {...props} />
+  );
+}
+```
+
+See `references/components.md` for Card, Input, Badge, and Modal patterns.
+
+---
+
+## Responsive Design
+
+**Mobile-first — always start with base (mobile), add larger breakpoints:**
+
+```html
+<!-- Mobile: 1 col → md: 2 col → lg: 3 col -->
+<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+
+<!-- Mobile: full width → sm: auto -->
+<button class="w-full sm:w-auto">Submit</button>
+```
+
+**Container queries (v4 built-in) — adapt to parent size, not viewport:**
+
+```html
+<div class="@container">
+  <div class="grid grid-cols-1 @md:grid-cols-2 @lg:grid-cols-3">
+    <!-- Layout based on container width, not screen width -->
+  </div>
+</div>
+```
+
+---
+
+## Dark Mode
+
+```css
+/* Class-based dark mode in globals.css */
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+```tsx
+// Toggle on <html> element
+document.documentElement.classList.toggle('dark');
+```
+
+```html
+<div class="bg-white dark:bg-slate-900 text-slate-900 dark:text-white">
+  Content
+</div>
+```
+
+See `references/patterns.md` for full dark mode strategy, animations, and layout patterns.
+
+---
+
+## Core References
+
+| Topic | File |
+|---|---|
+| Setup — Vite, Next.js, shadcn/ui | `references/setup.md` |
+| Design tokens — @theme, colors, fonts, spacing | `references/design-tokens.md` |
+| Components — cn(), CVA, Button, Card, Input | `references/components.md` |
+| Patterns — responsive, dark mode, animations, typography | `references/patterns.md` |