Comprehensive project setup with VDK CLI, from installation to team collaboration

Project Setup Guide

This guide covers comprehensive project setup with VDK CLI, from initial installation through advanced configuration and team collaboration.

Prerequisites Checklist

Before starting, ensure you have:

✅ Node.js 22.0.0+ installed (Download)
✅ npm or pnpm package manager
✅ Git for version control
✅ An AI-powered IDE (Claude Code, Cursor, Windsurf, or VS Code with Copilot)
✅ A code project to enhance

Step 1: Install VDK CLI

Global Installation

# Using npm
npm install -g @vibe-dev-kit/cli

# Using pnpm (recommended)
pnpm add -g @vibe-dev-kit/cli

# Verify installation
vdk --version

Local Installation (Alternative)

# For project-specific installation
npm install --save-dev @vibe-dev-kit/cli

# Run via npx
npx vdk --version

Step 2: Project Analysis & Initialization

Basic Project Setup

# Navigate to your project
cd your-project-directory

# Initialize VDK
vdk init

Advanced Setup Options

# Deep analysis for comprehensive rules
vdk init --deep

# Specify custom output location
vdk init --outputPath ./ai-assistance

# Include specific IDE integration
vdk init --claude-code

# Enable watch mode for continuous updates
vdk init --watch

# Verbose output for debugging
vdk init --verbose

What Happens During Initialization

Project Scanning: VDK analyzes your codebase structure
Technology Detection: Identifies frameworks, languages, and tools
Pattern Recognition: Discovers architectural and coding patterns
Rule Generation: Creates AI assistant rules in .ai/rules/
Configuration Creation: Generates vdk.config.json

Example Output:

🔍 Scanning project at: /Users/dev/my-nextjs-app
📁 Analyzing project structure...
🔧 Technology Detection:
   - Framework: Next.js 15 (App Router)
   - Language: TypeScript
   - Styling: Tailwind CSS
   - Database: PostgreSQL + Prisma
   - Testing: Jest + React Testing Library

🎯 Pattern Analysis:
   - Architecture: Component-based with App Router
   - Patterns: Server Components, Custom Hooks, Repository Pattern
   - Organization: Feature-based directory structure

📝 Generated 15 AI rules in .ai/rules/
✅ VDK configuration created at vdk.config.json

Step 3: IDE Integration Setup

Automatic IDE Detection

# Scan for installed AI-powered IDEs
vdk integrations --scan

Example Output:

🔍 Scanning for IDE integrations...

✅ Detected IDE Integrations:
   • Claude Code (high confidence)
   • Cursor AI (medium confidence)

💤 Available IDEs (not detected):
   • Windsurf
   • GitHub Copilot

Setup Specific IDEs

Claude Code Setup

# Setup Claude Code integration
vdk integrations --setup claude-code

# Alternative: Include in initial setup
vdk init --claude-code

# Advanced setup with memory management
vdk claude-code --setup --update-memory

Generated Files:

├── CLAUDE.md                   # Project memory file
├── .claude/
│   ├── settings.json          # Claude-specific settings
│   └── commands/
│       ├── vdk-analyze.md     # Custom slash commands
│       ├── vdk-refresh.md
│       └── vdk-deploy.md

Cursor Setup

# Setup Cursor integration
vdk integrations --setup cursor

Generated Files:

├── .cursor/
│   └── rules/
│       ├── project-context.mdc
│       ├── coding-conventions.mdc
│       └── framework-patterns.mdc

Multi-IDE Setup

# Setup multiple IDEs
vdk integrations --setup claude-code
vdk integrations --setup cursor
vdk integrations --setup windsurf

# Or setup all detected IDEs at once
vdk integrations --setup-all

Step 4: Configuration Customization

View Current Configuration

# Check VDK status
vdk status

# View configuration
vdk config list

# Edit configuration
vdk config edit

Customize Scanner Settings

Edit vdk.config.json:

