What is vibe-init?

vibe-init is a governance-first CLI that prepares any project for successful AI-assisted (vibe) coding. It generates governance policies, coding standards, Claude Code skills, and persistent context anchors — so Claude follows your rules from the first line of code.

graph LR
    A["vibe init"] --> B["CLAUDE.md<br/>AI Instructions"]
    A --> C[".vibe/policies/<br/>59 Governance Policies"]
    A --> D[".claude/commands/<br/>Auto-detected Skills"]
    A --> E["docs/adr/<br/>ADR Template"]
    
    F["vibe build"] --> G["Describe Idea"]
    G --> H["Claude Enrichment<br/>Personas · Features · Architecture"]
    H --> I["Claude Code Builds<br/>With Full Governance Context"]
    
    J["vibe audit"] --> K["10-Category<br/>Governance Scorecard"]
    
    L["vibe anchor"] --> M["Feature Context Docs<br/>Decisions · Constraints · State"]
    
    N["vibe avc"] --> O["Sponsor Call · Sprint Planning<br/>Epics · Stories · Traceability"]
    O --> I
    
    style A fill:#FF6B35,color:#fff
    style F fill:#FF6B35,color:#fff
    style J fill:#FF6B35,color:#fff
    style L fill:#FF6B35,color:#fff
    style N fill:#007AFF,color:#fff

Governance at a Glance

pie title 59 Policies Across 10 Categories
    "Security" : 9
    "Clean Code" : 10
    "Reliability" : 8
    "12-Factor Compliance" : 7
    "API Governance" : 5
    "Performance" : 4
    "Data Governance" : 4
    "Code Review" : 6
    "Observability" : 4
    "Accessibility" : 2

| Category | Policies | Severity | What it checks | |----------|:--------:|----------|---------------| | Security | 9 | block/warn/info | .gitignore, no secrets, env validation, input validation, ORM, lockfile, vuln scanning, auth, SECURITY.md | | Clean Code | 10 | block/warn/info | TS strict, no-any, linter, formatter, git hooks, commits, coverage, console.log, README, CLAUDE.md | | Reliability | 8 | block/warn/info | Health endpoint, CI/CD, tests, graceful shutdown, error boundaries, migrations, E2E, load testing | | 12-Factor | 7 | block/warn | VCS, deps, config-in-env, backing services as URLs, port binding, dev/prod parity, logs as streams | | API Governance | 5 | block/warn/info | OpenAPI spec, versioning, rate limiting, input validation, health endpoint | | Code Review | 6 | warn/info | PR templates, CODEOWNERS, issue templates, CONTRIBUTING.md, CHANGELOG, architecture docs | | Performance | 4 | warn/info | Structured logging, bundle analysis, image optimization, containerization | | Data Governance | 4 | warn | Privacy policy, password hashing, SECURITY.md, ORM | | Observability | 4 | warn/info | Logging, tracing (OpenTelemetry), metrics (Prometheus), error tracking (Sentry) | | Accessibility | 2 | warn | a11y linter (eslint-plugin-jsx-a11y), HTML lang attribute |

Install

npm install -g vibe-init-cli

Prerequisites

| Requirement | Purpose | Required? | |------------|---------|-----------| | Node.js 20+ | Runtime | Yes | | Claude CLI | AI commands (init, build, run, ask) | For AI features | | ANTHROPIC_API_KEY | Faster batch generation (falls back to Claude CLI) | Optional | | @agile-vibe-coding/avc | Agile ceremonies (epics, stories, sprint planning) | Optional | | @colbymchenry/codegraph | Semantic code intelligence — 94% fewer Explore calls | Optional | | graphifyy (PyPI) | Multi-modal knowledge graph (code + docs + papers + audio + video) | Optional |

The Vibe Coding Workflow

