ra

---
name: herdr-multiagent
description: "Cẩm nang vận hành song song nhiều tác tử lập trình dưới quyền quản lý của Herdr: phân rã giai đoạn, mỗi tác tử có một git worktree + môi trường cô lập + khung cửa sổ (pane) riêng, bản giao việc lưu dưới dạng tệp, giám sát trạng thái, đánh giá và gộp nhánh. Độc lập với loại tác tử: loại tác tử con được lấy từ `herdr pane current` (.result.pane.agent) và khớp với bộ điều phối (omp, opencode, claude, codex, kimi, ...). Sử dụng cho công việc đa tác tử chạy song song trên các worktree tách biệt. Yêu cầu HERDR_ENV=1."
---

# Làm việc đa tác tử thông qua Herdr

Cẩm nang thực hiện: chia phần công việc còn lại của dự án thành các giai đoạn độc lập, giao mỗi giai đoạn cho một tác tử riêng trên git worktree và khung cửa sổ (pane) Herdr riêng của nó, chuyển cho nó bản giao việc dưới dạng tệp, giám sát tiến trình và nghiệm thu kết quả.

Kỹ năng này độc lập với loại tác tử: loại (kind) của các tác tử con bằng đúng loại của bộ điều phối (orchestrator). Khởi chạy từ opencode thì các tác tử con là opencode; từ omp thì chúng là omp; từ claude thì chúng là claude. Không bao giờ gắn cứng (hardcode) loại của bộ điều phối theo trí nhớ và không bao giờ tự chọn một loại "phổ biến".

## 0. Điều kiện tiên quyết

```bash
test "-" = 1   # if this fails, stop - we are not inside Herdr
```

Nếu bước kiểm tra thất bại, hãy báo cho người dùng biết phiên làm việc hiện không chạy dưới Herdr và dừng lại. Không điều khiển Herdr của người khác từ bên ngoài.

Các lệnh quản lý pane/agent cơ bản nằm trong chính kỹ năng của Herdr (`herdr --skill`). Tệp thực thi đã cài đặt là nguồn chuẩn xác nhất về cú pháp; khi không chắc chắn, hãy đọc `herdr agent`, `herdr pane`, `herdr integration` thay vì đoán mò.

## 1. Xác định loại tác tử của chính bạn - trước mọi bước khác

```bash
herdr pane current --current
```

Trường `.result.pane.agent` CHÍNH LÀ loại của bộ điều phối, và cùng giá trị đó sẽ được truyền vào cờ `--kind` cho các tác tử con:

```bash
KIND=$(herdr pane current --current | jq -r '.result.pane.agent')
# without jq:
KIND=$(herdr pane current --current | sed -E 's/.*"agent":"([^"]+)".*/\1/' | head -1)
echo "$KIND"
```

Nếu giá trị rỗng hoặc là `unknown` - hãy hỏi người dùng xem nên khởi chạy các tác tử con bằng loại nào. Ở phần bên dưới, `$KIND` luôn mang ý nghĩa là giá trị đã được phân giải này, không bao giờ là một chuỗi ký tự viết cứng.

Kiểm tra gói tích hợp Herdr cho loại tác tử này (nó cung cấp các lệnh `agent list/wait/prompt`):

```bash
herdr integration status | grep -i "$KIND"
```

- `current` - tốt.
- `not installed` - hãy chạy `herdr integration install "$KIND"`. Chỉ những phiên làm việc **mới** mới nhận diện được gói tích hợp này, vì vậy hãy cài đặt nó TRƯỚC KHI khởi chạy các tác tử con; bản thân bộ điều phối vẫn sẽ không hiển thị trong `agent list`, điều này hoàn toàn bình thường vì nó không cần bị giám sát.
- Loại tác tử không có trong `herdr integration install` (ví dụ: `amp`, `cline`, `kiro`, `maki`) - sẽ không có tính năng giám sát cấu trúc, hãy sử dụng phương án dự phòng ở mục §7 (`pane read` + git). Đây không phải là lỗi chặn tiến trình.

