Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/swt-labs/vibe-better-with-claude-code-vbw/llms.txt

Use this file to discover all available pages before exploring further.

When you run /vbw:init in a directory that already has code, VBW detects the existing codebase and runs the full brownfield onboarding flow automatically. One command kicks off codebase analysis, stack detection, skill suggestions, and project planning — in sequence, with no manual steps.

​
The brownfield init flow

1

Run /vbw:init

VBW detects that source files already exist and switches to brownfield mode.
2

/vbw:map — parallel Scout analysis

VBW launches Scout teammates to analyze your codebase across four domains simultaneously. Depending on codebase size, it runs 1, 2, or 4 Scouts. Results are written to .vbw-planning/codebase/.
3

Stack detection

VBW identifies your tech stack from the map results — not just from manifest files, but from what’s actually used in your code.
4

Skill suggestions

Curated skill recommendations from skills.sh are surfaced based on the detected stack and codebase findings.
5

/vbw:vibe — planning with codebase context

VBW auto-chains into /vbw:vibe with full codebase awareness. The Lead agent reads INDEX.md and PATTERNS.md when generating plans.

​
How /vbw:map works

/vbw:map analyzes your codebase using specialized Scout teammates, then synthesizes their findings into structured documents your agents reference throughout the project.

​
The four Scout domains

ScoutWhat it analyzes
Tech ScoutDependencies, package managers, frameworks, language versions
Architecture ScoutModule structure, entry points, patterns, component boundaries
Quality ScoutCode conventions, test coverage, technical debt, code smells
Concerns ScoutSecurity issues, deprecated dependencies, configuration risks
Each Scout writes its findings directly to .vbw-planning/codebase/. After all Scouts complete, /vbw:map synthesizes the results into two summary documents:
  • INDEX.md — cross-referenced index of key findings with validation notes for contradictions
  • PATTERNS.md — recurring architectural, naming, quality, and dependency patterns

​
Codebase size and tier selection

/vbw:map scales automatically based on codebase size:
TierSource filesStrategy
solo< 200Orchestrator maps all domains inline
duo200 – 1,0002 Scouts, combined domains
quad1,000+Full 4-Scout team
You can override the tier with --tier=solo, --tier=duo, or --tier=quad. Agent Teams must be enabled — if they’re not, /vbw:map falls back to solo mode automatically.

​
Monorepo support

/vbw:map detects monorepos by looking for multiple build system roots (package.json, Cargo.toml, go.mod, pyproject.toml, and others at different directory levels). To scope the map to a single package, pass --package=<name> or run /vbw:map from the package subdirectory.

​
Security enforcement

/vbw:map never reads .env files or credential files. The PreToolUse hook enforces this for all Scout agents.

​
Planning with codebase context

Once the map is complete, every agent in your project has access to what’s actually in your code:
  • The Lead agent reads INDEX.md and PATTERNS.md when creating execution plans, so plans reference real file paths and respect existing patterns.
  • Dev agents know which files they own from the plan, based on the architecture map.
  • QA verifies against conventions surfaced by the Quality Scout.

​
Map staleness

Your codebase map can fall out of sync when the code changes significantly. The SessionStart hook detects staleness automatically and warns you when the map is out of date. Re-run /vbw:map after:
  • Major refactors that reorganize modules or change the architecture
  • Adding new packages or dependencies that change your stack profile
  • Starting a new milestone on a codebase you haven’t touched in a while
  • Any time Scout agents seem to have incorrect assumptions about your project structure
/vbw:map
/vbw:map --incremental
/vbw:map --package=api
--incremental compares the current git HEAD to the HEAD recorded in META.md and re-maps only changed areas. VBW selects incremental mode automatically when fewer than 20% of files changed since the last map.

​
Session resumption

When you return to a project — after closing your terminal, switching branches, or coming back after time away — run /vbw:resume to restore full project context. 
/vbw:resume
/vbw:resume reads ground truth directly from .vbw-planning/:
  • STATE.md — current phase, decisions, todos, blockers
  • ROADMAP.md — all phases and their completion status
  • phases/**/*-PLAN.md and phases/**/*-SUMMARY.md — plan and completion counts
  • .execution-state.json — detects interrupted builds
It reconciles stale execution state, detects interrupted builds, and tells you exactly what to do next. No prior /vbw:pause is required.
Do not use /clear. It destroys your entire context — every file read, every decision made, every in-progress task. Auto-compaction is surgical; /clear is a sledgehammer.If you accidentally use /clear, run /vbw:resume immediately. It restores project context from ground truth files in .vbw-planning/.

Skills integration

How VBW detects your stack and installs community skills automatically.

Troubleshooting

Fix common issues with agents, hooks, and context.

Build docs developers (and LLMs) love

Get started for freeTalk to us