feature-builder

What this skill does

# Feature Builder

This skill builds complete, production-ready React features with proper separation of concerns across presentation, business logic, and data access layers.

## Purpose

Transform feature requirements into complete, working implementations that include:
1. **UI Components** - Using react-component-generator
2. **Business Logic** - Hooks, stores, validation, transformations
3. **API Integration** - Data fetching, mutations, caching
4. **State Management** - Zustand for global state, React Query for server state
5. **Error Handling** - Comprehensive error management
6. **Type Safety** - Full TypeScript support

## When to Use This Skill

Use this skill when:
- User requests a complete feature (not just a UI component)
- Request involves business logic and data management
- User mentions: "implement", "build", "create feature"
- Examples:
  - "Implement user authentication"
  - "Build a shopping cart"
  - "Create a product listing with filters"
  - "Add file upload functionality"
  - "Implement real-time notifications"

## Architecture

Features are built with **3-layer architecture**:

```
┌──────────────────────────────────────┐
│   Presentation Layer                 │  ← UI Components
│   (React components, Tailwind CSS)   │
├──────────────────────────────────────┤
│   Business Logic Layer               │  ← Hooks, Stores, Validation
│   (Zustand, hooks, utils)            │
├──────────────────────────────────────┤
│   Data Access Layer                  │  ← API Calls, React Query
│   (API client, queries, mutations)   │
└──────────────────────────────────────┘
```

Reference `references/layered-architecture.md` for complete details.

## Workflow

### Step 1: Analyze Feature Request

When user requests a feature, analyze:

1. **Feature Type**:
   - Authentication/Authorization
   - CRUD operations
   - File handling
   - Real-time updates
   - Search/Filter
   - Complex workflows (multi-step, cart, checkout)

2. **Required Layers**:
   - Does it need UI? (Almost always yes)
   - Does it need business logic? (Forms, validation, calculations)
   - Does it need API integration? (Server data, persistence)
   - Does it need global state? (Shared across components)

3. **Dependencies**:
   - What other features does it depend on?
   - What APIs does it need?
   - What libraries are required? (React Query, Zustand, Zod)

### Step 2: Plan Architecture

Design the feature structure:

```
features/
└── [feature-name]/
    ├── components/         # Presentation Layer
    │   ├── FeatureMain.tsx
    │   ├── FeatureForm.tsx
    │   └── index.ts
    ├── hooks/              # Business Logic
    │   ├── useFeature.ts
    │   └── index.ts
    ├── stores/             # Global State (if needed)
    │   ├── featureStore.ts
    │   └── index.ts
    ├── api/                # Data Access
    │   ├── featureApi.ts
    │   ├── queries.ts
    │   └── index.ts
    ├── utils/              # Utilities
    │   ├── validation.ts
    │   └── transforms.ts
    ├── types/              # TypeScript Types
    │   └── feature.types.ts
    └── index.ts            # Public API
```

### Step 3: Clarify Requirements (Interactive)

Use `AskUserQuestion` to gather necessary details:

```typescript
AskUserQuestion({
  questions: [
    {
      question: "What data needs to be managed?",
      header: "Data",
      multiSelect: false,
      options: [
        { label: "User data", description: "Authentication, profiles" },
        { label: "Products", description: "E-commerce items" },
        { label: "Posts/Content", description: "Blog posts, articles" },
        { label: "Files", description: "File uploads/downloads" },
      ]
    },
    {
      question: "What operations are needed?",
      header: "Operations",
      multiSelect: true,
      options: [
        { label: "Create", description: "Add new items" },
        { label: "Read/List", description: "Fetch and display data" },
        { label: "Update", description: "Modify existing items" },
        { label: "Delete", description: "Remove items" },
        { label: "Search", description: "Find specific items" },
        { label: "Filter", description: "Filter by criteria" },
      ]
    },
    {
      question: "Does this need authentication?",
      header: "Auth",
      multiSelect: false,
      options: [
        { label: "Yes, required", description: "User must be logged in" },
        { label: "Optional", description: "Works with or without auth" },
        { label: "No", description: "Public feature" },
      ]
    },
    {
      question: "Any additional requirements?",
      header: "Extra",
      multiSelect: false,
      options: [
        { label: "No, that's all", description: "Just the basics" },
        { label: "Yes, let me specify", description: "Use 'Other' to describe" },
      ]
    }
  ]
})
```

### Step 4: Generate Feature Code

Generate code for each layer:

#### 4.1 Types First

```typescript
// features/user-auth/types/auth.types.ts
export interface User {
  id: string;
  email: string;
  name: string;
  role: 'admin' | 'user';
}

export interface LoginCredentials {
  email: string;
  password: string;
}

export interface LoginResponse {
  user: User;
  accessToken: string;
  refreshToken: string;
}
```

#### 4.2 API Layer

```typescript
// features/user-auth/api/authApi.ts
export const authApi = {
  login: async (credentials: LoginCredentials): Promise<LoginResponse> => {
    const response = await fetch('/api/auth/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(credentials),
    });

    if (!response.ok) throw new Error('Login failed');
    return response.json();
  },
  // ... other methods
};

// features/user-auth/api/queries.ts
import { useMutation } from '@tanstack/react-query';

export function useLogin() {
  return useMutation({
    mutationFn: authApi.login,
    onSuccess: (data) => {
      // Handle success
    },
  });
}
```

#### 4.3 Business Logic Layer

```typescript
// features/user-auth/stores/authStore.ts
import { create } from 'zustand';

export const useAuthStore = create<AuthStore>((set) => ({
  user: null,
  token: null,
  isAuthenticated: false,
  setUser: (user) => set({ user, isAuthenticated: true }),
  setToken: (token) => set({ token }),
  clearAuth: () => set({ user: null, token: null, isAuthenticated: false }),
}));

// features/user-auth/hooks/useAuth.ts
export function useAuth() {
  const { setUser, setToken } = useAuthStore();
  const { mutate: login, isPending, error } = useLogin();

  const handleLogin = async (credentials: LoginCredentials) => {
    return new Promise((resolve, reject) => {
      login(credentials, {
        onSuccess: (data) => {
          setToken(data.accessToken);
          setUser(data.user);
          localStorage.setItem('token', data.accessToken);
          resolve(data);
        },
        onError: (error) => reject(error),
      });
    });
  };

  return { login: handleLogin, isLoading: isPending, error };
}

// features/user-auth/utils/validation.ts
import { z } from 'zod';

export const loginSchema = z.object({
  email: z.string().email('Invalid email'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
});
```

#### 4.4 Presentation Layer

```typescript
// features/user-auth/components/LoginForm.tsx
import { useAuth } from '../hooks/useAuth';
import { loginSchema } from '../utils/validation';

export const LoginForm: React.FC = () => {
  const { login, isLoading, error } = useAuth();
  const [formData, setFormData] = useState({ email: '', password: '' });
  const [validationErrors, setValidationErrors] = useState<Record<string, string>>({});

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();

    // Validate
    try {
      loginSchema.parse(formData);
      setValidationErrors({});
    } catch (err) {
      if (err instanceof z.ZodError) {
        const errors = err.errors.reduce((acc, error) => {
          ac