← Về thư mục
📄 / / root / .hermes / skills / operate / handoff-task / SKILL.md

name: handoff-task description: Use when a user wants to handoff a task from one department to another. Creates a task in Lark Base (Task Hub) and notifies the target department. version: 3.2.0 author: Antigravity license: MIT metadata: hermes: tags: [handoff, task, operate, lark, telegram, nova] related_skills: [lark-task-hub, setup-departments]

Handoff Task — SOP 5.0 (Dual-Status Flow)

Single source of truth cho toàn bộ quy trình bàn giao liên phòng. Phiên bản này áp dụng dual-status system (tách Status thực thi và Handoff Status giao vận) theo chỉ đạo của CEO ngày 11/07/2026.

1. Architecture (Hybrid — Dual-Status + Hermes Kanban)

Key Rules: - Task ID Format: Top-level tasks MUST use [DEPT.SEQ] (e.g., [IT.01]). Sub-tasks use [DEPT.SEQ.SUB] (e.g., [IT.01.01]). No HO- or long alphanumeric strings. - Task Naming Rule: [DEPT.SEQ] Subject + CRUD + Object. Task từ CEO nên đặt tên cục bộ ngắn gọn: [IT.04] IT Tái cấu trúc phòng ban. - Task Creation: ONLY via /handoff command (do AI agent xử lý, không phải plugin). Never auto-create from natural language or cron jobs. - Global Sequence Generator: Quét Lark Base tìm SEQ lớn nhất của từng phòng, tăng lên 1. - Lark Base Payload: MUST be flat key-value map — NOT wrapped in "fields": {}.

Hybrid Model (Hero Design — Jul 2026)

Decision: Lark = Company View (IT BA, CEO dashboard). Hermes Kanban = Execution OS (AI agents, log, decompose). Two systems sync via the Handoff ID.

Layer Công nghệ Vai trò Ai dùng
0 — Command Telegram topics 6 commands (/accept, /block, /done, /report, /revise, /cancel) Người
1 — Intelligence AI Agent (tôi) Nhận /handoff, suy luận phòng ban, tạo task, route công việc AI
2a — Company State Lark Base (Task Hub) Company source of truth: Task ID, phòng ban, deadline, dual-status, exec view CEO, IT BA
2b — Execution OS Hermes Kanban Agent execution: claim, log, comment, decompose, worker runs, heartbeat AI Agent, Phong
3 — Dashboard Hermes Web UI (port 9119) Quản trị: KANBAN, CRON, SKILLS, FILES, SESSIONS Nhi (mọi thiết bị)

Khi nào dùng cái nào

