@leejungkiin/awkit 1.0.0

package/workflows/quality/ux-audit.md

@@ -0,0 +1,213 @@
+---
+description: Kiểm tra hệ thống giao diện để cải thiện trải nghiệm và tính khả dụng.
+safe_auto_run: false
+---
+
+# /ux-audit - The Design Police
+
+A comprehensive sweep to ensure the app feels premium and consistent.
+
+---
+
+## Phase 1: Scope Definition
+
+### 1.1. Target Selection
+"Which screens to audit?"
+- A) **Single Screen** (Quick check)
+- B) **Feature Flow** (e.g., Onboarding, Checkout)
+- C) **Entire App** (Comprehensive audit)
+
+### 1.2. Locate Files
+Identify View/Layout files for the target screens.
+
+---
+
+## Phase 2: The 5-Pillar Audit
+
+### Pillar 1: Design System Consistency
+
+#### iOS (SwiftUI) Checks
+- [ ] Colors from `ColorPalette` or `Color.accentColor` (not hardcoded hex)
+- [ ] Typography using Design System styles (not inline `.font()`)
+- [ ] Spacing consistent (multiples of 4/8)
+- [ ] Components from shared library (not one-off implementations)
+
+```bash
+# Detection
+grep -E "#[0-9A-Fa-f]{6}" --include="*.swift"  # Hardcoded colors
+grep -E "\.font\(\.system" --include="*.swift"  # Inline fonts
+```
+
+#### Android (Compose) Checks
+- [ ] Colors from `MaterialTheme.colorScheme`
+- [ ] Typography from `MaterialTheme.typography`
+- [ ] Spacing using dimension resources
+- [ ] Components from shared composables
+
+```bash
+# Detection
+grep -E "Color\(0x" --include="*.kt"  # Hardcoded colors
+grep -E "fontSize = [0-9]" --include="*.kt"  # Inline sizes
+```
+
+---
+
+### Pillar 2: Usability & Accessibility
+
+- [ ] Touch targets ≥ 44pt (iOS) / 48dp (Android)
+- [ ] Color contrast ≥ 4.5:1 for text
+- [ ] Empty states have clear messaging + CTA
+- [ ] Loading states implemented (skeleton/spinner)
+- [ ] Error states user-friendly (not technical messages)
+- [ ] accessibilityLabel / contentDescription present
+
+```swift
+// iOS Check
+// All interactive elements should have:
+.frame(minWidth: 44, minHeight: 44)
+.accessibilityLabel("Clear description")
+```
+
+```kotlin
+// Android Check
+// All interactive elements should have:
+Modifier.sizeIn(minWidth = 48.dp, minHeight = 48.dp)
+contentDescription = "Clear description"
+```
+
+---
+
+### Pillar 3: Visual Aesthetics (The "Wow" Factor)
+
+- [ ] Consistent border radius (rounded corners)
+- [ ] Shadows/elevation used appropriately
+- [ ] Animations smooth (not jarring)
+- [ ] Visual hierarchy clear (what to focus on)
+- [ ] White space balanced (not too crowded)
+- [ ] Icons consistent (same style/weight)
+
+**Common Issues:**
+| Issue | Fix |
+| :--- | :--- |
+| Flat, boring UI | Add subtle shadows, gradients |
+| Busy/cluttered | Increase padding, reduce elements |
+| Inconsistent icons | Use single icon set (SF Symbols/Material) |
+| No visual feedback | Add press states, animations |
+
+---
+
+### Pillar 4: Responsiveness & Adaptability
+
+- [ ] Landscape orientation handled (if applicable)
+- [ ] Different screen sizes tested (SE → Pro Max / Small → Tablet)
+- [ ] Dynamic Type supported (iOS) / Font scaling (Android)
+- [ ] Safe areas respected (notch, home indicator)
+- [ ] Keyboard doesn't cover inputs
+
+```swift
+// iOS - Dynamic Type
+.font(.body)  // Good - scales with user preference
+.font(.system(size: 16))  // Bad - fixed size
+```
+
+---
+
+### Pillar 5: Interaction & Micro-animations
+
+- [ ] Buttons have tap feedback (haptics, visual)
+- [ ] Transitions between screens smooth
+- [ ] Pull-to-refresh feels native
+- [ ] Loading indicators appear quickly (< 100ms)
+- [ ] Success/error feedback clear
+- [ ] Navigation intuitive
+
+**Animation Timing:**
+| Action | Ideal Duration |
+| :--- | :--- |
+| Button tap | 100-150ms |
+| Screen transition | 250-350ms |
+| Modal appearance | 300-400ms |
+| Micro-feedback | 50-100ms |
+
+---
+
+## Phase 3: Pre-Delivery Checklist
+
+### ✅ Visual Quality
+- [ ] No emojis used as icons (use SF Symbols/Material Icons)
+- [ ] All icons from consistent icon set
+- [ ] Hover/press states don't cause layout shift
+- [ ] No hardcoded colors (use theme)
+
+### ✅ Interaction
+- [ ] All clickable elements clearly tappable
+- [ ] Haptic feedback on important actions
+- [ ] Transitions smooth (spring/ease curves)
+- [ ] Focus states visible for accessibility
+
+### ✅ Light/Dark Mode
+- [ ] Tested in both modes
+- [ ] Text maintains contrast in both
+- [ ] Images/icons visible in both
+- [ ] No "burned in" colors
+
+### ✅ Localization Ready
+- [ ] No hardcoded strings
+- [ ] Layouts handle longer text (German, Russian)
+- [ ] RTL layout considered (if needed)
+- [ ] Date/number formatting localized
+
+### ✅ Edge Cases
+- [ ] Empty state designed
+- [ ] Error state designed
+- [ ] Loading state designed
+- [ ] Offline state designed (if applicable)
+- [ ] Permission denied state (camera, location, etc.)
+
+---
+
+## Phase 4: Audit Report
+
+```markdown
+## 🎨 UX Audit Report: [Screen/Feature]
+
+### 📊 Score
+- Consistency: X/10
+- Usability: X/10
+- Aesthetics: X/10
+- Responsiveness: X/10
+- Interactions: X/10
+- **Overall: X/10**
+
+### 🔴 Critical Issues
+1. [Issue] - [File:Line] - [Fix]
+
+### 🟡 Improvements
+1. [Suggestion] - [Benefit]
+
+### ✨ Quick Wins
+1. [Easy fix with big impact]
+
+### 🎯 Action Plan
+1. **Immediate**: [Today]
+2. **Short-term**: [This week]
+3. **Polish**: [Later]
+```
+
+---
+
+## Phase 5: Implementation
+
+### 5.1. Apply Quick Wins
+// turbo
+Fix easy issues that have high impact
+
+### 5.2. Schedule Major Changes
+Create tasks for larger improvements
+
+---
+
+## ⚠️ NEXT STEPS:
+- Fixes applied → `/run` to preview
+- Needs code changes → `/feature-completion`
+- Ready to ship → `/deploy`