Hãy nêu rõ cho người dùng biết: "children kind = $KIND".

## 2. Phân rã công việc - bước quan trọng nhất, đừng vội vàng

- Đọc kế hoạch/đặc tả dự án và trạng thái hiện tại (`git log`, các bài kiểm thử, `git worktree list`).
- Chia phần công việc còn lại thành các giai đoạn có **vùng tệp không chồng lấn nhau**. Hai tác tử cùng làm việc trên một gói (package) - chỉ thực hiện khi có chủ đích rõ ràng và theo một thứ tự tường minh (làm nối tiếp nhau sau đó, không làm song song).
- Các chỉnh sửa mang tính bổ sung (additive edits) vào những tệp dùng chung (cấu hình, tệp khóa lock) là có thể chấp nhận được - hãy ghi rõ trong bản giao việc là "chỉ thêm mới, không thay đổi chữ ký hàm/cấu trúc cũ"; bộ điều phối sẽ giải quyết xung đột khi gộp nhánh (merge conflicts).
- Viết ra ma trận "giai đoạn -> các tệp ĐƯỢC PHÉP / TUYỆT ĐỐI KHÔNG ĐƯỢC chạm vào".

Trước khi khởi chạy: mọi thứ đã hoàn tất trên nhánh main phải được commit, cây thư mục làm việc phải sạch (clean).

## 3. Worktree + môi trường cô lập cho từng tác tử

```bash
git worktree add ../<proj>-s<N> -b stage-<N>-<name>
```

Bẫy thường gặp với Python: một môi trường ảo (venv) dùng chung sẽ import mã nguồn CỦA TÁC TỬ KHÁC (do cài đặt chế độ editable của kho mã nguồn chính). Hãy cấp cho mỗi worktree một venv riêng của nó:

```bash
cd ../<proj>-s<N> && python -m venv .venv \
  && ./.venv/Scripts/python.exe -m pip install -q -e "./api[dev]"
```

Cài đặt tuần tự nhiều venv trong một lệnh chạy nền duy nhất (bộ nhớ đệm pip được dùng chung). Đối với nền tảng JS: mỗi worktree có thư mục `node_modules` riêng (`npm ci`).

Nếu bộ điều phối có một hook bọc lệnh (như rtk hoặc tương tự): đường dẫn trình thông dịch tương đối (`../.venv/Scripts/python.exe`) trong bản giao việc sẽ không phân giải được qua hook đó (báo lỗi "command not found"). Trong các bản giao việc và prompt, chỉ sử dụng đường dẫn TUYỆT ĐỐI trỏ tới python/npm của worktree đó.

## 4. Bản giao việc (Briefs) - lưu dưới dạng tệp, không truyền trực tiếp trên dòng lệnh

`<repo>/.briefs/stage-<N>.md` (không đưa vào diện theo dõi của git - untracked). Cấu trúc bản giao việc:

- **context**: những gì cần đọc trước tiên (đặc tả, hợp đồng giao diện, các tệp chính), những gì đã được thực hiện xong;
- **task**: các yêu cầu cụ thể có tham chiếu tới từng mục trong bản đặc tả;
- **boundaries**: các tệp được phép/bị cấm chỉnh sửa, "không được rời khỏi worktree", "TUYỆT ĐỐI KHÔNG push";
- **acceptance**: các lệnh chạy kiểm thử/linter chính xác (với đường dẫn trình thông dịch tuyệt đối của worktree đó), "các bài kiểm thử hiện có vẫn phải vượt qua (xanh)", commit vào nhánh riêng của nó, báo cáo cuối cùng.

Bản giao việc không được giả định trước một loại tác tử cụ thể nào: không viết "chạy omp/skill/..." vào đó - hãy viết mục tiêu, ranh giới giới hạn và các lệnh nghiệm thu. Tác tử con sẽ tự quyết định sử dụng công cụ nào của riêng nó.

Câu lệnh prompt gửi cho tác tử rất ngắn gọn: "Hãy đọc tệp <brief> và hoàn thành toàn bộ nội dung trong đó".

