npm package: @leejungkiin/awkit
Description: Antigravity Workflow Kit v12.5. Unified AI agent orchestration system with Mindful Checkpoints.
Author: Kien Le
Latest version: 1.6.4

# AWKit — Antigravity Workflow Kit v12.5

> **v12.5** · Single Source of Truth · Symphony-First · Mindful Execution

AWKit là framework điều phối AI agent chuyên nghiệp. Đây là **nơi duy nhất** chứa toàn bộ workflows, skills, GEMINI.md và cấu hình — không còn phân tán giữa nhiều repo.
AWKit giúp tối ưu context khi làm việc, có khả năng quản lý task, đồng bộ Trello và báo cáo lên Telegram, ngoài ra Awkit còn sử dụng cơ chế checkpoint để dev dừng đúng lúc tránh tâm lý tối ưu hóa quá mức (over-optimization) một vấn đề phổ biến khi làm việc với AI.

---

## 🧠 Gstack Core Principles

AWKit (Antigravity v12+) thực thi 8 nguyên tắc lõi (Gstack-inspired) nhằm đảm bảo AI hoạt động an toàn và hiệu quả:

1. **Anti-sycophancy:** AI phải phản biện các hướng tiếp cận có rủi ro, không đồng ý mù quáng khi có red flags.
2. **Search Before Building (3-layer):** Tìm kiếm NeuralMemory/codebase → Tìm standard libraries/SDKs → Chỉ code mới nếu 2 bước trên thất bại.
3. **Completion Status Protocol:** 4 trạng thái rõ ràng: `DONE`, `DONE_WITH_CONCERNS`, `BLOCKED`, `NEEDS_CONTEXT`.
4. **6 Decision Principles:** Complete > Shortcuts, Evidence > Assumptions, Standard > Custom, Explicit > Implicit, Test > Trust, Small > Big.
5. **3-Strike Escalation:** Sau 3 lần thử fix bug thất bại → STOP, báo cáo context và chờ user quyết định.
6. **Scope Freeze:** Khi debugging: KHÔNG sửa code không liên quan, KHÔNG refactor. Chỉ tập trung root cause.
7. **Boil-the-Lake Checklist:** Checklist trước khi báo DONE: error handling, edge cases, logging, cleanup, input validation...
8. **Safety Guardrails:** Chặn auto-run cho các lệnh nguy hiểm (`rm -rf`, `git push --force`, deploy production). Bắt buộc double-confirm.
9. **Mindful Execution (v12.5+):** Chống AI "brain fry" bằng Iteration Counter (dừng sau 3 lần polish), Scope Guard, và Milestone Rest.

---

## 🚀 Quick Start

### Cài đặt (3 bước)

```bash
# 1. AWKit Core (CLI + workflows + skills)
npm install -g @leejungkiin/awkit
awkit install

# 2. Symphony (Task Management & Multi-Agent Orchestration)
npm install -g @leejungkiin/awkit-symphony

# 3. Optional: NeuralMemory pack (AI Memory Engine — requires Python >= 3.11)
pip install neural-memory
nmem init

# Verify
awkit doctor
symphony --version
nmem --version
```

> 💡 `awkit install` giờ chỉ cài **core runtime profile** cho **active platform** mặc định để giữ context nhẹ và tránh generate artifact không cần thiết cho Cline/Claude.
> Các skill chuyên sâu theo domain sẽ được bật sau bằng `awkit enable-pack <name>`.
> Dùng `awkit install --all` chỉ khi anh/chị thực sự muốn regenerate tất cả platform cùng lúc.


## 📦 Commands

| Command | Description |
|---------|-------------|
| `awkit install` | Deploy AWKit core runtime vào active platform hiện tại |
| `awkit install --all` | Deploy AWKit core runtime cho mọi platform được hỗ trợ |
| `awkit update` | Update lên version mới nhất |
| `awkit init` | Khởi tạo project mới (tạo .project-identity, CODEBASE.md, etc.) |
| `awkit sync` | Full sync: harvest + install (one shot) |
| `awkit status` | So sánh repo vs installed (diff view) |
| `awkit harvest` | Pull từ `~/.gemini/antigravity/` về repo |
| `awkit doctor` | Kiểm tra sức khoẻ installation |
| `awkit enable-pack <name>` | Kích hoạt skill pack |
| `awkit disable-pack <name>` | Vô hiệu skill pack |
| `awkit list-packs` | Xem danh sách skill packs |
| `awkit tg setup` | Cài đặt Telegram Bot Token, Chat ID & Topic |
| `awkit tg send <msg>` | Gửi tin nhắn qua Telegram |
| `awkit version` | Show version |

### Typical Workflow

```bash
# 1. Check what's out of sync
awkit status

# 2a. You edited in ~/.gemini/ → pull back to repo
awkit harvest

# 2b. You edited in repo → deploy to active runtime
awkit install

# 2b-alt. Regenerate every platform on purpose
awkit install --all

# 2c. Both directions (full round-trip)
awkit sync

# 3. Commit the snapshot
git add -A && git commit -m "chore: sync AWKit v1.5.0"
```



