# Initialize VDK with Windsurf integration
vdk init --ide-integration

# Or setup Windsurf specifically
vdk integrations --setup windsurf

# Check if Windsurf is detected
vdk integrations --scan

# Setup Windsurf integration
vdk integrations --setup windsurf

# Verify setup
vdk integrations --list

.windsurf/
├── rules/
│   ├── project-overview.md       # Main project context
│   ├── development-guidelines.md # Development standards
│   ├── architecture-patterns.md  # Architectural guidance
│   ├── code-conventions.md       # Coding standards
│   └── ai-agent-config.md        # AI agent configurations
├── workspace.json                # Windsurf workspace settings
└── preferences.json              # User preferences

# Project Overview

## Project Context
This is a Next.js 15 application built with TypeScript, featuring a modern tech stack including Tailwind CSS for styling, Prisma for database operations, and NextAuth.js for authentication.

**Key Characteristics:**
- App Router architecture for optimal performance
- Server-first approach with selective client components
- Type-safe database operations with Prisma
- Responsive design with Tailwind CSS
- Secure authentication flow with NextAuth.js

## Technology Stack
**Primary Technologies:**
- Framework: Next.js 15 (App Router)
- Language: TypeScript 5.0+
- Runtime: Node.js 18+
- Database: PostgreSQL with Prisma ORM
- Styling: Tailwind CSS v3
- Authentication: NextAuth.js v4
- State Management: Zustand
- Testing: Jest + React Testing Library
- Deployment: Vercel

**Development Tools:**
- Package Manager: pnpm
- Linting: ESLint + Prettier
- Type Checking: TypeScript strict mode
- Git Hooks: Husky + lint-staged

## Project Structure

## Development Workflow
1. **Local Development**: Use `pnpm dev` for development server
2. **Database Management**: Use Prisma Studio for database inspection
3. **Type Safety**: Run `pnpm type-check` before commits
4. **Testing**: Execute `pnpm test` for unit tests
5. **Code Quality**: Lint with `pnpm lint` and format with `pnpm format`

# Development Guidelines

## Component Development

**Component Structure:**
```typescript
interface ComponentProps {
  // Props definition with JSDoc
  /** User data object */
  user: User;
  /** Optional click handler */
  onClick?: () => void;
}

/**
 * UserCard component displays user information in a card format
 * @param props - Component props
 */
export default function UserCard({ user, onClick }: ComponentProps) {
  return (
    <div className="p-4 border rounded-lg hover:shadow-md transition-shadow">
      <h3 className="text-lg font-semibold">{user.name}</h3>
      <p className="text-gray-600">{user.email}</p>
      {onClick && (
        <button 
          onClick={onClick}
          className="mt-2 px-3 py-1 bg-blue-500 text-white rounded"
        >
          View Profile
        </button>
      )}
    </div>
  );
}

// Use interfaces for object shapes
interface User {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
}

// Use type aliases for unions, primitives, and computed types
type Status = 'pending' | 'approved' | 'rejected';
type UserWithStatus = User & { status: Status };

// Good: Specific generic constraints
interface ApiResponse<T extends Record<string, unknown>> {
  data: T;
  message: string;
  success: boolean;
}

// Generic utility types
type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;

// app/users/page.tsx - Server Component
import { getUsers } from '@/lib/api/users';

export default async function UsersPage() {
  const users = await getUsers(); // Server-side data fetching
  
  return (
    <div>
      <h1>Users</h1>
      <UsersList users={users} />
    </div>
  );
}

'use client'

import { useState, useTransition } from 'react';

export default function InteractiveForm() {
  const [isPending, startTransition] = useTransition();
  const [formData, setFormData] = useState({});
  
  const handleSubmit = () => {
    startTransition(() => {
      // Async operation
    });
  };
  
  return (
    <form onSubmit={handleSubmit}>
      {/* Form content */}
    </form>
  );
}

### AI Agent Configuration (ai-agent-config.md)

```markdown
# AI Agent Configuration

## AI Agent Personas

### Developer Agent
**Role**: Senior Full-Stack Developer
**Expertise**: Next.js, TypeScript, React, Node.js
**Focus Areas**:
- Component architecture and design patterns
- API development and database operations
- Performance optimization and best practices
- Code review and refactoring suggestions