## 5. Các khung cửa sổ (Panes): tạo và đặt tên cho chúng NGAY LẬP TỨC

Bố cục khuyến nghị - chính ở bên trái (main-left): khung cửa sổ của bộ điều phối nằm bên trái chiếm toàn bộ chiều cao, tất cả các tác tử con xếp thành một cột ở bên phải, cái này nằm dưới cái kia. Nếu người dùng có các plugin bố cục được xây dựng xoay quanh kiểu main-left, bất kỳ cách sắp xếp nào khác cũng sẽ làm hỏng giao diện của họ. Nếu người dùng yêu cầu rõ ràng một bố cục khác, hãy làm theo ý người dùng.

Tác tử con đầu tiên - `split --current --direction right`, các tác tử con còn lại - `split --pane <previous child> --direction down` BÊN TRONG cột bên phải. TUYỆT ĐỐI KHÔNG chia tách khung cửa sổ của bộ điều phối thêm lần nữa, và không chia tách các khung cửa sổ của tác tử sang bên phải - chỉ tạo chuỗi chia xuống dưới bên trong cột bên phải.

```bash
herdr pane split --current --direction right --cwd "<worktree1>" --no-focus
herdr pane split --pane <agent1-pane> --direction down --cwd "<worktree2>" --no-focus
```

Mã định danh (ID) của khung cửa sổ mới được lấy từ trường JSON `.result.pane.pane_id`. Không làm mất tiêu điểm (focus) hiện tại của người dùng (`--no-focus`). Tác tử con sẽ nhận tên của nó ở bước 6 thông qua lệnh `agent start`; ngoài ra hãy chạy thêm `herdr pane rename <pane_id> "s<N>-<name>"` để dễ nhìn.

## 6. Khởi chạy tác tử con cùng loại với bạn

Cách chuẩn nhất là dùng `agent start`, lệnh này đồng thời xác thực rằng tác tử dự kiến đã thực sự khởi động thành công trong khung cửa sổ:

```bash
herdr agent start s1-<name> --kind "$KIND" --pane <pane_id> -- <autonomy-flags>
```

Tên tác tử phải khớp với biểu thức chính quy `[a-z][a-z0-9_-]{0,31}` và là duy nhất trong số các tác tử đang hoạt động.

### Các cờ tự chủ (Autonomy flags)

Tác tử con hoạt động tự động không cần người giám sát, nếu không nó sẽ bị dừng lại ở các bước chờ phê duyệt. Cờ này thuộc về công cụ CLI của tác tử, không phải của Herdr. Các cờ đã được xác nhận:

| loại (kind) | tham số khởi chạy |
|---|---|
| `omp` | `-- --yolo` |
| `claude` | `-- --dangerously-skip-permissions` (hoặc `--permission-mode bypassPermissions`) |
| `opencode` | `-- --auto` |

Đối với bất kỳ loại tác tử nào khác (codex, gemini, kimi, cursor, copilot, droid, kilo, grok, hermes, qodercli, mastracode, pi, ...), TUYỆT ĐỐI KHÔNG tự bịa ra cờ. Hãy tìm đường dẫn tệp thực thi chuẩn và đọc phần trợ giúp (help) của nó:

```bash
herdr agent start --help        # the --kind help text names the canonical executable
<executable> --help | grep -iE "permission|approve|yolo|auto|dangerous|allow"
```

Nếu không tìm thấy cờ nào - hãy kiểm tra xem CLI đó có chế độ tự chủ trong tệp cấu hình của nó hay không (ví dụ: `~/.omp/agent/config.yml: tools.approvalMode: yolo`, `~/.claude/settings.json: permissions`, `opencode.json: permission`), đồng thời cảnh báo người dùng rằng tác tử con có thể dừng lại để chờ phê duyệt - những trường hợp đó sẽ hiển thị thành trạng thái `blocked` (§7).

### Nếu `agent start` bị hết thời gian chờ (timeout)

