Initial rules for cursor.

010-workflow.mdc

---
description: 
globs: 
alwaysApply: true
---
# Workflow Guidelines

## First Step for Any Task
- Before starting work on any task, always check the `.cursor/rules` directory for relevant guidance
- These documents contain established workflows, conventions, and requirements for different aspects of the project
- Following these rule files will ensure consistency and reduce rework
- If multiple rule files seem relevant, review all of them before proceeding

## Last Step for Any Task
- If you've learned new concepts, workflows, or best practices during task completion, suggest updates to the relevant rules
- For new workflows that aren't covered by existing rules, suggest creating a new rule file
- Evaluate whether tests should be added for your changes:
  - For functional code, new features, API changes, or bug fixes, tests are essential
  - For content-only changes like frontend changes or documentation updates, tests are typically not required
  - When in doubt, err on the side of adding tests - they provide long-term stability and prevent regressions
- Always run appropriate linting and type checking before considering a task complete:
  ```bash
  pnpm lint
  pnpm check-types
  ```
- Verify that no regressions are introduced by your changes

020-codebase-structure.mdc

---
description: 
globs: 
alwaysApply: true
---

# Codebase Structure and Commands -- THIS IS OUTOFDATE

## Project Structure

The project follows a monorepo structure using pnpm workspaces:

### Core Directories
- `apps/` - Main applications
  - `backend/` - Backend service built with Bun and Hono
  - `client/` - Web client application built with React and Vite
  - `extension/` - Browser extension for Kick platform enhancements using Plasmo
- `packages/` - Shared packages and utilities
  - `shared/` - Shared utilities and type definitions
  - `eslint-config/` - Shared eslint config
  - `typescript-config/` - Shared typescript config
- `.cursor/` - Project rules and documentation
- `.vscode/` - VS Code configuration

### Configuration Files
- `package.json` - Project dependencies and scripts
- `pnpm-workspace.yaml` - Workspace configuration
- `turbo.json` - Turborepo configuration
- `docker-compose.yml` - Docker configuration
- `.npmrc` - NPM configuration
- `.gitignore` - Git ignore configuration

## Available Commands

### Development Commands
```bash
# Start development servers
pnpm dev                    # Start all development servers
pnpm --filter @riftmaker/backend dev  # Start backend development server
pnpm --filter @riftmaker/client dev   # Start client development server
pnpm --filter @riftmaker/extension dev # Start extension development server
pnpm docker                 # Start services with Docker

# Code Quality
pnpm lint                  # Run linting
pnpm format               # Format code
pnpm check-types         # Type check all packages
```

### Database Commands (Backend)
```bash
pnpm --filter @riftmaker/backend db:push      # Push schema to database
pnpm --filter @riftmaker/backend db:generate  # Generate migrations from schema changes
pnpm --filter @riftmaker/backend db:migrate   # Apply migrations to database
pnpm --filter @riftmaker/backend db:studio    # Launch Drizzle Studio
```

### Build Commands
```bash
pnpm build                 # Build all packages
pnpm --filter @riftmaker/extension build    # Build only extension
pnpm --filter @riftmaker/client build       # Build only client
```

### Package Management
```bash
# Add dependencies to specific packages
pnpm add <package> --filter <package-name>      # Add production dependency
pnpm add -D <package> --filter <package-name>   # Add dev dependency
```

## Development Setup

1. Install dependencies:
   ```bash
   npm i -g pnpm
   pnpm install
   ```

2. Configure environment:
   - Create appropriate environment files for each app
   - Fill required environment variables

3. Start development:
   ```bash
   # Start all apps
   pnpm dev
   
   # Or start individual apps
   pnpm --filter @riftmaker/backend dev
   pnpm --filter @riftmaker/client dev
   pnpm --filter @riftmaker/extension dev
   ```

4. Build for production:
   ```bash
   pnpm build
   ```

## Best Practices

1. Always use pnpm for package management
2. Use the `--filter` flag when working with specific packages
3. Keep shared code in the `packages/shared` directory
4. Follow the established environment variable conventions
5. Run code quality checks before committing:
   ```bash
   pnpm lint
   pnpm check-types
   ``` 

030-coding-style.mdc

---
description: Coding Style: Guidelines for code formatting, naming conventions, and best practices
globs: **/*.ts, **/*.tsx, **/*.js, **/*.jsx
alwaysApply: true
---

# Coding Style Guidelines

## Technology-Specific Guidelines

### TypeScript
- Use TypeScript strictly - avoid `any` types
- Use interfaces for object shapes that will be extended
- Use type aliases for complex types and unions
- Use the latest TypeScript features appropriately

### React Components
- Use functional components with hooks
- Use named exports for components
- Keep components small and focused on a single responsibility
- Use proper prop typing

### Backend (Hono)
- Use middleware for cross-cutting concerns
- Validate request data with Zod
- Use proper error handling with structured responses
- Structure routes logically by resource

### Browser Extension (Plasmo)
- Follow Plasmo framework conventions
- Separate content scripts from background logic
- Keep performance in mind for extension code

## Comments and Documentation
- Write self-documenting code, no need to add extra comments
- Add comments for complex logic
- Document public APIs and interfaces
```typescript
/**
 * Fetches user data and handles pagination
 * @param page - The page number to fetch
 * @param limit - Number of items per page
 * @returns Paginated user data
 */
async function fetchUsers(page: number, limit: number): Promise<PaginatedResponse<User>> {
  // ...
}
```

