# 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.*