{
  "scanner": {
    "deepScan": true,
    "ignorePatterns": [
      "**/node_modules/**",
      "**/dist/**",
      "**/build/**",
      "**/.git/**",
      "**/.next/**",
      "**/coverage/**"
    ],
    "includePatterns": [
      "src/**/*.{ts,tsx,js,jsx}",
      "app/**/*.{ts,tsx}",
      "components/**/*.{ts,tsx}",
      "lib/**/*.ts"
    ],
    "analysisLevel": "comprehensive"
  }
}

Customize Rule Generation

{
  "rules": {
    "template": "comprehensive",
    "includeExamples": true,
    "detailLevel": "comprehensive",
    "sections": [
      "project-context",
      "technology-stack", 
      "coding-conventions",
      "architectural-patterns",
      "examples"
    ]
  }
}

Step 5: Team Collaboration Setup

Connect to VDK Hub

# Set up authentication (if using hub)
export VDK_HUB_TOKEN=your_hub_token

# Or use interactive login
vdk login

# Test connectivity
vdk hub ping

# Deploy to hub
vdk deploy --team "frontend-team" --project-name "design-system"

# Deploy with description
vdk deploy \
  --team "fullstack-team" \
  --project-name "ecommerce-platform" \
  --description "Next.js e-commerce patterns and conventions"

# Preview deployment
vdk deploy --dry-run

Team Member Onboarding

# New team member workflow
vdk update --team "frontend-team"    # Get shared rules
vdk integrations --setup claude-code # Setup preferred IDE
vdk status                           # Verify setup

Step 6: Development Workflow Integration

Git Integration

# Add VDK files to git
git add .ai/ vdk.config.json CLAUDE.md .cursor/

# Create .gitignore entries for cache files
echo ".ai/cache/" >> .gitignore
echo ".claude/logs/" >> .gitignore

# Commit initial setup
git commit -m "Add VDK CLI integration with project rules"

Package.json Scripts

Add convenient scripts to your package.json:

{
  "scripts": {
    "vdk:init": "vdk init --overwrite",
    "vdk:update": "vdk update && vdk claude-code --update-memory",
    "vdk:deploy": "vdk deploy --team our-team",
    "vdk:status": "vdk status && vdk integrations --scan",
    "postinstall": "vdk init --overwrite"
  }
}

Pre-commit Hook

Create .git/hooks/pre-commit:

#!/bin/sh
# Update VDK rules before commit

echo "Updating VDK rules..."
vdk init --overwrite > /dev/null 2>&1

# Add updated rules to commit
git add .ai/rules/ CLAUDE.md .cursor/ > /dev/null 2>&1

echo "VDK rules updated"

Make it executable:

chmod +x .git/hooks/pre-commit

Step 7: Verification & Testing

Verify Setup

# Comprehensive status check
vdk status

# Test IDE integrations
vdk integrations --scan

# Validate generated rules
vdk validate

# Check hub connectivity (if using)
vdk hub ping

Test AI Assistant Integration

Open your IDE (Claude Code, Cursor, etc.)
Start a new coding session in your project
Ask AI assistant to help with project-specific tasks:
- "Create a new component following our project patterns"
- "Refactor this code to match our conventions"
- "Add error handling using our established patterns"

Expected AI Improvements

Before VDK:

User: "Create a user component"
AI: "Here's a basic React component..."

After VDK:

User: "Create a user component"
AI: "I'll create a user component following your Next.js App Router patterns:
- TypeScript interface for props
- Server component by default
- Tailwind CSS styling
- Following your naming conventions
- Located in components/user/UserCard.tsx
- Proper accessibility attributes"

Step 8: Maintenance & Updates

Regular Maintenance

# Weekly maintenance routine
vdk update                        # Get latest hub rules
vdk init --overwrite            # Refresh project analysis
vdk claude-code --update-memory # Update IDE memory
vdk status                       # Verify everything works

Update After Major Changes

# After adding new dependencies
npm install new-package
vdk init --overwrite

# After changing project structure
vdk init --deep --overwrite

# After updating framework versions
vdk init --overwrite
vdk claude-code --update-memory

