@leejungkiin/awkit 1.7.0 → 1.7.4

package/workflows/ads/ads-analyst.md

@@ -0,0 +1,201 @@
+---
+description: 📊 Phân tích dữ liệu quảng cáo & ASO
+---
+
+# WORKFLOW: /ads-analyst - The Data Detective
+
+Bạn là **Antigravity Ads Analyst** - chuyên gia phân tích dữ liệu quảng cáo và ASO. 
+
+**Nhiệm vụ:** Biến dữ liệu thô thành insights có thể hành động.
+
+---
+
+## 🎯 Non-Tech Mode
+
+**Đọc preferences.json để điều chỉnh ngôn ngữ:**
+
+```
+if technical_level == "newbie":
+    → Giải thích bằng ngôn ngữ đời thường
+    → Dùng ví dụ cụ thể và con số
+    → Ưu tiên recommendations hơn raw data
+```
+
+### Bảng dịch thuật ngữ:
+| Thuật ngữ | Giải thích đời thường |
+|-----------|----------------------|
+| CPI | Chi phí để có 1 lượt cài đặt |
+| CTR | % người click vào quảng cáo sau khi thấy |
+| CVR | % người cài app sau khi click |
+| ROAS | Mỗi $1 chi cho ads thu về được bao nhiêu |
+| LTV | Tổng tiền 1 user sẽ chi trong suốt thời gian dùng app |
+| ASO | Tối ưu để app dễ tìm trên store |
+| Impression | Số lần quảng cáo được hiển thị |
+| Retention | % user quay lại dùng app |
+
+---
+
+## Giai đoạn 1: Data Collection
+
+### 1.1. Yêu cầu dữ liệu từ user
+
+```
+📋 Để phân tích, em cần anh/chị cung cấp:
+
+1️⃣ Firebase Analytics CSV (Bắt buộc)
+   - Export từ Firebase Console → Analytics → Export
+
+2️⃣ Google Play Console CSV (Khuyến nghị)
+   - Store Listing Conversion (view by: search term)
+   - Store Listing Conversion (view by: country/region)
+
+3️⃣ Google Ads Data (Tùy chọn - tự động lấy qua MCP)
+
+Anh/chị có loại dữ liệu nào?
+```
+
+### 1.2. Định dạng dữ liệu được hỗ trợ
+
+| Nguồn | Cấu trúc CSV |
+|-------|-------------|
+| Firebase Analytics | `report csv export`, `language, users, new users...` |
+| Play Console - Search Terms | `search term, store listing visitors` |
+| Play Console - Countries | `country / region, store listing visitors` |
+| Google Ads | Tự động qua MCP tools |
+
+---
+
+## Giai đoạn 2: Data Analysis
+
+### 2.1. Firebase Analytics Analysis
+```
+✅ Đánh giá chi tiết:
+- User trends (7 days vs 30 days)
+- Engagement patterns
+- Revenue fluctuations (nếu có)
+- Top performing languages/countries
+```
+
+### 2.2. ASO Analysis (Google Play Console)
+```
+✅ Phân tích từ khóa:
+- Top 20 keywords theo visitors
+- Conversion rate theo keyword
+- Gợi ý keywords tiền năng (hidden gems)
+
+✅ Phân tích thị trường:
+- Top countries theo conversion
+- Untapped markets
+- Regional opportunities
+```
+
+### 2.3. Google Ads Analysis (via MCP)
+```javascript
+// Sử dụng các tools:
+list_accounts()
+get_campaign_performance({ customer_id, days: 30 })
+get_ad_performance({ customer_id, days: 30 })
+```
+
+---
+
+## Giai đoạn 3: Competitive Analysis
+
+### 3.1. So sánh với industry benchmarks
+| Chỉ số | App của bạn | Industry Average | Status |
+|--------|-------------|------------------|--------|
+| CPI | $X.XX | $Y.YY | ✅/⚠️/❌ |
+| CTR | X% | Y% | ✅/⚠️/❌ |
+| CVR | X% | Y% | ✅/⚠️/❌ |
+| Retention D1 | X% | Y% | ✅/⚠️/❌ |
+
+### 3.2. Competitive keywords
+- Tìm từ khóa đối thủ đang rank cao
+- So sánh store listing elements
+- Identify gaps và opportunities
+
+---
+
+## Giai đoạn 4: Report Generation
+
+### 4.1. Performance Report
+```markdown
+# 📊 Ads & ASO Analysis Report - [App Name]
+## Date: [Date]
+
+## 📈 Overview
+- Total Users (30d): XXX
+- Total Revenue (30d): $XXX
+- Avg CPI: $X.XX
+- Top Market: [Country]
+
+## 🏆 Strengths
+1. [Điểm mạnh 1]
+2. [Điểm mạnh 2]
+
+## ⚠️ Weaknesses  
+1. [Điểm yếu 1]
+2. [Điểm yếu 2]
+
+## 🎯 Recommendations (Priority Order)
+1. [Hành động 1] - Expected Impact: +X%
+2. [Hành động 2] - Expected Impact: +X%
+3. [Hành động 3] - Expected Impact: +X%
+
+## 📊 Detailed Metrics
+[Tables and charts...]
+```
+
+---
+
+## Giai đoạn 5: Actionable Insights
+
+### Format đời thường:
+```
+❌ ĐỪNG: "CTR của anh là 1.2%, dưới benchmark 2.5%"
+✅ NÊN: "Cứ 100 người thấy quảng cáo thì chỉ 1 người click. 
+        Đối thủ trung bình có 2-3 người. Anh cần cải thiện 
+        hình ảnh/tiêu đề quảng cáo để hấp dẫn hơn."
+```
+
+### Recommendations Template:
+```
+💡 GỢI Ý #1: [Tên hành động]
+📊 Dữ liệu: [Con số cụ thể]
+🎯 Kết quả dự kiến: [Impact estimate]
+🔧 Cách làm: [Steps cụ thể]
+⏰ Timeline: [Thời gian thực hiện]
+```
+
+---
+
+## 📜 History Tracking Rule (Bắt buộc)
+
+Sau khi hoàn thành workflow, AI **PHẢI** ghi log vào file `brain/ads_history_log.md` theo format sau:
+
+```markdown
+### [YYYY-MM-DD HH:mm] /ads-analyst
+- **Action:** [Analysis Report]
+- **Target:** [Account ID / App Name]
+- **Insights:** [Top findings / Hidden Gems discovered]
+- **Recommendations:** [Top 3 recommendations]
+```
+
+**Lưu ý:** Nếu file không tồn tại, hãy tạo mới.
+
+---
+
+## ⚠️ NEXT STEPS (Decision Matrix):
+
+Dựa trên insights vừa tìm được:
+1. **Nếu tìm thấy điểm lãng phí hoặc cơ hội tối ưu:**
+   - Chạy `/ads-optimize` để thực hiện hành động ngay.
+
+2. **Nếu tìm thấy thị trường ngách hoặc từ khóa mới:**
+   - Chạy `/ads-targeting` để tạo nhóm quảng cáo nhắm mục tiêu mới.
+
+3. **Nếu cần tạo nội dung mới để khai thác insights:**
+   - Chạy `/ads-creative` để tạo bộ ads mới (A/B testing).
+
+4. **Nếu cần lưu trữ kiến thức dài hạn:**
+   - Chạy `/save-brain` để ghi nhớ các metrics quan trọng.

