VTD vs. V025 Claude Toolkit — Comparison, Assessment & Learnings¶

Date: 2026-07-24 Author: PM (evidence-based analysis, both repos read first-hand) Subjects: - VTD — visitrans-dev-toolkit (VisiFair dev team), ~/01-repositories/99-claude code/visitrans-dev-toolkit - V025 — this toolkit, V025-claude-toolkit (core-standards v3.52.0, 128 skills)

Status: Analysis + assessment. Feeds ranked toolkit-optimisation proposals in intake/pending/from-research/ (run /vt-c-spec-from-requirements on the chosen ones). Shareable dev-facing version: see the companion Artifact.

1. Executive summary¶

VTD and V025 are not competing tools — they operate at different altitudes. VTD is a narrow, deep inner-loop task orchestrator: one command wraps a single task in Plan → Implement → Review → Document with human gates. V025 is a broad governance + product-management + multi-workflow platform: a spec lifecycle, machine-checked gates, multi-agent review, cross-repo PM dashboards, compliance, brand and design, spanning code and non-code deliverables.

They are complementary and can literally coexist. Namespaces (vtd-* vs vt-c-*) and per-project state (.vtd/ vs .design-state.yaml) do not collide; both install into ~/.claude/.

Verdict on the developers' question ("V025 is too big / VTD is enough" vs "V025 raises quality"): both sides are partly right, and the answer is working-style-dependent (see §5). For a serial, one-task-at-a-time developer, VTD's low ceremony genuinely wins on felt speed, and V025's full 0→6 + spec lifecycle is overkill for a one-file bugfix. But the specific quality levers V025 adds — diff-scoped multi-agent review, a spec-compliance gate, security/supply-chain hooks, DoR/DoD, spec traceability — are real, and most of them can be adopted selectively without swallowing the whole platform. The highest-value move is not "make V025 smaller" or "replace VTD"; it is cross-pollination plus a serious look at whether a parallel working model would make V025's ceremony free rather than costly.

2. Side-by-side profile¶

Dimension	VTD	V025
What it is	Claude Code slash-command workflow orchestrator (`README.md:6` — "not a standalone tool… installs as a set of slash commands")	Claude Code plugin marketplace (`plugins/registry.json`): 1 required base + 5 department plugins
Altitude	Single task / developer inner-loop	Program / spec / portfolio + inner-loop
Stack	Markdown command prompts + ~1,600 LOC Bash; no runtime, no daemon, no MCP	Markdown skills + Bash/Python scripts + hooks; MCP servers (azure-devops, github…)
Size	~8 commands, 14 scripts, 3 skills, 6 templates. `src/commands/vtd.md` alone is 1,347 lines of orchestration prompt. Bulk of the repo is self-dogfooding history (30 `.vtd/tasks/`)	128 skills / 55 agents / 31 commands / 7 orchestrators / 9 hooks (`README.md`)
Install target	`~/.claude/vtd/` + commands `vtd-*` (`README.md` install table)	`~/.claude/` via `scripts/setup.sh`; skills `vt-c-*`, symlink manifests
Core loop	`/vtd <task>` → classify (`bugfix\\|simple\\|complex`) → Plan → Implement → Review → Document, ~8 human gates (`src/commands/vtd.md`)	`/vt-c-0-start → 1-bootstrap → 2-plan → 3-build → 4-review → 5-finalize → 6-operate`, machine-checked gate files
Unit of work	A task (`.vtd/tasks/NNN-slug/`)	A spec (`SPEC-NNN`, `.design-state.yaml` + `specs/N-*/state.yaml`)
Gates	Interactive `AskUserQuestion` between every phase (approve/refine/add-context/abort)	Hard machine gates: `.plan-gate.md`, `.test-gate.md`, `.review-gate.md`, `state.yaml.*_gate`; Phase 5 refuses to run without review+test PASS
Review	1 agent (bugfix/simple) or 4 parallel specialists (complex): lint, test, security(read-only), simplification, + acceptance-criteria check	Deterministic diff-scoped selection (`persona-select.sh`): floor ∪ diff-triggers ∪ deliverable-type reviewers, from a 24-agent catalog
Model economy	Per-phase model-tier routing Haiku/Sonnet/Opus + upgrade-on-retry (`src/commands/vtd.md:188-203`)	No per-phase model routing
Task numbering	Airtable atomic counter keyed off git-remote, graceful local fallback (`src/scripts/common.sh`; `README.md`)	`SPEC-NNN` derived from local registry scan (mis-numbers on stale branches — known issue)
Learning loop	Two-tier memory; lesson `L-` → pattern `P-` after 3 uses → constitution amendment after 3 same-root-cause (`README.md`)	`docs/solutions/patterns/` + review-history + Beads issues; promotion is manual/curated
Reliability extras	Statusline (model/context/cost/phase), `/vtd-resume` + auto-resume, self-healing `doctor`/`repair`, desktop notifications	`context: fork` async review/finalize, `.claude-checkpoint.md`, worktree offers
Scope of deliverables	Code only	Code + document + presentation + research + project-plan (`deliverable_types` polymorphism)
PM / cross-repo	None (single repo, single task)	register → sync → `domain-dashboard` across all registered repos
Security posture	Deterministic secret scan, credential deny-list by default, injection guardrail (treat `$ARGUMENTS`/file content as untrusted DATA)	Hard secret-scanner hook (blocks Write/Edit), supply-chain CVE guard, partition guard, branch-protection pre-commit
Project-agnostic?	Yes — zero VisiFair business logic in shipped `src/`; only Azure-DevOps git-remote parsing is VisiTrans-flavoured (also handles GitHub)	Mostly — but carries VisiTrans brand/compliance/PM plugins and product path-scoping (`intake/projects.yaml`)
Philosophy	Low-ceremony, single-harness, stay-in-flow-but-keep-control, self-improving. Its own roadmap explicitly rejects a second runtime, daemons, SQLite, and "262-skill catalogs" as "contrary to VTD's low-ceremony single-harness design" (`docs/ecc-harvest-roadmap.md`)	Spec-driven, governed, evidence-based, security-first; breadth across roles and deliverable types

