Vibe Coder Kit

Production-ready AI agent workflow template with TypeScript enforcement.

What is it?

Vibe Coder Kit (VCK) is a framework that makes AI agents work safely, traceably, and with quality. It replaces mutable STATE.md with immutable event logs, linear phase numbering with DAG-based workflows, and natural language rules with TypeScript enforcement.

Quick Start

Install globally

npm install -g vibe-coder-kit

Add to any project

cd your-project
vibe init

Or use with npx (no install)

npx vibe-coder-kit init

Usage

# Install VCK to current project
vibe init

# Show current status
vibe status

# Health check
vibe doctor

# Show version
vibe version

What it does

Workflow Management

Manages the entire software development lifecycle:

init → clarify → brainstorm → plan → approve → code → review → learn → done

Agent Control

Prevents AI agents from working carelessly:

• Secret detection: Catches API keys, passwords in code
• Test enforcement: Can't skip tests
• RBAC: Role-based access control
• Budget limits: Stops when token limit exceeded

Reliability

Prevents system crashes:

• Circuit Breaker: Stops on too many failures
• Saga: Automatic rollback on step failure
• Retry: Auto-retry with exponential backoff

Observability

Everything is logged:

• Event Store: All operations recorded (append-only)
• Telemetry: Performance metrics
• Knowledge Store: Lessons learned

Project Structure

After installation, your project will have:

your-project/
├── .vibe/
│   ├── core/           # TypeScript modules
│   ├── flows/          # Workflow definitions
│   ├── plugins/        # Rule plugins
│   ├── behaviors/      # Behavior protocols
│   ├── config.json     # Configuration
│   ├── phase-graph.json # DAG workflow
│   └── state/          # Event store
└── AGENTS.md           # Agent instructions

Configuration

Edit .vibe/config.json to customize:

{
  "projectType": "web",
  "teamSize": "small",
  "painPoint": "review",
  "costTracking": {
    "budgetPerSession": 50000
  }
}

How to use with AI agents

Just tell your agent:

"Follow the rules in .vibe/"

The agent will:

1. Read AGENTS.md
2. Follow the workflow in phase-graph.json
3. Execute flows from .vibe/flows/
4. Log events to .vibe/state/events.jsonl
5. Enforce rules from .vibe/plugins/

Requirements

• Node.js >= 18.0.0
• npm >= 9.0.0

License

MIT