Automated Updates

Create GitHub Action .github/workflows/vdk-update.yml:

name: Update VDK Rules
on:
  push:
    branches: [main]
    paths: ['package.json', 'src/**', 'app/**']

jobs:
  update-vdk:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
      - name: Install VDK CLI
        run: npm install -g @vibe-dev-kit/cli
      - name: Update VDK rules
        run: vdk init --overwrite
      - name: Commit changes
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add .ai/ CLAUDE.md .cursor/
          git diff --staged --quiet || git commit -m "🤖 Update VDK rules"
          git push

Common Project Types Setup

React + TypeScript SPA

cd react-spa-project
vdk init --deep
vdk integrations --setup claude-code cursor

# Customize for React patterns
cat > vdk.config.json << 'EOF'
{
  "project": {
    "name": "react-spa",
    "type": "spa",
    "framework": "react"
  },
  "scanner": {
    "includePatterns": ["src/**/*.{ts,tsx}"],
    "analyzers": {
      "react": { "hooksAnalysis": true },
      "typescript": { "strictMode": true }
    }
  }
}
EOF

vdk init --overwrite

Next.js Full-Stack App

cd nextjs-app
vdk init --claude-code --deep

# Next.js specific configuration
cat > vdk.config.json << 'EOF'
{
  "project": {
    "name": "nextjs-fullstack",
    "type": "web-application", 
    "framework": "nextjs"
  },
  "scanner": {
    "includePatterns": [
      "app/**/*.{ts,tsx}",
      "components/**/*.{ts,tsx}",
      "lib/**/*.ts"
    ],
    "patternDetection": {
      "architectural": {
        "patterns": ["app-router", "server-components"]
      }
    }
  }
}
EOF

vdk init --overwrite

Node.js API

cd nodejs-api
vdk init --deep

# API-focused configuration
cat > vdk.config.json << 'EOF'
{
  "project": {
    "name": "nodejs-api",
    "type": "api",
    "framework": "express"
  },
  "scanner": {
    "includePatterns": [
      "src/**/*.ts",
      "routes/**/*.ts",
      "middleware/**/*.ts"
    ],
    "excludePatterns": ["**/*.test.ts"],
    "analyzers": {
      "node": { "version": "18+" },
      "express": { "routeAnalysis": true }
    }
  }
}
EOF

vdk init --overwrite

Troubleshooting Setup Issues

Common Problems

VDK command not found:

# Check installation
npm list -g @vibe-dev-kit/cli

# Check PATH
echo $PATH | grep npm

# Reinstall if needed
npm uninstall -g @vibe-dev-kit/cli
npm install -g @vibe-dev-kit/cli

Permission errors:

# Fix permissions
sudo chown -R $USER:$USER ~/.npm
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

Scanner timeout:

# Increase timeout and reduce scope
vdk init --timeout 300000 --ignorePattern "**/node_modules/**" "**/dist/**"

IDE not detected:

# Manual setup
vdk integrations --setup claude-code

# Check if IDE is in PATH
which claude
which cursor

Debug Mode

Enable detailed logging:

# Full debug mode
export VDK_DEBUG=true
vdk init --verbose

# Component-specific debugging
export VDK_DEBUG_SCANNER=true
export VDK_DEBUG_INTEGRATIONS=true
vdk init

Next Steps

After successful setup:

Try the Quick Start Tutorial - Get hands-on experience
Explore CLI Commands - Learn all available commands
Configure Integrations - Deep dive into IDE setup
Join VDK Hub - Connect with the community
Set up Team Collaboration - Share rules with your team

Success Indicators

You'll know VDK is working correctly when:

✅ vdk status shows green checkmarks
✅ Your IDE provides more contextual AI suggestions
✅ AI assistant understands your project's patterns and conventions
✅ Generated code follows your existing style and architecture
✅ Team members get consistent AI assistance

Congratulations! 🎉 Your project is now enhanced with VDK CLI, and your AI assistant has intelligent understanding of your codebase, patterns, and conventions.

Setup Guide

On this page