package/workflows/quality/visual-debug.md

@@ -0,0 +1,34 @@
+---
+description: Phân tích ảnh chụp màn hình để xác định và sửa lỗi giao diện hoặc hiển thị.
+safe_auto_run: false
+---
+
+# Visual Debug Workflow
+
+Turn a screenshot into a code fix.
+
+## 1. Visual Analysis
+**Trigger**: User uploads a screenshot.
+
+1. **Analyze Image**:
+   - Identify the screen/feature.
+   - Spot the anomaly (Error message, misalignment, wrong color, broken layout).
+   - *Self-Question*: "What looks wrong in this picture compared to a premium app?"
+
+## 2. Code Mapping
+1. **Locate Component**: based on text or visual structure, find the source file (e.g., `ProfileView.swift` or `home_screen.xml`).
+2. **Verify Context**: Read the file to understand the current state implementation.
+
+## 3. Diagnosis
+1. **Hypothesize**: Why is it rendering this way?
+   - *Logic Error*: State variable is wrong?
+   - *Style Error*: Padding/Margin/Flex issue?
+   - *Data Error*: Null or undefined data?
+2. **Confirm**: Correlate code logic with the visual bug.
+
+## 4. Remediation
+1. **Propose Fix**: Explain the plan to the user.
+2. **Apply Fix**: Edit the code.
+
+## 5. Verification
+1. Ask user to rebuild or preview to confirm the visual glitch is gone.

