@leejungkiin/awkit 1.7.4 → 1.7.5

package/core/GEMINI.md

@@ -152,6 +152,10 @@ symphony-orchestrator → awf-session-restore (gitnexus state) → nm-memory-syn
   - Định nghĩa custom subagent bằng `define_subagent` (ví dụ: `critic` phải cấu hình read-only toolsets).
   - Tái sử dụng subagent ở trạng thái `Idle` qua việc gửi tin nhắn thay vì tạo mới.
   - Tuân thủ giới hạn lồng tác tử (nesting limit) tối đa 10 cấp.
+- **Tận dụng Multi-Agent CLI Pipeline (Claude, Codex, Qwen):**
+  - Tích hợp điều phối liên hoàn để tăng tốc độ: **Claude CLI** (Lập kế hoạch/Architect), **Qwen CLI** (Viết code/Executor), và **Codex CLI** (UI preview/GUI assets & review).
+  - Tự động kiểm tra cấu hình (`audioAlerts`, `runners.claude`, `runners.codex`, `runners.qwen`) và độ khả dụng của binary CLI để điều phối/tự động fallback về **Gemini Flash** (`agy`) khi runner bị tắt hoặc chưa cài đặt.
+  - Các lệnh quản lý: `awkit config <runner> <on|off>`, `awkit config list`, `awkit config runners` và `awkit config models`.
 
 ### Mandatory Check-Then-Act Protocol (🔥 BẮT BUỘC)
 - TRƯỚC khi dùng công cụ sửa code/run command lần đầu mỗi task, PHẢI tự trả lời trong `<thought>` (KHÔNG in ra chat):

package/core/GEMINI.md.bak

@@ -152,6 +152,10 @@ symphony-orchestrator → awf-session-restore (gitnexus state) → nm-memory-syn
   - Định nghĩa custom subagent bằng `define_subagent` (ví dụ: `critic` phải cấu hình read-only toolsets).
   - Tái sử dụng subagent ở trạng thái `Idle` qua việc gửi tin nhắn thay vì tạo mới.
   - Tuân thủ giới hạn lồng tác tử (nesting limit) tối đa 10 cấp.
+- **Tận dụng Multi-Agent CLI Pipeline (Claude, Codex, Qwen):**
+  - Tích hợp điều phối liên hoàn để tăng tốc độ: **Claude CLI** (Lập kế hoạch/Architect), **Qwen CLI** (Viết code/Executor), và **Codex CLI** (UI preview/GUI assets & review).
+  - Tự động kiểm tra cấu hình (`audioAlerts`, `runners.claude`, `runners.codex`, `runners.qwen`) và độ khả dụng của binary CLI để điều phối/tự động fallback về **Gemini Flash** (`agy`) khi runner bị tắt hoặc chưa cài đặt.
+  - Các lệnh quản lý: `awkit config <runner> <on|off>`, `awkit config list`, `awkit config runners` và `awkit config models`.
 
 ### Mandatory Check-Then-Act Protocol (🔥 BẮT BUỘC)
 - TRƯỚC khi dùng công cụ sửa code/run command lần đầu mỗi task, PHẢI tự trả lời trong `<thought>` (KHÔNG in ra chat):

package/core/GreetingEngine/index.js

