abdelhakrazi/flutter-bloc-clean-architecture-skill

Overview

This skill automates production-grade Flutter development using BLoC state management, strict clean architecture layers, and the project's design system. It enforces feature-first structure, repository/datasource separation, and zero hardcoded UI constants. Use it to scaffold, validate, or refactor screens, widgets, and data integrations to meet team standards.

How this skill works

The skill inspects the task type (new feature, widget, data integration, or refactor) and applies a decision tree to generate or validate files in the correct feature folder. It creates BLoC event/state/bloc files, data layer datasources/repositories/models, view pages and widgets, and barrel exports while enforcing Equatable, Loading→Success/Error flows, and datasource-only SDK usage. It also replaces inline colors, spacing, radii, and typography with design system constants.

When to use it

• Building a new screen or complete feature — scaffold BLoC, data, and view layers.
• Adding or updating a reusable widget — implement in feature/view/widgets or shared/widgets with design tokens.
• Integrating a backend endpoint — add datasource + repository and wire to an existing or new BLoC.
• Refactoring code that mixes business logic into UI or uses hardcoded styles.
• Validating PRs to ensure Equatable usage, loading states, and correct error handling.

Best practices

• Keep feature-specific code inside lib/[feature]/ and shared code in lib/shared/ only when used by 2+ features.
• Always emit a Loading state before async work, then emit Success or Error; never skip Loading.
• Place all backend SDK calls in datasources; repositories map responses to domain entities.
• Use AppColors, AppSpacing, AppRadius, and AppTypography—no hardcoded colors, paddings, radii, or text styles.
• Use Equatable for all Event and State classes and show errors via SnackBar with AppColors.error.

Example use cases

• Scaffold an earnings feature: bloc, data/datasources, repositories, models, view page, widgets, and barrel exports.
• Create a shared API client in shared/data/datasources and reference it from multiple feature repositories.
• Replace inline padding and color values across a screen with AppSpacing and AppColors to satisfy design tokens.
• Add a new data integration: implement FeatureDataSource calling the SDK, FeatureRepository mapping DTOs, and FeatureBloc handling states.
• Refactor a widget that performs business logic into events dispatched to a BLoC with proper states.