Note: VTD's roadmap line about rejecting "262-skill catalogs" is essentially a direct critique of a V025-style platform. That is the crux of the disagreement, and §4–§5 address it head-on.

3. The shared concepts, compared¶

Both toolkits independently converged on the same backbone — Plan / Implement / Review / Document + a learning memory + secret scanning. VTD compresses it into one command; V025 spreads it across governed phases.

Concept	VTD	V025
Plan	Phase 1: subagent scans code → structured plan incl. acceptance-criteria table; one gate	`/vt-c-2-plan`: conceptual-orchestrator (research + architecture) → `plan-checker` validation loop (max 3) → `.plan-gate.md`; optional `/vt-c-shape` + `/vt-c-spec-check`
Implement	Phase 2: subagent executes plan, TDD red-green; one gate	`/vt-c-3-build`: implementation guidance + `/vt-c-journal` capture
Review	Phase 3: lint/test/typecheck auto-fix loop (max 5) + specialists	`/vt-c-4-review`: `persona-select.sh` → bounded parallel reviewers + spec-compliance gate + auto-fix (max 2)
Document	Phase 4: lessons + patterns + feature doc	`/vt-c-journal`, `docs/solutions/patterns/`, review-history; DoD at `/vt-c-5-finalize`
Memory	Mechanical promotion ladder (3-use rule)	Curated pattern docs + Beads persistence
Secrets	Deterministic scan + deny-list + injection guardrail	Hard PreToolUse secret-scanner hook (blocks the write)

Read this way, VTD's 4 phases ≈ a compressed 2-plan + 3-build + 4-review + journaling. The difference is not what they do but how much ceremony and governance wraps it, and how many deliverable types and roles are in scope.

4. Assessment — Einsatzgebiet (where each wins)¶

VTD wins the inner loop. - One command, plain language, stays in flow. Proportional ceremony via the bugfix|simple|complex classifier — a bugfix does not get a design phase. - Resumable single-task state + statusline + notifications = strong solo-developer ergonomics. - Cheap and fast: per-phase model routing keeps the common path on Sonnet/Haiku. - The developers are right: V025's full 0→6 + spec lifecycle is genuinely overkill for a one-file fix.

V025 wins everything around the code. - Spec governance and traceability (SPEC-NNN, DoR/DoD, dependency waves), so work is auditable and requirements do not silently drop. - Deliverable breadth — the same phases serve documents, presentations, research, project plans, not just code. - Cross-repo PM visibility (domain-dashboard) — no VTD equivalent; this is a PM-level capability, not a keystroke-level one. - Brownfield onboarding (/vt-c-0-init → /vt-c-repo-init --adopt), compliance, brand/design system. - Deeper, security-hardened review (24-agent catalog, supply-chain CVE guard, hard secret block).

