vibe-engineer

Vibe Engineer

Documentation-driven development for AI-assisted coding.

ve is a CLI for organizing AI-assisted code changes around architectural intent. Vibe coding is magic on day 1: you describe what you want, the agent builds it, it works. Day 2 breaks because the codebase kept the implementation but not the judgment that produced it. ve adds the missing layer: chunks that record why a piece of the system has the shape it has and stay current as the code evolves.

Website: veng.dev

Installation

From PyPI

pip install vibe-engineer

Or with UV:

uv tool install vibe-engineer

From Git

Install directly from the repository:

uv tool install git+https://github.com/netguy204/vibe-engineer.git

Or install from a local clone:

git clone https://github.com/netguy204/vibe-engineer.git
cd vibe-engineer
uv tool install .

After installation, the ve command is available from anywhere:

ve --help
ve init
ve chunk create my-feature

To upgrade to the latest version:

uv tool upgrade vibe-engineer

To uninstall:

uv tool uninstall vibe-engineer

Upgrading from 0.x entities (pre-worktree)

VE 1.0 attaches entities as git worktrees of a shared canonical clone in ~/Entities/<name>. VE 0.x attached them as git submodules. The 1.0 attach code has no submodule code path: it cannot detect or upgrade in-place a 0.x submodule attachment.

If you have any .entities/<name> directories created by VE 0.x, do this before upgrading ve:

1. In each project, ve entity list to see what is attached, then ve entity detach <name> (with your existing 0.x ve) for each one. Commit the resulting .gitmodules deletion.
2. Upgrade ve (e.g. uv tool upgrade vibe-engineer).
3. Create ~/.ve-config.toml once for this machine:

   entities_dir = "~/Entities"
   git_base = "[email protected]:my-org"
   

4. In each project, run ve entity attach <name> to re-attach via the worktree pathway. The canonical clone at ~/Entities/<name> is cloned on first use and shared across every project on this machine.

If you skip step 1, VE 1.0 will refuse to clobber the pre-existing .entities/<name> directory at attach time — your old submodule sits untouched until you remove it by hand.

For the full rationale and a script-friendly version, see docs/chunks/entity_worktree_attach/MIGRATION.md.

Claude Code Plugin

This repository is also a Claude Code plugin marketplace. The plugin is the distribution channel for the agent-facing workflow content (slash commands, skills, hooks, subagents); the ve CLI installed above remains the workflow engine that the plugin shells out to.

Install the plugin from within Claude Code:

/plugin marketplace add netguy204/vibe-engineer
/plugin install vibe-engineer

Or from a local checkout:

/plugin marketplace add /path/to/vibe-engineer
/plugin install vibe-engineer

Both the plugin and the ve CLI are required: install the CLI with uv/pip (see above), install the plugin through Claude Code, and run ve init in your project to scaffold the workflow documentation. Plugin updates arrive through /plugin update vibe-engineer — no re-rendering into your repository.

Session hook

The plugin installs a SessionStart hook that runs whenever you open a session inside a ve project (detected by docs/trunk/GOAL.md). It surfaces the currently IMPLEMENTING chunk, and when the ve CLI is missing it installs it for you from the plugin's own checkout (uv tool install), announcing what it is doing first — so on a machine with uv, installing the plugin is the only setup step (see DEC-013 in docs/trunk/DECISIONS.md). Installs the hook created this way are kept version-synced with the plugin automatically; a ve you installed yourself is never touched — the hook only warns when the versions diverge. The plugin and the ve package are co-versioned: they are compatible when their major.minor versions match (DEC-011). Check your CLI version with ve --version. Without uv the hook falls back to a one-line install hint, and outside ve projects it is silent.

Usage (Building with the Vibe Engineering workflow)

Initialize a Project

Initialize the vibe-engineer scaffolding in a project:

ve init

This creates docs/trunk/ for project-level docs (GOAL, SPEC, DECISIONS, TESTING_PHILOSOPHY), docs/chunks/ for the work itself, and AGENTS.md plus CLAUDE.md so agents know how to navigate the layout.

Edit docs/trunk/ next: this is where you describe what the project is for and the rules an agent should respect when working in it. The docs/trunk/ of this repository is a worked example.

Migrating from the legacy rendered layout