vibes

README

vibes

A sidecar context workspace for agentic engineering: typed markdown documents that live next to your repos, not inside a vendor's memory feature. Agents read and write them, humans review them, and they survive switching tools.

• FRAMEWORK.md — the method (Part 1, tool-free) and the conformance spec (Part 2, normative).
• CLI.md — command specification.
• skills/vibes/SKILL.md — an agent skill teaching the method.

Why

Engineering context — what's true in this codebase, what we decided and why, what review found — has to live somewhere. Chat history dies with the session. Vendor memory locks it to one tool. Repo docs can't hold cross-repo work. Most of it cannot be reconstructed from git: a commit shows what changed, not the three options you considered.

Install

Requires Go 1.22 or newer.

go install github.com/brdv/vibes@latest

Check it worked:

vibes -h

vibes: command not found?

go install puts the binary in $GOBIN, or $GOPATH/bin when GOBIN is unset — usually ~/go/bin. Print the exact directory and add it to your PATH:

go env GOPATH        # binary is in <that path>/bin

# add to ~/.zshrc (or ~/.bashrc), then restart your shell
export PATH="$PATH:$(go env GOPATH)/bin"

If vibes runs but seems to ignore an upgrade, you probably have a second copy earlier in your PATH. which -a vibes lists every one it can find; delete the stale ones.

From source

git clone https://github.com/brdv/vibes
cd vibes
go install .        # same destination as above

Or drop the binary wherever you like:

go build -o /usr/local/bin/vibes .

Use

vibes init                              # scaffold a workspace, register repos
vibes search "guest checkout"           # ALWAYS do this before creating anything
vibes new findings "Current state" -topic checkout-flow
vibes lint                              # must exit 0 before you call the work done
vibes index                             # regenerate INDEX.md and AGENTS.md
vibes status                            # open decisions, unresolved contracts, staleness

Importing an existing pile of markdown:

vibes migrate            # dry run — prints the inference table, writes nothing
vibes migrate -apply

What makes it more than a folder of markdown

The linter. Every serious failure mode observed in a real 116-document workspace is mechanically detectable:

Failure	Rule
A session re-creates a document that already exists	vibes new refuses near-duplicates
One API contract defined in four documents, disagreeing	V3 — one active provider per key
A contract consumed but owned by nothing	V4
"Status: complete" above 30 unchecked boxes	V9
A decision with answers but still marked open	V10
Links broken by moved files	V7

Retiring a document — moves it, transfers contract ownership, and repoints every inbound link so nothing dangles:

vibes archive old-design -superseded-by new-design -reason "Replaced by async v2." -dry-run

Versioning and releases

Versions come from semver git tags — that is the whole mechanism. Tag, push the tag, and go install github.com/brdv/vibes@latest resolves to it.

git tag v0.1.0
git push origin v0.1.0

vibes version reports build identity with no build flags, because the Go toolchain embeds it from VCS:

$ vibes version
vibes v0.1.0
  commit    ba98102882ac9782054e37ac4e3c53e3e4c3f108
  committed 2026-07-27T12:51:20Z
  go        go1.26.5
  platform  darwin/arm64

vibes -v prints the one-line form. Builds that are not on a tag report a pseudo-version (v0.1.1-0.20260727125121-7f144c779d67), and builds from a modified working tree say (dirty) — so a bug report always identifies the exact source.

Two things worth knowing:

• Don't rely on -ldflags alone. go install pkg@version cannot pass build flags, so an ldflags-only version reads dev for everyone installing the documented way. An -X github.com/brdv/vibes/internal/version.stamped=… override exists for release automation, but VCS-derived versioning is the default for good reason.
• v2 changes the module path. Going to v2.0.0 or beyond requires the module path to become github.com/brdv/vibes/v2 (a Go module rule, not a convention). Staying in v0.x while the type taxonomy settles avoids that, and signals the API may still move.

Status

Implemented: init, new, index, lint, search, show, status, archive, migrate, version.

Not yet implemented: open, link, lint --fix for every mechanical rule. See the build order at the end of CLI.md.

The type taxonomy is inferred from one real corpus and should be treated as provisional — run vibes migrate (dry run) against your own documents and check the inference table before trusting it.