The honest trade: V025 buys governance, breadth and auditability at the cost of ceremony and a large surface area. VTD buys flow and speed at the cost of scope (code-only, single-task, no PM, no cross-repo memory of specs). Neither is strictly better; they are tuned for different jobs.

5. Working-style axis: serial babysitting vs. parallel throughput¶

This is the decisive lens, and it is usually left implicit. The "lightweight feels faster" preference may be an artifact of a serial working style, not a property of the toolkit.

Serial model — one task, babysat end-to-end. The developer starts a task and watches the agent through every phase, idle much of the wall-clock time. Here every gate is a tax the human waits through, so lightweight ceremony genuinely feels better and VTD wins on perceived velocity. This is the world the developers are optimising for, and within it their preference is rational.

Parallel model — 4–6 tasks in flight (worktrees). The developer keeps several tasks moving at once; the human's attention, not the agent, is the bottleneck. Now the async ceremony that felt like a tax gets amortised across the idle gaps — while task A is in review, the developer is steering task B. V025's heavier machinery is largely asynchronous by design and fits this model: - context: fork review and finalize run as isolated sub-agents that must not prompt interactively (plugins/core-standards/skills/workflow-4-review/SKILL.md, workflow-5-finalize/SKILL.md) — i.e. they are built to run in the background while you work elsewhere. - /vt-c-activate computes dependency waves (Wave 1 = everything runnable in parallel now). - vt-c-git-worktree + the SPEC-151 pattern (docs/solutions/patterns/v025-multi-worktree-workflow.md) are explicit multi-worktree conventions. - domain-dashboard gives the cross-task/cross-repo visibility you need once many things are in flight.

By contrast, VTD is architected for one active task: its statusline tracks a single task and it resumes a single task. It has no concept of N-in-parallel or of a portfolio view — because that is not its job.

The hypothesis (to validate, not assert): under a parallel model, V025's ceremony stops costing throughput and starts paying for itself in consistent quality at roughly equal developer output — because the developer was going to be idle during those gate cycles anyway. The honest counter-weight: parallel work raises context-switching cost and reduces deep flow-state, which some developers value highly; throughput-per-developer is not the only variable.

So the recommendation is style-dependent, and this is testable. A time-boxed trial (e.g. two developers, two weeks, VTD-serial vs V025-parallel-worktrees) measuring throughput at equal quality, defect/rework rate, and subjective flow would settle it far better than opinion. This is exactly the kind of question the domain-dashboard + review-history data can help answer.

6. Verdict on the developers' question¶

Is using V025 an upgrade in quality, or overkill? — Both, depending on the task and the working style:

For a serial, one-file inner-loop: VTD (or V025's /vt-c-3-build used on its own) is the right ceremony level. Full V025 would be overkill.
For spec-worthy features, or anything needing traceability/PM visibility: V025 adds real, defensible quality (spec-compliance gate, DoR/DoD, security/supply-chain hooks, cross-repo dashboards) that VTD structurally cannot provide.
The quality uplift is separable from the platform size. The specific levers that would raise the devs' quality — diff-scoped multi-agent review depth, the spec-compliance gate, the security hooks — can be adopted à la carte. The "128 skills" figure is the whole core-standards plugin across all domains (verified: 128 manifest entries — dev/implementation ≈ a dozen, PD 12, KW 9, plus content/diagram/brand/ compliance/domain skills; department plugins add ~18 more: vms 10, support 3, ufi/project-updates 2 each, finance 1). The developer flow proper is ~a dozen skills — nobody has to "swallow 128" to get the quality levers.
The biggest open question is working style, not tooling. If a parallel-worktree model fits the team, V025's ceremony is largely free and the "too big" objection weakens substantially. That is worth a trial.

Best path forward: cross-pollination, not replacement. Bring VTD's best inner-loop ideas into V025 (proportional-ceremony fast lane, model-tier routing, atomic numbering, statusline, promotion ladder), and package V025's parallel machinery so the devs can adopt it without ceremony overload. See the ranked proposals (§8).

7. Separation: cross-cutting workflow vs. VisiFair-repo-specific¶

A recurring VisiTrans question: what belongs in the cross-cutting toolkit vs. what is a repo-specific skill/doc? The two toolkits give a clean answer.

VTD ships entirely cross-cutting. There is no VisiFair business logic in its shipped src/; its tool detection (detect-tools.sh) is generic across Node/Python/Rust/Go/PHP/Makefile. Good model to copy: the workflow engine should be project-agnostic.
The VisiFair-specific layer is thin and belongs in the repo, not the toolkit. Concretely for VisiFair:
Stack: VisiFair is a PHP codebase (evidenced by .idea/php.xml in the VTD repo). Neither toolkit currently has a PHP reviewer — V025's persona-select.sh detects angular.json, nest-cli.json, and Python markers only; PHP falls through to the default kieran-typescript-reviewer (plugins/core-standards/skills/workflow-4-review/scripts/persona-select.sh:93-108). This is a concrete gap.
House coding guidelines → the project CLAUDE.md (## Conventions, ## Sensitive Areas, ## What NOT to Change), layered under the @-imported global CLAUDE.defaults.md.
Domain skills → the repo-local .claude/skills/ slot, or toolkit skills marked scope: product:[…].

Rule of thumb: the engine and gates are cross-cutting (toolkit); the stack, house style, and domain knowledge are repo-specific (project CLAUDE.md, .claude/skills/, scope:). V025 already has the slots; what is missing is a declarative surface that the toolkit reads — see the appendix.

8. Learnings — two buckets, kept honest¶

An important distinction (raised in review): not everything worth doing is a VTD feature. Some items are things VTD genuinely has that V025 lacks (adopt from VTD); others are things V025 already can do but under-exposes — the contrast with VTD surfaced them, but they are not "borrowed". Mixing the two overstates what VTD offers. Verified per item against both repos:

Full write-ups (problem, evidence, proposed change, reconcile-with, effort) are in intake/pending/from-research/.

Bucket A — genuinely adopt from VTD (VTD has it; V025 lacks or is weaker)¶

Proportional-ceremony "fast lane" (HIGH) — VTD's bugfix|simple|complex classifier (src/commands/vtd.md). Closes the V025 gap between /vt-c-quickfix (trivial only — typos/labels, <30 min, no plan/review, per quickfix/SKILL.md) and the full 0→6 (too heavy). Note: V025 already has rich bug investigation (systematic-debugging, root-cause-tracing, /vt-c-investigate-bug, 6-operate, bug-reproduction-validator) — the fast lane does not duplicate those; it is the missing orchestration/ routing layer that classifies a task and runs a compressed plan→build→review→doc over the existing pieces.
Concurrency-safe SPEC-NNN allocation (HIGH) — VTD's Airtable atomic counter (git-remote-keyed, local fallback, src/scripts/common.sh). Fixes V025's known stale-branch mis-numbering.
Generic tool auto-detection (MED) — VTD's detect-tools.sh auto-detects lint/test/build/typecheck across 6 ecosystems. V025's stack detection is scattered; a single detector would centralise it.
Per-phase model-tier routing (MED) — VTD routes Haiku/Sonnet/Opus per phase + upgrade-on-retry (src/commands/vtd.md:188-215). Verified: V025's orchestrators (agents/orchestrators/) do no model routing — a real gap, for cost economy.
Live statusline / progress surface (MED-LOW) — VTD's vtd-statusline.sh (active task, phase, context, cost).

Checked and dropped — mechanical lesson→pattern→constitution promotion. V025 already has this: continuous-learning/SKILL.md promotes on "3+ similar bugs" with an occurrence-count auto-detection ("missing_include: 5 occurrences → suggest promotion to critical-patterns.md"), and claudemd-evolve promotes a pattern that "appeared 3 times" to a permanent rule — embedded in a broader compound-engineering loop (learnings-researcher, compound-docs, ROI metrics, Beads). This is essentially equal to or broader than VTD's 3-use rule, so it is not a genuine borrow. (At most, a minor calibration tweak: VTD auto-promotes; V025 suggests and asks — a deliberate "never mutate standards silently" choice.)

Bucket B — V025's own strengths to exploit (NOT from VTD; the contrast surfaced them)¶

B1. Parallel multi-task working model (MED-HIGH) — this is not a VTD feature. Verified: VTD's src/ has no worktree/parallel/multi-task concept — it is a single-active-task tool (statusline tracks one task, single resume). The parallel machinery (vt-c-git-worktree, vt-c-activate waves, context: fork review/finalize, domain-dashboard) is V025-native; the proposal is to package it as a documented "run 4–6 in flight" workflow. VTD's single-task limit only makes the latent V025 capability visible by contrast.
B2. Declarative stack descriptor + PHP reviewer (MED-HIGH) — V025-native improvement. VTD has no stack-based reviewer selection at all (it runs generic lint/test); the stack: descriptor and the PHP reviewer agent are new V025 capabilities. (Only the auto-detection idea behind it — Bucket A#3 — comes from VTD.)

(List-only, low priority — genuinely from VTD) resumable task-state + self-healing doctor/repair; an injection-guardrail standard line for skills consuming $ARGUMENTS/untrusted file content.

9. Toolkit-Aufteilung: ein separates `dev-flow`-Plugin¶

The "128 skills feels too big" objection is partly a packaging problem, not a capability problem. The 128 are the entire core-standards plugin across all domains — dev, product design, knowledge work, compliance, content, diagrams, brand, PM, meta. A developer only ever touches a fraction. Splitting a dedicated dev-flow plugin that bundles just the end-to-end path (PRD → prototype → spec → plan → build → review → finalize → operate) plus its direct engineering support makes the developer-facing surface honest.

core-standards is today a god-plugin — base and six domains at once. The clever split is a thin base + persona plugins (principle: one plugin = one job for one persona), extending the existing pattern (finance/vms/ufi/… already depends_on: core-standards). Full skill-by-skill assignment (all 128, machine-verified unique) in dev-flow-plugin-skill-map.md:

Plugin	Persona	Skills (of 128)
vt-base (required)	everyone	17 + all hooks + shared review agents
vt-product-dev	builder, end-to-end	59
vt-office	knowledge worker	13
vms (exists)	compliance	1 (+ its 10 `vms-*`)
vt-toolkit	toolkit maintainer	12
vt-pm-intake (new/small)	PM / intake	11
product-scope	per product repo	3
retire (deprecated)	—	12

The product-dev plugin (~59 skills) is the headline win: it bundles the whole regular path PRD → prototype → spec → plan → build → review → finalize, so the fragile design→dev seam (pd-6-handoff → activate) is inside the plugin and one person works it front-to-back. This turns "128 = too big" into a focused plugin roughly half the size. Open decisions (base cut, orphan homes, shared brand, retiring KW, and the naming convention / Kürzel) are in the spec candidate.

Open decision to resolve in planning — naming convention. Today the developer-facing skills carry a mix of sub-prefixes: vt-c-pd-* (design), vt-c-kw-* (knowledge work, would leave), numbered vt-c-2-plan, and bare vt-c-<name>. If a dev-flow plugin is carved out, the prefix scheme should be decided deliberately (options in the spec candidate): keep vt-c- as-is; introduce one consistent developer prefix (e.g. vt-d-*) with backward-compatible aliases; or rationalise only the sub-families. This is captured as an explicit decision in the spec, not pre-decided here — renames touch the symlink manifest, cross-skill invocations, docs, and muscle memory (cf. SPEC-150 cross-skill-invocation gotchas). Full proposal: intake/pending/from-research/2026-07-24-dev-flow-plugin-split.md.

Appendix — Scoped: connecting the global toolkit to a specific brownfield repo¶

(This is the secondary question, included scoped. Candidate #3 above is its seed; a full design is a separate workstream.)

The connective tissue between the repo-agnostic global toolkit and a concrete repo is thin and one-directional (toolkit → project pushes structure/standards/governance via 0-init → repo-init → scaffold/bootstrap; global CLAUDE.defaults.md is @-imported under a user-owned CLAUDE.md). What is missing:

No declarative per-project stack descriptor the toolkit reads. Stack detection is duplicated across persona-select.sh (marker files), bootstrap (menu), and pd-3-prototype (heuristics). A repo whose stack isn't recognised (PHP, Go, Java, Rust) gets only floor reviewers + the default TS reviewer.
The repo-local skill slot exists but is unused. bootstrap creates .claude/skills/.gitkeep and scope: product: supports path-scoping, but no workflow generates a project-specific skill or a house-coding-standards doc into that slot during onboarding.
No hook for a project to inject house style into review agents. Reviewers carry baked-in standards (kieran-typescript-reviewer, etc.); a project cannot supply its own rules for them to honour.

Direction (for a future spec): a stack: block in .repo-manifest.yaml/.design-state.yaml + a project coding-standards doc that persona-select.sh and the reviewers consume; a PHP reviewer agent; and a 0-init step that seeds .claude/skills/ with a project-scoped standards skill. This unifies where it's safe (the engine) while giving each repo a declarative, toolkit-honoured place for its stack and house style.