1. Bắt đầu nhanh

Cài CLI bằng 1 dòng (tự nhận macOS/Linux · arm64/amd64, đặt sẵn gateway):

curl -fsSL https://kdev.k-solutions.vn/api/install | sh

Cách nhanh nhất cho dev: nhận flow key từ quản lý rồi mở thẳng dự án (tự đăng nhập + tự gắn AI):

kdev open kflw_xxxxxxxxxxxx

Hoặc đăng nhập thường (gateway mặc định là domain prod, chỉ cần email + mật khẩu):

kdev auth login
kdev auth status

Panel web: https://kdev.k-solutions.vn — đăng nhập cùng tài khoản đó.

Cập nhật CLI: kdev update. Xem toàn bộ lệnh ngay trên terminal: kdev guide.

2. 6 checkpoint của dự án

1. Tiếp nhận (intake) — brief + AI cấu trúc + kế hoạch. Leader duyệt để qua.
2. Phát triển (development) — dev code với AI, xong hết task chuẩn.
3. Kiểm thử (quality) — gate tự động: staging, SEO, link, CI xanh.
4. Review — nội bộ + khách (link review) + vòng chỉnh sửa. Leader duyệt để qua.
5. Bàn giao (deploy) — checklist trước deploy + đẩy production. Optional: dự án từ PMS mặc định bỏ qua (PMS quản bàn giao) — bật/tắt ở trang dự án.
6. Đúc kết (knowledge) — rút pattern/bài học vào kho tri thức.

Gate chặn tự động: task chưa xong / CI đỏ / PR chưa approve thì không qua được checkpoint.

3. Vai trò — IAM 3 cấp (lớn thấy nhỏ)

• CEO: cấp cao nhất — thấy toàn bộ công ty, duy nhất có quyền đổi vai trò / tạo Quản lý, gán member vào team bất kỳ.
• Quản lý (manager): có team riêng — chỉ thấy member team mình + dự án của team; nhận member chưa thuộc team vào team; tạo member (tự vào team mình); quản tài khoản AI, flow, prompt, tích hợp.
• Trưởng nhóm (leader): member cấp cao — duyệt checkpoint 1 (kế hoạch) + 4 (review) trong dự án của mình, gắn repo, đặt deploy info.
• Developer: làm việc hoàn toàn qua CLI — start, chat, work, demo, finish.
• QA / Designer / Sales: member theo chức năng ở các checkpoint tương ứng.

Mọi danh sách & thống kê (dự án, người dùng, token AI, sự kiện realtime) đều tự thu hẹp theo cấp: CEO thấy tất cả, Quản lý thấy team, member thấy việc của mình.

Sales/PM/Marketing/Khách hàng nằm ở PMS — K-DEV chỉ lo phần sản xuất/kỹ thuật/AI.

4. Luồng Developer (daily)

1. kdev auth login (1 lần) hoặc kdev open <flow-key>. Quên đang ở đâu? Gõ kdev — nó hiện trạng thái + việc tiếp theo.
2. kdev start — bắt đầu dự án đúng chuẩn (idempotent): init framework + SDD + git + GitHub layer (nhánh kdev/work) + nhập requirement + worklist. Sau đó: chat → demo (PR + staging + link khách) → feedback → nghiệm thu → finish.
3. kdev use — map dự án vào phiên (theo số hoặc tên: kdev use bánh mì); lo trọn workspace + phân agent theo slot pool.
4. kdev chat — box chat toàn màn hình với agent: vùng chat cuộn được, ô nhập cố định, footer trạng thái. Gõ tự nhiên là giao việc (bận thì tự xếp hàng), gõ /lệnh là chạy kdev (/task /done /next /init /update… — /help xem hết). Esc thoát, agent vẫn chạy nền.
5. kdev init wordpress / laravel — 1 lệnh ra site chạy local (Valet) + agent rules + SDD (requirements · goals · checklist).
6. Dạng lệnh rời (tương đương chat): kdev dev mở phiên agent ẩn, kdev work nội dung gửi lượt, kdev work log -f theo dõi.
7. kdev task done <số> (hoặc --all) — chốt việc; kdev staging sync khi lên Kiểm thử.
8. kdev next — qua checkpoint (gate tự kiểm CI/PR/staging); Leader duyệt 2 điểm chốt.

kdev auth login                 # 1 lần
kdev use bánh mì                # map dự án (số hoặc tên)
kdev chat                       # box chat: việc gì gõ nấy
› làm trang chủ theo brief      #   -> agent làm, stream vào chat
› /done all                     #   -> chốt task
› /next                         #   -> qua checkpoint

Mọi lượt việc đi qua pool AI công ty (mượn → chạy → tự trả), token tính vào đúng dự án trên trang Thống kê. Không bắt buộc git — Leader gắn repo/deploy trên panel khi cần.

5. Lệnh CLI (tham chiếu)

6. AI & nạp token

Mô hình lease: mượn tài khoản AI subscription từ pool → chạy Claude/Codex trên máy → tự trả.

kdev ai run -- claude        # mượn → nạp auth → chạy → tự trả khi thoát
kdev ai cost                 # chi phí AI của dự án hiện tại

Nạp tài khoản AI vào pool (quản lý) — 3 cách:

• 1 token: Tài khoản AI → Thêm (dán sk-ant-oat01-…).
• Nhiều token: Tài khoản AI → Thêm hàng loạt.
• Trên máy đã login Max: kdev ai add-account --setup.

Lưu ý: luôn ở đúng ngữ cảnh dự án trước khi ai run — usage không gắn dự án sẽ bị đánh dấu off-project ở trang Thống kê.

7. Deploy

Quản lý đặt staging host dùng chung 1 lần (Tích hợp / deploy-config, vd demo1.domaincty.vn). Mỗi dự án có prefix → staging tự suy https://host/{prefix}.

Trên trang dự án → card Triển khai (Deploy): đặt prefix + domain production, và đích deploy theo môi trường:

• WordPress → method wpcli (native wp-cli qua SSH).
• Framework khác → method git (pipeline CI/CD tự deploy).

Credential (SSH key/pass) mã hoá AES, không hiển thị lại. Hoạt động không cần PMS.

8. Thống kê & giám sát

Trang Thống kê AI: token & chi phí theo user / dự án / model / thời gian (ngày-giờ), biểu đồ cost per-user, và cảnh báo dùng sai mục đích (usage không gắn dự án + ngoài giờ). Mọi bảng sort được + Xuất CSV.

9. Đồng bộ PMS

PMS là nguồn sự thật của dự án/kinh doanh; K-DEV là nguồn sự thật của trạng thái sản xuất.

• PMS → K-DEV: POST/PUT /api/v1/projects (service token X-API-Key).
• K-DEV → PMS: webhook ký HMAC (stage.advanced, gate.evaluated, project.completed, repo.activity) + redelivery khi mạng lỗi.

Chưa nối PMS vẫn dùng được — tạo dự án + deploy info nhập tay trên panel.