react-native-mvvm-guardian
A Claude Code plugin that keeps a React Native app faithful to MVVM +
SOLID + best practices + conventions, helps you choose your stack without
breaking the architecture, and — when the app outgrows its shape — knows how to
scale it up a deliberate ladder:
screen-based → feature-based → modular monolith → micro-frontend
It ships one pair — a skill and an agent, both named rn-mvvm-guardian:
| Component | What it does |
|---|
rn-mvvm-guardian skill | Loads the MVVM contract, the conformance checklist, the scaling ladder + migration playbooks, and the guide to where each library plugs into the boundaries. Stack-agnostic and structure-agnostic. |
rn-mvvm-guardian agent | Audits a codebase for MVVM/SOLID faithfulness, advises which lib belongs where (and whether you can swap it), and drafts/executes scaling migrations — running the real gates and citing evidence. |
It works for any RN app — whatever your stack (React Navigation or
expo-router, with or without TanStack Query/SWR, fetch or axios, Zustand/Redux/
MobX/Context/Jotai) and whatever your structure (screen-based through micro-frontend). The
MVVM triad and every layer's responsibility never change; only how files are
grouped (the rung) and which library sits inside a layer do. A concrete Expo +
expo-router + TanStack Query + Zustand + axios instantiation is included as a
copy-and-adapt worked example — not a separate, competing skill.
The north star is constant: guide toward MVVM, SOLID, best practices, and
conventions. You keep the power to choose your libraries and your structure; the
skill keeps each choice behind its boundary so the app stays faithful and the
choice stays reversible.
New here? Skim the cheatsheet
for a 60-second orientation, then copy the
§0 quickstart (~40 lines —
the smallest faithful triad) and add layers only when a distinct reason to change
appears. Everything else is reference you reach for on demand.
Install
This repo self-hosts as a plugin marketplace (.claude-plugin/marketplace.json).
In Claude Code:
/plugin marketplace add alexandrecoura96/react-native-mvvm-guardian
/plugin install rn-mvvm-guardian@react-native-mvvm-guardian
(Update the owner if you fork/transfer the repo.) Then:
- Skill:
/rn-mvvm-guardian:rn-mvvm-guardian — Claude also auto-invokes it based on its description.
- Agent: appears in
/agents (rn-mvvm-guardian).
To try it before publishing, add a local path instead:
/plugin marketplace add ./react-native-mvvm-guardian.
What's inside
skills/rn-mvvm-guardian/SKILL.md — the stack- and structure-agnostic skill (triad,
boundaries, activation flow, stack-neutral red flags).skills/rn-mvvm-guardian/references/:
cheatsheet.md — the one-screen digest (triad table, where-does-X-go, red flags,
the ladder, the gates, naming), each row pointing at the deep reference. Start here.mvvm-and-scaling.md — the layer contract, conformance checklist, scaling
ladder, migration playbooks, and governance.triad-example.md — the triad in code: a full Model→…→View→Screen slice, the
ViewModel contract as a discriminated union, controlled inputs, tests, and the
harder cases — typed route params, mutations (optimistic + rollback), an error
boundary, and the same triad on MobX / RTK Query / Redux.conventions.md — glossary, naming rules, canonical folder trees, VM-state
modeling, the adoption ladder, and what's out of scope (so far).stack-choices.md — the library menu per concern, where each plugs into the
boundaries, and how swappable each is.worked-examples.md — a concrete Expo + TanStack instantiation: conformance
greps, the feature-boundary ESLint recipe, the AuthBridge inversion,
server-/client-state specifics, and the worked screen→feature migration —
plus §10, the same recipes re-derived on a contrasting stack (bare RN +
React Navigation + Redux Toolkit + fetch) so the patterns are shown changing
imports only. Keep the pattern, swap the specifics for your libs.integration-recipes.md — the previously-deferred concerns worked in code:
observability, real-time, offline-first/sync, GraphQL, deep linking, and security —
each kept behind one layer's neutral contract (so a library swap stays one-layer).
agents/rn-mvvm-guardian.md — the audit + stack-choice advice + scaling agent.
Provenance