Lỗi đã biết trên Windows trong các khung cửa sổ PowerShell: `agent start` gửi một lệnh `Start-Process` bị lỗi cú pháp -> dẫn đến timeout. Cách khắc phục tạm thời - khởi chạy trực tiếp CLI trong khung cửa sổ đó:

```bash
herdr pane run <pane_id> "<executable> <autonomy-flags>"
sleep 3 && herdr pane read <pane_id> --lines 15   # expect the CLI prompt
herdr agent rename <pane_id> s1-<name>            # if herdr recognized the agent
```

Nếu sau đó lệnh `herdr agent explain <pane_id>` vẫn báo không nhận diện được tác tử nào, thì tính năng giám sát cấu trúc không khả dụng cho khung cửa sổ đó - hãy sử dụng phương án dự phòng ở mục §7.

### Bàn giao bản giao việc

KHÔNG gửi qua lệnh `pane run`: phím Enter sẽ bị nuốt mất trong lúc giao diện TUI đang xử lý văn bản được dán vào. Hãy thực hiện qua hai bước có nghỉ giữa chừng:

```bash
herdr pane send-text <pane_id> "Read the file <absolute path to the brief> - that is your brief. Complete it fully (code, tests, linter, commit to your own branch), then give a final report."
sleep 5 && herdr pane send-keys <pane_id> Enter
```

Phương án thay thế chuẩn một khi gói tích hợp đã được cài đặt và `agent start` đã thành công:

```bash
herdr agent prompt s1-<name> "Read the file <brief> and complete it fully" --wait --timeout 300000
```

Kiểm tra lại bằng lệnh `pane read` để chắc chắn rằng bản giao việc ĐÃ THỰC SỰ ĐƯỢC NHẬN: ô nhập liệu trống, tác tử đang làm việc.

## 7. Giám sát - thông qua gói tích hợp, KHÔNG dùng cron

```bash
herdr agent list                       # states of all children
herdr agent wait s1-<name> --until idle --timeout 1800000
herdr agent prompt s1-<name> "<text>"  # push an instruction to a working child
herdr agent read s1-<name> --lines 40
```

Ý nghĩa của các trạng thái: `idle` - sẵn sàng nhận lệnh mới và thẻ (tab) của nó đã được xem trên giao diện người dùng; `done` - cùng là trạng thái nghỉ sau khi hoàn thành công việc chạy nền nhưng chưa được người dùng mở xem (việc đọc qua CLI không đánh dấu thẻ là đã xem); `blocked` - Herdr nhận diện được một giao diện đang chờ phê duyệt/hỏi ý kiến, tác tử con ĐANG CHỜ con người phản hồi; `unknown` - có tác tử đang hiện diện nhưng không thể phân loại trạng thái, đây KHÔNG phải là bằng chứng cho thấy công việc đã hoàn tất.

Vòng lặp của bộ điều phối: gọi `agent wait` lần lượt hoặc theo sự kiện -> chuyển sang bước nghiệm thu (§8).
`blocked` -> chạy `agent read`, tìm hiểu câu hỏi đang vướng, trả lời qua `agent prompt` hoặc hỏi
người dùng. Im lặng đáng ngờ -> chạy `pane read <pane_id>`.

Giữ thời gian chờ (timeout) của lệnh `wait` ở mức vừa phải (~30 phút) và đặt lại sau mỗi lần trả về: các giá trị quá lớn
cuối cùng sẽ báo lỗi "timed out".

Phương án dự phòng khi tích hợp cho `$KIND` không khả dụng hoặc `agent explain` không
nhận diện được tiến trình con (child): định kỳ chạy `herdr pane read <pane_id> --lines 60` cộng với
`git log/status` trong worktree. Chỉ dùng cron như giải pháp cuối cùng, và luôn gỡ bỏ nó
khi hoàn tất.

Phiên của tác tử con bị ngắt đột ngột: phần việc trong worktree vẫn còn nguyên vẹn. Khởi động lại bằng cùng CLI đó
với cờ tiếp tục tương ứng (kiểm tra `--help`): `omp --resume`, `claude --continue`,
`opencode --continue`. Sau đó gửi prompt: "Phiên làm việc của bạn đã bị gián đoạn. Hãy kiểm tra git status
và hoàn thành bản mô tả nhiệm vụ (brief) <file>".

