uwuclxdy/agenticat / skills/clean-flutter
clean-flutter
VerifiedIdiomatic Flutter and Dart rules: feature-first layout, Riverpod, freezed, go_router, const correctness.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.2 KB |
| references/architecture.md | markdown | 3.2 KB |
| references/models-serialization.md | markdown | 2.8 KB |
| references/navigation.md | markdown | 1.9 KB |
| references/packages.md | markdown | 2.9 KB |
| references/pitfalls.md | markdown | 4.4 KB |
| references/state-management.md | markdown | 3.9 KB |
| references/testing.md | markdown | 3.2 KB |
references/architecture.md
View on GitHub# Architecture
Feature-first layout, MVVM inside a feature, and the `Result` boundary. Project-shaping rules; the always-on discipline is in `SKILL.md`.
## Feature-First, Not Layer-First
Group by feature, layer inside each feature. Layer-first (`models/`, `services/`, `widgets/` at the top) scatters one feature's files across the tree and gets painful as the app grows. Reserve it for a genuinely tiny single-screen app.
```
lib/src/
core/ shared: theme, router, Result, common widgets, env
features/
auth/
data/ repositories + data sources (API clients, DB, DTOs)
domain/ models + logic spanning repos (pure Dart, no Flutter import)
presentation/ widgets (View) + view models (Riverpod notifiers)
profile/
data/ domain/ presentation/
```
## MVVM Inside a Feature
| Layer | Holds | May depend on |
|---|---|---|
| presentation | View (widgets) + ViewModel (a Riverpod `Notifier`/`AsyncNotifier`) | domain |
| domain | immutable models, optional use-case/service classes for logic crossing repos | nothing (pure Dart) |
| data | repositories, data sources, DTOs, API clients, DB access | domain |
- The View watches its ViewModel and renders; it holds no business logic. The ViewModel exposes UI state and calls repositories.
- Dependency points inward: presentation to domain to data. The View never imports a data source; it goes through a repository. The domain layer imports no Flutter.
- Keep DTOs (the wire shape) out of the domain. Map DTO to domain model in the data layer so an ugly API can't leak its shape across the app.
## The `Result` Boundary
Dart exceptions are invisible in the type system: nothing forces a caller to handle a throw, so an uncaught one becomes a runtime crash. A sealed `Result<T>` moves the failure path into the signature, checked by `switch` exhaustiveness.
```dart
sealed class Result<T> {
const Result();
}
final class Ok<T> extends Result<T> {
const Ok(this.value);
final T value;
}
final class Failure<T> extends Result<T> {
const Failure(this.error);
final Object error;
}
```
Repositories contain the `try/catch` and translate throws into `Result`. Nothing leaks to callers:
```dart
Future<Result<User>> fetchUser(String id) async {
try {
final dto = await _api.getUser(id);
return Ok(dto.toDomain());
} on DioException catch (e) {
return Failure(NetworkError(e));
}
}
```
Callers `switch` instead of wrapping every call in `try/catch`:
```dart
switch (await repo.fetchUser(id)) {
case Ok(:final value):
state = AsyncData(value);
case Failure(:final error):
state = AsyncError(error, StackTrace.current);
}
```
- Only wrap **expected** failures (network down, file missing, bad input) in `Result`. Let programmer errors throw and crash-report.
- The real cost: chaining several sequential `Result`-returning async calls is more verbose than `try/catch`, since each step unwraps by hand. Worth it at the repository boundary; don't thread `Result` through every internal helper.
- Ready-made packages (`result_dart`, `multiple_result`) exist if you'd rather not hand-roll, but the sealed class above is about ten lines and adds no dependency. freezed can generate the union too.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |