@namch/agent-assistant 1.0.0 → 1.0.2

package/skills/frontend-dev-guidelines/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: frontend-dev-guidelines
+description: Opinionated frontend development standards for modern React + TypeScript applications. Covers Suspense-first data fetching, lazy loading, feature-based architecture, MUI v7 styling, TanStack Router, performance optimization, and strict TypeScript practices.
+---
+
+
+# Frontend Development Guidelines
+
+**(React · TypeScript · Suspense-First · Production-Grade)**
+
+You are a **senior frontend engineer** operating under strict architectural and performance standards.
+
+Your goal is to build **scalable, predictable, and maintainable React applications** using:
+
+* Suspense-first data fetching
+* Feature-based code organization
+* Strict TypeScript discipline
+* Performance-safe defaults
+
+This skill defines **how frontend code must be written**, not merely how it *can* be written.
+
+---
+
+## 1. Frontend Feasibility & Complexity Index (FFCI)
+
+Before implementing a component, page, or feature, assess feasibility.
+
+### FFCI Dimensions (1–5)
+
+| Dimension             | Question                                                         |
+| --------------------- | ---------------------------------------------------------------- |
+| **Architectural Fit** | Does this align with feature-based structure and Suspense model? |
+| **Complexity Load**   | How complex is state, data, and interaction logic?               |
+| **Performance Risk**  | Does it introduce rendering, bundle, or CLS risk?                |
+| **Reusability**       | Can this be reused without modification?                         |
+| **Maintenance Cost**  | How hard will this be to reason about in 6 months?               |
+
+### Score Formula
+
+```
+FFCI = (Architectural Fit + Reusability + Performance) − (Complexity + Maintenance Cost)
+```
+
+**Range:** `-5 → +15`
+
+### Interpretation
+
+| FFCI      | Meaning    | Action            |
+| --------- | ---------- | ----------------- |
+| **10–15** | Excellent  | Proceed           |
+| **6–9**   | Acceptable | Proceed with care |
+| **3–5**   | Risky      | Simplify or split |
+| **≤ 2**   | Poor       | Redesign          |
+
+---
+
+## 2. Core Architectural Doctrine (Non-Negotiable)
+
+### 1. Suspense Is the Default
+
+* `useSuspenseQuery` is the **primary** data-fetching hook
+* No `isLoading` conditionals
+* No early-return spinners
+
+### 2. Lazy Load Anything Heavy
+
+* Routes
+* Feature entry components
+* Data grids, charts, editors
+* Large dialogs or modals
+
+### 3. Feature-Based Organization
+
+* Domain logic lives in `features/`
+* Reusable primitives live in `components/`
+* Cross-feature coupling is forbidden
+
+### 4. TypeScript Is Strict
+
+* No `any`
+* Explicit return types
+* `import type` always
+* Types are first-class design artifacts
+
+---
+
+## 3. When to Use This Skill
+
+Use **frontend-dev-guidelines** when:
+
+* Creating components or pages
+* Adding new features
+* Fetching or mutating data
+* Setting up routing
+* Styling with MUI
+* Addressing performance issues
+* Reviewing or refactoring frontend code
+
+---
+
+## 4. Quick Start Checklists
+
+### New Component Checklist
+
+* [ ] `React.FC<Props>` with explicit props interface
+* [ ] Lazy loaded if non-trivial
+* [ ] Wrapped in `<SuspenseLoader>`
+* [ ] Uses `useSuspenseQuery` for data
+* [ ] No early returns
+* [ ] Handlers wrapped in `useCallback`
+* [ ] Styles inline if <100 lines
+* [ ] Default export at bottom
+* [ ] Uses `useMuiSnackbar` for feedback
+
+---
+
+### New Feature Checklist
+
+* [ ] Create `features/{feature-name}/`
+* [ ] Subdirs: `api/`, `components/`, `hooks/`, `helpers/`, `types/`
+* [ ] API layer isolated in `api/`
+* [ ] Public exports via `index.ts`
+* [ ] Feature entry lazy loaded
+* [ ] Suspense boundary at feature level
+* [ ] Route defined under `routes/`
+
+---
+
+## 5. Import Aliases (Required)
+
+| Alias         | Path             |
+| ------------- | ---------------- |
+| `@/`          | `src/`           |
+| `~types`      | `src/types`      |
+| `~components` | `src/components` |
+| `~features`   | `src/features`   |
+
+Aliases must be used consistently. Relative imports beyond one level are discouraged.
+
+---
+
+## 6. Component Standards
+
+### Required Structure Order
+
+1. Types / Props
+2. Hooks
+3. Derived values (`useMemo`)
+4. Handlers (`useCallback`)
+5. Render
+6. Default export
+
+### Lazy Loading Pattern
+
+```ts
+const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
+```
+
+Always wrapped in `<SuspenseLoader>`.
+
+---
+
+## 7. Data Fetching Doctrine
+
+### Primary Pattern
+
+* `useSuspenseQuery`
+* Cache-first
+* Typed responses
+
+### Forbidden Patterns
+
+❌ `isLoading`
+❌ manual spinners
+❌ fetch logic inside components
+❌ API calls without feature API layer
+
+### API Layer Rules
+
+* One API file per feature
+* No inline axios calls
+* No `/api/` prefix in routes
+
+---
+
+## 8. Routing Standards (TanStack Router)
+
+* Folder-based routing only
+* Lazy load route components
+* Breadcrumb metadata via loaders
+
+```ts
+export const Route = createFileRoute('/my-route/')({
+  component: MyPage,
+  loader: () => ({ crumb: 'My Route' }),
+});
+```
+
+---
+
+## 9. Styling Standards (MUI v7)
+
+### Inline vs Separate
+
+* `<100 lines`: inline `sx`
+* `>100 lines`: `{Component}.styles.ts`
+
+### Grid Syntax (v7 Only)
+
+```tsx
+<Grid size={{ xs: 12, md: 6 }} /> // ✅
+<Grid xs={12} md={6} />          // ❌
+```
+
+Theme access must always be type-safe.
+
+---
+
+## 10. Loading & Error Handling
+
+### Absolute Rule
+
+❌ Never return early loaders
+✅ Always rely on Suspense boundaries
+
+### User Feedback
+
+* `useMuiSnackbar` only
+* No third-party toast libraries
+
+---
+
+## 11. Performance Defaults
+
+* `useMemo` for expensive derivations
+* `useCallback` for passed handlers
+* `React.memo` for heavy pure components
+* Debounce search (300–500ms)
+* Cleanup effects to avoid leaks
+
+Performance regressions are bugs.
+
+---
+
+## 12. TypeScript Standards
+
+* Strict mode enabled
+* No implicit `any`
+* Explicit return types
+* JSDoc on public interfaces
+* Types colocated with feature
+
+---
+
+## 13. Canonical File Structure
+
+```
+src/
+  features/
+    my-feature/
+      api/
+      components/
+      hooks/
+      helpers/
+      types/
+      index.ts
+
+  components/
+    SuspenseLoader/
+    CustomAppBar/
+
+  routes/
+    my-route/
+      index.tsx
+```
+
+---
+
+## 14. Canonical Component Template
+
+```ts
+import React, { useState, useCallback } from 'react';
+import { Box, Paper } from '@mui/material';
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { featureApi } from '../api/featureApi';
+import type { FeatureData } from '~types/feature';
+
+interface MyComponentProps {
+  id: number;
+  onAction?: () => void;
+}
+
+export const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {
+  const [state, setState] = useState('');
+
+  const { data } = useSuspenseQuery<FeatureData>({
+    queryKey: ['feature', id],
+    queryFn: () => featureApi.getFeature(id),
+  });
+
+  const handleAction = useCallback(() => {
+    setState('updated');
+    onAction?.();
+  }, [onAction]);
+
+  return (
+    <Box sx={{ p: 2 }}>
+      <Paper sx={{ p: 3 }}>
+        {/* Content */}
+      </Paper>
+    </Box>
+  );
+};
+
+export default MyComponent;
+```
+
+---
+
+## 15. Anti-Patterns (Immediate Rejection)
+
+❌ Early loading returns
+❌ Feature logic in `components/`
+❌ Shared state via prop drilling instead of hooks
+❌ Inline API calls
+❌ Untyped responses
+❌ Multiple responsibilities in one component
+
+---
+
+## 16. Integration With Other Skills
+
+* **frontend-design** → Visual systems & aesthetics
+* **page-cro** → Layout hierarchy & conversion logic
+* **analytics-tracking** → Event instrumentation
+* **backend-dev-guidelines** → API contract alignment
+* **error-tracking** → Runtime observability
+
+---
+
+## 17. Operator Validation Checklist
+
+Before finalizing code:
+
+* [ ] FFCI ≥ 6
+* [ ] Suspense used correctly
+* [ ] Feature boundaries respected
+* [ ] No early returns
+* [ ] Types explicit and correct
+* [ ] Lazy loading applied
+* [ ] Performance safe
+
+---
+
+## 18. Skill Status
+
+**Status:** Stable, opinionated, and enforceable
+**Intended Use:** Production React codebases with long-term maintenance horizons
+

