# AWKit — Antigravity Workflow Kit

> **ZeroTeamDev Fork** · Antigravity v12.6 · npm package v1.7.5 · Single Source of Truth · Symphony-first · Mindful execution

AWKit is a professional AI-agent orchestration framework. This repository is the single source of truth for workflows, skills, core rules (GEMINI.md), and installation tooling (no more scattered configs across multiple repos) maintained by **ZeroTeamDev**.

---

## 🚀 Hướng dẫn nhanh cho người mới bắt đầu (Beginner's Guide)

Chào mừng bạn đến với **AWKit CLI**. Dưới đây là hướng dẫn từng bước kèm ví dụ cụ thể giúp bạn làm quen và vận hành hệ thống một cách nhanh chóng.

### 1. Luồng làm việc cơ bản (The Daily Workflow Loop)
AWKit hoạt động dựa trên cơ chế đồng bộ giữa **Thư mục dự án (Source of Truth)** và **Thư mục Runtime** nơi AI thực sự đọc cấu hình (`~/.gemini/antigravity/`).

```text
main-awf/ (Thư mục dự án)  ── awkit install ──>  ~/.gemini/antigravity/ (Runtime của AI)
                          <── awkit harvest ── 
                          <──  awkit sync   ──>
```

*   **Quy tắc vàng**: 
    *   Mọi thay đổi về cấu hình, luật AI (`core/GEMINI.md`, `AGENTS.md`) hay workflows cần được thực hiện trong **Thư mục dự án (main-awf/)**.
    *   Sau khi sửa xong, bắt buộc chạy `awkit install` để cập nhật lên Runtime.

### 2. Ví dụ thực hành từng bước (Step-by-Step Examples)

#### Ví dụ 1: Kiểm tra trạng thái đồng bộ
Xem có sự sai lệch nào giữa thư mục dự án và thư mục runtime của AI hay không:
```bash
awkit status
```
*Ý nghĩa:* Giúp bạn biết các thay đổi bạn vừa thực hiện trên máy đã được triển khai cho AI chưa, hoặc AI có tự ý sửa đổi file nào ở runtime không.

#### Ví dụ 2: Khởi tạo một dự án mới
Để bắt đầu một dự án mới và tích hợp sẵn cấu trúc chuẩn của AWKit:
```bash
awkit init
```
*Ý nghĩa:* Lệnh này sẽ tự động sinh ra các file cấu hình quan trọng như `.project-identity`, `CODEBASE.md` và cấu trúc thư mục ban đầu.

#### Ví dụ 3: Triển khai các thay đổi lên Runtime
Giả sử bạn vừa cập nhật luật AI mới trong file `core/GEMINI.md` tại thư mục dự án. Hãy deploy lên Runtime để AI nhận diện:
```bash
awkit install
```
*Ý nghĩa:* Copy các cấu hình mới nhất từ thư mục dự án sang runtime của AI.

#### Ví dụ 4: Đồng bộ ngược từ Runtime về Thư mục dự án
Nếu AI tự tạo các file brainstorm hoặc chỉnh sửa file trực tiếp tại runtime và bạn muốn kéo các thay đổi đó về thư mục dự án:
```bash
awkit harvest
```
*Ý nghĩa:* Đồng bộ ngược từ runtime về thư mục code gốc để lưu trữ/commit.
> **Mẹo:** Bạn có thể chạy `awkit sync` để thực hiện cả `harvest` và `install` cùng một lúc.

#### Ví dụ 5: Commit code an toàn bằng Gate tự động
Thay vì dùng lệnh `git commit` trực tiếp, hãy dùng gate của AWKit để tự động kiểm tra cú pháp và build trước khi commit:
```bash
awkit gate git auto "feat(docs): add beginner quickstart guide to readme"
```

### 3. Các lệnh hữu ích khác để kiểm tra hệ thống
*   **Chẩn đoán lỗi cài đặt:** `awkit doctor`
*   **Xem danh sách các model AI đang chạy:** `awkit config models`
*   **Mở Kanban Board quản lý tác vụ:** `symphony board` (hoặc `kanban`)

---

## 👥 Git Team Workflow (ZeroTeamDev)