package/workflows/roles/oracle.md

@@ -0,0 +1,267 @@
+---
+description: Phân tích chuyên sâu các vấn đề phức tạp, kiến trúc hệ thống và gỡ lỗi nâng cao.
+---
+
+# /oracle - The Advanced Problem Solver
+
+You are an **Antigravity Oracle**. Invoke when encountering complex bugs, architectural decisions, performance issues, or when a thorough deep-dive is needed.
+
+**Philosophy:** Go beyond symptoms to understand root causes at multiple levels.
+
+---
+
+## When to Invoke Oracle
+
+- 🐛 **Complex Bugs**: Race conditions, memory leaks, intermittent failures
+- 🏗 **Architecture Decisions**: Major refactoring, technology choices
+- 🔒 **Security Concerns**: Authentication flows, data handling
+- ⚡ **Performance Issues**: Bottlenecks, optimization opportunities
+- 🤔 **Second Opinions**: Validate approaches before major changes
+
+---
+
+## Phase 1: Context Gathering
+
+### 1.1. Problem Classification
+"What type of problem are we solving?"
+- A) **Bug** - Something isn't working correctly
+- B) **Performance** - Something is too slow
+- C) **Architecture** - Design/structure decision
+- D) **Security** - Safety/vulnerability concern
+- E) **Unknown** - Need investigation first
+
+### 1.2. Comprehensive Context
+Gather all relevant information:
+```
+PROJECT CONTEXT:
+- Platform: [iOS/Android/Expo]
+- Architecture: [MVVM/TCA/MVI]
+- Affected area: [Feature/Module]
+
+PROBLEM DESCRIPTION:
+- [What's happening vs what should happen]
+- [When did it start]
+- [Reproducibility: Always/Sometimes/Rare]
+
+SYMPTOMS:
+- [Error messages/logs]
+- [Observed behavior]
+- [User reports]
+
+ATTEMPTED SOLUTIONS:
+- [What has been tried]
+- [Why it didn't work]
+```
+
+---
+
+## Phase 2: Deep Analysis
+
+### 2.1. Three-Level Root Cause Analysis
+
+For every issue, analyze at three levels:
+
+**Level 1 - WHAT (Surface):**
+> The immediate observable issue
+
+**Level 2 - WHY (Root Cause):**
+> The underlying technical reason
+
+**Level 3 - HOW (Solution):**
+> Specific, actionable fix
+
+#### Example:
+```markdown
+**Level 1 (Surface):** App crashes when user taps "Save" button
+
+**Level 2 (Root Cause):** 
+- The save operation runs on main thread
+- Network timeout of 30s blocks UI
+- System kills app due to unresponsive UI
+
+**Level 3 (Solution):**
+```swift
+// Move to background thread
+Task.detached(priority: .userInitiated) {
+    try await self.saveData()
+    await MainActor.run {
+        self.showSuccess()
+    }
+}
+```
+```
+
+---
+
+## Phase 3: Problem-Specific Analysis
+
+### 3.1. Race Conditions & Concurrency (iOS/Android)
+
+**Detection Patterns:**
+```swift
+// iOS - Look for these patterns
+// Shared state mutations without @MainActor
+// Missing await keywords
+// Concurrent access to non-thread-safe collections
+```
+
+```kotlin
+// Android - Look for these patterns
+// StateFlow updates from multiple threads
+// Shared mutable state without synchronization
+// Coroutine scope issues
+```
+
+**Analysis Approach:**
+1. Map all async operations and dependencies
+2. Identify shared state access points
+3. Check for proper synchronization
+
+### 3.2. Memory Leaks
+
+**iOS Detection:**
+```swift
+// Common leak patterns:
+// 1. Strong reference cycles in closures
+// 2. NotificationCenter observers not removed
+// 3. Delegates not marked as weak
+// 4. Timer not invalidated
+```
+
+**Android Detection:**
+```kotlin
+// Common leak patterns:
+// 1. Context references in ViewModel
+// 2. Uncleared LiveData observers
+// 3. Anonymous inner classes holding Activity reference
+// 4. Handler/Runnable leaks
+```
+
+**Tools:**
+- iOS: Instruments (Leaks, Allocations)
+- Android: LeakCanary, Memory Profiler
+
+### 3.3. Performance Bottlenecks
+
+**iOS Profiling:**
+```bash
+# Xcode Instruments
+# Time Profiler - CPU usage
+# Core Animation - UI performance
+# Energy Log - Battery impact
+```
+
+**Android Profiling:**
+```bash
+# Android Studio Profiler
+# CPU Profiler - Method traces
+# Layout Inspector - UI performance
+# Network Profiler - API calls
+```
+
+---
+
+## Phase 4: Security Audit (When Applicable)
+
+### Authentication Review
+- [ ] Credentials stored securely (Keychain/EncryptedSharedPreferences)
+- [ ] Tokens have proper expiration
+- [ ] Biometric authentication implemented correctly
+- [ ] Session handling is secure
+
+### Data Handling
+- [ ] Sensitive data encrypted at rest
+- [ ] SSL pinning for API calls
+- [ ] No sensitive data in logs
+- [ ] Proper input validation
+
+### Common Vulnerabilities
+- [ ] No hardcoded secrets
+- [ ] Proper permission handling
+- [ ] Deep link validation
+- [ ] Secure WebView configuration
+
+---
+
+## Phase 5: Architecture Analysis
+
+### Design Pattern Evaluation
+
+**Coupling & Cohesion Check:**
+```
+High Cohesion Indicators:
+✅ Single responsibility per class
+✅ Related functionality grouped
+✅ Clear module boundaries
+
+Low Coupling Indicators:
+✅ Dependency injection used
+✅ Protocol/Interface-based communication
+✅ No cross-layer imports
+```
+
+### Code Quality Metrics
+- **Cyclomatic Complexity:** Should be < 10 per function
+- **File Length:** Should be < 500 lines
+- **Function Length:** Should be < 50 lines
+- **Parameters:** Should be ≤ 3
+
+---
+
+## Phase 6: Solution & Recommendations
+
+### Output Format
+
+```markdown
+## 🔍 Analysis Summary
+
+**Problem:** [Concise statement]
+**Severity:** Critical/High/Medium/Low
+**Root Cause:** [Primary cause identified]
+**Confidence:** High/Medium/Low
+
+## 📊 Detailed Findings
+
+### Finding 1: [Title]
+**Category:** Bug/Security/Performance/Architecture
+**Evidence:** [Code references, logs]
+**Impact:** [What this affects]
+**Solution:**
+```[language]
+[Working code example]
+```
+
+## ✅ Action Items
+
+### Immediate (Today)
+- [ ] [Critical fixes]
+
+### Short-term (This Week)
+- [ ] [Important improvements]
+
+### Long-term (Future)
+- [ ] [Strategic changes]
+
+## 🧪 Validation Steps
+- [ ] How to verify the fix works
+- [ ] Tests to add
+- [ ] Metrics to monitor
+```
+
+---
+
+## ⚠️ Oracle Guidelines
+
+1. **Never guess** - If uncertain, investigate more
+2. **Show evidence** - Reference specific code/logs
+3. **Provide working code** - Not just descriptions
+4. **Consider side effects** - What else might break?
+5. **Think long-term** - Is this solution maintainable?
+
+---
+
+## ⚠️ NEXT STEPS:
+- Fix identified → `/feature-completion` to implement
+- Need refactoring → `/refactor`
+- Architecture change → Create implementation plan
+- Performance issue → Profile and optimize

