Hermes Agent Kanban: Khi Một Agent Không Đủ Sức Gánh Cả Dự Án

TL;DR

Hermes Agent Kanban là task board SQLite-backed, chia sẻ giữa mọi profile Hermes trên một host.
Dispatcher tick mỗi 60 giây: reclaim task stale, phát hiện crash (POSIX kill(pid, 0)), auto-decompose triage, promote dependency, spawn worker.
Agent dùng kanban_* Python tools - KHÔNG shell ra CLI - để đọc và cập nhật board từ bất kỳ backend nào (Docker, SSH, local).
Vòng đời task: triage → todo → ready → running → blocked → done → archived. Mỗi lần claim tạo một row task_runs riêng - lịch sử không bao giờ mất.
Ba lỗi phổ biến nhất: wrong board (shell cũ), scratch ghost (output không có workspace cố định), stale lock (card hiện running nhưng process đã chết).

Vấn Đề: Context Window Không Phải Manager

Bạn đã bao giờ để một task "running" suốt 40 phút trên board, rồi nhận ra worker đã chết từ sớm mà không ai hay? Hoặc tạo một task, để output vào scratch workspace, rồi khi task complete thì mọi file biến mất vì scratch là ephemeral? Những thất bại này không có gì dramatic cả - chúng im lặng. Buổi chiều cứ thế trôi qua từng mẩu stale state, từng lời hứa hẹn không được thực hiện.

Đây chính là vấn đề cốt lõi mà Tony Simons đặt tên "One Agent Is The Wrong Unit."

Nhiều người cố chạy công việc phức tạp trong một chat session duy nhất vì ban đầu nó trông nhanh và gọn. Một prompt, một worker, một stream output sạch sẽ. Rất ngăn nắp. Rất giả tạo. Rồi công việc phình ra, transcript dài thêm, ai đó cần parallel research, ai đó cần review, một worker crash. Session bắt đầu mang theo nửa project trong prompt residue và nửa còn lại trong hy vọng. Kết quả: context soup - một memory leak với formatting đẹp.

Context window không phải manager. Nó chỉ là một hộp có giới hạn. Giải pháp không phải prompt thông minh hơn mà là board, contract, và receipts.

Hermes Kanban Là Gì

Hermes Agent Kanban là durable task board, chia sẻ giữa mọi Hermes profile trên một host, cho phép nhiều named agent cộng tác mà không cần fragile in-process subagent swarm. Mỗi task là một row trong ~/.hermes/kanban.db, mỗi handoff là một row ai cũng đọc và ghi được, mỗi worker là một OS process với identity riêng.

Khác biệt chính so với delegate_task - tool call synchronous của Hermes:

delegate_task: RPC call (fork → join). Parent block chờ child trả về. Child là anonymous subagent, không có memory. Nếu fail thì fail, audit trail mất khi context compress.
Kanban: Durable message queue + state machine. Fire-and-forget sau khi create. Child là named profile với persistent memory. Crash → reclaim → retry. Audit trail là durable rows trong SQLite mãi mãi.

Câu phân biệt ngắn nhất: delegate_task là function call; Kanban là work queue mà mọi handoff là một row bất kỳ profile (hoặc human) đều có thể đọc và sửa.

Kiến Trúc Bên Trong

Kiến trúc Hermes Kanban: Dispatcher 60s, kanban.db, và các agent chuyên biệt

Dispatcher tick mỗi 60 giây, phát hiện crash trong cùng chu kỳ, tự động promote dependency và spawn worker mới.

Stripped down đến core, Hermes Kanban có ba thành phần:

SQLite database tại ~/.hermes/kanban.db - WAL mode, concurrent reads, serialized writes bằng BEGIN IMMEDIATE và compare-and-swap (CAS) cho tasks.status và tasks.claim_lock. Bốn tables chính: tasks, task_links, task_comments, task_events.
Dispatcher loop chạy embedded trong Hermes gateway, tick mỗi 60 giây theo sáu phase: reclaim stale claims → detect crashed workers → auto-decompose triage → promote dependencies → claim & spawn workers → wait.
kanban_* Python tools - agent tương tác trực tiếp với board thông qua tool calls, KHÔNG shell ra hermes kanban. Lý do: backend portability (Docker/SSH không cài hermes), no shell-quoting fragility, structured JSON error handling.

Crash detection đặc biệt nhanh: dispatcher dùng POSIX kill(pid, 0) probe - một lệnh check xem process có tồn tại không mà không gửi signal thực. Nếu PID đã biến mất (segfault, OOM-kill, systemd stop), task về lại ready và crash được ghi vào task_runs ngay trong tick đó - 60 giây, không phải 15 phút chờ TTL expire.

Xây Dựng Board Đầu Tiên

Đừng over-design board đầu. Bắt đầu với setup đơn giản nhất có thể hoạt động:

# Xem board hiện tại
hermes kanban boards show

# Tạo board mới với default workdir
hermes kanban boards create my-project \
  --switch \
  --default-workdir /home/user/projects/my-project

Flag --default-workdir quan trọng hơn nó trông. Nếu board biết file nên nằm ở đâu, bạn ngừng mất thời gian tự hỏi "files đi đâu rồi?". Đây không phải vấn đề triết học - đây là vấn đề path.

Tạo task đầu tiên:

hermes kanban create "Khảo sát source notes" \
  --assignee hkg-researcher \
  --workspace dir:/home/user/projects/my-project \
  --max-runtime 30m \
  --json

Dùng --json khi cần task id không bị chôn vùi trong scrollback. Nếu bạn chain các task với nhau, machine-readable output không phải luxury - đó là sự khác biệt giữa một dependency graph sạch và một terminal đầy vibes.

Cho task chưa rõ spec, park nó vào triage thay vì giả vờ đã sẵn sàng:

hermes kanban create "Clarify requirement" \
  --assignee hkg-director \
  --triage \
  --json

--triage dành cho requests chưa đủ spec. --initial-status blocked dùng khi task rõ nhưng cần quyết định từ con người trước khi worker có thể tiến tiếp.

Vòng Đời Task: Contract Nhỏ Hơn Prompt Khổng Lồ

Pattern cơ bản: khảo sát trước, viết sau.

# Task 1: Research
hermes kanban create "Khảo sát source notes" \
  --assignee hkg-researcher \
  --workspace dir:/home/user/projects/my-project \
  --max-runtime 30m \
  --json

# Task 2: Draft (phụ thuộc task 1)
hermes kanban create "Viết bài từ khảo sát" \
  --assignee hkg-writer \
  --parent <survey-task-id> \
  --workspace dir:/home/user/projects/my-project \
  --max-runtime 2h \
  --json

# Task 3: Review (phụ thuộc task 2)
hermes kanban create "Review drift và repetition" \
  --assignee hkg-reviewer \
  --parent <draft-task-id> \
  --workspace dir:/home/user/projects/my-project \
  --max-runtime 30m \
  --json

Dependency DAG tự động: task ở todo cho đến khi toàn bộ parent tasks đều done, sau đó tự promote sang ready. Không cần coordinate thủ công.

Khi task được nhận:

# Claim task với TTL 15 phút (lease, không phải ownership)
hermes kanban claim <task_id> --ttl 900

# Block nếu cần quyết định con người
hermes kanban block <task_id> "Cần source notes trước khi draft"

# Schedule nếu chỉ thiếu thời gian
hermes kanban schedule <task_id> "Chờ answer lúc 3 PM"

# Promote khi upstream done
hermes kanban promote <task_id> "Survey xong, có thể bắt đầu draft" --json

Complete với structured handoff - đây là phần quan trọng nhất:

hermes kanban complete <task_id> \
  --summary "Đã draft article-v5 từ review notes" \
  --metadata '{"changed_files":["drafts/article-v5.md"],"tests_run":0,"decisions":["giữ title và opener","thêm lifecycle section","cắt bớt repetition"]}'

Summary là cho con người. Metadata là cho downstream workers và future you. Nếu quan trọng sau này, đưa vào handoff ngay bây giờ. Không có secrets hay raw logs trong metadata - chỉ pointers và summaries.

Receipts Beat Vibes: Cách Debug Board

Dashboard có thể làm bạn cảm thấy mọi thứ đang chạy tốt khi thực tế worker state đã stale, stuck, hoặc chết. Đó là lý do bạn phải tin vào receipts trước.

Khi có mùi bất thường, đừng đoán - pull state:

# Xem task, comments, events
hermes kanban show <task_id> --json

# Xem có thực sự có attempt hay không
hermes kanban runs <task_id> --json

# Tail output của worker (không scroll qua wall of noise)
hermes kanban log <task_id> --tail 4000

# Follow event stream nếu task vẫn đang thay đổi
hermes kanban tail <task_id>

Rồi kiểm tra process thực sự:

pgrep -af 'hermes.*kanban.*<task_id>'
ps aux | grep 'hermes.*kanban' | grep '<task_id>'

Nếu board nói running nhưng không có live process và runs không show healthy attempt, bạn đang có stale lock hoặc dead worker. Đừng tranh luận triết học với UI. Reclaim nó:

hermes kanban reclaim <task_id> --reason "stale lock, no live process"

Chuỗi kiểm tra này tiết kiệm nhiều buổi chiều hơn bất kỳ lượng confidence nào.

Ba Lỗi Phổ Biến Nhất

Hầu hết nỗi đau với Kanban không phải mystery kiến trúc phức tạp. Đó là ba lỗi đơn giản đang mang những cái mũ khác nhau.

1. Wrong Board

