@leejungkiin/awkit 1.1.0 → 1.1.2

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

package/skills/telegram-notify/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: telegram-notify
+description: Send Telegram notifications via AWKit CLI (Bot API). Use when tasks complete, deploys finish, or user requests Telegram alerts.
+triggers:
+  - keywords: ["telegram", "tg", "notify", "gửi telegram", "báo telegram", "thông báo"]
+  - events: ["deploy_complete", "task_complete", "user_request"]
+priority: low
+---
+
+# Telegram Notify Skill
+
+Send messages to Telegram groups/topics via `awkit tg` CLI command (Bot API, zero MCP needed).
+
+## When to Use
+
+- User explicitly asks to send a Telegram message
+- After deploy/release completion (if user has configured notifications)
+- Task completion summaries when user requests
+
+## Prerequisites
+
+User must have run `awkit tg setup` first. If not configured, guide them:
+
+```bash
+awkit tg setup
+# Prompts: Bot Token → Chat ID → Topic ID (optional)
+```
+
+## Commands
+
+```bash
+# Send plain text
+awkit tg send "message here"
+
+# Send to specific chat
+awkit tg send --chat -100xxx "message"
+
+# Send to specific forum topic
+awkit tg send --topic 123 "message"
+
+# Markdown formatting
+awkit tg send --parse-mode md "**bold** _italic_ `code`"
+
+# HTML formatting
+awkit tg send --parse-mode html "<b>bold</b> <i>italic</i>"
+
+# Combine flags
+awkit tg send --chat -100xxx --topic 456 --parse-mode md "**Done!**"
+```
+
+## AI Usage Rules
+
+1. **NEVER send without user consent** — always confirm before sending
+2. **Keep messages concise** — summarize, don't dump full logs
+3. **Use Markdown** for formatted messages (`--parse-mode md`)
+4. **Config location**: `~/.gemini/antigravity/.tg_config.json`
+5. If `awkit tg send` returns error about config, tell user to run `awkit tg setup`

package/symphony/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AWKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/symphony/README.md

