@leejungkiin/awkit 1.1.4 → 1.1.7

package/skills/aso-audit/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: aso-audit
+description: When the user wants a full ASO health audit, review their App Store listing quality, or diagnose why their app isn't ranking. Also use when the user mentions "ASO audit", "ASO score", "why am I not ranking", "listing review", or "optimize my app store page". For keyword-specific research, see keyword-research. For metadata writing, see metadata-optimization.
+metadata:
+  version: 1.0.0
+---
+
+# ASO Audit
+
+You are an expert in App Store Optimization with deep knowledge of Apple's and Google's ranking algorithms. Your goal is to perform a comprehensive ASO health audit and provide a prioritized action plan.
+
+## Initial Assessment
+
+1. Check for `app-marketing-context.md` — read it if available for app context
+2. Ask for the **App ID** (Apple numeric ID or Google Play package name)
+3. Ask for the **target country** (default: US)
+4. Ask which **platform** to audit (iOS / Android / Both)
+
+## Data Collection
+
+If Appeeky MCP or API is available, fetch:
+- App metadata (title, subtitle, description, screenshots, ratings)
+- Current keyword rankings
+- Competitor data (top 3-5 in same category)
+- Category chart position
+- Review sentiment
+
+If not available, ask the user to provide their current metadata.
+
+## Audit Framework
+
+Score each factor on a 0-10 scale. Calculate an overall ASO Score (weighted average).
+
+### 1. Title (Weight: 20%)
+
+| Check | What to look for |
+|-------|-----------------|
+| Keyword presence | Does the title contain the #1 target keyword? |
+| Character usage | Using close to 30 characters? (iOS) |
+| Brand vs keyword balance | Is the brand name necessary, or wasting space? |
+| Readability | Natural reading, not keyword-stuffed? |
+| Uniqueness | Distinct from competitors? |
+
+**Scoring:**
+- 9-10: Primary keyword + brand, natural, full character usage
+- 7-8: Has keyword but room for optimization
+- 4-6: Missing primary keyword or poor balance
+- 0-3: Generic, no keywords, or truncated
+
+### 2. Subtitle (Weight: 15%) — iOS only
+
+| Check | What to look for |
+|-------|-----------------|
+| Keyword presence | Contains secondary keywords not in title? |
+| No repetition | Doesn't repeat title keywords? |
+| Value proposition | Communicates a benefit? |
+| Character usage | Using close to 30 characters? |
+
+### 3. Keyword Field (Weight: 15%) — iOS only
+
+| Check | What to look for |
+|-------|-----------------|
+| No repetition | No keywords repeated from title/subtitle? |
+| No spaces | Commas without spaces? |
+| Singular forms | Using singular (Apple indexes both forms)? |
+| Character usage | Using all 100 characters? |
+| Relevance | All keywords relevant to the app? |
+| No wasted words | No brand names, category names, or "app"? |
+
+### 4. Description (Weight: 5% iOS / 15% Android)
+
+| Check | What to look for |
+|-------|-----------------|
+| First 3 lines | Compelling hook above the fold? |
+| Feature highlights | Clear benefits, not just features? |
+| Keyword density (Android) | Natural keyword usage throughout? |
+| Formatting | Uses line breaks, bullets, or emoji for readability? |
+| Call to action | Ends with a clear CTA? |
+| Social proof | Mentions awards, press, or user count? |
+
+### 5. Screenshots (Weight: 15%)
+
+| Check | What to look for |
+|-------|-----------------|
+| Count | All 10 slots used? |
+| First 3 | Most compelling features shown first? |
+| Text overlays | Clear, readable benefit-driven captions? |
+| Consistency | Cohesive design language? |
+| Localization | Localized for target market? |
+| Device frames | Modern device frames (or frameless)? |
+
+### 6. App Preview Video (Weight: 5%)
+
+| Check | What to look for |
+|-------|-----------------|
+| Exists | Has a preview video? |
+| First 3 seconds | Hook in the first 3 seconds? |
+| Length | 15-30 seconds optimal? |
+| Sound | Works without sound (captions)? |
+
+### 7. Ratings & Reviews (Weight: 15%)
+
+| Check | What to look for |
+|-------|-----------------|
+| Average rating | 4.5+ stars? |
+| Rating count | Sufficient for category? |
+| Recent reviews | Positive trend in last 30 days? |
+| Review responses | Developer responds to negative reviews? |
+| Rating prompts | Strategic in-app rating prompts? |
+
+### 8. Icon (Weight: 5%)
+
+| Check | What to look for |
+|-------|-----------------|
+| Distinctiveness | Stands out in search results? |
+| Simplicity | Clear at small sizes? |
+| Category fit | Matches category expectations? |
+| No text | Avoids text (unreadable at small sizes)? |
+
+### 9. Keyword Rankings (Weight: 10%)
+
+| Check | What to look for |
+|-------|-----------------|
+| Top 10 keywords | Ranking in top 10 for target keywords? |
+| Keyword coverage | Ranking for enough relevant keywords? |
+| Trend | Rankings improving or declining? |
+| Competitor gap | Missing keywords competitors rank for? |
+
+### 10. Conversion Signals (Weight: 5%)
+
+| Check | What to look for |
+|-------|-----------------|
+| Promotional text | Using promotional text for timely messaging? |
+| What's New | Recent, informative update notes? |
+| In-App Events | Using in-app events for visibility? |
+| Custom Product Pages | Multiple product pages for different audiences? |
+
+## Output Format
+
+### ASO Score Card
+
+```
+Overall ASO Score: [X]/100
+
+Title:              [X]/10  ████████░░
+Subtitle:           [X]/10  ██████░░░░
+Keyword Field:      [X]/10  ████░░░░░░
+Description:        [X]/10  ████████░░
+Screenshots:        [X]/10  ██████████
+Preview Video:      [X]/10  ██░░░░░░░░
+Ratings & Reviews:  [X]/10  ████████░░
+Icon:               [X]/10  ████████░░
+Keyword Rankings:   [X]/10  ██████░░░░
+Conversion Signals: [X]/10  ████░░░░░░
+```
+
+### Quick Wins (implement today)
+
+List 3-5 changes that can be made immediately with high impact.
+
+### High-Impact Changes (this week)
+
+List 3-5 changes that require more effort but have significant impact.
+
+### Strategic Recommendations (this month)
+
+List 3-5 longer-term strategic improvements.
+
+### Competitor Comparison
+
+Brief comparison table showing how the app stacks up against top 3 competitors on key metrics.
+
+## Related Skills
+
+- `keyword-research` — Deep dive into keyword opportunities found during audit
+- `metadata-optimization` — Implement the metadata improvements identified
+- `screenshot-optimization` — Redesign screenshots based on audit findings
+- `competitor-analysis` — Detailed competitive analysis
+- `review-management` — Address review issues found in audit

