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.

Start with /vbw:doctor. It runs 16 health checks across your VBW installation and project setup, and tells you exactly what’s wrong.

​
Running /vbw:doctor

/vbw:doctor
/vbw:doctor --cleanup
/vbw:doctor checks:
#Check
1jq installed
2VERSION file present
3Version synced with marketplace.json
4Plugin cache present and valid
5hooks.json valid JSON
6Agent YAML files present (expects 7: lead, dev, qa, scout, debugger, architect, docs)
7config.json valid JSON (project only)
8Script file permissions (executable)
9gh CLI available
10sort -V support
11Stale agent teams
12Orphaned processes
13Dangling PIDs in .vbw-planning/.agent-pids
14Stale markers
15Watchdog status (tmux only)
16CLAUDE.md sections up to date
/vbw:doctor --cleanup goes further: it cleans stale teams, orphaned processes, dangling PIDs, and stale markers. It also refreshes VBW-owned sections of CLAUDE.md without touching anything else.

​
Common issues

Check for stale teams and orphaned processes first:
/vbw:doctor --cleanup
If agents are still stuck:
  • Check .vbw-planning/.agent-pids for running agent PIDs
  • If you’re using tmux, check for orphaned panes that weren’t cleaned up
  • Look in .vbw-planning/phases/ for incomplete SUMMARY.md files — the TeammateIdle hook may be blocking if a SUMMARY.md is missing for a task that should be done
  • Re-run /vbw:vibe after cleanup — it resumes from the last completed state
Run /vbw:resume immediately:
/vbw:resume
/vbw:resume reads ground truth from .vbw-planning/ — STATE.md, ROADMAP.md, all plans, and all summaries — and rebuilds your full project context. It detects interrupted builds and tells you exactly what to do next. No prior /vbw:pause is required.
Prefer auto-compaction over /clear. Claude Code auto-compacts your context window intelligently when it fills up, preserving active plan tasks, file paths, decisions, and error context. VBW enhances this with PreCompact hooks and post-compaction verification. /clear bypasses all of this.
Check hook validity first:
/vbw:doctor
If check 5 (hooks.json) or check 8 (script permissions) fails:
  1. Re-run /vbw:init — it re-installs all hooks
  2. Verify that bash is available at the path your hooks expect
  3. Fix script permissions manually if needed:
chmod +x .claude/hooks/*.sh
If hooks still don’t run after re-init, check that hooks.json is not malformed by opening it directly and validating the JSON.
VBW’s bash-guard.sh blocks patterns like migrate:fresh, db:reset, and similar destructive database commands by default. This is intentional — see Database safety for the full list of blocked patterns.To allow destructive commands temporarily for a session:
VBW_ALLOW_DESTRUCTIVE=1 claude
To add project-specific patterns to the blocklist (additional commands to block beyond the defaults):
echo "scripts/nuke-dev-data\.sh" >> .vbw-planning/destructive-commands.local.txt
One regex per line. Local patterns supplement the built-in list — they don’t replace it.To disable the guard entirely (not recommended):
/vbw:config bash_guard false
Run /vbw:doctor and check that check 8 (script permissions) passes. The statusline scripts need execute permissions.If you’re using tmux, check these settings:
SettingEffect
statusline_hide_agent_in_tmuxHides agent info in tmux status bar
statusline_collapse_agent_in_tmuxShows a compact form instead
If you’re in a monorepo, the statusline config is resolved by walking up from your current working directory to find .vbw-planning/config.json. Make sure you run VBW from the right subdirectory — the one that contains (or is a child of) your .vbw-planning/ folder.
Parallel execution requires all of the following to be true:
  1. Plans have no depends_on in their YAML frontmatter
  2. The prefer_teams config setting is "auto" or "always" (not "never")
  3. Claude Code Agent Teams are available in your subscription
Check your current team state with /vbw:status. If prefer_teams is set to "never", VBW forces solo mode regardless of codebase size or plan structure.
/vbw:config prefer_teams auto
VBW detects GSD during /vbw:init and offers to import your existing work automatically.To migrate:
  1. Run /vbw:init in your GSD project directory
  2. When prompted (“GSD project detected. Import work history?”), approve the import
  3. VBW copies .planning/ to .vbw-planning/gsd-archive/ and generates an INDEX.json
  4. Your original .planning/ directory is never modified or deleted
  5. Continue with /vbw:vibe — agents can reference the GSD archive for historical context
Key differences:
  • Commands: GSD uses /gsd:*, VBW uses /vbw:*
  • Planning directory: GSD uses .planning/, VBW uses .vbw-planning/
  • VBW warns at SessionStart if GSD is co-installed
If you want strict separation between the two systems while migrating incrementally, enable GSD isolation during init. This prevents agents from one plugin from accessing the other plugin’s planning directory.If you declined import during init and want to import manually:
cp -r .planning/ .vbw-planning/gsd-archive/
bash scripts/generate-gsd-index.sh
Run inside Claude Code:
/vbw:update
/vbw:update fetches the latest version and refreshes the plugin cache automatically. To see what changed:
/vbw:whats-new

Working with existing codebases

Brownfield init, codebase mapping, and session resumption.

Database safety

How bash-guard works and how to configure destructive command rules.

Build docs developers (and LLMs) love

Get started for freeTalk to us