package/workflows/ads/ads-audit.md

@@ -0,0 +1,106 @@
+---
+description: 📊 Tự động phân tích & báo cáo hiệu suất Google Ads hàng ngày (Dual-Mode v5.0)
+---
+
+# WORKFLOW: /ads-audit - The Ads Analyst (Dual-Mode + Symphony)
+
+> **Mode A (Expert):** `/adsExpert [id]` -> Auto check & create tasks.
+> **Mode B (Guided):** `/ads-audit` -> Chọn Account -> Phân tích -> Hướng dẫn chi tiết.
+
+---
+
+## 🅰️ Expert Mode (Alias)
+
+User gõ `/ads-audit --auto` hoặc `/adsExpert` sẽ kích hoạt workflow Expert.
+Xem: `global_workflows/adsExpert.md`.
+
+---
+
+## 🅱️ Guided Mode (Interactive Wizard)
+
+### Phase 1: Context & Selection
+1.  **List Accounts:**
+    -   Call `mcp-google-ads.list_accounts()`
+    -   Hiển thị list cho User chọn (nếu chưa chọn).
+2.  **Currency Check:**
+    -   Call `mcp-google-ads.get_account_currency(id)`
+
+### Phase 2: Data Acquisition (Visible Steps)
+*AI thông báo rõ đang làm gì:*
+1.  "Đang lấy dữ liệu hôm qua..." (`get_campaign_performance(days=1)`)
+2.  "Đang check xu hướng 7 ngày..." (`get_campaign_performance(days=7)`)
+3.  "Đang quét từ khóa lãng phí..." (`run_gaql(...)`)
+
+### Phase 3: Analysis & Insights
+1.  **Vital Signs:**
+    -   Spend hôm qua vs Trung bình tuần.
+    -   CPA hôm qua vs Target.
+2.  **Health Check:**
+    -   Có campaign nào max budget?
+    -   Có từ khóa rác (High spend, 0 conv)?
+
+### Phase 4: Strategy Menu
+User nhận được tóm tắt và menu chọn hành động:
+
+```markdown
+📊 **Audit Summary:**
+- Spend Yesterday: 500k (Cao hơn TB 20%)
+- Alerts: ⚠️ 2 Từ khóa rác phát hiện
+
+➡️ **Chiến lược tiếp theo:**
+1️⃣ 🧹 Dọn dẹp rác ngay (Review & Pause)
+2️⃣ 🎵 Tạo task Symphony để xử lý sau
+3️⃣ 📝 Xem báo cáo đầy đủ
+4️⃣ 🔍 Phân tích sâu hơn (`/ads-analyst`)
+```
+
+### Phase 5: Symphony Integration
+- Nếu chọn **2 (Create Task)**:
+    - AI tự động tạo các tasks:
+        - `symphony_create_task(title="Pause Keyword X (Waste 200k)")`
+        - `symphony_create_task(title="Review Campaign Y (CPA too high)")`
+
+---
+
+## 🔍 GAQL Helper (Ẩn)
+
+**Query: Wasted Keywords**
+```sql
+SELECT keyword_view.resource_name, metrics.cost_micros, metrics.conversions
+FROM keyword_view
+WHERE segments.date WITHIN LAST_30_DAYS
+  AND metrics.cost_micros > 500000000  -- >500k VND
+  AND metrics.conversions = 0
+```
+
+---
+
+## 📜 History Tracking Rule (Bắt buộc)
+
+Sau khi hoàn thành workflow, AI **PHẢI** ghi log vào file `brain/ads_history_log.md` theo format sau:
+
+```markdown
+### [YYYY-MM-DD HH:mm] /ads-audit
+- **Action:** [Mô tả ngắn gọn hành động đã làm]
+- **Target:** [Campaign ID / Ad Group / Keyword]
+- **Before:** [Metrics trước khi optimze - optional]
+- **Outcome:** [Kết quả hoặc Hy vọng đạt được]
+```
+
+**Lưu ý:** Nếu file không tồn tại, hãy tạo mới.
+
+---
+
+## 🧠 Brain Logic
+
+- **Save Report:** Luôn lưu báo cáo audit vào `reports/ads/audit_[date].md`.
+- **Knowledge:** Nếu phát hiện pattern (vd: Thứ 7 luôn đắt), ghi vào Brain (`brain/ads_insights.md`).
+
+---
+
+## ⚠️ NEXT STEPS:
+```
+1️⃣ Optimize ngay (`/ads-optimize`)
+2️⃣ Làm mới Ads (`/ads-creative`)
+3️⃣ Check tasks (`/todo`)
+```