sequenceDiagram
    participant Dev as Developer
    participant AVC as vibe avc (Agile)
    participant VI as vibe init
    participant VB as vibe build
    participant CC as Claude Code
    participant VA as vibe audit
    
    Dev->>VI: vibe init
    VI->>VI: Generate CLAUDE.md
    VI->>VI: Generate 59 governance policies
    VI->>VI: Auto-detect & install skills
    VI-->>Dev: Framework ready
    
    Dev->>AVC: vibe avc
    AVC->>AVC: Sponsor Call → Epics
    AVC->>AVC: Sprint Planning → Stories
    AVC-->>Dev: Backlog with traceability
    
    Dev->>VB: vibe build
    VB->>CC: Describe your idea
    CC->>CC: Enrich → Personas, Features, Architecture
    CC->>CC: Generate ADR
    CC->>CC: Build project (governed by CLAUDE.md)
    CC-->>Dev: Project built with governance
    
    Dev->>VA: vibe audit
    VA->>VA: Check 59 policies + traceability
    VA-->>Dev: Governance scorecard (A+ to F)

Step 1: Prepare the room

mkdir my-app && cd my-app
vibe init

Generates: CLAUDE.md (with CodeGraph + Graphify guidance) + .vibe/policies/ (59 YAML policies) + .claude/commands/ (auto-detected skills + codegraph + graphify skills) + .claude/settings.json (with codegraph MCP allow-list) + ADR template + .gitignore (excludes .codegraph/ and graphify-out/cache/)

Step 2: Build from your idea

vibe build

Describe your idea → Claude enriches it (personas, P0/P1/P2 features, architecture) → Claude Code builds it following your governance framework.

Step 3: Track decisions

vibe anchor "user authentication"

Creates docs/context/user-authentication.md with decisions table, constraints, open questions, and state tracking. Context persists across AI sessions.

Step 4: Check compliance

vibe audit    # or: vibe doctor

10-category governance scorecard with blocking violations, warnings, and quick-fix commands.

Commands

| Command | Description | |---------|-------------| | vibe init | Set up governance framework (CLAUDE.md, policies, skills, ADR template) | | vibe build | Build a project from your idea with governance context | | vibe anchor [feature] | Create/view feature context anchors for persistent decisions | | vibe audit / vibe doctor | Governance compliance audit (59 policies, 10 categories) | | vibe scan [dir] | Analyze project stack and engineering practices | | vibe add <feature> | Inject features: docker, ci, testing, logging, validation, health, hooks, auth, db | | vibe run <task> | Code with Claude using project context | | vibe ask <question> | Read-only advisory from Claude | | vibe codegraph [args...] | Semantic code intelligence (wraps @colbymchenry/codegraph, auto-installs) | | vibe graphify [args...] | Multi-modal knowledge graph — code + docs + papers + audio + video (wraps graphifyy, auto-installs via uv/pipx/pip) | | vibe agents-cli [args...] | Build / eval / deploy ADK agents on Google Cloud (wraps google-agents-cli, runs via uvx) |

Context Anchoring

Based on Martin Fowler's Context Anchoring pattern.

graph TD
    A["Long AI Chat<br/>Context trapped in session"] -->|"vibe anchor"| B["docs/context/feature.md"]
    B --> C["Decisions Table<br/>Decision | Reason | Rejected Alternative"]
    B --> D["Constraints<br/>Hard boundaries"]
    B --> E["Open Questions<br/>Unresolved items"]
    B --> F["State<br/>Progress tracking"]
    
    G["New AI Session"] -->|reads| B
    G --> H["Full context restored<br/>No re-explanation needed"]
    
    style A fill:#DC2626,color:#fff
    style B fill:#22C55E,color:#fff
    style H fill:#22C55E,color:#fff

Litmus test: Can you close your AI chat and start fresh without anxiety? If yes, context is anchored.

Agile Vibe Coding Integration

New in v0.6.0 — Built on the Agile Vibe Coding Manifesto, vibe-init now integrates with the AVC framework for traceable, accountable AI-assisted development.

graph LR
    AVC["vibe avc<br/>Sponsor Call · Sprint Planning"] --> Epics["Epics &<br/>Stories"]
    Epics --> VI["vibe init<br/>Governance Framework"]
    VI --> VB["vibe build<br/>With Traceability"]
    VB --> VA["vibe audit<br/>Traceability Checks"]
    
    style AVC fill:#007AFF,color:#fff
    style Epics fill:#BF5AF2,color:#fff
    style VI fill:#FF6B35,color:#fff
    style VB fill:#FF6B35,color:#fff
    style VA fill:#34C759,color:#fff

