@leejungkiin/awkit 1.0.6 → 1.0.8

package/workflows/mobile/reverse-android-build.md

@@ -1,170 +1,210 @@
 ---
-description: 🔨 RE Android Phase 2+3 — Per-feature Blueprint → Implementation → Parity Check
+description: 🔨 RE Android Phase 2+3+4 — Blueprint + UI Shell → Logic Build → Final Parity (UI-First)
 parent: reverse-android
 ---
 
-# /re-android-build — Blueprint & Build (Per Feature)
+# /re-android-build — Blueprint + UI + Build (Per Feature)
 
-> **Parent:** [`/reverse-android`](reverse-android.md) → Phase 2+3
+> **Parent:** [`/reverse-android`](reverse-android.md) → Phase 2+3+4
 > **Prerequisite:** Completed Architecture from [`/re-android-design`](reverse-android-design.md)
-> **Skill:** `smali-to-kotlin` → `phase-2-blueprint.md` + `phase-3-build.md`
+> **Skill:** `smali-to-kotlin` → `phase-2-blueprint-ui.md` + `phase-3-logic-build.md`
 
 ---
 
-## 🔄 Feature Loop
+## 🔄 Feature Loop (UI-First)
 
 ```
 For each feature (from Architecture Build Order):
-    Phase 2: Blueprint (Zoom 2 — signatures only)
-        ↓ [User approves]
-    Phase 3: Implementation (Zoom 3 — full code)
-        ↓ [Checkpoint]
+    Phase 2: Blueprint + UI (contracts + visual shell)
+        ↓ 🚦 GATE: User approves UI + contracts
+    Phase 3: Logic Build (domain → data → wire)
+        ↓ 📊 CHECKPOINT
     → Next feature
 ```
 
 ---
 
-## 📐 Phase 2: Feature Blueprint (Zoom 2)
+## 📐🎨 Phase 2: Blueprint + UI Design
 
-> **Output:** Contracts, interfaces, state design. **Signatures only, no bodies.**
+> **Output:** Approved contracts + Working Compose UI shell with mock data.
 
-### 2.1: Deep Smali Reading
+### Part A: Contracts (signatures only)
 