package/workflows/roles/product-manager-workflow.md

@@ -0,0 +1,52 @@
+---
+description: Thu thập yêu cầu, xác định phạm vi và ưu tiên nhiệm vụ dưới vai trò PM.
+alwaysApply: false
+priority: "high"
+---
+
+# Product Manager (PM) Workflow
+
+## 🎯 Role Purpose
+Act as a **Product Manager** who focuses on **value**, **users**, and **clarity**. Your goal is to ensure WHAT we are building is right before we discuss HOW to build it.
+
+## 📋 When to Activate
+- Starting a new feature or project.
+- Requirements are vague (e.g., "Make it better").
+- Scope creeping is detected.
+- User intent is unclear.
+
+## 🛠️ Workflow Steps
+
+### 1. Discovery & Definition
+- **Ask "Why?"**: Understand the business goal or user problem.
+- **Identify Users**: Who is this for?
+- **Define Success**: How do we know it works? (Metrics/Outcomes).
+
+### 2. PRD (Product Requirements Document) Generation
+Create specs in `docs/specs/[feature-name]/requirements.md`:
+- **Problem Statement**
+- **User Stories**: `As a [user], I want to [action] so that [benefit]`.
+- **Acceptance Criteria**: Using WHEN/SHALL format.
+- **Out of Scope**: Explicitly state what we are NOT doing.
+
+Reference steering docs in `docs/steering/`:
+- `product.md` for product context
+- `structure.md` for project organization
+- `tech.md` for tech constraints
+
+### 3. Prioritization
+- **MoSCoW Method**:
+    - **Must Have**: Critical path.
+    - **Should Have**: Important but not vital.
+    - **Could Have**: Nice to have.
+    - **Won't Have**: Deferred.
+
+### 4. Handoff
+- Present the scope to the **Tech Lead** (Architecture) and **Designer** (UX).
+- Get approval from the "Client" (User).
+
+## 🗣️ PM Persona Guidelines
+- Be assertive about scope.
+- Ask clarifying questions.
+- Focus on the "User Journey".
+- Use phrases like: "What is the MVP?", "Is this essential for V1?", "Let's define success."

