VIBESTRATE.md

VIBESTRATE.md is a committed file at your project root saying what this project is and how you like it run: its domains, its commands, the conventions you keep having to repeat.

# VIBESTRATE.md

## Project Model
A billing service. Money flows through `src/ledger/` and nothing else writes to it.

## Development Commands
pnpm install · pnpm typecheck · pnpm test · pnpm build

## Risk Rules
Propose sandbox mode when a task touches provider execution or credential paths.

You read it back through consult - the orb in the corner of every dashboard page. Ask “should this use a heavier review?” and the answer is grounded in your manual rather than guesswork.

vibe ui, then the orb, or the Consult page directly. Its This project side answers from your manual, your config and your recent runs; Work in Vibestrate answers about the product itself.

An answer can carry a proposed addition to the manual, and nothing is written until you press Apply to VIBESTRATE.md. Rejecting one keeps it on record rather than deleting it.

vibe shell has the same Consult tab, with a to apply a proposal, x to reject and r to refresh. On the CLI:

vibe consult "should this use a heavier review?"
vibe guide show                # print the manual
vibe guide init                # scaffold a starter one
vibe guide proposals           # open proposals
vibe guide apply <id>          # append a proposal's text

Headings that earn their place, written in plain prose. Project Model, Development Commands and Risk Rules, as in the sample at the top, plus any of:

## Orchestration Preferences
Preferred flows and crews; when to go heavier.

## Codebase Conventions
## Known Constraints
## Lessons Learned

Next to the manual sits a different kind of memory: .vibestrate/CODEBASE.md and .vibestrate/codebase-map.json. Where VIBESTRATE.md is your intent, the map is a deterministic scan - stack, scripts, layout, languages, entry points, best-effort HTTP routes, tooling markers. Nobody writes it by hand, and the same repo state always produces the same map, so there is nothing to keep in sync.

It has a screen of its own: Codebase, then the Map chip above the file tree. Project type, package manager, tracked-file and route counts, then Commands, Layout, Entry points and HTTP routes (best effort). Generate map on a project without one, Refresh map after that, and a stale marker once your HEAD has moved past the version on disk.

It also refreshes itself whenever a run reaches a terminal outcome. vibe learn regenerates it from a terminal; vibe learn show prints CODEBASE.md with the same staleness note.

The same scan collects your codebase’s TODO and FIXME comments. Those are a third kind of memory again: not your authored intent and not a fact about the project’s shape, but candidate work your team already wrote down. They are kept out of the map itself - it carries only the counts - and live in .vibestrate/roadmap/todos/, because the roadmap is what consumes them. Nothing reaches the Board without an explicit promote. See Picking up a project already underway.

The planner, by default, and only the planner. That is deliberate: every other role stands in the worktree, holding a plan that already names the files, running an agent CLI that opens them natively. A generated summary costs those roles tokens every turn and gives them a second, staler account of a repo they can already read. The planner has to name real files before it has read anything, which is why it is the exception.

Widen the audience when the crew cannot explore for itself - a small local model, a sandbox with no file tools - or when the flow has no planner seat at all. express, scaffold and quality-arbitration are all in that category, so none of them sees a map whatever else is configured:

codebaseMapRoles: [planner, implementer]

Names are crew role ids, and each listed role is oriented once per run, so a role taking several turns does not pay again.

consult, safety, configuration.