-Read Smali files for the chosen feature. Extract:
-- Class hierarchy, fields, method signatures
-- String constants (URLs, keys, messages)
-- Control flow → business rules (document, don't code)
-
-### 2.2: Contracts
-
-Define for this feature:
+#### 2.1: Deep Smali Reading
+Read Smali files for the chosen feature. Extract class hierarchy, fields, method signatures,
+string constants, control flow. See `smali-reading-guide.md`.
 
+#### 2.2–2.5: Define Contracts
 ```kotlin
-// Domain Model
-data class [Model](val field1: Type, ...)
+// 2.2 Domain Model
+data class [Model](val field: Type, ...)
 
-// Repository Interface
+// 2.3 Repository Interface
 interface [Feature]Repository {
     suspend fun [method](...): Result<[Type]>
-    fun [stream](): Flow<[Type]>
 }
 
-// API Interface
+// 2.4 API Interface
 interface [Feature]Api {
     @[METHOD]("[endpoint]")
     suspend fun [method](...): [Response]
 }
 
-// UseCase
+// 2.5 UseCase
 class [Action]UseCase(repo: [Feature]Repository) {
     suspend operator fun invoke(...): Result<[Type]> // TODO()
 }
 ```
 
-### 2.3: UI State Design
-
+#### 2.6: UI State Design
 ```kotlin
 data class [Screen]UiState(
     val field: Type = default,
     val isLoading: Boolean = false,
     val error: String? = null
 )
-
 sealed interface [Screen]Event { /* navigation, snackbar */ }
 sealed interface [Screen]Action { /* user interactions */ }
 ```
 
-### 2.4: Wireframe + File List
+### Part B: UI Visual Shell
+
+#### 2.7: Resource Extraction ⭐ (BEFORE UI code!)
+
+```bash
+# Only resources for THIS screen
+grep -o '@drawable/[a-z_]*' [apktool_dir]/res/layout/activity_[screen].xml | sort -u
+grep -o '@color/[a-z_]*' [apktool_dir]/res/layout/activity_[screen].xml | sort -u
+```
 
-ASCII wireframe + list of files to create.
+Copy ONLY needed resources. Verify they compile.
 
-### ✅ Blueprint Gate
+#### 2.8: UI Implementation ⭐ (Visual shell with mock data)
 
+- Use UiState from 2.6 with hardcoded defaults
+- Use REAL resources from 2.7
+- Create `[Screen]Content` composable (stateless)
+- Match visual parity with original app
+- NO ViewModel connection, NO real API calls
+
+```kotlin
+@Composable
+fun [Screen]Content(
+    uiState: [Screen]UiState = [Screen]UiState(),  // Mock
+    onAction: ([Screen]Action) -> Unit = {}          // No-op
+) {
+    // Full Compose UI matching original app
+}
+
+@Preview @Composable
+private fun NormalPreview() { AppTheme { [Screen]Content() } }
+
+@Preview @Composable
+private fun LoadingPreview() { AppTheme { [Screen]Content([Screen]UiState(isLoading = true)) } }
+
+@Preview @Composable
+private fun ErrorPreview() { AppTheme { [Screen]Content([Screen]UiState(error = "Error")) } }
 ```
-"📐 Blueprint cho [Feature] xong. Anh xem OK không? → Em bắt đầu code."
+
+#### 2.9: Visual Parity Check ⭐
+
+Compare with original app:
+- [ ] Layout structure matches
+- [ ] Colors, typography, spacing correct
+- [ ] Icons/images positioned correctly
+- [ ] All states: normal, loading, error, empty
+
+### 🚦 UI + Contracts Gate (MANDATORY)
+
+```
+"📐🎨 Blueprint + UI cho [Feature] xong:
+📝 Contracts: [N] models, [N] repos, [N] use cases, [N] APIs
+🎨 UI: [Screen] with [N] state previews
+📸 Visual Parity: [OK / needs adjustment]
+
+→ ✅ Approve → Phase 3 (Logic Build)
+→ 🎨 Adjust UI → fix then re-check
+→ 📝 Adjust contracts → revise"
 ```
 
+> ⚠️ **DO NOT proceed to Phase 3 without user approval.**
+
 ---
 
-## 🔨 Phase 3: Implementation (Zoom 3)
+## 🔨 Phase 3: Logic Build
 
-> **Output:** Full production-quality Kotlin code for THIS feature only.
+> **Output:** Full production-quality Kotlin code. Wire logic to EXISTING UI.
 
 ### 3.1: Domain Layer
-
-- Models (data classes from Blueprint)
-- Repository interfaces (from Blueprint)
-- UseCases (implement invoke with repo calls)
+Models + Repository interfaces + UseCases (implement invoke with repo calls)
 
 ### 3.2: Data Layer
-
-- DTOs (@Serializable)
-- Retrofit API interface
-- Room entities + DAOs (if applicable)
-- Repository implementation (offline-first)
+DTOs + Retrofit API + Room (if applicable) + Repository implementation
 
 ### 3.3: DI Module
-
-- Hilt @Module with @Binds for repository
+Hilt @Module with @Binds for repository
 
 ### 3.4: ViewModel
+@HiltViewModel with StateFlow + SharedFlow, implements onAction()
 
-- @HiltViewModel with StateFlow + SharedFlow
-- Implement onAction() handler from Blueprint actions
-
-### 3.5: Compose Screen
+### 3.5: Wire UI ↔ Logic ⭐ (NOT "code new UI")
 
-- Collect state with collectAsStateWithLifecycle()
-- UI from wireframe
-- LaunchedEffect for events
+The UI already exists from Phase 2.8. Only CONNECT it:
 
-### 3.6: Resource Extraction (On-Demand only)
-
-```bash
-# Only resources for THIS screen
-grep -o '@drawable/[a-z_]*' [apktool_dir]/res/layout/activity_[screen].xml | sort -u
+```kotlin
+// Keep stateless Content composable from Phase 2 (for Preview):
+// [Screen]Content(uiState, onAction) — DO NOT MODIFY
+
+// ADD wrapper that wires ViewModel:
+@Composable
+fun [Screen](
+    viewModel: [Screen]ViewModel = hiltViewModel(),
+    onNavigate: () -> Unit
+) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+    LaunchedEffect(Unit) {
+        viewModel.events.collect { event -> /* handle navigation */ }
+    }
+    [Screen]Content(uiState = uiState, onAction = viewModel::onAction)
+}
 ```
 
-### 🔒 Crypto Utils (Special)
+### 3.6: Integration Test ⭐
+- [ ] API calls succeed, data displays
+- [ ] Loading/error states work
+- [ ] Navigation correct
+- [ ] Crypto output matches (if applicable)
 
-If feature involves crypto/hashing:
-1. Read Smali carefully (exact algorithm)
-2. Implement in Kotlin
-3. Unit test IMMEDIATELY with known pairs
-
-> ⚠️ Crypto MUST produce identical output to original app.
+### 🔒 Crypto Utils (Special)
+If crypto involved: implement + unit test IMMEDIATELY with known pairs.
+> ⚠️ MUST produce identical output.
 
 ### ✅ Feature Checkpoint
 
 ```markdown
 ## ✅ Feature Complete: [Name]
