{"id":50842838,"url":"https://github.com/kvnwolf/dobby","last_synced_at":"2026-06-14T07:34:53.160Z","repository":{"id":364452944,"uuid":"1266942472","full_name":"kvnwolf/dobby","owner":"kvnwolf","description":"Agentic engineering kit for Claude Code — an architect main thread, worker agents, and staged work sessions, packaged as a plugin","archived":false,"fork":false,"pushed_at":"2026-06-13T03:26:54.000Z","size":80,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T07:34:52.352Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kvnwolf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-12T04:55:44.000Z","updated_at":"2026-06-13T03:26:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kvnwolf/dobby","commit_stats":null,"previous_names":["kvnwolf/dobby"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kvnwolf/dobby","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvnwolf%2Fdobby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvnwolf%2Fdobby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvnwolf%2Fdobby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvnwolf%2Fdobby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kvnwolf","download_url":"https://codeload.github.com/kvnwolf/dobby/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvnwolf%2Fdobby/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34313515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-14T07:34:52.474Z","updated_at":"2026-06-14T07:34:53.155Z","avatar_url":"https://github.com/kvnwolf.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dobby\n\nKevin 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.\n\n## Install\n\n```\n/plugin marketplace add kvnwolf/dobby\n/plugin install dobby@dobby\n```\n\nOr with [vercel-labs/plugins](https://github.com/vercel-labs/plugins): `npx plugins add kvnwolf/dobby`.\n\nThen start your first session from any project:\n\n```\n/dobby:scope \u003cwhat you want to build\u003e\n```\n\n**Prerequisites**: the [`ctx7` CLI](https://context7.com) (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.\n\n## The mental model\n\nTwo roles, never mixed:\n\n- **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.\n- **The workers** (custom agents, addressed as `dobby:\u003cname\u003e`) — each runs with its own model and effort, tuned to its job:\n\n| Agent | Role | Model |\n| --- | --- | --- |\n| `researcher` | Explore code, fetch current docs (ctx7), resolve unknowns | Opus / medium |\n| `implementor` | Write the code for one scoped task | Fable 5 / xhigh |\n| `reviewer` | Code-review a task's diff, pass/fail verdict | Opus / high |\n| `verifier` | Prove the task works against the running app | Sonnet / high |\n\nThe 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\".\n\n## The lifecycle\n\nA 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):\n\n```\n/dobby:scope        ground the goal in the codebase, create STATE.md\n      │\n/dobby:interview    resolve EVERY ambiguity, one question at a time\n      │\n/dobby:research     current docs + unknowns, via researchers     (skipped when no external tech)\n      │\n/dobby:spec         the build plan, printed in full — you approve it\n      │\n/dobby:execute      waves of implement → review → verify (the trifecta)\n      │\n/dobby:wrap         human smoke test, docs/ADRs, STATE.md disposed\n      │\n/dobby:commit       branch, commit, push, PR\n```\n\nSide paths, available at any point:\n\n- `/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.\n- `/dobby:diagnose` — when something breaks during execute (or any time), a disciplined hypothesis-driven debugging loop.\n- `/dobby:dispatch` — the whole architect/worker machinery for a task too small to deserve a session.\n\n## Your first session — end-to-end walkthrough\n\nOne 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.\n\n### 1. Scope\n\n```\n/dobby:scope add a CSV export button to the admin users table\n```\n\nThe 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.\n\n**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).\n\n**Artifact:** `STATE.md` with a filled `## Exploration` section.\n\n### 2. Interview\n\nThe architect now interrogates you — **one focused question at a time**, each informed by what the researcher found, each with a recommended answer:\n\n\u003e 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.)*\n\nExpect 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.\n\nIf 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.\n\n**Artifact:** `## Findings (interview)` in `STATE.md` — every decision, with the rejected alternative and the why.\n\n### 3. Research\n\nResearchers 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.\n\n**You'll see:** a tight research brief — key facts with doc sources, what to reuse, open questions flagged.\n\n**Artifact:** `## Research` in `STATE.md`.\n\n### 4. Spec\n\n```\n/dobby:spec\n```\n\nThe 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.\n\n**Artifact:** `## Spec` in `STATE.md`.\n\n### 5. Execute\n\n```\n/dobby:execute\n```\n\nThe architect starts your dev server once, then launches the build workflow. Per task, **three separate agents** run a state machine:\n\n```\nimplement → code review → (findings? fix → re-review) → verify → (fail? restart) → done\n```\n\nThe 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.\n\n**You'll see:** live workflow progress, then a status table per task, and the work log appended to `STATE.md`.\n\n### 6. Wrap\n\n```\n/dobby:wrap\n```\n\nThe 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.\n\nThen you type `/dobby:commit`: pre-commit checks, branch, conventional commit, push, PR.\n\n## When to use what\n\n| Situation | Reach for |\n| --- | --- |\n| A feature, fix, or refactor with real surface area | `/dobby:scope` — the full session |\n| A one-off fix, small change, or bounded question | `/dobby:dispatch` |\n| Something is broken and the cause isn't obvious | `/dobby:diagnose` |\n| A design/UX question words can't settle | `/dobby:prototype` |\n| \"Is this module structured well?\" | `/dobby:improve-architecture` |\n| An idea/bug worth tracking, mid-flow | `/dobby:backlog` — capture and keep moving |\n| A repeatable workflow worth packaging | `/dobby:create-skill` |\n| A brand-new empty repo | `/dobby:bootstrap` |\n| Work is done, ship it | `/dobby:commit` |\n| Building or refactoring a form | `/dobby:forms` (auto-activates) |\n| Wiring server data into a list/table | `/dobby:data-fetching` (auto-activates) |\n\nRule 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.\n\n## Convention skills\n\nTwo 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:\n\n- `/dobby:forms` — form conventions: `useAppForm` from `@/shared`, Zod validation, field anatomy, submit/secondary buttons, dialog forms.\n- `/dobby:data-fetching` — the TanStack DB recipe: session-guarded server fn → query collection → the `LiveQuery` component.\n\n## The artifacts: STATE.md\n\nEvery 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:\n\n```\nSTATE.md\n├── ## Exploration            ← scope: what the codebase says\n├── ## Findings (interview)   ← interview: every decision + why\n├── ## Research               ← research: the brief the plan consumes\n├── ## Spec                   ← spec: the approved task table + verify recipes\n└── ## Work log               ← execute: what each implementor actually did\n```\n\nIt is **never committed** — `/dobby:wrap` disposes it after reconciling the durable docs (`CONTEXT.md`, `CLAUDE.md`, ADRs).\n\n## Also ships\n\n- **Hook `vp-check-changes`** — after every Edit/Write, runs `vp check` in projects that have a `vite.config.ts` (no-op everywhere else).\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| `Agent type 'dobby:researcher' not found` | Agents register at session startup | `/reload-plugins`; if that doesn't take, restart the session |\n| `/dobby:*` skills don't show up | Plugin not enabled | `/plugin` → enable `dobby@dobby` (or reinstall) |\n| Researchers cite stale/odd docs | `ctx7` CLI missing or unauthenticated | Install `ctx7`; set `CONTEXT7_API_KEY` for higher limits |\n| Skill edits not picked up (local dev) | Only `SKILL.md` hot-reloads | `/reload-plugins` for agents/hooks changes |\n| Post-edit check hook never fires | By design outside vite-plus projects | Gate = `vite.config.ts` at project root **and** `vp` on PATH |\n| 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 |\n\n## Recovery quick reference\n\n- **Session interrupted mid-stage?** `STATE.md` is the source of truth. Re-invoke the stage you were in — it reads the doc and continues.\n- **Want to revisit a decision?** Re-run `/dobby:interview`; it updates `## Findings` and downstream stages pick up the change.\n- **A task came back `needs-human`?** That's the workflow refusing to thrash. Read the reason in the status table, then `/dobby:diagnose` or `/dobby:dispatch` the fix.\n- **Abandon a session?** Delete `STATE.md`. Nothing else was written outside the code changes themselves.\n\n## Local development\n\n```\nclaude --plugin-dir .\n```\n\nSkill edits hot-reload; agents and hooks need `/reload-plugins`.\n\n---\n*`/dobby:prototype` is adapted from [mattpocock/skills](https://github.com/mattpocock/skills) `engineering/prototype`.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkvnwolf%2Fdobby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkvnwolf%2Fdobby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkvnwolf%2Fdobby/lists"}