Hatch

Embedded harness cho một squad coding-agent làm chung trên một repo — tối ưu instructions + context + phối hợp cho nhiều agent, trên nhiều surface. Sản phẩm thuộc hệ sinh thái Finolabs (Fioenix + Dinosaur Labs).

Tên gọi

Hatch = ổ trứng nở ra thành viên đội. Đặt tên theo chủ đề khủng long/phượng hoàng của Finolabs, và khớp xương sống thiết kế — một bầy phối hợp săn mồi. (Nghĩa kép cũ "hatch run <ticket> nở một agent" thuộc về mô hình orchestrator trước pivot, nay đã archived — xem doc 20.)

Nó là gì

Hatch là một embedded harness cho coding agent. Coding agent là entrypoint — user mở Claude Code / Codex / Antigravity CLI (agy) / Kiro ngay trong workspace, và agent tự lái mình. Hatch không spawn, không điều khiển agent; nó cung cấp một lớp nền chung mà mọi agent với tới qua MCP server:

• một chat dùng chung (bus) — đồng thời là backlog: một thread = một task;
• một Knowledge Base dùng chung (bộ nhớ chung bền của hệ);
• một ledger audit append-only.

Nhờ đó nhiều agent trên cùng một repo phối hợp theo phong cách async kiểu Slack (mở thread cho mỗi task, brief tiến độ trong thread, @mention đồng đội, chat_search/kb_search để nhớ lại), giữ vai trò khác nhau theo một quy trình kiểu Agile, để lại audit trail đầy đủ, và không lãng phí token vì mỗi agent chỉ nạp đúng phần context của mình.

Lưu ý về docs. Các doc 00–19 mô tả thiết kế GỐC (trước pivot) — khi Hatch còn là orchestrator tự lái agent. Mô hình hiện hành là doc 20 — embedded-harness pivot. Khi đối chiếu hành vi CLI thực tế, doc 20 thắng.

Phép ẩn dụ neo: một đội Agile người

Mọi thành phần trong Hatch đều có một đối ứng trong một squad người. Đây là la bàn thiết kế — khi phân vân, hỏi "đội người làm việc này thế nào?".

Thành phần Hatch	Đối ứng trong squad người
charter.md	Team charter / mục tiêu sản phẩm
roles/	Bản mô tả công việc (JD) từng vai
registry.yaml	Danh bạ nhân sự + năng lực + ai giữ vai gì
kb/	Wiki / bộ não chung của đội (Confluence) — đọc và ghi
workflow.yaml	Quy trình làm việc của đội — template, sửa được
board/	Bảng sprint (Jira)
ledger/	Sổ standup / nhật ký hoạt động / git log
protocol/	Working agreements của đội
chat (bus)	Slack của đội — kênh trao đổi và backlog (mỗi thread = một task)
compiler	Bộ sinh tài liệu onboarding + working agreements cho từng người mới
MCP server	Cánh cửa mỗi người dùng để vào Slack chung + wiki chung
agent lead/Conductor	Engineering Manager / Scrum Master — là một agent tự lái, không phải Hatch

Bộ nhớ chung. Agents không chia sẻ RAM (mỗi con một process), nhưng cùng khai thác và đóng góp vào Knowledge Base (kb/) — y như một đội người không đọc được não nhau nhưng cùng tra cứu và cập nhật một wiki. KB là bộ nhớ chung bền của hệ; agent vừa input (tra cứu để khỏi suy diễn lại) vừa ghi lại (quyết định, bài học, gotcha) khi làm. Xem 09-knowledge-base.

Bốn agent, bốn vai mặc định

Agent	Vai mặc định	Vì sao
Claude Code (chính)	Architect / Tech Lead + Conductor	Reasoning sâu, giữ bức tranh tổng thể, lập kế hoạch
Kiro	Spec-driven Implementer	Mạnh quy trình PRD → design → tasks
Codex	Autonomous Implementer	Thực thi nhanh, lặp nhiều
Antigravity CLI	Implementer / Utility	Linh hoạt, gánh việc phụ