-
-### Files created: [list]
-### Resources extracted: [only needed]
-### Tests: [crypto verified? API matches?]
-
-### ⏭️ Next Feature: [Name]
-→ Return to Phase 2 (Blueprint) for next feature
+Files: [list] | Resources: [count] | Tests: [status]
+⏭️ Next Feature: [Name] → Return to Phase 2
 ```
 
 ---
 
-## ✅ Final Parity Check (After ALL features)
+## ✅ Phase 4: Final Parity Check (After ALL features)
 
 ### Checklist
 - [ ] API Parity — all endpoints match (headers, body, encoding)
 - [ ] Data Parity — crypto/hash output identical
 - [ ] UI Parity — screen-by-screen comparison
 - [ ] Edge Cases — empty states, errors, offline, lifecycle
-- [ ] Build & Test: `./gradlew assembleDebug && ./gradlew test && ./gradlew lint`
+- [ ] Build: `./gradlew assembleDebug && ./gradlew test && ./gradlew lint`
 
 ### 🎉 Final Summary
 
 ```markdown
 ## ✅ Reverse Engineering Complete!
-- Screens: [count] | Features: [count]
-- Libs reused: [count] | Replaced: [count]
-- Tests: [pass/fail] | Lint: [pass/warnings]
+- Screens: [N] | Features: [N]
+- Libs reused: [N] | Replaced: [N]
+- Tests: [pass/fail] | Lint: [warnings]
 
 ⏭️ Next: /test → /deploy → /code-janitor
 ```
@@ -175,8 +215,8 @@ If feature involves crypto/hashing:
 
 - **Parent:** [`/reverse-android`](reverse-android.md)
 - **Previous:** [`/re-android-design`](reverse-android-design.md) (Phase 1)
-- **Skill:** `smali-to-kotlin` → `phase-2-blueprint.md` + `phase-3-build.md`
+- **Skill:** `smali-to-kotlin` → `phase-2-blueprint-ui.md` + `phase-3-logic-build.md`
 
 ---
 
-*re-android-build v3.0.0 — Phase 2+3: Blueprint & Build*
+*re-android-build v4.0.0 — UI-First Blueprint + Build*

package/workflows/mobile/reverse-android-design.md

@@ -84,16 +84,19 @@ app/src/main/java/[package]/
 └── util/
 ```
 
-## 🔢 Step 6: Build Order
+## 🔢 Step 6: Build Order (UI-First) ⭐
 
 | # | Phase | Scope | Complexity |
 |---|-------|-------|-----------|
-| 1 | 🟢 Setup | Project + DI + Theme | Low |
-| 2 | 🟢 Models | Domain data classes | Low |
-| 3 | 🟡 Data | API + Room + DataStore | Medium |
-| 4 | 🟡 Utils | Crypto, formatters | Medium |
-| 5 | 🔴 Features | Per-feature Blueprint→Build | High |
-| N | 🔴 Final | Parity check | High |
+| 1 | 🟢 Foundation | Project + DI skeleton + Theme/Design System | Low |
+| 2 | 🟢 Navigation | Routes, tab bar, NavGraph | Low |
+| 3 | 🔵 Per Feature | Blueprint (contracts) + UI Shell (visual) | Medium |
+| 4 | 🚦 UI Gate | User approves UI before logic | — |
+| 5 | 🟡 Per Feature | Logic Build (Domain → Data → VM → Wire UI) | High |
+| 6 | 📦 SDKs | Third-party SDK + Native libs integration | Medium |
+| N | 🔴 Final | Full Parity Check | High |
+
+> **UI-First:** Design and approve UI before coding logic for each feature.
 
 ## 🔧 Step 7: Tech Stack Confirmation
 

package/workflows/mobile/reverse-android.md

@@ -1,20 +1,20 @@
 ---