Tình huống Dùng
CEO hỏi "task IT.04 đang ở đâu?" hoặc "status tổng thể các phòng" Lark Base (company view, có deadline + phòng ban)
AI agent (tôi/Phong) muốn nhận task, log, comment, decompose Hermes Kanban (claim/log/comment tools)
CEO muốn xem agent đang chạy gì, log lỗi, worker runs Hermes Dashboard (http://<tailscale-ip>:9119)
Phòng Grill/Brainstorm bàn giao task cho một phòng khác Telegram → AI (/handoff) → tạo task/record + Kanban task + file .md dossier

Pitfalls thực chiến (đã gặp)

Base Token (Lark)

QIx1bOHuzapATFslt4yl8zWTgnt Table ID: tblN85Tinj2x1tnf

2. Dual-Status System (CEO Design — 2026-07-11)

"1 Công ty khó có thể có tới 9 status 1 task. Nó nên tách ra 2 luồng: status handoff (xác minh task đang ở phòng nào), và status của bản chất project." — Nhi Vo

Trường Ý nghĩa Trạng thái
Status (Thực thi) Phase của vòng đời thực thi Draft → In progress → Blocked → Done
Handoff Status (Giao vận) Giai đoạn bàn giao giữa phòng Ready for handoff → Handed off → Accepted → Reported → Revised → Cancelled

Ma trận chuyển đổi

Lệnh Handoff Status Status Ghi chú
/handoff Handed off Draft Bàn giao xong, chờ xác nhận
/accept Accepted In progress Bắt đầu làm
/block (giữ nguyên) Blocked Kẹt
/done (giữ nguyên) Done Hoàn tất
/report Reported Done Đã báo cáo + link
/clarify Ready for handoff Draft Trả về phòng gửi
/revise Revised In progress Sửa lại
/cancel Cancelled Done Đóng task

3.5 Pitfall: Parent-child deadlock trong Hermes Kanban

Vấn đề: Hermes tự động block child task khi parent chưa done. Nếu task Umbrella (vd IT.05) được set làm parent của task con, task con sẽ luôn ở todo không thể claim.

Giải pháp (đã xác nhận với CEO): - Task Umbrella (cha tổng thể) KHÔNG link parent-child chính thức với các task con - Chỉ link dependency tuyến tính giữa các task con với nhau (DEPT.01 → DEPT.02 → DEPT.03) - Trên board, hierarchy được biểu diễn qua tên task (IT.05.01, IT.05.02) chứ không qua link Hermes

# ĐÚNG: Only link dependency chain, không link umbrella làm parent
hermes kanban link t_05_01 t_05_02    # DEPT.01 → DEPT.02
hermes kanban link t_05_02 t_05_03    # DEPT.02 → DEPT.03

# SAI: Link umbrella làm parent
hermes kanban link t_umbrella t_05_01 # → child bị parents_not_done lock

Cách sửa nếu lỡ link sai:

hermes kanban unlink t_umbrella t_05_01

2.5 Project Dossier — .md Pack & Handoff

"Mỗi phòng ban khi xử lý xong việc, nếu tôi đồng ý cho handoff thì tôi sẽ nhắn command handoff, phòng ban đó đóng gói lại file .md và handoff cho phòng ban liên quan." — Nhi Vo, 2026-07-11

Nguyên tắc

Cấu trúc file .md chuẩn

# projects/<TASK_ID>.md

## Tổng quan
(1-2 câu về dự án, phòng nào đang giữ, mục tiêu cuối)

## Output
- [ ] Phòng 1: việc đã làm → output
- [ ] Phòng 2: việc đã làm → output
- [ ] Phòng hiện tại: đang làm gì

## Context / Input
(Links, tài liệu tham khảo, quyết định quan trọng)

## Insights & Phát hiện
(Các phát hiện trong quá trình xử lý — ghi ngày + người)

## Handoff Log
| Thời gian | Từ | Đến | File .md |
|-----------|:--:|:---:|:---------|

Quy trình bắt buộc

  1. Khởi tạo: /handoff → tạo file projects/<ID>.md + template + link trên Lark.
  2. Process: Mỗi lần có output mới → update file .md trước khi rời task.
  3. Đóng gói: Trước /handoff tiếp → phải update file .md = xong phần output của phòng ban mình.
  4. Handoff: /handoff <phòng-tiếp> kèm dòng 📄 projects/<ID>.md trong nội dung.
  5. Nhận: Phòng tiếp theo đọc file .md → biết toàn bộ lịch sử + việc cần làm.

Ví dụ thực tế (IT.04)

File projects/IT.04.md (15KB, 316 dòng) chứa: - Tổng quan dự án Nova - Review tính khả thi kỹ thuật - Implementation Plan 4 phase, 19 task - Department code mapping - Timeline & dependencies

3. Eight-Command Trigger Set

Trigger Dùng khi nào Mục đích
/handoff <phòng_nhận> Hoàn tất đầu ra, cần bàn giao Tạo task, ghi vào source of truth
/accept <task_id> Phòng nhận xác nhận đã nhận task Vào hàng đợi thực thi
/clarify <task_id> Brief mơ hồ, thiếu link Buộc quay lại làm rõ
/block <task_id> Kẹt tài nguyên/quyết định Báo blocker sớm
/done <task_id> Output hoàn tất Chuyển sang báo cáo
/report <task_id> Gửi kết quả cuối + link Khép kín vòng lặp
/revise <task_id> Output chưa đạt Vòng phản hồi rõ ràng
/cancel <task_id> Task hết hợp lệ Đóng task sạch

Lưu ý: /handoff unregister khỏi plugin — fallback AI agent suy luận phòng + nội dung. Các lệnh còn lại giữ trong plugin (xử lý nhanh, không cần NLP).

4. Auto-Run & Escalate Rules

Auto-run (tự động xử lý ngay nếu đủ):

Escalate CEO nếu:

4.5 Kanban-Native Pipeline (New Pattern — Jul 2026)

Sau khi nghiên cứu Story 1-4 của Hermes Kanban Tutorial, hệ thống đã chuyển từ dual-status Lark + handoff.py cồng kềnh sang Kanban-native pipeline làm Execution OS. Lark Base giữ vai trò Executive View thuần tuý.

Pipeline Execution Path (thay thế /handoff cho AI Agent)

# Worker A (vd IT Dev) hoàn thành task
kanban_complete(
    summary="Implemented X with Y approach",
    metadata={
        "output_files": ["..."],
        "decisions": ["bcrypt for hashing", "JWT session tokens"],
        "duration_seconds": 120
    }
)
# → Auto-promotion: Task B (Review) chuyển từ blocked → ready
# → Gateway dispatcher tự động spawn worker B

Task Creation Rules (Hermes Kanban)

# BẮT BUỘC: dùng --assignee khi create (nếu không → unassigned/null)
hermes kanban create "IT.08.01 Task mẫu" --assignee it-ai --body "..."

# ƯU TIÊN: dùng --parent flag lúc create (thay vì link sau)
# → parent task's summary + metadata tự động vào worker_context của child
hermes kanban create "IT.08.02 Child task" --assignee grill-qa --parent $PARENT_ID --body "..."

# KHÔNG: tạo task rồi mới link (vẫn được nhưng mất context inheritance)
# KHÔNG: create không có --assignee (gây ra unassigned/null)

Gateway = Dispatcher nền

# Không gọi dispatch thủ công nữa
hermes gateway start   # chạy nền, auto-dispatch mỗi 60s

Ex vs Sup — không cần 2 profile cho 1 phòng

Cách sai: Tạo it-ai-ex và it-ai-sup riêng biệt → 10 profile cho 5 phòng. Cách đúng (Story 3): Dùng pipeline link để review qua profile khác:

Task A (it-ai: implement) ──link──→ Task B (grill-qa: review)
                                    Task C (str-mkt: approve)

Profile executor (it-ai, str-mkt, writers) IMPLEMENT rồi complete. Profile reviewer (grill-qa) REVIEW trước khi promote sang department khác. Không cần nhân đôi profile — pipeline link làm nhiệm vụ phân luồng.

Mỗi Profile cần mô tả chi tiết bằng describe (NOT per-profile SOUL.md)

⚠️ Cảnh báo (2026-07-12): Hermes chỉ đọc DUY NHẤT một file SOUL.md toàn cục tại ~/.hermes/SOUL.md. Các file SOUL.md riêng trong từng profile của phòng ban (~/.hermes/profiles/{phòng}/SOUL.md) sẽ bị hệ thống bỏ qua và không có tác dụng.

Để định hình tính cách và luồng điều phối của từng phòng ban, hãy sử dụng lệnh gán mô tả:

hermes profile describe it-ai --text "Expert IT & AI engineer. Focus on code quality, devops, automation."
hermes profile describe r-and-d --text "Policy & research analyst. Focus on evidence, citations, methodology."

Dispatcher sẽ dựa vào chính text mô tả này để điều phối task tự động. Không tạo file SOUL.md rác trong thư mục profile.

6. Route List & Department Mapping

Bảng định tuyến (routing map) và danh sách phòng ban chính thức của Nova (gộp R&D về thread_id: 14):

Mã phòng ban Tên phòng ban Prefix Telegram Chat ID Telegram Thread ID
IT IT & AI IT -1003707758328 18
RD R&D RD -1003707758328 14
SM Strategy & Marketing SM -1003707758328 12
WR Writers WR -1003707758328 1591
GQ Grill & QA GQ -1003707758328 20

Python MAPPING in handoff.py

MAPPING = {
    # IT & AI
    "it-ai": {"name": "IT & AI", "chat_id": "-1003707758328", "thread_id": 18, "prefix": "IT"},
    "it": {"name": "IT & AI", "chat_id": "-1003707758328", "thread_id": 18, "prefix": "IT"},
    # R&D (merge Policy Lab + Research & Inno. về thread_id 14)
    "r-d": {"name": "R&D", "chat_id": "-1003707758328", "thread_id": 14, "prefix": "RD"},
    "rd": {"name": "R&D", "chat_id": "-1003707758328", "thread_id": 14, "prefix": "RD"},
    "policy-lab": {"name": "R&D", "chat_id": "-1003707758328", "thread_id": 14, "prefix": "RD"},
    "pl": {"name": "R&D", "chat_id": "-1003707758328", "thread_id": 14, "prefix": "RD"},
    "research-inno": {"name": "R&D", "chat_id": "-1003707758328", "thread_id": 14, "prefix": "RD"},
    "ri": {"name": "R&D", "chat_id": "-1003707758328", "thread_id": 14, "prefix": "RD"},
    "rs": {"name": "R&D", "chat_id": "-1003707758328", "thread_id": 14, "prefix": "RD"},
    # Strategy & Marketing
    "strategy-marketing": {"name": "Strategy & Marketing", "chat_id": "-1003707758328", "thread_id": 12, "prefix": "SM"},
    "sm": {"name": "Strategy & Marketing", "chat_id": "-1003707758328", "thread_id": 12, "prefix": "SM"},
    "marketing": {"name": "Strategy & Marketing", "chat_id": "-1003707758328", "thread_id": 12, "prefix": "SM"},
    "mk": {"name": "Strategy & Marketing", "chat_id": "-1003707758328", "thread_id": 12, "prefix": "SM"},
    # Writers
    "writers": {"name": "Writers", "chat_id": "-1003707758328", "thread_id": 1591, "prefix": "WR"},
    "wr": {"name": "Writers", "chat_id": "-1003707758328", "thread_id": 1591, "prefix": "WR"},
    # Grill & QA
    "grill-qa": {"name": "Grill & QA", "chat_id": "-1003707758328", "thread_id": 20, "prefix": "GQ"},
    "gq": {"name": "Grill & QA", "chat_id": "-1003707758328", "thread_id": 20, "prefix": "GQ"},
    "grill-brainstorm": {"name": "Grill & QA", "chat_id": "-1003707758328", "thread_id": 20, "prefix": "GQ"},
    "gb": {"name": "Grill & QA", "chat_id": "-1003707758328", "thread_id": 20, "prefix": "GQ"},
}

7. Dashboard & Remote Access (Tailscale)

Nhi cần access dashboard từ điện thoại và mọi thiết bị → dùng Tailscale VPN (không public Internet).

Setup 1-lần trên VPS

curl -fsSL https://tailscale.com/install.sh | sh
tailscale up
# Mở link https://login.tailscale.com/a/... → login Google

Hàng ngày

Lưu ý

Handoff-to-QA pattern

Khi task nghiên cứu đã có output đủ để Grill-QA review, ưu tiên reassign + comment thay vì cố complete nếu task vẫn còn phụ thuộc cha hoặc chưa vào terminal state. Mẫu thực hành:

hermes kanban comment t_<id> "Deliverable ready for QA; file: content/.../topic.md"
hermes kanban reassign t_<id> grill-qa --reason "Handoff to Grill-QA for review"

Pitfall: hermes kanban complete có thể fail trên task todo còn parent dependency. Đó không phải lỗi của handoff; chỉ cần chuyển assignee sang grill-qa và để QA tiếp tục luồng review.

8. Communication Style (Nhi Vo)