Modularity is a Claude Code plugin that judges a codebase by three coupling dimensions

The plugin argues that code level review misses the costly mistakes

Modularity is a Claude Code plugin for designing and analyzing modular software systems, and the README's argument for it starts with a claim about where problems hide.

The framing is that there is no shortage of AI tools that provide code-level feedback, best practices, edge cases and potential bugs, and that this is useful but not where the costly mistakes hide. The argument continues that in the AI era code is generated faster than ever and so technical debt accumulates faster too, and that any architectural inefficiency, any misdrawn boundary and any unmanaged coupling will grow into a big ball of mud at a pace that was not possible before.

That is a coherent position, and it is the reason the plugin exists rather than being another linter prompt. The value of a code level checker is that it is cheap and fast. The value of an architectural check is that it addresses the failures that only show up after a year of changes, and the plugin takes the position that you need a model to reason about those rather than a list of heuristics.

The plugin operates at the architectural level and includes two skills, and both are grounded in the Balanced Coupling model, so every recommendation traces back to a concrete dimension, integration strength, distance or volatility, rather than to gut feel.

The repository is small: a .claude-plugin/ directory for the plugin manifest, a skills/ directory holding the two skills, an ai.txt file, a LICENSE, a README and a .gitignore. The primary language is recorded as HTML, which fits a skill that produces HTML review documents as well as Markdown.

The review skill asks about your domain before it says anything

The review skill, /modularity:review, analyzes an existing codebase for coupling imbalances: what knowledge is properly encapsulated, what is leaking across component boundaries, and where cascading changes are waiting to happen. It produces actionable recommendations for improving modularity.

The documented use cases are reviewing code for coupling problems, assessing architecture quality, identifying distributed monolith risks, and investigating why changes in one area break things elsewhere. That last one is the sharpest use case, because it is the symptom an architecture problem produces after the fact.

The mechanism is a five step process, and step two is the one worth knowing about before you run it.

1. Reads your code and functional requirements 2. Asks you about domain classification (core/supporting/generic), team structure, and known pain points 3. Maps integrations between components across three dimensions: integration strength, distance, and volatility 4. Applies the balance rule to flag imbalances 5. Produces a review document (Markdown + HTML) with a coupling overview table, issue descriptions, and concrete improvement recommendations

So the plugin interviews you before it analyses you. It asks how you classify your domains, how your teams are structured and what already hurts, and those answers feed the mapping step. That is a reasonable design, because two of the three dimensions are not derivable from the code: distance depends on team boundaries, and volatility is judged from the business domain perspective rather than from the repository.

The output is a document rather than a chat reply, and the review output includes hyperlinks to coupling.dev for each coupling concept referenced, so the reader can look up the reasoning behind a flagged imbalance rather than taking it on trust.

The design skill produces contracts and test specs, and iterates on itself

The design skill, /modularity:design, goes the other direction, designing modular architectures from functional requirements.

Its documented use cases are designing a new system from scratch, creating architecture documentation for an existing system, and producing module-level design specs with integration contracts and test specifications.

The process has seven steps, and two of them are unusual for a plugin.

1. Reads your functional requirements and asks clarifying questions 2. Classifies domain areas by volatility (core/supporting/generic subdomains) 3. Designs the modular architecture, assessing coupling across all three dimensions 4. Produces design documents for each module (responsibilities, encapsulated knowledge, integration contracts, change vectors) 5. Produces test specifications for each module 6. Produces an architecture overview document 7. Self-reviews the design for modularity imbalances and iterates until clean

Step five is the one that distinguishes this from a diagram tool. A design that names modules and their responsibilities is a slide deck; a design that also states the test specifications per module is a contract that someone can be held to.

Step seven is the other one. The skill checks its own output against the same model it used to produce it, and iterates until the imbalances are gone. And there is a gate between the steps: each step requires your approval before proceeding. So the design is produced incrementally and you can stop it at the point where it stops making sense, rather than receiving one large document at the end.

The balance rule is a formula, and that is the whole argument

Both skills are grounded in the Balanced Coupling model, which evaluates coupling across three dimensions.

Integration strength is how much knowledge is shared between components, and the documentation gives the ordering as intrusive, functional, model, contract. Distance is the socio-technical cost of co-evolving components, covering code structure, team boundaries and runtime dependencies. Volatility is the probability of a component needing to change, evaluated from the business domain perspective.

The rule itself is written out as a single expression, `BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY`, and the interpretation follows: coupling is balanced when strength and distance counterbalance each other, or when volatility is low enough to neutralize the imbalance.