-description: 🔧 Dịch ngược APK Android (Apktool output) → App Kotlin hiện đại với Jetpack Compose, Clean Architecture. Progressive Disclosure: Map → Blueprint → Build.
+description: 🔧 Dịch ngược APK Android (Apktool output) → App Kotlin hiện đại với Jetpack Compose, Clean Architecture, và UI-First methodology.
 skill: smali-to-kotlin
 ---
 
 # /reverse-android — Android APK Reverse Engineering Workflow
 
 > **Skill:** `smali-to-kotlin` v2.0 | **Tech:** Kotlin + Compose + Hilt + Retrofit + Room
-> **Philosophy:** "Treat decompiled code as a MAP, not a TODO list"
-> **Approach:** Map → Blueprint → Build (progressive disclosure)
+> **Philosophy:** "Map → Blueprint → UI First → Logic Behind"
+> **Key:** UI is designed and approved BEFORE coding any business logic.
 
 ---
 
 ## ⚡ QUICK START
 
 User cung cấp: Apktool output dir, `AndroidManifest.xml`, hoặc nói "reverse engineer APK này".
-Workflow dẫn dắt qua **4 phases** — mỗi phase có zoom level riêng, **không bao giờ nhảy cóc**.
+Workflow dẫn dắt qua **5 phases** — UI-First approach, **không bao giờ nhảy cóc**.
 
 ---
 
@@ -27,10 +27,11 @@ reverse_session:
   project_name: "[TBD - từ manifest]"
   apktool_dir: "[path]"
   current_phase: 0
-  current_zoom: 0       # 0=satellite, 1=district, 2=block, 3=ground
-  current_feature: null  # set khi user chọn feature ở Phase 2
-  app_map_done: false
-  architecture_done: false
+  current_feature: null
+  phase_2_status:
+    contracts: pending
+    ui_shell: pending
+    resources: pending
   completed_features: []
   pending_features: []
   decisions: []
@@ -39,7 +40,7 @@ reverse_session:
 ### Bước 0.2: Xác nhận input
 
 ```
-🔧 Android Reverse Engineering v2.0 — Map → Blueprint → Build
+🔧 Android Reverse Engineering v2.0 — UI-First Pipeline
 
 Em cần biết:
 1. Thư mục Apktool output ở đâu?
@@ -50,14 +51,15 @@ Chưa chạy Apktool? → apktool d your-app.apk -o ./decompiled/
 
 ---
 
-## 📋 Pipeline Overview (4 Phases)
+## 📋 Pipeline Overview (5 Phases — UI-First)
 
-| Phase | Name | Sub-workflow | Zoom | Code? | Gate |
-|-------|------|-------------|------|-------|------|
-| 0 | 🗺️ Discovery | [`/re-android-discover`](reverse-android-discover.md) | Satellite | ❌ | User approves Map |
-| 1 | 🏗️ Architecture | [`/re-android-design`](reverse-android-design.md) | District | ❌ | User approves Architecture |
-| 2 | 📐 Blueprint | [`/re-android-build`](reverse-android-build.md) | Block | Signatures | Per-feature approval |
-| 3 | 🔨 Implementation | [`/re-android-build`](reverse-android-build.md) | Ground | Full | Per-feature checkpoint |
+| Phase | Name | Sub-workflow | Code? | Gate |
+|-------|------|-------------|-------|------|
+| 0 | 🗺️ Discovery | [`/re-android-discover`](reverse-android-discover.md) | ❌ | User approves Map |
+| 1 | 🏗️ Architecture | [`/re-android-design`](reverse-android-design.md) | ❌ | User approves Architecture |
+| 2 | 📐🎨 Blueprint + UI | [`/re-android-build`](reverse-android-build.md) | UI code | User approves UI + Contracts |
+| 3 | 🔨 Logic Build | [`/re-android-build`](reverse-android-build.md) | Full logic | Feature checkpoint |
+| 4 | ✅ Final Parity | [`/re-android-build`](reverse-android-build.md) | — | Final check |
 
 ### Execution Flow
 
@@ -68,31 +70,34 @@ Phase 0: Discovery (/re-android-discover) → App Map
     ↓ [User approves]
 Phase 1: Architecture (/re-android-design) → Architecture Blueprint
     ↓ [User approves + picks feature]
-Phase 2+3 Loop (/re-android-build):
-    → Blueprint Feature X → Build Feature X → Checkpoint
-    → Blueprint Feature Y → Build Feature Y → Checkpoint
-    → ... (repeat for all features)
+Feature Loop (/re-android-build):
+    Phase 2: Blueprint + UI (contracts + visual shell + resources)
+        ↓ 🚦 GATE: User approves UI + contracts
+    Phase 3: Logic Build (domain → data → DI → VM → wire UI)
+        ↓ 📊 CHECKPOINT: Feature done
+    → Repeat for next feature
     ↓
-Final: Parity Check & Quality Gate
+Phase 4: Final Parity Check & Quality Gate
 ```
 
 ---
 
 ## 🔭 ZOOM CONTROL
 
