# Fork and clone the repository
git clone https://github.com/your-username/VDK-Blueprints.git
cd VDK-Blueprints

# Create a feature branch
git checkout -b feature/new-rule-name

# Set up development environment
npm install  # If package.json exists

.ai/
├── rules/                    # Main rules directory
│   ├── core/                # Core behavioral patterns
│   ├── languages/           # Programming languages
│   ├── technologies/        # Frameworks and tools
│   ├── stacks/             # Technology combinations
│   ├── tasks/              # Development workflows
│   ├── assistants/         # AI platform configs
│   └── tools/              # Development tools
├── schemas/                 # Validation schemas
├── templates/              # Contribution templates
└── scripts/                # Utility scripts

---
# === Core Identification ===
id: "unique-rule-id"
title: "Human Readable Title"
description: "Brief description of what this rule does"
version: "2.0.1"
lastUpdated: "2025-07-25"

# === Categorization ===
category: "technology"  # core|languages|technologies|stacks|tasks|assistants|tools
subcategory: "framework"  # Optional subcategory
complexity: "medium"  # simple|medium|complex
scope: "project"  # system|project|component|file
audience: "developer"  # developer|team-lead|architect
maturity: "stable"  # experimental|beta|stable|deprecated

# === Platform Compatibility ===
platforms:
  claude-code:
    compatible: true
    command: false
    memory: true
    namespace: "project"
    allowedTools: ["Read", "Write", "Edit"]
    mcpIntegration: false
  cursor:
    compatible: true
    activation: "auto-attached"
    globs: ["**/*.tsx", "**/*.jsx"]
    priority: "high"
  windsurf:
    compatible: true
    mode: "workspace"
    xmlTag: "react-patterns"
    characterLimit: 700
  github-copilot:
    compatible: true
    priority: 8
    reviewType: "code-quality"

# === Dependencies & Relationships ===
requires: []  # Required rules that must be loaded
suggests: ["typescript-modern", "tailwind4"]  # Recommended rules
conflicts: []  # Rules that conflict with this one
supersedes: []  # Rules this one replaces

# === Content Structure ===
contentSections:
  - "overview"
  - "patterns"
  - "examples"
  - "best-practices"
  - "common-mistakes"
---

# Rule Content Goes Here

## Overview
Brief explanation of what this rule covers and when to use it.

## Core Patterns
Key patterns and approaches the AI should follow.

## Examples
Concrete code examples showing the patterns in action.

## Best Practices
Guidelines for optimal implementation.

## Common Mistakes
What to avoid and how to prevent errors.

❌ Bad: "Write good React code"
✅ Good: "Use functional components with hooks. Prefer const assertions for better type inference. Always handle loading and error states in data fetching components."

## Data Fetching Pattern
```typescript
const UserProfile = ({ userId }: { userId: string }) => {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    fetchUser(userId)
      .then(setUser)
      .catch(err => setError(err.message))
      .finally(() => setLoading(false));
  }, [userId]);

  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage error={error} />;
  if (!user) return <NotFound />;

  return <UserCard user={user} />;
};

#### 3. Context-Aware Guidance
```markdown
## When to Apply
- ✅ React components that fetch data
- ✅ Components with async operations
- ❌ Pure presentational components
- ❌ Server-side rendering contexts

platforms:
  cursor:
    # Auto-activate for React files
    globs: ["**/*.tsx", "**/*.jsx", "src/components/**/*"]
    priority: "high"
  windsurf:
    # Memory-optimized version
    characterLimit: 500
    xmlTag: "react-data-fetching"

# Validate rule schema
./scripts/validate-rule.py .ai/rules/technologies/my-new-rule.mdc

# Validate all rules
./scripts/validate-all-rules.py

# Add to CLAUDE.md for testing
Test rule: .ai/rules/technologies/my-new-rule.mdc
Expected behavior: [Describe expected AI behavior]
Test scenarios: [List test cases]

# Add to .cursorrules for testing
Include new rule content
Test with file patterns: **/*.tsx
Expected auto-completion improvements

{
  "testRule": {
    "source": ".ai/rules/technologies/my-new-rule.mdc",
    "characterLimit": 700,
    "expectedBehavior": "Describe expected behavior"
  }
}

# 1. Create feature branch
git checkout -b feature/add-vue3-rule

# 2. Copy template
cp .ai/templates/rule-template.mdc .ai/rules/technologies/vue3.mdc

# 3. Write rule content
# Edit the rule file with your content

# 4. Validate rule
./scripts/validate-rule.py .ai/rules/technologies/vue3.mdc

# 5. Test with AI assistants
# Test rule with your preferred AI assistant

# 6. Commit changes
git add .ai/rules/technologies/vue3.mdc
git commit -m "feat: add Vue 3 development patterns rule"

# 7. Push and create PR
git push origin feature/add-vue3-rule

## Description
Brief description of the new rule or changes.

## Rule Details
- **Category**: technology
- **Target Technology**: Vue 3
- **Complexity**: medium
- **Platforms Tested**: Claude Code, Cursor

## Testing
- [ ] Schema validation passed
- [ ] Tested with Claude Code
- [ ] Tested with Cursor
- [ ] No conflicts with existing rules
- [ ] Performance impact assessed

## Checklist
- [ ] Rule follows template structure
- [ ] Metadata is complete and accurate
- [ ] Examples are practical and tested
- [ ] Documentation is clear
- [ ] Platform compatibility verified

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "customField": {
      "type": "string",
      "description": "Custom field for specialized rules"
    }
  }
}

# In rule metadata
requires: ["typescript-modern"]  # Must have TypeScript rule
suggests: ["react19", "nextjs"]  # Works well with these
conflicts: ["vue3"]              # Cannot coexist with Vue
supersedes: ["react18"]          # Replaces older version

platforms:
  windsurf:
    # Optimize for memory constraints
    characterLimit: 500
    essentialOnly: true
    xmlTag: "performance-critical"

i18n:
  supported: ["en", "es", "fr", "de"]
  defaultLocale: "en"
  translationRequired: false