Quickstart

ve is a CLI for organizing AI-assisted code changes around architectural intent. Engineering isn't about writing code; it's about making architectural choices that hold the implementation in productive shape over time.

Code owns how the system works: mutable, refactorable, tactical. Chunks own why a piece of the system has the shape it has, and stay current as the implementation evolves underneath them. Most engineering effort with ve goes into chunks; agents handle the typing.

This page gets you from zero to a completed first chunk.

1. Install

$ uv tool install vibe-engineer

pip install vibe-engineer works too. ve is a Python package; it has no opinions about your project's language.

2. Initialize a project

$ cd path/to/your/project
$ ve init

What this creates:

• docs/trunk/: project-level docs (GOAL, SPEC, DECISIONS, TESTING_PHILOSOPHY, and others)
• docs/chunks/: where each chunk lives
• AGENTS.md and .agents/skills/: agents-standard orientation and skill layout. This is the source of truth.
• CLAUDE.md and .claude/commands/: symlinks into the above, so Claude Code finds the orientation and skills in the layout it expects. No duplication; just a shim. Other harnesses get similar shims as we add them.

ve init is safe to run repeatedly, and you should re-run it as new versions of ve ship. Files that describe the ve workflow itself (skill templates, command files, internal docs) get overwritten with the latest versions. Files you also edit, like AGENTS.md, use marked sections: ve refreshes its own content and leaves your additions untouched.

3. Complete the trunk docs

Brain-dump the big purpose and intent of your project to the agent and ask it to complete the docs/trunk/ directory. The agent is good at turning a vibey intent into a clean breakdown across the templates: GOAL.md captures the problem and success criteria, SPEC.md the technical shape, DECISIONS.md the early architectural choices, TESTING_PHILOSOPHY.md the testing approach.

This is the anchor every chunk traces back to. You don't have to get it perfect on the first pass; revise as you learn.

4. Pick something chunk-worthy

Not every change earns a chunk. Apply one test: does this code need to remember why it exists?

• Yes: there's a contested design decision, a constraint that future contributors will accidentally break, or a tradeoff worth recording. Make a chunk.
• No: typo, dep bump, mechanical rename, an off-by-one that was just wrong. Vibe it. A chunk would add ceremony without adding memory.

Both paths end in a commit; the difference is whether you're recording architectural intent on the way.

For your first chunk, pick something on the "yes" side. A small but real architectural decision is the cleanest first run.

5. Run /chunk-create

Describe the chunk-worthy thing you picked and ask your agent to use /chunk-create. The skill scaffolds the chunk directory and walks you through writing GOAL.md, refining your vibey intent in light of the existing code and the project's trunk goal. This is where the architecture work happens.

Under the hood the skill calls ve chunk create to instantiate the templates. You'll see this pattern across ve: skills are the operator-facing surface where intent gets shaped, CLI commands are plumbing.

A chunk directory now exists at docs/chunks/<your_chunk>/ with two files:

• GOAL.md: the architectural record. Why the code has the shape it has, written in present tense so it ages well.
• PLAN.md: still a template at this point. The next skill fills it in.

Status is IMPLEMENTING. Only one chunk can be IMPLEMENTING at a time per worktree, which keeps an agent's attention bounded.

6. Run /chunk-plan

The skill writes PLAN.md as a literate-programming bridge from the codebase as it stands today to the codebase that satisfies the goal. Read it. If the plan goes somewhere surprising, the goal didn't constrain the solution tightly enough; refine the goal and regenerate the plan. If the plan reads as the path you'd have taken, the goal was specific enough.

7. Run /chunk-implement

The agent works through the plan. When it writes code that the chunk's intent governs, it adds a backreference comment near the top:

# Chunk: docs/chunks/<your_chunk> - Brief description

The next agent that reads the code follows that comment back to the chunk and learns why the code is the way it is. Backreferences accumulate as chunks land; the codebase teaches the next agent instead of handing it a blank slate.

8. Run /chunk-complete

The skill walks the chunk's code_references, verifies they resolve to real symbols, fills in any references the agent collected during implement, and flips status from IMPLEMENTING to ACTIVE. It also scans for other chunks that govern the same code, surfacing potential COMPOSITE situations early. The chunk now owns the intent that governs the code it produced.

Greenfield or legacy

These steps work the same on a brand-new project and on a legacy codebase you're retrofitting. The difference is when you can hand things off to the orchestrator.

Greenfield projects can reach for the orchestrator immediately, because you've been articulating the architecture as chunks from day one. Legacy projects need a few chunks of scaffolding first: a clean trunk and a handful of chunks that stake out the parts of the architecture the agent will need to reason about. Once that's in place, the orchestrator works just as well on the legacy project.

What next

• Most days are a sequence of chunks. The chunks page goes deeper.
• When work is too big for one chunk, write a narrative first.
• When you don't yet know what the work should be, run an investigation.
• Pain points you keep hitting? Log them in the friction log.
• To run multiple chunks in parallel, use the orchestrator.