dartway

Finishing a dartway task before a commit/PR (DartWay projects): the "definition of done". Audits the diff against the base branch using the dartway-clean-code contract (Flutter + server), checks the affected feature's description for drift (DwFeatureSpec next to the code, doc comments above the CRUD config) and test coverage, then SHOWS suggestions and applies ONLY what was confirmed — it never changes anything silently. Use when a task/feature is done, before committing or opening a PR (Law 6); runs as /dartway-finish.

DartwayTeam strict clean-code rules for ALL Flutter/Dart work (DartWay projects): self-explanatory naming (min 2 words), single responsibility per file (length is a soft signal: >200 lines a nudge, >350 a warning — split by responsibility, not by line count), never pass BuildContext or WidgetRef as params, no _buildXxx() widget-returning methods, no ref.invalidate, no GlobalKey tree lookups, no outer padding/margin inside a widget, no private widget classes in public feature files; plus SOLID, KISS, DRY, YAGNI, Law of Demeter, composition over inheritance, separation of concerns, fail-fast, tell-don't-ask, single source of truth, and tests for complex features / non-trivial bugfixes.

Step-by-step playbook for building a new DartWay feature end-to-end (Flutter + Serverpod): navigation → UI entry point → state/logic via the data layer and Riverpod → backend CRUD configs → models/DB → tests. Feature structure (entry point + widgets + logic), isolation (import the entry point only), domain/app/ui_kit boundaries, the `DwFeatureSpec` feature spec in the feature's own file. Use when adding new functionality, a screen, a flow, or a model.

Server-side Serverpod YAML models in DartWay: .spy.yaml files in lib/src/models/<domain>/, enums in enums/. Base vs Event models (current state vs changes on top of the base — for money/ transactions), field types and nullable discipline (nullable only if the value is genuinely absent in the domain), 1-1/1-N/N-N relations via relation(name=...) (bidirectional — the same name on both sides), onDelete=Cascade, indexes/unique, default=, enum models (serialized: byName). Workflow: edit YAML → serverpod generate → create-migration → DwCrudConfig + registration in crudConfigurations → migrations at startup. Use when creating or changing models, fields, relations, enums and the DB schema.

DartWay Flutter data layer and specials (DartWay projects): data access only through dw.repo — reads are providers under the native ref.watch/read/refresh (dw.repo.model/maybeModel/modelList), writes are dw.repo.saveModel/deleteModel (no repositories, no manual syncing), lists via dwBuildListAsync(loadingItemsCount:), narrowing by query via backendFilter, local filtering you do yourself with .where in the widget, actions from the UI via dw.action (unified error/loading handling), notifications via dw.notify.* (not SnackBar), the profile via ref.watchUserProfile/readUserProfile (getters, not CRUD), sign-out via sessionProvider.notifier.signOut(). Use when working with data, actions, notifications, loading/saving models in Flutter features.

The DartWay/Serverpod server playbook: how to write CRUD configs — DwCrudConfig<T> (one per model), DwGetModelConfig, DwGetModelListConfig (both require accessFilter), DwSaveConfig (allowSave/validateSave/beforeSaveTransaction/afterSaveTransaction/afterSaveTransform/ afterSaveSideEffects), DwDeleteConfig (allowDelete/afterDelete), DwModelWrapper, Event models, the domain(pure)/app(session-aware) boundary. All server logic goes through configs, not through endpoints. Use when adding or changing server logic, permissions, validations, or side effects for a model.

Аудит синхронизации перед коммитом изменений фреймворка DartWay — проверяет, что изменения публичного API отражены в example/, template/, toolkit/skills/, docs/ и CHANGELOG. Запускать после завершения работы над кодом пакетов, перед коммитом/PR.

DartWay Router navigation rules for Flutter (DartWay projects): zones as enums implementing DwNavigationRoute<AppRouterState>; descriptors DwNavigationRouteDescriptor.zoneRoot/.simple/.parameterized; zone guards in zoneGuards; type-safe parameters via an enum with DwNavigationParamsMixin (set/fromPath/fromQuery); the router is assembled with DwRouter<T>(routerState:, navigationZones:, pageBuilder:, options:). Use when creating or editing routes, screens, redirects and navigation between zones.

Development planning AFTER the requirements are agreed (DartWay projects): the requirements are approved and an implementation option is chosen — the skill analyses the codebase once more for the chosen approach and produces a detailed step-by-step end-to-end plan (models → migrations → CRUD configs → server-side logic → Flutter data layer/feature/navigation/UI Kit → tests → docs), highlights the subtleties and risks and gives a verification checklist for after the implementation. Read-only: produces a plan, writes no code. Run as /dartway-plan after /dartway-requirements, before writing code.

Requirements analysis BEFORE starting a DartWay task (DartWay projects): the developer gives a spec — the skill studies in depth what the project already has on the topic (models, CRUD configs, features, docs), identifies refactoring and code-quality opportunities in the affected feature per the dartway-clean-code contract (blocking debt vs adjacent debt), assembles a pool of clarifying questions and proposes 2–3 implementation options along the 3-level DartWay ladder (Event models → CRUD configuration → custom endpoint) with constraints, tradeoffs, risks and a rough time estimate. Read-only: writes nothing, only a report. Run as /dartway-requirements at the start of work on a feature/task — before planning and code.

Bring a DartWay project up locally and confirm it is alive (DartWay projects): dependencies, Postgres in docker, migrations, seeding test users, the server, the app. Knows the order of the steps (seeding before migrations does not work), the real ports (API 8080, development DB 8090, test DB 9090, object storage 8100 and its console 8101), where to find the sign-in code (printed in the server console) and how to fix the typical failures: docker not running, port already taken, schema drifted, model changed without serverpod generate, serverpod_cli version not matching the project, images not opening by link, upload failing on unconfigured storage. Use when asked to "bring the project up", "run it", "why does it not start", "check that it works", and also after a model change or a fresh git clone.

UI Kit rules in DartWay Flutter: the kit lives as SOURCE inside the app (lib/ui_kit/) — the framework ships neither buttons, nor text, nor a theme. AppText/AppButton are app widgets with named constructors, AppTextStyle is a token for places where Flutter demands a TextStyle; the theme (AppTheme) is in the kit too. DwActionBuilder from the framework guards the action (busy, double tap, form validation). Inside features Color/TextStyle/BorderRadius/Theme.of/context.textTheme/colorScheme are forbidden; the only import is ui_kit.dart; part-of structure. Use when creating/editing UI components, styles, colors, themes, buttons, or when adding widgets to the kit.

Server-side push delivery in DartWay via the optional dartway_push_server Serverpod module: DwPush engine, DwPushConfig with recipientResolver + transport, built-in FCM/RuStore providers, idempotent enqueue, worker/cleanup, retries, account-deletion lock, campaign progress. Use when adding or reviewing push notifications in a DartWay Serverpod app. The module is opt-in — an app that does not depend on it has no push tables.