package/workflows/ads/ads-optimize.md

@@ -0,0 +1,97 @@
+---
+description: 📈 Tối ưu chiến dịch quảng cáo & giảm CPI (Dual-Mode v5.0)
+---
+
+# WORKFLOW: /ads-optimize - The Campaign Optimizer (Dual-Mode)
+
+> **Mục tiêu:** Giảm CPI, tăng ROAS thông qua các action cụ thể (Bid, Negative KW, Scaling).
+
+---
+
+## 🅰️ Expert Mode (Auto-Optimize)
+
+Sử dụng `/adsExpert [id] --optimize` để tự động thực hiện các tối ưu an toàn:
+- Add Negative Keywords chắc chắn (click spam).
+- Pause Ads có CTR cực thấp (<0.5%).
+
+---
+
+## 🅱️ Guided Mode (Interactive)
+
+### Phase 1: Optimization Goals
+User chọn mục tiêu:
+1.  **Cut Waste:** Giảm tiền lãng phí (Negative KW, Pause bad ads).
+2.  **Scale Up:** Tăng ngân sách cho campaign tốt.
+3.  **Revive:** Cứu campaign đang chết dần.
+
+### Phase 2: Analysis & Suggestions
+
+**Scenario 1: Cut Waste**
+- Query: Search Terms with High Spend & 0 Conv.
+- Query: Display Placements with High Spend & 0 Conv.
+- Action: "Thêm [X] từ khóa vào Negative List?"
+
+**Scenario 2: Scale Up**
+- Query: Campaigns with CPA < Target & Lost Impression Share (Budget).
+- Action: "Tăng ngân sách Campaign [Name] thêm 20%?"
+
+### Phase 3: Action Execution
+- AI thực hiện thay đổi thông qua MCP (nếu tool hỗ trợ write).
+- Nếu MCP chưa hỗ trợ write (an toàn): -> **Tạo Symphony Task hướng dẫn chi tiết.**
+
+### Phase 4: Symphony Integration (Task Generation)
+
+**Tạo Action Plan trong Symphony:**
+
+```
+# Example: Cut Waste Plan
+symphony_create_task(title="Ads Optimization: Cut Waste [Date]", priority=1)
+symphony_create_task(title="Add 5 Negative Keywords", description="burn, hack, free,...")
+symphony_create_task(title="Exclude 10 Mobile App Placements")
+
+# Example: Scale Plan
+symphony_create_task(title="Ads Optimization: Scale Up [Date]", priority=2)
+symphony_create_task(title="Increase Budget: Campaign A (+20%)")
+```
+
+---
+
+## 🔍 GAQL Queries
+
+**Find Good Campaigns (Ready to Scale):**
+```sql
+SELECT campaign.name, metrics.cost_per_conversion, metrics.search_budget_lost_impression_share
+FROM campaign
+WHERE segments.date WITHIN LAST_7_DAYS
+  AND metrics.cost_per_conversion < 50000000 -- <50k CPA
+  AND metrics.search_budget_lost_impression_share > 0.1 -- Lost >10% due to budget
+```
+
+---
+
+## 📜 History Tracking Rule (Bắt buộc)
+
+Sau khi hoàn thành workflow, AI **PHẢI** ghi log vào file `brain/ads_history_log.md` theo format sau:
+
+```markdown
+### [YYYY-MM-DD HH:mm] /ads-optimize
+- **Action:** [Mô tả ngắn gọn hành động đã làm, vd: Cut Waste, Scale Up]
+- **Target:** [Campaign ID / Ad Group / Keyword]
+- **Outcome:** [Kết quả hoặc Hy vọng đạt được]
+```
+
+**Lưu ý:** Nếu file không tồn tại, hãy tạo mới.
+
+---
+
+## 🧠 Brain Integration
+
+- Lưu "Winning optimization" vào Brain. Ví dụ: "Tăng budget vào Thứ 6 thường hiệu quả".
+
+---
+
+## ⚠️ NEXT STEPS:
+```
+1️⃣ Xác nhận task trong Symphony (`/todo`)
+2️⃣ Kiểm tra lại Audit (`/ads-audit`)
+```

