โจ VibeDraft โจ
Where specs meet vibes, and code flows like magic
๐จ The most vibey way to build software - turn ideas into reality with Spec-Driven Development! ๐
๐ฆ Install: npm install -g vibedraft-cli
๐ Start: vibedraft init my-project
---
## ๐ฏ What's the Vibe?
**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!
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. ๐
## ๐ Quick Start
### Install VibeDraft
**Option 1: Global Install (Recommended)**
```bash
npm install -g vibedraft-cli
```
Then vibe anywhere:
```bash
vibedraft init my-awesome-project
vibedraft check
```
**Option 2: Quick Vibe (One-Time)**
```bash
npx vibedraft-cli init my-awesome-project
```
### The VibeDraft Workflow
Once installed, your AI coding assistant gets these powerful slash commands:
```bash
# 1. Set your project's vibe ๐
/vibedraft.constitution
# 2. Dream up your feature ๐ญ
/vibedraft.draft "Build a chat app with real-time messaging"
# 3. (Optional) Clarify ambiguities ๐ค
/vibedraft.clarify
# 4. Plan the tech stack ๐บ๏ธ
/vibedraft.plan "Use WebSocket, React, and PostgreSQL"
# 5. (Optional) Validate quality โ
/vibedraft.checklist
# 6. Break it into tasks ๐
/vibedraft.tasks
# 7. (Optional) Check consistency ๐
/vibedraft.analyze
# 8. Make it happen! ๐
/vibedraft.implement
```
**Boom!** From idea to implementation with clear, trackable steps. โจ
---
## ๐ธ 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
### ๐ค **Multi-Agent Support**
Works with your favorite AI coding assistants:
- **Claude Code** (Anthropic)
- **Gemini CLI** (Google)
- **GitHub Copilot** (Microsoft)
- **Cursor** (AI-first IDE)
- **Windsurf** (IDE workflows)
- **Qwen Code** (Alibaba)
- **Amazon Q Developer**
- And more!
### ๐ **Cross-Platform**
- **Node.js** for maximum compatibility
- **Bash scripts** for Unix/Linux/macOS/Windows
- Auto-detects your platform!
### ๐ **Smart Templates**
Pre-built templates for:
- Feature specifications
- Implementation plans
- Task breakdowns
- Quality checklists
- Project constitutions
### ๐ **Git Integration**
- Automatic branch creation per feature
- Sequential feature numbering
- Clean commit history
### ๐ **Intelligent Technology Stack Detection** โจ NEW in v0.1.0
When initializing VibeDraft in an **existing project**, it automatically:
- **Scans** your `package.json` for dependencies and configuration
- **Detects** frameworks (React, Next.js, Vue, Angular, Express, NestJS, and 20+ more)
- **Identifies** languages by file patterns (TypeScript, JavaScript, Python, Rust, Go, etc.)
- **Recognizes** build tools (Vite, Webpack, Rollup, esbuild, Turborepo, Nx)
- **Determines** project type (monorepo, web-app, fullstack, mobile, library, cli)
- **Discovers** package manager (npm, yarn, pnpm)
- **Analyzes** architectural patterns (JAMstack, microservices, TypeScript-first)
- **Auto-populates** your project constitution with detected tech stack
- **Generates** technology-specific principles and constraints
- **Pre-fills** plan templates with known technical context
**Before & After:**
**Before (v0.0.x):**
```bash
$ vibedraft init . --here
๐จ Found files here already
Do you want to continue? (y/n)
```
**After (v0.1.0):**
```bash
$ vibedraft init . --here
๐จ Found files here already
๐ Detected existing application:
๐ฆ Package: my-app v1.2.3
๐ง Tech Stack:
โข React 18.2.0 (Frontend Framework)
โข TypeScript 5.0.4 (primary language)
โข Vite 4.3.9 (build tool)
โข Jest 29.5.0 (testing)
๐ Project Type: Web Application (frontend)
๐ Structure: src/, public/, tests/
โจ VibeDraft will populate your constitution with this tech stack
Do you want to continue? (y/n)
```
**Benefits:**
- ๐ **Zero Manual Setup** - No need to manually document your tech stack
- ๐ **Instant Context** - AI understands your project from day one
- ๐ฏ **Better Planning** - Plans pre-filled with correct frameworks and tools
- ๐ **Consistent Constraints** - Auto-generated principles match your stack
- ๐ **Living Documentation** - Constitution stays in sync with reality
---
## ๐ฏ Core Commands
### CLI Commands
| Command | What It Does | Example |
|---------|-------------|---------|
| `vibedraft init` | ๐ฌ Bootstrap a new project | `vibedraft init my-app --ai claude` |
| `vibedraft init .` | ๐ฌ Initialize in current directory | `vibedraft init . --ai cursor` |
| `vibedraft check` | ๐ Check your dev environment | `vibedraft check` |
### Slash Commands (In Your AI Agent)
#### Essential Flow ๐ฏ
| 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` | ๐ Check consistency | After tasks - verify everything aligns |
| `/vibedraft.implement` | ๐ Execute tasks | Ready to code - let's build! |
---
## ๐ง Context-Aware Drafting
VibeDraft is **seriously smart** about your project! When you run `/vibedraft.draft`, the AI automatically scans your **entire project structure** for documentation to understand your project better.
### What Gets Scanned ๐
- โ
**Root-level docs**: `README.md`, `ARCHITECTURE.md`, `CONTRIBUTING.md`, `DESIGN.md`
- โ
**Feature specs**: All specifications in `.vibedraft/specs/` directory (or `specs/` for legacy projects)
- โ
**Documentation folders**: `docs/`, `.github/`, `guides/`, `.vibedraft/docs/`, etc.
- โ
**Nested markdown**: ANY `.md` file anywhere in your project
- โ **Excluded**: `node_modules/`, `.git/`, `build/`, `dist/`, coverage directories
### How It Works ๐ฏ
1. **Scan**: Finds all markdown files in your project
2. **Prioritize**: Reads critical docs first (README, ARCHITECTURE)
3. **Contextualize**: Uses this knowledge to draft your feature
4. **Align**: Creates specs that fit your project's patterns and goals
### Best Practices ๐
**Organize Your Documentation**:
```
project/
โโโ README.md # ๐ Project overview - always read
โโโ ARCHITECTURE.md # ๐๏ธ System design - always read
โโโ CONTRIBUTING.md # ๐ Dev practices - always read
โโโ DESIGN.md # ๐จ UI/UX patterns - always read
โโโ docs/
โ โโโ api-guidelines.md # ๐ก API conventions
โ โโโ database.md # ๐พ Data model
โ โโโ security.md # ๐ Security practices
โโโ .vibedraft/
โ โโโ specs/
โ โ โโโ 001-auth-system/spec.md # ๐ Existing features
โ โ โโโ 002-user-profile/spec.md # ๐ค Related features
โ โโโ docs/ # ๐ VibeDraft documentation
โโโ .github/
โโโ workflows.md # โ๏ธ CI/CD info
```
**Document Everything**:
- Project vision and goals
- Architectural decisions
- Existing features and patterns
- Technical constraints
- Domain terminology
- Integration points
### Example in Action ๐
```bash
# You have these docs:
# - README.md (mentions React + TypeScript)
# - ARCHITECTURE.md (describes microservices)
# - .vibedraft/specs/001-user-auth/spec.md (existing auth system)
# - docs/api-guidelines.md (REST conventions)
/vibedraft.draft "Add user notifications"
# AI automatically:
# โ Reads your README - understands it's a React/TS project
# โ Reviews ARCHITECTURE - knows to use microservices pattern
# โ Checks user-auth spec - reuses existing auth patterns
# โ Applies API guidelines - follows your REST conventions
# โ Creates a spec that perfectly fits your project! ๐ธ
```
### The More You Document, The Smarter It Gets! ๐ก
VibeDraft learns from your project's documentation. Well-documented projects get:
- ๐ฏ More accurate specifications
- ๐ Better alignment with existing features
- โก Faster drafting (less clarification needed)
- ๐ค Consistent patterns and terminology
**Pro Tip**: Keep a `docs/` folder with architecture decisions, guidelines, and patterns. VibeDraft will use it all! ๐ธ
---
## ๐ง Memory Bank System
VibeDraft includes a **Memory Bank** - a persistent knowledge system that helps AI assistants maintain context across sessions, memory resets, and team handoffs.
### What is the Memory Bank? ๐พ
The Memory Bank is a structured set of documentation files that capture your project's essence in a way AI assistants can reliably reference. Think of it as your project's "memory" that persists even when AI sessions reset.
### Core Files ๐
The Memory Bank consists of six interconnected files:
```
.cursor/rules/memory-bank/ (or .claude/, .github/, etc.)
โโโ 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
โโโ Notes/ # Additional detailed documentation
```
### File Hierarchy ๐๏ธ
Files build upon each other:
1. **projectbrief.md** โ Foundation document
2. **productContext.md, systemPatterns.md, techContext.md** โ Different perspectives
3. **activeContext.md** โ Combines all for current work
4. **progress.md** โ Tracks implementation status
### Automatic Creation โจ
Memory Bank is created automatically during `vibedraft init`:
```bash
# Full Memory Bank (all 6 files)
vibedraft init my-project --ai cursor
# Minimal Memory Bank (3 essential files)
vibedraft init my-project --ai cursor --minimal
```
### Manual Management ๐๏ธ
Create or update Memory Bank independently:
```bash
# 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
```
### Minimal vs Full Mode ๐ฏ
**Minimal Mode** (`--minimal` flag):
- **Best for**: Small projects, prototypes, focused tools, solo developers
- **Files**: projectbrief.md, techContext.md, activeContext.md
- **Use when**: Minimal documentation overhead desired, scope is well-defined
**Full Mode** (default):
- **Best for**: Large projects, teams, complex systems, long-term projects
- **Files**: All 6 core files + Notes/ directory
- **Use when**: Complex architecture, multiple stakeholders, project will evolve significantly
### Intelligent Auto-Population ๐ค
VibeDraft automatically populates Memory Bank with project data:
**What gets auto-filled** (100% certain):
- โ
Project name (from directory)
- โ
Technology stack (from detection)
- โ
Core dependencies (from package.json)
- โ
Build tools and setup requirements
- โ
Current date and initialization status
**What requires user input** (clear placeholders):
- ๐ Project scope and deliverables
- ๐ Target users and use cases
- ๐ Success metrics and timeline
- ๐ Architectural details
- ๐ Business value and UX goals
### Multi-Agent Support ๐
Memory Bank works with **all supported AI agents**:
| Agent | Location | Format | Status |
|-------|----------|--------|--------|
| **Cursor** | `.cursor/rules/memory-bank/` | MDC | โ
Full Support |
| **Claude Code** | `.claude/memory-bank/` | Markdown | โ
Full Support |
| **GitHub Copilot** | `.github/memory-bank/` | Markdown | โ
Full Support |
| **Gemini CLI** | `.gemini/memory-bank/` | Markdown | โ
Full Support |
| **Windsurf** | `.windsurf/memory-bank/` | Markdown | โ
Full Support |
| **Qwen Code** | `.qwen/memory-bank/` | Markdown | โ
Full Support |
| **opencode** | `.opencode/memory-bank/` | Markdown | โ
Full Support |
| **Amazon Q** | `.amazonq/memory-bank/` | Markdown | โ
Full Support |
| **Codex** | `.codex/memory-bank/` | Markdown | โ
Full Support |
| **Kilocode** | `.kilocode/memory-bank/` | Markdown | โ
Full Support |
| **Auggie** | `.augment/memory-bank/` | Markdown | โ
Full Support |
| **Roo** | `.roo/memory-bank/` | Markdown | โ
Full Support |
### Usage in AI Sessions ๐ฌ
Within your AI assistant, use the `/vibedraft.memory-bank` slash command to:
- Create Memory Bank for your agent
- Update Memory Bank with recent changes
- Review and fill in placeholders
- Maintain consistency across files
Example workflow:
```
User: "update memory bank"
AI: Reviewing all Memory Bank files...
โ activeContext.md - Updated with recent authentication work
โ progress.md - Marked user registration as complete
โ techContext.md - Added JWT and bcrypt dependencies
โ Other files - No changes needed
Memory Bank updated successfully!
```
### Benefits ๐
- **๐ Persistent Context** - AI maintains understanding across sessions
- **๐ฅ Team Onboarding** - New members and AI agents get up to speed faster
- **๐ Consistent Documentation** - Structured approach to project knowledge
- **๐ Multi-Agent Flexibility** - Use any AI assistant with same context
- **๐ Incremental Adoption** - Start minimal, expand as complexity grows
- **๐ฏ Reduced Repetition** - Stop re-explaining project details to AI
- **โก Faster Development** - AI has context without lengthy explanations
### Best Practices ๐ก
1. **Start Minimal, Expand Later**
- Begin with `--minimal` for new projects
- Add full structure when complexity grows
2. **Regular Updates**
- Update `activeContext.md` frequently (weekly)
- Update `progress.md` after features complete
- Update others when major changes occur
3. **Use Notes/ for Details**
- Create feature-specific docs in Notes/
- Keep core files concise
- Link from core files to detailed notes
4. **Respect File Boundaries**
- Don't duplicate information across files
- Reference other files instead of repeating
- Keep each file focused on its purpose
5. **Fill Placeholders Gradually**
- Start with what you know
- Add details as project evolves
- Don't over-document too early
### Example Session ๐
```bash
# Initialize project with Memory Bank
$ vibedraft init my-app --ai cursor --here
๐ Detected existing application:
โข React 18.2.0
โข TypeScript 5.3.0
โข Vite 5.0.0
โข 45 dependencies detected
โจ VibeDraft will populate your constitution with this tech stack
โ Memory Bank created for cursor
Location: .cursor/rules/memory-bank
Files: 6 (full)
๐ Memory Bank created!
Review and fill in placeholders in:
.cursor/rules/memory-bank/
```
### Learning More ๐
- See `templates/commands/vibedraft.memory-bank.md` for detailed AI usage guide
- Check individual Memory Bank files for inline documentation
- Use `/vibedraft.memory-bank` command within your AI assistant
---
## ๐ ๏ธ Installation Options
### Prerequisites
- **Node.js** 18.0.0 or higher
- **npm** or **npx**
- **Git** (optional but recommended)
- **AI coding assistant** of your choice
### Install from npm (Recommended)
```bash
# Global install
npm install -g vibedraft-cli
# Or use with npx (no install needed)
npx vibedraft-cli init my-project
```
### Verify Installation
```bash
vibedraft --version
vibedraft --help
```
### Development Mode (Contributing)
```bash
# Clone the repository
git clone https://github.com/MantisWare/VibeDraft.git
cd VibeDraft
# Install dependencies
npm install
# Link for local development
npm link
# Use anywhere
vibedraft init test-project
```
---
## ๐จ Usage Examples
### Example 1: Quick Start
```bash
# Initialize a new project with Claude
vibedraft init my-chat-app --ai claude
# In your AI agent
/vibedraft.draft Build a real-time chat app with rooms and DMs
/vibedraft.plan Use Socket.io for WebSocket, Express backend, React frontend
/vibedraft.tasks
/vibedraft.implement
```
### Example 2: Quality-First Approach
```bash
# Start with a constitution
/vibedraft.constitution Create principles for security, performance, and accessibility
# Draft your feature
/vibedraft.draft User authentication with OAuth providers
# Clarify ambiguities
/vibedraft.clarify
# Plan with clarifications
/vibedraft.plan
# Analyze for consistency
/vibedraft.analyze
# Generate tasks
/vibedraft.tasks
# Create quality checklist
/vibedraft.checklist Create security checklist for auth
# Implement
/vibedraft.implement
```
### Example 3: Current Directory Init
```bash
# Initialize in existing directory
cd my-existing-project
vibedraft init --here --ai cursor --script sh
```
---
## ๐ค Supported AI Agents
| Agent | Status | Format | Notes |
|-------|--------|--------|-------|
| **Claude Code** | โ
Full | Markdown | Anthropic's CLI tool |
| **Gemini CLI** | โ
Full | TOML | Google's AI CLI |
| **GitHub Copilot** | โ
Full | Markdown | IDE-based (VS Code) |
| **Cursor** | โ
Full | Markdown | AI-first IDE |
| **Windsurf** | โ
Full | Markdown | Workflow-based IDE |
| **Qwen Code** | โ
Full | TOML | Alibaba's AI CLI |
| **Opencode** | โ
Full | Markdown | Open-source option |
| **Amazon Q** | โ
Full | Markdown | AWS Developer CLI |
VibeDraft auto-generates the right command format for your agent! ๐ฏ
---
## ๐ Project Structure
After running `vibedraft init`, you'll get:
```
your-project/
โโโ .vibedraft/ # All VibeDraft files live here! โจ
โ โโโ scripts/ # Automation scripts
โ โ โโโ bash/ # Unix/Linux/macOS/Windows scripts
โ โโโ templates/ # Spec, plan, and task templates
โ โ โโโ commands/ # Slash command definitions
โ โ โโโ spec-template.md
โ โ โโโ plan-template.md
โ โ โโโ tasks-template.md
โ โโโ memory/
โ โ โโโ constitution.md # Project principles
โ โโโ specs/ # ๐ Your feature specs (moved from root)
โ โ โโโ 001-your-feature/
โ โ โโโ spec.md # Feature specification
โ โ โโโ plan.md # Implementation plan
โ โ โโโ tasks.md # Actionable tasks
โ โโโ docs/ # ๐ VibeDraft documentation
โ โ โโโ VIBEDRAFT_README.md # VibeDraft guide
โ โ โโโ spec-driven.md # SDD methodology
โ โโโ .gitignore # ๐ VibeDraft-specific ignores
โโโ .gitignore # Project-level ignores
โโโ README.md # Your project README (created if doesn't exist)
โโโ [your AI agent config] # .claude/, .cursor/, etc. (stays in root)
```
### ๐ v1.0.0 Structure Changes
**All VibeDraft files now live in `.vibedraft/`** to prevent conflicts with your application:
- โ
**Specs moved**: `.vibedraft/specs/` (was `specs/` in root)
- โ
**Docs organized**: `.vibedraft/docs/` (was root-level files)
- โ
**Backward compatible**: Supports both old (`specs/`) and new (`.vibedraft/specs/`) locations
- โ
**Clean root**: Only README, .gitignore, and agent configs in root
---
## ๐๏ธ Command Options
### `vibedraft init`
```bash
vibedraft init [project-name] [options]
```
**Arguments:**
- `project-name` - Name of your project (creates new directory)
- `.` - Initialize in current directory
- `--here` - Initialize in current directory (alternative syntax)
**Options:**
- `--ai ` - Choose AI agent: `claude`, `gemini`, `copilot`, `cursor`, `qwen`, `opencode`, `windsurf`, `q`
- `--ignore-agent-tools` - Skip AI agent CLI tool checks
- `--no-git` - Skip Git repository initialization
- `--force` - Overwrite existing files without asking
**Examples:**
```bash
# Basic init
vibedraft init my-project
# With specific AI agent
vibedraft init my-project --ai claude
# Current directory
vibedraft init --here
# Force overwrite in current directory
vibedraft init . --force --ai cursor
```
### `vibedraft check`
Check your development environment:
```bash
vibedraft check
```
Verifies:
- Git installation
- AI agent CLI tools (Claude, Gemini, Cursor, etc.)
- Node.js version
- Script permissions
---
## ๐จ The VibeDraft Philosophy
### 1. **Specs Are Executable**
Your specifications aren't just documentation - they're executable blueprints that AI can implement.
### 2. **Constitution-Driven**
Every project starts with a constitution defining principles, patterns, and practices. AI respects these throughout development.
### 3. **Feature Isolation**
Each feature gets its own:
- Git branch
- Spec directory
- Implementation plan
- Task list
### 4. **AI-Augmented, Human-Guided**
AI helps with the heavy lifting, but you stay in control with clear specifications and quality checks.
### 5. **Quality Built-In**
Checklists, analysis, and clarification steps ensure you build the right thing, the right way.
---
## ๐ Development Workflow
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Start New Feature โ
โโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ /vibedraft.constitution โ Set principles
โ (First time) โ
โโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ /vibedraft.draft โ What to build?
โ (Feature description) โ
โโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ /vibedraft.clarify โ (Optional)
โ Ask clarifying questions โ Remove ambiguity
โโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ /vibedraft.plan โ How to build?
โ (Technical approach) โ
โโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ /vibedraft.analyze โ (Optional)
โ Check consistency โ Verify alignment
โโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ /vibedraft.tasks โ Break it down
โ (Actionable steps) โ
โโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ /vibedraft.checklist โ (Optional)
โ Generate quality checks โ Validate quality
โโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ /vibedraft.implement โ Make it real!
โ (Build the feature) โ
โโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโ
โ
โผ
โจ Done! โจ
```
---
## ๐ Learn More
### Documentation
- **[Quick Start Guide](https://github.com/MantisWare/VibeDraft/blob/master/docs/quickstart.md)** - Get up and running fast
- **[Installation Guide](https://github.com/MantisWare/VibeDraft/blob/master/docs/installation.md)** - Detailed setup instructions
- **[Spec-Driven Development](https://github.com/MantisWare/VibeDraft/blob/master/spec-driven.md)** - Deep dive into the methodology
- **[Agent Support Guide](https://github.com/MantisWare/VibeDraft/blob/master/AGENTS.md)** - Adding new AI agents
- **[Local Development](https://github.com/MantisWare/VibeDraft/blob/master/docs/local-development.md)** - Contributing to VibeDraft
### Examples
Check out the [templates/](https://github.com/MantisWare/VibeDraft/tree/master/templates) directory for example specs, plans, and task lists!
---
## ๐ง Scripts Reference
VibeDraft includes automation scripts in both Node.js and Bash:
### Node.js Scripts
- `check-prerequisites.js` - Validate project setup
- `create-new-feature.js` - Initialize new feature structure
- `setup-plan.js` - Set up implementation plan
- `update-agent-context.js` - Refresh AI agent context
### Bash Scripts
- `check-prerequisites.sh` - Validate project setup
- `create-new-feature.sh` - Initialize new feature structure
- `setup-plan.sh` - Set up implementation plan
- `update-agent-context.sh` - Refresh AI agent context
Scripts are cross-platform compatible and work on Unix/Linux/macOS/Windows!
---
## ๐งช Testing
VibeDraft includes a comprehensive test suite covering all CLI functionality.
### Run Tests
```bash
# Run all tests
npm test
# Run with verbose output
npm run test:verbose
# Run with coverage (Node 20+)
node --test --experimental-test-coverage test/cli.test.js
```
### Test Coverage
The test suite includes **46 test cases** covering:
- โ
CLI help and version commands
- โ
`vibedraft check` - Environment validation
- โ
`vibedraft init` - Project initialization
- All AI agent integrations (8 agents)
- Git repository management
- File structure validation
- Error handling
- โ
Edge cases and error scenarios
- โ
Integration tests
See [`test/README.md`](https://github.com/MantisWare/VibeDraft/blob/master/test/README.md) for detailed test documentation.
### Test Results
```
โ
25+ passing tests
๐ 60+ test cases total
๐ฏ All CLI commands covered
```
---
## ๐จ Development
### Build Scripts
```bash
# Install dependencies
npm install
# Run tests
npm test
# Run tests with verbose output
npm run test:verbose
# Run tests with coverage
npm run test:coverage
# Lint code (autofix enabled)
npm run lint
# Lint without fixing
npm run lint:check
# Clean build artifacts
npm run clean
```
### Local Development
To work on VibeDraft locally:
1. Clone the repository
2. Install dependencies: `npm install`
3. Link locally: `npm link`
4. Lint and fix code: `npm run lint`
5. Test your changes: `npm test`
6. Run the CLI: `vibedraft --help`
See [docs/local-development.md](https://github.com/MantisWare/VibeDraft/blob/master/docs/local-development.md) for detailed development instructions.
### Code Quality
VibeDraft uses **ESLint** for code quality and consistency:
- **Automatic Fixing**: `npm run lint` automatically fixes most issues
- **Check Only**: `npm run lint:check` reports issues without fixing
- **Modern Config**: Uses ESLint 9+ flat config format
- **Pre-publish**: Linting runs automatically before publishing
#### ESLint Rules
- ES6+ modern JavaScript
- Consistent code style (semicolons, quotes, spacing)
- No unused variables (prefix with `_` for intentionally unused)
- Enforces best practices and error prevention
- Custom configuration in `eslint.config.js`
### Publishing & Versioning
VibeDraft includes automated release scripts with version bumping:
#### Quick Release (Patch)
```bash
# Bump patch version (1.0.0 โ 1.0.1), test, commit, tag, and publish
npm run release
```
#### Version Bump Types
```bash
# Patch release (bug fixes): 1.0.0 โ 1.0.1
npm run release:patch
# Minor release (new features): 1.0.0 โ 1.1.0
npm run release:minor
# Major release (breaking changes): 1.0.0 โ 2.0.0
npm run release:major
```
#### Manual Publishing
```bash
# Just publish (without version bump)
npm run publish:npm
```
#### What Happens During Release
1. **Pre-version checks**: Runs linting and tests
2. **Version bump**: Increments version in `package.json`
3. **Auto-fix**: Runs linter with autofix
4. **Git commit**: Commits version bump with message "Release vX.X.X"
5. **Git tag**: Creates a git tag for the version
6. **Git push**: Pushes commits and tags to remote
7. **Publish**: Publishes to npm registry
#### Version Script Hooks
- `preversion`: Runs lint and tests before versioning
- `version`: Runs lint with autofix and stages changes
- `postversion`: Pushes commits and tags to git
- `prepublishOnly`: Final lint and test check before publish
---
## ๐ Why VibeDraft?
### โ
For Developers
- Clear, trackable development process
- AI assistance without losing control
- Better specs = better code
- Git integration out of the box
### โ
For Teams
- Consistent project structure
- Constitutional principles everyone follows
- Easy onboarding with clear workflows
- Quality built into the process
### โ
For AI Agents
- Structured context and workflows
- Clear templates to follow
- Consistent command patterns
- Constitutional guidance for decisions
---
## ๐ค Contributing
Want to make VibeDraft even more vibey? We'd love your help!
1. **Fork the repo**
2. **Create a feature branch** - Use VibeDraft to spec it! ๐
3. **Make your changes** - Keep the vibes flowing
4. **Test thoroughly** - Make sure it rocks
5. **Submit a PR** - Share the love!
Check out our contributing guidelines for more details.
---
## ๐ Environment Variables
| Variable | Description | Example |
|----------|-------------|---------|
| `VIBEDRAFT_FEATURE` | Override feature detection (for non-Git repos) | `001-chat-feature` |
| `GH_TOKEN` / `GITHUB_TOKEN` | GitHub token for downloading releases | `ghp_xxx...` |
---
## ๐ค Support
- **Issues**: Found a bug? [Open an issue](https://github.com/MantisWare/VibeDraft/issues)
- **Discussions**: Questions? [Start a discussion](https://github.com/MantisWare/VibeDraft/discussions)
- **Docs**: Check the [docs folder](https://github.com/MantisWare/VibeDraft/tree/master/docs)
---
## ๐ License
MIT License - See [LICENSE](https://github.com/MantisWare/VibeDraft/blob/master/LICENSE) for details
---
## ๐ธ Keep the Vibes Flowing!
---
## ๐ Quick Command Reference
```bash
# CLI Commands
vibedraft init # Start a new project
vibedraft init . # Init in current directory
vibedraft check # Check your environment
# Slash Commands (In Your AI Agent)
/vibedraft.constitution # Set project principles
/vibedraft.draft # Draft a feature
/vibedraft.clarify # Ask clarifying questions
/vibedraft.plan # Create implementation plan
/vibedraft.analyze # Check consistency
/vibedraft.tasks # Generate task list
/vibedraft.checklist # Create quality checklist
/vibedraft.implement # Execute implementation
```
**Now go build something amazing!** ๐โจ