@leejungkiin/awkit 1.0.9 → 1.1.1

package/skills/swiftui-pro/references/performance.md

@@ -0,0 +1,46 @@
+# Performance
+
+- When toggling modifier values, prefer ternary expressions over if/else view branching to avoid `_ConditionalContent`, preserve structural identity, and avoid repeatedly recreating underlying platform views.
+- Avoid `AnyView` unless absolutely required. Use `@ViewBuilder`, `Group`, or generics instead.
+- If a `ScrollView` has an opaque, static, and solid background, prefer to use `scrollContentBackground(.visible)` to improve scroll-edge rendering efficiency.
+- It is more efficient to break views up by making dedicated SwiftUI views rather than place them into computed properties or methods. Using `@ViewBuilder` on a property or method does not solve this; breaking views up is strongly preferred.
+- Always ensure view initializers are kept as small and simple as possible, avoiding any non-trivial work. Flag any work that can be moved into a `task()` modifier to be run when the view is shown.
+- Similarly, assume each view’s `body` property is called frequently – if logic such as sorting or filtering can be moved out of there easily, it should be.
+- Avoid creating properties to store formatters such as `DateFormatter` unless they are required. A more natural approach is to use `Text` with a format, like this: `Text(Date.now, format: .dateTime.day().month().year())` or `Text(100, format: .currency(code: "USD"))`.
+- Avoid expensive inline transforms in `List`/`ForEach` initializers (e.g. `items.filter { ... }`) when they are repeated often.
+- Prefer deriving transformed data from the source-of-truth using `let`, or caching in `@State`. However, do not cache derived collections in `@State` unless you also own explicit invalidation logic to avoid stale UI.
+- For large data sets in `ScrollView`, use `LazyVStack`/`LazyHStack`; flag eager stacks with many children.
+- Prefer using `task()` over `onAppear()` when doing async work, because it will be cancelled automatically when the view disappears.
+- Avoid storing escaping `@ViewBuilder` closures on views when possible; store built view results instead.
+
+Example:
+
+```swift
+// Anti-pattern: stores an escaping closure on the view.
+struct CardView<Content: View>: View {
+    let content: () -> Content
+
+    var body: some View {
+        VStack(alignment: .leading) {
+            content()
+        }
+        .padding()
+        .background(.ultraThinMaterial)
+        .clipShape(.rect(cornerRadius: 8))
+    }
+}
+
+// Preferred: store the built view value; the synthesized init handles calling the builder.
+struct CardView<Content: View>: View {
+    @ViewBuilder let content: Content
+
+    var body: some View {
+        VStack(alignment: .leading) {
+            content
+        }
+        .padding()
+        .background(.ultraThinMaterial)
+        .clipShape(.rect(cornerRadius: 8))
+    }
+}
+```

package/skills/swiftui-pro/references/swift.md

