VBW uses 7 specialized agents. Each agent has a defined role, an explicit tool allowlist, a platform-enforced denylist, and a permission mode. These constraints are declared in YAML frontmatter and enforced by Claude Code itself — not by instructions the agent could ignore during context compaction.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.
Agent overview
| Agent | Role | Tools allowed | Denied | Permission mode |
|---|---|---|---|---|
| Scout | Research and information gathering | Inherited + MCP (all except denied) | Bash, Edit, NotebookEdit, Task | plan |
| Architect | Creates roadmaps and phase structure | Read, Glob, Grep, Write | Edit, WebFetch, Bash | acceptEdits |
| Lead | Orchestrates planning and execution | Read, Glob, Grep, Write, Bash, WebFetch | Edit | acceptEdits |
| Dev | Writes code, makes commits | Full access | — | acceptEdits |
| QA | Goal-backward verification | Read, Grep, Glob, Bash | Write, Edit, NotebookEdit | plan |
| Debugger | Scientific method bug investigation | Full access | — | acceptEdits |
| Docs | Documentation specialist | Read, Grep, Glob, Bash, Write, Edit | — | acceptEdits |
Agent details
Scout — research and information gathering
Scout — research and information gathering
Scout gathers information from the web, documentation, MCP tools, and your codebase. It runs in
plan mode — it can read and write, but cannot execute commands or modify existing files.When it runs: /vbw:map launches 4 parallel Scout instances, each covering a different domain — tech stack, architecture, quality, and concerns. Scout also runs standalone via /vbw:research.What it writes: Research files directly to .vbw-planning/. Scout can only write to paths inside .vbw-planning/ and only to paths explicitly specified in its task prompt. It cannot create files anywhere else.Denied tools: Bash, Edit, NotebookEdit, Task. Scout cannot run commands, modify existing files, or spawn subagents. These denials are platform-enforced — they cannot be overridden even during context compaction.Security: Scout’s hook configuration blocks access to .env files and credential paths. It never reads secrets.Architect — roadmaps and phase structure
Architect — roadmaps and phase structure
Architect transforms your requirements into a structured roadmap. It writes planning artifacts —
PROJECT.md, REQUIREMENTS.md, ROADMAP.md — but never writes product code.When it runs: During /vbw:init and when /vbw:vibe enters scope mode for a new project or new phase.What it produces: A phased roadmap with goal-backward success criteria, requirement IDs with acceptance criteria, and phase stubs that Lead will decompose into plans.Denied tools: Edit, WebFetch, Bash. Architect uses Write to create new planning files but cannot modify existing files, fetch external documentation, or run shell commands. It works from what’s already in the codebase and your input.Write scope: Architect is constrained by instruction to write only to .vbw-planning/ paths. The file-guard hook enforces this at the platform level.Lead — orchestrator
Lead — orchestrator
Lead is the planning and orchestration agent. It reads research from Scout and roadmaps from Architect, decomposes a phase into plans, and spawns Dev agents to execute them.When it runs: During
/vbw:vibe --plan (or when vibe auto-detects the plan phase). Lead also orchestrates execution — it spawns Dev teammates, monitors their progress, collects summaries, and runs QA at the end of the phase.What it produces: PLAN.md files — one per plan, written immediately to disk for compaction resilience. Each plan contains structured YAML frontmatter with tasks, dependencies, must-haves, and success criteria.Denied tools: Edit. Lead has Read, Write, Bash, and WebFetch — Bash for git history and directory exploration, WebFetch for external library documentation. It cannot edit existing files.Parallelism design: Lead maximizes wave parallelism when decomposing a phase. Plans in the same wave run simultaneously. Lead ensures plans in the same wave do not modify overlapping files — if two concerns touch the same file, they go in the same plan or are sequenced with depends_on.Dev — code execution
Dev — code execution
Dev writes code, makes commits, and builds things. It has full tool access and runs in
acceptEdits mode — it can read, write, edit, run commands, and commit.When it runs: During /vbw:vibe --execute (or when vibe auto-detects the execute phase). Lead spawns one Dev per plan. Each Dev works through its assigned plan’s tasks sequentially.Execution protocol:- Read PLAN.md from disk (source of truth)
- For each task: implement → verify checks → stage files → commit
- Write SUMMARY.md on completion
QA — goal-backward verification
QA — goal-backward verification
QA verifies completed work against the plan’s success criteria. It works backward from goals — deriving testable conditions from must-haves, then checking the actual code against those conditions.When it runs: Automatically at the end of each phase (after all Dev agents finish), and on demand via
/vbw:qa.Three verification tiers:- Quick (5–10 checks): File existence, frontmatter, and key strings
- Standard (15–25 checks): + structure, imports, links, and conventions
- Deep (30+ checks): + anti-patterns, requirement mapping, and cross-file dependencies
Write, Edit, NotebookEdit. QA cannot modify any files — these denials are platform-enforced. The only write path is piping its verification JSON through write-verification.sh via Bash. Any VERIFICATION.md not produced by this script is rejected.Deviation handling: Every deviation from the plan is a FAIL check. Deviations are defects — the plan was the agreement. QA also scans for undeclared deviations: mismatches between what PLAN.md specified and what the code actually contains.Permission mode: plan — QA proposes no interactive edits. It reads, runs Bash verification commands, and persists results through the deterministic write script.Debugger — bug investigation
Debugger — bug investigation
Debugger investigates bugs using the scientific method: hypothesis → evidence gathering → root cause → fix. It has full tool access and focuses on one bug per session.When it runs: Via
/vbw:debug. Scope creep is explicitly out of scope — Debugger commits one fix per session.Parallel investigation: At Thorough effort level with ambiguous bugs, Debugger spawns 3 parallel instances, each investigating a competing hypothesis. The strongest supported hypothesis wins.Protocol: Hypothesis → evidence → root cause → fix → commit. No exploratory commits. No fixing adjacent issues. One bug, one session, one fix.Docs — documentation specialist
Docs — documentation specialist
Docs writes and maintains documentation — READMEs, changelogs, API docs, and guides. It has read, write, edit, and Bash access, constrained by instruction to documentation files only.When it runs: Invoked by the orchestrator during
/vbw:vibe --archive for completion documentation, and on demand for documentation tasks.What it produces: READMEs, changelogs, API reference, inline code documentation, and guides. By instruction, it writes only to documentation files — not product code.Permission model
Three layers of control govern what each agent can do:tools — the explicit allowlist. If a tool isn’t on this list, the agent doesn’t have access to it.
disallowedTools — the platform-enforced denylist. These tools are blocked by Claude Code at the platform level. They cannot be overridden by instructions, cannot be unlocked during context compaction, and cannot be bypassed by any prompt. This is the hard boundary.
permissionMode — how the agent interacts with the session:
plan— no interactive edits. The agent can read and propose, but cannot apply changes interactively. Scout and QA both run inplanmode.acceptEdits— the agent can propose and apply changes. Lead, Dev, Architect, Debugger, and Docs all run inacceptEditsmode.
disallowedTools and permissionMode means that even if an agent’s instructions were overridden or degraded during compaction, the platform-level denials remain in effect. Scout cannot run Bash. QA cannot write files directly. These are hard constraints, not soft guidelines.
Permissions reference
Full reference for tool allowlists, denylists, and permission modes across all agents.
Execution model
How Lead, Dev, and QA coordinate across phases, plans, and tasks.