vibe-doc

Vibe Doc

AI-powered documentation gap analyzer for modern codebases. Scan your project, identify missing technical documentation, and generate professional docs from your existing artifacts in minutes.

The Problem

Vibe coding produces real artifacts fast — working code, architecture decisions, test suites, deployment configs. But corporate documentation requirements don't care about your momentum. You need ADRs, runbooks, threat models, API specs, and deployment procedures. Writing them by hand is bureaucratic overhead. Ignoring them is a shipping risk.

Vibe Doc bridges the gap. It analyzes what you've actually built, finds the documentation holes, and generates the docs you need.

How It Works

Vibe Doc operates in four stages:

1. Scan — Walk your codebase. Extract artifacts, identify patterns, build a project profile.
2. Classify — Hybrid classifier (rules + LLM) determines your project type and architecture patterns.
3. Gap Analysis — Cross-reference your artifacts against the 7-doc v1 standard. Generate a prioritized gap report.
4. Generate — Create missing docs from your existing code, configs, and conversations.

The dual-layer design means you get intelligent recommendations in conversations (Skills) and deterministic, reproducible outputs from the CLI.

Installation

Pick whichever matches how you're running Claude Code. All three lead to the same plugin working.

Option 1: Claude Desktop — Add marketplace (recommended)

The cleanest install. Pulls straight from GitHub, no file download, supports Sync to update.

1. Open Claude Desktop → Personal plugins panel
2. Click the + button → Add marketplace
3. Enter: estevanhernandez-stack-ed/Vibe-Doc
4. Click Sync

Claude Desktop reads .claude-plugin/marketplace.json at the repo root and loads the vibe-doc plugin from inside ./packages/vibe-doc. The slash commands (/scan, /generate, /check, /status) become available.

Option 2: Claude Code CLI — Plugin manager

Use the built-in plugin manager from any Claude Code CLI or IDE terminal session.

/plugin marketplace add estevanhernandez-stack-ed/Vibe-Doc
/plugin install vibe-doc@Vibe-Doc
/reload-plugins

After reload, type / and you'll see the Vibe Doc commands (/scan, /generate, /check, /status) in autocomplete. This installs the plugin only — for the standalone CLI binary, also install via npm (Option 3).

Option 3: Claude Code CLI + terminal CLI — npm

The only path that gives you both the Claude Code plugin surface and a standalone vibe-doc binary you can run from any terminal.

npm install -g @esthernandez/vibe-doc
vibe-doc --version
# 0.3.0

Now you can run Vibe Doc either conversationally via Claude Code slash commands (install Option 1 alongside this), or deterministically from any shell:

cd ~/Projects/my-app
vibe-doc scan
vibe-doc generate adr
vibe-doc check --threshold 20

The dual-layer design means CI/CD pipelines use the CLI (reproducible, no conversational loop), and interactive sessions use the skills (agent-interviewed, conversational fill).

Option 4: Claude Desktop — Upload plugin (for local iteration)

For testing plugin changes locally before pushing to GitHub.

1. Clone the repo: git clone https://github.com/estevanhernandez-stack-ed/Vibe-Doc

2. Build a .plugin bundle:

   python scripts/build-plugin.py
   

   This writes bundles/vibe-doc-<version>.plugin — a zip archive Cowork accepts directly. The script excludes dist/, node_modules/, and other runtime artifacts per Cowork's plugin spec.

3. In Claude Desktop → Personal plugins → + → Upload plugin, pick the .plugin file.

You can also download a pre-built .plugin file from the GitHub releases page — each tagged release ships a ready-to-upload asset.

Which option should I use?

Situation	Option
I want to use Vibe Doc conversationally in Claude Desktop	Option 1 (Add marketplace)
I use Claude Code CLI or an IDE terminal	Option 2 (Plugin manager)
I want the vibe-doc CLI available in my terminal / CI / IDE	Option 3 (npm) — pair with Option 1 or 2 for full coverage
I'm developing or testing plugin changes locally	Option 4 (Upload plugin)
I want to install without an internet connection	Option 4 — download .plugin from releases ahead of time

Quick Start

Step 1: Scan Your Project

/scan
# or via CLI:
npx vibe-doc scan