flutter-app-builder: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Repo Is

This repo is not a Flutter application — it is the flutter-app-builder skill package consumed by agents (Codex / Claude Code) to act as a pragmatic senior Flutter engineer. The "source" here is prose guidance and code templates, not runtime code.

When a task involves editing this repo, you are editing skill instructions, not application logic. When a task uses this skill, you are following SKILL.md to work on some other Flutter target the user points you at.

Core Principle

No coupling — every external dependency is wrapped behind an app-owned interface and registered in DI. This is the central invariant of the entire skill. Every template must reinforce it. If a template introduces a direct third-party import outside a wrapper file, it is a defect.

Repository Layout

• SKILL.md — lightweight orchestrator and dispatch table. References individual skills and defines greenfield phases, non-negotiable rules, and post-implementation audit.
• skills/ — 36 individual skill files, one per topic. Each skill has YAML front matter (name + description), inline key rules, co-load dependencies, and a link to the full template reference. Skills are the primary dispatch layer:
  • flutter-app-shell.md — project layout, pubspec, entry points, bootstrap, opinionated stack.
  • flutter-theme.md — AppColors, AppSpacing, AppTypography (Google Fonts/Inter), AppTheme light+dark.
  • flutter-di.md — service_locator.dart, wrapper rule, composition-root rule, lifetimes.
  • flutter-network.md — Failure hierarchy, interceptors, DioClient, ApiClient, JSON patterns.
  • flutter-storage.md — SecureStorage, KeyValueStore, drift AppDatabase + DAO, pagination.
  • flutter-routing.md — GoRouter, auth guard, ShellRoute, StatefulShellRoute, deep linking.
  • flutter-logging.md — AppLogger interface, LoggerImpl wrapper, observability patterns.
  • flutter-base-classes.md — BaseEntity, BaseDto, BaseCubit, BaseState, BasePaginatedCubit, BasePage, BaseRepository.
  • flutter-architecture.md — Clean architecture: entity → DTO → data source → use case → cubit → page.
  • flutter-feature.md — Feature end-to-end: cubit, state, repository, DI module, page.
  • flutter-auth.md — AuthService, TokenManager, BiometricService, token refresh, auth guard.
  • flutter-forms.md — Multi-step wizard, validators, FormFieldState, async validation.
  • flutter-loading.md — SuperListView (shimmer→error/empty→data+refresh), AppShimmer, LoadingButton.
  • flutter-dialog.md — AppDialog wrapper: toast, confirm, notification, loading, custom dialogs.
  • flutter-common-widgets.md — App bars, buttons, fields, cards, badges, chips, avatars, empty/error states.
  • flutter-offline.md — ConnectivityService, SyncQueue, SyncManager, offline-first repository.
  • flutter-analytics.md — AnalyticsService + CrashReporter wrappers (Firebase Analytics, Sentry).
  • flutter-permissions.md — PermissionService wrapper: camera, location, notifications.
  • flutter-push.md — PushNotificationService + LocalNotificationService wrappers (FCM).
  • flutter-localization.md — LocalizationService wrapper, plurals, RTL, dynamic locale.
  • flutter-error-handling.md — ErrorHandler, zone guard, FlutterError/PlatformDispatcher, ErrorBoundary.
  • flutter-feature-flags.md — FeatureFlagService, A/B testing, kill switches, FeatureGate widget.
  • flutter-state-restoration.md — RestorationMixin, HydratedCubit, form/scroll/tab restoration.
  • flutter-platform-channels.md — MethodChannel, EventChannel, BasicMessageChannel wrappers.
  • flutter-flavors.md — Env enum, EnvConfig, AppConfig, per-flavor entry points.
  • flutter-design-system.md — Figma → JSON → Dart tokens, Widgetbook catalog, golden tests.
  • flutter-animations.md — AppAnimations constants, flutter_animate, Lottie wrapper, hero transitions.
  • flutter-performance.md — Const rules, rebuild minimization, list performance, isolates.
  • flutter-memory-leak.md — Dispose contracts, StreamSubscription cancel, leak_tracker, DevTools memory profiling.
  • flutter-security.md — Secret management, SecureStorage, certificate pinning, obfuscation, log redaction, OWASP Mobile Top 10.
  • flutter-accessibility.md — Semantics, tap targets, focus management, contrast, screen reader testing.
  • flutter-tests.md — bloc_test, widget tests, golden tests, integration tests, coverage gate.
  • flutter-ci.md — GitHub Actions: analyze, test, coverage gate, build artifacts, dependabot.
  • flutter-release.md — Signing, obfuscation, Fastlane, Firebase/TestFlight/stores, Shorebird.
  • flutter-migration.md — Existing-app adoption: audit, phased wrapping, centralize DI, feature migration.
  • flutter-dart-patterns.md — Records, sealed classes, extension methods, mixins, pattern matching, typedefs (Dart 3).
• evals/ — automated eval suite verifying skill output compliance:
  • cases/ — 36 eval case definitions, one per skill, each named flutter-<skill>.md.
  • check-output.sh — deterministic grep-based rule checker (23 checks spanning architecture invariants, state/safety rules, security, UI quality, and toolchain).
  • run-evals.sh — runner: generate → check → score. Supports Claude Code CLI, Codex, and custom agents.
  • rubric.md — scoring model, pass thresholds (Production >= 95%, RC >= 85%, Beta >= 70%).
• README.md — public-facing overview, installation, and usage guide.