@leejungkiin/awkit 1.1.1 → 1.1.2

package/core/GEMINI.md

@@ -1,6 +1,6 @@
-# GEMINI.md — Antigravity v10.0
+# GEMINI.md — Antigravity v11.0
 
-> Rules + routing only. Gate details → skills. Updated: 2026-03-10
+> Rules + routing only. Gate details → skills. Updated: 2026-03-18
 
 ---
 
@@ -8,7 +8,6 @@
 
 - Bạn là **Antigravity Orchestrator**.
 - Pragmatic. Regression-averse. Symphony-first. Multi-project.
-- Luôn khai báo mô hình trước mỗi câu trả lời
 
 ---
 
@@ -33,8 +32,9 @@ Mỗi skill tự xử lý gate logic riêng — xem SKILL.md của từng skill.
 
 ### Exit Protocol
 
-- Task done → `nm-memory-sync` auto-save (W1–W4 triggers).
-- Brainstorm/analysis artifact tạo → auto POST metadata vào Symphony Notes (W7 trigger).
+- Task done → auto-complete Symphony → **BẮT BUỘC** `symphony next` + present gợi ý.
+- Kết thúc message → **LUÔN** kèm "Next steps" section.
+- `nm-memory-sync` auto-save (W1–W4 triggers).
 - Deploy/push → kiểm tra in-progress tasks trước, confirm với user.
 
 ---
@@ -50,6 +50,11 @@ Mỗi skill tự xử lý gate logic riêng — xem SKILL.md của từng skill.
 - AI models: Gemini 2.5+ only.
 - Firebase: Firebase AI Logic SDK.
 
+### Spec-First (NEW v11.0)
+- PLANNING mode PHẢI đọc `docs/specs/` **trước** khi viết `implementation_plan.md`.
+- Mỗi task trong plan NÊN có format XML `<task>` (xem `templates/specs/task-spec-template.xml`).
+- `implementation_plan.md` PHẢI reference `TECH-SPEC.md` constraints khi relevant.
+
 ### NeuralMemory
 - Brain = projectId. Switch trước mọi nmem call.
 - Mọi `nmem_remember()` PHẢI tag projectId.
@@ -62,16 +67,8 @@ Mỗi skill tự xử lý gate logic riêng — xem SKILL.md của từng skill.
 - Kết thúc task: Tóm tắt + Test + Next steps.
 - Không rõ: Hỏi lại, tối đa 2 lần.
 
-### Project Context (CODEBASE Gate)
-
-> [!CAUTION]
-> TRƯỚC KHI dùng `grep_search` / `codebase_search` / `list_dir` → **PHẢI đọc CODEBASE.md** của project đó.
-> Bỏ qua = vi phạm. KHÔNG CÓ NGOẠI LỆ.
-
-- **Quy trình bắt buộc:** Đọc CODEBASE.md → xác định file/layer target → search cụ thể.
-- **KHÔNG search "mù"** (search mà chưa biết project structure).
-- CODEBASE.md là **bản đồ project** — dạng compact (path + purpose). Đọc nhanh, tốn ít context.
-- KHÔNG scan raw directory (`list_dir`, `find_by_name`) nếu đã có CODEBASE.md.
+### Project Context
+- CODEBASE.md tồn tại → KHÔNG scan raw directory.
 - KHÔNG hỏi user về project structure.
 - CODEBASE.md outdated → ghi chú "⚠️ dùng /codebase-sync".
 
@@ -88,9 +85,9 @@ Mỗi skill tự xử lý gate logic riêng — xem SKILL.md của từng skill.
 
 ## Routing
 
-- **Execution order:** `symphony-orchestrator` → `awf-session-restore` → `nm-memory-sync` → `orchestrator` → action
+- **Execution order:** `symphony-orchestrator` → `awf-session-restore` → `nm-memory-sync` → `symphony-enforcer` → `orchestrator` → action
 - **Skill catalog:** xem `orchestrator/SKILL.md`
-- **Workflows:** 75+ (`/xxx`). Core: `/plan` `/code` `/debug` `/recap` `/next` `/todo`
+- **Workflows:** 75+ (`/xxx`). Core: `/init` `/code` `/debug` `/recap` `/next` `/todo`
 - **Shortcuts:** `/todo` `/done` `/next`
 
 ---

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@leejungkiin/awkit",
-  "version": "1.1.1",
-  "description": "AWKit v1.0.9 — Antigravity Workflow Kit. Unified AI agent orchestration system.",
+  "version": "1.1.2",
+  "description": "AWKit v1.1.2 — Antigravity Workflow Kit. Unified AI agent orchestration system.",
   "main": "bin/awk.js",
   "bin": {
     "awkit": "bin/awk.js",

package/skills/orchestrator/SKILL.md

@@ -40,10 +40,6 @@ context_intent:
 ads_intent:
   keywords: ["ads", "campaign", "CPI", "ROAS", "quảng cáo"]
   action: Suggest `/ads-audit` or `/adsExpert`
-
-conductor_intent:
-  keywords: ["analyze project", "phân tích project", "review toàn bộ", "cross-module", "refactor lớn", "conductor", "CLI analysis", "second opinion", "kiến trúc tổng"]
-  action: Auto-activate `gemini-conductor` skill or suggest `/conductor`
 ```
 
 ### 3. Skill Pack Check

package/skills/symphony-enforcer/SKILL.md

@@ -4,12 +4,13 @@ description: |
   Mandatory Symphony checkpoint system. Ensures AI never forgets to create,
   update, or complete tasks in Symphony. Enforces progress reporting at every
   milestone and auto-detects task completion without waiting for user confirmation.
+  v3.1: Pre-Plan Gate, Auto-Lifecycle, Auto-Next, Atomic Git Commits.
 metadata:
   stage: core
-  version: "2.0"
-  replaces: null
+  version: "3.1"
+  replaces: "v2.0"
   requires: symphony-orchestrator
-  tags: [symphony, enforcement, checkpoint, task-lifecycle, core]
+  tags: [symphony, enforcement, checkpoint, task-lifecycle, core, spec-first, auto-next]
 agent: Symphony Enforcer
 allowed-tools:
   - symphony_create_task
@@ -23,11 +24,15 @@ invocation-type: auto
 priority: 1
 ---
 
-# Symphony Enforcer — Mandatory Task Lifecycle Checkpoints
+# Symphony Enforcer v3.1 — Spec-First + Auto-Lifecycle + Auto-Next + Atomic Commits
 
 > **Purpose:** Đảm bảo AI KHÔNG BAO GIỜ quên cập nhật Symphony.
-> **Method:** Strict sequential protocol + 4 Trigger Points.
-> **Key Principle:** AI tự detect completion — user KHÔNG CẦN nói "xong".
+> **Key Changes v3.1:**
+> - **Pre-Plan Gate**: Đọc spec trước khi plan, hỏi user về constraints
+> - **Auto-Lifecycle**: Liên kết task_boundary ↔ Symphony tự động
+> - **Auto-Next**: BẮT BUỘC gợi ý next steps sau mỗi task done
+> - **Atomic Git Commits**: Tự động commit sau mỗi task done (NEW v3.1)
+> **Principle:** AI tự detect completion — user KHÔNG CẦN nói "xong".
 
 ---
 
@@ -35,34 +40,28 @@ priority: 1
 
 ```
 KHÔNG CÓ NGOẠI LỆ:
-- Mọi code/debug/plan task PHẢI qua STRICT STARTUP PROTOCOL (5 steps)
+- Mọi code/debug/plan task PHẢI qua STRICT STARTUP PROTOCOL
 - Mọi milestone PHẢI report progress
 - AI tự detect completion và auto-complete task
+- Task done → PHẢI atomic git commit trước khi suggest next
+- Kết thúc task PHẢI kèm next suggestion
 - BỎ QUA BẤT KỲ STEP NÀO = VI PHẠM
 ```
 
 ---
 
-## 🔒 STRICT STARTUP PROTOCOL (BẮT BUỘC — KHÔNG ĐƯỢC BỎ QUA)
+## 🔒 STRICT STARTUP PROTOCOL (BẮT BUỘC)
 
-Mỗi khi bắt đầu task code/debug/plan, AI PHẢI đi qua **4 steps tuần tự**.
-KHÔNG được bắt đầu work cho đến khi TẤT CẢ 4 steps đều ✅.
-
-> **Note:** Symphony server + project registration đã được `symphony-orchestrator` xử lý
-> trước khi skill này chạy. Enforcer chỉ lo `.project-identity` → Brain → Task.
+Mỗi khi bắt đầu task code/debug/plan, AI PHẢI đi qua **5 steps tuần tự**.
+KHÔNG được bắt đầu work cho đến khi TẤT CẢ steps ✅.
 
 ### Step 1: Project Identity — `.project-identity`
 
 ```
-→ Kiểm tra: file .project-identity có tồn tại trong project root?
-→ CÓ  → Đọc projectId, projectName từ file
-→ KHÔNG → ⛔ DỪNG LẠI. Hỏi user hoặc tạo .project-identity:
-         {
-           "id": "project-slug",
-           "name": "Project Name",
-           "path": "/absolute/path"
-         }
-→ Output: "📋 Step 1/4: Project Identity ✅ — {projectId}"
+→ Kiểm tra: file .project-identity có tồn tại?
+→ CÓ  → Đọc projectId, projectName
+→ KHÔNG → ⛔ DỪNG. Hỏi user hoặc tạo .project-identity.
+→ Output: "📋 Step 1/5: Project Identity ✅ — {projectId}"
 ```
 
 ### Step 2: NeuralMemory Brain — Switch brain
@@ -70,42 +69,74 @@ KHÔNG được bắt đầu work cho đến khi TẤT CẢ 4 steps đều ✅.
 ```
 → nmem brain use <projectId>
 → nmem_recap(level=1) — load context
-→ Output: "🧠 Step 2/4: Brain ✅ — switched to {projectId}"
+→ Output: "🧠 Step 2/5: Brain ✅ — switched to {projectId}"
+```
+
+### Step 3: Spec Alignment — Đọc Project Spec (NEW v3.0)
+
+```
+→ Kiểm tra: docs/specs/PROJECT.md tồn tại?
+→ CÓ  → Đọc silent: PROJECT.md + TECH-SPEC.md + REQUIREMENTS.md
+       → Extract constraints liên quan đến task hiện tại
+       → NẾU PLANNING mode:
+          - Hỏi user 1-3 câu về constraints/UX cụ thể của feature
+          - Ví dụ: "Feature này cần offline support không?"
+          - Ví dụ: "UI nên dạng list hay cards?"
+       → Output: "📐 Step 3/5: Spec Aligned ✅"
+→ KHÔNG → Skip (project chưa /init) → "📐 Step 3/5: No spec — skipped"
 ```
 
-### Step 3: Symphony Task — Tạo hoặc nhận task
+> **Quan trọng:** Nếu TECH-SPEC.md có "Constraints & Non-Negotiables",
+> AI PHẢI tuân thủ chúng trong implementation_plan.md.
+
+### Step 4: Symphony Task — Tạo hoặc nhận task
 
 ```
 → symphony_available_tasks(filter="my") → check active tasks
 → CÓ task in_progress phù hợp → dùng tiếp
 → CÓ task ready phù hợp → symphony_claim_task
-→ KHÔNG CÓ → symphony_create_task(title, description)
-            → symphony_claim_task(new_task_id)
-→ Lưu task_id cho TP1-TP3
-→ Output: "🎯 Step 3/4: Task ✅ — #sym-XYZ claimed"
+→ KHÔNG CÓ → symphony_create_task(title) → symphony_claim_task(new_id)
+→ Lưu task_id cho TP1-TP4
+→ Output: "🎯 Step 4/5: Task ✅ — #sym-XYZ claimed"
 ```
 
-### Step 4: Confirmation Block — Hiển thị tổng kết
+### Step 5: Confirmation Block
 
 ```
 🚦 STARTUP PROTOCOL COMPLETE
 ══════════════════════════════════════
   Step 1: 📋 Project Identity  ✅  {projectId}
   Step 2: 🧠 NeuralMemory      ✅  brain: {projectId}
-  Step 3: 🎯 Task              ✅  #sym-XYZ — "{title}"
-  Step 4: ✅ READY TO WORK
+  Step 3: 📐 Spec Alignment     ✅  {constraints_count} constraints loaded
+  Step 4: 🎯 Task              ✅  #sym-XYZ — "{title}"
+  Step 5: ✅ READY TO WORK
 ══════════════════════════════════════
 ```
 
-> ⛔ **Nếu KHÔNG hiển thị confirmation block = VI PHẠM — KHÔNG ĐƯỢC BẮT ĐẦU WORK**
+> ⛔ **Nếu KHÔNG hiển thị confirmation block = VI PHẠM**
+
+---
+
+## Auto-Lifecycle: task_boundary ↔ Symphony (NEW v3.0)
+
+```
+LIÊN KẾT TỰ ĐỘNG:
+- task_boundary(PLANNING)  → symphony_create_task (nếu chưa có)
+- task_boundary(EXECUTION) → symphony_report_progress(40%)
+- task_boundary(VERIFICATION) → symphony_report_progress(80%)
+- notify_user(BlockedOnUser=false) → TRIGGER TP2 (completion check)
+```
+
+AI PHẢI giữ `current_task_id` xuyên suốt session.
+Mỗi lần gọi `task_boundary` với mode mới → đồng thời report progress.
 
 ---
 
-## Trigger Points (Trong quá trình làm việc)
+## Trigger Points
 
-### TP1: Progress Milestone — Tại mỗi giai đoạn quan trọng
+### TP1: Progress Milestone
 
-**Khi nào:** Bất kỳ milestone nào xảy ra:
+**Khi nào:** Milestone xảy ra:
 - Chuyển mode: PLANNING → EXECUTION → VERIFICATION
 - Gọi `notify_user` (TRƯỚC khi gọi)
 - Hoàn thành 1 component/file lớn
@@ -116,11 +147,11 @@ KHÔNG được bắt đầu work cho đến khi TẤT CẢ 4 steps đều ✅.
 symphony_report_progress(
   task_id=current_task,
   progress=estimated_percentage,
-  last_action="mô tả ngắn milestone"
+  last_action="mô tả ngắn"
 )
 ```
 
-**Progress Estimation Guide:**
+**Progress Guide:**
 ```
   10% — Task created, đang research/đọc code
   25% — Implementation plan approved
@@ -137,7 +168,7 @@ symphony_report_progress(
 
 ---
 
-### TP2: Task Complete — AI tự detect hoàn thành
+### TP2: Task Complete — Auto-detect
 
 **Khi nào:** AI detect ≥2/4 completion signals:
 
@@ -145,7 +176,7 @@ symphony_report_progress(
 Signal 1: Final notify_user với BlockedOnUser=false
 Signal 2: Walkthrough artifact đã tạo
 Signal 3: Tất cả checklist items trong task.md đã [x]
-Signal 4: Verification pass (tests chạy OK, build thành công)
+Signal 4: Verification pass (tests OK, build OK)
 ```
 
 **Action:**
@@ -155,12 +186,55 @@ Signal 4: Verification pass (tests chạy OK, build thành công)
      summary="mô tả ngắn kết quả"
    )
 2. Hiển thị: "✅ SYM #sym-XYZ — Done"
-3. KHÔNG cần chờ user confirm
+3. → TRIGGER TP2.5 (Atomic Git Commit)
+4. → TRIGGER TP4 (Auto-Next) NGAY LẬP TỨC
 ```
 
-**Nếu user thấy chưa xong:**
-- User chỉ cần nói → AI reopen task và tiếp tục
-- Không phải lỗi — đây là flow bình thường
+---
+
+### TP2.5: Atomic Git Commit (NEW v3.1 — BẮT BUỘC)
+
+**Khi nào:** Ngay sau TP2 (task completed), TRƯỚC TP4 (Auto-Next).
+Chỉ trigger khi task có code changes (có files_changed).
+
+**Action:**
+```
+1. Kiểm tra: git status --porcelain
+   → Nếu KHÔNG CÓ changes → skip ("📝 No code changes to commit")
+   → Nếu CÓ changes → tiếp tục
+
+2. Xác định commit type từ task context:
+   → PLANNING/EXECUTION mới → "feat"
+   → Debug/fix → "fix"
+   → Refactor/cleanup → "refactor"
+   → Docs/specs → "docs"
+
+3. Tạo commit message theo Conventional Commits:
+   → Format: "{type}({scope}): {task_summary_ngắn}"
+   → scope = module/feature name (từ task title)
+   → Ví dụ: "feat(auth): implement login with Firebase"
+   → Ví dụ: "fix(camera): resolve 10s delay on tab switch"
+
+4. Stage & commit:
+   → git add <files_changed từ symphony_complete_task>
+   → Nếu không rõ files → git add -A (thận trọng)
+   → git commit -m "{message}"
+
+5. Hiển thị:
+   🔀 Atomic Commit: {short_hash} — "{message}"
+   📁 {N} files changed
+
+6. ⚠️ KHÔNG AUTO-PUSH:
+   → Chỉ commit local
+   → Push = yêu cầu user confirm hoặc dùng /smart-git-ops
+```
+
+**Enforcement:**
+- ❌ KHÔNG được auto-push (chỉ commit local)
+- ❌ KHÔNG được commit nếu có unresolved merge conflicts
+- ❌ KHÔNG được commit files ngoài scope task
+- ✅ NÊN commit ngay khi task done — đừng để accumulate
+- ✅ Mỗi task = 1 commit (atomic, traceable)
 
 ---
 
@@ -173,14 +247,69 @@ Signal 4: Verification pass (tests chạy OK, build thành công)
 
 **Action:**
 ```
-symphony_abandon_task(
-  task_id=current_task,
-  reason="mô tả lý do"
-)
+symphony_abandon_task(task_id=current_task, reason="...")
 ```
 
 ---
 
+### TP4: Auto-Next Suggestion (NEW v3.0 — BẮT BUỘC)
+
+**Khi nào:** Ngay sau TP2 (task completed). KHÔNG ĐƯỢC BỎ QUA.
+
+**Action:**
+```
+1. ĐỌC projectId từ .project-identity (đã có từ Step 1)
+2. symphony task list -P <projectId> -s ready (CHỈ tasks cùng project)
+   ⚠️ TUYỆT ĐỐI KHÔNG dùng filter="ready" không có project filter
+   ⚠️ Dùng CLI: symphony task list -P <projectId> -s ready
+   ⚠️ Hoặc MCP: symphony_available_tasks + parse project field
+3. Lọc top 2-3 ready tasks theo priority
+4. Present cho user:
+
+   ➡️ NEXT STEPS ({projectName})
+   ─────────────────────────────────
+   📋 #sym-A1 — Auth Module (P0, ready)
+   📋 #sym-A2 — Dashboard UI (P1, ready)
+   
+   Bạn muốn tiếp tục với task nào?
+
+5. Nếu KHÔNG CÓ ready tasks trong project hiện tại:
+   "✨ Không còn task ready cho {projectName}! Tạo task mới hoặc chuyển phase."
+```
+
+**Enforcement:**
+- ❌ KHÔNG được kết thúc conversation mà KHÔNG present next suggestion
+- ❌ KHÔNG được show tasks từ project khác
+- Nếu quên filter projectId → vi phạm nghiêm trọng (cross-project contamination)
+
+---
+
+## XML Task Spec trong Implementation Plans (NEW v3.0)
+
+Khi PLANNING mode tạo `implementation_plan.md`, MỖI task NÊN dùng XML format:
+
+```xml
+<task type="auto">
+  <name>Task name</name>
+  <files>file1.swift, file2.swift</files>
+  <spec_ref>REQUIREMENTS.md § R1</spec_ref>
+  <depends_on>none</depends_on>
+  <action>Specific instructions</action>
+  <verify>How to verify completion</verify>
+  <done>Expected final state</done>
+</task>
+```
+
+Template đầy đủ: `~/.gemini/antigravity/templates/specs/task-spec-template.xml`
+
+Lợi ích:
+- AI parse chính xác hơn markdown
+- `<spec_ref>` ép buộc liên kết với project spec
+- `<depends_on>` cho phép wave grouping (parallel execution)
+- `<verify>` built-in verification step
+
+---
+
 ## Ngoại lệ — Khi nào KHÔNG cần Startup Protocol
 
 ```
@@ -193,8 +322,6 @@ symphony_abandon_task(
 
 ## Sync Block Format
 
-Mỗi khi sync, AI hiển thị dòng ngắn:
-
 ```
 🎯 SYM #sym-XYZ — 40% → 70% "Implemented auth module"
 ```
@@ -202,6 +329,7 @@ Mỗi khi sync, AI hiển thị dòng ngắn:
 Nếu completed:
 ```
 ✅ SYM #sym-XYZ — Done "Auth module with tests"
+➡️ Next: #sym-A1 — Dashboard UI (P1)
 ```
 
 ---
@@ -211,17 +339,24 @@ Nếu completed:
 | Tình huống | Xử lý |
 |-----------|--------|
 | Project chưa có .project-identity | ⛔ Dừng, tạo file trước |
+| Project chưa có docs/specs/ | Skip Step 3, tiếp tục |
 | Symphony server down | Start server, retry. Nếu fail → warning + tiếp tục |
 | User follow-up nhỏ sau task done | ≤2 file changes → không cần task mới |
 | Nhiều task cùng lúc | Track task_id riêng, report đúng task |
 | User reopen task đã complete | Claim lại, resume từ progress cuối |
+| Không có ready tasks cho TP4 | Gợi ý tạo phase tiếp theo |
 
 ---
 
 ## Learnings
 
 - AI quên Symphony vì nó là "side task" — strict protocol biến nó thành MAIN flow
-- Step-by-step sequential = AI không thể skip — mỗi step phụ thuộc step trước
-- Confirmation block = visual proof cho user thấy đã qua protocol
-- User KHÔNG muốn nói "xong" — AI phải tự detect completion signals
-- Progress % không cần chính xác — rough estimate đủ tốt
+- Step-by-step sequential = AI không thể skip
+- Confirmation block = visual proof cho user
+- User KHÔNG muốn nói "xong" — AI phải tự detect completion
+- Pre-Plan Discussion giúp plan đúng hướng từ đầu (learned from GSD)
+- XML task format chính xác hơn markdown cho AI parsing (learned from GSD)
+- Auto-Next giữ momentum — user không cần tự tìm task tiếp theo
+- Spec alignment tránh plan bị lệch khỏi project constraints
+- Atomic commits giúp rollback chính xác — 1 task = 1 commit (learned from GSD)
+- KHÔNG auto-push — chỉ commit local, push cần user confirm

package/templates/specs/PROJECT.md

@@ -0,0 +1,50 @@
+# {{PROJECT_NAME}} — Project Spec
+
+> Created: {{DATE}} | Last Updated: {{DATE}}
+
+## Vision
+
+[1-2 sentences describing the core purpose and value proposition of this project.]
+
+## Goals
+
+1. **Primary Goal:** [What is the #1 thing this project must achieve?]
+2. **Secondary Goal:** [What else matters?]
+3. **Stretch Goal:** [Nice-to-have if time permits]
+
+## Target Audience
+
+| Segment | Description | Pain Point |
+|---------|-------------|------------|
+| Primary | [Who is the main user?] | [What problem do they face?] |
+| Secondary | [Other user group] | [Their specific need] |
+
+## Success Metrics
+
+- [ ] **Metric 1:** [e.g., 1000 DAU within 3 months]
+- [ ] **Metric 2:** [e.g., 4.5+ App Store rating]
+- [ ] **Metric 3:** [e.g., < 2s cold start time]
+
+## Scope
+
+### In Scope (v1)
+- Feature A
+- Feature B
+- Feature C
+
+### Out of Scope (v1)
+- Feature X (deferred to v2)
+- Feature Y (requires further research)
+
+## Key Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| [e.g., Backend] | [e.g., Firebase] | [Why this choice] |
+| [e.g., State Mgmt] | [e.g., SwiftUI @Observable] | [Why] |
+
+## References
+
+- [Design inspiration link]
+- [Competitor analysis link]
+- [Technical reference]

package/templates/specs/ROADMAP.md

@@ -0,0 +1,79 @@
+# {{PROJECT_NAME}} — Roadmap
+
+> Created: {{DATE}} | Last Updated: {{DATE}}
+> Source of truth: PROJECT.md
+
+## Overview
+
+| Phase | Title | Status | Priority |
+|-------|-------|--------|----------|
+| 1 | [Phase title] | 🔲 Not Started | P0 |
+| 2 | [Phase title] | 🔲 Not Started | P1 |
+| 3 | [Phase title] | 🔲 Not Started | P2 |
+
+---
+
+## Phase 1: [Title] — [Target Date]
+
+**Goal:** [What this phase delivers in 1 sentence]
+
+**Requirements Covered:** REQUIREMENTS.md § R1, R2
+
+### Features
+- [ ] Feature 1.1 — [Short description]
+- [ ] Feature 1.2 — [Short description]
+- [ ] Feature 1.3 — [Short description]
+
+### Dependencies
+- [External service / API / library needed]
+
+### Definition of Done
+- [ ] All features functional
+- [ ] Core tests passing
+- [ ] No P0 bugs
+
+---
+
+## Phase 2: [Title] — [Target Date]
+
+**Goal:** [What this phase delivers]
+
+**Requirements Covered:** REQUIREMENTS.md § R3, R4
+
+### Features
+- [ ] Feature 2.1
+- [ ] Feature 2.2
+
+### Dependencies
+- Phase 1 complete
+
+### Definition of Done
+- [ ] All features functional
+- [ ] Integration tests passing
+
+---
+
+## Phase 3: [Title] — [Target Date]
+
+**Goal:** [What this phase delivers]
+
+**Requirements Covered:** REQUIREMENTS.md § R5+
+
+### Features
+- [ ] Feature 3.1
+- [ ] Feature 3.2
+
+### Definition of Done
+- [ ] All features functional
+- [ ] Performance benchmarks met
+- [ ] Ready for production release
+
+---
+
+## Milestone Tracking
+
+| Milestone | Target | Actual | Status |
+|-----------|--------|--------|--------|
+| MVP (Phase 1) | [Date] | — | 🔲 |
+| Beta (Phase 2) | [Date] | — | 🔲 |
+| Launch (Phase 3) | [Date] | — | 🔲 |

package/templates/specs/TECH-SPEC.md

@@ -0,0 +1,81 @@
+# {{PROJECT_NAME}} — Technical Specification
+
+> Created: {{DATE}} | Last Updated: {{DATE}}
+> Companion to: PROJECT.md, REQUIREMENTS.md
+
+## Architecture Overview
+
+[1-2 sentences describing the high-level architecture pattern being used.]
+
+```
+[Simple ASCII diagram of the system architecture]
+```
+
+## Tech Stack
+
+| Layer | Technology | Version | Rationale |
+|-------|-----------|---------|-----------|
+| Language | [e.g., Swift] | [e.g., 6.0] | [Why] |
+| Framework | [e.g., SwiftUI] | [e.g., iOS 17+] | [Why] |
+| Backend | [e.g., Firebase] | [e.g., v11] | [Why] |
+| Database | [e.g., GRDB] | [e.g., 7.x] | [Why] |
+| AI/ML | [e.g., Gemini 2.5] | — | [Why] |
+| Analytics | [e.g., Firebase Analytics] | — | [Why] |
+
+## Architecture Decisions
+
+### AD-1: [Decision Title]
+
+**Context:** [What problem or question prompted this decision?]
+**Decision:** [What was decided]
+**Consequences:** [What trade-offs or implications does this have?]
+**Alternatives Considered:** [What else was evaluated?]
+
+### AD-2: [Decision Title]
+
+**Context:** [...]  
+**Decision:** [...]  
+**Consequences:** [...]
+
+## Patterns & Conventions
+
+### Code Organization
+```
+[Folder structure with descriptions]
+```
+
+### Naming Conventions
+- Files: [e.g., PascalCase for types, camelCase for functions]
+- Modules: [e.g., feature-based grouping]
+- Tests: [e.g., Test suffix, describe/it pattern]
+
+### Error Handling
+[Standard error handling approach for the project]
+
+### State Management
+[How state is managed across the app]
+
+## Constraints & Non-Negotiables
+
+> [!CAUTION]
+> These constraints MUST be followed in ALL implementation plans.
+
+1. **[Constraint 1]:** [e.g., All network calls must have offline fallback]
+2. **[Constraint 2]:** [e.g., No hardcoded strings — use localization]
+3. **[Constraint 3]:** [e.g., All AI calls must respect quota limits]
+4. **[Constraint 4]:** [e.g., Minimum iOS 17 / Android 14 support]
+
+## Security Requirements
+
+- Authentication: [e.g., Firebase Auth with Apple/Google Sign-In]
+- Data at rest: [e.g., Keychain for sensitive data]
+- API keys: [e.g., Firebase Remote Config, never hardcoded]
+
+## Performance Targets
+
+| Metric | Target | How to Measure |
+|--------|--------|----------------|
+| Cold start | < [X]s | Instruments / Profiler |
+| API response | < [X]ms | Network logs |
+| Memory | < [X]MB | Memory profiler |
+| App size | < [X]MB | Archive build |

package/templates/specs/task-spec-template.xml

@@ -0,0 +1,65 @@
+<!-- 
+  AWF Task Spec Template (XML Format)
+  
+  Usage: Copy this structure into implementation_plan.md for each task.
+  AI parses these blocks precisely during EXECUTION mode.
+  
+  Attributes:
+    type="auto"   → AI executes without user interaction
+    type="manual" → Requires user action (e.g., config, credentials)
+    
+  Elements:
+    <name>       → Short task title
+    <files>      → Comma-separated list of files to create/modify
+    <spec_ref>   → Reference to REQUIREMENTS.md or TECH-SPEC.md section
+    <depends_on> → Task names this depends on (for wave grouping)
+    <action>     → Specific implementation instructions
+    <verify>     → Command or check to verify task completion
+    <done>       → Expected final state description
+-->
+
+<!-- Example: Single independent task -->
+<task type="auto">
+  <name>Create User model</name>
+  <files>Models/User.swift, Models/UserRepository.swift</files>
+  <spec_ref>REQUIREMENTS.md § R1, TECH-SPEC.md § AD-1</spec_ref>
+  <depends_on>none</depends_on>
+  <action>
+    Create User struct with Codable conformance.
+    Implement UserRepository with GRDB persistence.
+    Follow offline-first pattern from TECH-SPEC.md.
+  </action>
+  <verify>Unit test: UserRepositoryTests — insert, fetch, delete pass</verify>
+  <done>User model persists to local DB with full CRUD</done>
+</task>
+
+<!-- Example: Dependent task -->
+<task type="auto">
+  <name>Create login endpoint</name>
+  <files>Services/AuthService.swift, ViewModels/LoginViewModel.swift</files>
+  <spec_ref>REQUIREMENTS.md § R2</spec_ref>
+  <depends_on>Create User model</depends_on>
+  <action>
+    Use Firebase Auth for authentication.
+    Store session in Keychain per TECH-SPEC.md § Security.
+    Handle offline: queue login attempt, retry on connectivity.
+  </action>
+  <verify>Login with test credentials returns valid session token</verify>
+  <done>User can log in; session persists across app restarts</done>
+</task>
+
+<!-- Example: Manual task -->
+<task type="manual">
+  <name>Configure Firebase project</name>
+  <files>GoogleService-Info.plist</files>
+  <spec_ref>TECH-SPEC.md § Tech Stack</spec_ref>
+  <depends_on>none</depends_on>
+  <action>
+    User must:
+    1. Create Firebase project at console.firebase.google.com
+    2. Download GoogleService-Info.plist
+    3. Add to Xcode project root
+  </action>
+  <verify>FirebaseApp.configure() succeeds without crash</verify>
+  <done>Firebase SDK initialized on app launch</done>
+</task>

package/workflows/lifecycle/init.md

@@ -1,152 +1,164 @@
 ---
-description: ✨ Khởi tạo dự án chuẩn Antigravity (v4.1 - Master Orchestrator)
+description: ✨ Khởi tạo dự án chuẩn Antigravity (v5.0 - Spec-First + CLI Hybrid)
 ---
 
-# WORKFLOW: /init - The Antigravity Orchestrator (v4.1)
+# WORKFLOW: /init - The Antigravity Orchestrator (v5.0)
 
-> **Mission:** Không chỉ tạo file. `/init` thiết lập toàn bộ "Hệ điều hành phát triển" (OS for Development), tích hợp sẵn tư duy Spec-First, Clean Architecture và MCP Tools.
+> **Mission:** Thiết lập "Hệ điều hành phát triển" (OS for Development) với Spec-First approach.
+> **Key Change v5.0:** Tạo Project-Level Spec (PROJECT.md, REQUIREMENTS.md, ROADMAP.md, TECH-SPEC.md) ngay từ đầu.
+> **Hybrid:** CLI scaffolds → AI fills content through brainstorm.
 
 ---
 
-## 🚀 Giai đoạn 0: Environment & MCP Check (New in v4.1)
-Trước khi làm bất cứ điều gì, kiểm tra "vũ khí":
+## 🚀 Giai đoạn 0: Environment & MCP Check
 
 1.  **MCP Status Check**:
-    *   `firebase-mcp-server`: [Check] -> Nếu thiếu, hỏi user có cần Backend/Auth không?
-    *   `maestro`: [Check] -> Nếu thiếu, warn "Sẽ không thể chạy test UI tự động".
-    *   `ios-simulator`: [Check] -> Nếu là dự án Mobile, yêu cầu bật Simulator.
-    *   `google-ads-mcp`: [Check] -> (Optional) Cho Marketing.
+    *   `firebase-mcp-server`: [Check] → Nếu thiếu, hỏi user có cần Backend/Auth không?
+    *   `maestro`: [Check] → Nếu thiếu, warn "Sẽ không thể chạy test UI tự động".
+    *   `ios-simulator`: [Check] → Nếu là dự án Mobile, yêu cầu bật Simulator.
 
-2.  **Dev Environment**:
-    *   Node/Ruby/Java/Swift versions.
-    *   Docker status (nếu là Backend).
+2.  **Dev Environment**: Node/Ruby/Java/Swift versions.
 
 ---
 
 ## ⚡ Giai đoạn 1: Context Awareness & Smart Adoption
-*Thay vì hỏi máy móc, hãy quan sát:*
 
 **Kịch bản A: Thư mục trống (New Project)**
-*   Chạy quy trình phỏng vấn **Vision Capture** (như bản cũ).
-*   Hỏi thêm: "Anh muốn dùng template có sẵn không?" (Clean Arch, Boilerplate).
+*   Chạy quy trình phỏng vấn **Vision Capture**.
+*   Hỏi: "Anh muốn dùng template có sẵn không?" (Clean Arch, Boilerplate).
 
 **Kịch bản B: Thư mục có Code (Adoption Mode)**
 *   AI quét cấu trúc hiện tại.
 *   Tự động điền `.project-identity`.
-*   Đề xuất: "Em thấy dự án này đang dùng [Stack]. Anh có muốn em setup lại folder `docs/` và `scripts/` để chuẩn hóa theo Antigravity Workflow không?"
+*   Đề xuất chuẩn hóa theo Antigravity Workflow.
 
 ---
 
-## 🧠 Giai đoạn 2: The Antigravity Core Injection
-*Đây là "bí mật" tạo nên sự khác biệt. Setup nền tảng cho các workflow nâng cao.*
+## 🧠 Giai đoạn 2: Project Skeleton
 
-### 2.1. Create Standard Ecosystem
-Tự động tạo các thư mục và file mẫu:
+1.  **Generate `.project-identity`** (Bắt buộc):
+    *   Copy template từ `~/.gemini/antigravity/templates/project-identity/[platform].json`.
+    *   Customize: Thay thế `{{DATE}}`, `projectName` bằng thông tin thực tế.
 
-1.  **Antigravity Core**:
+2.  **Create Standard Ecosystem**:
     ```bash
-    mkdir -p docs/specs/_templates
+    mkdir -p docs/specs
     mkdir -p docs/architecture/decisions
-    mkdir -p .gemini/scripts
+    mkdir -p .planning/research
     ```
 
-2.  **App Structure (Platform-Specific)**:
-    *   **Action:** Đọc template cấu trúc từ `~/.gemini/antigravity/templates/structures/[platform].txt`.
-    *   **Execute:** Tạo folder tree tương ứng.
-    *   *Ví dụ iOS:* `App/Features`, `App/Shared`, `Tests`, ...
+3.  **App Structure (Platform-Specific)**:
+    *   Đọc template từ `~/.gemini/antigravity/templates/structures/[platform].txt`.
+    *   Tạo folder tree tương ứng.
 
-### 2.2. Inject Templates (Spec & Architecture)
-Tạo file mẫu để workflow `/plan` (create-spec) hoạt động trơn tru:
+4.  **Git Setup**: `.gitignore` thông minh theo stack.
 
-**`docs/specs/_templates/requirements_template.md`**:
-*(Mẫu chuẩn Requirements từng dùng ở `create-spec-architect`)*
+---
 
-**`docs/specs/_templates/architecture_template.md`**:
-*(Mẫu chuẩn Clean Architecture Decision)*
+## 📐 Giai đoạn 3: Project Spec Generation (NEW — Spec-First)
 
-### 2.3. Inject Automation Scripts
-Tạo script để user gõ lệnh tắt là chạy workflow:
+> **Đây là bước mới quan trọng nhất.** AI brainstorm với user để tạo ra "hiến pháp" của dự án.
+> Tất cả feature-level planning SAU NÀY phải tuân theo spec này.
 
-**`scripts/scaffold_feature.sh`**:
-*(Script gọi đến `structure-clean-architect` workflow)*
+### 3.1. Copy Templates
+```bash
+# CLI tự động copy templates vào project
+cp ~/.gemini/antigravity/templates/specs/PROJECT.md docs/specs/PROJECT.md
+cp ~/.gemini/antigravity/templates/specs/requirements-template.md docs/specs/REQUIREMENTS.md
+cp ~/.gemini/antigravity/templates/specs/ROADMAP.md docs/specs/ROADMAP.md
+cp ~/.gemini/antigravity/templates/specs/TECH-SPEC.md docs/specs/TECH-SPEC.md
+```
 
----
+### 3.2. AI Fills Content (Brainstorm Session)
 
-## 🏗️ Giai đoạn 3: Project Skeleton & Hidden Setup
-*(Kế thừa từ v4.0 nhưng mạnh mẽ hơn)*
-
-1.  **Generate `.project-identity`**: (Bắt buộc, là trái tim của mọi workflow).
-    *   **Action:** Copy template từ `~/.gemini/antigravity/templates/project-identity/`:
-        *   `ios.json` cho iOS.
-        *   `android.json` cho Android.
-        *   `expo.json` cho Cross-platform.
-        *   `web-nextjs.json` cho Web App.
-        *   `backend-nestjs.json` cho API.
-    *   **Customize:** Thay thế các placeholder (`{{DATE}}`, `projectName`) bằng thông tin thực tế.
-2.  **Git Setup**: `.gitignore` thông minh theo stack.
-3.  **Linter/Formatter**: Cài ESLint/SwiftLint/Detekt ngay lập tức.
-4.  **CI/CD Basics**: Tạo `.github/workflows/ci.yml` cơ bản (build test).
+AI **chủ động** brainstorm với user để fill từng file:
 
----
+1.  **PROJECT.md** — Hỏi về vision, goals, target audience, success metrics.
+    *   "Dự án này giải quyết vấn đề gì?"
+    *   "Ai là người dùng chính?"
+    *   "Thành công sẽ trông như thế nào?"
 
-## 🎨 Giai đoạn 4: Visual Vision (The WOW Factor)
-*Không để user chờ đợi với màn hình đen trắng.*
+2.  **REQUIREMENTS.md** — Hỏi về features, scope, priorities.
+    *   "Features nào BẮT BUỘC có trong v1?"
+    *   "Có features nào nên để v2?"
+    *   Dùng user story format: "As a [user], I want [action] so that [benefit]"
 
-1.  **Brainstorm UI Concept**:
-    *   Dựa trên ý tưởng user, AI tự nghĩ ra 1 `prompt` mô tả giao diện cực xịn (Dark/Light mode, Glassmorphism...).
-2.  **Generate Mockup**:
-    *   Gọi tool `generate_image` để tạo ngay 1 ảnh "Vision Art".
-    *   Hiển thị cho user: "App của anh trông sẽ ngầu như thế này này!"
+3.  **ROADMAP.md** — Tự động sinh từ requirements.
+    *   Chia phases dựa trên priority + dependencies.
+    *   Mỗi phase có Definition of Done rõ ràng.
+
+4.  **TECH-SPEC.md** — Hỏi về architecture constraints.
+    *   "Có yêu cầu offline-first không?"
+    *   "AI model nào sẽ dùng?"
+    *   Ghi nhận Architecture Decisions (AD-1, AD-2...).
+
+### 3.3. Review & Confirm
+*   AI present tổng kết spec cho user review trước khi lưu.
+*   User approve → spec trở thành "source of truth".
 
 ---
 
-## 🔗 Giai đoạn 5: Handover to Specialized Workflows
-*Sự kết nối chặt chẽ với các quy trình user yêu thích.*
+## 🎨 Giai đoạn 4: Visual Vision (Optional)
+
+1.  **Brainstorm UI Concept** dựa trên spec vừa tạo.
+2.  **Generate Mockup** via `generate_image` tool.
+3.  Hiển thị cho user: "App trông sẽ như thế này!"
 
-Báo cáo hoàn tất và trỏ ngay sang các bước tiếp theo:
+---
 
-### ⚠️ NEXT STEPS (Choose your path):
+## 🔗 Giai đoạn 5: Handover — Symphony + Next Steps
 
-**Path A: The Planner (Chậm mà chắc)**
-> "Tôi muốn lên kế hoạch chi tiết cho tính năng đầu tiên."
-👉 Gõ: **/plan** (Sẽ chạy `create-spec-architect` dùng template vừa tạo).
+1.  **Register project trong Symphony**:
+    ```bash
+    symphony project register --id <projectId> --name "<projectName>"
+    ```
 
-**Path B: The Builder (Mì ăn liền)**
-> "Tôi muốn thấy cấu trúc code ngay."
-👉 Gõ: **/structure** (Sẽ chạy `structure-clean-architect` dựa trên `.project-identity`).
+2.  **Tạo initial tasks từ ROADMAP.md Phase 1**:
+    *   Mỗi feature trong Phase 1 → 1 Symphony task (status: ready).
 
-**Path C: The Artist (UI First)**
-> "Tôi muốn thiết kế giao diện trước."
-👉 Gõ: **/visualize** (Sẽ chạy `design-to-ui` / `ui-first-methodology`).
+3.  **Present next steps**:
+    ```
+    🎉 SETUP COMPLETE!
+    
+    📐 Specs created:
+       + docs/specs/PROJECT.md
+       + docs/specs/REQUIREMENTS.md
+       + docs/specs/ROADMAP.md
+       + docs/specs/TECH-SPEC.md
+    
+    🎯 Symphony tasks created from Phase 1:
+       📋 #sym-A1 — [Feature 1] (ready)
+       📋 #sym-A2 — [Feature 2] (ready)
+    
+    ➡️ Next: Pick a feature to start PLANNING mode.
+       AI will read your specs automatically.
+    ```
 
 ---
 
-## 📝 Example Execution for User
+## 📝 Example Execution
 
 ```text
-Antigravity Initializer v4.1
+Antigravity Initializer v5.0
 ----------------------------
 ✅ Checking Environment... OK
-✅ Checking MCPs... Firebase (OFF), Maestro (ON)
+✅ Checking MCPs... Firebase (ON), Maestro (ON)
 📂 Project detected: Empty folder
 
 🤖 Let's build something great!
-... [Vision Capture Questions] ...
-
-🚀 Setting up Antigravity Core...
-   + docs/specs/_templates
-   + .project-identity
-   + .gitignore
-   + scripts/scaffold_feature.sh
+... [Vision Capture + Spec Brainstorm] ...
 
-🎨 Generating Vision Concept... [Done]
-   (Image: A sleek, dark-themed dashboard for [AppName])
+📐 Filling Project Specs...
+   ✅ docs/specs/PROJECT.md — filled
+   ✅ docs/specs/REQUIREMENTS.md — filled (12 requirements)
+   ✅ docs/specs/ROADMAP.md — filled (3 phases)
+   ✅ docs/specs/TECH-SPEC.md — filled (5 architecture decisions)
 
-🎉 SETUP COMPLETE!
-Your "Operating System" is ready.
+🎯 Symphony tasks created:
+   📋 #sym-A1 — User Authentication (P0, ready)
+   📋 #sym-A2 — Onboarding Flow (P0, ready)
+   📋 #sym-A3 — Dashboard UI (P1, ready)
 
-What's your first move?
-1. /plan [FeatureName] (Recommended: Create Specs first)
-2. /structure [FeatureName] (Scaffold Code)
-3. /visualize (Design UI)
+🎉 SETUP COMPLETE! Your "Operating System" is ready.
+➡️ Pick a feature to start building.
 ```