VibeDraft - Installation & Usage Guide

🎯 What is VibeDraft?

Stop coding, start vibing! 🎮

VibeDraft flips traditional development on its head. Instead of jumping straight into code, you:

💭

1. Draft your vision

What do you want to build?

🗺️

2. Plan the tech

How will you build it?

📋

3. Break it down

What are the steps?

🚀

4. Make it real

Let AI help you implement!

💡 The Big Idea: Your specifications become executable - they don't just guide development, they drive it. No more drift between docs and code. No more "but the spec says..." Just pure, aligned, vibey development flow. 🌊

📦 Installation

Option 1: Global Install (Recommended)

Install VibeDraft globally to use it anywhere on your system:

npm install -g vibedraft-cli

Then you can vibe anywhere:

vibedraft init my-awesome-project
vibedraft check

Option 2: Quick Vibe (One-Time Use)

Use npx to run VibeDraft without installing:

npx vibedraft-cli init my-awesome-project

✅ Verify Installation:
Run vibedraft --version to check your installation.

Prerequisites

Node.js version 18 or higher
npm or yarn package manager
Git for version control
One of the supported AI coding assistants (see AI Agents section)

First-Time Setup

After installation, check your environment:

vibedraft check

This will show your VibeDraft version, verify that all required tools are installed and properly configured, and display a summary of available tools in your development environment.

🆕 v1.2.x: Memory Bank files are now intelligently populated with real project data! Deep codebase analysis automatically detects your project structure, patterns, and technology stack.

🌊 The VibeDraft Workflow

Once you initialize a project, your AI coding assistant gets access to 9 powerful slash commands that guide you through the entire development process:

🆕 v1.2.x: Memory Bank system now includes intelligent auto-population! During initialization, VibeDraft performs deep codebase analysis to automatically fill Memory Bank files with meaningful, project-specific content including detected patterns, architecture, and features.

/vibedraft.constitution 📜

Set your project's vibe

Define core principles, architectural decisions, and coding standards. This is your project's DNA - everything else flows from here.

/vibedraft.constitution

/vibedraft.draft 💭

Dream up your feature

Create a baseline specification for what you want to build. Be as detailed or high-level as you want - the AI will help fill in the gaps.

/vibedraft.draft "Build a chat app with real-time messaging"

/vibedraft.clarify 🤔 OPTIONAL

Clarify ambiguities

Ask structured questions to de-risk ambiguous areas before planning. The AI will identify gaps and help you nail down fuzzy details.

/vibedraft.clarify

/vibedraft.plan 🗺️

Plan the tech stack

Generate an implementation plan with technical decisions, architecture, and approach. Decide how to build it.

/vibedraft.plan "Use WebSocket, React, and PostgreSQL"

/vibedraft.checklist ✅ OPTIONAL

Validate quality

Generate quality checklists to validate requirements completeness, clarity, and consistency.

/vibedraft.checklist

/vibedraft.tasks 📋

Break it into tasks

Generate actionable, ordered tasks from your plan. Get specific implementation steps.

/vibedraft.tasks

/vibedraft.analyze 🔍 OPTIONAL

Check consistency

Run a cross-artifact consistency and alignment report. Ensure everything fits together perfectly.

/vibedraft.analyze

/vibedraft.implement 🚀

Make it happen!

Execute implementation based on your plan and tasks. The AI reads everything and helps you code it up!

/vibedraft.implement

🧠

/vibedraft.memory-bank 💾 NEW v1.1.0

Manage persistent context

Update or create the Memory Bank - a persistent knowledge system that helps AI maintain project context across sessions. Perfect for team handoffs and long-term projects!

/vibedraft.memory-bank

The Memory Bank is automatically created during initialization and includes 6 core files (or 3 in minimal mode) that capture your project's essence.

🎉 Boom! From idea to implementation with clear, trackable steps. Your specs and code stay in perfect harmony throughout the entire process. Plus, your project context persists across AI sessions!

🎯 Command Reference

CLI Commands

Command	What It Does	Example
`vibedraft init`	🎬 Bootstrap a new VibeDraft project	`vibedraft init my-app --ai claude`
`vibedraft init .`	🎬 Initialize in current directory	`vibedraft init . --ai cursor`
`vibedraft check`	🔍 Check your development environment v1.1.1	`vibedraft check`
`vibedraft memory-bank`	🧠 Create/manage Memory Bank NEW v1.1.0	`vibedraft memory-bank --agent cursor`
`vibedraft --version`	📌 Show VibeDraft version	`vibedraft --version`
`vibedraft --help`	❓ Get help and usage info	`vibedraft --help`

Slash Commands (In Your AI Agent)

These 9 commands are available in your AI coding assistant after initializing a VibeDraft project:

Command	Purpose	When to Use
`/vibedraft.constitution`	📜 Set project principles	First thing - establish your project's DNA
`/vibedraft.draft`	💭 Create feature spec	When you have a new feature idea
`/vibedraft.clarify`	🤔 Ask clarifying questions	Before planning - nail down fuzzy details
`/vibedraft.plan`	🗺️ Generate tech plan	After drafting - decide how to build it
`/vibedraft.checklist`	✅ Generate quality checks	Anytime - validate requirements quality
`/vibedraft.tasks`	📋 Break into tasks	After planning - get actionable steps
`/vibedraft.analyze`	🔍 Consistency check	Before implementing - validate alignment
`/vibedraft.implement`	🚀 Execute implementation	When ready to code - AI reads everything
`/vibedraft.memory-bank` NEW v1.1.0	🧠 Update Memory Bank	Anytime - maintain persistent project context

🤖 Supported AI Agents

VibeDraft works seamlessly with your favorite AI coding assistants:

Claude Code Anthropic

Cursor AI-first IDE

GitHub Copilot Microsoft

Gemini CLI Google

Windsurf IDE workflows

Qwen Code Alibaba

opencode Open Source

Amazon Q AWS Developer

Codex CLI AI Assistant

Kilo Code Developer Tool

Auggie CLI AI Helper

Roo Code Code Assistant

How to Choose Your Agent

When initializing a project, specify your preferred AI agent:

# Choose during initialization
vibedraft init my-project --ai claude

# Or let VibeDraft prompt you
vibedraft init my-project

💡 Pro Tip: VibeDraft automatically configures the right command formats and directory structures for your chosen agent. Just pick your favorite and start vibing!

🧠 Memory Bank System NEW v1.1.0

Persistent Project Context for AI Assistants

The Memory Bank is a structured documentation system that helps AI assistants maintain understanding of your project across sessions, memory resets, and team handoffs.

Core Files (Full Mode)

📄 projectbrief.md

Foundation - what we're building

💡 productContext.md

Why - problems solved, users, value

🏗️ systemPatterns.md

How - architecture, patterns, design

⚙️ techContext.md

What - technologies, setup, constraints

📍 activeContext.md

Now - current focus, recent changes

✅ progress.md

Status - what works, what's left

Automatic Creation

Memory Bank is automatically created during initialization:

# Full Memory Bank (6 core files)
vibedraft init my-project --ai cursor

# Minimal Memory Bank (3 essential files: projectbrief, techContext, activeContext)
vibedraft init my-project --ai cursor --minimal

Manual Management

# Create for specific agent
vibedraft memory-bank --agent cursor

# Create for all detected agents
vibedraft memory-bank --all

# Create minimal version
vibedraft memory-bank --agent claude --minimal

# Update existing Memory Bank
vibedraft memory-bank --update --agent cursor

🚀 Intelligent Auto-Population (v1.2.x)

VibeDraft now performs deep codebase analysis during initialization and automatically populates Memory Bank files with:

✅ Project Structure - Directory organization, entry points, patterns
✅ Architectural Patterns - MVC, Component-Based, Redux, etc.
✅ Framework Detection - React, TypeScript, Jest, and more
✅ Coding Patterns - Modern JavaScript patterns in use
✅ Documentation Parsing - Features extracted from README
✅ Technology Stack - Complete tech stack with versions
✅ Dependencies - Core and dev dependencies
✅ Build Tools - Detected build tools and configurations
✅ Context-Aware Content - Different content for greenfield vs existing projects

💡 New in v1.2.x:

Memory Bank files are no longer empty templates! They now contain actionable, project-specific content based on deep analysis of your codebase. This means AI assistants have immediate, accurate context about your project from the moment you initialize.

💡 Benefits:

🔄 Persistent Context - AI maintains understanding across sessions
👥 Team Onboarding - New members get up to speed faster
📖 Consistent Documentation - Structured approach to project knowledge
🔀 Multi-Agent Flexibility - Use any AI assistant with same context

🎸 Features That Rock

🎨

Spec-Driven Development

Write specifications that AI can execute. Keep specs and code in perfect harmony. Track every feature from conception to completion.

🧠

Smart Memory Bank v1.2.x

Persistent project context with intelligent auto-population. Deep codebase analysis automatically detects your project structure, architectural patterns, frameworks, and coding styles. Memory Bank files contain real, actionable content from initialization.

🤖

Multi-Agent Support

Works with 12+ AI coding assistants including Claude, Cursor, GitHub Copilot, and more. Use your favorite tool!

🌍

Cross-Platform

Built on Node.js with Bash scripts for maximum compatibility across Unix, Linux, macOS, and Windows (WSL).

📋

Smart Templates

Pre-built templates for feature specs, implementation plans, task breakdowns, quality checklists, and project constitutions.

🔄

Git Integration

Automatic branch creation per feature, sequential feature numbering, and clean commit history out of the box.

⚡

Context-Aware

VibeDraft automatically scans all markdown files in your project for context. Document your patterns - the AI will read and apply them!

📁

Clean File Structure v1.0.0

All VibeDraft files in .vibedraft/ directory. Backward compatible with old structure. Specs, docs, and scripts organized cleanly.

🔍

Deep Codebase Analysis v1.2.x