This repository is a fork of [babyskill/awk](https://github.com/babyskill/awk) for the Git team's internal development.

### Keeping Fork Updated (Sync with Upstream)

To fetch and merge the latest updates from the upstream repository (`babyskill/awk`):

```bash
# Fetch latest changes from upstream
git fetch upstream

# Merge upstream changes into your active branch (e.g., main)
git checkout main
git merge upstream/main

# Push updates back to ZeroTeamDev fork
git push origin main
```

---

## Core Principles

AWKit (Antigravity v12+) enforces a small set of non-negotiable principles to keep AI work safe and effective:

1. **Anti-sycophancy**: push back when an approach has red flags; do not agree blindly.
2. **Search before building (3-layer)**: check NeuralMemory/codebase first → then standard libraries/SDKs → only write new code as a last resort.
3. **Completion status protocol**: use one of `DONE`, `DONE_WITH_CONCERNS`, `BLOCKED`, `NEEDS_CONTEXT`.
4. **Decision principles**: Complete > Shortcuts, Evidence > Assumptions, Standard > Custom, Explicit > Implicit, Test > Trust, Small > Big.
5. **3-strike escalation**: after 3 failed attempts at fixing the same issue, stop and report context for a decision.
6. **Scope freeze for debugging**: no unrelated edits, no refactors; focus on root cause.
7. **"Boil-the-lake" checklist before DONE**: error handling, edge cases, logging, cleanup, input validation, etc.
8. **Safety guardrails**: block dangerous commands by default; require double confirmation.
9. **Mindful execution (v12.5+)**: iteration counter, scope guard, milestone rest.

---

## Quick Start

### Install (recommended paths)

### Option A: Install from ZeroTeamDev Fork (Recommended for Git Team)

You can install AWKit directly from this fork repository via Git without configuring npm GitHub Packages.

**Using HTTPS (for public/configured access):**
```bash
npm install -g ZeroTeamDev/awk && awkit install
```

**Using SSH (if you use SSH keys for GitHub):**
```bash
npm install -g git+ssh://git@github.com:ZeroTeamDev/awk.git && awkit install
```

---

### Option B: Install official upstream release (Requires GitHub Packages Auth)

If you prefer to install the official package published on `@babyskill` registry:

```bash
# Authenticate and configure npm package registry
gh auth login --web
npm config set @babyskill:registry https://npm.pkg.github.com
npm config set //npm.pkg.github.com/:_authToken "$(gh auth token)"

# Install and initialize
npm install -g @babyskill/awkit && awkit install
```

---

### Option C: Complete Setup with Symphony & NeuralMemory

For full capabilities, run:

```bash
# 1) Install AWKit (from ZeroTeamDev Fork)
npm install -g ZeroTeamDev/awk && awkit install

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

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

# 4) Verify installation
awkit doctor
```

Notes:

- `awkit install` installs only the core runtime profile for the active platform by default (keeps context lean).
- Enable domain-heavy packs later via `awkit enable-pack <name>`.
- Use `awkit install --all` only if you explicitly want to regenerate every supported platform.

---

## CLI Commands

| Command | Description |
|---------|-------------|
| `awkit install` | Install AWKit core runtime to the active platform |
| `awkit install --all` | Install AWKit core runtime for all supported platforms |
| `awkit update` | Update to the latest version |
| `awkit init` | Initialize a new project (creates `.project-identity`, `CODEBASE.md`, etc.) |
| `awkit sync` | Full sync: harvest + install (one shot) |
| `awkit status` | Compare repo vs installed runtime (diff view) |
| `awkit harvest` | Pull from `~/.gemini/antigravity/` back into this repo |
| `awkit doctor` | Health checks for installation |
| `awkit list-packs` | List optional skill packs |
| `awkit enable-pack <name>` | Enable a skill pack |
| `awkit disable-pack <name>` | Disable a skill pack |
| `awkit gate ...` | Execute gated automation (git/trello/telegram) |
| `awkit tg setup` | Configure Telegram bot token, chat id, and topic |
| `awkit tg send <msg>` | Send a Telegram message |
| `awkit version` | Print version |

### Typical Workflow

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

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

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

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

# 3) Commit safely (gated)
awkit gate git auto "chore: sync AWKit snapshot"
```

---

## Repository Layout

```text
main-awf/ (Source of Truth)
├── bin/                        # CLI entry points
├── core/                       # Core rules/routing for agents
├── workflows/                  # Workflow library
├── skills/                     # Source skill library
├── schemas/                    # JSON schemas
├── templates/                  # Project templates
├── scripts/                    # Harvest, automation gate, tooling
└── package.json                # @babyskill/awkit
```

---

## Harvest (Migration)

If you edited files directly in `~/.gemini/antigravity/` and want to sync them back to this repo:

```bash
# Preview (no changes)
node scripts/harvest.js --dry-run

# Execute harvest
node scripts/harvest.js
```

---

## Runtime Model

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

---

## Lean Runtime

`awkit install` does not copy the entire source skill library into runtime by default.

- Default install = core work profile only (orchestration, planning, debugging, verification, review, coordination).
- Default target = active platform only, keeping platform-specific generated artifacts untouched unless explicitly requested.
- Domain-heavy packs (reverse engineering, marketing/ASO, media production, etc.) are excluded until you opt in.
- `awkit status` compares runtime against the core profile + enabled packs (optional packs do not create false drift).

---

## Automation Gate

AWKit provides a gated automation layer that reads `.project-identity` and enforces `automation.*` before executing:

```bash
awkit gate git commit "chore: update"
awkit gate git push
awkit gate git auto "chore: update"

awkit gate trello complete "Task Name"
awkit gate trello comment "Progress note..."
awkit gate trello block "Reason"

awkit gate telegram send "Message"
```

---

## Telegram Integration

Configure AWKit to send notifications (e.g., after pushes, tests, deploys):

```bash
# Setup bot token, chat id, and thread id (topic)
awkit tg setup

# Send a test message
awkit tg send "Hello from AWKit!"

# Send to a specific chat/topic
awkit tg send "Hello" --chat -100123456789 --topic 1234
```

---

## GitNexus Code Intelligence

AWKit integrates GitNexus for code intelligence and knowledge graphs.

You can run GitNexus commands directly via simplified top-level `awkit` shortcuts:

```bash
# 1) Build/refresh a knowledge graph for the current codebase
awkit index

# 2) View current project index information (or 'awkit gn status')
awkit status gn

# 3) List all indexed repositories in the registry
awkit list

# 4) Interactively cleanup stale or unused indexes
awkit clean
```

---

## Multi-Agent & CLI Configuration

AWKit integrates third-party CLI agents (Claude, Codex, Qwen) to optimize reasoning quality and speed:
- **Claude CLI** ➜ Architect planning & complex reasoning (Gate 2/4)
- **Codex CLI** ➜ UI shell design, asset generation & reviews (Gate 2.5/5)
- **Qwen Coder** ➜ Fast local boilerplate code execution (Gate 4)
- **Gemini Flash** ➜ Central coordination, active context & fallback routing

### CLI Configuration & Runner Controls

Manage AI runners, tiers, and system alerts via `awkit config`:

```bash
# 1) List current configurations (runners, audio status, etc.)
awkit config list

# 2) Check runner status, binary paths, and system availability
awkit config runners

# 3) Show the project's active model policies and defaults
awkit config models

# 4) Enable/disable a runner or configure completion chimes
awkit config claude <on|off>
awkit config audio <on|off>
```

### 9Router Proxy & Custom Provider Routing

AWKit supports connecting custom models and API endpoints via **9Router Proxy** (OpenAI-compatible). This is useful for utilizing remote/private models in `models.runner` or running sub-agents with custom provider paths (e.g., `ag/gemini-3-flash`, `alibaba/qwen3.7-max`).

#### 1) Configuration via TUI

Run the interactive TUI configuration menu:
```bash
awkit config
```
Choose the option **9Router Proxy Manager** to configure:
- **Enabled**: `true`/`false`
- **Base URL**: `http://192.168.50.59:20127/v1` (or your custom 9Router API gateway)
- **API Key**: `sk-...`

#### 2) Multi-Model Syncing

Sync online models configured in your 9Router server back to AWKit's registry:
```bash
awkit model sync
```

#### 3) Custom Provider Paths Routing (e.g. `<provider>/<model_name>`)

When you specify a model ID containing a slash `/` (representing a provider path), AWKit automatically uses the Codex CLI with isolated session profiles (`scratch/codex-tmp/`) to bypass any local ChatGPT account session, and configures a custom OpenAI provider routing requests to 9Router.

You can run commands directly with:
```bash
awkit exec -m ag/gemini-3-flash "Say hello in 3 words"
```
Or define them inside `.project-identity` under `models.runner` to assign tasks to custom models on 9Router.

---

## 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
awkit enable-pack game-design
```

---

## License

MIT