@appiq/flutter-workflow 1.2.0 → 1.3.0

package/bin/cli.js

@@ -54,7 +54,8 @@ const AGENTS = [
   'domain-agent',
   'data-agent',
   'security-agent',
-  'test-agent'
+  'test-agent',
+  'initial-flow-agent'
 ];
 
 program
@@ -144,6 +145,27 @@ program
         const featuresDir = path.join(docsDir, 'features');
         await fs.ensureDir(featuresDir);
         
+        // Copy additional requirement templates
+        const templatesDir = path.join(__dirname, '../templates');
+        const targetTemplatesDir = path.join(currentDir, 'docs', 'additional_requirements');
+        await fs.ensureDir(targetTemplatesDir);
+        
+        const additionalTemplates = [
+          'additional_ui_req.md',
+          'additional_cubit_req.md', 
+          'additional_domain_req.md',
+          'additional_data_req.md'
+        ];
+        
+        for (const template of additionalTemplates) {
+          const sourceTemplate = path.join(templatesDir, template);
+          const targetTemplate = path.join(targetTemplatesDir, template);
+          
+          if (await fs.pathExists(sourceTemplate)) {
+            await fs.copy(sourceTemplate, targetTemplate);
+          }
+        }
+
         // Create sample feature documentation
         const sampleFeatureContent = `---
 name: SampleFeature
@@ -152,6 +174,7 @@ domain: open
 data: open
 security: open
 test: open
+initial_flow: open
 status: open
 ---
 
@@ -168,6 +191,20 @@ Describe your feature here. This will be analyzed by the PO Agent to create deta
 - Any technical considerations
 - Dependencies
 - Performance requirements
+
+## Additional Requirements
+After basic implementation, you can use additional requirement templates:
+- docs/additional_requirements/additional_ui_req.md - Role-based UI and access control
+- docs/additional_requirements/additional_cubit_req.md - Advanced state management and provider setup
+- docs/additional_requirements/additional_domain_req.md - Complex business rules and domain logic
+- docs/additional_requirements/additional_data_req.md - Supabase MCP integration and advanced data patterns
+
+## Integration Setup
+Use the Initial Flow Agent for:
+- Dependency injection configuration
+- Provider setup and initialization
+- Integration testing and validation
+- Error prevention and troubleshooting
 `;
         
         await fs.writeFile(
@@ -189,6 +226,7 @@ Describe your feature here. This will be analyzed by the PO Agent to create deta
       
       console.log(chalk.gray('\\n📁 Created directories:'));
       console.log(chalk.gray('  📄 docs/features/ - Feature documentation and status tracking'));
+      console.log(chalk.gray('  📋 docs/additional_requirements/ - Advanced requirement templates'));
       
       console.log(chalk.bold.yellow('\\n🚀 Next Steps:'));
       console.log(chalk.gray('1. Create your feature documentation in docs/features/'));
@@ -204,6 +242,7 @@ Describe your feature here. This will be analyzed by the PO Agent to create deta
       console.log(chalk.gray('  🗄️  Data Agent - Backend integration specialist'));
       console.log(chalk.gray('  🔐 Security Agent - Security and compliance expert'));
       console.log(chalk.gray('  🧪 Test Agent - Testing pyramid implementation'));
+      console.log(chalk.gray('  🚀 Initial Flow Agent - Provider setup and integration specialist'));
       
     } catch (error) {
       console.error(chalk.red('❌ Installation failed:'), error.message);
@@ -292,6 +331,7 @@ domain: open
 data: open
 security: open
 test: open
+initial_flow: open
 status: open
 ---
 
@@ -322,6 +362,19 @@ As a [user type], I want [functionality] so that [benefit].
 - UI/UX requirements
 - Screen designs
 - User flow
+
+## Additional Requirements (Optional)
+Use these templates after basic implementation for advanced features:
+- docs/additional_requirements/additional_ui_req.md - Role-based access control
+- docs/additional_requirements/additional_cubit_req.md - Advanced state management
+- docs/additional_requirements/additional_domain_req.md - Complex business logic
+- docs/additional_requirements/additional_data_req.md - Supabase MCP integration
+
+## Integration Setup
+After implementation, use Initial Flow Agent for:
+- Complete dependency injection setup
+- Provider hierarchy configuration  
+- Integration testing and validation
 `;
       
       const fileName = name.toLowerCase().replace(/[^a-z0-9]/gi, '-');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@appiq/flutter-workflow",
-  "version": "1.2.0",
-  "description": "🚀 Professional Flutter development with AI-powered agents following Clean Architecture principles - Automated agent-based feature development system by AppIQ Solutions",
+  "version": "1.3.0",
+  "description": "🚀 [BETA] Professional Flutter development with AI-powered agents following Clean Architecture principles - Automated agent-based feature development system by AppIQ Solutions",
   "main": "bin/cli.js",
   "bin": {
     "appiq-workflow": "bin/cli.js"

package/templates/additional_cubit_req.md

@@ -0,0 +1,357 @@
+# Additional Cubit Requirements - State Management Integration
+
+This template defines additional state management requirements, provider setup, and integration patterns for your feature.
+
+## State Management Architecture
+
+### Cubit Integration Pattern
+```dart
+// Feature-specific state management structure
+lib/features/{feature}/presentation/cubit/
+├── {feature}_cubit.dart           // Main cubit implementation
+├── {feature}_state.dart           // State definitions
+└── {feature}_event.dart           // Events (if using BLoC pattern)
+```
+
+### Global State Dependencies
+- [ ] Authentication state integration
+- [ ] User role state management  
+- [ ] Theme/settings state access
+- [ ] Navigation state coordination
+- [ ] Network connectivity state
+- [ ] Offline/online state management
+
+## Provider Setup Requirements
+
+### Main App Provider Configuration
+```dart
+// Add to main.dart MultiBlocProvider
+MultiBlocProvider(
+  providers: [
+    // Existing providers...
+    BlocProvider<{Feature}Cubit>(
+      create: (context) => GetIt.instance<{Feature}Cubit>(),
+    ),
+    // Additional feature dependencies...
+  ],
+  child: MyApp(),
+)
+```
+
+### Dependency Injection Setup
+```dart
+// Add to dependency injection configuration
+void configureDependencies() {
+  // Repository registration
+  getIt.registerLazySingleton<{Feature}Repository>(
+    () => {Feature}RepositoryImpl(
+      remoteDataSource: getIt(),
+      localDataSource: getIt(),
+      networkInfo: getIt(),
+    ),
+  );
+
+  // Use case registration
+  getIt.registerLazySingleton(() => Get{Feature}UseCase(getIt()));
+  getIt.registerLazySingleton(() => Create{Feature}UseCase(getIt()));
+  getIt.registerLazySingleton(() => Update{Feature}UseCase(getIt()));
+  getIt.registerLazySingleton(() => Delete{Feature}UseCase(getIt()));
+
+  // Cubit registration
+  getIt.registerFactory<{Feature}Cubit>(
+    () => {Feature}Cubit(
+      get{Feature}UseCase: getIt(),
+      create{Feature}UseCase: getIt(),
+      update{Feature}UseCase: getIt(),
+      delete{Feature}UseCase: getIt(),
+    ),
+  );
+}
+```
+
+## State Initialization Requirements
+
+### Initial State Setup
+```dart
+class {Feature}Cubit extends Cubit<{Feature}State> {
+  {Feature}Cubit({
+    required this.get{Feature}UseCase,
+    required this.create{Feature}UseCase,
+    required this.update{Feature}UseCase,
+    required this.delete{Feature}UseCase,
+  }) : super(const {Feature}State.initial());
+
+  // Initialize feature data on cubit creation
+  Future<void> initialize() async {
+    emit(state.copyWith(status: {Feature}Status.loading));
+    
+    try {
+      final result = await get{Feature}UseCase.call(NoParams());
+      result.fold(
+        (failure) => emit(state.copyWith(
+          status: {Feature}Status.error,
+          errorMessage: failure.message,
+        )),
+        (data) => emit(state.copyWith(
+          status: {Feature}Status.loaded,
+          items: data,
+        )),
+      );
+    } catch (e) {
+      emit(state.copyWith(
+        status: {Feature}Status.error,
+        errorMessage: 'Unexpected error occurred',
+      ));
+    }
+  }
+}
+```
+
+### Widget Integration Pattern
+```dart
+class {Feature}Page extends StatefulWidget {
+  @override
+  _State createState() => _State();
+}
+
+class _State extends State<{Feature}Page> {
+  late {Feature}Cubit cubit;
+
+  @override
+  void initState() {
+    super.initState();
+    cubit = context.read<{Feature}Cubit>();
+    // Initialize cubit data
+    cubit.initialize();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return BlocConsumer<{Feature}Cubit, {Feature}State>(
+      listener: (context, state) {
+        // Handle side effects (navigation, snackbars, etc.)
+        if (state.status == {Feature}Status.error) {
+          ScaffoldMessenger.of(context).showSnackBar(
+            SnackBar(content: Text(state.errorMessage ?? 'Error occurred')),
+          );
+        }
+      },
+      builder: (context, state) {
+        return Scaffold(
+          body: _buildBody(state),
+        );
+      },
+    );
+  }
+}
+```
+
+## Common Integration Issues & Solutions
+
+### Issue 1: Cubit Not Initialized
+**Problem**: `BlocProvider.of() called with a context that does not contain a Cubit`
+**Solution**:
+```dart
+// Ensure proper provider hierarchy
+MaterialApp(
+  home: MultiBlocProvider(
+    providers: [
+      BlocProvider<{Feature}Cubit>(
+        create: (context) => GetIt.instance<{Feature}Cubit>(),
+      ),
+    ],
+    child: {Feature}Page(),
+  ),
+)
+```
+
+### Issue 2: Duplicate Cubit Registration
+**Problem**: Multiple registrations of the same cubit type
+**Solution**:
+```dart
+// Use registerFactory for cubits (new instance per request)
+getIt.registerFactory<{Feature}Cubit>(() => {Feature}Cubit(...));
+
+// Or check if already registered
+if (!getIt.isRegistered<{Feature}Cubit>()) {
+  getIt.registerFactory<{Feature}Cubit>(() => {Feature}Cubit(...));
+}
+```
+
+### Issue 3: State Not Persisting Across Navigation
+**Problem**: State resets when navigating between screens
+**Solution**:
+```dart
+// Use singleton registration for state that should persist
+getIt.registerLazySingleton<{Feature}Cubit>(() => {Feature}Cubit(...));
+
+// Or use global provider at app level
+class MyApp extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return MultiBlocProvider(
+      providers: [
+        BlocProvider<{Feature}Cubit>(
+          create: (context) => GetIt.instance<{Feature}Cubit>(),
+        ),
+      ],
+      child: MaterialApp(...),
+    );
+  }
+}
+```
+
+## Cross-Feature State Communication
+
+### Feature-to-Feature State Updates
+```dart
+class {Feature}Cubit extends Cubit<{Feature}State> {
+  final AuthenticationCubit authCubit;
+  final UserRoleCubit userRoleCubit;
+  late StreamSubscription authSubscription;
+
+  {Feature}Cubit({
+    required this.authCubit,
+    required this.userRoleCubit,
+    // ... other dependencies
+  }) : super(const {Feature}State.initial()) {
+    // Listen to authentication changes
+    authSubscription = authCubit.stream.listen((authState) {
+      if (authState is! AuthenticatedState) {
+        // Clear feature data on logout
+        emit(const {Feature}State.initial());
+      }
+    });
+  }
+
+  @override
+  Future<void> close() {
+    authSubscription.cancel();
+    return super.close();
+  }
+}
+```
+
+### Global State Access Pattern
+```dart
+// Access other cubits from within a cubit
+void updateBasedOnUserRole() {
+  final userRole = userRoleCubit.state.role;
+  
+  switch (userRole) {
+    case UserRole.admin:
+      loadAdminData();
+      break;
+    case UserRole.manager:
+      loadManagerData();
+      break;
+    case UserRole.user:
+      loadUserData();
+      break;
+  }
+}
+```
+
+## Performance Optimization
+
+### Selective State Updates
+```dart
+// Use copyWith efficiently to avoid unnecessary rebuilds
+emit(state.copyWith(
+  status: {Feature}Status.loading,
+  // Only update changed fields
+));
+
+// Use state comparison to prevent duplicate emissions
+void updateItems(List<{Entity}> newItems) {
+  if (!listEquals(state.items, newItems)) {
+    emit(state.copyWith(items: newItems));
+  }
+}
+```
+
+### Memory Management
+```dart
+class {Feature}Cubit extends Cubit<{Feature}State> {
+  final List<StreamSubscription> _subscriptions = [];
+
+  void addSubscription(StreamSubscription subscription) {
+    _subscriptions.add(subscription);
+  }
+
+  @override
+  Future<void> close() {
+    // Cancel all subscriptions
+    for (final subscription in _subscriptions) {
+      subscription.cancel();
+    }
+    _subscriptions.clear();
+    return super.close();
+  }
+}
+```
+
+## Testing Integration
+
+### Cubit Testing Setup
+```dart
+// Test setup with proper mocking
+class MockAuthCubit extends MockCubit<AuthState> implements AuthCubit {}
+class MockUserRoleCubit extends MockCubit<UserRoleState> implements UserRoleCubit {}
+
+void main() {
+  late {Feature}Cubit cubit;
+  late MockAuthCubit mockAuthCubit;
+  late MockUserRoleCubit mockUserRoleCubit;
+
+  setUp(() {
+    mockAuthCubit = MockAuthCubit();
+    mockUserRoleCubit = MockUserRoleCubit();
+    
+    cubit = {Feature}Cubit(
+      authCubit: mockAuthCubit,
+      userRoleCubit: mockUserRoleCubit,
+      // ... other dependencies
+    );
+  });
+
+  tearDown(() {
+    cubit.close();
+  });
+}
+```
+
+## Integration Checklist
+
+### Provider Setup
+- [ ] Cubit registered in dependency injection
+- [ ] Provider added to MultiBlocProvider
+- [ ] Dependencies properly injected
+- [ ] Initialization logic implemented
+
+### State Management
+- [ ] Initial state properly defined
+- [ ] State transitions implemented
+- [ ] Error handling added
+- [ ] Loading states managed
+
+### Cross-Feature Integration
+- [ ] Authentication state integration
+- [ ] User role state access
+- [ ] Global state dependencies resolved
+- [ ] Navigation state coordination
+
+### Performance & Memory
+- [ ] Efficient state updates implemented
+- [ ] Memory leaks prevented (subscriptions canceled)
+- [ ] Unnecessary rebuilds minimized
+- [ ] State persistence strategy defined
+
+### Testing
+- [ ] Unit tests for cubit logic
+- [ ] Integration tests with providers
+- [ ] Mock implementations for dependencies
+- [ ] Error scenario testing
+
+## Notes
+Add any feature-specific state management requirements, custom integration patterns, or special initialization needs.