package/skills/code-review/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: code-review
+description: Use when completing tasks, implementing features, or before merging. Dispatch structured code review with severity classification. Auto-triggers after task completion in subagent-driven or single-flow execution.
+---
+
+# Code Review
+
+## Overview
+
+Review early, review often. Catch issues before they cascade.
+
+**Core principle:** Structured review with actionable, severity-classified feedback.
+
+## When to Request Review
+
+**Mandatory:**
+- After completing each task in execution flow
+- After implementing major feature or fix
+- Before merge to main branch
+- Before deploy to production
+
+**Optional but valuable:**
+- When stuck (fresh perspective helps)
+- Before refactoring (baseline check)
+- After fixing complex bug
+
+## The Review Process
+
+### Step 1: Prepare Context
+
+Gather what the reviewer needs:
+
+```bash
+# Get the diff scope
+git diff main..HEAD --stat
+git log main..HEAD --oneline
+
+# OR for specific task
+git diff HEAD~1..HEAD --stat
+```
+
+### Step 2: Construct Review Request
+
+Every review request needs:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| **WHAT** | What was implemented | "Water reminder notification system" |
+| **SPEC** | What it should do | "Send notification every 2h between 8am-10pm" |
+| **FILES** | Changed files | `WaterReminderManager.swift`, `NotificationService.swift` |
+| **SCOPE** | Review focus | "Logic correctness + thread safety" |
+
+### Step 3: Classify Findings
+
+| Severity | Action | Example |
+|----------|--------|---------|
+| 🔴 **Critical** | BLOCK — fix immediately | Thread-unsafe shared state, data loss risk |
+| 🟡 **Important** | Fix before proceeding | Missing error handling, incomplete validation |
+| 🟢 **Minor** | Note for later | Naming convention, code style preference |
+| ℹ️ **Suggestion** | Consider but optional | Performance optimization, alternative approach |
+
+### Step 4: Act on Feedback
+
+1. Fix 🔴 Critical issues IMMEDIATELY
+2. Fix 🟡 Important issues before proceeding to next task
+3. Log 🟢 Minor issues — fix in refactoring pass
+4. Evaluate ℹ️ Suggestions — adopt if clear improvement
+
+## Two-Stage Review (Subagent-Driven)
+
+For automated execution, run TWO separate review passes:
+
+### Stage 1: Spec Compliance Review
+```
+- Does the code implement ALL requirements from the spec/plan?
+- Is anything MISSING from the spec?
+- Is anything EXTRA that wasn't specified (scope creep)?
+- Does behavior match expected output for each requirement?
+```
+
+### Stage 2: Code Quality Review
+```
+- Is the code clean, readable, and well-structured?
+- Are there any thread safety issues?
+- Is error handling comprehensive?
+- Are there performance concerns?
+- Does it follow project coding conventions?
+- Are there any security vulnerabilities?
+```
+
+**Order matters:** Spec compliance FIRST, then code quality. No point reviewing quality of wrong code.
+
+## Self-Review Checklist (Before Requesting External Review)
+
+Before asking for review, verify yourself:
+
+- [ ] All requirements from plan/spec addressed
+- [ ] No TODO/FIXME/HACK left unresolved  
+- [ ] Error handling for all failure paths
+- [ ] No hardcoded values that should be configurable
+- [ ] Thread safety for shared state
+- [ ] Localization for user-facing strings
+- [ ] No print/debugPrint left in production code
+- [ ] File sizes < 500 lines
+
+## Integration
+
+**Used by:**
+- `single-flow-task-execution` — Review after each task
+- `symphony-enforcer` — Review before `symphony_complete_task`
+
+**Related skills:**
+- `verification-gate` — Run tests BEFORE requesting review
+- `systematic-debugging` — If review reveals bugs
+
+## Anti-Rationalization Table
+
+| Excuse | Reality |
+|--------|---------|
+| "It's a small change" | Small changes cause big bugs |
+| "Tests pass so it's correct" | Tests ≠ requirements. Review catches logic gaps |
+| "I'm confident in this code" | Confidence ≠ correctness |
+| "No time for review" | 5 min review saves 2 hours debugging |
+| "I'll review it later" | Later never comes. Review now |
+| "Only I understand this code" | That's exactly why someone else should review |

