appiq-solution 1.6.4 → 1.7.0

package/bmad-core/data/mandatory-development-rules.md

@@ -0,0 +1,170 @@
+# MANDATORY DEVELOPMENT RULES
+## THESE RULES MUST ALWAYS BE FOLLOWED - NO EXCEPTIONS!
+
+This file provides mandatory guidance that MUST be followed by ALL agents when working with code in ANY repository.
+
+## 🚨 CRITICAL: Standard Workflow (ALWAYS FOLLOW!)
+
+### MANDATORY 8-Step Process:
+1. **THINK**: First think through the problem, read the codebase for relevant files
+2. **PLAN**: Write a detailed plan to `tasks/todo.md` with checkable items
+3. **VERIFY**: Check in with user - get plan approval before starting
+4. **WORK**: Work on todo items, marking them complete as you go
+5. **EXPLAIN**: Give high-level explanation of changes at every step
+6. **SIMPLE**: Make every change as simple as possible - impact minimal code
+7. **REVIEW**: Add review section to `todo.md` with summary of changes
+8. **COMMIT**: After every fully finished task - make git commit with proper message
+
+### MANDATORY Workflow Rules:
+- ✅ **NEVER start coding without a verified plan**
+- ✅ **ALWAYS check existing code before creating new code**
+- ✅ **ALWAYS extend existing code instead of duplicating**
+- ✅ **ALWAYS use existing patterns and folder structure**
+- ✅ **ALWAYS check if functionality already exists**
+- ✅ **ALWAYS make git commits after completed tasks**
+
+## 🎯 MANDATORY Quality Criteria (ALL 5 MUST PASS!)
+
+### 1. 🧹 DRY (Don't Repeat Yourself)
+- ✅ **NO code duplication allowed**
+- ✅ **ALWAYS reuse existing functions/classes/components**
+- ✅ **ALWAYS extract common functionality into shared utilities**
+- ✅ **ALWAYS check if similar code exists before writing new code**
+
+### 2. 📖 Readable
+- ✅ **Code MUST be self-documenting with clear naming**
+- ✅ **Methods MUST be small and focused (max 20 lines)**
+- ✅ **Classes MUST have single responsibility**
+- ✅ **Comments MUST explain WHY, not WHAT**
+
+### 3. 🔧 Maintainable
+- ✅ **MUST follow Clean Architecture with proper layer separation**
+- ✅ **MUST use dependency injection**
+- ✅ **MUST have modular design**
+- ✅ **MUST follow existing folder/file structure**
+
+### 4. ⚡ Performant
+- ✅ **MUST avoid redundant API calls**
+- ✅ **MUST use efficient algorithms**
+- ✅ **MUST optimize resource usage**
+- ✅ **MUST follow existing performance patterns**
+
+### 5. 🧪 Testable
+- ✅ **ALL business logic MUST be unit tested**
+- ✅ **ALL UI components MUST be widget tested**
+- ✅ **MUST use dependency injection for testability**
+- ✅ **MUST follow existing testing patterns**
+
+## 📱 MANDATORY Flutter-Specific Rules
+
+### Architecture Compliance (ALWAYS!)
+- ✅ **MUST follow Clean Architecture (Presentation → Domain ← Data)**
+- ✅ **MUST use Cubit for state management**
+- ✅ **MUST implement Repository pattern**
+- ✅ **MUST use GetIt for dependency injection**
+
+### Localization (ALWAYS!)
+- ✅ **NO static text allowed - EVER!**
+- ✅ **ALL user-facing text MUST use AppLocalizations**
+- ✅ **ALL localization keys MUST be descriptive**
+- ✅ **MUST add keys to ALL supported ARB files**
+
+### Code Structure (ALWAYS!)
+- ✅ **MUST follow existing folder structure**
+- ✅ **MUST use snake_case for files**
+- ✅ **MUST use PascalCase for classes**
+- ✅ **MUST use camelCase for methods/variables**
+
+### Integration Rules (ALWAYS!)
+- ✅ **BEFORE creating new files**: Check if similar exists
+- ✅ **BEFORE new widgets**: Review `lib/shared/widgets/`
+- ✅ **BEFORE new services**: Check `lib/shared/services/`
+- ✅ **BEFORE new utilities**: Review `lib/shared/utils/`
+
+## 🛠️ MANDATORY MCP Tool Usage
+
+### When to Use MCPs (ALWAYS check these!):
+- ✅ **sequential-thinking**: For complex problem analysis
+- ✅ **context7**: For up-to-date library documentation
+- ✅ **memory**: For storing important decisions/patterns
+- ✅ **puppeteer**: For web scraping/testing needs
+- ✅ **fetcher**: For external API data retrieval
+
+## 🔍 MANDATORY Pre-Development Checklist
+
+### Before ANY coding (ALWAYS!):
+- [ ] **Read existing codebase** for similar functionality
+- [ ] **Check shared components** for reusable parts
+- [ ] **Review existing patterns** in similar features
+- [ ] **Verify architecture compliance** with existing structure
+- [ ] **Plan minimal impact changes** - avoid massive refactors
+- [ ] **Ensure localization keys** are planned
+- [ ] **Identify testing requirements** early
+
+### During Development (ALWAYS!):
+- [ ] **Follow existing naming conventions** exactly
+- [ ] **Use existing error handling patterns**
+- [ ] **Reuse existing validation logic**
+- [ ] **Follow existing state management patterns**
+- [ ] **Use existing navigation patterns**
+- [ ] **Follow existing styling/theming**
+
+### After Development (ALWAYS!):
+- [ ] **Run all tests** and ensure they pass
+- [ ] **Check code coverage** meets minimum requirements
+- [ ] **Verify localization** works for all languages
+- [ ] **Test on different screen sizes**
+- [ ] **Review code** against all 5 quality criteria
+- [ ] **Make proper git commit** with descriptive message
+
+## 🚨 CRITICAL VALIDATION RULES
+
+### Code Review Criteria (ALL MUST PASS!):
+1. ✅ **Architecture**: Follows Clean Architecture with proper layer separation
+2. ✅ **Localization**: All text supports multi-language
+3. ✅ **Quality**: Passes all 5 quality criteria (DRY, Readable, Maintainable, Performant, Testable)
+4. ✅ **Documentation**: Code is properly documented with examples
+5. ✅ **Consistency**: Code style matches existing patterns
+
+### Failure Conditions (NEVER ALLOWED!):
+- ❌ **Static text in UI** - Immediate failure
+- ❌ **Code duplication** - Immediate failure
+- ❌ **Breaking existing patterns** - Immediate failure
+- ❌ **Missing tests** - Immediate failure
+- ❌ **Poor performance** - Immediate failure
+
+## 📋 MANDATORY Commit Message Format
+
+```
+type(scope): brief description
+
+- Detailed explanation of changes
+- Why the changes were made
+- What patterns were followed
+- What tests were added
+
+Quality Checklist:
+✅ DRY: No code duplication
+✅ Readable: Clear naming and structure
+✅ Maintainable: Modular design
+✅ Performant: Optimized implementation
+✅ Testable: Comprehensive test coverage
+```
+
+## 🎯 REMEMBER: Consistency is King!
+
+> **When in doubt, ALWAYS follow existing patterns in the codebase.**
+> **NEVER create new patterns without explicit approval.**
+> **ALWAYS prefer extending existing code over creating new code.**
+
+---
+
+## ⚠️ ENFORCEMENT NOTICE
+
+**These rules are MANDATORY and MUST be followed by:**
+- ✅ All BMAD agents (dev, flutter-ui-agent, flutter-cubit-agent, etc.)
+- ✅ All development workflows
+- ✅ All IDE integrations (Cursor, Claude Code, etc.)
+- ✅ All automated processes
+
+**NO EXCEPTIONS! NO SHORTCUTS! NO COMPROMISES!**