**Communication Style**: Technical, detailed, with code examples

### Designer Agent  
**Role**: UI/UX Designer & Frontend Specialist
**Expertise**: Tailwind CSS, responsive design, accessibility
**Focus Areas**:
- Component styling and visual hierarchy
- Responsive design implementation
- Accessibility compliance (WCAG 2.1)
- User experience optimization

**Communication Style**: Visual-focused, design-conscious

### DevOps Agent
**Role**: Infrastructure and Deployment Specialist  
**Expertise**: Vercel, Docker, CI/CD, monitoring
**Focus Areas**:
- Deployment configuration and optimization
- Environment setup and management
- Performance monitoring and analytics
- Security best practices

**Communication Style**: Infrastructure-focused, security-conscious

## Agent Instructions

### Context Awareness Rules

1. **Always consider the current file context**: Understand the file type, location, and purpose
2. **Respect the established patterns**: Follow existing code patterns and conventions
3. **Maintain consistency**: Ensure suggestions align with project architecture
4. **Consider performance implications**: Prioritize optimal solutions for Next.js
5. **Include accessibility**: Always consider accessibility in UI components
6. **Security first**: Apply security best practices to all suggestions

## Specialized Workflows

### Component Creation Workflow

**Step 1: Analyze Context**
- Determine if server or client component is needed
- Identify reusability requirements
- Consider accessibility needs

**Step 2: Create Structure**
```typescript
// 1. Define props interface with JSDoc
interface ComponentProps {
  /** Description */
  prop: Type;
}

// 2. Create component with proper typing
export default function Component(props: ComponentProps) {
  // Implementation
}

// 3. Add display name for debugging
Component.displayName = 'Component';

// app/api/users/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const createUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
});

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const validatedData = createUserSchema.parse(body);
    
    // Database operation
    const user = await createUser(validatedData);
    
    return NextResponse.json(user, { status: 201 });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { error: 'Validation failed', details: error.errors },
        { status: 400 }
      );
    }
    
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

## Windsurf-Specific Features

### XML-Enhanced Tags

Windsurf supports rich XML-like tags for enhanced AI understanding:

#### Project Context Tags
High-level project information and business logic:
```markdown
<!-- Project Context -->
E-commerce platform with multi-tenant architecture, supporting 
vendor management, product catalogs, order processing, and 
payment integration with Stripe.

<!-- Technology Stack -->
Frontend: Next.js 15 + TypeScript + Tailwind CSS
Backend: Next.js API Routes + Prisma + PostgreSQL  
Auth: NextAuth.js with JWT + OAuth providers
Payments: Stripe integration
Deployment: Vercel with edge functions

<!-- Coding Standards -->
1. Use TypeScript strict mode
2. Prefer server components over client components
3. Implement proper error boundaries
4. Use Tailwind utility classes over custom CSS
5. Follow the repository pattern for data access

<!-- Agent Instructions -->
When suggesting code changes:
- Always include proper TypeScript types
- Consider performance implications
- Ensure accessibility compliance
- Follow the established file structure
- Include error handling

<!-- Agent Routing Rules -->
## Agent Selection Rules

**Code Generation**: Use Developer Agent
- Component creation
- API route development  
- Database operations
- Business logic implementation

**UI/UX Tasks**: Use Designer Agent
- Styling and layout
- Responsive design
- Component variants
- Accessibility improvements

**Infrastructure**: Use DevOps Agent
- Deployment configuration
- Environment setup
- Performance optimization
- Security implementations

{
  "name": "Next.js Project",
  "version": "2.0.1",
  "settings": {
    "ai": {
      "contextAwareness": true,
      "projectMemory": true,
      "agentPersonas": true,
      "multiAgentMode": true
    },
    "rules": {
      "enabled": true,
      "autoUpdate": true,
      "xmlTagsEnabled": true,
      "agentInstructions": true
    },
    "editor": {
      "formatOnSave": true,
      "typescript": {
        "strictMode": true,
        "noImplicitAny": true
      }
    }
  },
  "vdk": {
    "integration": "windsurf",
    "version": "2.0.1",
    "rulesPath": ".windsurf/rules/",
    "lastUpdated": "2024-01-15T10:30:00Z",
    "features": {
      "xmlTags": true,
      "multiAgent": true,
      "contextMemory": true
    }
  }
}