@@ -0,0 +1,178 @@
+# 🎼 AWKit Symphony
+
+> Multi-Agent Orchestration for AI Coding Assistants
+
+Symphony coordinates multiple AI agents working on the same codebase — managing tasks, preventing file conflicts, and providing real-time visibility through a dashboard.
+
+## ✨ Features
+
+| Feature | Description |
+|---------|-------------|
+| **Task Management** | Create, assign, track tasks with priority & acceptance criteria |
+| **Git Isolation** | Auto worktree/clone per task — agents work on separate branches |
+| **File Locking** | Pessimistic locking prevents two agents from editing the same file |
+| **Merge Pipeline** | Auto-rebase + fast-forward merge when tasks complete |
+| **MCP Server** | 14 tools for IDE integration via Model Context Protocol |
+| **Dashboard** | Real-time Kanban board, agent status, events feed |
+| **Context Bus** | Event pub/sub — agents notify each other of changes |
+
+## 🚀 Quick Start
+
+```bash
+# Install
+cd symphony
+npm install
+
+# Start dashboard (port 3100)
+npm run dev
+
+# Or use CLI
+node cli/index.js status
+node cli/index.js task list
+```
+
+## 📋 CLI Commands
+
+```bash
+# System
+symphony status                        # Show system status
+symphony start                         # Start dashboard server
+symphony dashboard                     # Open dashboard in browser
+
+# Tasks
+symphony task list [-s ready]          # List tasks (filter by status)
+symphony task create "Feature X" -p 1  # Create task (priority 1-3)
+symphony task show <id>                # Show task details
+
+# Workspaces
+symphony workspace list                # List active workspaces
+symphony workspace create <task-id>    # Create workspace for task
+symphony workspace merge <task-id>     # Auto-merge completed task
+symphony workspace clean               # Remove merged workspaces
+
+# File Locks
+symphony lock list                     # Show active locks
+symphony lock release <file>           # Force-release stuck lock
+
+# MCP Server
+symphony mcp-serve [-n "Agent Name"]   # Start MCP server (stdio)
+```
+
+## 🔌 MCP Integration
+
+Add to your IDE's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "symphony": {
+      "command": "node",
+      "args": ["/path/to/symphony/mcp/server.js"],
+      "env": {
+        "SYMPHONY_AGENT_NAME": "my-agent"
+      }
+    }
+  }
+}
+```
+
+### Available MCP Tools (14)
+
+| Tool | Description |
+|------|-------------|
+| `symphony_available_tasks` | List available tasks |
+| `symphony_claim_task` | Claim a task (get workspace + branch) |
+| `symphony_report_progress` | Report progress (0-100%) |
+| `symphony_complete_task` | Complete task + trigger merge |
+| `symphony_abandon_task` | Abandon a task |
+| `symphony_check_files` | Check file lock status |
+| `symphony_lock_files` | Lock files for editing |
+| `symphony_unlock_files` | Release file locks |
+| `symphony_broadcast` | Broadcast event to other agents |
+| `symphony_events` | Query context bus events |
+| `symphony_status` | Get system status |
+| `symphony_create_task` | Create a new task |
+| `symphony_workspace_status` | Get workspace info + diff stats |
+| `symphony_merge_task` | Run auto-merge pipeline |
+
+## 🏗️ Architecture
+
+```
+symphony/
+├── core/                    # Engine
+│   ├── db.js                # SQLite (WAL mode)
+│   ├── task-manager.js      # Task CRUD + state machine
+│   ├── workspace-manager.js # Git worktree lifecycle
+│   ├── merge-pipeline.js    # Auto-rebase + merge
+│   ├── file-lock-manager.js # Pessimistic file locking
+│   ├── context-bus.js       # Event pub/sub
+│   └── orchestrator.js      # Agent dispatch + state
+├── mcp/                     # MCP Server
+│   ├── server.js            # stdio transport
+│   ├── index.js             # Tool registry (14 tools)
+│   └── tools/               # Tool implementations
+├── cli/                     # CLI
+│   └── index.js             # Commander.js commands
+├── app/                     # Dashboard (Next.js)
+│   ├── page.js              # Kanban + status + events
+│   └── api/                 # REST API routes
+└── lib/
+    └── core.mjs             # ESM bridge for Turbopack
+```
+
+## ⚙️ Configuration
+
+Edit `symphony.config.js`:
+
+```js
+module.exports = {
+    port: 3100,
+    maxAgents: 3,
+    workspace: {
+        type: 'hybrid',       // 'worktree' | 'clone' | 'hybrid'
+        cloneThreshold: 30,   // files > 30 → full clone
+    },
+    git: {
+        autoMerge: true,
+        targetBranch: 'main',
+        branchPrefix: 'symphony/',
+    },
+    locks: {
+        strategy: 'pessimistic',
+        autoRelease: 3600,    // seconds
+    },
+};
+```
+
+## 📊 Dashboard
+
+The dashboard runs on `http://localhost:3100` and provides:
+
+- **Kanban Board** — Tasks by status (Ready → In Progress → Review → Done)
+- **Agent Panel** — Connected agents with live status
+- **Events Feed** — Real-time context bus events
+- **Lock Panel** — Active file locks with force-release
+- **Stats Bar** — Task counts and system health
+
+## 🔄 Task Lifecycle
+
+```
+Ready → Claimed → In Progress → Review → Done
+  │                                        │
+  └─── Abandoned ◀────────────────────────┘
+```
+
+1. **Create** task via CLI or dashboard
+2. **Agent claims** via MCP → gets isolated workspace + branch
+3. **Agent works** → reports progress, locks files, broadcasts events
+4. **Agent completes** → triggers auto-merge pipeline
+5. **Merge** → rebase onto main, fast-forward, cleanup workspace
+
+## 📦 Tech Stack
+
+- **Runtime:** Node.js
+- **Database:** SQLite (via better-sqlite3, WAL mode)
+- **Dashboard:** Next.js 16 + React 19
+- **MCP:** @modelcontextprotocol/sdk
+- **CLI:** Commander.js
+- **Git:** Native git commands (worktree, rebase, merge)