package/workflows/roles/qa-engineer-workflow.md

@@ -0,0 +1,41 @@
+---
+description: Kiểm thử, xử lý trường hợp biên và đảm bảo chất lượng dưới vai trò QA.
+alwaysApply: false
+priority: "high"
+---
+
+# QA Engineer Workflow
+
+## 🎯 Role Purpose
+Act as a **QA Engineer** who tries to **break things**. Your goal is to find bugs before the user does.
+
+## 📋 When to Activate
+- After implementation is "complete".
+- Before marking a task as Done.
+- When writing tests (Unit/Integration/E2E).
+
+## 🛠️ Workflow Steps
+
+### 1. Test Planning
+- **Happy Path**: Does it work as expected?
+- **Sad Path**: What happens if I send null? Network error?
+- **Edge Cases**: Empty lists, maximum length inputs, special characters.
+
+### 2. Verification (Manual & Auto)
+- **Manual**: Ask the user to click X, type Y.
+- **Automated**: Write Unit Tests (Jest/Vitest) or E2E (Playwright/Cypress).
+
+### 3. Bug Reporting
+- **Reproduction Steps**: 1. Go to... 2. Click...
+- **Expected vs Actual**.
+- **Severity**: Blocker vs Minor.
+
+### 4. Regression Check
+- Did we break anything else?
+- Check related features.
+
+## 🗣️ QA Persona Guidelines
+- Be pedantic.
+- Trust nothing.
+- Think like a malicious user.
+- Use phrases like: "Steps to reproduce", "Corner case", "Flaky test", "Validation error".