-AI phải tự check **TRƯỚC MỖI output**:
-
 ```yaml
 pre_output_check:
-  - "Đang ở zoom level nào? (0/1/2/3)"
-  - "Output có đúng zoom level không?"
-  - "Có function body trong Phase 0/1 không? → REMOVE"
-
-zoom_rules:
-  zoom_0: "NO CODE. Only diagrams, tables, maps."
-  zoom_1: "NO CODE BODIES. Only architecture diagrams, file lists."
-  zoom_2: "SIGNATURES ONLY. Interfaces, data classes, sealed classes."
-  zoom_3: "FULL CODE. Implementation for ONE feature at a time."
+  - "Đang ở phase nào?"
+  - "Output có đúng phase rule không?"
+  - "Phase 0/1: NO CODE BODIES"
+  - "Phase 2: UI code + signatures (no logic bodies)"
+  - "Phase 3: Full implementation code"
+
+phase_rules:
+  phase_0: "NO CODE. Only diagrams, tables, maps."
+  phase_1: "NO CODE BODIES. Only architecture diagrams, file lists."
+  phase_2_contracts: "SIGNATURES ONLY. Interfaces, data classes, sealed classes."
+  phase_2_ui: "FULL UI CODE. Compose with hardcoded mock data + @Preview."
+  phase_3: "FULL LOGIC CODE. Domain → Data → DI → VM → Wire UI."
 ```
 
 ---
@@ -101,23 +106,24 @@ zoom_rules:
 
 ```yaml
 never_skip:
-  - Phase 0 (Discovery) — always first, MUST create App Map
-  - Phase 1 (Architecture) — MUST design before coding
-  - User approval at each phase gate
-  - Per-feature Blueprint before Implementation
+  - Phase 0 (Discovery) — always first
+  - Phase 1 (Architecture) — design before coding
+  - Phase 2 UI Gate — user MUST approve UI before Phase 3
+  - Per-feature Blueprint before Logic Build
 
 never_do:
-  - Write code in Phase 0 or Phase 1
+  - Write logic code before UI is approved
   - Mass-copy resources from APK (on-demand only)
   - Implement multiple features simultaneously
-  - Skip parity check for crypto utils
+  - Modify UI significantly in Phase 3 (only wire, don't redesign)
+  - Skip crypto parity check
 
 always_do:
-  - Start with App Map (Phase 0)
-  - Present Architecture for review (Phase 1)
-  - Create Blueprint before coding each feature (Phase 2)
-  - Checkpoint after each feature (Phase 3)
-  - Document all decisions in session state
+  - Extract resources BEFORE coding UI (Phase 2.7 → 2.8)
+  - Create @Preview for ALL states
+  - Keep stateless composable (LoginScreenContent) after wiring
+  - Checkpoint after each feature
+  - Document all decisions
 ```
 
 ---
@@ -127,11 +133,11 @@ always_do:
 - **Sub-workflows:**
   - [`/re-android-discover`](reverse-android-discover.md) — Phase 0: Discovery
   - [`/re-android-design`](reverse-android-design.md) — Phase 1: Architecture
-  - [`/re-android-build`](reverse-android-build.md) — Phase 2+3: Blueprint + Build
-- **Skill:** `smali-to-kotlin` v2.0 (core knowledge & rules)
+  - [`/re-android-build`](reverse-android-build.md) — Phase 2+3+4: Blueprint + UI + Build
+- **Skill:** `smali-to-kotlin` v2.0 (UI-First pipeline)
 - **Sibling:** `/reverse-ios` (iOS counterpart)
 - **After RE done:** `/test`, `/deploy`, `/code-janitor`
 
 ---
 
-*reverse-android workflow v3.0.0 — Progressive Disclosure RE Pipeline*
+*reverse-android workflow v4.0.0 — UI-First RE Pipeline*