VGV FFCA Plugin
A Claude Code plugin that operationalizes Feature-First Clean Architecture (FFCA) for Flutter monorepos.
Developed with 💙 by Very Good Ventures 🦄
Overview
VGV FFCA Plugin teaches Claude the Feature-First Clean Architecture conventions and enforces its layer rules as you work. It ships three asset types:
- Skills that guide FFCA workflows: where code lives, how to scaffold a feature, how to wire routing, how to couple features, and how to audit a repo.
- Hooks: a blocking validation hook that runs on every
pubspec.yaml edit and stops the edit when it breaks a layer dependency rule, with the rule and the fix in the message so Claude self-corrects, plus a Very Good CLI check that gates its MCP tool calls.
- An MCP configuration that wires the Very Good CLI server for project and package operations.
The conventions themselves live in references/ffca/, a byte mirror of the canonical FFCA documentation on VGV Engineering, regenerated by scripts/sync_reference.dart. The skills never restate the conventions: they point into the mirror by file and section, so the architecture has exactly one source of truth.
The architecture reference
references/ffca/ holds one file per page of the canonical documentation, fetched verbatim from the FFCA section of VGV Engineering:
| File | Covers |
|---|
overview.md | Goals, the three-part structure, feature archetypes, shared libraries, the layer model |
domain.md | Models, Commands and Queries, repository interfaces, composing features, the Summary pattern |
data.md | Data sources, DTOs, converters and mappers |
presentation.md | Modules, localizations, widgets that own state, widget slots, subfeature barrels |
navigation.md | Callback injection, typed routes, splitting the routing table, deep links |
project_structure.md | Dependency rules, deferred loading, naming, folder layout, tooling, add-to-app |
faq.md | Callable classes, auth and user profiles, one big OpenAPI spec, nested objects |
Do not edit these by hand. Fix the architecture at the source, then sync:
dart run scripts/sync_reference.dart # rewrite the mirror
dart run scripts/sync_reference.dart --check # fail if it is stale
A scheduled workflow runs --check weekly, so the mirror cannot quietly fall behind upstream.
The stack
This plugin is the structure layer of Very Good Ventures' AI-assisted engineering stack. It composes with the other two plugins rather than replacing them.
| Layer | Plugin | Role |
|---|
| Workflow | vgv-wingspan | brainstorm, plan, build, review |
| Structure | vgv-ffca-plugin | Monorepo structure, layer rules, FFCA conventions |
| Code quality | vgv-ai-flutter-plugin | Bloc, testing, a11y, theming, analyze and format hooks |
Each FFCA skill self-scopes to FFCA repos through its trigger description, so the plugin coexists with vgv-ai-flutter-plugin without conflicts. The detection signal is a features/ folder containing {feature}_domain, {feature}_data, or {feature}_presentation packages.
FFCA architecture vs layered architecture: which applies
Both this plugin and vgv-ai-flutter-plugin ship an architecture skill, and they target different structures. Use the signal in the repo to tell them apart:
- This plugin's
ffca-architecture applies to FFCA monorepos: a features/ folder of {feature}_domain, {feature}_data, and {feature}_presentation packages, with apps/ and shared/ alongside.
- vgv-ai-flutter-plugin's
layered-architecture applies to the standard VGV layered app: a packages/ folder of _repository and _api_client packages with business logic and presentation in the app's lib/.
The ffca-architecture skill defers to layered-architecture when it sees the packages/ + _repository/_api_client shape, and the validation hook only runs on repos that have a features/ folder, so a layered repo never triggers FFCA enforcement.
Installation
One-line install from your terminal:
claude plugin marketplace add VeryGoodOpenSource/very-good-claude-code-marketplace && claude plugin install vgv-ffca-plugin
Or inside an active Claude Code session, run these as two separate commands (the second only after the first completes):
-
Add the marketplace:
/plugin marketplace add VeryGoodOpenSource/very-good-claude-code-marketplace
-
Install the plugin:
/plugin install vgv-ffca-plugin
For more details, see the Very Good Claude Marketplace.
Local development
Load the plugin from a local checkout, validate it, and run the validator tests:
claude --plugin-dir .
claude plugin validate .
cd scripts && dart test
Skills
| Skill | Description |
|---|
| FFCA Architecture | Orientation: where code lives across apps/, features/, shared/, the naming conventions, the layer dependency rules, and the anti-patterns to reject |
| FFCA Feature | Scaffold and extend a feature: the three-package domain, data, and presentation structure, headless and presentation-only features, models, repositories, Commands and Queries, DTOs, mappers, Cubits, and Modules |
| FFCA Routing | Navigation: callback injection, go_router_builder typed routes, splitting the routing table, deferred imports, the $extra hydration pattern, and the feature-isolation constraints |
| FFCA Cross-Feature | Coupling features: domain-to-domain dependencies, the Summary pattern, Queries that combine repositories, sharing widgets, widget slots, and composing features |
| FFCA Audit | Whole-repo health check: dispatches the ffca-layer-auditor agent, which runs the mechanical layer, naming, and cycle checks plus a qualitative review and returns a per-package verdict table |
Skills activate automatically when Claude detects an FFCA repo or an FFCA-shaped question. You can also invoke them directly:
/ffca-architecture
/ffca-feature
/ffca-routing
/ffca-cross-feature
/ffca-audit
Hooks
A PostToolUse hook runs on every Edit, MultiEdit, or Write and ignores any other tool call. When the edited file is a pubspec.yaml inside an FFCA-shaped repo, it validates the package's layer dependencies. When it is a Dart file, it validates that file's imports and exports. A PreToolUse hook gates every Very Good CLI MCP tool call.
| Hook | Event | Behavior |
|---|
Validate layers (validate_layers.sh) | PostToolUse (Edit/MultiEdit/Write) | Runs the FFCA validator incrementally: on the edited package and its direct dependents for a pubspec edit (errors only for dependents), and on the edited file alone for a Dart edit. Exits 2 on an error (blocking: Claude must fix the dependency before continuing), printing the rule and the fix. Passes warnings to Claude as non-blocking context. Passes silently otherwise |
Check VGV CLI (check_vgv_cli.sh) | PreToolUse (mcp__.*very-good-cli__.*) | Auto-approves Very Good CLI MCP tool calls when the CLI is installed at 1.3.0 or newer, so they work in every run mode. Denies with an install or upgrade message when the CLI is missing or outdated. Stands aside for any other tool, or when the CLI version cannot be read |
The validator checks package naming under features/, the layer dependency rules, that nothing depends on an app, and cycles. It also checks that each feature's packages fit together: a data package depends on its own _domain under dependencies, a data package never exists without a _domain in its feature, and a _domain package never depends on the Flutter SDK. In lib/ and bin/, it checks that each feature package has a primary barrel lib/{package}.dart, that imports of other workspace packages go through a barrel at the root of their lib/, that another feature's presentation is imported through a dedicated barrel rather than its primary one, that a data barrel never exports DTOs or mappers, that every declared workspace dependency is imported, and that every imported workspace package is declared. An import of an undeclared package is checked against the same layer rules as a pubspec dependency, since a Dart workspace resolves it anyway. On a pubspec edit, a package with no lib/ yet is not required to have a barrel, so a new package can be scaffolded pubspec first.
The validator is also runnable directly for CI and audits, across the whole workspace:
dart run scripts/validate_layers.dart --all
Rules, severities, and suppressions
Every finding carries a rule ID in brackets. An error exits 2 and blocks the hook. A warning is reported but exits 0.
| Rule ID | Severity | Finding |
|---|
package-name | error | A package under features/{f}/ is not named {f}_domain, {f}_data, {f}_data_{backend}, or {f}_presentation |
depends-on-app | error | Any package depends on an app |
shared-depends-on-feature | error | A shared package depends on a feature package |
presentation-depends-on-data | error | A presentation package depends on a data package |
domain-depends-on-data | error | A domain package depends on a data package |
domain-depends-on-presentation | error | A domain package depends on a presentation package |
data-depends-on-presentation | error | A data package depends on a presentation package |
data-depends-on-feature-data | error | A data package depends on another feature's data package |
layer-dependency | error | Any other dependency the rules table does not allow |
dependency-cycle | error | Packages depend on each other in a cycle |
data-missing-own-domain | error | A data package does not depend on its own _domain under dependencies |
data-without-domain | error | A data package's feature has no _domain package |
domain-uses-flutter | error | A domain package depends on the Flutter SDK |
presentation-missing-own-domain | warning | A presentation package does not depend on its feature's existing _domain |
missing-primary-barrel | error | A feature package has no lib/{package}.dart |
deep-import | error | A Dart file imports or exports another workspace package past the barrels at the root of its |
To accept a finding as a deliberate exception, add a comment with the rule ID and a reason to the pubspec of the package it is reported on:
# ffca-ignore: data-missing-own-domain — legacy repository, moving to orders_domain in #123
name: orders_data
A finding in a Dart file can also be suppressed in that file, with //:
// ffca-ignore: deep-import — the model is not exported from orders_domain yet
import 'package:orders_domain/models/order.dart';
The separator after the rule ID can be an em dash, an en dash, a hyphen, or a colon. A suppression in a pubspec covers every finding with that rule ID in that package, and one in a Dart file covers that file. Rules reported on the pubspec, such as unused-dependency or missing-primary-barrel, can only be suppressed in the pubspec. The reason is required, so each exception explains itself in review. The last three rules cannot be suppressed. --all reports how many findings were suppressed, and flags suppressions that no longer match anything so they can be removed.
Prerequisites
- Dart SDK must be available on your
PATH. The validator imports only dart:io, so it runs with just the SDK, no dart pub get required.
- jq is used to parse the hook payload. The hooks are skipped gracefully if
jq is not installed, and the validation hook also if dart is not installed.
Run the hook tests with:
bash hooks/check_vgv_cli_test.sh
bash hooks/validate_layers_test.sh
MCP Integration
The plugin's .mcp.json connects Claude Code to the Very Good CLI MCP server (very_good mcp) under the server name very-good-cli, the same name vgv-ai-flutter-plugin uses. The ffca-feature skill calls it to scaffold and resolve each feature package.
| Tool | What it does |
|---|
create | Scaffold packages from templates. FFCA uses dart_package for domain and data, flutter_package for presentation |
packages_get | Get dependencies for a single package or recursively across the monorepo |
test | Run tests with coverage enforcement |
packages_check_licenses | Audit dependency licenses against an allowed list |
When installed from a marketplace, Claude Code names these tools mcp__plugin_vgv-ffca-plugin_very-good-cli__<tool>, and the skills' allowed-tools use that full name.
The plugin does not bundle the Dart MCP server (dart mcp-server). No FFCA skill calls it, and vgv-ai-flutter-plugin already provides it for analyze and format.
The server needs Very Good CLI 1.3.0 or newer. Install it with dart pub global activate very_good_cli.
Agent
| Agent | Behavior |
|---|
| ffca-layer-auditor | Read-only architecture auditor. Runs the validator in --all mode, then adds source-level checks (barrel scope, DTO leakage, Command/Query necessity, module entry, split routing tables, deferred-loading reachability, misplaced packages, high fan-in) and returns a per-package verdict table. Reports violations, never auto-fixes |
The auditor runs in its own context, so the same architecture review can be dispatched from the ffca-audit skill, a refactor, or a pre-PR flow without crowding the main conversation. The per-edit hook prevents bad pubspec dependencies as they are written; the agent answers whether the whole repo is healthy on demand.
How it fits together
The hook keeps individual pubspec edits compliant. The skills teach the conventions and workflows. The ffca-layer-auditor agent answers whether the whole repo is healthy, on demand and reusable across flows. All of them read from the same references/ffca/ mirror, so when the architecture evolves, a sync is the only change.