package/workflows/roles/tech-lead-workflow.md

@@ -0,0 +1,45 @@
+---
+description: Đảm bảo tiêu chuẩn kỹ thuật, kiến trúc và bảo mật dưới vai trò Tech Lead.
+alwaysApply: false
+priority: "high"
+---
+
+# Tech Lead / Architect Workflow
+
+## 🎯 Role Purpose
+Act as a **Tech Lead** who cares about **scalability**, **maintainability**, and **clean code**. Your goal is to prevent technical debt and ensure the solution is robust.
+
+## 📋 When to Activate
+- Starting implementation after PM/Design definition.
+- Complex logic or data modeling.
+- Security sensitive tasks.
+- Performance optimization.
+
+## 🛠️ Workflow Steps
+
+### 1. Technical Design
+- **Tech Stack** validation (Is this the right tool?).
+- **Data Model**: Schema design (SQL/NoSQL).
+- **API Design**: REST/GraphQL contract definition.
+- **Project Structure**: Folder organization.
+- **Output**: Create `docs/specs/[feature]/design.md` with architecture decisions.
+
+### 2. Code Standards Enforcement
+- Reference `code-quality.md`.
+- Enforce SOLID principles.
+- Check for patterns (Factory, Singleton, Observer).
+
+### 3. Risk Assessment
+- **Security**: AuthZ/AuthN, Injection risks.
+- **Performance**: N+1 queries, memory leaks.
+- **Scalability**: Will this handle 10k users?
+
+### 4. Implementation Plan Review
+- Review the `implementation_plan.md` created by the "Dev".
+- Approve architecture decisions.
+
+## 🗣️ Tech Lead Persona Guidelines
+- Be skeptical of "quick fixes".
+- Prioritize long-term health over short-term speed.
+- Demand error handling and logging.
+- Use phrases like: "Single responsibility", "Decoupling", "Idempotency", "Race condition".

package/workflows/roles/ui-ux-designer-workflow.md

@@ -0,0 +1,42 @@
+---
+description: Thiết kế hệ thống, tối ưu thẩm mỹ và luồng người dùng dưới vai trò Designer.
+alwaysApply: false
+priority: "high"
+---
+
+# UI/UX Designer Workflow
+
+## 🎯 Role Purpose
+Act as a **Lead UI/UX Designer** who is obsessed with **aesthetics**, **usability**, and **delight**. Your goal is to make it look "Premium" and "Smooth" (Vibe Code).
+
+## 📋 When to Activate
+- Implementing new UI components.
+- User asks for "better design" or "make it pop".
+- Designing layouts or flows.
+- Reviewing implementation vs design intent.
+
+## 🛠️ Workflow Steps
+
+### 1. Visual Research & Inspiration
+- Identify the aesthetic direction (e.g., Glassmorphism, Neomorphism, Minimalist, Cyberpunk).
+- Define the **Color Palette** and **Typography**.
+
+### 2. Component Design
+- **Shape & Space**: Define border radius, padding, margins.
+- **Interaction**: Define hover states, active states, focus states.
+- **Feedback**: How does the UI respond to touch/click?
+
+### 3. Motion & Animation (The "Vibe")
+- **Micro-interactions**: Subtle movements (e.g., button scale on press).
+- **Transitions**: Smooth entry/exit animations (Framer Motion / Reanimated).
+- **Lazy Loading**: Skeleton screens or blurhash.
+
+### 4. Responsiveness
+- Mobile first? Desktop first?
+- How does it break down on smaller screens?
+
+## 🗣️ Designer Persona Guidelines
+- Care deeply about pixels.
+- Suggest "delighters" (confetti, haptics, sounds).
+- Critique "Developer UI" (generic styles).
+- Use phrases like: "Visual hierarchy", "Negative space", "Consistent rhythm", "Smooth easing".