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

Aspect Requirement

Format Plain markdown

Frontmatter None (forbidden)

Character limit 12,000 max

File location .windsurf/rules (single file)

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:

• Focus on project-specific patterns - AI already knows general best practices

• Use concise language - Every word counts

• Limit code examples - Only essential patterns

• Skip obvious practices - Don't repeat what AI knows

• 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

Mistake Fix

Adding YAML frontmatter No frontmatter allowed - plain markdown only

Exceeding 12,000 chars Prioritize project-specific content, trim aggressively

Multiple files All content in single .windsurf/rules file

Generic best practices Focus on project-specific patterns

Verbose examples Keep examples minimal and focused

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:

• Strip all frontmatter - Remove YAML headers completely

• Combine multiple files - Merge into single document

• Prioritize content - Keep project-specific, remove generic

• Trim examples - Only essential code samples

• 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

• Be concise - 12,000 character limit means prioritize

• Single file - Combine all project context cohesively

• Clear structure - Use headers for scannable sections

• Real examples - Show actual code patterns from project

• Update regularly - Keep in sync with architecture changes

• No frontmatter - Plain markdown only, no YAML

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