Getting Started

Install vibe-init and set up governance for your project in under 60 seconds.

Installation

Install the CLI globally via npm:

npm install -g vibe-init-cli

Verify the installation:

vibe --version
vibe --help

Prerequisites

Requirement	Purpose	Required?
Node.js 20+	Runtime environment	Yes
Claude CLI	AI-powered commands (init, run, ask)	For AI features
ANTHROPIC_API_KEY	Faster batch generation via Anthropic SDK (falls back to Claude CLI)	Optional
Docker	Local dev stack (PostgreSQL, Redis)	Optional
@agile-vibe-coding/avc	Agile ceremonies — epics, stories, sprint planning	Optional

Installing Claude CLI

The Claude CLI is required for AI-powered commands. Install it globally:

npm install -g @anthropic-ai/claude-code

Setting up your API key

Get your key from console.anthropic.com and set it as an environment variable:

# Add to your shell profile (~/.zshrc, ~/.bashrc, etc.)
export ANTHROPIC_API_KEY="sk-ant-..."

The vibe coding workflow

vibe-init uses a structured workflow: prepare the room, plan with agile, then build with AI.

# Step 1: Set up the vibe coding framework
mkdir my-app && cd my-app
vibe init

# Step 2: Plan with Agile Vibe Coding (optional)
npm install -g @agile-vibe-coding/avc
vibe avc                      # Sponsor Call → Epics → Sprint Planning → Stories

# Step 3: Build your project from an idea
vibe build

Step 1: vibe init — Prepare the room

Run vibe init to generate the AI coding framework. This creates the files that make Claude Code effective on your project:

vibe init

You'll be asked for a project name and stack preference (Next.js, Express, FastAPI, or Go). Then it generates:

• CLAUDE.md — Comprehensive coding instructions, conventions, architecture patterns, security guardrails, and testing strategy
• .claude/commands/ — Custom skills for Claude Code: /test, /lint, /build, /commit, /review, /add-feature
• .claude/settings.json — Permission allowlists and deny lists
• docs/adr/000-template.md — Architecture Decision Record template
• .gitignore — Stack-appropriate ignores

Step 2: vibe build — Build from your idea

Once the framework is in place, run vibe build to describe your idea and let Claude build it:

vibe build

This walks you through a 3-phase flow:

1. Enrichment — Describe your idea in plain English. Claude generates personas, prioritized features (P0/P1/P2), tech stack, and architecture. You can accept, edit, or restart.
2. ADR — Architecture Decision Record is auto-generated documenting decisions, alternatives, and trade-offs.
3. Build — Claude Code is spawned with your CLAUDE.md framework + enrichment brief + ADR as full context. It builds the project following all your conventions.

Brownfield: Existing projects

Already have a codebase? vibe init detects it's an existing project and generates the framework from analysis:

cd my-existing-app
vibe init              # Scans project, generates CLAUDE.md + skills

Then use vibe scan for a detailed practice report, and vibe add to fix gaps:

vibe scan                # See what's missing
vibe add docker          # Dockerfile + docker-compose.yml
vibe add ci              # GitHub Actions CI pipeline
vibe add testing         # Vitest config + sample test
vibe add logging         # Pino structured logging
vibe doctor              # Check health score

Anchor your decisions

As you build, anchor important feature decisions so context persists across chat sessions:

vibe anchor "user authentication"   # Create a feature context doc
vibe anchor "payment flow"          # Another feature
vibe anchor                         # List all anchored features

Each anchor creates docs/context/<feature>.md with a decisions table, constraints, open questions, and progress tracking. Claude reads these before starting work on a feature.

Check governance compliance

vibe audit    # or: vibe doctor

59 policies across 10 categories (security, accessibility, reliability, performance, 12-factor compliance, clean code, API governance, data governance, code review, observability). Shows blocking violations, warnings, and quick-fix commands.

Plan with Agile Vibe Coding

For structured, traceable AI development, use Agile Vibe Coding before building:

# Install AVC
npm install -g @agile-vibe-coding/avc

# Run ceremonies
cd your-project
vibe avc

AVC walks you through two ceremonies:

1. Sponsor Call — Define your project vision and create epics with business context
2. Sprint Planning — Break epics into user stories with acceptance criteria and traceability

Every epic and story links back to a requirement — so when you run vibe build and vibe audit, there's a complete traceability chain from business requirement to deployed code.

Continue building with context

Use vibe run to keep adding features with full project context:

vibe run "add pagination to the users API endpoint"
vibe run "refactor auth middleware for role-based access"
vibe run "write integration tests for the checkout flow"

Ask without changing files

Get read-only advice from Claude about your project:

vibe ask "should I use Redis for sessions or stick with JWT?"
vibe ask "what are the security risks in the current auth setup?"
vibe ask "which endpoints might have N+1 query problems?"

Generate a CLAUDE.md

A CLAUDE.md file gives Claude context about your project's architecture, conventions, and patterns. Generate one from a scan:

vibe scan --generate-claude-md

Global flags

These flags work with any command:

Flag	Description
--verbose	Show detailed debug output and full error stack traces
--dry-run	Preview changes without writing files to disk
--version	Print the installed version
--help	Show help text for any command