@@ -0,0 +1,225 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const HOME = process.env.HOME || process.env.USERPROFILE;
+const GLOBAL_LOG_DIR = path.join(HOME, '.gemini', 'antigravity');
+const DEFAULT_LOCAL_PATH = path.join(__dirname, '..', '..', 'greeting_history.jsonl');
+
+/**
+ * Resolves the path to the history file.
+ */
+function getHistoryFilePath() {
+    if (fs.existsSync(GLOBAL_LOG_DIR)) {
+        return path.join(GLOBAL_LOG_DIR, 'greeting_history.jsonl');
+    }
+    // Consistent fallback to workspace root
+    return DEFAULT_LOCAL_PATH;
+}
+
+/**
+ * Strips HTML tags and escapes dangerous characters to prevent XSS and injection.
+ */
+function sanitizeName(name) {
+    if (!name) return 'Guest';
+    const clean = name.replace(/<[^>]*>/g, '').trim();
+    if (!clean) return 'Guest';
+    return clean.replace(/[&<>"']/g, (m) => ({
+        '&': '&amp;',
+        '<': '&lt;',
+        '>': '&gt;',
+        '"': '&quot;',
+        "'": '&#39;'
+    })[m]);
+}
+
+/**
+ * Detect time of day category based on hour.
+ * Morning: 05:00 - 11:59
+ * Afternoon: 12:00 - 17:59
+ * Evening: 18:00 - 21:59
+ * Night: 22:00 - 04:59
+ */
+function getTimeOfDay(hour) {
+    if (hour >= 5 && hour < 12) return 'morning';
+    if (hour >= 12 && hour < 18) return 'afternoon';
+    if (hour >= 18 && hour < 22) return 'evening';
+    return 'night';
+}
+
+/**
+ * Returns local hour for the given timezone, or falls back to server local hour.
+ */
+function getHourInTimezone(date, timezone) {
+    if (timezone) {
+        try {
+            const parts = new Intl.DateTimeFormat('en-US', {
+                timeZone: timezone,
+                hour: 'numeric',
+                hour12: false
+            }).formatToParts(date);
+            const hourPart = parts.find(p => p.type === 'hour');
+            if (hourPart) {
+                return parseInt(hourPart.value, 10);
+            }
+        } catch (e) {
+            console.warn(`[GreetingEngine] Invalid timezone: "${timezone}". Falling back to system timezone.`);
+        }
+    }
+    return date.getHours();
+}
+
+const LOCALES = {
+    en: require('./locales/en.json'),
+    vi: require('./locales/vi.json'),
+    ja: require('./locales/ja.json')
+};
+
+/**
+ * Load localization dictionary. Falls back to 'en' if lang is invalid.
+ */
+function getLocaleTemplates(lang) {
+    let resolvedLang = lang || 'en';
+    if (!LOCALES[resolvedLang]) {
+        console.warn(`[GreetingEngine] Locale "${resolvedLang}" not found. Falling back to "en".`);
+        resolvedLang = 'en';
+    }
+    return { templates: LOCALES[resolvedLang], lang: resolvedLang };
+}
+
+/**
+ * Generates greeting message, logs to file, and returns structured data.
+ */
+function generateGreeting({ name, lang, timezone }) {
+    const rawName = (name && name.trim()) || 'Guest';
+    const resolvedName = sanitizeName(rawName);
+    const rawLang = (lang && lang.trim().toLowerCase()) || 'en';
+    const date = new Date();
+
+    const hour = getHourInTimezone(date, timezone);
+    const timeOfDay = getTimeOfDay(hour);
+
+    const { templates, lang: resolvedLang } = getLocaleTemplates(rawLang);
+    const template = templates[timeOfDay] || templates['morning'];
+
+    const message = template.replace(/{name}/g, resolvedName);
+    const timestamp = date.toISOString();
+
+    const record = {
+        id: crypto.randomUUID(),
+        name: resolvedName,
+        language: resolvedLang,
+        timestamp,
+        time_of_day: timeOfDay,
+        greeting_message: message
+    };
+
+    saveGreetingToHistory(record);
+
+    return {
+        status: 'success',
+        data: {
+            message,
+            name: resolvedName,
+            lang: resolvedLang,
+            timestamp,
+            timeOfDay,
+            timezone: timezone || 'system'
+        }
+    };
+}
+
+/**
+ * Save record into history.jsonl
+ */
+function saveGreetingToHistory(record) {
+    const logPath = getHistoryFilePath();
+    try {
+        const dir = path.dirname(logPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.appendFileSync(logPath, JSON.stringify(record) + '\n', 'utf8');
+    } catch (e) {
+        console.error(`[GreetingEngine] Failed to log greeting to history: ${e.message}`);
+    }
+}
+
+/**
+ * Reads and returns history records from jsonl.
+ */
+function getGreetingHistory() {
+    const logPath = getHistoryFilePath();
+    if (!fs.existsSync(logPath)) {
+        return [];
+    }
+
+    try {
+        const content = fs.readFileSync(logPath, 'utf8');
+        return content
+            .split('\n')
+            .filter(line => line.trim().length > 0)
+            .map(line => JSON.parse(line));
+    } catch (e) {
+        console.error(`[GreetingEngine] Failed to read greeting history: ${e.message}`);
+        return [];
+    }
+}
+
+/**
+ * Aggregates statistics based on history.
+ */
+function getGreetingStats() {
+    const history = getGreetingHistory();
+    const totalGreetings = history.length;
+
+    if (totalGreetings === 0) {
+        return {
+            totalGreetings: 0,
+            mostActiveUser: 'N/A',
+            mostUsedLanguage: 'N/A',
+            popularTimeOfDay: 'N/A'
+        };
+    }
+
+    const userCounts = {};
+    const langCounts = {};
+    const timeOfDayCounts = { morning: 0, afternoon: 0, evening: 0, night: 0 };
+
+    history.forEach(record => {
+        userCounts[record.name] = (userCounts[record.name] || 0) + 1;
+        langCounts[record.language] = (langCounts[record.language] || 0) + 1;
+        
+        // Use stored time_of_day for 100% accuracy, fallback to client parsing if old log
+        const tod = record.time_of_day || 'morning';
+        if (timeOfDayCounts[tod] !== undefined) {
+            timeOfDayCounts[tod]++;
+        }
+    });
+
+    const getMaxKey = (obj) => {
+        let maxKey = 'N/A';
+        let maxVal = -1;
+        Object.entries(obj).forEach(([key, val]) => {
+            if (val > maxVal) {
+                maxVal = val;
+                maxKey = key;
+            }
+        });
+        return maxKey;
+    };
+
+    return {
+        totalGreetings,
+        mostActiveUser: getMaxKey(userCounts),
+        mostUsedLanguage: getMaxKey(langCounts),
+        popularTimeOfDay: getMaxKey(timeOfDayCounts)
+    };
+}
+
+module.exports = {
+    generateGreeting,
+    getGreetingHistory,
+    getGreetingStats,
+    getHistoryFilePath
+};

package/core/GreetingEngine/locales/en.json

@@ -0,0 +1,6 @@
+{
+  "morning": "Good morning, {name}!",
+  "afternoon": "Good afternoon, {name}!",
+  "evening": "Good evening, {name}!",
+  "night": "Good night, {name}!"
+}

package/core/GreetingEngine/locales/ja.json

@@ -0,0 +1,6 @@
+{
+  "morning": "おはようございます、{name}さん！",
+  "afternoon": "こんにちは、{name}さん！",
+  "evening": "こんばんは、{name}さん！",
+  "night": "おやすみなさい、{name}さん！"
+}

package/core/GreetingEngine/locales/vi.json

@@ -0,0 +1,6 @@
+{
+  "morning": "Chào buổi sáng, {name}!",
+  "afternoon": "Chào buổi chiều, {name}!",
+  "evening": "Chào buổi tối, {name}!",
+  "night": "Chúc {name} ngủ ngon!"
+}

package/core/GreetingEngine/test.js

@@ -0,0 +1,37 @@
+const { generateGreeting, getGreetingHistory, getGreetingStats } = require('./index');
+const fs = require('fs');
+
+function runTests() {
+  console.log("🧪 Testing Qwen's Generated GreetingEngine...");
+
+  // Run a few greetings
+  const g1 = generateGreeting({ name: "Alice", lang: "en" });
+  console.log(`✅ Greeting 1: "${g1.data.message}"`);
+
+  const g2 = generateGreeting({ name: "Bình", lang: "vi" });
+  console.log(`✅ Greeting 2: "${g2.data.message}"`);
+
+  const g3 = generateGreeting({ name: "Yamada", lang: "ja" });
+  console.log(`✅ Greeting 3: "${g3.data.message}"`);
+
+  // Language fallback test
+  const g4 = generateGreeting({ name: "Charlie", lang: "fr" }); // French not supported, should fallback to English
+  console.log(`✅ Greeting 4 (Fallback): "${g4.data.message}" (Language: ${g4.data.lang})`);
+
+  // Verify history
+  const history = getGreetingHistory();
+  console.log(`📊 History has ${history.length} records.`);
+
+  // Verify stats
+  const stats = getGreetingStats();
+  console.log("📈 Statistics:", stats);
+
+  if (history.length >= 4 && stats.totalGreetings >= 4) {
+    console.log("🎉 Qwen's GreetingEngine verified successfully!");
+  } else {
+    console.error("❌ Stats or history mismatch!");
+    process.exit(1);
+  }
+}
+
+runTests();

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/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/history/PRD.v1.md

@@ -0,0 +1,55 @@
+# Product Requirements Document (PRD) — MemoizedFibonacci
+
+## Revision History
+
+| Version | Date | Author | Description |
+| :--- | :--- | :--- | :--- |
+| 1.0 | 2026-06-22 | Antigravity Orchestrator | Initial draft for MemoizedFibonacci feature. |
+
+---
+
+## 1. Vision & Objectives
+
+* **Project Summary:** The `MemoizedFibonacci` feature provides a highly optimized, high-performance utility class/module for calculating Fibonacci sequences. It leverages an advanced caching (memoization) mechanism to avoid the exponential time complexity $O(2^n)$ associated with naive recursive methods, turning sequence generation into a linear time $O(n)$ or constant-time $O(1)$ operation for subsequent lookups.
+* **Problem Statement:** Standard recursive calculations of Fibonacci numbers quickly exhaust CPU resources and crash due to call stack size limits or integer overflows when $n \ge 79$ in standard floating-point representation. Naive memory caches can also grow indefinitely, leading to memory leaks in server environments.
+* **Target Audience:** Core application developers, backend engineers running mathematical modeling services, and background agents requiring sequence calculations.
+
+---
+
+## 2. Core Principles & Philosophy
+
+* **Performance & Scalability:** Constant lookups $O(1)$ for cached values, linear complexity $O(n)$ for first-time calculations.
+* **Robustness & Accuracy:** Complete support for `BigInt` calculations to prevent integer overflow beyond JS safe limit ($n > 78$).
+* **Memory Safety & Self-Regulation:** Integrated Least Recently Used (LRU) cache eviction strategy to guarantee a fixed maximum memory footprint.
+* **Non-Blocking Operation:** Heavy calculations ($n \ge 100,000$) must run asynchronously (chunked loops or offloaded execution) to prevent thread/event-loop blockage.
+
+---
+
+## 3. Scope & Feature List
+
+### In Scope
+* **Multiple Calculation Modes:** Synchronous calculations for small inputs; asynchronous (non-blocking) computation for larger values.
+* **Flexible Precision:** Standard JS numbers for fast calculations ($n \le 78$) and `BigInt` for arbitrarily large numbers.
+* **LRU Caching Strategy:** A bounded in-memory cache that automatically evicts least recently accessed Fibonacci numbers when the maximum cache capacity is reached.
+* **Cache Metrics:** Reporting of cache metrics such as hit rate, miss rate, current size, and eviction count.
+* **Resource Guardrails:** Hard limits on inputs to prevent CPU exhaustion.
+
+### Out of Scope
+* **Negative/Fractional Fibonacci:** No support for negative numbers or fractional inputs (standard integer sequence only).
+* **Distributed Cache integration:** No built-in Redis/Memcached integration (limited to localized, bounded memory cache with extensible hooks).
+
+---
+
+## 4. Key Performance Indicators (KPIs)
+
+* **Execution Time (Cached):** Sub-microsecond response time for any cached value.
+* **Execution Time (Uncached):** Linear scaling $O(n)$. Computing $F(10000)$ uncached must complete in under 5 milliseconds.
+* **Call Stack Safety:** Zero recursion-based Call Stack Size Exceeded errors.
+* **Memory Limit:** Strict enforcement of maximum cache entries (e.g. defaults to 1,000 values), keeping peak memory consumption under 25MB even for large BigInts.
+
+---
+
+## 5. Anti-Patterns (What NOT to do)
+* Do not use recursive calls without tail call optimization or loop conversion. Recursion is forbidden for calculations.
+* Do not store calculated BigInt values as standard floats since precision is lost.
+* Do not allow the cache size to grow indefinitely (bounded cache is mandatory).