Creating Windsurf Packages

Creating Windsurf Packages

Overview

Windsurf uses a single .windsurf/​rules file containing plain markdown instructions with NO frontmatter.

CRITICAL CONSTRAINTS:

• No frontmatter - Pure markdown only
• 12,000 character limit - Hard limit enforced by Windsurf
• Single file - All rules in one .windsurf/​rules file

Quick Reference

Creating Rules

Plain markdown with optional H1 title and organized sections:

# React Development Guidelines

Guidelines for building React applications in this project.

## Component Structure

- Use functional components with hooks
- Keep components under 200 lines
- Extract logic into custom hooks when appropriate
- Co-locate styles with components

## State Management

We use Zustand for global state:

- Create stores in `src/​stores/`
- Use selectors to prevent unnecessary re-renders
- Keep stores focused on single concerns

\`\`\`typescript
// Good: Focused store
const useAuthStore = create((set) => ({
  user: null,
  login: (user) => set({ user }),
  logout: () => set({ user: null }),
}));
\`\`\`

## Testing

- Write tests alongside components (`.test.tsx`)
- Use React Testing Library
- Test user behavior, not implementation details
- Aim for 80% coverage on new code

Character Budget Tips

To stay under 12,000 characters:

1. Focus on project-specific patterns - AI already knows general best practices
2. Use concise language - Every word counts
3. Limit code examples - Only essential patterns
4. Skip obvious practices - Don't repeat what AI knows
5. Reference external docs - Link instead of repeating

Example: Project-Specific Context

# Project Architecture

## Tech Stack

- **Frontend**: React 18 + TypeScript + Vite
- **Styling**: Tailwind CSS
- **State**: Zustand
- **Routing**: React Router v6
- **API**: REST with axios

## Directory Structure

\`\`\`
src/
  components/     # Reusable UI components
  features/       # Feature-specific code
  hooks/          # Custom React hooks
  stores/         # Zustand stores
  utils/          # Helper functions
  types/          # TypeScript types
\`\`\`

## Coding Conventions

- Use PascalCase for components
- Use camelCase for functions/​variables
- Use kebab-case for file names
- Export components as named exports

## API Integration

All API calls go through `src/​api/​client.ts`:

\`\`\`typescript
import { apiClient } from '@/​api/​client';

// Use the client
const users = await apiClient.get('/​users');
\`\`\`

## Environment Variables

Access via `import.meta.env`:

- `VITE_API_URL` - Backend API URL
- `VITE_APP_ENV` - Environment (dev/​staging/​prod)

Content Format

Standard markdown including:

• H1 title: Main heading (optional)
• H2/​H3 sections: Organize content
• Lists: Unordered and ordered
• Code blocks: With language specifiers
• Standard markdown: Bold, italic, links

Common Mistakes

Checking Character Count

Use this command to check character count:

wc -m .windsurf/​rules

Stay well under 12,000 to leave room for updates.

What to Include

High Priority (include these):

• Project-specific tech stack
• Directory structure and naming conventions
• API patterns unique to your project
• Custom tooling and scripts
• Environment-specific configuration
• Team conventions and workflows

Low Priority (skip these):

• General programming best practices
• Language syntax explanations
• Framework basics (React, TypeScript)
• Obvious code quality rules
• Verbose explanations of standard patterns

Example: Full Stack Project

# TaskMaster Development Guide

## Architecture

### Frontend
- React 18 with TypeScript
- Vite for build tooling
- Zustand for state management
- React Query for server state
- Tailwind CSS for styling

### Backend
- Node.js with Express
- PostgreSQL with Prisma ORM
- WebSocket for real-time features
- Redis for caching and pub/​sub
- JWT for authentication

## File Structure

\`\`\`
src/
  components/     # Reusable UI components
  features/       # Feature-based modules
  hooks/          # Custom React hooks
  lib/            # Utility functions
  pages/          # Route pages
  types/          # TypeScript types
\`\`\`

## Development Workflow

1. Create feature branch from `main`
2. Write tests first (TDD)
3. Implement feature
4. Run `pnpm test` and `pnpm lint`
5. Create PR with description
6. Merge after approval

## Testing

- Use Vitest for unit tests
- Use Playwright for E2E tests
- Aim for 80% coverage on new code
- Mock external dependencies

Compression Techniques

Verbose (100+ words):

When you are working with React components, it's very important to remember
that you should always use functional components with hooks instead of class
components. This is because hooks provide a more modern and flexible way to
manage state and side effects. Additionally, you should keep your components
small and focused on a single responsibility...

Concise (30 words):

## React Components

- Use functional components with hooks (no classes)
- Keep under 200 lines
- Single responsibility
- Custom hooks for complex logic

Migration from Other Formats

When converting to Windsurf:

1. Strip all frontmatter - Remove YAML headers completely
2. Combine multiple files - Merge into single document
3. Prioritize content - Keep project-specific, remove generic
4. Trim examples - Only essential code samples
5. Monitor length - Check character count regularly

Validation

Documentation: /​Users/​khaliqgant/​Projects/​prpm/​app/​packages/​converters/​docs/​windsurf.md

Schema location: /​Users/​khaliqgant/​Projects/​prpm/​app/​packages/​converters/​schemas/​windsurf.schema.json

Best Practices

1. Be concise - 12,000 character limit means prioritize
2. Single file - Combine all project context cohesively
3. Clear structure - Use headers for scannable sections
4. Real examples - Show actual code patterns from project
5. Update regularly - Keep in sync with architecture changes
6. No frontmatter - Plain markdown only, no YAML

---

Remember: Windsurf uses plain markdown with NO frontmatter. 12,000 character limit. Single .windsurf/​rules file.