Bảng trên chỉ là template khởi đầu. Vai trò là do người dùng tự cấu hình ở từng project qua registry.yaml của project đó — không fix cứng. Cùng một agent có thể giữ vai khác nhau ở các project khác nhau. Xem 02-roles.

Bảy trụ thiết kế

1. Single Source of Truth → compile xuống từng agent. Một nguồn canonical (.hatch/: charter.md, roles/, registry.yaml, workflow.yaml), một compiler sinh ra CLAUDE.md / AGENTS.md / GEMINI.md / .kiro/steering tự động. Không copy-paste, không drift.
2. Knowledge Base dùng chung (kb/) — bộ nhớ chung bền của hệ; mọi agent đọc và ghi qua MCP. Thay cho "shared memory" mà các process không có.
3. Token optimization = context phân tầng (L0 mission → L1 role → L2 task + KB on-demand). Mỗi agent chỉ nạp tầng của nó + thread task đang làm.
4. Role assignment per-project — map vai ↔ điểm mạnh từng agent; user tự thiết kế ở mỗi project qua registry.yaml.
5. Coordination protocol = chat async. Phối hợp qua chat dùng chung (bus): mở thread cho mỗi task, brief tiến độ trong thread, @mention để nhờ. Không agent nào spawn hay gọi trực tiếp agent khác; Hatch cũng không. Audit qua ledger.
6. Workflow = protocol được COMPILE, không phải engine. workflow.yaml (Agile: scrum/kanban/spec-first/…) + roles + DoD vẫn là SSOT, nhưng compile biến chúng thành văn bản hành vi (prose) tiêm vào instruction surface từng agent. Agent đọc và tự tuân theo; Hatch không cưỡng chế bằng code.
7. Governance & audit — ledger append-only; Definition-of-Done là self-check agent tự chạy; thẩm quyền agent khai trong SSOT.

Mô hình phối hợp: chat async, agent tự lái

• Agent đầu tiên user mở (thường Claude Code) mặc định là Conductor/orchestrator và có thể kiêm các vai khác (architect/reviewer…). Việc này khai trong registry.yaml và tiêm qua compile vào CLAUDE.md (kèm khối "orchestrator").
• Conductor bẻ việc → mở một thread cho mỗi task trong chat, brief, @tag agent phù hợp.
• Agent được tag đọc thread, làm, brief kết quả lại trong cùng thread. Trạng thái task suy ra từ hội thoại (post type done/block/decision), không cần lane/claim/gate engine.
• Reviewer ≠ implementer tự chạy DoD self-check rồi báo done trong thread.
• Tất cả async (kiểu Slack): agent chỉ phản hồi khi nó đang chạy. Không lời gọi trực tiếp giữa agent, không ai spawn ai — y như một đội người trao đổi qua Slack.

Đọc docs theo thứ tự

Quan trọng: Doc 00–19 mô tả thiết kế GỐC trước pivot (Hatch tự lái agent, orchestrator là entrypoint, board là control panel, backlog kiểu Jira). Mô hình hiện hành nằm ở doc 20. Khi mâu thuẫn, doc 20 thắng. Đọc doc 20 trước để hiểu mô hình thực tế, rồi dùng 00–19 cho bối cảnh/ý tưởng nền.

