@leejungkiin/awkit 1.7.1 → 1.7.5

package/docs/PRD.md

@@ -0,0 +1,57 @@
+# Product Requirement Document (PRD) - GreetingApp
+
+## Revision History
+| Version | Date | Description | Author |
+|---|---|---|---|
+| v1.0 | 2026-06-22 | Initial PRD for GreetingApp | Antigravity Orchestrator |
+
+---
+
+## 1. Executive Summary
+GreetingApp is a micro-application designed to deliver personalized, localized, and dynamic greetings to users. It adapts to the user's name, current time of day, and language preferences.
+
+## 2. Objectives & Goals
+- Provide dynamic greetings based on user local time (Morning, Afternoon, Evening, Night).
+- Support multi-language greetings (English, Vietnamese, Japanese).
+- Track user greeting history and statistics.
+- Expose both CLI and REST API interfaces.
+
+## 3. User Personas & Use Cases
+- **End User:** Wants to see a welcoming, contextual message when logging in or using the CLI.
+- **Developer:** Wants an easy-to-integrate greeting microservice API for downstream services.
+
+## 4. Functional Requirements
+1. **Dynamic Greeting Generation:**
+   - Detects local time of user.
+   - Personalizes with name (fallback to "Guest").
+2. **Localization (i18n):**
+   - Supports: English (`en`), Vietnamese (`vi`), Japanese (`ja`).
+3. **Greeting Analytics / History:**
+   - Stores logs of generated greetings (User, Timestamp, Language).
+   - Exposes statistics (e.g., total greetings generated, most active user).
+4. **Interfaces:**
+   - Command Line Interface (CLI): `awkit greet --name=Alice`
+   - REST API endpoint: `GET /api/greet?name=Alice&lang=vi`
+
+## 5. Non-Functional Requirements
+- **Performance:** Response time for greeting generation under 50ms.
+- **Reliability:** Storage fallback to memory if database/file storage is offline.
+- **Extensibility:** Easy configuration to add new languages.
+
+## 6. System Flow & Sequence Diagram
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant Client as CLI / API Client
+    participant Engine as Greeting Engine
+    participant DB as Storage / History DB
+
+    User->>Client: Triggers greeting command/request (name, lang)
+    Client->>Engine: Resolve greeting configuration
+    Engine->>Engine: Validate input & detect Time of Day
+    Engine->>DB: Log transaction (user, time, format)
+    DB-->>Engine: Log confirmation
+    Engine->>Client: Return formatted greeting string
+    Client->>User: Display greeting output
+```

package/docs/android_kotlin_system_instruction.md

@@ -0,0 +1,210 @@
+# System Instruction for Premium Android Kotlin App Development
+
+You are the **Ultimate Senior Android Developer, Mobile Architect, and Motion UI/UX Specialist**. Your mission is to design, scaffold, and implement industry-leading, premium-tier, production-ready Android applications from scratch. You write clean, scalable Kotlin, build fluid motion designs in Jetpack Compose, enforce strict Clean Architecture boundaries, and deploy using high-performance engineering standards.
+
+---
+
+## 1. Architectural & Engineering Standards (Clean Architecture)
+
+### 1.1 Folder & Package Structure
+
+Organize the codebase following feature-based modularization, isolating features into self-contained architectural directories:
+
+```
+app/src/main/java/com/company/myapp/
+├── core/                         # Shared utilities, DI modules, theme, navigators
+│   ├── di/                       # Global AppModule, NetworkModule, DatabaseModule
+│   ├── theme/                    # Color, Type, Shape, Theme definitions
+│   └── utils/                    # Extensions, formatters, cryptography helpers
+└── features/                     # Feature-specific modules
+    └── [feature_name]/           # e.g., authentication, dashboard, onboarding
+        ├── domain/               # Pure Business Logic (No android framework imports)
+        │   ├── entities/         # Business domain models (standard Kotlin classes)
+        │   ├── usecases/         # Single-responsibility use cases
+        │   └── repositories/     # Repository interfaces (abstractions)
+        ├── data/                 # Platform & External Systems
+        │   ├── datasources/      # Local (Room/DataStore) & Remote (Retrofit/Ktor) sources
+        │   ├── dto/              # API and DB data transfer objects (with @Serializable)
+        │   └── repositories/     # Concrete repository implementations (extends domain)
+        └── presentation/         # Jetpack Compose UI Layer
+            ├── ui/               # Stateless screens, composables, views, styling
+            └── viewmodels/       # Flow state holders, screen action handlers
+```
+
+### 1.2 Strict Layer Boundaries & Dependency Rules
+
+Enforce the inward dependency rule (**Presentation → Domain ← Data**):
+
+- **Domain Layer**: MUST be pure Kotlin. Never import `android.*`, `androidx.*`, `retrofit.*`, or other framework libraries. It defines the business entities and repository abstractions.
+- **Presentation Layer**: Consists of composables and ViewModels. ViewModels use Domain UseCases to fetch and transform data.
+- **Data Layer**: Responsible for persistence (Room), caching (DataStore), and network communications (Retrofit). Implements repository interfaces defined in the Domain layer.
+
+### 1.3 Dependency Injection (Dagger Hilt)
+
+- Always use Dagger Hilt for DI: annotate your Application class with `@HiltAndroidApp`, activities with `@AndroidEntryPoint`, and ViewModels with `@HiltViewModel`.
+- Use `@Inject constructor` for class dependencies.
+- Define interface bindings cleanly in Hilt `@Module` classes using `@Binds` (for repository implementations) and `@Provides` (for external clients like Retrofit, Room, or DataStore instances).
+
+---
+
+## 2. UI-First Methodology & Premium Motion UX
+
+Aesthetics and responsiveness are core features. The user must feel the fluidity of the interface through premium, elastic movements and elegant spacing.
+
+### 2.1 The UI-First Implementation Pipeline
+
+Always prototype the visual design and settle the visual shell before wiring up reactive database endpoints:
+
+1.  **Draft UI Skeleton**: Set up the visual container blocks.
+2.  **Add Static Mock Data**: Render standard visual states (empty, loading, normal, error).
+3.  **Implement Micro-interactions & Motion**: Add smooth spring transitions, hover states, and keyframe animations.
+4.  **Connect Presentation State**: Wire the stateless UI components to real Hilt-injected ViewModels.
+5.  **Final Parity Audit**: Verify screen performance on virtual emulators or physical testing targets.
+
+### 2.2 Elastic & Spring Physics Animations
+
+Any dynamic presentation, button click, or page transition must utilize **spring-based physics** by default to create a premium, tactile feel.
+
+- **Spring Press Effect on Buttons**:
+  ```kotlin
+  @Composable
+  fun PrimaryButton(
+      text: String,
+      onClick: () -> Unit,
+      modifier: Modifier = Modifier
+  ) {
+      var isPressed by remember { mutableStateOf(false) }
+      val scale by animateFloatAsState(
+          targetValue = if (isPressed) 0.95f else 1f,
+          animationSpec = spring(
+              dampingRatio = Spring.DampingRatioMediumBouncy,
+              stiffness = Spring.StiffnessLow
+          )
+      )
+
+      Button(
+          onClick = onClick,
+          modifier = modifier
+              .fillMaxWidth()
+              .scale(scale)
+              .pointerInput(Unit) {
+                  detectTapGestures(
+                      onPress = {
+                          isPressed = true
+                          tryAwaitRelease()
+                          isPressed = false
+                      }
+                  )
+              }
+      ) {
+          Text(text, style = MaterialTheme.typography.bodyLarge)
+      }
+  }
+  ```
+
+### 2.3 Curated Color Systems & Typography Tokens
+
+- **No Raw Primary Colors**: Utilize highly cohesive, harmonized HSL/Material 3 theme palettes. Enforce curated dark themes, neon borders, and soft semantic alerts.
+- **Typography**: Dynamically fetch professional modern fonts (e.g., _Inter_, _Outfit_, _Roboto_) with a strong, highly readable visual hierarchy. Support Dynamic Type to scale text gracefully based on accessibility settings.
+- **Glassmorphism**: Use semi-transparent container fills with fine, light borders, subtle background blurs, and soft shadows (`Modifier.shadow()`) to deliver modern UI depth.
+
+### 2.4 Touch Psychology
+
+- **Tap Targets**: Maintain all interactive targets at a minimum of **48dp × 48dp** (based on Fitts' Law for human fingertips).
+- **Spacing**: Ensure a minimum gap of **8-12dp** between adjacent interactive elements to prevent accidental miss-taps.
+- **Thumb Zone Optimization**: Place core navigation controls, primary CTAs, and dynamic tab bars at the bottom half of the screen (the "easy-to-reach" zone).
+
+---
+
+## 3. High-Performance Engineering & Data Security
+
+### 3.1 Jetpack Compose List Optimizations
+
+Improperly written lists cause jank and frame drops. Always adhere to these performance rules:
+
+- **Always use Lazy Lists**: Use `LazyColumn` or `LazyRow` instead of `ScrollView` for lists with dynamic content.
+- **Explicit State Keying**: Always provide a unique, stable ID for every list item using the `key` parameter to prevent redundant compose recompositions:
+  ```kotlin
+  LazyColumn {
+      items(
+          items = itemList,
+          key = { item -> item.stableId }
+      ) { item ->
+          ListItemComponent(item = item)
+      }
+  }
+  ```
+- **Stateless Preview Delegates**: Break screens into a parent stateful wrapper (injecting ViewModel and handling navigation) and a child stateless screen composable containing only hardcoded parameters. This enables rapid Material Preview compilation for multiple states (Normal, Loading, Empty, Error).
+
+### 3.2 Secure Persistence & Tokens
+
+- **Zero PII Leakage**: Never print user tokens, passwords, database values, or personal identifiers in production log outputs.
+- **Encrypted Storage**: Cache API tokens, user authorization flags, and sensitive user states exclusively in `EncryptedSharedPreferences` or encrypted local databases (e.g., SQLCipher on top of Room).
+- **Environment Configs**: Configure API endpoints, API keys, and deployment profiles in a secure `.env` or system environment mapping, injecting them through gradle custom `BuildConfig` fields.
+
+### 3.3 Asynchronous Threading & Flows
+
+- **Explicit Dispatchers**: Ensure heavy calculations and local/remote source operations are launched on the correct dispatchers:
+  ```kotlin
+  viewModelScope.launch(Dispatchers.IO) {
+      repository.fetchData()
+  }
+  ```
+- **Lifecycle-aware Flows**: Collect flows in Composable scopes safely using `collectAsStateWithLifecycle()` to prevent memory leaks and background battery drainage.
+
+---
+
+## 4. AWKit Android CLI & ADB Commands
+
+Utilize the unified `android` CLI tool and ADB commands to execute system interactions, layout inspection, and test setups cleanly:
+
+```bash
+# 1. Environment & Device Scaffolding
+android info                                                          # Retrieve current Android SDK locations and configuration
+android sdk install platforms/android-34                              # Download a specific platform SDK target
+android emulator start --name="Pixel_7_API_34"                        # Launch a selected Android Virtual Device (AVD)
+
+# 2. Build & Layout Audits
+android describe --project_dir=.                                      # Scan targets and locate built APK paths
+android layout --pretty                                               # Dump the raw UI layout tree as formatted JSON
+android layout --diff                                                 # Identify changed layout tree nodes since the last dump
+
+# 3. Precise Visual Inspection & ADB Tap Actions
+android screen capture -o ./tmp/capture.png                           # Capture active viewport to a PNG file
+android screen capture --annotate -o ./tmp/capture_annotated.png      # Capture active screen with bounding boxes and numeric labels
+android screen resolve --screen ./tmp/capture_annotated.png --string "#3" # Get exact X/Y coordinate for visual box #3
+adb shell input $(android screen resolve --screen ./tmp/capture_annotated.png --string "tap #3") # Tap visual region #3 directly
+
+# 4. Device Interaction Control
+adb shell input keyevent 66                                           # Trigger ENTER key event
+adb shell input text "user@example.com"                               # Type literal string into the currently focused text field
+adb shell input swipe 500 1500 500 500 800                            # Slow vertical drag/swipe (duration: 800ms)
+```
+
+---
+
+## 5. Testing & CI/CD Pipelines
+
+### 5.1 Journey Validation & Test Reports
+
+Validate end-to-end user journeys using structured XML flows and export execution outcomes using a standardized JSON schema:
+
+```json
+{
+  "journey": "Premium User Subscription Flow",
+  "results": [
+    {
+      "action": "Verify that the welcome headline is displayed on screen",
+      "status": "PASSED",
+      "commands": [],
+      "comment": "Headline 'Welcome to App' was successfully identified."
+    },
+    {
+      "action": "Tap the 'Go Premium' button",
+      "status": "PASSED",
+      "commands": ["adb shell input tap 450 1200"],
+      "comment": "Button region matched layout bounds."
+    }
+  ]
+}
+```

package/docs/brainstorm_multi_agent_cli.md

@@ -0,0 +1,211 @@
+# Brainstorming: Tích Hợp Đa Tác Tử (Multi-Agent CLI Pipeline) để Tối Ưu Chi Phí và Hiệu Năng trong AWKit
+
+> **Tác giả:** Antigravity Orchestrator  
+> **Ngày cập nhật:** 2026-06-22  
+> **Phiên bản:** v1.0  
+> **Trạng thái:** Thảo luận / Ý tưởng thiết kế
+
+---
+
+## 1. Mục tiêu (Objective)
+
+Tối ưu hóa chi phí API và nâng cao hiệu suất làm việc bằng cách định tuyến thông minh (Smart Routing) các tác vụ phát triển phần mềm trong framework AWKit đến ba nhóm CLI agents khác nhau:
+
+1. **Claude Code CLI (`claude`)** — Nhóm siêu trí tuệ (Premium Model).
+2. **Codex CLI (`codex`)** — Nhóm kiểm thử & thẩm định (Intermediate/Audit Model).
+3. **Qwen Code CLI (`qwen-code` hoặc runner tương đương)** — Nhóm mã nguồn mở hiệu năng cao, chi phí rẻ (Cost-optimized Open-Source).
+
+---
+
+## 2. Phân tích Thế mạnh & Định vị Vai trò (Agent Capabilities & Roles)
+
+Dựa trên đặc điểm kỹ thuật và chi phí của từng mô hình, ta phân chia vai trò như sau:
+
+| CLI Agent         | Model Phía Sau           | Thế mạnh Đặc trưng                                                                                                                                                                                                                                                                                                                                             | Vai trò trong Hệ thống                                                         | Chiến lược Chi phí                                            |
+| :---------------- | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- | :------------------------------------------------------------ |
+| **Claude Code**   | Claude 3.5 Sonnet / Opus | - Suy luận logic phức tạp cực tốt.<br>- Lập kế hoạch kiến trúc chính xác.<br>- Khả năng giải quyết bug khó tốt nhất.                                                                                                                                                                                                                                           | **Architect (Kiến trúc sư)** & **Complex Solver (Giải quyết sự cố lớn)**       | Hạn chế số lần gọi (chỉ dùng cho Gate 2 & Gate 4 Complex).    |
+| **Codex CLI**     | GPT-4o / Codex custom    | - Review code khách quan với [$code-review](~/.agents/skills/code-review/SKILL.md).<br>- Thiết kế UI & Character assets chuyên sâu bằng [$hatch-pet](~/.codex/skills/hatch-pet/SKILL.md) và [$generate-gui-assets](~/.agents/skills/generate-gui-assets/SKILL.md).<br>- Tạo UI Shell tĩnh, HTML/CSS, Mockup nhanh.<br>- Sinh unit/integration tests chuẩn xác. | **Inspector (Kiểm định viên)** & **UI/Asset Builder (Tạo giao diện & Asset)**  | Sử dụng trung bình (Gate 2.5 & Gate 5).                       |
+| **Qwen Code CLI** | Qwen 2.5 Coder (32B/72B) | - Viết code boilerplate rất nhanh.<br>- Hiểu tốt nhiều ngôn ngữ lập trình.<br>- Tốc độ phản hồi cực nhanh, chi phí siêu rẻ hoặc miễn phí (tự host).                                                                                                                                                                                                            | **Boilerplate Generator (Sinh mã nền)** & **Local Executor (Thực thi cục bộ)** | Sử dụng tối đa cho các task đơn giản, viết code thô ở Gate 4. |
+| **Gemini (IDE)**  | Gemini 3.5 Flash         | - Context window khổng lồ (2M+).<br>- Tổng hợp và phân tích log/dữ liệu cực lớn.<br>- Phân tích codebase toàn diện.                                                                                                                                                                                                                                            | **Central Orchestrator (Điều phối viên trung tâm)** & **Context Sync**         | Chạy nền liên tục (chi phí cực rẻ).                           |
+
+---
+
+## 3. Quy trình Điều phối Đa Tác tử theo Hệ thống 7-Gate (7-Gate Routing Pipeline)
+
+Để tối ưu hóa chi phí, quy trình xử lý một Task (đi qua các Gate) sẽ được định tuyến tự động như sau:
+
+```mermaid
+graph TD
+    A[Bắt đầu Task] --> B{Phân loại độ khó Task}
+
+    B -->|Trivial / Simple| C[Qwen Code / Gemini Flash]
+    B -->|Moderate| D[Phối hợp Qwen & Codex]
+    B -->|Complex| E[Claude Code CLI]
+
+    subgraph Gate_2 [Gate 2: Spec & Architecture Planning]
+        E -->|Lập kế hoạch chính| F[Claude Code: claude-plan.js]
+        F --> G[Tạo implementation_plan.md]
+    end
+
+    subgraph Gate_2.5 [Gate 2.5: UI Shell & Assets]
+        G --> H[Codex CLI: codex exec GUI asset]
+    end
+
+    subgraph Gate_4 [Gate 4: Code Implementation]
+        H --> I{Phân rã Component}
+        I -->|Core Logic phức tạp| J[Claude Code CLI]
+        I -->|Boilerplate / Simple UI| K[Qwen Code CLI]
+    end
+
+    subgraph Gate_5 [Gate 5: Verification & QA]
+        J & K --> L[Codex CLI: Chạy Test & Code Review]
+        L --> M[Hoàn thành Task]
+    end
+```
+
+### Chi tiết Phân phối theo từng Gate:
+
+1. **Gate 1 & 1.5 (Brainstorm & Module Spec)**:
+   - **Tác tử**: Gemini Flash (Tích hợp sẵn trong IDE) làm việc trực tiếp với User.
+   - **Lý do**: Cần context lớn để hiểu toàn bộ yêu cầu của User và đọc tài liệu cũ. Chi phí cực thấp.
+
+2. **Gate 2 (Spec & Architecture Planning)**:
+   - **Tác tử**: **Claude Code CLI** (`node scripts/claude-plan.js`).
+   - **Lý do**: Lập kế hoạch sai sẽ dẫn đến viết code sai, gây lãng phí lớn chi phí API sau đó. Claude sẽ tạo ra `implementation_plan.md` cực kỳ chuẩn xác và hạn chế tối đa rủi ro regression.
+
+3. **Gate 2.5 (Visual Design & Asset Generation)**:
+   - **Tác tử**: **Codex CLI** (`codex exec`).
+   - **Lý do**: Codex thực hiện xuất sắc việc sinh UI shell/mockup và thiết kế UI & Character assets thông qua tích hợp các kỹ thuật chuyên sâu như [$hatch-pet](~/.codex/skills/hatch-pet/SKILL.md) (cho nhân vật/thú cưng) và [$generate-gui-assets](~/.agents/skills/generate-gui-assets/SKILL.md) (cho các thành phần giao diện).
+
+4. **Gate 4 (Execution - Viết Code)**:
+   - **Task Trivial (Dưới 3 files / Boilerplate)**: Định tuyến 100% qua **Qwen Code CLI** hoặc Gemini Flash.
+   - **Task Moderate/Complex**:
+     - **Qwen Code CLI** sẽ viết các file cấu trúc, helper, boilerplate và shell UI (Phase A + Phase B).
+     - **Claude Code CLI** sẽ được gọi để chèn logic cốt lõi (Core Business Logic) và giải quyết các phần tích hợp phức tạp (Phase C).
+
+5. **Gate 5 (Verification & QA)**:
+   - **Tác tử**: **Codex CLI** (phục vụ thẩm định chất lượng cao).
+   - **Lý do**: Codex có kỹ năng rà soát chất lượng code xuất sắc nhờ kỹ thuật [$code-review](~/.agents/skills/code-review/SKILL.md). Nó cũng rà soát sự tuân thủ các quy tắc coding (như Ponytail rules) và tự động sinh unit/integration tests để giảm thiểu rủi ro regression trước khi tích hợp vào nhánh chính.
+
+---
+
+## 4. Giải pháp Tích hợp Kỹ thuật vào AWKit (Technical Integration)
+
+Để triển khai ý tưởng này vào AWKit hiện tại, chúng ta cần thực hiện các bước sau:
+
+### Bước 4.1: Bổ sung cấu hình điều hướng trong `.project-identity`
+Thêm cấu hình điều phối đa tác tử để dễ dàng chuyển đổi chế độ hoạt động:
+```json
+"automation": {
+  "multiAgent": {
+    "enabled": true,
+    "routingMode": "cost-optimized", // "cost-optimized" hoặc "quality-first"
+    "audioAlerts": true, // Bật/tắt âm thanh thông báo cấp độ project (override)
+    "runners": {
+      "codex": "codex"
+    }
+  }
+}
+```
+
+### Bước 4.1.2: Cấu hình cấp độ Global (`~/.awkit_config.json`)
+Để bật/tắt hoặc tinh chỉnh các tính năng CLI (như âm thanh thông báo) trên toàn bộ thiết bị (global), ta sử dụng tệp cấu hình `~/.awkit_config.json` thông qua lệnh CLI:
+```bash
+# Xem toàn bộ cấu hình global hiện tại
+awkit config-global list
+
+# Bật hoặc tắt âm thanh thông báo hệ thống
+awkit config-global set audioAlerts false
+awkit config-global set audioAlerts true
+
+# Lấy giá trị của một cấu hình cụ thể
+awkit config-global get audioAlerts
+```
+*Ghi chú:* Cấu hình `audioAlerts` cục bộ trong `.project-identity` của dự án sẽ được ưu tiên cao hơn cấu hình global này.
+
+### Bước 4.2: Xây dựng Qwen CLI Wrapper (`scripts/qwen-plan.js` hoặc `scripts/qwen-exec.js`)
+
+Do Qwen CLI có thể chạy thông qua Ollama (local) hoặc qua API của các nhà cung cấp giá rẻ (OpenRouter, TogetherAI, v.v.), ta có thể viết một script trung gian để gọi:
+
+```javascript
+// scripts/qwen-exec.js
+const { execSync } = require("child_process");
+// Ví dụ: gọi Ollama chạy local model qwen2.5-coder:32b
+const prompt = process.argv[2];
+try {
+  const output = execSync(`ollama run qwen2.5-coder "${prompt}"`, {
+    encoding: "utf8",
+  });
+  console.log(output);
+} catch (e) {
+  // Fallback sang API hoặc Gemini Flash
+}
+```
+
+### Bước 4.3: Cập nhật Multi-Model Pipeline (`scripts/multi-model-pipeline.js`)
+
+Chỉnh sửa pipeline hiện tại để tích hợp tác tử Qwen vào giai đoạn Code Step:
+
+- **Trước đây**: Chỉ dùng `gemini-2.5-flash` hoặc `claude-opus`.
+- **Mới**: Định tuyến thông minh:
+  ```javascript
+  if (taskDifficulty === "trivial" || routingMode === "cost-optimized") {
+    runQwenCodeStep(featureName);
+  } else {
+    runClaudeCodeStep(featureName);
+  }
+  ```
+
+---
+
+## 5. Đánh giá Hiệu quả Chi phí (Cost-Benefit Analysis)
+
+Giả sử một task phát triển tính năng trung bình tiêu tốn khoảng **100,000 input tokens** và **10,000 output tokens**:
+
+| Chiến lược                           | Chi tiết phân phối                                                                                                                                          | Chi phí ước tính (USD/Task) | Tỷ lệ Tiết kiệm                                                                                       |
+| :----------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------- | :---------------------------------------------------------------------------------------------------- |
+| **Chỉ dùng Claude 3.5**              | 100% sử dụng Claude                                                                                                                                         | ~$0.45                      | 0% (Mốc chuẩn)                                                                                        |
+| **Chỉ dùng Gemini Flash**            | 100% sử dụng Gemini Flash                                                                                                                                   | ~$0.012                     | 97% (Nhưng chất lượng logic phức tạp có thể giảm)                                                     |
+| **Đa Tác tử (Multi-Agent Pipeline)** | - **Claude** (10% tokens cho Planning)<br>- **Qwen Coder** (80% tokens cho Boilerplate & Coding - Local/Free)<br>- **Codex** (10% tokens cho Review & Test) | **~$0.07**                  | **~85% Tiết kiệm** mà vẫn giữ được chất lượng kiến trúc của Claude và chất lượng kiểm định của Codex. |
+
+---
+
+## 6. Cơ Chế Hoạt Động Chi Tiết (How it Works)
+
+Cơ chế điều phối sub-agent CLI trong AWKit hoạt động theo 6 bước tuần tự:
+1. **Nhận diện và Kích hoạt (Trigger Detection)**: Dựa trên Gate hiện tại (Gate 2, 2.5, 4, 5) hoặc độ phức tạp của task (Trivial, Moderate, Complex), Central Agent (Gemini Flash) xác định CLI agent cần dùng.
+2. **Thu thập Ngữ cảnh (Context Gathering)**: Central Agent tự động đóng gói các tài liệu liên quan (`.project-identity`, `implementation_plan.md`, `git diff`...) thành một prompt có cấu trúc.
+3. **Chạy Trực Tiếp / Ủy quyền (Execution Delegation)**: Chạy CLI qua terminal bằng lệnh `run_command` hoặc thông qua các wrapper script chuyên dụng (như `scripts/multi-model-pipeline.js`, `scripts/claude-plan.js`).
+4. **Cơ chế Dự phòng (Graceful Fallback)**: Nếu CLI không được cài đặt (Exit code `127`) hoặc gặp lỗi xác thực (Exit code `2`), hệ thống sẽ tự động chuyển sang mô hình mặc định trong IDE mà không làm gián đoạn luồng làm việc.
+5. **Ghi nhận & Tiêu thụ Báo cáo (Result Consumption)**: Kết quả từ CLI được lưu dưới dạng file báo cáo (`.md` hoặc `.json`) trong thư mục `codex-reports/` hoặc `brain/`. Central Agent sẽ đọc báo cáo này để cập nhật ngữ cảnh và tiếp tục thực hiện mã nguồn.
+6. **Thông Báo Hoàn Tất Bằng Âm Thanh (Audio Notification)**: Đối với các tác vụ chạy nền (background tasks) tốn thời gian, hệ thống tự động phát âm thanh hệ thống (ví dụ: `afplay /System/Library/Sounds/Glass.aiff`) và thông báo bằng giọng nói (ví dụ: `say "Done"`) trên macOS để thông báo cho người dùng khi quy trình hoàn thành.
+
+---
+
+## 7. Khảo Sát Môi Trường Thực Tế & Thử Nghiệm (Environment Audit & Prototype)
+
+Kết quả khảo sát môi trường tại máy local `/Users/trungkientn/Dev/NodeJS/main-awf`:
+* **Codex CLI**: ✅ Đã được cài đặt tại `/Users/trungkientn/.nvm/versions/node/v22.22.0/bin/codex`.
+* **agy CLI (Gemini)**: ✅ Đã được cài đặt tại `/Users/trungkientn/.local/bin/agy` (Version 1.0.0).
+* **Claude Code CLI**: ✅ Đã cài đặt dưới dạng alias, trỏ trực tiếp đến `/Users/trungkientn/.claude/local/claude` (Sử dụng đường dẫn tuyệt đối này trong các script tự động hóa).
+* **Qwen Code CLI**: ✅ Đã được cài đặt với tên lệnh `qwen` tại `/Users/trungkientn/.nvm/versions/node/v22.22.0/bin/qwen`.
+
+### Kết Quả Thử Nghiệm Thực Tế (Test Run Results - 2026-06-22):
+
+#### 1. Kiểm thử đơn lẻ (Unit Test Run):
+- **agy CLI (Gemini)**: ✅ Thành công phản hồi câu hỏi lý thuyết sau `20,195ms`.
+- **Codex CLI (OpenAI - Model: `gpt-5.5`)**: ✅ Thành công review mã nguồn cứng API key sau `10,182ms`.
+
+#### 2. Kiểm thử phối hợp chuỗi (Multi-Agent Pipeline Test Run):
+Đã chạy thành công kịch bản lập kế hoạch, sinh mã nguồn và rà soát tự động cho hàm Fibonacci memoization thông qua script `run_multi_agent_pipeline.js`:
+- **Bước 1: Claude CLI (Architect)**: ✅ Thành công thiết kế sơ đồ logic và kế hoạch memoization lưu tại [test_plan.md](file:///Users/trungkientn/.gemini/antigravity-ide/brain/c843a673-f692-4562-a065-0000e76bff71/scratch/test_plan.md).
+- **Bước 2: Qwen CLI (Executor)**: ✅ Thành công đọc kế hoạch của Claude và viết mã nguồn JavaScript tương thích 100%, lưu tại [test_code.js](file:///Users/trungkientn/.gemini/antigravity-ide/brain/c843a673-f692-4562-a065-0000e76bff71/scratch/test_code.js) (`21,237ms`).
+- **Bước 3: Codex CLI (Inspector)**: ✅ Thành công đối chiếu `test_code.js` với `test_plan.md`, chỉ ra 2 cảnh báo độ ưu tiên Medium (tràn số khi `n >= 79` và lỗi call stack đệ quy sâu) kèm 2 nhận xét Low, lưu tại [test_review.md](file:///Users/trungkientn/.gemini/antigravity-ide/brain/c843a673-f692-4562-a065-0000e76bff71/scratch/test_review.md) (`23,250ms`).
+- **Kết luận**: Quy trình hoạt động đồng bộ hoàn hảo. Sự phối hợp giúp phân tách trách nhiệm rõ rệt: thiết kế cao cấp (Claude) -> lập trình cơ bản (Qwen) -> rà soát chi tiết (Codex). Log đầy đủ tại [pipeline_run_log.json](file:///Users/trungkientn/.gemini/antigravity-ide/brain/c843a673-f692-4562-a065-0000e76bff71/scratch/pipeline_run_log.json).
+
+---
+
+## 8. Các Bước Tiếp Theo Đề Xuất (Next Steps)
+1. **Tạo kịch bản thử nghiệm thực tế (Test Run Script)**: Viết script `test_sub_agents.js` trong thư mục `scratch/` để gọi thử `codex` và `agy` kiểm tra logic review/plan thô.
+2. **Cập nhật wrapper script gọi Claude và Qwen**: Thiết lập đường dẫn tuyệt đối `/Users/trungkientn/.claude/local/claude` cho Claude và tên lệnh `qwen` cho Qwen trong hệ thống multi-model routing của AWKit.
+3. **Đóng gói Skill**: Phát triển `skills/qwen-conductor/SKILL.md` để tự động hóa định tuyến.

package/docs/brainstorm_ponytail_integration.md

@@ -0,0 +1,146 @@
+# Revision History
+
+| Version | Date | Author | Description |
+|---|---|---|---|
+| v1.0 | 2026-06-15 | Antigravity Orchestrator | Bản thảo brainstorm tích hợp triết lý Ponytail vào dự án AWKit |
+| v1.1 | 2026-06-15 | Antigravity Orchestrator | ✅ Approved: Giải pháp 1 (Gate enforcement), mặc định bật, cấu hình qua `.project-identity` |
+
+---
+
+# Brainstorm: Tích hợp Triết lý Ponytail vào AWKit
+
+Tài liệu này tập trung vào việc áp dụng thực tế triết lý "lazy senior developer" từ dự án [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) vào hệ thống **AWKit (Antigravity Workflow Kit)**.
+
+---
+
+## 1. Phân tích bối cảnh dự án & Vấn đề thực tế
+
+Trong quá trình phát triển các ứng dụng bằng AI (chẳng hạn như React Dashboard của Symphony, game Expo/Unity, hay các app iOS/Android trong hệ sinh thái của User):
+* **AI thường "over-deliver"**: Khi được yêu cầu viết một tính năng đơn giản (ví dụ: bộ lọc ngày, cache dữ liệu), AI thường tự ý cài thêm các thư viện bên ngoài (Moment.js, Flatpickr, custom cache classes với TTL phức tạp) thay vì sử dụng tính năng native của trình duyệt/nền tảng hoặc thư viện tiêu chuẩn (stdlib).
+* **Token Bloat**: Việc sinh thêm code boilerplate và các tầng trừu tượng không cần thiết làm phình to context của session làm việc, dẫn đến cạn kiệt ngân sách token nhanh hơn và làm chậm thời gian phản hồi của AI.
+* **Gia tăng Technical Debt**: Nhiều class phức tạp được tạo ra "để dành cho tương lai" (speculative generality) nhưng thực tế không bao giờ được sử dụng đến, gây khó khăn cho việc bảo trì.
+
+---
+
+## 2. Giải pháp tích hợp thực tế vào AWKit
+
+Chúng ta sẽ tích hợp triết lý Ponytail vào hai lớp của AWKit: **Lớp ràng buộc hệ thống (System Enforcer)** và **Lớp công cụ nhà phát triển (Developer Tools)**.
+
+### ✅ Giải pháp 1: Ràng buộc trực tiếp vào Quy trình 7-Gate (Internal Enforcement) — APPROVED
+Hệ thống Gate của AWKit (đặc biệt là Gate 4 - Execution và Gate 5 - Verification) sẽ được bổ sung các chốt chặn tự động:
+* **Gate 4 Phase B (UI Shell Mock) & Phase C (Logic)**: 
+  * AI bắt buộc phải đối chiếu danh sách linh kiện/native API trước khi bắt tay viết code.
+  * *Ví dụ:* Nếu làm UI React, cấm cài thêm thư viện date/color picker hay modal nếu HTML5 `<input type="date">` hoặc `<dialog>` đáp ứng được.
+* **Gate 5 (Verification)**: 
+  * Tích hợp bước tự động rà soát over-engineering. Trước khi commit code qua `awkit gate git auto`, AI phải tự chạy bộ lọc Ponytail để tối giản hóa code vừa viết. Nếu có thể rút gọn tối thiểu 10% số dòng code mà vẫn giữ nguyên logic và tính an toàn, AI phải tự tái cấu trúc ngay lập tức.
+
+### Giải pháp 2: Xây dựng Kỹ năng `awf-ponytail` & `awf-ponytail-review`
+* **Skill `awf-ponytail`**: Khi người dùng yêu cầu AI viết code tối giản bằng các từ khóa như `be lazy`, `lazy mode`, `ponytail`, AI sẽ tự động kích hoạt chế độ sinh code siêu tinh gọn, chỉ dùng stdlib và native APIs, đồng thời luôn đánh dấu các phần giản lược bằng comment `// ponytail: [giới hạn] -> [cách nâng cấp]`.
+* **Skill `awf-ponytail-review`**: Hỗ trợ review độ phức tạp của code. Khi người dùng gọi `/ponytail-review` hoặc hỏi "code này có over-engineered không?", AI sẽ phân tích và đưa ra báo cáo cực kỳ ngắn gọn dạng:
+  `L<line>: <tag> <what>. <replacement>.`
+  * `delete:` Xóa bỏ boilerplate hoặc abstractions thừa.
+  * `stdlib:` Thay bằng hàm có sẵn của thư viện chuẩn.
+  * `native:` Thay bằng tính năng native của trình duyệt/HĐH.
+  * `yagni:` Gộp class/interface chỉ có một implementation duy nhất.
+  * `shrink:` Viết lại đoạn code ngắn gọn hơn.
+
+### Giải pháp 3: Xây dựng Workflow `workflows/quality/ponytail-review.md`
+Cung cấp một workflow dạng manual để người dùng kích hoạt bất kỳ lúc nào nhằm quét toàn bộ codebase hoặc diff hiện tại để tìm các điểm có thể tối giản hóa, tính toán số dòng code tối đa có thể cắt giảm (`net: -<N> lines possible`).
+
+---
+
+## 3. Bản thảo Chi tiết Kỹ thuật (Technical Drafts)
+
+### A. Ràng buộc mới trong `core/GEMINI.md` (English)
+```markdown
+### Lazy Dev Mode (Ponytail Rules)
+- **Ladder of Simplicity**: Before writing code, stop at the first rung:
+  1. YAGNI: Speculative need = skip it.
+  2. Stdlib does it? Use it.
+  3. Native platform feature covers it? Use it (e.g. `<input type="date">`, `<dialog>`, native CSS transitions).
+  4. Installed dependency solves it? Use it. Do not add new dependencies unless explicitly authorized.
+  5. One line? Make it one line.
+  6. Minimum code that works.
+- **Complexity Guard**: No unrequested abstractions, interfaces with a single implementation, boilerplate, or scaffolding "for later".
+- **Simplification Marker**: Mark intentional simplifications with a `ponytail:` comment describing the known ceiling and the upgrade path (e.g. `// ponytail: global lock, switch to per-account locks if throughput degrades`).
+```
+
+### B. Cấu trúc Skill `skills/awf-ponytail-review/SKILL.md` (English)
+```markdown
+---
+name: awf-ponytail-review
+description: Hunt for over-engineering and bloated code in diffs or directories.
+version: 1.0.0
+---
+
+# AWF Ponytail Review
+
+Audit code exclusively for unnecessary complexity, speculative features, and boilerplate. 
+
+## Audit Rules
+1. Identify code that duplicates stdlib (e.g., manual debouncers, custom string pads).
+2. Find unneeded third-party libraries doing what native features can do.
+3. Locate one-off abstractions (interfaces, factories, wrappers) that add no value.
+
+## Output Format
+Strictly one line per finding:
+`L<line>: <tag> <what>. <replacement>.`
+
+End with: `net: -<N> lines possible.`
+If the code is already optimized, output: `Lean already. Ship.`
+```
+
+---
+
+## 4. Các điểm cần thảo luận thêm (Open Questions)
+
+1. ~~**Có nên tự động kích hoạt Ponytail Mode cho mọi task không?**~~ → ✅ **QUYẾT ĐỊNH: MẶC ĐỊNH BẬT**
+   * Ponytail Mode mặc định **enabled** cho mọi dự án.
+   * Người dùng vibe coding thường không thể xác định rõ cái nào cần lazy, cái nào không → hệ thống nên tự áp dụng.
+   * Nếu người dùng muốn tắt (ví dụ: Enterprise projects cần kiến trúc mở rộng cao), cấu hình qua `.project-identity`:
+   ```json
+   "automation": {
+     "ponytailMode": {
+       "enabled": false,
+       "level": "full"
+     }
+   }
+   ```
+   * **Giá trị mặc định khi không khai báo**: `enabled: true`, `level: "full"`.
+   
+2. **Comment `ponytail:` có nên là bắt buộc không?**
+   * *Đề xuất:* Rất cần thiết. Khi AI viết code quá tối giản (ví dụ: không dùng framework test phức tạp mà chỉ dùng `assert`), lập trình viên khác đọc vào có thể nghĩ AI làm ẩu hoặc thiếu kiến thức. Comment `// ponytail:` giúp làm rõ đó là sự giản lược có chủ đích.
+
+---
+
+## 5. Schema cấu hình `.project-identity`
+
+Trường `automation.ponytailMode` sẽ tuân theo cấu trúc tương tự `communication.cavemanMode`:
+
+```json
+{
+  "automation": {
+    "ponytailMode": {
+      "enabled": true,
+      "level": "full"
+    }
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Bật/tắt Ponytail enforcement trong Gate 4 & Gate 5 |
+| `level` | `string` | `"full"` | Mức độ: `"lite"` (gợi ý), `"full"` (bắt buộc stdlib/native first), `"ultra"` (YAGNI cực đoan) |
+
+**Quy tắc đọc cấu hình:**
+```
+config = read(".project-identity")
+ponytail = config?.automation?.ponytailMode
+enabled = ponytail?.enabled ?? true   // mặc định BẬT
+level   = ponytail?.level ?? "full"    // mặc định FULL
+```
+
+---
+
+*Đã duyệt Giải pháp 1. Sẵn sàng triển khai khi user approve.*