## Styling
- Use Tailwind CSS for styling
- Follow component-based styling practices
- Use utility classes for one-off styling needs
- Extract common patterns to shared components

## Git Commit Guidelines

### Commit Messages
- Use conventional commits format
- Include ticket number when applicable
- Keep messages clear and concise
```bash
# Format: <type>(<scope>): <description>
feat(auth): add social login support
fix(api): handle pagination edge cases
chore(deps): update dependencies
```

### Branch Names
- Use feature/, bugfix/, hotfix/ prefixes
- Include ticket number when applicable
- Use kebab-case
```bash
feature/KR-123-user-authentication
bugfix/api-pagination
hotfix/login-crash
```

## Core Philosophy

- Code is primarily written for humans to read and understand, not just for computers to execute
- "Explicit is better than implicit. Simple is better than complex. Readability counts."
- Maintain consistency with existing code style when modifying files
- Keep code DRY (Don't Repeat Yourself)
- Prefer verbose variable names and maintainability over concise code

999-mdc-format.mdc

---
description: Use when user asks to create or update *.mdc files
globs: **/*.mdc
alwaysApply: false
---
# MDC File Format Guide

MDC (Markdown Configuration) files are used by Cursor to provide context-specific instructions to AI assistants. This guide explains how to create and maintain these files properly.

## File Structure

Each MDC file consists of two main parts:

1. **Frontmatter** - Configuration metadata at the top of the file
2. **Markdown Content** - The actual instructions in Markdown format

### Frontmatter

The frontmatter must be the first thing in the file and must be enclosed between triple-dash lines (`---`). Configuration should be based on the intended behavior:

```
---
# Configure your rule based on desired behavior:

description: Brief description of what the rule does
globs: **/*.js, **/*.ts  # Optional: Comma-separated list, not an array
alwaysApply: false       # Set to true for global rules
---
```

> **Important**: Despite the appearance, the frontmatter is not strictly YAML formatted. The `globs` field is a comma-separated list and should NOT include brackets `[]` or quotes `"`.

#### Guidelines for Setting Fields

- **description**: Should be agent-friendly and clearly describe when the rule is relevant. Format as `<topic>: <details>` for best results.
- **globs**: 
  - If a rule is only relevant in very specific situations, leave globs empty so it's loaded only when applicable to the user request.
  - If the only glob would match all files (like `**/*`), leave it empty and set `alwaysApply: true` instead.
  - Otherwise, be as specific as possible with glob patterns to ensure rules are only applied with relevant files.
- **alwaysApply**: Use sparingly for truly global guidelines.

#### Glob Pattern Examples

- **/*.js - All JavaScript files
- src/**/*.jsx - All JSX files in the src directory
- **/components/**/*.vue - All Vue files in any components directory

### Markdown Content

After the frontmatter, the rest of the file should be valid Markdown:

```markdown
# Title of Your Rule

## Section 1
- Guidelines and information
- Code examples

## Section 2
More detailed information...
```

## Special Features

### File References

You can reference other files from within an MDC file using the markdown link syntax:

```
[rule-name.mdc](mdc:location/of/the/rule.mdc)
```

When this rule is activated, the referenced file will also be included in the context.

### Code Blocks

Use fenced code blocks for examples:

````markdown
```javascript
// Example code
function example() {
  return "This is an example";
}
```
````

## Best Practices

1. **Clear Organization**
   - Use numbered prefixes (e.g., `01-workflow.mdc`) for sorting rules logically
   - Place task-specific rules in the `tasks/` subdirectory
   - Use descriptive filenames that indicate the rule's purpose

2. **Frontmatter Specificity**
   - Be specific with glob patterns to ensure rules are only applied in relevant contexts
   - Use `alwaysApply: true` for truly global guidelines
   - Make descriptions clear and concise so AI knows when to apply the rule

3. **Content Structure**
   - Start with a clear title (H1)
   - Use hierarchical headings (H2, H3, etc.) to organize content
   - Include examples where appropriate
   - Keep instructions clear and actionable

4. **File Size Considerations**
   - Keep files focused on a single topic or closely related topics
   - Split very large rule sets into multiple files and link them with references
   - Aim for under 300 lines per file when possible

## Usage in Cursor

When working with files in Cursor, rules are automatically applied when:

1. The file you're working on matches a rule's glob pattern
2. A rule has `alwaysApply: true` set in its frontmatter
3. The agent thinks the rule's description matches the user request
4. You explicitly reference a rule in a conversation with Cursor's AI

## Creating/Renaming/Removing Rules

   - When a rule file is added/renamed/removed, update also the list under 010-workflow.mdc.
   - When changs are made to multiple `mdc` files from a single request, review also [999-mdc-format](mdc:(mdc:.cursor/rules/999-mdc-format.mdc)) to consider whether to update it too.

## Updating Rules

When updating existing rules:

1. Maintain the frontmatter format
2. Keep the same glob patterns unless intentionally changing the rule's scope
3. Update the description if the purpose of the rule changes
4. Consider whether changes should propagate to related rules (e.g., CE versions)