#	Doc	Nội dung
00	vision	Vấn đề, tầm nhìn, phép ẩn dụ squad
01	architecture	6 trụ, layout .hatch/, các thành phần
02	roles	Mô hình vai, map năng lực agent
03	coordination-protocol	Hybrid, board, claim/lock, handoff, DoD
04	context-compiler	SSOT vs KB, compile per-agent, 3 tầng token
05	workflow	Workflow-as-template, lifecycle, ceremonies
06	governance	Ledger, gates, giới hạn thẩm quyền
07	orchestrator	Phase 3: CLI hatch launch & drive agent
08	roadmap	Lộ trình Phase 1 → 2 → 3
09	knowledge-base	KB dùng chung: cấu trúc, đọc/ghi, vs SSOT/ledger
10	agent-adapters	Compile surface + headless invocation từng agent CLI
11	communication	Agents nói chuyện trực tiếp: DM · ask/reply · convene
12	ceremonies-escalation	Standup · retro · planning · escalation · decision→ADR
13	management	(thiết kế) Workload · performance · budget/lương — góc CEO/CTO
14	org-and-cadence	(thiết kế) Org-chart/uỷ quyền · external deps · heartbeat
15	obsidian-kb	(thiết kế) Obsidian vault làm KB chính qua CLI
16	document-templates	(thiết kế) Template/spec tài liệu theo framework, custom được
17	pre-implementation	Quyết định cần chốt trước khi implement toàn bộ
18	observability	Quan sát agents: transcript · TUI · tmux/Zellij
19	going-real	Chuyển từ mock sang agent CLI thật (doctor, creds, an toàn)
20	embedded-harness-pivot	MÔ HÌNH HIỆN HÀNH — Hatch là embedded harness (MCP + chat=backlog), agent tự lái; thắng khi mâu thuẫn

Sơ đồ trực quan: overview (bản đồ tổng plaintext) · architecture-diagram (kiến trúc + workflow + sequence).

Spec kỹ thuật: registry · ticket · ledger · workflow

Cài đặt & Onboarding (user mới)

Yêu cầu

• Go 1.24+ (build hatch) và git (Hatch dùng filesystem + git làm database).
• Ít nhất một coding agent CLI để chạy thật: Claude Code (claude), Codex (codex), Antigravity (agy), hoặc Kiro (kiro-cli). Không bắt buộc đủ cả bốn — hatch doctor chỉ cần ≥1 sẵn sàng. Muốn thử trước khi cài agent thì dùng demo bên dưới.

Bước 1 — Cài hatch

# A. Nhanh nhất: build + dựng workspace demo để xem ngay (không cần agent thật)
git clone https://github.com/fioenix/hatch && cd hatch
./scripts/onboard.sh                 # build bin/hatch + demo trong .hatch-demo/

# B. Cài lên PATH
make install                         # go install ./cmd/hatch  → $(go env GOPATH)/bin
#   hoặc:  go install github.com/fioenix/hatch/cmd/hatch@latest
export PATH="$(go env GOPATH)/bin:$PATH"   # nếu chưa có
hatch --version

Bước 2 — Setup máy một lần: hatch setup

Chạy một lần cho mỗi máy. hatch setup tạo workspace global ~/.hatch (mặc định cho mọi repo) và wire các coding-agent CLI mà MCP config của chúng nằm ở $HOME (codex, agy) cùng plugin Claude Code:

hatch setup                       # có terminal → hỏi chọn client; --dry-run để xem trước
hatch setup --client cc,codex,agy # non-interactive (CI/script); --yes để chắc chắn không hỏi

• cc — in hướng dẫn cài plugin Claude Code (MCP + skill hatch-chat + /hatch):

  /plugin marketplace add fioenix/hatch
  /plugin install hatch@hatch
  

