@leejungkiin/awkit 1.0.0

package/workflows/ads/smali-ads-native.md

@@ -0,0 +1,382 @@
+---
+description: 📰 Tích hợp Native Ads vào APK mod - Tận dụng library có sẵn
+---
+
+# Smali Native Ads Integration
+
+> **🎯 Mục tiêu**: Tích hợp Native Ads bằng cách tận dụng ads library có sẵn trong APK.
+
+---
+
+## 🔍 Phase 1: Discovery - Tìm Native Ads Library
+
+### 1.1. Scan Pattern-based Search
+
+**Pattern 1: Tìm theo keyword**
+```bash
+# Tìm file chứa "Native"
+find smali* -name "*Native*.smali" | grep -i ad
+
+# Tìm theo nội dung
+find smali* -name "*.smali" | xargs grep -l "NativeAd\|native.*ad"
+```
+
+**Pattern 2: Tìm theo View components**
+```bash
+# Native Ad thường có View custom
+find smali* -name "*AdView*.smali"
+find smali* -name "*NativeView*.smali"
+
+# Hoặc trong layout
+grep -r "NativeAd" res/layout/
+```
+
+**Pattern 3: Google AdMob Native**
+```bash
+# Native Ad từ AdMob SDK
+find smali* -path "*/gms/ads/nativead/*" -type f
+```
+
+### 1.2. Identify Components
+
+**Common structures:**
+- `NativeAd.smali` - Core ad object
+- `NativeAdView.smali` - Container view
+- `NativeAdOptions.smali` - Configuration
+- `MediaView.smali` - Media content view
+- Custom wrappers: `*NativeAdHelper*.smali`
+
+**Document findings:**
+```
+[Native Ads Discovery]
+
+Library Location: smali_classes*/{path}/
+Core Classes:
+- NativeAd: {ClassName}.smali
+- AdView: {ViewClassName}.smali
+- Loader: {LoaderClassName}.smali
+
+View Components:
+- Layout: res/layout/{native_ad_layout}.xml
+- Binding: {package}/databinding/{Binding}.smali (nếu có)
+
+Current Usage:
+- Used in: {Activity/Fragment}.smali
+- Inflated in: {methodName}()
+```
+
+---
+
+## 📦 Phase 2: Understanding Native Ad Structure
+
+### 2.1. Ad Assets Components
+
+**Standard Native Ad có các thành phần:**
+
+| Asset | Purpose | View Type |
+|-------|---------|-----------|
+| **Headline** | Tiêu đề chính | TextView |
+| **Body** | Mô tả | TextView |
+| **Icon** | Logo/Icon | ImageView |
+| **Media** | Ảnh/Video lớn | MediaView |
+| **Call to Action** | Button hành động | Button |
+| **Advertiser** | Tên advertiser | TextView |
+| **Star Rating** | Đánh giá | RatingBar |
+| **Price** | Giá (nếu có) | TextView |
+| **Store** | Store name | TextView |
+
+### 2.2. Analyze Existing Layout
+
+**Tìm layout XML:**
+```bash
+# Tìm layout có Native Ad
+grep -r "NativeAdView\|native.*ad" res/layout/
+
+# Hoặc tìm theo ID
+grep -r "@id/ad_" res/layout/
+```
+
+**Structure thường gặp:**
+```xml
+<com.google.android.gms.ads.nativead.NativeAdView>
+    <ImageView android:id="@+id/ad_app_icon" />
+    <TextView android:id="@+id/ad_headline" />
+    <TextView android:id="@+id/ad_body" />
+    <com.google.android.gms.ads.nativead.MediaView 
+        android:id="@+id/ad_media" />
+    <Button android:id="@+id/ad_call_to_action" />
+</com.google.android.gms.ads.nativead.NativeAdView>
+```
+
+### 2.3. API Pattern Recognition
+
+**Sử dụng jadx để xem pattern:**
+```java
+// Example pattern
+AdLoader adLoader = new AdLoader.Builder(context, "AD_UNIT_ID")
+    .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
+        @Override
+        public void onNativeAdLoaded(NativeAd nativeAd) {
+            // Populate views
+        }
+    })
+    .build();
+    
+adLoader.loadAd(new AdRequest.Builder().build());
+```
+
+---
+
+## 🔧 Phase 3: Integration Strategy
+
+### 3.1. Determine Placement
+
+**Từ `/smali-ads-flow`:**
+- **Onboarding Activity** - Between slides
+- **Other screens** (optional) - List items, feed, etc.
+
+**Layout Strategy:**
+
+**Option A: Inline placement**
+```xml
+<ScrollView>
+    <LinearLayout>
+        <!-- Content -->
+        <TextView .../>
+        
+        <!-- Native Ad Container -->
+        <include layout="@layout/native_ad_layout" />
+        
+        <!-- More content -->
+    </LinearLayout>
+</ScrollView>
+```
+
+**Option B: Overlay placement**
+```xml
+<FrameLayout>
+    <!-- Main content -->
+    <ViewPager .../>
+    
+    <!-- Ad overlay -->
+    <include 
+        layout="@layout/native_ad_layout"
+        android:layout_gravity="bottom" />
+</FrameLayout>
+```
+
+### 3.2. Loading Pattern
+
+**Lifecycle integration:**
+```
+onCreate/onViewCreated:
+  → Initialize AdLoader
+  → Load ad
+
+onNativeAdLoaded:
+  → Populate NativeAdView
+  → Show ad container
+  → Track impression
+
+onDestroy:
+  → Destroy ad
+  → Cleanup resources
+```
+
+### 3.3. View Population
+
+**Generic pattern trong Smali:**
+```
+1. Get ad assets (headline, body, icon, etc.)
+2. Set to corresponding views
+3. Register NativeAdView
+4. Track loaded state
+```
+
+**Implementation**: Xem existing usage trong APK để copy pattern
+
+---
+
+## 🎨 Phase 4: UI Implementation
+
+### 4.1. Layout Creation/Reuse
+
+**Option 1: Reuse existing layout**
+```bash
+# Tìm layout có sẵn
+find res/layout -name "*native*.xml"
+find res/layout -name "*ad*.xml"
+
+# Copy và modify cho use case mới
+cp res/layout/existing_native_ad.xml res/layout/onboarding_native_ad.xml
+```
+
+**Option 2: Create new layout**
+- Design theo style app
+- Include all required ad components
+- Match NativeAdView structure
+
+### 4.2. Styling Considerations
+
+**Tuân thủ AdMob policy:**
+- Phải có "Ad" badge/label
+- Không được misleading
+- CTA button phải rõ ràng
+- Không che khuất nội dung bắt buộc
+
+**Implementation:**
+```xml
+<!-- Ad badge -->
+<TextView
+    android:text="Ad"
+    android:background="@color/ad_badge_bg"
+    .../>
+```
+
+---
+
+## 🔌 Phase 5: Code Injection
+
+### 5.1. Hook Points
+
+**Trong OnboardingActivity:**
+```
+Location: OnboardingActivity.smali
+Method: onCreate() hoặc setupUI()
+
+Actions:
+1. Initialize AdLoader
+2. Load native ad
+3. Setup callback handlers
+```
+
+### 5.2. Injection Pattern
+
+**Generic template:**
+```smali
+# In onCreate or initialization method
+
+# Create AdLoader
+new-instance v0, Lcom/google/android/gms/ads/AdLoader$Builder;
+const-string v1, "{AD_UNIT_ID}"
+invoke-direct {v0, p0, v1}, ...; <init>(...)
+
+# Set native ad listener
+# ... (copy pattern from existing usage)
+
+# Build and load
+invoke-virtual {v0}, ...; build()
+move-result-object v1
+invoke-virtual {v1, ...}, ...; loadAd(...)
+```
+
+### 5.3. Callback Implementation
+
+**Pattern:**
+```smali
+.method private onNativeAdLoaded(Lcom/.../NativeAd;)V
+    # 1. Get ad container view
+    # 2. Populate assets to views
+    # 3. Register ad view
+    # 4. Make container visible
+.end method
+
+.method private onAdFailedToLoad()V
+    # Fallback: hide ad container
+    # Continue without ad
+.end method
+```
+
+---
+
+## ✅ Phase 6: Testing & Validation
+
+### 6.1. Functional Tests
+
+| Test | Expected | Verification |
+|------|----------|--------------|
+| **Load Success** | Ad loads, views populated | Visual check |
+| **All Assets** | Headline, body, media, CTA shown | Check each element |
+| **Click Works** | Clicking opens advertiser page | Test CTA |
+| **Fallback** | No ad = hidden container | Test with no network |
+| **No Memory Leak** | Destroy properly | Monitor memory |
+
+### 6.2. UI/UX Tests
+
+- [ ] Ad không che khuất content quan trọng
+- [ ] "Ad" badge visible
+- [ ] Layout responsive với different screen sizes
+- [ ] Không conflict với app UI
+- [ ] Smooth scroll/transition
+
+### 6.3. Debug Commands
+
+```bash
+# Monitor native ad events
+adb logcat | grep -E "NativeAd|AdLoader|MediaView"
+
+# Test with test ad ID
+# ca-app-pub-3940256099942544/2247696110 (Android Test Native)
+
+# Check view hierarchy
+adb shell uiautomator dump
+adb pull /sdcard/window_dump.xml
+```
+
+---
+
+## 📋 Implementation Checklist
+
+### Discovery
+- [ ] Tìm được native ad library/wrapper
+- [ ] Xác định NativeAd và NativeAdView classes
+- [ ] Tìm được existing layout
+- [ ] Document API usage pattern
+
+### Layout
+- [ ] Có layout cho native ad
+- [ ] Include tất cả required components
+- [ ] Add "Ad" badge
+- [ ] Styling match app design
+
+### Integration
+- [ ] Hook vào OnboardingActivity
+- [ ] Inject AdLoader initialization
+- [ ] Implement onNativeAdLoaded callback
+- [ ] Populate view assets
+
+### Testing
+- [ ] Load ad successfully
+- [ ] All assets display correctly
+- [ ] Click tracking works
+- [ ] Fallback when no ad
+- [ ] No memory leaks
+
+---
+
+## 🔗 Related Resources
+
+### Workflows
+- `/smali-ads-flow` - Main ads flow
+- `/smali-ads-interstitial` - Interstitial ads
+- `/smali-ads-config` - Remote config
+
+### References
+- [AdMob Native Ads Guide](https://developers.google.com/admob/android/native)
+- [Native Ads Policies](https://support.google.com/admob/answer/6329638)
+- [Test Ads](https://developers.google.com/admob/android/test-ads)
+
+---
+
+## 💡 Tips & Best Practices
+
+1. **Reuse existing implementation**: Copy pattern từ native ad có sẵn trong app
+2. **Respect policies**: Luôn có "Ad" badge, không misleading
+3. **Test thoroughly**: Native ad có nhiều assets, test kỹ
+4. **Handle missing assets**: Một số ad không có đủ assets (rating, price)
+5. **Cleanup properly**: Destroy ad trong onDestroy để tránh memory leak
+6. **Responsive design**: Test với nhiều screen sizes
+
+---
+
+**⚠️ Quan trọng**: Native Ads phải tuân thủ strict policies về disclosure và presentation!

package/workflows/context/auto-execution-workflow.md

@@ -0,0 +1,291 @@
+---
+description: ⚡ Auto-execution với verification gates
+---
+
+# UI-First Auto Execution Workflow
+
+## Philosophy: UI-First Spec-Driven Development
+
+**Core Principle**: Build and verify UI first, then implement logic with confidence  
+**Purpose**: Ensure polished UX before investing in complex logic  
+**Benefit**: Reduced rework, better UX, improved code reusability
+
+### Key Benefits
+
+- **User-Centric**: UI validated before logic implementation
+- **Reduced Rework**: UI changes don't affect completed logic
+- **Better Planning**: Logic design informed by confirmed UI
+- **Code Reusability**: Components designed for reuse from start
+- **Quality Focus**: Clear quality gates per phase
+
+## Workflow Phases Overview
+
+```mermaid
+graph TD
+    A[Phase 1: UI] --> B{Verify}
+    B -->|OK| C[Phase 2: UI Test]
+    B -->|No| A
+    C --> D{Pass?}
+    D -->|Yes| E[Phase 3: Logic]
+    D -->|No| A
+    E --> F[Phase 4: Logic Test]
+    F --> G{Pass?}
+    G -->|Yes| H[Phase 5: Integration]
+    G -->|No| E
+    H --> I[Done]
+```
+
+## Phase 1: UI Implementation
+
+### Objectives
+Build complete UI with design specs, animations, responsive design, and reusable components
+
+### Execution Steps
+
+```yaml
+# 1. Spec Analysis
+ui_spec_review:
+  - Read docs/specs/[feature]/design.md
+  - Identify screens, components, UI states
+  - Note animations, transitions, reusable parts
+
+# 2. Component Architecture
+component_structure:
+  - Design hierarchy, shared components
+  - Plan composition, props, UI state management
+
+# 3. Build Sequence
+build_sequence:
+  1. Shared: Buttons, inputs, cards, tokens, layouts
+  2. Feature: Screen layouts, components, custom elements
+  3. Polish: Animations, micro-interactions, responsive, a11y
+
+# 4. Implementation Rules
+implementation_rules:
+  - Use mock data, implement all visual states
+  - Add placeholder handlers, focus on visual perfection
+  - No business logic, API calls, or data persistence yet
+```
+
+### Quality Checklist
+
+- [ ] All screens/states implemented (loading, error, empty, success)
+- [ ] Smooth animations (60fps), responsive design
+- [ ] Accessibility (VoiceOver, Dynamic Type)
+- [ ] Consistent design system, reusable components
+
+## Phase 2: UI Verification Gate
+
+**MANDATORY CHECKPOINT**: User must approve UI before logic
+
+### Verification Process
+
+```yaml
+# 1. Demo Prep
+demo_preparation:
+  - Build app, prepare scenarios
+  - Document limitations (mock data)
+
+# 2. Review Checklist
+review_checklist:
+  Visual: Colors, typography, spacing, icons
+  Interactions: Animations, transitions, touch targets, gestures
+  UX: Navigation, hierarchy, error/loading states
+  Responsive: Devices, orientations, content lengths
+  A11y: VoiceOver, Dynamic Type, contrast
+
+# 3. Feedback
+feedback_format:
+  changes_required: [List, priority, affected screens]
+  approval_status: approved | minor_changes | major_changes
+
+# 4. Decision
+gate_decision:
+  approved/minor_changes: Document → Phase 3
+  major_changes: Document → Phase 1
+```
+
+**Gate Doc**: Create `docs/specs/[feature]/ui-approval.md` with review date, status, feedback, changes, approver, next steps
+
+## Phase 3: UI Testing
+
+### Test Implementation
+
+```yaml
+# Snapshot, Component, Accessibility, Visual Regression Tests
+tests:
+  snapshot: All screens, states, devices, light/dark
+  component: Rendering, props, state, interactions
+  accessibility: VoiceOver, Dynamic Type, contrast, touch sizes
+  visual_regression: Compare designs, detect changes
+```
+
+**Run**: `npm run test:ui` or `./scripts/run-ui-tests.sh`
+
+### Quality Gate
+- [ ] All tests pass (snapshot, component, a11y, visual regression)
+- [ ] No warnings/errors, performance < 16ms render
+
+## Phase 4: Logic Implementation
+
+### Objectives
+Implement business logic, API integration, persistence, error handling, reusability
+
+### Planning & Strategy
+
+```yaml
+# Architecture
+architecture_review:
+  - Review UI, design data flow, state management
+  - Identify reusable logic, design service layer
+
+# Reusability
+reusability_planning:
+  shared: Common patterns → services/utilities
+  feature: Isolated logic, dependency injection, testability
+
+# Implementation
+implementation:
+  1. Service Layer: Interfaces, API clients, repositories, logic, errors
+  2. State: Connect UI, updates, side effects, async
+  3. Integration: Replace mocks, connect handlers, add states/errors/validation
+
+# Build Sequence
+logic_build:
+  1. Core: API clients, repositories, utilities
+  2. Business: Feature logic, transformations, validation
+  3. State: Containers, actions/reducers, side effects
+  4. Integration: Connect UI, replace mocks, errors
+```
+
+### Code Reusability Patterns
+
+**Service Pattern**
+```typescript
+interface DataService<T> {
+  fetch(id: string): Promise<T>
+  create(data: Partial<T>): Promise<T>
+  update(id: string, data: Partial<T>): Promise<T>
+  delete(id: string): Promise<void>
+}
+class UserService implements DataService<User> { /* ... */ }
+```
+
+**Repository Pattern**
+```typescript
+abstract class BaseRepository<T> {
+  abstract fetch(id: string): Promise<T>
+  abstract save(data: T): Promise<void>
+  protected handleError(error: Error): void { /* shared */ }
+}
+class UserRepository extends BaseRepository<User> { /* ... */ }
+```
+
+**Hook Pattern**
+```typescript
+function useDataFetch<T>(fetcher: () => Promise<T>) {
+  const [data, setData] = useState<T | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+  return { data, loading, error, refetch }
+}
+```
+
+### Quality Checklist
+- [ ] Logic, API, persistence complete
+- [ ] Comprehensive error handling
+- [ ] Reusable, composable, testable code
+- [ ] SOLID principles, dependency injection
+
+## Phase 5: Logic Testing
+
+### Test Implementation
+
+```yaml
+tests:
+  unit: Services, logic, transformations, validation (mock deps)
+  integration: API, persistence, state, errors
+  e2e: User flows, real data, errors, edge cases
+```
+
+**Run**: `npm run test:logic|integration|e2e|coverage`
+
+### Quality Gate
+- [ ] Coverage > 80%, all tests pass
+- [ ] E2E for critical flows, no critical bugs
+- [ ] Performance acceptable, errors verified
+
+## Phase 6: Integration & Final Validation
+
+### Integration Steps
+
+```yaml
+integration:
+  final: Remove mocks, connect UI to logic, verify states/errors
+  testing: Run all UI/logic/integration/e2e/performance tests
+  uat: Build RC, prepare scenarios, document issues, schedule UAT
+```
+
+### Final Quality Gate
+- [ ] All tests pass, no critical bugs
+- [ ] Performance, accessibility verified
+- [ ] Documentation complete, user acceptance obtained
+
+## Automation Support
+
+### Task Spec Format
+
+```yaml
+feature_task:
+  id: "feature_001"
+  name: "User Profile"
+  
+  phase_1_ui:
+    components: [{name: "ProfileHeader", type: "component", reusable: true}]
+    states: [loading, error, empty, success]
+    animations: [fade_in, slide_up, spring_bounce]
+  
+  phase_2_verification:
+    demo_scenarios: ["View with data", "loading", "error"]
+    approval_required: true
+  
+  phase_3_ui_testing:
+    test_types: [snapshot, component, accessibility, visual_regression]
+  
+  phase_4_logic:
+    services: [{name: "UserService", reusable: true}]
+    integrations: [{api: "GET /users/:id"}, {storage: "UserDefaults"}]
+  
+  phase_5_logic_testing:
+    test_types: [unit, integration, e2e]
+    coverage_target: 80
+  
+  phase_6_integration:
+    validation: [full_test_suite, performance_check, uat_approval]
+```
+
+### Execution Control
+
+```yaml
+execution_rules:
+  phase_gates:
+    - {phase: ui_implementation, next: ui_verification, auto_proceed: false}
+    - {phase: ui_verification, next: ui_testing, auto_proceed: true, conditions: [approval_status: approved]}
+    - {phase: ui_testing, next: logic_implementation, auto_proceed: true, conditions: [all_tests_pass: true]}
+    - {phase: logic_implementation, next: logic_testing, auto_proceed: true}
+    - {phase: logic_testing, next: integration, auto_proceed: true, conditions: [coverage: ">=80%", all_tests_pass: true]}
+    - {phase: integration, next: complete, auto_proceed: false, conditions: [uat_approved: true]}
+```
+
+## Error Handling
+
+**UI Errors**: Syntax → fix/rebuild | Design → spec review | Component → isolate/fix  
+**UI Rejection**: Document → prioritize → Phase 1 → schedule review  
+**UI Test Fail**: Identify → fix → re-run → update snapshots  
+**Logic Errors**: API → check integration | State → review mgmt | Data → validate transforms  
+**Logic Test Fail**: Fix → improve coverage → re-run  
+**Integration Issues**: Isolate → fix → re-test → validate flow
+
+---
+
+**Success**: Polished UI approved, comprehensive tests, clean reusable code, smooth UI-logic integration