Vibe Init - AI-First Project Initializer

A CLI tool to bootstrap React + Convex monorepo projects with AI-first documentation structure.

Features

• 🚀 Simple Setup - Answer 5 questions to create your project structure
• 📁 Auto-Generate Docs - Creates PROJECT.md, ROADMAP.md, STATE.md + full codebase architecture
• 🎯 AI-Ready - Documentation structure optimized for AI context loading
• 📚 Complete Architecture - Copies all .specs/codebase/ documentation automatically
• 🔧 Git Integration - Optional git initialization with first commit
• 💡 Next Steps Guide - Clear instructions on how to proceed with AI

Installation

Option 1: NPM Link (Development)

cd cli
npm install
npm link

Now you can use vibe-init globally.

Option 2: Direct Execution

cd cli
npm install
npm start

Option 3: NPX (Future)

npx @vibe/init

Usage

With npx (Recommended - No Installation)

npx vibe-machine

With Global Installation

npm install -g vibe-machine
vibe-machine

What It Does

1. Asks 5 simple questions about your project
2. Creates a new directory with your project name
3. Generates complete documentation structure
4. Copies all architecture docs
5. Optionally initializes git
6. Provides a ready-to-use AI prompt

Example Session

$ npx vibe-machine

🚀 Vibe Init

Creating a new React + Convex monorepo project

? Project name: TaskFlow Pro
? What does this project do? Task and time tracking for freelancers
? What problem does this project solve? Helps freelancers track time and generate invoices
? Who is the target audience? Freelancers and small business owners
? List MVP features (comma-separated, optional): Task management, Time tracking, Invoice generation

✓ Created directory taskflow-pro
✓ Documentation generated successfully!
✓ Git repository initialized

📁 Project Location: taskflow-pro/

🚀 Next Steps:
1. cd taskflow-pro
2. code .
3. [Ready-to-use AI prompt displayed]

Your project is now ready! Just navigate to the directory and start building.

Generated Structure

After running vibe-init, you'll have:

.specs/
├── README.md           # Complete workflow guide
├── project/
│   ├── PROJECT.md      # Vision, goals, success criteria
│   ├── ROADMAP.md      # Feature list, milestones, priorities
│   └── STATE.md        # AI's session memory
├── codebase/           # Complete architecture documentation
│   ├── ARCHITECTURE.md # Core patterns & state management
│   ├── CONVENTIONS.md  # Naming & code style
│   ├── STACK.md        # Tech stack details
│   ├── STRUCTURE.md    # File organization
│   ├── TESTING.md      # Testing strategy
│   ├── INTEGRATIONS.md # External services
│   └── README.md       # Navigation guide
└── features/
    ├── .gitkeep
    └── TEMPLATE_FEATURE.md  # Template for new features

What You'll Be Asked

The CLI asks 5 simple questions:

1. Project name - What's your project called?
2. Description - What does this project do? (brief)
3. Problem - What problem does it solve?
4. Target audience - Who will use it?
5. MVP features - List of initial features (optional)

That's it! The tool handles the rest.

AI Workflow Integration

After initialization, use these AI commands:

# 1. Specify what to build
"Specify feature: user authentication"

# 2. Design the architecture
"Design feature: user authentication"

# 3. Break into tasks
"Break into tasks"

# 4. Implement incrementally
"Implement task AUTH-001"
"Implement task AUTH-002"

Architecture

The tool generates documentation following the AI-First Architecture:

• React 19 + Vite + TanStack Router (Frontend)
• Convex (Backend + Real-time Database)
• Zustand (UI State Management)
• Zod (Validation)
• Vitest (Testing)
• BiomeJS (Linting & Formatting)

See .specs/codebase/ for complete patterns and conventions.

Configuration

Custom Templates

You can customize templates by editing:

• src/templates/project.template.js
• src/templates/roadmap.template.js
• src/templates/state.template.js

Custom Presets

Add new presets in src/presets.js:

export const presets = {
  myPreset: {
    name: 'My Custom Preset',
    description: '...',
    vision: '...',
    primaryGoals: [...],
    features: [...],
    // ...
  },
};

Development

# Install dependencies
npm install

# Run locally
npm start

# Link globally for testing
npm link

# Unlink
npm unlink -g @vibe/init

Troubleshooting

"Command not found: vibe-init"

Make sure you've run npm link in the cli/ directory.

"Permission denied"

Make the binary executable:

chmod +x bin/vibe-init.js

Git initialization fails

The tool will continue even if git init fails. You can initialize manually:

git init
git add .specs/
git commit -m "Initial commit: Project documentation"

Dependencies

• inquirer - Interactive command-line prompts
• chalk - Terminal string styling
• ora - Elegant terminal spinners
• boxen - Create boxes in the terminal

Contributing

Contributions are welcome! Feel free to:

• Add new preset templates
• Improve question flows
• Enhance documentation generation
• Add new features

License

MIT

Related

• Vibe Coding Machine - The parent methodology
• .specs/ Documentation - Complete architectural patterns
• tlc-spec-driven Skill - AI workflow automation

Built with ❤️ for seamless AI collaboration