Cắn khi bạn đang chuyển nhanh qua nhiều shell và một terminal vẫn đang point vào board cũ. Title trông đúng. Task id trông đúng. Nhưng task lại nằm sai queue. hermes kanban boards show tồn tại vì lý do này, và hermes kanban boards switch <slug> không phải optional theater. Nếu bạn đang bounce giữa các project, switch một cách có chủ ý và ngừng tin vào may mắn của shell bạn mở lần cuối.

2. Scratch Ghost

Worker xong việc, summary trông sạch sẽ, rồi bạn đi tìm file và nhận ra output nằm trong scratch workspace - một dead-end mà không ai theo dõi. Bài viết, notes, proof, handoff - giờ chỉ tồn tại như ký ức về công việc. Đó là lý do dir:<absolute-path> tồn tại và board default workspace có ích đến vậy. Bạn muốn file ở nơi người khác có thể mở, diff, và tin tưởng mà không cần đuổi theo temp paths.

3. Stale Lock

Đây là cái xấu xí nhất vì nó nói dối lịch sự. Card nói running. Dashboard vẫn có cảm giác sống. Log dừng từ lúc nào. Process table trống. Rồi bạn nhận ra board đang kể một câu chuyện về công việc không còn xảy ra nữa. Đây là lúc receipts chứng minh giá trị. show cho biết task state. runs cho biết có attempt thực không. log --tail cho biết output dừng ở đâu. tail cho biết event stream có còn moving không. Rồi live process check cho biết có worker thật sau curtain hay chỉ là một card với stage makeup.

Bốn trạng thái không phải synonyms:

Triage: spec là mush
Blocked: thiếu quyết định từ con người
Scheduled: time là dependency
Running: process đang alive ngay lúc này

Blur chúng lại với nhau, bạn ngừng chạy một system và bắt đầu chạy một superstition machine.

Khi Nào KHÔNG Nên Dùng Board

Điều trung thực này quan trọng vì nó giữ lời khuyên đáng tin cậy.

Task một-lần nhỏ không deserve một board. Mọi thứ khác thì có.

Nếu công việc là một lookup nhanh, chỉnh sửa nhỏ, hoặc một câu trả lời ngắn xong trước khi cà phê nguội, Kanban chỉ thêm overhead. Đừng bọc ceremony quanh thứ không cần nó.

Dùng chat cho việc nhỏ:

"Syntax chính xác của hermes kanban promote là gì?"
"Rename heading này."
"--max-runtime có nhận raw seconds không?"

Dùng board khi công việc cần bất kỳ yếu tố nào sau:

Parallel workstreams
Review gates
Crash recovery
Durable handoff
Specialist profiles
State phải survive được khi shell chết
Công việc kéo dài nhiều giờ hoặc ngày

Ranh giới rõ ràng: "Rewrite article-v5 từ review notes, giữ draft task, review task, và fallback recovery path nếu worker bị reclaim giữa chừng" - đó là việc cần board. "Syntax của kanban promote là gì?" - đó là việc giữ trong chat.

Operator Sở Hữu Judgment

Phần này không thể thương lượng.

Agent có thể làm việc. Agent có thể recommend scope. Agent có thể thực hiện contract và handoff sạch sẽ. Agent không được quyết định brief, sequencing, hoặc liệu board có xứng đáng hay không. Đó không phải limitation - đó là thiết kế.

Task cần board vì con người quyết định nó cần durable coordination.
Task cần review vì con người quyết định output cần thêm một cặp mắt khác.
Task cần schedule vì con người quyết định thời gian quan trọng.
Task quá nhỏ nên ở trong chat vì con người quyết định ceremony không xứng đáng.

Kể cả những quyết định khó cũng là quyết định của con người. Nếu draft thiếu source notes, block nó. Nếu job chỉ cần wake up sau, schedule nó. Nếu graph malformed, link các mảnh lại hoặc recreate card. Nếu task chết và workspace sai, archive và làm lại thay vì giả vờ mình đang efficient.

Đây không phải agent yếu. Đây là agent đang ở trong contract của mình. Và đó là toàn bộ điểm mấu chốt của system. Hermes Kanban không phải để làm một agent cảm thấy thông minh hơn. Nó ở đây để làm một team agents và humans kém fragile hơn.

Kết

Một agent ổn đến khi công việc mọc răng. Sau điểm đó, bạn không cần chat thông minh hơn. Bạn cần durable coordination.

Receipts beat vibes, và durable coordination beat hy vọng rằng một agent nhớ mọi thứ.

Bắt đầu từ setup đơn giản nhất: tạo board, tạo task nhỏ đủ để xong và đủ to để verify, chú ý xem gì fail đầu tiên. Hệ thống được thiết kế để survive chính xác những thí nghiệm đó.

• via Hermes Agent Docs - Kanban