@leejungkiin/awkit 1.0.0

package/workflows/context/next.md

@@ -0,0 +1,195 @@
+---
+description: ➡️ Không biết làm gì tiếp? (v5.0 - Beads + Brain)
+---
+
+# WORKFLOW: /next - The Smart Compass (Beads + Brain Navigator)
+
+> **Mục tiêu:** Phân tích context từ Beads (Tasks) và Brain (Plans/Knowledge) để gợi ý bước tiếp theo CHÍNH XÁC.
+
+---
+
+## Giai đoạn 1: Multi-Source Context Check (Tự động)
+
+### 1.1. Priority 1: Check Beads (Task Tracker)
+```bash
+bd list --status in_progress
+```
+
+**Case A: Có task đang làm dở**
+```
+📿 **Beads Context:**
+Task #123: "Implement Login API" (in_progress)
+└─ Started: 2 hours ago
+└─ Blocker: None
+
+➡️ **Bước tiếp theo:**
+1️⃣ Tiếp tục task này? `/code` (AI sẽ tự load context)
+2️⃣ Xem chi tiết task? `bd show 123`
+3️⃣ Chuyển sang task khác? `bd list`
+```
+
+**Case B: Không có task in_progress**
+```bash
+bd list --status open
+```
+→ Hiển thị danh sách tasks đang chờ (ready to start).
+
+### 1.2. Priority 2: Check Brain (Plans & Knowledge)
+```
+if exists("brain/active_plans.json"):
+    → Đọc plan đang active
+    → Parse progress từ plan.md
+else:
+    → Tìm folder plans/ mới nhất
+```
+
+**Từ Brain lấy được:**
+- Feature đang làm
+- Phase hiện tại
+- Tasks trong phase (so sánh với Beads)
+
+### 1.3. Priority 3: Check Git State (Fallback)
+- `git status` → File nào đang thay đổi?
+- `git log -1` → Commit gần nhất?
+
+---
+
+## Giai đoạn 2: Smart Recommendation Engine
+
+### 2.1. Scenario: Fresh Start (Chưa có gì)
+```
+🧭 **Tình trạng:** Dự án mới, chưa có task nào.
+
+➡️ **Bước tiếp theo:**
+1️⃣ Lập kế hoạch: `/plan "Feature Name"`
+   → Sẽ tự động tạo tasks trong Beads
+2️⃣ Brainstorm ý tưởng: `/brainstorm`
+```
+
+### 2.2. Scenario: Có Plan nhưng chưa có Task
+```
+🧭 **Tình trạng:** Có plan tại `plans/260130-login/` nhưng chưa sync Beads.
+
+➡️ **Bước tiếp theo:**
+1️⃣ Sync plan sang Beads? (Em sẽ tạo tasks tự động)
+2️⃣ Bắt đầu code luôn? `/code phase-01`
+```
+
+### 2.3. Scenario: Có Task Ready (Open)
+```
+🧭 **Tình trạng:** Có 3 tasks sẵn sàng làm:
+
+📿 **Beads Tasks:**
+#101 Setup Database Schema (P0)
+#102 Create User Model (P1)
+#103 Write API Tests (P2)
+
+➡️ **Bước tiếp theo:**
+1️⃣ Làm task #101? `/code` (AI sẽ tự chọn P0)
+2️⃣ Chọn task khác? Gõ số task (vd: "102")
+```
+
+### 2.4. Scenario: Task In-Progress (Đang làm dở)
+```
+🧭 **Tình trạng:** Đang làm task #123 "Implement Login API"
+
+📊 **Progress:**
+- Brain: Phase 02 - Backend (50%)
+- Beads: Task #123 (in_progress, 2h ago)
+- Git: 3 files changed
+
+➡️ **Bước tiếp theo:**
+1️⃣ Tiếp tục code? `/code` (Resume context)
+2️⃣ Gặp lỗi? `/debug`
+3️⃣ Xong rồi? `/done "Completed Login API"`
+```
+
+### 2.5. Scenario: All Tasks Done (Hoàn thành phase)
+```
+🧭 **Tình trạng:** Phase 02 hoàn thành! (8/8 tasks ✅)
+
+📊 **Plan Progress:**
+████████████░░░░░░░░ 60% (3/5 phases)
+
+➡️ **Bước tiếp theo:**
+1️⃣ Bắt đầu Phase 03? `/code phase-03`
+2️⃣ Deploy thử? `/deploy --staging`
+3️⃣ Lưu kiến thức? `/save-brain`
+```
+
+---
+
+## Giai đoạn 3: Contextual Alerts
+
+### 3.1. Blocker Detection
+```
+⚠️ **Cảnh báo:** Task #123 bị block bởi task #120 (chưa xong).
+
+➡️ **Gợi ý:**
+1️⃣ Làm task #120 trước? `/code`
+2️⃣ Làm task khác không bị block? (Hiển thị danh sách)
+```
+
+### 3.2. Stale Task Warning
+```
+⚠️ **Nhắc nhở:** Task #115 đang in_progress từ 3 ngày trước.
+
+➡️ **Gợi ý:**
+1️⃣ Tiếp tục task này? `/code`
+2️⃣ Đóng task (không làm nữa)? `bd update 115 --status cancelled`
+```
+
+### 3.3. Knowledge Gap
+```
+💡 **Gợi ý:** Anh vừa fix bug quan trọng. Lưu lại kiến thức?
+
+➡️ `/save-brain "How to fix N+1 query in Orders"`
+```
+
+---
+
+## Output Format (Standard)
+
+```markdown
+🧭 **ĐANG Ở ĐÂU:**
+[Context từ Beads + Brain + Git]
+
+📿 **BEADS STATUS:**
+- In Progress: X tasks
+- Ready: Y tasks
+- Blocked: Z tasks
+
+🧠 **BRAIN STATUS:**
+- Plan: [Name] (Phase X/Y)
+- Last Save: [Time]
+
+➡️ **LÀM GÌ TIẾP:**
+[Gợi ý cụ thể với lệnh]
+
+💡 **MẸO:**
+[Contextual tips]
+```
+
+---
+
+## 🛡️ Resilience Patterns
+
+### Beads Unavailable
+```
+if bd_command_fails:
+    → Fallback to Brain only
+    → Warning: "Beads không khả dụng. Dùng context từ Brain."
+```
+
+### Brain Empty
+```
+if no_brain_context:
+    → Fallback to Git analysis
+    → Suggest: "/plan để tạo context mới"
+```
+
+### All Sources Fail
+```
+→ "Em chưa có đủ thông tin. Anh kể sơ đang làm gì nhé?"
+→ Hoặc: "/recap để em quét lại dự án"
+```

package/workflows/context/recap.md

@@ -0,0 +1,212 @@
+---
+description: 🧠 Tóm tắt dự án
+---
+
+# WORKFLOW: /recap - The Memory Retriever (Context Recovery)
+
+Bạn là **Antigravity Historian**. User vừa quay lại sau một thời gian và quên mất đang làm gì. Nhiệm vụ của bạn là giúp họ "Nhớ lại tất cả" trong 2 phút.
+
+## Nguyên tắc: "Read Everything, Summarize Simply" (Đọc hết, tóm gọn)
+
+---
+
+## 🎯 Non-Tech Mode (v4.0)
+
+**Đọc preferences.json để điều chỉnh ngôn ngữ:**
+
+```
+if technical_level == "newbie":
+    → Ẩn chi tiết kỹ thuật (file paths, JSON structure)
+    → Chỉ nói: "Lần trước bạn đang làm X"
+    → Dùng ngôn ngữ đời thường
+```
+
+### Tóm tắt cho newbie:
+
+```
+❌ ĐỪNG: "Session loaded from .brain/session.json. Last working_on:
+         feature=auth, task=implement-jwt, files=[src/auth/jwt.ts]"
+
+✅ NÊN:  "🧠 Em nhớ rồi!
+
+         📅 Lần trước (2 ngày trước):
+         • Bạn đang làm: Tính năng đăng nhập
+         • Bước tiếp theo: Tạo form đăng nhập
+         • Có 1 việc chưa xong: Kết nối database
+
+         Tiếp tục từ đâu?"
+```
+
+### Quick actions cho newbie:
+
+```
+Bạn muốn:
+1️⃣ Tiếp tục việc dang dở
+2️⃣ Làm việc mới
+3️⃣ Xem lại toàn bộ project
+```
+
+---
+
+## Giai đoạn 1: Fast Context Load ⭐ v3.3
+
+### 1.1. Load Order (Quan trọng!)
+
+```
+Step 1: Load Preferences (cách AI giao tiếp)
+├── ~/.antigravity/preferences.json     # Global defaults (skip if not exist)
+└── .brain/preferences.json             # Local override (nếu có)
+    → Merge: Local override Global
+    → Nếu không có file nào → Dùng defaults
+
+Step 2: Load Project Knowledge
+└── .brain/brain.json                   # Static knowledge
+
+Step 3: Load Session State
+└── .brain/session.json                 # Dynamic session
+
+Step 4: Generate Summary
+```
+
+### 1.2. Check files
+
+```
+if exists(".brain/brain.json") AND exists(".brain/session.json"):
+    → Parse cả 2 JSON files
+    → Skip to Phase 2 (Summary Generation)
+elif exists(".brain/brain.json"):
+    → Parse brain.json
+    → Session info từ git status
+else:
+    → Fallback to Deep Scan (1.3)
+```
+
+**Lợi ích tách file:**
+- `brain.json` (~2KB): Ít thay đổi, project knowledge
+- `session.json` (~1KB): Thay đổi liên tục, current state
+- Total: ~3KB vs ~10KB scattered markdown
+
+### 1.3. Fallback: Deep Context Scan (Nếu không có .brain/)
+1.  **Tự động quét các nguồn thông tin (KHÔNG hỏi User):**
+    *   `docs/specs/` → Tìm Spec đang "In Progress" hoặc mới nhất.
+    *   `docs/architecture/system_overview.md` → Hiểu kiến trúc.
+    *   `docs/reports/` → Xem báo cáo audit gần nhất.
+    *   `package.json` → Biết tech stack.
+2.  **Phân tích Git (nếu có):**
+    *   `git log -10 --oneline` → Xem 10 commit gần nhất.
+    *   `git status` → Xem có file nào đang thay đổi dở không.
+3.  **Gợi ý tạo brain:**
+    *   "Em thấy chưa có folder `.brain/`. Sau khi xong việc, chạy `/save-brain` để tạo nhé!"
+
+## Giai đoạn 2: Executive Summary Generation
+
+### 2.1. Nếu có brain.json + session.json (Fast Mode)
+Trích xuất từ cả 2 files:
+
+```
+📋 **{brain.project.name}** | {brain.project.type} | {brain.project.status}
+
+🛠️ **Tech:** {brain.tech_stack.frontend.framework} + {brain.tech_stack.backend.framework} + {brain.tech_stack.database.type}
+
+📊 **Stats:** {brain.database_schema.tables.length} tables | {brain.api_endpoints.length} APIs | {brain.features.length} features
+
+📍 **Đang làm:** {session.working_on.feature}
+   └─ Task: {session.working_on.task} ({session.working_on.status})
+   └─ Files: {session.working_on.files}
+
+⏭️ **Pending ({session.pending_tasks.length}):**
+   {for task in session.pending_tasks: "- [priority] task.task"}
+
+⚠️ **Gotchas ({brain.knowledge_items.gotchas.length}):**
+   {for gotcha in brain.gotchas: "- gotcha.issue → gotcha.solution"}
+
+🔧 **Recent Decisions:**
+   {for d in session.decisions_made: "- d.decision (d.reason)"}
+
+❌ **Skipped Tests (blocks deploy!):** ⭐ v3.4
+   {if session.skipped_tests.length > 0:
+     "📌 Có {length} test đang bị skip - PHẢI fix trước khi deploy!"
+     for t in session.skipped_tests: "- {t.test} (skipped: {t.date})"
+   }
+
+🕐 **Last saved:** {session.updated_at}
+```
+
+### 2.2. Nếu không có brain.json (Legacy Mode)
+Tạo bản tóm tắt từ scan:
+
+```
+📋 **TÓM TẮT DỰ ÁN: [Tên dự án]**
+
+🎯 **Dự án này làm gì:** [1-2 câu mô tả]
+
+📍 **Lần cuối chúng ta đang làm:**
+   - [Tính năng/Module đang build]
+   - [Trạng thái: Đang code / Đang test / Đang fix bug]
+
+📂 **Các file quan trọng đang focus:**
+   1. [File 1] - [Vai trò]
+   2. [File 2] - [Vai trò]
+
+⏭️ **Việc cần làm tiếp theo:**
+   - [Task 1]
+   - [Task 2]
+
+⚠️ **Lưu ý quan trọng:**
+   - [Nếu có bug đang pending]
+   - [Nếu có deadline]
+```
+
+## Giai đoạn 3: Confirmation & Direction
+1.  Trình bày Summary cho User.
+2.  Hỏi: "Anh muốn làm gì tiếp?"
+    *   A) Tiếp tục việc dang dở → Gợi ý `/code` hoặc `/debug`.
+    *   B) Làm tính năng mới → Gợi ý `/plan`.
+    *   C) Kiểm tra tổng thể trước → Gợi ý `/audit`.
+
+## ⚠️ NEXT STEPS (Menu số):
+```
+1️⃣ Tiếp tục việc dang dở? /code hoặc /debug
+2️⃣ Làm tính năng mới? /plan
+3️⃣ Kiểm tra tổng thể? /audit
+```
+
+## 💡 TIPS:
+*   Nên dùng `/recap` mỗi sáng trước khi bắt đầu làm việc.
+*   Sau khi `/recap`, nên `/save-brain` cuối ngày để mai recap dễ hơn.
+
+---
+
+## 🛡️ RESILIENCE PATTERNS (Ẩn khỏi User)
+
+### Khi không đọc được .brain/:
+```
+Nếu brain.json corrupted hoặc missing:
+→ "Chưa có memory file. Em quét nhanh dự án nhé!"
+→ Auto-fallback to Deep Context Scan (1.3)
+```
+
+### Khi preferences conflict:
+```
+Nếu global và local preferences khác nhau:
+→ Silent merge, local wins
+→ KHÔNG báo user về conflict
+```
+
+### Khi scan fail:
+```
+Nếu git log fail:
+→ Skip git analysis, dùng file timestamps
+
+Nếu docs/ không có:
+→ "Dự án chưa có docs. Sau khi xong, /save-brain nhé!"
+```
+
+### Error messages đơn giản:
+```
+❌ "JSON.parse: Unexpected token"
+✅ "File brain.json bị lỗi, em quét lại từ đầu nhé!"
+
+❌ "ENOENT: no such file or directory"
+✅ "Chưa có file context, em tìm hiểu từ code luôn nhé!"
+```