Why Agile Vibe Coding?

"Zero traceability of decisions" — that's the exact pain point. Vibe coding ships fast but the governance layer is missing, and that's where production risk accumulates.

The manifesto's core values:

• Accountability over anonymous generation — clear human responsibility for AI output
• Traceable intent over opaque implementation — every change links to a requirement
• Discoverable domain structure over scattered code — organized around business concepts
• Human-readable documentation over implicit knowledge — preserved understanding

Quick Start with AVC

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

# Set up governance framework
cd your-project
vibe init

# Run AVC ceremonies
vibe avc
# → Sponsor Call: define epics and priorities
# → Sprint Planning: break epics into stories with acceptance criteria

# Build with full traceability
vibe build

What AVC Adds

| Ceremony | Purpose | Output | |----------|---------|--------| | Sponsor Call | Define project vision, epics, and priorities | Epics with business context | | Sprint Planning | Break epics into stories, estimate complexity | Sprint backlog with traceability |

Every epic, story, and task created by AVC links back to a requirement — making governance auditable end-to-end.

Semantic Code Intelligence (CodeGraph)

vibe init wires up CodeGraph so Claude Code's Explore agents can answer "how does X work?" with one MCP call instead of dozens of grep/read calls — 94% fewer tool calls and 77% faster on average across real-world codebases.

graph LR
    Init["vibe init"] --> CG["CodeGraph<br/>guidance in CLAUDE.md"]
    Init --> Skill[".claude/commands/codegraph.md<br/>(when to use which tool)"]
    Init --> Perms[".claude/settings.json<br/>MCP allow-list"]

    User["vibe codegraph init -i"] --> Index[".codegraph/<br/>SQLite knowledge graph"]
    Index --> MCP["mcp__codegraph__*<br/>search · callers · impact · ..."]
    MCP --> CC["Claude Code Explore agent"]

    style Init fill:#FF6B35,color:#fff
    style User fill:#06B6D4,color:#fff
    style CC fill:#22C55E,color:#fff

What vibe init adds for CodeGraph:

• CLAUDE.md gets a marker-fenced ## CodeGraph section telling Claude when to use codegraph_* tools vs. grep/read.
• .claude/commands/codegraph.md — a skill describing each MCP tool and when to reach for it.
• .claude/settings.json — pre-allowed mcp__codegraph__* permissions so there are no permission prompts.
• .gitignore — .codegraph/ excluded (regenerable local cache).
• Optional prompt at the end of vibe init to run codegraph init -i immediately — declined gracefully if CodeGraph isn't installed.

Quick start

# Run anywhere — auto-installs @colbymchenry/codegraph globally on first use
vibe codegraph

# In a project: build the index
vibe codegraph init -i

# Status / search / sync — args pass through to the codegraph CLI
vibe codegraph status
vibe codegraph query UserService
vibe codegraph sync

CodeGraph supports 19+ languages (TypeScript, JavaScript, Python, Go, Rust, Java, C/C++, Swift, Kotlin, Ruby, PHP, Dart, Svelte, Pascal/Delphi). All processing is 100% local — no API keys, no external services.

Multi-Modal Knowledge Graph (Graphify)

New in v0.7.0 — vibe init also wires up Graphify (PyPI: graphifyy) so Claude can navigate your project by structure rather than by grep. Where CodeGraph indexes code symbols, Graphify builds a cross-modal graph spanning code, docs, papers, images, audio, and video — and emits a one-page audit (graphify-out/GRAPH_REPORT.md) plus a queryable JSON graph.

graph LR
    Init["vibe init"] --> GFY["Graphify<br/>guidance in CLAUDE.md"]
    Init --> Skill[".claude/commands/graphify.md<br/>(when to query the graph)"]

    User["vibe graphify ."] --> Out["graphify-out/<br/>graph.html · GRAPH_REPORT.md · graph.json"]
    Out --> Queries["vibe graphify query / path / explain / stats"]
    Queries --> CC["Claude Code<br/>navigates by structure"]

    style Init fill:#FF6B35,color:#fff
    style User fill:#06B6D4,color:#fff
    style CC fill:#22C55E,color:#fff

What vibe init adds for Graphify:

• CLAUDE.md gets a marker-fenced ## Graphify section telling Claude to read GRAPH_REPORT.md before broad exploration.
• .claude/commands/graphify.md — a skill describing when Graphify beats CodeGraph (and vice versa), and which query commands to use.
• .gitignore — excludes graphify-out/cache/, manifest.json, and cost.json (regenerable / local-only). The committed graph (graph.json, GRAPH_REPORT.md) is shared with the team.

Quick start

# Run anywhere — auto-installs graphifyy (uv → pipx → pip) on first use
vibe graphify .

# Wire up always-on hooks for your AI assistant
vibe graphify install

# Query the graph
vibe graphify query "show the auth flow"
vibe graphify path DigestAuth Response
vibe graphify explain UserService
vibe graphify stats

# Cross-repo
vibe graphify clone https://github.com/owner/repo
vibe graphify merge-graphs a/graph.json b/graph.json --out merged.json

Graphify vs CodeGraph — when to use which

| Use Graphify | Use CodeGraph | |--------------|---------------| | Cross-modal questions (docs ↔ code ↔ papers) | Pure code questions (callers, callees, impact) | | "What is this project about?" / orientation | "What calls function X?" | | Surprising connections, design rationale | Symbol lookup / blast-radius analysis | | Mixed corpora (audio transcripts, images, PDFs) | Source-tree-only repos |

Both can coexist in the same project — they are complementary, not exclusive. Every Graphify edge is tagged EXTRACTED (found directly in source), INFERRED (reasonable inference, with a confidence score), or AMBIGUOUS (flagged for review), so you always know what was found vs. guessed.

Google Agents CLI Bridge

New in v0.7.1 — vibe agents-cli is a thin pass-through wrapper around google/agents-cli (the Python CLI for building, evaluating, and deploying ADK agents on Google Cloud). All flags pass through verbatim; if the agents-cli binary isn't installed, vibe-init runs it ephemerally via uvx google-agents-cli — no global Python install required, only uv on PATH. Run vibe help agents-cli for the full vibe-side surface, or vibe agents-cli --help for the canonical upstream help.

# Setup
vibe agents-cli setup                          # Install agents-cli + skills into your coding agents
vibe agents-cli update                         # Force reinstall skills to all IDEs
vibe agents-cli info                           # Show project config and CLI version

# Auth
vibe agents-cli login                          # Authenticate with Google Cloud or AI Studio
vibe agents-cli login --status                 # Show authentication status

# Scaffold
vibe agents-cli scaffold my-agent              # Create a new ADK agent project
vibe agents-cli scaffold enhance               # Add deploy / CI/CD / RAG to an existing project
vibe agents-cli scaffold upgrade               # Upgrade project to a newer agents-cli version

# Develop
vibe agents-cli run "prompt"                   # Run agent with a single prompt
vibe agents-cli install                        # Install project dependencies
vibe agents-cli lint                           # Run code quality checks (Ruff)

# Evaluate
vibe agents-cli eval run                       # Run agent evaluations
vibe agents-cli eval compare a.json b.json     # Compare two eval result files

# Deploy & Publish
vibe agents-cli deploy                         # Deploy to Agent Runtime / Cloud Run / GKE
vibe agents-cli publish gemini-enterprise      # Register with Gemini Enterprise
vibe agents-cli infra single-project           # Provision single-project infrastructure
vibe agents-cli infra cicd                     # Set up CI/CD + staging/prod infrastructure

# Data / RAG
vibe agents-cli infra datastore                # Provision datastore infrastructure for RAG
vibe agents-cli data-ingestion                 # Run data ingestion pipeline

agents-cli setup installs seven coding-agent skills that work alongside vibe-init's governance:

| Skill | What your coding agent learns | |-------|-------------------------------| | google-agents-cli-workflow | Development lifecycle, code preservation rules, model selection | | google-agents-cli-adk-code | ADK Python API — agents, tools, orchestration, callbacks, state | | google-agents-cli-scaffold | Project scaffolding — create, enhance, upgrade | | google-agents-cli-eval | Evaluation methodology — metrics, evalsets, LLM-as-judge, trajectory scoring | | google-agents-cli-deploy | Deployment — Agent Runtime, Cloud Run, GKE, CI/CD, secrets | | google-agents-cli-publish | Gemini Enterprise registration | | google-agents-cli-observability | Observability — Cloud Trace, logging, third-party integrations |