@@ -0,0 +1,56 @@
+# Swift
+
+- Prefer Swift-native string methods over Foundation equivalents: use `replacing("a", with: "b")` not `replacingOccurrences(of: "a", with: "b")`.
+- Prefer modern Foundation API: `URL.documentsDirectory` instead of `FileManager` directory lookups, `appending(path:)` to append strings to a URL.
+- Never use C-style number formatting like `String(format: "%.2f", value)`. Use `Text(value, format: .number.precision(.fractionLength(2)))` or similar `FormatStyle` APIs.
+- Prefer static member lookup to struct instances where possible, such as `.circle` rather than `Circle()`, and `.borderedProminent` rather than `BorderedProminentButtonStyle()`.
+- Avoid force unwraps (`!`) and force `try` unless the failure is truly unrecoverable, and even then prefer using `fatalError()` with a clear description. If possible, use `if let`, `guard let`, nil-coalescing, or `try?`/`do-catch`.
+- Filtering text based on user-input must be done using `localizedStandardContains()` as opposed to `contains()` or `localizedCaseInsensitiveContains()`.
+- Strongly prefer `Double` over `CGFloat`, except when using optionals or `inout`; Swift is able to bridge the two freely except in those two cases.
+- If you want to count array objects that match a predicate, always use `count(where:)` rather than `filter()` followed by `count`.
+- Prefer `Date.now` over `Date()` for clarity.
+- When `import SwiftUI` is already in a file, you do not need to add `import UIKit` or `import AppKit` to access things like `UIImage` or `NSImage` – they are imported automatically on the appropriate platform.
+- When dealing with the names of people, strongly prefer to use `PersonNameComponents` with modern formatting over simple string interpolation such as `Text("\(firstName) \(lastName)")`.
+- If a given type of data is repeatedly sorted using an identical closure, e.g. `books.sorted { $0.author < $1.author }`, prefer to make the type in question conform to `Comparable` so the sort order is centralized.
+- Prefer to avoid manual date formatting strings if possible. If manual date formatting *is* used for user display, at least make sure to use “y” rather than “yyyy” for years, so the year value is correct in all localizations. If the purpose is data exchange with an API, this rule does not apply.
+- When trying to convert a string to a date, prefer the modern `Date` initializer API such as `Date(myString, strategy: .iso8601)`.
+- Flag instances where errors triggered by a user action are swallowed silently, e.g. using `print(error.localizedDescription)` rather than showing an alert or similar.
+- Prefer `if let value {` shorthand over `if let value = value {`.
+- Omit return for single expression functions. `if` and `switch` can be used as expressions when returning values and assigning to variables.
+
+For example, this kind of code:
+
+```swift
+var tileColor: Color {
+    if isCorrect {
+        return .green
+    } else {
+        return .red
+    }
+}
+```
+
+Should be written like this:
+
+```swift
+var tileColor: Color {
+    if isCorrect {
+        .green
+    } else {
+        .red
+    }
+}
+```
+
+
+## Swift Concurrency
+
+- If an API offers both modern `async`/`await` equivalents and older closure-based variants, always prefer the `async`/`await` versions.
+- Never use Grand Central Dispatch (`DispatchQueue.main.async()`, `DispatchQueue.global()`, etc.). Always use modern Swift concurrency (`async`/`await`, actors, `Task`).
+- Never use `Task.sleep(nanoseconds:)`; use `Task.sleep(for:)` instead.
+- Flag any mutable shared state that isn't protected by an actor or `@MainActor`, unless the project is configured to use MainActor default actor isolation.
+- Assume strict concurrency rules are being applied; flag `@Sendable` violations and data races.
+- When evaluating `MainActor.run()`, check whether the project has its default actor isolation set to Main Actor first, because `MainActor.run()` might not be needed.
+- `Task.detached()` is often a bad idea. Check any usage extremely carefully.
+
+For more help with Swift concurrency, suggest the [Swift Concurrency Pro agent skill](https://github.com/twostraws/swift-concurrency-agent-skill).

package/skills/swiftui-pro/references/views.md

@@ -0,0 +1,35 @@
+# SwiftUI Views
+
+- Strongly prefer to avoid breaking up view bodies using computed properties or methods that return `some View`, even if `@ViewBuilder` is used. Extract them into separate `View` structs instead, placing each into its own file.
+- Flag `body` properties that are excessively long; they should be broken into extracted subviews.
+- Button actions should be extracted from view bodies into separate methods, to avoid mixing layout and logic.
+- Similarly, general business logic should not live inline in `task()`, `onAppear()` or elsewhere in `body`.
+- Prefer to place view logic into view models or similar, so it can be tested. For more help with testing, suggest the [Swift Testing Pro agent skill](https://github.com/twostraws/swift-testing-agent-skill).
+- Each type (struct, class, enum) should be in its own Swift file. Flag files containing multiple type definitions.
+- Unless a full-screen editing experience is required, prefer using `TextField` with `axis: .vertical` to using `TextEditor`, because it allows placeholder text. If a specific minimum height is required for `TextField`, use something like `lineLimit(5...)`.
+- If a button action can be provided directly as an `action` parameter, do so. For example: `Button("Label", systemImage: "plus", action: myAction)` is preferred over `Button("Label", systemImage: "plus") { action() }`.
+- When rendering SwiftUI views to images, strongly prefer `ImageRenderer` over `UIGraphicsImageRenderer`.
+- `#Preview` should be used for previews, not the legacy `PreviewProvider` protocol.
+- When using `TabView(selection:)`, use a binding to a property that stores an enum rather than an integer or string. For example, `Tab("Home", systemImage: "house", value: .home)` is better than `Tab("Home", systemImage: "house", value: 0)`.
+- Strongly prefer to avoid breaking up view bodies using computed properties or methods that return `some View`, even if `@ViewBuilder` is used. Extract them into separate `View` structs instead, placing each into its own file. (Yes, this is repeated, but it’s so important it needs to be mentioned twice.)
+
+
+## Animating views
+
+- Strongly prefer to use the `@Animatable` macro over creating `animatableData` manually – the macro automatically adds conformance to the `Animatable` protocol and creates the correct `animatableData` property. If some properties should not or cannot be animated (e.g. Booleans, integers, etc), mark them `@AnimatableIgnored`.
+- Never use `animation(_ animation: Animation?)`; always provide a value to watch, such as `.animation(.bouncy, value: score)`.
+- Chaining animations must be done using a `completion` closure passed to `withAnimation()`, rather than trying to execute multiple `withAnimation()` calls using delays.
+
+For example:
+
+```swift
+Button("Animate Me") {
+    withAnimation {
+        scale = 2
+    } completion: {
+        withAnimation {
+            scale = 1
+        }
+    }
+}
+```

package/skills/symphony-enforcer/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: symphony-enforcer
+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.
+metadata:
+  stage: core
+  version: "2.0"
+  replaces: null
+  requires: symphony-orchestrator
+  tags: [symphony, enforcement, checkpoint, task-lifecycle, core]
+agent: Symphony Enforcer
+allowed-tools:
+  - symphony_create_task
+  - symphony_claim_task
+  - symphony_complete_task
+  - symphony_report_progress
+  - symphony_available_tasks
+  - symphony_status
+trigger: always
+invocation-type: auto
+priority: 1
+---
+
+# Symphony Enforcer — Mandatory Task Lifecycle Checkpoints
+
+> **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".
+
+---
+
+## ⚠️ Core Rule
+
+```
+KHÔNG CÓ NGOẠI LỆ:
+- Mọi code/debug/plan task PHẢI qua STRICT STARTUP PROTOCOL (5 steps)
+- Mọi milestone PHẢI report progress
+- AI tự detect completion và auto-complete task
+- BỎ QUA BẤT KỲ STEP NÀO = VI PHẠM
+```
+
+---
+
+## 🔒 STRICT STARTUP PROTOCOL (BẮT BUỘC — KHÔNG ĐƯỢC BỎ QUA)
+
+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.
+
+### 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}"
+```
+
+### Step 2: NeuralMemory Brain — Switch brain
+
+```
+→ nmem brain use <projectId>
+→ nmem_recap(level=1) — load context
+→ Output: "🧠 Step 2/4: Brain ✅ — switched to {projectId}"
+```
+
+### Step 3: 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"
+```
+
+### Step 4: Confirmation Block — Hiển thị tổng kết
+
+```
+🚦 STARTUP PROTOCOL COMPLETE
+══════════════════════════════════════
+  Step 1: 📋 Project Identity  ✅  {projectId}
+  Step 2: 🧠 NeuralMemory      ✅  brain: {projectId}
+  Step 3: 🎯 Task              ✅  #sym-XYZ — "{title}"
+  Step 4: ✅ READY TO WORK
+══════════════════════════════════════
+```
+
+> ⛔ **Nếu KHÔNG hiển thị confirmation block = VI PHẠM — KHÔNG ĐƯỢC BẮT ĐẦU WORK**
+
+---
+
+## Trigger Points (Trong quá trình làm việc)
+
+### TP1: Progress Milestone — Tại mỗi giai đoạn quan trọng
+
+**Khi nào:** Bất kỳ milestone nào 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
+- Phát hiện vấn đề cần thay đổi approach
+
+**Action:**
+```
+symphony_report_progress(
+  task_id=current_task,
+  progress=estimated_percentage,
+  last_action="mô tả ngắn milestone"
+)
+```
+
+**Progress Estimation Guide:**
+```
+  10% — Task created, đang research/đọc code
+  25% — Implementation plan approved
+  40% — Bắt đầu code changes
+  60% — Code changes xong, đang test
+  80% — Tests pass, đang verification
+  90% — Walkthrough/docs tạo xong
+ 100% — Hoàn thành (auto-trigger TP2)
+```
+
+**Enforcement:**
+- ❌ KHÔNG được gọi `notify_user` mà chưa `report_progress` trước đó
+- ❌ KHÔNG được chuyển mode (task_boundary) mà chưa report
+
+---
+
+### TP2: Task Complete — AI tự detect hoàn thành
+
+**Khi nào:** AI detect ≥2/4 completion signals:
+
+```
+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)
+```
+
+**Action:**
+```
+1. symphony_complete_task(
+     task_id=current_task,
+     summary="mô tả ngắn kết quả"
+   )
+2. Hiển thị: "✅ SYM #sym-XYZ — Done"
+3. KHÔNG cần chờ user confirm
+```
+
+**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
+
+---
+
+### TP3: Abandoned / Context Switch
+
+**Khi nào:**
+- User đổi topic sang task khác hoàn toàn
+- AI bị lỗi/timeout giữa chừng
+- User explicitly nói dừng task
+
+**Action:**
+```
+symphony_abandon_task(
+  task_id=current_task,
+  reason="mô tả lý do"
+)
+```
+
+---
+
+## Ngoại lệ — Khi nào KHÔNG cần Startup Protocol
+
+```
+- Simple Q&A: Câu hỏi đơn giản, giải thích concept
+- Quick lookup: Đọc file, search code, không sửa gì
+- User nói rõ bỏ qua: "skip symphony", "không cần task"
+```
+
+---
+
+## Sync Block Format
+
+Mỗi khi sync, AI hiển thị dòng ngắn:
+
+```
+🎯 SYM #sym-XYZ — 40% → 70% "Implemented auth module"
+```
+
+Nếu completed:
+```
+✅ SYM #sym-XYZ — Done "Auth module with tests"
+```
+
+---
+
+## Edge Cases
+
+| Tình huống | Xử lý |
+|-----------|--------|
+| Project chưa có .project-identity | ⛔ Dừng, tạo file trướ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 |
+
+---
+
+## 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

package/skills/symphony-orchestrator/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: symphony-orchestrator
+description: |
+  Symphony setup, health check, and auto-start skill. Ensures Symphony server
+  is running before any task management. Handles installation, global CLI setup,
+  project registration, and server lifecycle management.
+metadata:
+  stage: core
+  version: "3.0"
+  replaces: null
+  requires: awkit-symphony (npm i -g awkit-symphony)
+  tags: [symphony, setup, server, orchestration, core, preflight, multi-project, agent]
+agent: Symphony Conductor
+allowed-tools:
+  - run_command
+  - read_url_content
+  - view_file
+trigger: always
+invocation-type: auto
+priority: 0
+---
+
+# Symphony Orchestrator Skill — Multi-Project & Agent Orchestration
+
+> **Purpose:** Đảm bảo Symphony server luôn sẵn sàng cho mọi session.
+> **Key Feature:** Single preflight call thay thế 4+ API calls.
+> **Gate Enforcement:** User PHẢI thấy checklist block, nếu không = vi phạm.
+
+---
+
+## ⚠️ Core Principle: Multi-Project First
+
+```
+QUAN TRỌNG:
+- Symphony quản lý tasks từ NHIỀU project cùng lúc
+- "Active project" trên UI CHỈ ảnh hưởng hiển thị dashboard
+- "Active project" KHÔNG filter queries API/CLI
+- CLI/API mặc định trả về TẤT CẢ tasks, dùng --project/-P để filter
+- AI agents làm việc cross-project — không bị giới hạn bởi active project
+```
+
+**Database:** Centralized tại `~/.gemini/antigravity/symphony/symphony.db`
+- CLI (`core/db.js`) và API (`lib/core.mjs`) dùng CHUNG 1 database
+- Tất cả tasks từ mọi project nằm trong 1 DB duy nhất
+
+---
+
+## Installation (One-Time Setup)
+
+### Bước 1: Install Global
+
+```bash
+cd ~/Dev/NodeJS/main-awf/symphony
+npm link
+```
+
+> Hoặc khi publish npm:
+> ```bash
+> npm i -g awkit-symphony
+> ```
+
+### Bước 2: Verify
+
+```bash
+symphony --version   # Expected: 0.1.0+
+symphony --help      # Shows: preflight, task, agent, dispatch, next, etc.
+```
+
+### Bước 3: Build + Start
+
+```bash
+symphony build          # Production build (~5-10s)
+symphony start -p 3100  # Start server
+```
+
+### Troubleshooting
+
+| Lỗi | Giải pháp |
+|------|-----------|
+| `command not found: symphony` | `source ~/.nvm/nvm.sh && nvm use default` |
+| `better-sqlite3 architecture mismatch` | `npm rebuild better-sqlite3` |
+| `EADDRINUSE port 3100` | Đã có instance → dùng port khác: `-p 3101` |
+| `.next/ not found` | Chạy `symphony build` thủ công |
+
+---
+
+## 🚦 Preflight Gate Protocol (Gate 0) — BẮT BUỘC
+
+Mỗi session, AI PHẢI thực hiện **1 call duy nhất**:
+
+### Via API (khi server đang chạy):
+
+```bash
+curl -s http://localhost:3100/api/preflight
+```
+
+### Via CLI:
+
+```bash
+symphony preflight          # Pretty output
+symphony preflight --json   # JSON cho AI parsing
+```
+
+### Checklist Output (AI PHẢI hiển thị):
+
+```
+🚦 SYMPHONY PREFLIGHT
+──────────────────────────────────────────────────
+   Server:  ✅ PASS
+   Project: ✅ PASS — 🧘 Giác Ngộ
+   Tasks:   🔵 HAS_ACTIVE
+   Overall: ✅ PASS
+
+📿 In Progress: #sym-X1Y2 — Theme System (P1)
+📋 Ready: #sym-A3B4 — Dark Mode (P2)
+```
+
+> ⚠️ **Nếu không hiển thị checklist block này = VI PHẠM GATE**
+
+---
+
+## Auto-Start Protocol
+
+```
+1. curl -s http://localhost:3100/api/preflight
+2. Nếu FAIL (connection refused):
+   → symphony start -p 3100 &
+   → Đợi 3-5 giây
+   → Retry preflight
+3. Nếu vẫn FAIL:
+   → "⚠️ Symphony không khởi động được"
+   → Hướng dẫn: cd ~/Dev/NodeJS/main-awf/symphony && npm link && symphony start
+```
+
+---
+
+## CLI Commands — Full Reference
+
+### Task Management
+
+```bash
+# Listing (cross-project by default)
+symphony task list                   # ALL tasks, mọi project
+symphony task list -P giacngo        # Chỉ project giacngo
+symphony task list -s ready          # Filter by status
+symphony task list -P awkit -s done  # Combine filters
+
+# CRUD
+symphony task create "title"         # Create task
+symphony task show <id>              # Show details
+
+# Lifecycle
+symphony task claim <id>             # ready → claimed
+symphony task start <id>             # → in_progress (auto-claim)
+symphony task done <id> -m "summary" # → done (auto-claim nếu cần)
+symphony task approve <id>           # draft → ready
+symphony task reopen <id>            # done → ready
+symphony task abandon <id>           # → ready (reset agent)
+symphony task delete <id>            # Xóa (draft/ready only)
+symphony task update <id>            # Sửa title/priority/desc
+```
+
+### Agent Management & AI Orchestration
+
+```bash
+# Agents
+symphony agent list                         # Tất cả agents + status
+symphony agent register <id> -n "name" -s "code,debug"  # Đăng ký
+symphony agent show <id>                    # Chi tiết
+symphony agent update <id> -s "new,specs"   # Sửa profile
+symphony agent remove <id>                  # Xóa (idle only)
+symphony agent assign <agent-id> <task-id>  # Gán task → agent
+symphony agent idle <id>                    # Mark idle
+
+# Orchestration Shortcuts
+symphony dispatch <task-id>              # 🎯 Auto-pick idle agent phù hợp
+symphony dispatch <task-id> -a <agent>   # 🎯 Dispatch cho agent chỉ định
+symphony next                            # 📋 Gợi ý task tiếp theo
+symphony next -n 5                       # 📋 Top 5 suggestions
+```
+
+### Server & System
+
+```bash
+symphony status                # Full system status
+symphony preflight             # Gate check (BẮT BUỘC)
+symphony start [-p PORT]       # Production mode
+symphony dev [-p PORT]         # Dev mode
+symphony build                 # Build dashboard
+symphony dashboard             # Open browser
+```
+
+---
+
+## Multi-Project Workflow
+
+### Scenario: AI làm việc trên 2 project cùng lúc
+
+```bash
+# 1. Xem tất cả tasks cross-project
+symphony task list
+# → Hiển thị tasks từ cả giacngo, awkit, filmcam...
+
+# 2. Filter khi cần focus 1 project
+symphony task list -P giacngo -s ready
+
+# 3. Claim task từ project bất kỳ
+symphony task start sym-W0jcDtRo       # giacngo task
+symphony task start sym-VKTqZkyF       # awkit task — vẫn hoạt động
+
+# 4. Complete không cần switch project
+symphony task done sym-W0jcDtRo -m "Theme system done"
+
+# 5. Dispatch task cho agent cụ thể
+symphony dispatch sym-A3B4 -a agent-frontend
+```
+
+### AI Agent Orchestration Flow
+
+```
+1. AI registers as agent:
+   symphony agent register antigravity-main -n "Antigravity" -s "code,debug,plan"
+
+2. AI picks next task from ANY project:
+   symphony next
+   → Shows ready tasks across all projects with project column
+
+3. AI claims and starts:
+   symphony task start <task-id>
+
+4. AI completes:
+   symphony task done <task-id> -m "summary"
+
+5. AI checks next:
+   symphony next
+```
+
+### Concurrency Control
+
+```bash
+# Max 3 working agents (symphony.config.js → maxAgents: 3)
+# Dispatch will fail if all slots occupied:
+#   "❌ No available agent slots"
+# → Free a slot: symphony agent idle <agent-id>
+```
+
+---
+
+## API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| **GET** | **`/api/preflight`** | **🚦 Single-call gate check (BẮT BUỘC)** |
+| GET | `/api/status` | Full system status |
+| GET | `/api/tasks` | List tasks (?status=, ?project=) |
+| POST | `/api/tasks` | Create task |
+| PATCH | `/api/tasks` | Actions: claim, complete, abandon, approve, reopen |
+| DELETE | `/api/tasks?id=` | Delete task |
+| GET | `/api/projects` | List projects (?stats=true) |
+| POST | `/api/projects` | Register project |
+| PATCH | `/api/projects` | Activate project (UI only) |
+| GET | `/api/agents` | List agents |
+| POST | `/api/agents` | Register agent |
+| PATCH | `/api/agents` | Update profile / assign task |
+| DELETE | `/api/agents` | Remove agent |
+
+---
+
+## Integration with GEMINI.md Gates
+
+| Gate | Protocol |
+|------|----------|
+| **Gate 0** | `curl /api/preflight` → checklist block → NeuralMemory warm-up |
+| Gate 0.5 | Check `preflight.projects` → auto-register if missing → switch brain |
+| Gate 1 | `symphony task list -s in_progress` → claim/create task (cross-project) |
+| Gate 2 | `symphony task done <id> -m "..."` → `symphony next` → suggest |
+| Gate 3 | `symphony task list -s in_progress` → block deploy if any |
+
+---
+
+## Database Location
+
+```
+~/.gemini/antigravity/symphony/symphony.db  # Centralized (all projects share 1 DB)
+```
+
+> ⚠️ CLI và API dùng CHUNG database này.
+> Active project selection trên dashboard KHÔNG ảnh hưởng queries.
+
+---
+
+## Learnings
+
+- `npm link` requires NVM PATH — user may need `source ~/.nvm/nvm.sh`
+- `better-sqlite3` is native module — may need `npm rebuild` after arch changes
+- Production server ~170ms vs ~3s for dev — always prefer `symphony start`
+- Preflight replaces 4+ API calls with 1 — much harder for AI to skip
+- Preflight checklist block acts as visual enforcement — user sees immediately if skipped
+- Active project is UI-only — NEVER use it to scope CLI/API queries
+- CLI and API share centralized DB at `~/.gemini/antigravity/symphony/symphony.db`
+- Multi-project work is default — tasks from all projects visible simultaneously