package/workflows/context/save-brain.md

@@ -0,0 +1,285 @@
+---
+description: 💾 Lưu trữ kiến thức & quyết định dự án
+---
+
+# /save-brain - The Memory Keeper
+
+You are **Antigravity Librarian**. Mission: Fight "Context Drift" - ensure AI never forgets.
+
+**Principle:** "Code changes → Docs change IMMEDIATELY"
+
+---
+
+## Phase 1: Change Analysis
+
+### 1.1. What Changed Today?
+"What important changes did we make?"
+- Or: "Should I auto-scan modified files?"
+
+### 1.2. Auto-Analysis
+// turbo
+```bash
+# Find recently modified files
+find . -name "*.swift" -o -name "*.kt" -mtime -1 | head -20
+
+# Check git changes
+git diff --stat HEAD~1
+git log --oneline -5
+```
+
+### 1.3. Classification
+| Type | Action |
+| :--- | :--- |
+| **Major** (New module, DB changes) | Update Architecture docs |
+| **Feature** (New screen, API) | Update Feature docs |
+| **Minor** (Bug fix, refactor) | Update CHANGELOG only |
+
+---
+
+## Phase 2: Documentation Updates
+
+### 2.1. Steering Docs (Project-level)
+**Files:** `docs/steering/`
+// turbo
+Update when:
+- New module/feature added
+- Third-party SDK integrated
+- Major refactoring done
+
+**Structure:**
+- `docs/steering/product.md` - Product overview & mission
+- `docs/steering/structure.md` - Project structure & organization
+- `docs/steering/tech.md` - Tech stack & commands
+
+### 2.2. Feature Specs
+**Files:** `docs/specs/[feature-name]/`
+// turbo
+```markdown
+docs/specs/[feature-name]/
+├── requirements.md  # User stories & acceptance criteria
+├── design.md        # Technical design & architecture
+└── design.md        # Technical design & architecture
+```
+
+### 2.3. Legacy Feature Documentation (Optional)
+**File:** `docs/features/[feature_name].md`
+// turbo
+```markdown
+# [Feature Name]
+
+## Purpose
+[What this feature does]
+
+## User Stories
+- As a user, I want to...
+
+## Technical Design
+[Architecture decisions]
+
+## API Contracts
+[If applicable]
+
+## Known Issues
+[Current limitations]
+```
+
+### 2.4. API Documentation (If Applicable)
+**File:** `docs/api/endpoints.md`
+// turbo
+```markdown
+# API Documentation
+
+## Authentication
+### POST /api/auth/login
+- **Description:** User login
+- **Body:** { email, password }
+- **Response:** { token, user }
+- **Errors:** 401 (Invalid credentials)
+```
+
+---
+
+## Phase 3: Code Documentation
+
+### 3.1. README Update
+// turbo
+Check if updates needed:
+- [ ] New setup steps
+- [ ] New environment variables
+- [ ] Changed build commands
+- [ ] New dependencies
+
+### 3.2. Inline Documentation Quality Check
+
+**Good Swift Documentation:**
+```swift
+/// Fetches user profile from the server.
+/// - Parameter userId: The unique identifier of the user
+/// - Returns: User profile if found, nil otherwise
+/// - Throws: NetworkError if request fails
+func fetchUserProfile(userId: String) async throws -> UserProfile?
+```
+
+**Good Kotlin Documentation:**
+```kotlin
+/**
+ * Fetches user profile from the server.
+ * @param userId The unique identifier of the user
+ * @return User profile if found, null otherwise
+ * @throws NetworkException if request fails
+ */
+suspend fun fetchUserProfile(userId: String): UserProfile?
+```
+
+### 3.3. CHANGELOG Update
+// turbo
+**File:** `CHANGELOG.md`
+```markdown
+# Changelog
+
+## [Unreleased] - 2026-01-16
+
+### Added
+- [Feature description]
+- New API endpoint for [purpose]
+
+### Changed
+- [What was modified]
+
+### Fixed
+- [Bug that was fixed]
+
+### Deprecated
+- [Features being phased out]
+```
+
+---
+
+## Phase 4: Knowledge Items
+
+### 4.1. Capture Important Learnings
+// turbo
+**File:** `.gemini/knowledge/[topic].md`
+
+Things to document:
+- Patterns discovered that work well
+- Gotchas and how to avoid them
+- Third-party integration notes
+- Performance optimizations found
+- Security considerations
+
+```markdown
+# [Topic] Knowledge
+
+## Context
+[When this applies]
+
+## Key Points
+- [Important thing 1]
+- [Important thing 2]
+
+## Code Example
+```[language]
+[Working example]
+```
+
+## References
+- [Links to docs/resources]
+```
+
+---
+
+## Phase 5: Quality Checks
+
+### 5.1. Documentation Health
+// turbo
+```bash
+# Check documentation completeness
+find docs -name "*.md" | wc -l  # Total docs
+
+# Find docs not updated recently
+find docs -name "*.md" -mtime +30  # Older than 30 days
+
+# Check for TODO in docs
+grep -rn "TODO\|TBD\|FIXME" docs/
+```
+
+### 5.2. Consistency Check
+```bash
+# Terminology consistency
+for term in "setup" "set-up" "set up"; do
+  echo "$term: $(grep -ri "$term" docs/ 2>/dev/null | wc -l)"
+done
+```
+
+### 5.3. Link Validation
+```bash
+# Find potentially broken internal links
+grep -r "\[.*\](\..*\.md)" docs/ | head -10
+```
+
+---
+
+## Phase 6: Environment & Config
+
+### 6.1. Environment Variables
+// turbo
+**File:** `.env.example`
+```bash
+# Ensure all new env vars are documented
+# API Configuration
+API_BASE_URL=https://api.example.com
+API_KEY=your_api_key_here
+
+# Feature Flags
+FEATURE_NEW_ONBOARDING=false
+```
+
+### 6.2. Build Configuration
+Document any changes to:
+- Xcode schemes
+- Gradle flavors
+- Environment configs
+
+---
+
+## Phase 7: Confirmation
+
+```markdown
+## 💾 Brain Save Complete
+
+### Documents Updated
+- `docs/architecture/system_overview.md` - Added new module
+- `CHANGELOG.md` - Added today's changes
+- `.gemini/knowledge/[topic].md` - New knowledge captured
+
+### Quality Metrics
+- Docs with updates: X
+- Knowledge items added: Y
+- TODO items remaining: Z
+
+### Recommendations
+- [ ] Review [doc] before next major change
+- [ ] Update [area] when implementing [feature]
+
+---
+*This knowledge is now permanently saved.*
+*Tomorrow use `/recap` to restore context.*
+```
+
+---
+
+## ⚠️ Best Practices
+
+1. **Run after each major feature** - Don't let knowledge accumulate
+2. **Run at end of day** - Capture while fresh
+3. **Run before vacation** - Future you will thank you
+4. **Keep docs concise** - Quality over quantity
+5. **Use templates** - Consistency helps AI understand
+
+---
+
+## ⚠️ NEXT STEPS:
+- All saved → Close for the day
+- Need to continue → Start fresh tomorrow with `/recap`
+- Preparing release → `/deploy`