package/bmad-core/tasks/auto-detect-prds.md

@@ -0,0 +1,162 @@
+# Auto-Detect PRDs Task
+
+## Purpose
+Automatically detect PRD files based on pattern matching and trigger the complete BMAD workflow without manual Planning Phase.
+
+## Usage
+```bash
+@po auto-detect-prds
+```
+
+## Process
+
+### Step 1: Scan for PRD Files
+1. **Scan configured directories** from core-config.yaml `autoWorkflow.scanDirectories`
+2. **Look for files matching patterns**:
+   - `*_prd.md` (e.g., `livestream_prd.md`, `payment_prd.md`)
+   - `*_requirements.md`
+   - `*_feature.md`
+3. **List found files** and ask user for confirmation
+
+### Step 2: Process Each PRD File
+For each detected PRD file:
+
+1. **Validate PRD Structure**:
+   - Check for required sections (Features, Acceptance Criteria, etc.)
+   - Ensure proper markdown formatting
+   - Validate completeness
+
+2. **Auto-Shard Document**:
+   ```bash
+   md-tree explode {prd_file} docs/prd/{feature_name}
+   ```
+
+3. **Create Feature Directory Structure**:
+   ```
+   docs/
+   ├── prd/
+   │   └── {feature_name}/
+   │       ├── overview.md
+   │       ├── features.md
+   │       ├── acceptance-criteria.md
+   │       └── technical-requirements.md
+   └── stories/
+       └── {feature_name}/
+   ```
+
+### Step 3: Auto-Generate Stories
+1. **Extract Epics** from sharded PRD sections
+2. **Generate User Stories** from each epic
+3. **Create Story Files** in `docs/stories/{feature_name}/`
+4. **Apply Flutter-specific patterns** if Flutter extension detected
+
+### Step 4: Trigger Development Workflow
+1. **Notify SM** that stories are ready
+2. **Auto-start Flutter UI-First Workflow** if configured
+3. **Create initial todo.md** for development tracking
+
+## Example Workflow
+
+### Input Files:
+```
+docs/
+├── livestream_prd.md
+├── payment_prd.md
+└── user_profile_prd.md
+```
+
+### Command:
+```bash
+@po auto-detect-prds
+```
+
+### Output:
+```
+Found 3 PRD files:
+1. livestream_prd.md → Livestream Feature
+2. payment_prd.md → Payment Integration  
+3. user_profile_prd.md → User Profile Management
+
+Processing livestream_prd.md...
+✅ Sharded to docs/prd/livestream/
+✅ Generated 4 stories in docs/stories/livestream/
+✅ Ready for development
+
+Processing payment_prd.md...
+✅ Sharded to docs/prd/payment/
+✅ Generated 6 stories in docs/stories/payment/
+✅ Ready for development
+
+Processing user_profile_prd.md...
+✅ Sharded to docs/prd/user_profile/
+✅ Generated 3 stories in docs/stories/user_profile/
+✅ Ready for development
+
+🚀 All PRDs processed! Ready to start development with:
+@sm start-next-story
+```
+
+## PRD File Requirements
+
+Your `*_prd.md` files should contain:
+
+```markdown
+# Feature Name PRD
+
+## Overview
+Brief description of the feature
+
+## Features
+- Feature 1: Description
+- Feature 2: Description
+- Feature 3: Description
+
+## Acceptance Criteria
+### Feature 1
+- [ ] Criteria 1
+- [ ] Criteria 2
+
+### Feature 2
+- [ ] Criteria 1
+- [ ] Criteria 2
+
+## Technical Requirements
+- Flutter Clean Architecture
+- Cubit State Management
+- Repository Pattern
+- Unit Tests Required
+
+## User Stories
+### Epic: Feature Implementation
+- As a user I want to... so that...
+- As a user I want to... so that...
+
+## Dependencies
+- Backend API endpoints
+- Third-party integrations
+- Design assets
+```
+
+## Configuration
+
+Enable in `core-config.yaml`:
+```yaml
+autoWorkflow:
+  enabled: true
+  scanDirectories: 
+    - "docs/"
+    - "features/"
+  triggerPatterns:
+    - "*_prd.md"
+    - "*_requirements.md"
+```
+
+## Flutter-Specific Integration
+
+When Flutter extension is detected, automatically:
+1. **Apply Flutter story templates**
+2. **Set up UI-First workflow**  
+3. **Configure Clean Architecture patterns**
+4. **Prepare Cubit state management structure**
+
+This task bridges the gap between existing documentation and BMAD's development workflow, perfect for Brownfield projects!

