Dobby — Kit de Engenharia Agentic para Claude Code
kvnwolf/dobby
Disciplina agentic: arquiteto planeja, workers executam, revisores verificam
Ver no GitHubKit que estrutura o fluxo de trabalho entre um arquiteto (sua thread principal) e quatro agentes workers especializados (pesquisador, implementador, revisor, verificador). Cada mudança é implementada, revisada e verificada independentemente, garantindo qualidade e rastreabilidade. Elimina a desordem de contexto mantendo decisões na thread principal e execução delegada.
Instalação
npx convez-ai kvnwolf/dobby1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Projetos de médio/grande porte que precisam de código revisado e testado
- Quando contexto está grande e decisões ficam misturadas com implementação
- Features complexas que requerem pesquisa, design e verificação iterativa
- Equipes que querem rastreabilidade total de mudanças (audit trail)
Veredito

Abordagem rigorosa para engenharia agentic em Claude Code. O modelo arquiteto/workers força separação clara entre decisão e execução, valioso para evitar derivas de contexto. Requer disciplina do usuário (movimentos stage-by-stage), CLI externas (ctx7) e pré-requisitos, não é turnkey — mas entrega o que promete: código revisado e verificado, sem misturança.
README
A tradução para o português deste README ainda está na fila.
dobby
Kevin Wolf's agentic engineering kit for Claude Code, packaged as a plugin. dobby doesn't make Claude Code smarter — it makes it disciplined: the main thread stays an architect that frames, asks, decides, and reviews but never writes code, while four worker agents do the hands-on work. Every change is implemented, code-reviewed, and verified by separate agents before it counts as done.
Install
/plugin marketplace add kvnwolf/dobby
/plugin install dobby@dobby
Or with vercel-labs/plugins: npx plugins add kvnwolf/dobby.
Then start your first session from any project:
/dobby:scope <what you want to build>
Prerequisites: the ctx7 CLI (the researcher agent fetches current library docs through it), and vp (vite-plus) on PATH if you want the post-edit check hook to do anything.
The mental model
Two roles, never mixed:
- The architect (your main conversation) — interrogates you until the task has zero ambiguity, plans, dispatches workers, reviews what comes back, and owns every decision. If you ever see the main thread grepping around or editing files during kit stages, that's a bug in the kit.
- The workers (custom agents, addressed as
dobby:<name>) — each runs with its own model and effort, tuned to its job:
| Agent | Role | Model |
|---|---|---|
researcher | Explore code, fetch current docs (ctx7), resolve unknowns | Opus / medium |
implementor | Write the code for one scoped task | Fable 5 / xhigh |
reviewer | Code-review a task's diff, pass/fail verdict | Opus / high |
verifier | Prove the task works against the running app | Sonnet / high |
The payoff: your context stays clean for thinking, implementation quality is enforced by independent review, and "done" means proven against the running app, not "the code looks right".
The lifecycle
A work session moves through six stages. Each stage ends by telling you which command to type next — nothing advances until you type it. Handoffs are typed on purpose: typed entry is what applies each stage's own model and effort (an auto-invoked skill would ride the previous stage's override):
/dobby:scope ground the goal in the codebase, create STATE.md
│
/dobby:interview resolve EVERY ambiguity, one question at a time
│
/dobby:research current docs + unknowns, via researchers (skipped when no external tech)
│
/dobby:spec the build plan, printed in full — you approve it
│
/dobby:execute waves of implement → review → verify (the trifecta)
│
/dobby:wrap human smoke test, docs/ADRs, STATE.md disposed
│
/dobby:commit branch, commit, push, PR
Side paths, available at any point:
/dobby:prototype— when a decision can't be settled with words, interview/research hand off to a throwaway prototype you can play with, then resume./dobby:diagnose— when something breaks during execute (or any time), a disciplined hypothesis-driven debugging loop./dobby:dispatch— the whole architect/worker machinery for a task too small to deserve a session.
Your first session — end-to-end walkthrough
One concrete feature, carried through every stage: adding CSV export to an admin users table. Follow along to see what each command does, what you'll see, and what it leaves behind.
1. Scope
/dobby:scope add a CSV export button to the admin users table
The architect creates STATE.md at your repo root (the session's shared doc) and dispatches a dobby:researcher to ground the goal: where the users table lives, which conventions the project uses, what the domain glossary and ADRs say. You don't wait on grepping — a worker does it.
You'll see: a short grounded summary ("the table is src/admin/users/, it uses the shared DataTable, exports don't exist anywhere yet"), then the suggestion to type /dobby:interview next (or jump straight to research or spec).
Artifact: STATE.md with a filled ## Exploration section.
2. Interview
The architect now interrogates you — one focused question at a time, each informed by what the researcher found, each with a recommended answer:
Should the export respect the current filters and search, or always dump the full table? (Recommended: respect filters — that's what the visible data implies.)
Expect questions about edge cases you hadn't considered: empty results, the 50k-row tenant, who's allowed to export, date formatting, column selection. This is the kit's core bet: misalignment is the most common failure mode, so the interview doesn't stop until there's zero ambiguity — and it will refuse to end on a vague "anything else?" if open threads remain.
If a question can't be settled verbally ("which of these two layouts feels right?"), the interview sends you to type /dobby:prototype and resumes after you've played with the variants.
Artifact: ## Findings (interview) in STATE.md — every decision, with the rejected alternative and the why.
3. Research
Researchers fan out in parallel: one fetches current docs for the CSV library candidates (via ctx7 — never from training data), another checks how streaming downloads work in your framework version, another looks for an existing export pattern in the codebase worth reusing.
You'll see: a tight research brief — key facts with doc sources, what to reuse, open questions flagged.
Artifact: ## Research in STATE.md.
4. Spec
/dobby:spec
The architect turns decisions + research into a build plan and prints it in full in the conversation — overview, edge cases, and a task table where every task carries its own verify recipe (the exact steps that will later prove it works). Approval is asked in plain text at the end of the printed plan; nothing builds until you say so.
Artifact: ## Spec in STATE.md.
5. Execute
/dobby:execute
The architect starts your dev server once, then launches the build workflow. Per task, three separate agents run a state machine:
implement → code review → (findings? fix → re-review) → verify → (fail? restart) → done
The implementor never reviews itself; the reviewer never implements; the verifier checks the running app against the task's verify recipe. Independent tasks run in parallel waves. A task that exhausts its retries is flagged needs-human instead of thrashing forever.
You'll see: live workflow progress, then a status table per task, and the work log appended to STATE.md.
6. Wrap
/dobby:wrap
The closing pass: a short human smoke test (the few cross-task behaviors machines can't prove — you answer Pass/Fail/Skip, failures get dispatched to an implementor and re-presented), project docs reconciled (CONTEXT.md glossary terms the work introduced, ADRs the decisions earned), and STATE.md disposed — it's ephemeral by design.
Then you type /dobby:commit: pre-commit checks, branch, conventional commit, push, PR.
When to use what
| Situation | Reach for |
|---|---|
| A feature, fix, or refactor with real surface area | /dobby:scope — the full session |
| A one-off fix, small change, or bounded question | /dobby:dispatch |
| Something is broken and the cause isn't obvious | /dobby:diagnose |
| A design/UX question words can't settle | /dobby:prototype |
| "Is this module structured well?" | /dobby:improve-architecture |
| An idea/bug worth tracking, mid-flow | /dobby:backlog — capture and keep moving |
| A repeatable workflow worth packaging | /dobby:create-skill |
| A brand-new empty repo | /dobby:bootstrap |
| Work is done, ship it | /dobby:commit |
| Building or refactoring a form | /dobby:forms (auto-activates) |
| Wiring server data into a list/table | /dobby:data-fetching (auto-activates) |
Rule of thumb: if getting it wrong would cost you a rework cycle, it deserves a session (scope). If you could review the whole change in one glance, dispatch it.
Convention skills
Two skills are not work-session stages — they're stack-convention guides that auto-activate while you build, encoding Kevin's standard application stack (TanStack Start + Drizzle/Neon + Better Auth, the @/shared form/data system). You never type them to advance a session; they fire when the work matches and reference the consuming project's module barrels on purpose:
/dobby:forms— form conventions:useAppFormfrom@/shared, Zod validation, field anatomy, submit/secondary buttons, dialog forms./dobby:data-fetching— the TanStack DB recipe: session-guarded server fn → query collection → theLiveQuerycomponent.
The artifacts: STATE.md
Every session writes one shared doc at the target repo's root. It's how stages hand off to each other and how a session survives interruptions:
STATE.md
├── ## Exploration ← scope: what the codebase says
├── ## Findings (interview) ← interview: every decision + why
├── ## Research ← research: the brief the plan consumes
├── ## Spec ← spec: the approved task table + verify recipes
└── ## Work log ← execute: what each implementor actually did
It is never committed — /dobby:wrap disposes it after reconciling the durable docs (CONTEXT.md, CLAUDE.md, ADRs).
Also ships
- Hook
vp-check-changes— after every Edit/Write, runsvp checkin projects that have avite.config.ts(no-op everywhere else).
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Agent type 'dobby:researcher' not found | Agents register at session startup | /reload-plugins; if that doesn't take, restart the session |
/dobby:* skills don't show up | Plugin not enabled | /plugin → enable dobby@dobby (or reinstall) |
| Researchers cite stale/odd docs | ctx7 CLI missing or unauthenticated | Install ctx7; set CONTEXT7_API_KEY for higher limits |
| Skill edits not picked up (local dev) | Only SKILL.md hot-reloads | /reload-plugins for agents/hooks changes |
| Post-edit check hook never fires | By design outside vite-plus projects | Gate = vite.config.ts at project root and vp on PATH |
| Execute re-authored the workflow and lost the loop logic | The trifecta script must be used verbatim | Re-run /dobby:execute; the skill's references/build-workflow.md is the canonical script |
Recovery quick reference
- Session interrupted mid-stage?
STATE.mdis the source of truth. Re-invoke the stage you were in — it reads the doc and continues. - Want to revisit a decision? Re-run
/dobby:interview; it updates## Findingsand downstream stages pick up the change. - A task came back
needs-human? That's the workflow refusing to thrash. Read the reason in the status table, then/dobby:diagnoseor/dobby:dispatchthe fix. - Abandon a session? Delete
STATE.md. Nothing else was written outside the code changes themselves.
Local development
claude --plugin-dir .
Skill edits hot-reload; agents and hooks need /reload-plugins.
/dobby:prototype is adapted from mattpocock/skills engineering/prototype.