• codex — gọi codex mcp add hatch -- hatch mcp --as codex (→ ~/.codex/config.toml); cần codex trên PATH.
• agy — Antigravity CLI (khác Gemini CLI legacy) nạp MCP chỉ từ file HOME-level: ~/.gemini/config/mcp_config.json (cũ: ~/.gemini/antigravity-cli/mcp_config.json, nay symlink). Project-local bị bỏ qua (issue #60).
• kiro — project-scoped → không wire ở đây, để hatch init lo trong repo.

Vì codex/agy chạy ở thư mục bạn mở, chúng tự dùng .hatch local của repo (qua cwd resolution) và fallback ~/.hatch global — nên wire một lần là dùng được ở mọi repo, không lỗi.

Bước 3 — Vào repo: hatch init

Chạy trong repo dự án. hatch init tạo .hatch local (đè global), chọn một client làm orchestrator (--client, mặc định cc), compile surfaces, và đăng ký MCP cho client chỉ-wire-được-ở-repo (kiro → .kiro/settings/mcp.json). claude/codex/agy đã wire một lần ở hatch setup (plugin / ~/.codex / ~/.gemini) nên init không ghi .mcp.json. Mặc định init thêm vào .gitignore chỉ runtime của .hatch (board/ bus/ ledger/ compiled/ mcp/ — chat/ledger per-checkout, snippet regenerable); còn SSOT (charter/registry/roles/context/workflow/protocol) + kb/ + surfaces thì commit bình thường để chia sẻ squad config:

cd /đường/dẫn/repo-của-bạn
hatch init                   # orchestrator = Claude Code (mặc định); .hatch local
hatch init --client codex    # orchestrator = Codex → khối orchestrator vào AGENTS.md
hatch init -w kanban         # đổi workflow template (8 loại); --global để nhắm ~/.hatch

--client ghi orchestrator: <agent-id> vào registry.yaml (giữ nguyên comment) và compile đặt khối orchestrator vào surface của client đó. Các agent còn lại là team mà orchestrator điều phối qua chat. Sửa charter.md (sản phẩm) + registry.yaml (ai giữ vai gì) cho đúng đội rồi chạy lại hatch compile.

Cơ chế resolve: lệnh hatch tìm .hatch local (đi ngược lên từ cwd); không có thì dùng ~/.hatch global. Đặt HATCH_HOME để đổi vị trí global.

Bước 4 — Compile / validate / doctor

hatch compile                # SSOT → CLAUDE.md · AGENTS.md · GEMINI.md · .kiro/steering/ + đăng ký MCP
hatch validate               # kiểm tra registry + workflow
hatch doctor                 # agent CLI nào đã cài + đã đăng nhập (chỉ gọi lệnh auth, KHÔNG quét thư mục creds)

Bước 5 — Làm việc & quan sát

# Mở coding agent NGAY TRONG workspace (vd Claude Code). Nó đọc CLAUDE.md + nạp MCP
# (Claude qua plugin, codex/agy qua config $HOME — đã set ở `hatch setup`), rồi tự lái:
# mở thread mỗi task, @tag đồng đội, ghi KB qua MCP.
cd /đường/dẫn/repo-của-bạn && claude          # hoặc codex / agy / kiro-cli

# Bạn (con người) quan sát read-only ở terminal khác:
hatch chat       # live chat (threads + messages) + squad stats ở footer
                 #   (hatch board / hatch watch = alias mở cùng view)
hatch status     # tóm tắt thread + roster
hatch msg --from human:operator -c '#design' "@claude-code ưu tiên streaming"   # chèn ý kiến

Trên môi trường remote/CI không cài được agent thật: ./scripts/onboard.sh dựng demo (post một thread mẫu, in status/thread) để bạn thấy luồng mà không tốn token.

CLI (hatch)

Hatch là CLI viết bằng Go (single binary). Đây là embedded harness: agent là entrypoint, Hatch lo SSOT/chat/KB và phơi chúng qua MCP. Bộ lệnh mặc định (xem internal/cli/root.go):

./scripts/onboard.sh         # build + dựng demo workspace để thử ngay — hoặc `make onboard`
make build                   # → bin/hatch
bin/hatch setup               # 1 lần/máy: tạo ~/.hatch global + wire codex/agy/plugin (cc|codex|agy|kiro)
bin/hatch init --client codex # trong repo: .hatch local + chọn orchestrator (mặc định cc) + compile (--dry-run xem trước)
bin/hatch compile             # SSOT → CLAUDE.md / AGENTS.md / GEMINI.md / .kiro/steering
                              #   (protocol prose: workflow + chat etiquette + DoD self-check + khối orchestrator
                              #    cho lead) + đăng ký MCP cho kiro (.kiro/settings/mcp.json);
                              #    snippet .hatch/mcp/* cho codex/agy (claude dùng plugin)
bin/hatch compile --check     # CI: fail nếu output stale so với SSOT
bin/hatch validate            # kiểm tra registry + workflow
bin/hatch mcp --as claude-code  # MCP server (stdio) phơi tool chat + KB với danh tính agent này
                              #   (--as bỏ trống → $HATCH_AGENT, rồi agent kind=claude đầu tiên)
bin/hatch status              # read-only: tóm tắt thread chat (task) + roster agent
bin/hatch chat                # read-only live TUI: threads + chat + squad stats (footer)
bin/hatch board               # alias của `hatch chat` (cũng có `watch`)
bin/hatch kb add --type decision --title "CSV streaming" --tags export
bin/hatch kb query export     # kb add|query|index|link|backlinks|graph|open
bin/hatch msg --from human --channel '#design' "Streaming hay buffer?"   # human inject vào chat
bin/hatch inbox claude-code   # message gửi tới một agent
bin/hatch thread <id>         # xem một thread (task)
bin/hatch channel ls          # channel ls|show|join|leave|members
bin/hatch search export       # full-text qua chat
bin/hatch doc ...             # doc templates · logs · org · sync · hook · doctor

Luồng dùng thực tế:

hatch setup (1 lần/máy) → hatch init (trong repo) → mở coding agent NGAY TRONG workspace
   (CLAUDE.md + MCP từ plugin/$HOME config đã wire nó vào chat + KB chung) → agent tự lái qua MCP
Người xem bằng hatch board / hatch chat / hatch status; chèn ý kiến bằng hatch msg.

Lệnh archived (tùy chọn). Bộ operator tự-lái (run, plan, watch, tick, orchestrator, workflow-engine gate/escalate/ticket, ceremony/standup, ask/convene, pair/mob, presence, oncall, cost/budget, workload/perf, report) không nằm trong binary mặc định. Chúng được archive sau build tag và chỉ build khi cần: go build -tags hatch_legacy. Khôi phục được, không bị xóa.

Trạng thái implement

Pivot embedded-harness đã implement (xem doc 20):

• MCP server (hatch mcp --as <agent>, stdio) trên bus/KB — tools whoami · chat_open · chat_post · chat_read · chat_inbox · chat_search · chat_channels · kb_add · kb_search (internal/mcpserver, internal/cli/mcp.go).
• compile đổi mục đích: tiêm protocol (charter + roles + workflow-prose + DoD self-check + chat etiquette + khối orchestrator cho lead) vào CLAUDE.md/AGENTS.md/GEMINI.md/.kiro, kèm đăng ký MCP cho kiro (.kiro/settings/mcp.json merge) + snippet .hatch/mcp/* cho Codex/agy. Claude nạp MCP qua plugin, nên không ghi .mcp.json.
• Claude plugin tại plugin/ (MCP + skill hatch-chat + slash /hatch); .claude-plugin/marketplace.json ở repo root.
• chat/status read-only: hatch chat = live TUI một-view (threads + chat + squad stats ở footer; board/watch là alias); status = tóm tắt thread + roster. Không còn run/claim/compose.
• Operator tự-lái archived sau build tag hatch_legacy (không vào binary mặc định, khôi phục được).
• Cả build mặc định và -tags hatch_legacy đều compile/vet/test green.

Có unit + integration test, CI, Makefile. Mã nguồn: cmd/hatch + internal/. Thiết kế gốc (trước pivot) trong docs/00–19; mô hình hiện hành ở docs/20. Kiến trúc (Lean Hexagonal, ports & adapters): ARCHITECTURE.md.