package/skills/codex-conductor/SKILL.md

@@ -0,0 +1,337 @@
+---
+name: codex-conductor
+description: >-
+  Three-Agent Flow — Antigravity proactively invokes Codex CLI (headless)
+  for debugging, code review, logic verification, and plan auditing.
+  Codex is READ-ONLY: it inspects and reports to .md files, never edits code.
+metadata:
+  stage: core
+  version: "1.0"
+  requires: codex (npm i -g @openai/codex)
+  tags: [conductor, codex, debug, review, logic, verification, delegation]
+agent: Inspector
+trigger: conditional
+invocation-type: auto
+priority: 5
+---
+
+# 🔍 Codex Conductor Skill
+
+> **Purpose:** Antigravity gọi Codex CLI qua terminal khi cần rà soát logic, debug, hoặc review code chuyên sâu.
+> **Key Benefit:** Codex cực mạnh rule compliance + logic analysis. Output = báo cáo `.md`, KHÔNG sửa code.
+
+---
+
+## ⚠️ Core Principle
+
+```
+Antigravity (IDE) = Executor — code, implement, create
+Gemini CLI        = Strategist — analysis, architecture, planning
+Codex CLI         = Inspector — debug, review, verify, test
+
+   ┌──────────────────────────────────────────────┐
+   │  Codex CHỈ RÀ SOÁT + TẠO BÁO CÁO (.md)     │
+   │  TUYỆT ĐỐI KHÔNG ĐƯỢC SỬA CODE              │
+   └──────────────────────────────────────────────┘
+```
+
+---
+
+## 🔧 Prerequisites
+
+Trước khi gọi Codex CLI, kiểm tra:
+
+```bash
+# Check if codex is installed
+which codex || command -v codex
+```
+
+```yaml
+if_not_installed:
+  option_1: "npm i -g @openai/codex"
+  option_2: Ask user to install manually
+  message: "⚠️ Codex CLI chưa cài. Chạy: npm i -g @openai/codex"
+```
+
+---
+
+## 🎯 Trigger Conditions
+
+Kích hoạt khi Antigravity nhận diện task cần thế mạnh Codex:
+
+```yaml
+auto_trigger:
+  high_confidence:
+    - Bug report from user (crash, unexpected behavior)
+    - Pre-commit code review (>3 files changed)
+    - Logic verification (race conditions, edge cases)
+    - Implementation plan review (find holes in plan)
+    - Refactor verification (ensure no regression)
+
+  medium_confidence (confirm before invoking):
+    - Test case generation for new feature
+    - Security audit
+    - Performance bottleneck analysis
+
+  never_trigger:
+    - Simple questions / explanations
+    - UI-only changes (styling, layout)
+    - Documentation edits
+    - Tasks Antigravity can handle alone easily
+```
+
+---
+
+## 🔧 CLI Invocation Pattern
+
+### Mode 1: Quick Analysis (read + stream response)
+
+```bash
+cd <PROJECT_ROOT> && timeout 120 codex \
+  "<PROMPT>. DO NOT edit any files. Output your analysis as text." \
+  --approval-mode suggest \
+  -q 2>/dev/null
+```
+
+| Flag | Purpose |
+|------|---------|
+| `"prompt"` | Single-prompt mode — reads cwd, streams response, exits |
+| `--approval-mode suggest` | Read-only: can browse files, won't make changes |
+| `-q` | Quiet mode — no TUI, output to stdout |
+
+### Mode 2: Deep Inspection (exec with JSON output)
+
+```bash
+cd <PROJECT_ROOT> && timeout 180 codex exec \
+  "<PROMPT>. DO NOT edit any files. Output your findings as structured text." \
+  --json 2>/dev/null
+```
+
+| Flag | Purpose |
+|------|---------|
+| `exec` | Non-interactive scripting mode |
+| `--json` | Structured JSON output for parsing |
+
+### Safety Rules
+
+```yaml
+safety:
+  - Codex TUYỆT ĐỐI KHÔNG ĐƯỢC sửa code. CHỈ đọc + báo cáo.
+  - ALWAYS use --approval-mode suggest (read-only mode).
+  - ALWAYS inject "DO NOT edit any files" in every prompt.
+  - Timeout: 120s for quick analysis, 180s for deep inspection.
+  - If CLI fails → gracefully fallback to Antigravity-only mode.
+  - NEVER pass secrets/tokens in prompt.
+  - Working directory: ALWAYS set to project root.
+  - Output: ALWAYS save to .md report file.
+```
+
+---
+
+## 📋 Use Cases & Prompt Templates
+
+### 1. Bug Root Cause Analysis
+
+```bash
+codex "A bug was reported: <BUG_DESCRIPTION>. \
+Analyze the codebase to find the root cause. \
+List: (1) most likely root cause with file:line, \
+(2) contributing factors, (3) suggested fix approach. \
+DO NOT edit any files." \
+--approval-mode suggest -q
+```
+
+**When:** User reports a bug, crash, or unexpected behavior.
+**Report to:** `codex-reports/bug-analysis-<date>.md`
+
+### 2. Pre-Commit Code Review
+
+```bash
+codex "Review the uncommitted changes in this repo. \
+Check for: bugs, logic errors, edge cases, thread safety, \
+security issues, performance problems, naming inconsistencies. \
+Rank issues by severity (critical/warning/info). \
+DO NOT edit any files." \
+--approval-mode suggest -q
+```
+
+**When:** Before committing changes across >3 files.
+**Report to:** `codex-reports/review-<date>.md`
+
+### 3. Logic & Edge Case Analysis
+
+```bash
+codex "Analyze <FILE_OR_MODULE> for logic correctness. \
+Focus on: edge cases (null, empty, boundary), race conditions, \
+error handling gaps, unreachable code, off-by-one errors. \
+List each issue with file:line and severity. \
+DO NOT edit any files." \
+--approval-mode suggest -q
+```
+
+**When:** Complex logic that needs verification.
+**Report to:** `codex-reports/logic-analysis-<date>.md`
+
+### 4. Test Case Generation
+
+```bash
+codex "Analyze <FILE_OR_MODULE> and generate a comprehensive \
+list of test cases. Include: happy path, edge cases, error cases, \
+boundary values, concurrent scenarios. Format as markdown table. \
+DO NOT edit any files." \
+--approval-mode suggest -q
+```
+
+**When:** New feature needs test coverage planning.
+**Report to:** `codex-reports/test-cases-<date>.md`
+
+### 5. Implementation Plan Review
+
+```bash
+codex "Review this implementation plan: <PLAN_CONTENT>. \
+Find: logic holes, missing error handling, security risks, \
+race conditions, scalability issues, missing edge cases. \
+Rate each issue by severity. \
+DO NOT edit any files." \
+--approval-mode suggest -q
+```
+
+**When:** After Antigravity creates an implementation plan.
+**Report to:** `codex-reports/plan-review-<date>.md`
+
+### 6. Refactor Verification
+
+```bash
+codex "Compare the recent changes in this repo against the \
+original code. Verify: (1) no behavioral regression, \
+(2) all original edge cases still handled, \
+(3) no new bugs introduced. List any regressions found. \
+DO NOT edit any files." \
+--approval-mode suggest -q
+```
+
+**When:** After refactoring to ensure no regression.
+**Report to:** `codex-reports/refactor-verify-<date>.md`
+
+---
+
+## 🔄 Integration Flow
+
+```
+1. Antigravity detects trigger condition
+2. Check Codex CLI: which codex || prompt install
+3. Thông báo user: "🔍 Đang gọi Codex CLI để [mục đích]..."
+4. Build prompt with project context
+5. Run: run_command("cd <ROOT> && timeout 120 codex '<prompt>' --approval-mode suggest -q")
+6. Capture output
+7. Save report to codex-reports/<type>-<date>.md
+8. Summarize key findings for user
+9. Act on findings (Antigravity executes fixes if needed)
+```
+
+### Output Handling
+
+```yaml
+on_success:
+  - Parse Codex output (text or JSON)
+  - Save full report to codex-reports/<type>-<date>.md
+  - Extract key findings + severity
+  - Present summary to user
+  - If critical issues found → suggest fixes
+
+on_timeout:
+  - Log: "⏳ Codex analysis timed out (>120s), proceeding with Antigravity"
+  - Fall back to Antigravity-only analysis
+
+on_error:
+  - Log: "⚠️ Codex CLI invocation failed"
+  - Check: "codex --version" → suggest install if missing
+  - Fall back gracefully — CLI is enhancement, not dependency
+
+on_not_installed:
+  - Ask user: "Codex CLI chưa cài. Cài bằng: npm i -g @openai/codex?"
+  - If yes → run install → retry
+  - If no → fall back to Antigravity-only
+```
+
+---
+
+## 📁 Report Output Structure
+
+```
+<project_root>/
+└── codex-reports/          # Gitignored recommended
+    ├── bug-analysis-2026-03-21.md
+    ├── review-2026-03-21.md
+    ├── logic-analysis-2026-03-21.md
+    ├── test-cases-2026-03-21.md
+    ├── plan-review-2026-03-21.md
+    └── refactor-verify-2026-03-21.md
+```
+
+---
+
+## 🚫 Anti-Patterns
+
+```yaml
+never_do:
+  - Let Codex edit source code (EVER)
+  - Use --approval-mode auto or full-access (ALWAYS use suggest)
+  - Pass sensitive data (API keys, tokens) in prompts
+  - Block on CLI response indefinitely (always use timeout)
+  - Call CLI more than 3 times per task (diminishing returns)
+  - Ignore CLI output — if you called it, use the result
+  - Call Codex for tasks Antigravity handles well alone
+
+always_do:
+  - Mention to user: "🔍 Đang gọi Codex CLI [mục đích]..."
+  - Include "DO NOT edit any files" in EVERY prompt
+  - Use --approval-mode suggest (read-only)
+  - Save reports to codex-reports/ directory
+  - Summarize findings before acting on them
+  - Fall back gracefully if CLI unavailable
+  - Check codex installation before first use
+```
+
+---
+
+## 🤝 Three-Agent Collaboration
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    User Request                          │
+└─────────────┬───────────────────────────────────────────┘
+              │
+              ▼
+    ┌─────────────────┐
+    │   Antigravity    │ ← Primary: plan, code, implement
+    │   (IDE Agent)    │
+    └───┬─────────┬───┘
+        │         │
+   Strategy?   Debug/Review?
+        │         │
+        ▼         ▼
+  ┌──────────┐ ┌──────────┐
+  │ Gemini   │ │ Codex    │
+  │ CLI      │ │ CLI      │
+  │ ────────── │ ────────── │
+  │ Architect │ │ Inspector│
+  │ .md only  │ │ .md only │
+  └──────────┘ └──────────┘
+```
+
+---
+
+## 🧩 Skill Relationships
+
+```
+Uses:      run_command (to invoke codex CLI)
+Enhances:  /debug, /code, /refactor, /plan workflows
+Saves to:  codex-reports/*.md
+Parallel:  gemini-conductor (different role, can coexist)
+Independent of: NeuralMemory (CLI has its own context)
+```
+
+---
+
+*codex-conductor v1.0 — Three-Agent Flow Inspector for Antigravity*