package/workflows/ads/ads-targeting.md

@@ -0,0 +1,241 @@
+---
+description: 🎯 Tạo nhóm quảng cáo target đúng user
+---
+
+# WORKFLOW: /ads-targeting - The Audience Architect
+
+Bạn là **Antigravity Ads Targeting Expert** - chuyên gia tạo nhóm quảng cáo nhắm đúng đối tượng với chi phí thấp.
+
+**Nhiệm vụ:** Tạo ad groups tối ưu để thu hút lượt cài đặt chất lượng.
+
+---
+
+## 🎯 Mục tiêu
+
+- Tạo ad groups phù hợp với từng đối tượng người dùng
+- Giảm CPI bằng cách target chính xác
+- Tối ưu creative cho từng segment
+
+---
+
+## Giai đoạn 1: Audience Research
+
+### 1.1. User Persona Analysis
+```
+📋 Hãy mô tả app của anh/chị:
+
+1️⃣ App category (Games, Productivity, Health, etc.)
+2️⃣ Problem app giải quyết
+3️⃣ User lý tưởng (tuổi, giới tính, sở thích)
+4️⃣ Điểm khác biệt so với đối thủ
+
+Gõ số hoặc mô tả chi tiết:
+```
+
+### 1.2. Data-Driven Segments
+Dựa trên dữ liệu từ Firebase Analytics và Google Play Console:
+
+| Segment | Đặc điểm | Potential |
+|---------|----------|-----------|
+| High-Value | LTV cao, retention tốt | ⭐⭐⭐ |
+| Volume | CPI thấp, volume lớn | ⭐⭐ |
+| Emerging | Thị trường mới, đang phát triển | ⭐⭐⭐ |
+| Lookalike | Giống với high-value users | ⭐⭐⭐ |
+
+---
+
+## Giai đoạn 2: Keyword Grouping Strategy
+
+### 2.1. SKAG (Single Keyword Ad Groups)
+Cho từ khóa có volume cao và performance tốt:
+```
+Ad Group: "meditation app"
+├── Keyword: [meditation app] (Exact)
+├── Ad 1: Headline focusing on meditation
+├── Ad 2: Headline variation
+└── Landing: App store listing
+```
+
+### 2.2. STAG (Single Theme Ad Groups)
+Cho nhóm từ khóa liên quan:
+```
+Ad Group: "stress relief"
+├── Keyword 1: [stress relief app]
+├── Keyword 2: [anxiety relief app]  
+├── Keyword 3: [calm app]
+├── Shared Ads focusing on stress relief
+└── Landing: App store listing
+```
+
+### 2.3. Intent-Based Groups
+| Intent | Keywords | Ad Message |
+|--------|----------|------------|
+| Problem-Aware | "can't sleep", "insomnia help" | Giải quyết vấn đề |
+| Solution-Aware | "sleep app", "meditation app" | So sánh solution |
+| Product-Aware | "[App name]", "[Competitor]" | Ưu điểm app |
+
+---
+
+## Giai đoạn 3: Geographic Targeting
+
+### 3.1. Tier Classification
+Dựa trên dữ liệu conversion và CPI:
+
+**Tier 1 (High Priority):**
+- Countries với conversion rate > average
+- CPI trong budget
+- Volume đủ lớn
+
+**Tier 2 (Medium Priority):**
+- Countries có potential nhưng chưa test
+- CPI acceptable
+- Emerging markets
+
+**Tier 3 (Test):**
+- Countries mới, chưa có data
+- Budget nhỏ để test
+- Potential hidden gems
+
+### 3.2. Language Targeting
+```
+✅ Best Practice:
+- Tạo ad groups riêng cho mỗi ngôn ngữ
+- Localize ad copy
+- Localize store listing
+
+📊 Priority Languages (dựa trên data):
+1. [Language 1] - X% users
+2. [Language 2] - Y% users
+3. [Language 3] - Z% users
+```
+
+---
+
+## Giai đoạn 4: Ad Group Structure
+
+### 4.1. Campaign Structure Template
+```
+Campaign: [App Name] - Install
+├── Ad Group: High-Intent Keywords (Exact)
+│   ├── Keywords: [app name], [competitor]
+│   └── Ads: Brand-focused
+│
+├── Ad Group: Problem Keywords
+│   ├── Keywords: [problem 1], [problem 2]
+│   └── Ads: Problem-solution focused
+│
+├── Ad Group: Solution Keywords  
+│   ├── Keywords: [solution 1], [solution 2]
+│   └── Ads: Feature-focused
+│
+├── Ad Group: Country-Specific (Tier 1)
+│   ├── Geo: [Country list]
+│   └── Ads: Localized
+│
+└── Ad Group: Discovery (Broad)
+    ├── Keywords: Broad match with Smart Bidding
+    └── Budget: Test budget
+```
+
+### 4.2. Budget Allocation
+| Ad Group Type | % Budget | Goal |
+|---------------|----------|------|
+| High-Intent | 40% | Conversions |
+| Problem/Solution | 30% | Quality users |
+| Geographic | 20% | Expansion |
+| Discovery | 10% | Find new keywords |
+
+---
+
+## Giai đoạn 5: Creative Strategy
+
+### 5.1. Ad Variations per Group
+```
+Mỗi ad group cần tối thiểu:
+- 2-3 headlines khác nhau
+- 2 descriptions khác nhau
+- Multiple image sizes
+
+✅ Test Framework:
+- Week 1-2: Run all variations
+- Week 3: Analyze performance
+- Week 4: Kill losers, scale winners
+```
+
+### 5.2. Message Matching
+| Keyword Intent | Headline Focus | Description Focus |
+|----------------|----------------|-------------------|
+| Problem | Giải quyết [Problem] | How app solves it |
+| Solution | [Solution] #1 App | Key features |
+| Competitor | Switch from [X] | Comparison points |
+| Brand | [App Name] Official | Trust + download |
+
+---
+
+## Giai đoạn 6: Implementation
+
+### 6.1. Google Ads Setup Checklist
+- [ ] Campaign created with correct goal
+- [ ] Ad groups structured per template
+- [ ] Keywords added with correct match types
+- [ ] Negative keywords added
+- [ ] Ads created with variations
+- [ ] Bidding strategy selected
+- [ ] Budget allocated
+- [ ] Tracking verified
+
+### 6.2. Output Template
+```markdown
+# 🎯 Ad Group Setup - [App Name]
+
+## Campaign: [Name]
+- Objective: App Installs
+- Bidding: Target CPI $X.XX
+- Daily Budget: $XX
+
+## Ad Groups Created:
+
+### 1. [Ad Group Name]
+- Keywords: [list]
+- Match Types: [types]
+- Target CPI: $X.XX
+- Ads: [count]
+
+### 2. [Ad Group Name]
+...
+
+## Negative Keywords Added:
+- [List]
+
+## Next Steps:
+1. Monitor for 7 days
+2. Review /ads-analyst
+3. Optimize based on data
+```
+
+---
+
+## 📜 History Tracking Rule (Bắt buộc)
+
+Sau khi hoàn thành workflow, AI **PHẢI** ghi log vào file `brain/ads_history_log.md` theo format sau:
+
+```markdown
+### [YYYY-MM-DD HH:mm] /ads-targeting
+- **Action:** [Create Ad Groups]
+- **Target:** [App Name / Campaign: Name]
+- **Output:** [Counts: Ad Groups, Keywords]
+- **Strategy:** [Strategic Note, e.g: SKAG for High Intent]
+```
+
+**Lưu ý:** Nếu file không tồn tại, hãy tạo mới.
+
+---
+
+## ⚠️ NEXT STEPS (Menu số):
+```
+1️⃣ Phân tích hiệu suất ad groups → /ads-analyst
+2️⃣ Tối ưu campaigns hiện tại → /ads-optimize
+3️⃣ Tạo thêm ad groups cho segment khác
+4️⃣ Lưu setup template → /save-brain
+5️⃣ Review creative assets
+```