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.

VBW runs on a loop. You run /vbw:init once, then /vbw:vibe until your project is done. Every time you run /vbw:vibe, it reads ground truth from .vbw-planning/, figures out exactly where you are, and does the right thing — no flags required.

​
The lifecycle loop

                YOU HAVE AN IDEA
                       │
          ┌────────────┴────────────┐
          │                         │
    Greenfield                  Brownfield
          │                         │
   /vbw:init                  /vbw:init
   Scaffold                   Map codebase
          │                   (4 Scouts)
          └────────────┬────────────┘
                       │
                  /vbw:vibe
              Auto-detects state:
           No project?  → Scope
           No phases?   → Plan
           UAT issues?  → Remediate
           Planned?     → Execute
           All done?    → Archive
                       │
                  /vbw:qa
              Three-tier verification
              Outputs: VERIFICATION.md
                       │
             ┌─────────┴─────────┐
             │                   │
         More phases?        All done?
             │                   │
       Loop back to         /vbw:vibe --archive
        /vbw:vibe           Audit, tag, archive

​
Three modes when running /vbw:vibe

When you run /vbw:vibe, VBW auto-detects which mode applies based on what’s in .vbw-planning/. You never need to specify — but you can use explicit flags if you want control.
No existing codebase. VBW scaffolds .vbw-planning/, asks about your project, and generates a phased roadmap. Then it moves straight to planning and execution./vbw:init handles the setup automatically and auto-chains to /vbw:vibe. You answer a few questions and VBW starts building.
An existing codebase is detected during /vbw:init. VBW auto-chains four workflows in sequence: it runs /vbw:map with 4 parallel Scout agents across tech stack, architecture, quality, and concerns — then uses the map data to inform skill suggestions before auto-chaining to /vbw:vibe with full codebase awareness.You run one command. VBW does the codebase analysis, planning, and execution with context baked in.
Closed your terminal? Switched branches? Came back after a weekend? Run /vbw:resume.VBW reads ground truth directly from .vbw-planning/ — STATE.md, ROADMAP.md, plans, summaries — and rebuilds your full project context. It detects interrupted builds, reconciles stale execution state, and tells you exactly what to do next. No prior /vbw:pause needed.
Do not use /clear to reset your session. 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 /clear, run /vbw:resume immediately.

​
The .vbw-planning/ directory

All VBW state lives here. It’s the source of truth for every agent, every session, and every command.
FileWhat it contains
STATE.mdCurrent phase, execution status, and what happens next
ROADMAP.mdAll phases, their goals, dependencies, and success criteria
PLAN.mdTask-level breakdown for the current phase (written by Lead)
SUMMARY.mdWhat each Dev agent built and committed (written on plan completion)
config.jsonYour effort profile, autonomy level, concurrency settings, and model routing
VBW also writes research, verification, and milestone artifacts here as your project progresses. The directory survives terminal closes, branch switches, and context compaction.

​
State persistence

VBW knows where you are because everything is written to disk immediately. No in-memory state. No session dependency. When you run /vbw:vibe:
  1. It reads STATE.md to find the current phase and status.
  2. It reads ROADMAP.md to understand what phases exist and what’s been completed.
  3. It reads any existing PLAN.md files to see what’s been planned.
  4. It checks SUMMARY.md files to confirm what’s been built.
  5. It does the right thing based on what it finds.
This means you can run /vbw:vibe from any terminal, any day, and it picks up exactly where you left off. Phase 1 done? It moves to Phase 2. Phase 2 interrupted mid-execution? It resumes from the last completed task.

Execution model

How phases, plans, and tasks map to agent work — and how concurrency is controlled.

Agents

The 7 specialized agents, their tools, and the permission model that constrains them.

Build docs developers (and LLMs) love

Get started for freeTalk to us