Read as an engineer rather than as a formalist, the model says something fairly intuitive. Strong coupling between components that sit together and change together is fine. Strong coupling between components that live in different teams and change for different reasons is not. And any coupling is acceptable between components that simply do not change.

That is a useful reframing, because the usual advice about low coupling is wrong in the other direction. Two modules that must change together, owned by the same team, in the same directory, should be tightly coupled, and splitting them is what creates a distributed monolith. The XOR and the volatility term are there to say that.

The documentation recommends Claude Opus 4.5 or later, on the grounds that the skills rely on nuanced architectural reasoning that benefits from the most capable models.

Installing it is two commands in Claude Code, or a clone and a flag

The plugin requires Claude Code v1.0.33 or later.

The supported route is to add the marketplace and install the plugin, and both are slash commands inside Claude Code.

/plugin marketplace add vladikk/modularity
/plugin install modularity@vladikk-modularity

The alternative is to clone the repository and load it directly, which needs Git and the Claude Code CLI on the path.

git clone https://github.com/vladikk/modularity.git
claude --plugin-dir ./modularity

So there is no package to publish, no registry entry and no version constraint to manage beyond the Claude Code requirement. The plugin is a directory with a manifest and a skills folder, and Claude Code loads it.

Once installed, the two skills are invoked by name, /modularity:review and /modularity:design, each on its own line.

/modularity:review

The clone route is the one to use if you want to read the skill instructions before letting them run against your repository, since the review skill reads your code and asks questions about your team. It is also the route that works if the marketplace install is blocked in your environment, which is a reasonable thing to plan for in a locked down organisation.

The licence is non commercial, and the training clause is separate

The licence is the part to read carefully here, because it is not what a plugin normally ships with.

The work is licensed under CC BY-NC-SA 4.0. For commercial use, the instruction is to contact the author at the address given. So the plugin is free to read, modify and share for non commercial purposes, with attribution and share-alike, and a commercial deployment needs a conversation first.

There is a second clause that is unusual for a code repository. The repository and its contents may not be used for training, fine-tuning, or any other form of machine learning model development without explicit written permission from the author. That is separate from the licence terms, and it is about what you do with the skill text rather than about what you build with it.

The licence field in the project metadata is one GitHub cannot classify, and the LICENSE file at the root is where the authoritative terms are.

For an open source project or a personal codebase this is unremarkable. For a company that wants to run the review skill in its CI or on its engineers' machines during work hours, the commercial clause is a genuine gate, and the honest reading is that the contact is not optional.

The same applies to a smaller point: the review skill's output is a review document that may quote your code and your team's structure, and this is a plugin that sends your repository to a model provider. Nothing in the documentation addresses that, so it is worth knowing before you point it at a codebase with credentials or unreleased work in it.

Where the plugin is the wrong tool

There are honest limits, and the README states the first one plainly: code level feedback, best practices, edge cases and potential bugs, is not where the costly mistakes hide, and this plugin is not that tool. If the problem is a null dereference in a handler, a code level checker is the right instrument and this one will not help.

The second limit is the input. Both skills are interview driven. The review skill asks about domain classification, team structure and known pain points, and the design skill asks clarifying questions about your functional requirements. That makes the output better, because distance and volatility cannot be read from a directory tree, and it also means the plugin needs a person who knows the business to spend time with it. For a repository where nobody knows how the modules are supposed to relate, the review will be shallow no matter how good the model is.

The third is scope of the model. The balance rule is a three term formula over integration strength, distance and volatility, and it is a reduction. It will not tell you whether your boundaries are the right ones for a domain that does not fit the core, supporting and generic classification, and it does not consider things the formula does not name, such as data ownership, deployment topology or the cost of a shared schema. A team that reads the formula as a complete theory of modularity will draw conclusions the model cannot support.

The alternative to a plugin of this kind is a human architecture review, which costs days rather than minutes and is not bound by a three dimension formula. For a system about to be rewritten, that is usually the better buy, and this plugin is a good way to arrive at the review with the coupling map already drawn.

Editorial conclusion

The modularity plugin fits a team that has noticed a codebase turning into a distributed monolith and wants the diagnosis grounded in a written model rather than in taste, since every recommendation traces back to a named dimension. It does not fit a commercial project without contacting the author first, because the licence is CC BY-NC-SA 4.0 with a separate clause for commercial use, and it does not fit a team that wants code level bug finding, which the documentation explicitly places outside its scope. Before installing it, read the Balanced Coupling model and the plugin licence, confirm the model you use can run the reasoning, and expect the review to be an interview as much as an analysis, since the skill asks about domain classification and team structure before it says anything.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. vladikk/modularity on GitHub