```
main-awf/ (AWKit v1.5.x — Source of Truth)
├── bin/
│   ├── awk.js                  ← CLI entry point
│   └── awf.js                  ← (legacy, kept for reference)
├── core/
│   ├── GEMINI.md               ← Master AI config (v6.4+)
│   ├── AGENTS.md               ← Agent rules
│   └── orchestrator.md         ← Orchestrator skill
├── workflows/                  ← 75+ workflows, categorized
│   ├── lifecycle/              plan, code, debug, deploy...
│   ├── context/                recap, next, save-brain...
│   ├── quality/                audit, performance, ux...
│   ├── ui/                     visualize, design-to-ui...
│   ├── ads/                    ads-audit, optimize...
│   ├── mobile/                 maestro, turbo-build...
│   ├── expert/                 planExpert, codeExpert...
│   ├── git/                    commit, hotfix, rollback...
│   ├── roles/                  tech-lead, pm, qa...
│   ├── meta/                   customize, file-protection...
│   └── _uncategorized/         misc files
├── skills/                     ← Source skill library
│   ├── orchestrator/
│   ├── memory-sync/
│   ├── brainstorm-agent/
│   ├── symphony-orchestrator/
│   ├── awf-session-restore/
│   └── ...
├── skill-packs/                ← Optional add-ons, installed on demand
│   ├── mobile-ios/
│   ├── mobile-android/
│   ├── marketing/
│   ├── creator-studio/
│   ├── neural-memory/
│   └── superpowers/
├── schemas/                    ← JSON schemas
├── templates/                  ← Project templates
├── scripts/
│   └── harvest.js              ← Migration: pull from ~/.gemini/
├── VERSION                     → 1.5.0
└── package.json                (@leejungkiin/awkit)
```

## 🌾 Harvest (Migration)

Nếu bạn chỉnh sửa trực tiếp trong `~/.gemini/antigravity/` và muốn sync về repo:

```bash
# Xem trước (không thay đổi file)
node scripts/harvest.js --dry-run

# Thực thi harvest
node scripts/harvest.js
```

## 🔄 Workflow

```
main-awf/ (edit here)
    │
    ▼  awkit install
~/.gemini/antigravity/ (runtime)
    │
    ▼  AI reads from here
Gemini / Claude / Any AI
```

## 🪶 Lean Runtime

`awkit install` no longer copies the full source skill library into runtime by default.

- Default install = **core work profile** only: orchestration, planning, debugging, verification, review, and project coordination.
- Default target = **active platform only**, which keeps repo-local generated files like `CLAUDE.md` and `.clinerules/*` untouched unless you explicitly choose them.
- Domain-heavy skills like mobile reverse engineering, ASO/marketing, and media production stay out of runtime until you opt in.
- `awkit status` now compares runtime against the active core profile + enabled packs, so optional skills no longer show as false drift.
- Re-running `awkit install` archives old managed optional skills from runtime, which helps shrink the skill catalog exposed to the agent.

## 📨 Telegram Integration

Bạn có thể cấu hình AWKit gửi thông báo tự động (deploy xong, test pass...) qua Telegram:

```bash
# 1. Setup Bot Token, Chat ID và Message Thread ID (Topic)
awkit tg setup

# 2. Gửi thử tin nhắn kiểm tra
awkit tg send "Hello from AWKit!"

# 3. Gửi đến chat/topic cụ thể
awkit tg send "Hello" --chat -100123456789 --topic 1234
```

## 🧠 GitNexus Code Intelligence

AWKit (từ bản cập nhật tích hợp mới) sử dụng **GitNexus** làm engine cung cấp Code Intelligence & Knowledge Graph cho AI Agent. Sau khi chạy `npm install` AWKit, GitNexus sẽ sẵn sàng để dùng ngay.

Để kích hoạt GitNexus trên bất kỳ project nào anh/chị đang code:

```bash
# 1. Quét toàn bộ project để tạo knowledge graph (chỉ cần chạy lần đầu hoặc khi cấu trúc code thay đổi lớn)
npx @duytransipher/gitnexus analyze

# 2. Setup MCP servers và skills tự động cho Antigravity và các editors khác:
npx @duytransipher/gitnexus setup
```

AI agent của hệ thống cũng tự động gọi qua cổng GitNexus bằng MCP Tools để tự phân tích rủi ro trước khi commit!

## 📦 Skill Packs

```bash
awkit list-packs
awkit enable-pack neural-memory
awkit enable-pack mobile-ios
awkit enable-pack mobile-android
awkit enable-pack marketing
awkit enable-pack creator-studio
```

## 🏗️ Versioning

| Version | Name | Notes |
|---------|------|-------|
| 4.x | AWF v4 | Shell-based, `awf-` prefix skills |
| 5.x | Antigravity v5 | Node.js, Symphony integration |
| 6.x | AWF v6 | main-awf, multiple sources |
| **1.1.x** | **AWKit v1.1.9** | **Single source of truth, Native CLI, Telegram Integration** |
| **1.5.x** | **AWKit v1.5.0** | **Unified Orchestration, Symphony 1.5.0, 7-Gate Intelligence** |
| **12.5.x** | **Antigravity v12.5** | **Mindful Checkpoints (TP-ITER, TP-SCOPE, TP-REST), @duytransipher/gitnexus** |

---

*AWKit Antigravity Workflow Kit · Created by leejungkiin*