## 8. Nghiệm thu và hợp nhất (Acceptance and merge)

- Trên mỗi nhánh (branch): chạy kiểm thử (tests) + công cụ kiểm tra mã nguồn (linter) ngay trong worktree riêng của nhánh đó, xem xét `git diff main...<branch> --stat`.
- Đừng tin tưởng mù quáng vào báo cáo cuối cùng của tác tử con - hãy tự mình chạy các lệnh nghiệm thu.
- Chỉ hợp nhất (merge) vào nhánh main khi có xác nhận của người dùng; giải quyết thủ công các phần chồng lấn bổ sung.
- Sau khi hợp nhất: chạy `git worktree remove`; xử lý các nhánh theo thỏa thuận với người dùng.
- Giải phóng các khung cửa sổ (panes) của tác tử con mà không chạm vào khung cửa sổ của người dùng.

FILE:README.md
# herdr-multiagent

Một kỹ năng tác tử (agent skill / playbook) giúp điều phối dự án với **nhiều tác tử lập trình chạy
song song** thông qua [Herdr](https://herdr.dev), trình ghép kênh thiết bị đầu cuối (terminal multiplexer) dành cho các tác tử
lập trình — mỗi giai đoạn có một git worktree và một khung cửa sổ (pane) riêng, bản giao việc (brief) dựa trên tệp tin, giám sát
trạng thái và nghiệm thu kết quả.

Kỹ năng này **độc lập với loại tác tử (agent-agnostic)**: loại (kind) của các tác tử con được xác định từ Herdr và
khớp với loại của tác tử điều phối (orchestrator). Khởi chạy từ `opencode`, các tác tử con sẽ là
`opencode`; từ `omp`, chúng là `omp`; từ `claude`, chúng là `claude`. Bất kỳ loại nào
được liệt kê bởi `herdr agent start --help` đều hoạt động (pi, claude, codex, gemini, cursor, devin,
agy, cline, omp, mastracode, opencode, copilot, kimi, kiro, droid, amp, grok, hermes,
kilo, qodercli, maki).

## Nội dung bao gồm

- §1 xác định loại tác tử của chính bạn, kiểm tra tích hợp Herdr cho loại đó;
- §2 phân rã công việc thành các giai đoạn với các vùng tệp tin không chồng lấn;
- §3 worktree + môi trường cô lập (venv / node_modules riêng — nếu không các tác tử
  sẽ import nhầm mã nguồn của tác tử khác thông qua bản cài đặt editable của kho mã chính);
- §4 bản giao việc (briefs) lưu dưới dạng tệp tin, không truyền trực tiếp trên dòng lệnh;
- §5 bố cục khung cửa sổ chính bên trái (main-left pane layout), cờ `--no-focus` (không bao giờ chiếm quyền điều khiển con trỏ của người dùng);
- §6 khởi chạy tác tử con, các cờ tự chủ (autonomy flags) theo từng loại, cách khắc phục lỗi hết thời gian chờ của lệnh `agent start` trên Windows,
  bàn giao brief đúng cách (phím Enter bị `pane run` nuốt mất);
- §7 giám sát thông qua `herdr agent list/wait/prompt/read`, ngữ nghĩa của các trạng thái
  `idle/done/blocked/unknown`, phương án dự phòng dùng `pane read` + git, khôi phục phiên tác tử con
  bị ngắt kết nối;
- §8 nghiệm thu và hợp nhất chỉ khi có sự xác nhận của người dùng.

## Yêu cầu hệ thống

- Herdr, với phiên làm việc đang chạy bên trong một trong các khung cửa sổ của nó (`HERDR_ENV=1`). Bên ngoài
  Herdr, kỹ năng này sẽ dừng lại.
- Git (hỗ trợ worktrees).
- Một CLI tác tử được hỗ trợ nằm trong biến môi trường `PATH`.
- Để giám sát có cấu trúc: chạy `herdr integration install <kind>`. Các loại tác tử chưa có
  gói tích hợp sẽ chuyển sang dùng phương án dự phòng `pane read` + git — không làm gián đoạn công việc.
- Đã được kiểm chứng trên Windows (các khung cửa sổ Git Bash + PowerShell); các câu lệnh tuân theo chuẩn POSIX, kèm theo
  ghi chú rõ ràng ở những chỗ đường dẫn venv trên Windows có sự khác biệt.

## Cài đặt

Một kỹ năng là một thư mục chứa tệp `SKILL.md`. Hãy đặt nó vào thư mục gốc chứa kỹ năng (skills root) của tác tử bạn đang dùng:

| Tác tử (Agent) | Đường dẫn (đã kiểm chứng trên máy của tác giả) |
|---|---|
| omp, pi | `~/.agents/skills/herdr-multiagent/SKILL.md` |
| Claude Code | `~/.claude/skills/herdr-multiagent/SKILL.md` |
| opencode | `~/.config/opencode/skills/herdr-multiagent/SKILL.md` |
| project-local | `<repo>/.agents/skills/herdr-multiagent/SKILL.md` |

Cấu trúc thư mục không đệ quy: `<skills-root>/<skill-name>/SKILL.md`. Một đường dẫn lồng sâu
như `skills/team/herdr-multiagent/SKILL.md` sẽ không được tìm thấy.

Hãy kiểm tra tài liệu CLI của bạn để biết chính xác thư mục gốc chứa kỹ năng — các thư mục này khác nhau tùy theo
từng tác tử, trong khi tệp `SKILL.md` với phần khai báo đầu trang (frontmatter) gồm `name` + `description` đều được đọc theo cùng một cách.

## Cách sử dụng

Gọi tường minh: yêu cầu tác tử "làm việc theo kỹ năng herdr-multiagent", hoặc
gọi lệnh `/skill:herdr-multiagent` (trong omp, khi các lệnh kỹ năng được bật).

Tự động kích hoạt: kỹ năng sẽ tự động được chọn khi nhiệm vụ có nội dung tương tự như "xây dựng phần này bằng
nhiều tác tử chạy song song" và tác tử đang chạy bên trong Herdr.

Việc đầu tiên tác tử thực hiện là kiểm tra `HERDR_ENV=1` và xác định loại của chính nó; sau đó
nó đề xuất phương án phân rã công việc và hỏi xin xác nhận trước khi khởi chạy bất kỳ tác tử con nào.

## Cấu trúc thư mục

```
herdr-multiagent/
├─ SKILL.md      # nội dung kỹ năng: frontmatter (name, description) + §0–§8
└─ README.md     # tệp này, dành cho con người đọc; tác tử không cần đến nó
```

Các tài nguyên bổ sung (kịch bản lệnh, mẫu brief, `references/*.md`) được đặt trong cùng thư mục
và được tác tử đọc thông qua đường dẫn `skill://herdr-multiagent/<path>`. Ở đây không có các tệp phụ đó:
toàn bộ quy trình hướng dẫn nằm gọn trong một tệp duy nhất, và mẫu brief đã được mô tả bằng văn xuôi tại mục §4.

## An toàn

Các tác tử con chạy ở chế độ tự chủ (`omp --yolo`, `claude
--dangerously-skip-permissions`, `opencode --auto`) — không hiện lời nhắc xin phê duyệt. Điều đó
đồng nghĩa với toàn quyền truy cập hệ thống tệp và shell bên trong worktree của chúng. Kỹ năng này giới hạn
chúng thông qua bản giao việc brief ("không được rời khỏi worktree", "KHÔNG được push"), nhưng đó chỉ là
chỉ dẫn bằng lời chứ không phải cơ chế cô lập cứng. Việc hợp nhất (merge) vào nhánh main chỉ diễn ra khi có xác nhận
rõ ràng từ người dùng.

## Giấy phép

Miễn phí sử dụng.