From virtual-team
Provides formal architecture vocabulary (Depth, Seam, Leverage, Locality, Adapter, Pass-through) with diagnostic heuristics for precise, falsifiable tech-review findings.
How this skill is triggered — by the user, by Claude, or both
Slash command
/virtual-team:architecture-vocabularyThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use these terms and heuristics when evaluating architecture. Every architecture finding should reference at least one vocabulary term. Replace generic language with precise claims.
Use these terms and heuristics when evaluating architecture. Every architecture finding should reference at least one vocabulary term. Replace generic language with precise claims.
| Term | Definition | Diagnostic Heuristic |
|---|---|---|
| Depth | Deep module: simple interface, rich functionality. Shallow module: interface nearly as complex as its implementation. | Count public methods vs lines of meaningful logic. Ratio near 1:1 = shallow. |
| Seam | A point where behavior can be swapped without changing surrounding code. | One adapter = hypothetical seam. Two adapters = real seam. Zero = no seam yet. |
| Adapter | A thin translation layer at a seam boundary. Contains no business logic. | If your adapter has business logic, it's a service pretending to be an adapter. |
| Leverage | How much behavior a module provides per unit of interface complexity. | Deletion test: imagine deleting the module. If complexity reappears across callers, it was earning its keep (high leverage). If callers barely notice, it was unnecessary indirection (low leverage). |
| Locality | Related changes stay together. Modifying one behavior touches one file, not five. | A single conceptual change requiring edits in 3+ files = poor locality. The concept is scattered across wrong boundaries. |
| Pass-through | A method or layer that receives arguments, adds nothing, and forwards them. | If you can describe it as "calls X with the same arguments," it's a pass-through. Adds stack depth and maintenance cost without value. |
When forming architecture findings, follow this protocol:
Before: "This module has poor separation of concerns." After: "This module is shallow — 14 public methods, each a thin wrapper over the database client (ratio ~1:1). Consider consolidating into fewer, deeper methods."
Before: "The code is tightly coupled." After: "No seam exists between the notification service and the email provider (zero adapters). Adding a second provider would require modifying the service internals."
Before: "There's unnecessary abstraction here."
After: "The EventDispatcher has low leverage — deletion test shows callers would each add one direct call, replacing the dispatcher's 200-line interface with ~3 lines each. The indirection isn't earning its complexity."
Before: "Changes to billing touch too many files."
After: "Billing logic has poor locality — updating the tax calculation requires edits in models/order.ts, services/billing.ts, utils/tax.ts, and api/checkout.ts (4 files). Consider co-locating tax logic."
This skill is loaded by:
commands/tech-review.md — used during the Architecture & Structure evaluation dimensionnpx claudepluginhub ovargas/virtual-team --plugin virtual-teamAnalyzes codebase architecture, identifies shallow modules, and proposes deepening refactors to improve testability and AI-navigability using precise vocabulary (Module, Interface, Depth, Seam, Adapter).
Identifies shallow modules and architectural friction in a codebase, using domain language from CONTEXT.md and ADR decisions, to propose refactoring opportunities for testability and AI-navigability.
Identifies shallow modules and proposes deepening refactors to improve testability and AI-navigability. Leverages domain glossary (CONTEXT.md) and ADR decisions to find consolidation opportunities.