Why bridge rather than rebuild?

| vibe-init | agents-cli | |-------------|--------------| | Governance framework (59 policies, 10 categories, ADRs, context anchors) | ADK agent scaffolding, evaluation, and Google Cloud deployment | | Coding-assistant-agnostic skills wiring | Coding-assistant-agnostic skills wiring | | Layered on top of any project | Layered on top of any project |

The two are complementary: vibe init lays down governance; vibe agents-cli scaffold then creates ADK agents that inherit it; vibe agents-cli eval and vibe agents-cli deploy evaluate and ship them under the same policies.

Auto-Skills

vibe init auto-detects your tech stack and installs matching Claude Code skills:

| Detected | Skills installed | |----------|----------------| | React | react-patterns, component-design | | Next.js | nextjs-app-router, nextjs-server-components | | TypeScript | typescript-strict | | Prisma | prisma-patterns | | Tailwind | tailwind-patterns | | Express | express-patterns | | FastAPI | fastapi-patterns | | Vitest | vitest-testing | | Playwright | playwright-e2e | | Docker | docker-patterns |

Plus universal skills: /anchor (context memory) and /governance (audit check).

Integration with autoskills for community skill registry.

Governance Policy Format

Policies are generated as YAML files compatible with Microsoft Agent Governance Toolkit:

# .vibe/policies/security.yaml
category: "security"
conflict_resolution: "deny_overrides"

rules:
  - name: "sec-001"
    display_name: "Gitignore excludes .env"
    severity: "block"
    action: "deny"
    references:
      - "https://owasp.org/Top10/A07_2021"

Three severity levels:

• block — mandatory, must fix before shipping
• warn — should fix, impacts quality
• info — nice to have, best practice

Project Architecture

graph TD
    CLI["src/index.ts<br/>CLI Entry (Commander.js)"]
    
    CLI --> Init["commands/init.ts<br/>Framework Generation"]
    CLI --> Build["commands/build.ts<br/>Idea → Claude Build"]
    CLI --> Anchor["commands/anchor.ts<br/>Context Memory"]
    CLI --> Audit["commands/doctor.ts<br/>Governance Audit"]
    CLI --> Scan["commands/scan.ts<br/>Project Analysis"]
    CLI --> Add["commands/add.ts<br/>Feature Injection"]
    CLI --> Run["commands/run.ts<br/>Claude Code Tasks"]
    
    Init --> Framework["phases/framework.ts<br/>CLAUDE.md + Skills + Settings"]
    Init --> Policies["governance/yaml-generator.ts<br/>59 YAML Policy Files"]
    Init --> Skills["skills/autoskills.ts<br/>Stack Detection + Skill Install"]
    
    Audit --> Registry["governance/registry.ts<br/>10 Categories"]
    Registry --> SecPol["policies/security.ts"]
    Registry --> A11yPol["policies/accessibility.ts"]
    Registry --> RelPol["policies/reliability.ts"]
    Registry --> PerfPol["policies/performance.ts"]
    Registry --> CompPol["policies/compliance.ts"]
    Registry --> CCPol["policies/clean-code.ts"]
    Registry --> ApiPol["policies/api-governance.ts"]
    Registry --> DataPol["policies/data-governance.ts"]
    Registry --> CRPol["policies/code-review.ts"]
    Registry --> ObsPol["policies/observability.ts"]
    
    Build --> Enrich["phases/enrichment.ts<br/>Claude Enrichment"]
    Build --> ADR["phases/adr.ts<br/>Architecture Decision Record"]
    
    style CLI fill:#FF6B35,color:#fff
    style Registry fill:#06B6D4,color:#fff
    style Framework fill:#22C55E,color:#fff

Development

git clone https://github.com/vishalm/vibe-init.git
cd vibe-init
npm install

npm run build          # Build with esbuild
npm run lint           # TypeScript type check
npm run test           # Run all 103 tests
npm run prerelease     # Full pre-release checks
npm run dev            # Watch mode

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Commit with conventional commits
4. Push and open a Pull Request

License

MIT