{
  "ai": {
    "preferredAgent": "developer",
    "contextDepth": "comprehensive",
    "suggestionStyle": "detailed"
  },
  "rules": {
    "validationLevel": "strict",
    "autoComplete": true,
    "showHints": true
  },
  "workspace": {
    "autoSave": true,
    "minimap": true,
    "wordWrap": "on"
  }
}

<!-- Custom Agents -->
## Database Agent
**Specialization**: Prisma ORM, PostgreSQL, data modeling
**Trigger Keywords**: "database", "prisma", "schema", "migration"
**Instructions**:
- Always consider data integrity
- Suggest proper indexing strategies
- Include error handling for database operations
- Validate data types and constraints

## Testing Agent  
**Specialization**: Jest, React Testing Library, E2E testing
**Trigger Keywords**: "test", "testing", "spec", "coverage"
**Instructions**:
- Write comprehensive test cases
- Include edge cases and error scenarios
- Suggest proper mocking strategies
- Ensure good test coverage

<!-- Context Switching Rules -->
## File-Based Context

**Component Files** (*.tsx in components/):
- Use Designer Agent for styling questions
- Use Developer Agent for logic implementation
- Focus on reusability and accessibility

**API Routes** (app/api/*):
- Use Developer Agent for implementation
- Use DevOps Agent for deployment concerns
- Focus on security and performance

**Database Files** (prisma/*):
- Use Database Agent for schema changes
- Consider migration strategies
- Validate data relationships

<!-- Templates -->
## Feature Implementation Template

1. **Planning Phase**
   - Analyze requirements with Developer Agent
   - Design UI/UX with Designer Agent
   - Plan data model with Database Agent

2. **Implementation Phase**
   - Create database schema (Database Agent)
   - Implement API routes (Developer Agent)  
   - Build UI components (Designer Agent)
   - Add tests (Testing Agent)

3. **Review Phase**
   - Code review (Developer Agent)
   - Security review (DevOps Agent)
   - Accessibility check (Designer Agent)
   - Performance analysis (DevOps Agent)

# Check if XML tags are enabled
cat .windsurf/workspace.json | grep xmlTagsEnabled

# Enable XML tags
vdk config set windsurf.xmlTags true

# Regenerate rules
vdk init --overwrite --ide windsurf

# Verify agent configuration
vdk validate --ide windsurf --check agents

# Reset agent configuration
vdk integrations --reset windsurf
vdk integrations --setup windsurf

# Force rule regeneration
vdk init --overwrite --ide windsurf

# Clear Windsurf cache
rm -rf ~/.windsurf/cache/

# Restart Windsurf
pkill windsurf && windsurf .

# Debug Windsurf integration
VDK_DEBUG_WINDSURF=true vdk integrations --setup windsurf

# Windsurf debug logs
tail -f ~/.windsurf/logs/main.log

.windsurf/rules/
├── project/
│   ├── overview.md           # Project context
│   └── architecture.md       # System architecture
├── frontend/
│   ├── components.md         # Component patterns
│   ├── styling.md           # CSS and design
│   └── state-management.md  # State patterns
├── backend/
│   ├── api-design.md        # API patterns
│   ├── database.md          # Database operations
│   └── security.md          # Security practices
└── agents/
    ├── developer.md         # Developer agent config
    ├── designer.md          # Designer agent config
    └── devops.md           # DevOps agent config

<!-- Error Handling Strategy -->
Implement consistent error handling across the application:
- Use error boundaries for React components
- Return proper HTTP status codes from API routes
- Log errors with appropriate context
- Display user-friendly error messages

<!-- Feature Development Workflow -->
1. Requirements Analysis (Developer Agent)
2. UI/UX Design (Designer Agent)  
3. Implementation (Developer Agent)
4. Testing (Testing Agent)
5. Deployment (DevOps Agent)

<!-- Cross-Agent Coordination -->
- All agents should respect TypeScript conventions
- UI suggestions should consider API constraints
- Database changes should trigger security reviews
- Performance considerations across all domains