@leejungkiin/awkit 1.0.0

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 + Beads)
+
+> **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 Beads để xử lý sau
+3️⃣ 📝 Xem báo cáo đầy đủ
+4️⃣ 🔍 Phân tích sâu hơn (`/ads-analyst`)
+```
+
+### Phase 5: Beads Integration
+- Nếu chọn **2 (Create Task)**:
+    - AI tự động tạo các tasks:
+        - `bd create "Pause Keyword X (Waste 200k)" --label ads`
+        - `bd create "Review Campaign Y (CPA too high)" --label ads`
+
+---
+
+## 🔍 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 Beads Task hướng dẫn chi tiết.**
+
+### Phase 4: Beads Integration (Task Generation)
+
+**Tạo Action Plan trong Beads:**
+
+```bash
+# Example: Cut Waste Plan
+bd create "Ads Optimization: Cut Waste [Date]" --priority 1
+bd create "Add 5 Negative Keywords" --parent [ParentID] --note "burn, hack, free,..."
+bd create "Exclude 10 Mobile App Placements" --parent [ParentID]
+
+# Example: Scale Plan
+bd create "Ads Optimization: Scale Up [Date]" --priority 0
+bd create "Increase Budget: Campaign A (+20%)" --parent [ParentID]
+```
+
+---
+
+## 🔍 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 Beads (`/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
+```

package/workflows/ads/adsExpert.md

@@ -0,0 +1,160 @@
+---
+description: ⚡ Tối ưu Ads tự động (Expert Mode)
+---
+
+# WORKFLOW: /adsExpert - Instant Ads Optimization
+
+> **Expert Mode Only:** Tự động Audit & Optimize tài khoản Google Ads. Không hỏi, chỉ làm & báo cáo. Nội dung phản hồi và báo cáo bằng tiếng Việt
+
+---
+
+## Usage
+
+```bash
+/adsExpert [account_id] [--auto-fix]
+```
+
+**Examples:**
+```bash
+/adsExpert 5527743070           # Audit & Report only
+/adsExpert 5527743070 --auto-fix # Pause bad ads/keywords automatically
+```
+
+---
+
+## Execution Flow
+
+### 1. Data Fetching (Auto)
+*Utilizes `mcp-google-ads`*
+
+1.  **Get Currency:** `get_account_currency(customer_id)`
+2.  **Get Performance:**
+    -   `get_campaign_performance(days=1)` (Yesterday)
+    -   `get_campaign_performance(days=7)` (Trend)
+    -   `get_ad_performance(days=30)` (Deep Dive)
+
+### 2. Rule-Based Analysis (Auto)
+
+AI tự động check các rules sau:
+
+| Rule ID | Name | Condition | Severity |
+|---------|------|-----------|----------|
+| R1 | Wasted Spend | Cost > 200k & Conv = 0 | 🔴 Critical |
+| R2 | High CPA | CPA > 2x Account Avg | 🟠 Warning |
+| R3 | Low CTR | CTR < 1.0% (Search) | 🟡 Info |
+| R4 | Limited Budget | Cost ~= Budget | 🟠 Warning |
+| R5 | Good Mover | ROAS > 2.0 | 🟢 Opportunity |
+
+### 3. Execution (Action)
+
+**Without `--auto-fix`:**
+- Tổng hợp lỗi vào Report.
+- Tạo Beads Tasks cho các lỗi R1, R2.
+
+**With `--auto-fix`:**
+- **R1 (Wasted Spend):** Auto-pause Keyword/Ad Group.
+- **R2, R3, R4:** Tạo Beads Task.
+
+### 4. Beads Integration
+
+```bash
+# R1: Wasted Spend -> Critical Task
+bd create "Pause Waste: [Keyword] ($$ Spend, 0 Conv)" --label ads-waste --priority 0
+
+# R2: High CPA -> Investigation Task
+bd create "Investigate High CPA: [Campaign] (CPA: $$)" --label ads-optimize --priority 1
+
+# R5: Good Mover -> Scale Task
+bd create "Scale Up: [Campaign] (ROAS: 2.5)" --label ads-scale --priority 1
+```
+
+### 5. Report Generation
+
+Tạo file: `reports/ads/[date]_expert_audit.md`
+
+```markdown
+# ⚡ Ads Expert Report - [Date]
+
+## 📊 Pulse Check
+- Spend Yesterday: 500,000 VND
+- Conversions: 10 (CPA: 50,000 VND)
+- ROAS: 2.1
+
+## 🚨 Actions Taken (Auto-Fix)
+- Paused Keyword: "free download" (Spent 200k, 0 conv)
+
+## 📿 Beads Tasks Created
+1. [P0] Pause Waste: "cheat codes" (Spent 150k, 0 conv) #123
+2. [P1] Investigate High CPA: "Competitor Campaign" #124
+3. [P1] Scale Up: "Brand Campaign" #125
+
+➡️ **Next:** Review tasks at `/todo`
+```
+
+---
+
+## 📜 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] /adsExpert
+- **Action:** [Mô tả ngắn gọn hành động đã làm, vd: Auto-fix, Report Only]
+- **Target:** [Account ID]
+- **Action Details:** [List các hành động auto-fix đã thực hiện]
+```
+
+**Lưu ý:** Nếu file không tồn tại, hãy tạo mới.
+
+---
+
+## Analysis Logic (Internal)
+
+### Wasted Spend Query (GAQL)
+```sql
+SELECT 
+  campaign.name, 
+  ad_group.name, 
+  keyword_view.resource_name, 
+  metrics.cost_micros, 
+  metrics.conversions 
+FROM keyword_view 
+WHERE 
+  segments.date DURING LAST_30_DAYS 
+  AND metrics.cost_micros > 200000000 
+  AND metrics.conversions = 0
+```
+
+### High CPA Query (GAQL)
+```sql
+SELECT 
+  campaign.name, 
+  metrics.cost_micros, 
+  metrics.conversions,
+  metrics.cost_per_conversion
+FROM campaign 
+WHERE 
+  segments.date DURING LAST_7_DAYS
+  AND metrics.conversions > 0
+ORDER BY metrics.cost_per_conversion DESC
+```
+
+---
+
+## Error Handling
+
+### API Failures
+- `get_campaign_performance` fail -> Retry 3 times.
+- If fail -> Create Task "Check Google Ads Connection" & Exit.
+
+### No Data
+- If Spend = 0 -> "Account inactive. No optimization needed."
+
+---
+
+## ⚠️ NEXT STEPS (Menu):
+```
+1️⃣ Review tasks (`/todo`)
+2️⃣ Chạy Creative Audit (`/ads-creative`)
+3️⃣ Chạy Full Audit (`/ads-audit`)
+```