A pipeline of agents, each on the cheapest model that's safe for its job — where
"safe" is decided by one question: who catches the mistakes? Generated per harness by
vdb agents; executed through the same worktree/tmux delegation the
guides use.
The model tier compensates for the reviewer's ability to catch the model's mistakes. That single rule sets every tier on this page — and it inverts the intuition.
Notes from a template, Conventional Commits, status flips through a write tool. Nothing open-ended to get wrong — so nothing to review. Tier 1 never writes production code.
Work in a stack you know. A mid-tier model's bug doesn't survive your review, so paying for the top model buys nothing. Terse prompts: skip the tutorial, match the repo idiom.
Planning, review, and any stack you're still learning — where you can't reliably catch its mistakes. Counterintuitive corollary: declaring a stack "learning" makes its agent more expensive and more careful, not less.
A weak reviewer doesn't just miss bugs — it manufactures false confidence, and you stop
looking. Whatever acts as the safety net gets the best model: for a learning stack that's the
developer agent itself; for everything else it's vdb-reviewer, tier 3
unconditionally.
vdb agents --detect generates every agent file from three sources.
All of them carry the vdb- prefix and a pinned model: resolved from
your per-harness tier map (vdb models).
| Agent | Tier | Job |
|---|---|---|
vdb-planner | 3 | Turns a goal into a concrete plan + handoff. Errors here compound downstream. |
vdb-reviewer | 3 | The safety net. Reviews every delegated diff before it merges. Never economized. |
vdb-implementor | 2 | Orchestrator. Breaks the plan into tasks, routes each to the right agent, gates through review. |
vdb-default-developer | 2 | Bounded coding tasks in stacks without a dedicated agent. |
vdb-note-taker | 1 | Vault notes per the frontmatter contract. Formats, never invents. |
vdb-git-committer | 1 | Stages named files, writes a Conventional Commit. Never pushes, never amends. |
vdb-issue-updater | 1 | Status flips via vault_claim_story / vault_update_story_status / vault_mark_plan_executed. |
Declare what you work in and how well you know it; one
vdb-<stack>-developer is generated per stack. Expertise lives in the
user layer (~/.config/vdb/config.toml) because it's a property of you,
not of one vault; a vault can override per-stack (that work codebase where a familiar
language reads foreign).
vdb stacks set python expert # → vdb-python-developer, tier 2, terse vdb stacks set rust learning # → vdb-rust-developer, tier 3, explains + cites vdb stacks set "Next.js" working # names are slugified: vdb-next-js-developer vdb stacks list # merged view: user [stacks] < vault stacks:
Valid values: expert / working → tier 2,
learning / none → tier 3. Unknown values fail upward to
tier 3 — misconfiguration can never route to a weaker model. Expertise also shapes the
prompt: learning stacks get explain-and-cite guidance, familiar stacks get be-terse.
Skills are invoked via the Skill tool and don't need a duplicate agent entry. The few
marked delegate: true also become agents, buying model pinning + an isolated
context window for long sweeps: vdb-optimizer, vdb-weekly-review,
vdb-host-inventory-sync, vdb-shopping.
The implementor knows its roster — the generated agent list (name, stack, tier)
is baked into its prompt at vdb agents time, so routing is explicit, not guessed.
The review gate is a rule, not a suggestion: code headed for a commit goes through
vdb-reviewer first, every time.
/skill-name — you invoke it (an agent skill)
vault_tool() — called automatically over MCP
You hand vdb-planner the goal. It reads the code and the vault
(vault_search(), vault_source_repos()),
produces steps with file-level touch points, flags the decisions that are yours to make, and
writes the result out via /vdb-handoff — a durable note, not a
chat scrollback.
The handoff seeds an implementor in an isolated worktree — the same delegation machinery
as the background-agent guide: interactive
(/vdb-handoff-session, a tmux session you can take over) or
fire-and-forget (/vdb-dispatch). Either way it lands in the
vault_agent_sessions() ledger.
vdb spawn launch --name checkout-retry --handoff-src Handoffs/checkout-retry.md
vdb sessions # status of every delegated session
The implementor splits the plan: the Rust service change goes to
vdb-rust-developer (tier 3 — you marked rust learning, so that agent
explains its choices and cites docs), the Python glue goes to
vdb-python-developer (tier 2 — you'd catch its bugs), and anything without a
stack agent falls through to vdb-default-developer.
Before anything is committed, the diff goes through vdb-reviewer on the top
tier: findings come back as file:line + failure scenario + fix, with an explicit verdict.
Findings route back to the implementor; only an approval moves forward.
Tier 1 closes it out: vdb-git-committer writes the Conventional Commit,
vdb-issue-updater flips the story via
vault_update_story_status(), and vdb-note-taker
records the outcome in the vault. Fixed shapes, cheap model, zero judgment required.
Every generated agent is a plain text file — markdown with frontmatter for Claude Code and Pi, JSON for Gemini and Antigravity. They're starting points, not contracts: tighten a prompt, add house rules, re-order the process.
Change ~/.claude/agents/vdb-rust-developer.md and try it. Each generated file
carries a content fingerprint, so vdb agents detects your edit and skips
the file on the next run instead of clobbering it (--prune keeps edited
strays too). --force reclaims a file for regeneration — or just delete the
x_vdb_hash line.
Regeneration reads from your template clone, so edits there survive every run and apply to
every harness: agents/roles/*.md for a role,
agents/templates/stack-developer.md for all stack agents at once, and the
skill's SKILL.md for delegated skills.
Constrained roles ship a tools: allowlist that the Claude Code and Pi renderers
enforce — tier 1's "fixed output shape" is guaranteed by capability, not just prompt:
vdb-git-committer gets Bash, Read, Grep (it can commit but cannot
write files), vdb-note-taker can write files but has no Bash,
vdb-reviewer can run tests but cannot edit (it reports; the implementor fixes).
The orchestrator and developer agents inherit everything. One caveat: the allowlists grant
vault MCP access as mcp__vault-index — if you registered the MCP server under a
different name, adjust that token in the role file (the fingerprint keeps your edit).
External systems the template can't know about — your Jira MCP, a
GitHub tracker — are granted per agent with agents.extra_tools, which
extends the allowlist (unconstrained agents already have everything, so grants
there are ignored with a warning rather than accidentally restricting them):
[agents.extra_tools] vdb-issue-updater = "mcp__jira, mcp__github" # flip tickets in external trackers too vdb-git-committer = "mcp__gitlab" # same fixed-shape rules apply
Both review seams are named plug-in points, not hardcoded agents. Set
agents.reviewer and the implementor routes every code review through yours —
there are excellent reviewer agents and skills out there, and the pipeline shouldn't stop you
using one. Set agents.plan_reviewer and the planner puts its finished plan in
front of that instead of plain user approval — a plan-annotation tool like plannotator slots
in here. The user layer applies everywhere; a vault can override (say, a stricter reviewer
for the work vault):
# user layer (config.toml) # vault layer (vdb-config.yaml)
[agents] agents:
reviewer = "pr-review-toolkit" reviewer: security-first-reviewer
plan_reviewer = "plannotator-review" plan_reviewer: architecture-board
Re-run vdb agents: the implementor's
review-gate step and its roster both pick up the new name. vdb-reviewer is still
generated so you can switch back or A/B them — and lighter-touch options work too: edit
vdb-reviewer's prompt in place (the fingerprint protects it), or keep it as the
router and have it invoke review skills (e.g. a /code-review or
/security-review skill your harness ships) as part of its process.
In Claude Code, the built-in /agents command edits subagents interactively.
Anthropic's skill-creator skill guides
authoring and tightening agent instructions, and their
Building effective
agents essay is the harness-agnostic reference for what belongs in an agent prompt and
what doesn't. Or simplest: paste the agent file into any capable model and ask it to critique
the prompt against a transcript of the agent's last run.
vdb stacks set rust learning # declare expertise (repeat per stack) vdb models # see detected models per harness + tier vdb agents --detect --prune # write agent files; drop stale vdb-* ones
Or let /vdb-setup ask — the interview collects stack
expertise (§1c) and the tier→model map (§1h2), then generates everything. Re-run
vdb agents whenever stacks or models change.