Performs comprehensive project analysis: structure mapping, pattern detection, framework identification, and documentation parsing. Automatically populates Memory Bank with meaningful, project-specific content.

💡 Real-World Examples

Example 1: Building a User Authentication System

Step 1: Initialize Project

vibedraft init auth-system --ai cursor
cd auth-system

Step 2: Set Project Constitution

In your AI agent, run:

/vibedraft.constitution

# AI helps you define:
# - Security-first principles
# - Token-based authentication approach
# - Data privacy requirements

Step 3: Draft the Feature

/vibedraft.draft "User authentication system with JWT tokens, password hashing, email verification, and role-based permissions"

Step 4: Create Implementation Plan

/vibedraft.plan "Use bcrypt for passwords, JWT for tokens, PostgreSQL for user storage, and Express middleware for route protection"

Step 5: Generate Tasks

/vibedraft.tasks

# AI generates ordered tasks like:
# 1. Set up database schema for users
# 2. Implement password hashing with bcrypt
# 3. Create JWT token generation/verification
# 4. Build registration endpoint
# 5. Build login endpoint
# etc...

Step 6: Implement!

/vibedraft.implement

# AI reads all your specs and helps code it up!

Example 2: Adding a Feature to Existing Project

# Navigate to your VibeDraft project
cd my-existing-project

# In your AI agent:
/vibedraft.draft "Add real-time notifications using WebSockets"
/vibedraft.plan "Use Socket.io with Redis for scaling"
/vibedraft.tasks
/vibedraft.implement

🎯 Pro Pattern: Always run /vibedraft.constitution first on new projects, and use /vibedraft.clarify when requirements are fuzzy. These optional steps save massive time later!

✨ Best Practices

🎯 Project Setup

Start with Constitution: Always define your project's principles and patterns first
Choose the Right Agent: Pick the AI assistant you're most comfortable with
Version Control: Let VibeDraft initialize Git for you - it sets up proper branching

📝 Writing Specs

Be Specific: The more detail in your draft, the better the output
Use Clarify: Don't skip /vibedraft.clarify for complex features
Document Patterns: Add markdown files for architecture decisions - AI will read them
Iterate: Specs are living documents - update them as you learn

🔄 Development Workflow

One Feature at a Time: Complete the full cycle before starting the next
Use Analyze: Run /vibedraft.analyze before implementing to catch issues
Keep Plans Updated: If implementation diverges, update your plan
Quality Checks: Use /vibedraft.checklist to validate completeness

🚀 Advanced Tips

Memory Bank Workflow: Use --minimal flag for small projects, update Memory Bank regularly with /vibedraft.memory-bank
Context is King: VibeDraft scans ALL markdown files - use this for team knowledge
Tech Stack Detection: Initialize in existing projects with vibedraft init . --here to auto-detect your stack
Template Customization: Modify templates in .vibedraft/templates/ to fit your needs
Script Extension: Add custom scripts in .vibedraft/scripts/
Git Workflow: Each feature gets its own branch automatically

💡 Golden Rule: Keep your specs close to your code. When they drift, update them. VibeDraft works best when specifications and implementation stay in sync!

🔧 Troubleshooting

Common Issues

Issue: "Command not found: vibedraft"

Solution:

# Reinstall globally
npm install -g vibedraft-cli

# Or use npx
npx vibedraft-cli init my-project

Issue: AI agent doesn't recognize slash commands

Solution:

Make sure you're in a VibeDraft-initialized project
Check that command files exist in the agent's directory (e.g., .cursor/commands/)
For Cursor: Check .cursor/settings.json includes command recommendations
Verify Memory Bank files exist in agent's rules directory (e.g., .cursor/rules/memory-bank/)
Try reloading your IDE/editor

Issue: Memory Bank not created

Solution:

# Create Memory Bank manually
vibedraft memory-bank --agent cursor

# Or create for all detected agents
vibedraft memory-bank --all

Issue: Script permission errors

Solution:

# Make scripts executable
chmod +x .vibedraft/scripts/bash/*.sh

Issue: Git not initializing

Solution:

# Initialize manually
git init
git add .
git commit -m "Initial commit"

Getting Help

📚 Documentation: GitHub Repository
🐛 Report Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📦 npm Package: vibedraft-cli

📖 Need More Help? Check out the full README.md in the repository for advanced configuration and detailed documentation.

🚀 Quick Start Summary

Get up and running in 2 minutes:

1️⃣ Install

npm install -g vibedraft-cli

2️⃣ Initialize

vibedraft init my-project --ai cursor

3️⃣ Set Constitution

/vibedraft.constitution

4️⃣ Draft Feature

/vibedraft.draft "Your idea"

5️⃣ Create Plan

/vibedraft.plan "Tech details"

6️⃣ Generate Tasks

/vibedraft.tasks

7️⃣ Implement! 🎉

/vibedraft.implement

🎊 That's it! You're now using Spec-Driven Development. Your AI assistant has full context from your specs and will help you build exactly what you planned.