package/bmad-core/tasks/smart-auto-detect-prds.md

@@ -0,0 +1,299 @@
+# Smart Auto-Detect PRDs Task
+
+## Purpose
+Intelligently detect PRD files, analyze existing codebase, and determine optimal implementation paths while maximizing code reuse.
+
+## Usage
+```bash
+@po smart-auto-detect-prds
+```
+
+## Enhanced Process
+
+### Step 1: PRD Discovery & Analysis
+1. **Scan for PRD Files** matching patterns:
+   - `*_prd.md`
+   - `*_requirements.md` 
+   - `*_feature.md`
+
+2. **Parse PRD Content**:
+   - Extract feature name
+   - Parse implementation paths (if specified)
+   - Identify UI reference assets
+   - Extract integration points
+   - Parse code reuse requirements
+
+### Step 2: Codebase Analysis
+For each detected PRD:
+
+#### A. Existing Code Scan
+```bash
+# 1. Find similar features
+find lib/features/ -type d -name "*{feature_keyword}*"
+
+# 2. Scan shared components  
+find lib/shared/ -name "*.dart" | xargs grep -l "{relevant_keywords}"
+
+# 3. Check existing services
+find lib/shared/services/ lib/core/services/ -name "*.dart"
+
+# 4. Analyze existing patterns
+find lib/features/ -name "*_cubit.dart" -o -name "*_repository.dart" -o -name "*_usecase.dart"
+```
+
+#### B. Dependency Analysis
+```bash
+# Check pubspec.yaml for existing packages
+grep -E "(http|dio|cached_network_image|shared_preferences)" pubspec.yaml
+
+# Analyze DI container
+grep -n "registerLazySingleton\|registerFactory" lib/core/di/injection_container.dart
+
+# Check existing API endpoints
+find lib/features/*/data/datasources/ -name "*_remote_datasource.dart" -exec grep -l "http" {} \;
+```
+
+#### C. UI Component Analysis
+```bash
+# Find reusable widgets
+find lib/shared/widgets/ -name "*.dart" | sort
+
+# Check existing page structures
+find lib/features/*/presentation/pages/ -name "*.dart"
+
+# Analyze existing themes and styles
+find lib/shared/theme/ lib/core/theme/ -name "*.dart"
+```
+
+### Step 3: Smart Path Resolution
+
+#### If Implementation Paths Specified in PRD:
+1. **Validate Specified Paths**:
+   - Check if directories exist
+   - Verify no conflicts with existing files
+   - Ensure paths follow project conventions
+
+2. **Integration Point Validation**:
+   - Verify specified existing files exist
+   - Check if integration points are compatible
+   - Validate shared component references
+
+#### If No Paths Specified - Architect Mode:
+1. **Feature Complexity Analysis**:
+   ```markdown
+   Analyzing feature: {feature_name}
+   
+   Complexity Factors:
+   - [ ] Number of screens: {count}
+   - [ ] External dependencies: {list}
+   - [ ] Database changes needed: {yes/no}
+   - [ ] New API endpoints: {count}
+   - [ ] Shared state requirements: {yes/no}
+   
+   Recommendation: {simple_integration|new_feature|shared_component}
+   ```
+
+2. **Automatic Path Generation**:
+   ```bash
+   # For new features
+   mkdir -p lib/features/{feature_name}/{data,domain,presentation}
+   
+   # For simple integrations
+   # Add to existing feature folder
+   
+   # For shared components
+   mkdir -p lib/shared/{widgets,services,utils}/{feature_name}
+   ```
+
+### Step 4: Code Reuse Optimization
+
+#### Existing Component Mapping:
+```markdown
+Found Reusable Components for {feature_name}:
+
+UI Components:
+✅ lib/shared/widgets/custom_button.dart - Can be used for {action_buttons}
+✅ lib/shared/widgets/loading_widget.dart - For loading states
+❌ Need new: {specific_widget} - No existing equivalent found
+
+Services:
+✅ lib/shared/services/api_service.dart - Can be extended for {api_calls}
+✅ lib/shared/services/navigation_service.dart - For navigation
+❌ Need new: {specific_service} - No existing equivalent found
+
+Utilities:
+✅ lib/shared/utils/validators.dart - For input validation
+✅ lib/shared/utils/formatters.dart - For data formatting
+❌ Need new: {specific_utility} - No existing equivalent found
+```
+
+#### Integration Strategy:
+```markdown
+Integration Plan for {feature_name}:
+
+1. Extend Existing:
+   - {existing_cubit} → Add {new_states}
+   - {existing_repository} → Add {new_methods}
+   - {existing_service} → Add {new_functionality}
+
+2. Create New:
+   - {new_entity} → lib/features/{feature}/domain/entities/
+   - {new_usecase} → lib/features/{feature}/domain/usecases/
+   - {new_widget} → lib/features/{feature}/presentation/widgets/
+
+3. Shared Enhancements:
+   - Add {new_shared_widget} → lib/shared/widgets/
+   - Extend {existing_theme} → lib/shared/theme/
+```
+
+### Step 5: UI Reference Processing
+
+#### Asset Organization:
+```bash
+# Create asset directories if specified
+mkdir -p assets/images/{feature_name}
+mkdir -p assets/icons/{feature_name}
+
+# Validate referenced assets exist
+for asset in {ui_reference_assets}; do
+  if [[ -f "$asset" ]]; then
+    echo "✅ Found: $asset"
+  else
+    echo "❌ Missing: $asset - Please add this asset"
+  fi
+done
+```
+
+#### UI Pattern Analysis:
+```markdown
+UI Pattern Analysis for {feature_name}:
+
+Similar Existing Patterns:
+✅ {existing_feature}/presentation/pages/{page}.dart - Similar layout structure
+✅ {existing_feature}/presentation/widgets/{widget}.dart - Similar component pattern
+
+Recommended UI Approach:
+- Base Layout: Extend {existing_scaffold_pattern}
+- Components: Reuse {existing_widget_pattern}
+- Styling: Follow {existing_theme_pattern}
+- Navigation: Use {existing_navigation_pattern}
+```
+
+### Step 6: Enhanced Story Generation
+
+#### Context-Aware Stories:
+```markdown
+Generated Stories for {feature_name}:
+
+Story 1: Setup Infrastructure
+- Extend {existing_repository} with {new_methods}
+- Add {new_entity} following {existing_pattern}
+- Register dependencies in {existing_di_container}
+
+Story 2: UI Implementation  
+- Create {new_page} extending {existing_base_page}
+- Reuse {existing_shared_widgets}
+- Follow {existing_theme_patterns}
+
+Story 3: Integration
+- Connect to {existing_navigation}
+- Integrate with {existing_services}
+- Add to {existing_routing}
+```
+
+### Step 7: Architect Consultation
+
+#### When Architect Input Needed:
+```bash
+@architect analyze-implementation-strategy {feature_name}
+```
+
+**Triggers for Architect Consultation**:
+- Complex cross-feature dependencies detected
+- No clear existing patterns found
+- Conflicting implementation approaches possible
+- Major architectural changes suggested
+
+#### Architect Analysis Output:
+```markdown
+Architect Analysis for {feature_name}:
+
+Current Architecture Assessment:
+- Existing patterns: {list}
+- Architectural constraints: {list}
+- Integration challenges: {list}
+
+Recommended Approach:
+1. Implementation Strategy: {detailed_strategy}
+2. File Structure: {recommended_structure}
+3. Integration Points: {specific_integration_points}
+4. Risk Mitigation: {potential_issues_and_solutions}
+
+Code Reuse Opportunities:
+- {existing_component} can be extended for {new_functionality}
+- {existing_pattern} should be followed for consistency
+- {existing_service} can be enhanced with {new_methods}
+```
+
+## Example Enhanced Workflow
+
+### Input: `livestream_prd.md` with Implementation Paths
+```markdown
+## Implementation Paths
+### Suggested File Structure
+lib/features/livestream/...
+
+### Integration Points  
+- Existing Pages: lib/features/home/presentation/pages/home_page.dart
+- Shared Services: lib/shared/services/api_service.dart
+
+### UI References
+assets/images/livestream/mockup_main_screen.png
+```
+
+### Auto-Analysis Output:
+```markdown
+🔍 Analyzing livestream_prd.md...
+
+📁 Path Analysis:
+✅ lib/features/livestream/ - Path available
+✅ Integration with home_page.dart - Compatible
+✅ api_service.dart - Can be extended
+
+🔍 Codebase Scan Results:
+Found Similar Features:
+- lib/features/video_player/ - 67% similarity
+- lib/features/chat/ - 45% similarity
+
+Reusable Components:
+✅ lib/shared/widgets/video_controller.dart - Perfect for stream controls
+✅ lib/shared/services/websocket_service.dart - Can handle chat
+❌ Need new: Stream management service
+
+📱 UI Analysis:
+✅ Found: assets/images/livestream/mockup_main_screen.png
+✅ Existing video player patterns can be extended
+✅ Chat UI patterns exist in lib/features/chat/
+
+🚀 Generated Implementation Plan:
+1. Extend existing video_player patterns
+2. Reuse chat UI components  
+3. Create new stream management service
+4. Integrate with existing navigation
+
+Ready for development! 
+```
+
+## Configuration
+
+Enable in `core-config.yaml`:
+```yaml
+smartAnalysis:
+  enabled: true
+  codebaseAnalysis: true
+  architectConsultation: true
+  uiReferenceProcessing: true
+  reuseOptimization: true
+```
+
+This creates an intelligent system that maximizes code reuse and ensures optimal implementation paths! 🧠✨