package/skills/frontend-dev-guidelines/resources/common-patterns.md

@@ -0,0 +1,331 @@
+# Common Patterns
+
+Frequently used patterns for forms, authentication, DataGrid, dialogs, and other common UI elements.
+
+---
+
+## Authentication with useAuth
+
+### Getting Current User
+
+```typescript
+import { useAuth } from '@/hooks/useAuth';
+
+export const MyComponent: React.FC = () => {
+    const { user } = useAuth();
+
+    // Available properties:
+    // - user.id: string
+    // - user.email: string
+    // - user.username: string
+    // - user.roles: string[]
+
+    return (
+        <div>
+            <p>Logged in as: {user.email}</p>
+            <p>Username: {user.username}</p>
+            <p>Roles: {user.roles.join(', ')}</p>
+        </div>
+    );
+};
+```
+
+**NEVER make direct API calls for auth** - always use `useAuth` hook.
+
+---
+
+## Forms with React Hook Form
+
+### Basic Form
+
+```typescript
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { TextField, Button } from '@mui/material';
+import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
+
+// Zod schema for validation
+const formSchema = z.object({
+    username: z.string().min(3, 'Username must be at least 3 characters'),
+    email: z.string().email('Invalid email address'),
+    age: z.number().min(18, 'Must be 18 or older'),
+});
+
+type FormData = z.infer<typeof formSchema>;
+
+export const MyForm: React.FC = () => {
+    const { showSuccess, showError } = useMuiSnackbar();
+
+    const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
+        resolver: zodResolver(formSchema),
+        defaultValues: {
+            username: '',
+            email: '',
+            age: 18,
+        },
+    });
+
+    const onSubmit = async (data: FormData) => {
+        try {
+            await api.submitForm(data);
+            showSuccess('Form submitted successfully');
+        } catch (error) {
+            showError('Failed to submit form');
+        }
+    };
+
+    return (
+        <form onSubmit={handleSubmit(onSubmit)}>
+            <TextField
+                {...register('username')}
+                label='Username'
+                error={!!errors.username}
+                helperText={errors.username?.message}
+            />
+
+            <TextField
+                {...register('email')}
+                label='Email'
+                error={!!errors.email}
+                helperText={errors.email?.message}
+                type='email'
+            />
+
+            <TextField
+                {...register('age', { valueAsNumber: true })}
+                label='Age'
+                error={!!errors.age}
+                helperText={errors.age?.message}
+                type='number'
+            />
+
+            <Button type='submit' variant='contained'>
+                Submit
+            </Button>
+        </form>
+    );
+};
+```
+
+---
+
+## Dialog Component Pattern
+
+### Standard Dialog Structure
+
+From BEST_PRACTICES.md - All dialogs should have:
+- Icon in title
+- Close button (X)
+- Action buttons at bottom
+
+```typescript
+import { Dialog, DialogTitle, DialogContent, DialogActions, Button, IconButton } from '@mui/material';
+import { Close, Info } from '@mui/icons-material';
+
+interface MyDialogProps {
+    open: boolean;
+    onClose: () => void;
+    onConfirm: () => void;
+}
+
+export const MyDialog: React.FC<MyDialogProps> = ({ open, onClose, onConfirm }) => {
+    return (
+        <Dialog open={open} onClose={onClose} maxWidth='sm' fullWidth>
+            <DialogTitle>
+                <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+                    <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+                        <Info color='primary' />
+                        Dialog Title
+                    </Box>
+                    <IconButton onClick={onClose} size='small'>
+                        <Close />
+                    </IconButton>
+                </Box>
+            </DialogTitle>
+
+            <DialogContent>
+                {/* Content here */}
+            </DialogContent>
+
+            <DialogActions>
+                <Button onClick={onClose}>Cancel</Button>
+                <Button onClick={onConfirm} variant='contained'>
+                    Confirm
+                </Button>
+            </DialogActions>
+        </Dialog>
+    );
+};
+```
+
+---
+
+## DataGrid Wrapper Pattern
+
+### Wrapper Component Contract
+
+From BEST_PRACTICES.md - DataGrid wrappers should accept:
+
+**Required Props:**
+- `rows`: Data array
+- `columns`: Column definitions
+- Loading/error states
+
+**Optional Props:**
+- Toolbar components
+- Custom actions
+- Initial state
+
+```typescript
+import { DataGridPro } from '@mui/x-data-grid-pro';
+import type { GridColDef } from '@mui/x-data-grid-pro';
+
+interface DataGridWrapperProps {
+    rows: any[];
+    columns: GridColDef[];
+    loading?: boolean;
+    toolbar?: React.ReactNode;
+    onRowClick?: (row: any) => void;
+}
+
+export const DataGridWrapper: React.FC<DataGridWrapperProps> = ({
+    rows,
+    columns,
+    loading = false,
+    toolbar,
+    onRowClick,
+}) => {
+    return (
+        <DataGridPro
+            rows={rows}
+            columns={columns}
+            loading={loading}
+            slots={{ toolbar: toolbar ? () => toolbar : undefined }}
+            onRowClick={(params) => onRowClick?.(params.row)}
+            // Standard configuration
+            pagination
+            pageSizeOptions={[25, 50, 100]}
+            initialState={{
+                pagination: { paginationModel: { pageSize: 25 } },
+            }}
+        />
+    );
+};
+```
+
+---
+
+## Mutation Patterns
+
+### Update with Cache Invalidation
+
+```typescript
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
+
+export const useUpdateEntity = () => {
+    const queryClient = useQueryClient();
+    const { showSuccess, showError } = useMuiSnackbar();
+
+    return useMutation({
+        mutationFn: ({ id, data }: { id: number; data: any }) =>
+            api.updateEntity(id, data),
+
+        onSuccess: (result, variables) => {
+            // Invalidate affected queries
+            queryClient.invalidateQueries({ queryKey: ['entity', variables.id] });
+            queryClient.invalidateQueries({ queryKey: ['entities'] });
+
+            showSuccess('Entity updated');
+        },
+
+        onError: () => {
+            showError('Failed to update entity');
+        },
+    });
+};
+
+// Usage
+const updateEntity = useUpdateEntity();
+
+const handleSave = () => {
+    updateEntity.mutate({ id: 123, data: { name: 'New Name' } });
+};
+```
+
+---
+
+## State Management Patterns
+
+### TanStack Query for Server State (PRIMARY)
+
+Use TanStack Query for **all server data**:
+- Fetching: useSuspenseQuery
+- Mutations: useMutation
+- Caching: Automatic
+- Synchronization: Built-in
+
+```typescript
+// ✅ CORRECT - TanStack Query for server data
+const { data: users } = useSuspenseQuery({
+    queryKey: ['users'],
+    queryFn: () => userApi.getUsers(),
+});
+```
+
+### useState for UI State
+
+Use `useState` for **local UI state only**:
+- Form inputs (uncontrolled)
+- Modal open/closed
+- Selected tab
+- Temporary UI flags
+
+```typescript
+// ✅ CORRECT - useState for UI state
+const [modalOpen, setModalOpen] = useState(false);
+const [selectedTab, setSelectedTab] = useState(0);
+```
+
+### Zustand for Global Client State (Minimal)
+
+Use Zustand only for **global client state**:
+- Theme preference
+- Sidebar collapsed state
+- User preferences (not from server)
+
+```typescript
+import { create } from 'zustand';
+
+interface AppState {
+    sidebarOpen: boolean;
+    toggleSidebar: () => void;
+}
+
+export const useAppState = create<AppState>((set) => ({
+    sidebarOpen: true,
+    toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
+}));
+```
+
+**Avoid prop drilling** - use context or Zustand instead.
+
+---
+
+## Summary
+
+**Common Patterns:**
+- ✅ useAuth hook for current user (id, email, roles, username)
+- ✅ React Hook Form + Zod for forms
+- ✅ Dialog with icon + close button
+- ✅ DataGrid wrapper contracts
+- ✅ Mutations with cache invalidation
+- ✅ TanStack Query for server state
+- ✅ useState for UI state
+- ✅ Zustand for global client state (minimal)
+
+**See Also:**
+- [data-fetching.md](data-fetching.md) - TanStack Query patterns
+- [component-patterns.md](component-patterns.md) - Component structure
+- [loading-and-error-states.md](loading-and-error-states.md) - Error handling