orca-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: orca-workflow

🧭 Dispatch backend — chọn agent/model rẻ, chạy nhiều worker song song, cú pháp opencode/orchestration → xem orca-dispatch-reference (nguồn chân lý duy nhất, đừng nhân bản syntax ở đây).

🧭 Dispatch 后端——选择低成本的 agent/model，并行运行多个 worker；opencode/orchestration 语法参见 orca-dispatch-reference（唯一事实来源，请勿在此复制语法）。

WHAT

内容

Purpose và context

目的与上下文

Purpose: Propose → gate → dispatch → verify qua Orca. Agent pool 1:1 per engine (claude, agy, opencode, kiro, copilot). Claude: analyze. Others: execute. Kill opencode nếu chờ quá lâu.
Trigger (when to use):
"propose <feature>", "feature request", "implement <name>"
"chạy lint", "verify wiki"
"sync template", "upstream"
Non-goals: không xử lý SỰ CỐ (bug, lỗi runtime, regression →
```
orca-issue
```
); không nhân bản cú pháp dispatch backend (→
```
orca-dispatch-reference
```
); không mô tả lại hành vi
```
/propose
```
,
```
/plan
```
,
```
/query
```
(single source of truth ở skill con).

目的： 通过 Orca 执行 Propose → gate → dispatch → verify。Agent pool 按 engine 保持 1:1（claude、agy、opencode、kiro、copilot）。Claude：analyze。其他 agent：execute。如果 opencode 等待过久，则将其 kill。
触发条件（何时使用）：

propose <feature>

、

feature request

、

implement <name>

“运行 lint”、“验证 wiki”
“同步模板”、“同步上游”
非目标： 不处理事故（bug、runtime 错误、regression →
```
orca-issue
```
）；不复用 dispatch backend 语法（→
```
orca-dispatch-reference
```
）；不重述
```
/propose
```
、
```
/plan
```
、
```
/query
```
的行为（单一事实来源位于对应的子 skill 中）。

Mental model

心智模型

yêu cầu tính năng → R12 sweep → /query (wiki) → /propose (SPEC .md + .html render rẻ) → gate người duyệt → /plan (PLAN máy đọc) → task-create có dấu dự án → cổng HITL/AFK + kiểu việc → dispatch --inject nguyên văn → worker_done → [/qc-code] → verify-before-commit → output report

. Claude phân tích; agent khác thi hành; T-id (ledger bền) tách khỏi

task_xxxx

(Orca ephemeral, runtime-global).

功能请求 → R12 sweep → /query（wiki）→ /propose（SPEC .md + 低成本 .html 渲染）→ 人工审批 gate → /plan（机器可读 PLAN）→ 带项目标记的 task-create → HITL/AFK gate + 工作类型 → dispatch --inject 原文 brief → worker_done → [/qc-code] → verify-before-commit → output report

。Claude 负责分析；其他 agent 负责执行；T-id（持久 ledger）应与

task_xxxx

（Orca 临时、runtime-global 标识）分离。

Input và output contract

输入与输出契约

	Field	Required?	Ý nghĩa
In	mô tả tính năng ("propose <feature>", "implement <name>")	có	sự cố → rẽ sang `orca-issue`
In	`llmwiki/wiki/`	không	thiếu/rỗng → ghi "chưa có tiền lệ"
In	duyệt của user ở gate	có	trước khi `/plan` + dispatch
In	agent CLI sẵn có ( `opencode` / `agy` / `kiro` / `gh copilot` / `orca` )	không	cạn → Claude tự làm
Out	SPEC draft `.md` + `.html` (qua `/propose` )	có	thứ người duyệt
Out	`llmwiki/wiki/sources/draft/DDMMYY-<tên>-PLAN.md` (qua `/plan` )	có sau duyệt	thứ máy thi hành
Out	task Orca có dấu dự án + trạng thái T-id	có	`approved` / `rejected` / `dispatched` qua code-logger (fail-open)
Out	output report `llmwiki/wiki/draft/orca/DDMMYY-<ten>.md` + index + log	có (trừ khi 0 artifact)	"xong" = worker_done + verify-before-commit xanh + report cập nhật Status

	字段	必需？	含义
In	功能描述（ `propose <feature>` 、 `implement <name>` ）	是	遇到事故 → 转入 `orca-issue`
In	`llmwiki/wiki/`	否	缺失或为空 → 记录“尚无先例”
In	用户在 gate 的审批	是	必须先于 `/plan` + dispatch
In	可用的 agent CLI（ `opencode` / `agy` / `kiro` / `gh copilot` / `orca` ）	否	耗尽 → Claude 自行完成
Out	SPEC 草稿 `.md` + `.html` （通过 `/propose` ）	是	供用户审批
Out	`llmwiki/wiki/sources/draft/DDMMYY-<名称>-PLAN.md` （通过 `/plan` ）	审批后必需	供机器执行
Out	带项目标记的 Orca task + T-id 状态	是	通过 code-logger 记录 `approved` / `rejected` / `dispatched` （fail-open）
Out	输出报告 `llmwiki/wiki/draft/orca/DDMMYY-<名称>.md` + index + log	是（除非没有任何 artifact）	“完成” = worker_done + verify-before-commit 通过 + 报告已更新 Status

Rules và capabilities

规则与能力

RULE-01 (MUST): Caveman Mode: Chọn độ chi tiết theo người đọc file. File markdown mà MÁY hoặc AGENT đọc và thực thi (SKILL.md, policy.yaml, AGENT.md, bảng tham chiếu thuần) thì viết ngắn gọn được — caveman ở đây tiết kiệm token mà không hại gì. Nhưng tài liệu CON NGƯỜI đọc hoặc review thì BẮT BUỘC tắt caveman và viết đầy đủ — proposal, output-report, wiki content (concept/ADR/registry), README, CONTRIBUTING và runbook, cùng mọi trang HTML. Những file này phải là văn xuôi với câu hoàn chỉnh, dễ đọc; không bỏ liên từ, không viết tắt cụt, không nhồi bảng thay cho câu giải thích. Bài học 2026-06-27: user phản hồi "caveman đã nén quá mức khi viết tài liệu", rồi làm rõ — file máy đọc thì gọn được, file người đọc thì cần đầy đủ.
RULE-02 (MUST): Claude: analyze. Others: execute. Kill opencode nếu chờ quá lâu.
RULE-03 (MUST): Sổ vấn đề quy trình (problem-tree) — Dự án có
```
llmwiki/
```
thì sổ cây vấn đề nằm ở
```
llmwiki/html/problem-tree.html
```
(repo framework:
```
fdk-problem-tree.html
```
). Phiên nào phát hiện hoặc giải một vấn đề quy trình/framework → cập nhật node vào block JSON
```
#tree-data
```
(append-only; solved phải ghi
```
solvedBy
```
; scope theo 3 trụ harness/skills/llmwiki — xanh lá chỉ khi 3/3). Quên cũng không mất: hook SessionEnd (R17) tự ghi thẻ pending bằng code, lần sau distill.

RULE-04 (MUST): spec task PHẢI đóng dấu dự án:

orca orchestration task-create --spec "$(python3 harness/scripts/orca-reconcile.py --stamp '<spec>')"

(sổ task Orca là runtime-global).

RULE-05 (MUST): một agent được giao việc HITL chỉ còn cách đoán thay người dùng rồi im lặng — đó là con số 1/5, không phải model dốt — HITL không dispatch cho CLI headless.
RULE-06 (MUST):
```
--inject
```
bơm NGUYÊN VĂN brief của task từ PLAN kèm
```
## Global constraints
```
; KHÔNG tóm tắt lại.
RULE-07 (MUST): An toàn container / DB — chạy
```
docker inspect <container_name> --format '{{json .Mounts}}' | python3 -m json.tool
```
trước bất kỳ
```
--force-recreate
```
,
```
down
```
, recreate nào; khác volume → DỪNG, hỏi user (chi tiết ở Reference).
Capabilities: đọc wiki; tạo gate/task/dispatch qua orchestration runtime; chạy agent CLI headless hoặc terminal tương tác; ghi draft wiki + ledger T-id; (tuỳ chọn) bộ nhớ xuyên phiên qua HTTP; push đồng bộ skill lên repo nguồn.

RULE-01 (MUST)：Caveman Mode：根据文件读者选择详细程度。由机器或 AGENT 读取并执行的 Markdown 文件（SKILL.md、policy.yaml、AGENT.md、纯参考表）可以写得更简洁——这里的 caveman 能在不造成损害的情况下节省 token。但供人类阅读或评审的文档必须关闭 caveman 并完整撰写——包括 proposal、output-report、wiki 内容（concept/ADR/registry）、README、CONTRIBUTING、runbook，以及所有 HTML 页面。这些文件必须使用完整句子写成易读的连贯文字；不能省略连接词，不能过度缩写，也不能用表格代替解释。2026-06-27 的教训：用户反馈“caveman 在编写文档时压缩过度”，随后进一步澄清——机器读取的文件可以简洁，人类读取的文件必须完整。
RULE-02 (MUST)：Claude：analyze。其他 agent：execute。如果 opencode 等待过久，则将其 kill。
RULE-03 (MUST)：流程问题账本（problem-tree）——如果项目包含
```
llmwiki/
```
，问题树位于
```
llmwiki/html/problem-tree.html
```
（repo framework：
```
fdk-problem-tree.html
```
）。任何 session 发现或解决流程/framework 问题 → 更新
```
#tree-data
```
JSON block 中的节点（append-only；已解决节点必须写入
```
solvedBy
```
；按 harness/skills/llmwiki 三个轴限定 scope——只有达到 3/3 才标为绿色）。即使忘记也不会丢失：SessionEnd hook（R17）会自动通过 code 写入 pending 卡片，供下次 distill。
RULE-04 (MUST)：task spec 必须带有项目标记：
```
orca orchestration task-create --spec "$(python3 harness/scripts/orca-reconcile.py --stamp '<spec>')"
```
（Orca task ledger 是 runtime-global 的）。
RULE-05 (MUST)：被分配 HITL 工作的 agent 只能代替用户猜测，然后保持沉默——这正是 1/5 的原因，并非模型很笨——HITL 不得 dispatch 给 headless CLI。
RULE-06 (MUST)：
```
--inject
```
必须注入来自 PLAN 的 task brief 原文，并附带
```
## Global constraints
```
；不得重新概括。
RULE-07 (MUST)：容器/DB 安全——执行任何
```
--force-recreate
```
、
```
down
```
或 recreate 前，必须运行
```
docker inspect <container_name> --format '{{json .Mounts}}' | python3 -m json.tool
```
；如果 volume 不同 → 停止并询问用户（详见 Reference）。
能力：读取 wiki；通过 orchestration runtime 创建 gate/task/dispatch；以 headless 或交互式终端运行 agent CLI；写入 wiki 草稿 + T-id ledger；（可选）通过 HTTP 使用跨 session 记忆；将更新后的 skill push 到源 repo。

Failure boundaries

失败边界

Đầu vào là sự cố → rẽ sang
```
orca-issue
```
, không propose.
R12 sweep: subrepo TARGET sau remote → blocked tới khi
```
git pull --rebase
```
; offline → fail-open.
User từ chối ở gate → cancelled, T-id
```
state=rejected
```
.
Task HITL → không dispatch, nhãn
```
ready-for-human
```
(chờ người).
CLI headless im lặng quá ~60–90s / không tạo file / thiếu
```
diagram-box
```
→ kill, Claude tiếp quản (fallback).
Container volume khác compose → blocked, hỏi user.

task-update --status done

→

ok:false

lặng lẽ (status hợp lệ:

ready

in_progress

completed

failed

输入是事故 → 转入
```
orca-issue
```
，不要 propose。
R12 sweep：TARGET subrepo 落后于 remote → 阻塞，直到执行
```
git pull --rebase
```
；offline → fail-open。
用户在 gate 拒绝 → cancelled，T-id
```
state=rejected
```
。
HITL task → 不得 dispatch，标记为
```
ready-for-human
```
（等待人员处理）。
Headless CLI 静默超过约 60–90 秒、未创建文件或缺少
```
diagram-box
```
→ kill，由 Claude 接管（fallback）。
Container volume 与 compose 不一致 → blocked，询问用户。

task-update --status done

→ 静默返回

ok:false

（有效状态：

ready

in_progress

completed

failed

）。

HOW

执行方式

Main workflow

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	workspace	Bước 0 — R12 (B) pre-work sweep `pull-gate-sweep.sh` một lần	base tươi	TARGET sau remote → pull --rebase rồi lặp
W02	judgment	tính năng	Bước 1 — GỌI `/query` tổng hợp context wiki	điều đã biết + lỗ hổng	rỗng → "chưa có tiền lệ"
W03	judgment	context	Bước 2 — GỌI `/propose` (SPEC `.md` ); `.html` render dispatch sang CLI rẻ có watchdog	SPEC `.md` + `.html`	CLI im lặng → B03
W04	effect	SPEC	Bước 3 — `orca orchestration gate-create` , chờ user; ghi T-id approved/rejected	duyệt	từ chối → cancelled
W05	judgment	SPEC đã duyệt	Bước 4 — GỌI `/plan` → PLAN; `task-create` mỗi `### Task` với spec đóng dấu	task `task_xxxx`	R7 PLAN chặn → sửa PLAN
W06	judgment	task	Bước 4b — Cổng 1 HITL/AFK, Cổng 2 kiểu việc → archetype, rồi mới bảng chi phí	task AFK có kiểu + CLI	HITL → B02
W07	effect	task AFK	Bước 5 — `orca orchestration dispatch --task <id> --to <agent> --inject` (brief nguyên văn, dòng đầu khai kiểu việc); T-id dispatched	worker chạy	—
W08	deterministic	dispatch	Bước 6 — `orca orchestration check --wait --types worker_done --timeout-ms 300000`	worker_done	timeout/im lặng → B03
W09	deterministic	diff	Bước 7 — `verify-before-commit` (gồm `qc-regression.py --run` )	commit sạch	đỏ → sửa
W10	effect	kết quả	Output report + cập nhật Status agent + sync push skill (mục Delivery)	draft + index + log	0 artifact → skip

Chi tiết từng bước (nguồn chân lý cho W01–W09):

R12 (B) — pre-work sweep cả workspace (MỘT LẦN, trước khi làm / fan-out đa-agent): orchestrator chạy
```
harness/poc-vendor-neutral/bin/pull-gate-sweep.sh
```
— quét MỌI subrepo (từ
```
.harness-workspace.yaml
```
, thiếu → auto-discover harnessed), fetch song song; subrepo TARGET sau remote → DỪNG,
```
git pull --rebase
```
trong repo đó rồi mới dispatch (cả đàn agent chung base tươi); subrepo
```
watch
```
chỉ cảnh báo. 1 repo → sweep tự rút về
```
pull-gate.sh
```
. Offline → fail-open. KHÔNG chặn từng-edit (cố tình bỏ per-edit PreToolUse). R12 (C) gate2 per-repo: cài mọi subrepo bằng
```
install-harness.sh --all-subrepos
```
; check tay
```
pull-gate.sh gate2
```
.
query: GỌI skill
```
query
```
(Skill tool →
```
query
```
, hoặc
```
/query
```
) để synthesis context từ
```
wiki/
```
về tính năng — KHÔNG đọc tay rời rạc, dùng đúng wiki-loop
```
query
```
(tổng hợp
```
[[wikilinks]]
```
, trả về điều đã biết + lỗ hổng). Project chưa có
```
wiki/
```
(hoặc query trả rỗng) → ghi nhận "chưa có tiền lệ" rồi sang bước 2.
propose — KHÔNG mô tả lại; GỌI skill
propose
(Skill tool →
```
/propose
```
, đúng pattern bước 1 gọi
```
query
```
). Mọi yêu cầu R7 (cặp
```
.md
```
+
```
.html
```
,
```
## Plan
```
,
```
## Agent Task Assignment
```
, glass-style
```
docs-site-macos
```
, prose chi tiết) sống trong skill con — sửa hành vi propose chỉ sửa
```
llmwiki/skills/dev-loop/propose.md
```
, KHÔNG sửa ở đây (single source of truth, xem [[ADR-003-skill-as-single-source-of-truth]]).
- Tách Claude-nghĩ / CLI-rẻ-render: Claude (qua
```
/propose
```
  ) chỉ sản xuất SUBSTANCE =
```
.md
```
  render-complete (Plan + prose +
```
## Render brief
```
  = bước diagram dạng data + đoạn prose mỗi task). Phần
```
.html
```
  là RENDER cơ học của
```
## Render brief
```
  → dispatch sang một CLI rẻ theo bảng chi phí (OpenCode
```
big-pickle
```
  →
```
agy
```
  →
```
kiro
```
  , $0). Render free nên dùng Full
```
docs-site-macos
```
  richness, KHÔNG cắt bớt — token Claude chỉ tốn cho substance, không phình theo độ giàu HTML.
- Watchdog + R7 gate (bài học 250626 — headless giao ~1/5): chờ ~60–90s; im lặng / không tạo file / thiếu
```
diagram-box
```
  → kill, Claude render fallback. Thử CLI rẻ theo thứ tự sẵn-có (probe
```
--version
```
  ); cạn → Claude. R7 vẫn chặn lúc write+commit nên chất lượng được gác bất kể ai render.
gate:
```
orca orchestration gate-create --question "Duyệt proposal này?"
```
→ chờ user (gửi kèm preview URL của html)
- Trụ 3 lifecycle (best-effort, fail-open): user DUYỆT →
```
python3 harness/scripts/code-logger.py --task set <T-id> state=approved note="gate"
```
  (
```
<T-id>
```
  = field
```
task:
```
  trong frontmatter draft do
```
/propose
```
  mint; trống thì bỏ qua). User TỪ CHỐI →
```
--task set <T-id> state=rejected
```
  . Lệnh fail-open, không chặn flow.
Sau duyệt — GỌI skill
plan
(Skill tool →
/plan
) TRƯỚC KHI phân rã.
```
/propose
```
sinh SPEC (thứ NGƯỜI đọc để duyệt);
```
/plan
```
mở rộng nó thành
```
llmwiki/wiki/sources/draft/DDMMYY-<tên>-PLAN.md
```
— thứ MÁY đọc để thi hành: mỗi
```
### Task
```
có
```
**Files:**
```
(đường dẫn chính xác),
```
**Interfaces:**
```
(Consumes/Produces — chữ ký cho task hàng xóm), và các bước 2–5 phút kiểu TDD có code thật + lệnh + output mong đợi. R7 nhánh PLAN chặn nếu thiếu. Rồi mới
```
orca orchestration task-create
```
cho mỗi
```
### Task
```
— spec phải ĐÓNG DẤU dự án:
```
orca orchestration task-create --spec "$(python3 harness/scripts/orca-reconcile.py --stamp '<spec>')"
```
. Sổ task của Orca là runtime-global (guide Orca nói thẳng); đo 2026-07-20: 18 terminal của NHIỀU dự án cùng ghi một sổ, nên
```
task-list
```
ở repo A trả về cả việc của repo B — và một orchestrator sẽ claim nhầm task của dự án khác, phá đúng mục tiêu tách-bias-tầng-vật-lý. Orca không có trường dự án (
```
task-create
```
không có tag,
```
task-list
```
không có bộ lọc), nên dấu này là cách duy nhất để quy thuộc chính xác — và nó còn đúng cả sau khi terminal tạo task đã chết (thực đo: 0/17 terminal cũ còn sống). Đối soát:
```
orca-reconcile.py [--scope current|all]
```
.
- Vì sao bắt buộc, không phải "nên": agent CLI rẻ chạy headless không thừa hưởng context nào của phiên này và không hỏi lại được — nó chỉ có đúng thứ ta bơm vào; gặp chỗ mơ hồ nó đoán rồi im lặng. Brief mỏng chính là nguyên nhân của thực đo "giao hàng ~1/5" (bài học 250626), không phải do model dốt.
- PLAN không cần
  .html
  — HTML gắn với SPEC (thứ người xem lúc duyệt), do
```
/propose
```
  sinh. Vẽ diagram cho agent đọc là đốt token vô ích. 4b. GIAO ĐÚNG LOẠI VIỆC — cổng chạy TRƯỚC khi chọn CLI. Bảng chi phí bên dưới chỉ trả lời "model nào rẻ nhất". Nó chưa bao giờ hỏi "việc này làm được không cần người không" — và đó là mảnh còn thiếu của con số ~1/5. Hai cổng, đúng thứ tự:
- Cổng 1 — HITL/AFK. Task cần một người sống trả lời (quyết định thiết kế, đánh đổi, thứ chỉ user biết, truy cập ngoài, kiểm thủ công) là HITL → nhãn
```
ready-for-human
```
  trong ledger, KHÔNG dispatch cho CLI headless. Chỉ task AFK (
```
ready-for-agent
```
  ) mới đi tiếp. Luật cứng: một agent được giao việc HITL chỉ còn cách đoán thay người dùng rồi im lặng — đó là con số 1/5, không phải model dốt.
- Cổng 2 — kiểu việc → archetype. Gắn kiểu cho task:
```
research
```
  (lôi ra fact) ·
```
prototype
```
  (bản thô để phản ứng) ·
```
grilling
```
  (hỏi từng câu) ·
```
build
```
  (thi hành theo brief) ·
```
sweep
```
  (dọn cơ học). Map sang archetype (ADR-015) → persona preamble. Rồi mới tới bảng chi phí chọn CLI — nó tụt xuống bước cuối, không phải bước đầu.
dispatch:
```
orca orchestration dispatch --task <id> --to <agent> --inject
```
- --inject
  bơm NGUYÊN VĂN brief của task đó từ PLAN (Files + Interfaces + Steps) kèm
  ## Global constraints
  của PLAN. KHÔNG tóm tắt lại — tóm tắt chính là chỗ context rụng, và cái rụng luôn là cái agent cần.
- Dòng ĐẦU của brief khai kiểu việc: một câu nói thẳng phiên này là phiên gì — "anh đang giải một QUYẾT ĐỊNH, không phải đi build" / "anh đang dọn cơ học, KHÔNG thêm feature". Kiểu việc quyết định hình dạng của phiên, không chỉ chọn model; một agent biết mình đang làm gì hành xử khác hẳn agent nhận một cục mô tả.
- Trụ 3 lifecycle (best-effort): khi giao việc →
```
python3 harness/scripts/code-logger.py --task set <T-id> state=dispatched note="<agent>"
```
  . Đây là
```
T-id
```
  bền (audit trail bất biến), độc lập với
```
task_xxxx
```
  ephemeral của orca orchestration. Fail-open.
- Persona theo archetype (Boris Cherny — 5 vai vòng đời): muốn dispatch theo một posture cụ thể thì gọi bằng từ khoá —
```
/proto
```
```
/build
```
```
/sweep
```
```
/grow
```
```
/maintain
```
  . Cơ chế:
```
python3 harness/scripts/archetype.py --get /<kw>
```
  → in (a) CLI gợi ý cho archetype đó (Prototyper→opencode rẻ · Builder/Grower/Maintainer→Claude · Sweeper→opencode), và (b) PREAMBLE persona (
```
llmwiki/personas/<archetype>.md
```
  ) — inject preamble đó vào
  <task>
  trước khi dispatch để agy/opencode/kiro vào đúng vai (vd Sweeper bị cấm thêm feature). CLI nào hợp archetype nào là adapter
```
verified:false
```
  (
```
harness/archetypes.config.yaml
```
  ). Xem ADR-015.
Chờ:
```
orca orchestration check --wait --types worker_done --timeout-ms 300000
```
6b. (Tùy chọn) QC senior trước commit — muốn một cặp mắt senior soi diff trước khi chốt thì gọi
```
/qc-code
```
(Skill tool →
```
qc-code
```
): review 4 mục (security/performance/naming/logic) chấm điểm + verdict, và sinh test tái hiện
```
qc-*
```
cho mỗi bug logic. Verdict CẦN SỬA → sửa trước khi commit. Tùy chọn, không bắt buộc — verdict LLM là advisory (người quyết), thứ gác cứng là test
```
qc-*
```
chạy ở bước 7.
Kiểm tra:
```
verify-before-commit
```
tự động chạy trước mỗi commit (gồm bước 3b:
```
qc-regression.py --run
```
chạy test
```
qc-*
```
tất định — bug đã tái hiện không âm thầm quay lại).

步骤	类型	输入	操作	输出/退出条件	失败/下一步
W01	确定性	workspace	步骤 0——运行一次 R12 (B) pre-work sweep `pull-gate-sweep.sh`	获得最新 base	TARGET 落后于 remote → pull --rebase 后重试
W02	判断	功能	步骤 1——调用 `/query` 汇总 wiki context	已知信息 + 缺口	为空 → “尚无先例”
W03	判断	context	步骤 2——调用 `/propose` （SPEC `.md` ）；将 `.html` 渲染 dispatch 给带 watchdog 的低成本 CLI	SPEC `.md` + `.html`	CLI 静默 → B03
W04	执行	SPEC	步骤 3—— `orca orchestration gate-create` ，等待用户；记录 T-id approved/rejected	审批结果	拒绝 → cancelled
W05	判断	已审批的 SPEC	步骤 4——调用 `/plan` → PLAN；为每个 `### Task` 创建带标记的 `task-create`	task `task_xxxx`	R7 阻止 PLAN → 修复 PLAN
W06	判断	task	步骤 4b——Gate 1 HITL/AFK、Gate 2 工作类型 → archetype，最后才查询成本表	带类型和 CLI 的 AFK task	HITL → B02
W07	执行	AFK task	步骤 5—— `orca orchestration dispatch --task <id> --to <agent> --inject` （brief 使用原文，首行声明工作类型）；T-id dispatched	worker 运行	—
W08	确定性	dispatch	步骤 6—— `orca orchestration check --wait --types worker_done --timeout-ms 300000`	worker_done	timeout/静默 → B03
W09	确定性	diff	步骤 7—— `verify-before-commit` （包含 `qc-regression.py --run` ）	干净的 commit	失败 → 修复
W10	执行	结果	输出报告 + 更新 agent Status + sync push skill（见 Delivery）	草稿 + index + log	0 artifact → skip

以下为各步骤详情（W01–W09 的事实来源）：

R12 (B)——pre-work sweep，覆盖整个 workspace（仅执行一次，在进行 / 或多 agent fan-out 之前）：orchestrator 运行
```
harness/poc-vendor-neutral/bin/pull-gate-sweep.sh
```
——扫描所有 subrepo（来源为
```
.harness-workspace.yaml
```
；缺失时自动发现已接入 harness 的 repo），并行 fetch；如果 TARGET subrepo 落后于 remote → 停止，在该 repo 中执行
```
git pull --rebase
```
，然后才能 dispatch（确保整组 agent 使用相同的最新 base）；标记为 watch 的 subrepo 只发出警告。只有 1 个 repo 时，sweep 自动退化为
```
pull-gate.sh
```
。Offline → fail-open。不阻止逐次编辑（有意移除 per-edit PreToolUse）。R12 (C) per-repo gate2：使用
```
install-harness.sh --all-subrepos
```
安装所有 subrepo；手动检查
```
pull-gate.sh gate2
```
。
query：调用 skill
```
query
```
（Skill tool →
```
query
```
，或
```
/query
```
），从
```
wiki/
```
综合与该功能有关的 context——不要零散地手动读取，应使用正确的 wiki-loop
```
query
```
（汇总
```
[[wikilinks]]
```
，返回已知信息 + 缺口）。如果项目还没有
```
wiki/
```
（或 query 返回空）→ 记录“尚无先例”，然后进入步骤 2。
propose——不要再次描述其行为；调用 skill
propose
（Skill tool →
```
/propose
```
，模式与步骤 1 调用
```
query
```
相同）。所有 R7 要求（
```
.md
```
+
```
.html
```
文件对、
```
## Plan
```
、
```
## Agent Task Assignment
```
、glass-style
```
docs-site-macos
```
、详细 prose）均定义在子 skill 中——只能通过修改
```
llmwiki/skills/dev-loop/propose.md
```
调整 propose 行为，不得在此修改（单一事实来源，参见 [[ADR-003-skill-as-single-source-of-truth]]）。
- 分离 Claude 思考与低成本 CLI 渲染： Claude（通过
```
/propose
```
  ）只生成实质内容 = 完整可渲染的
```
.md
```
  （Plan + prose +
```
## Render brief
```
  = data 形式的 diagram 步骤 + 每个 task 的 prose）。
```
.html
```
  是
```
## Render brief
```
  的机械渲染 → 按成本表 dispatch 给低成本 CLI（OpenCode
```
big-pickle
```
  →
```
agy
```
  →
```
kiro
```
  ，$0）。渲染免费，因此应使用 Full
  docs-site-macos
  richness，不得删减——Claude token 只消耗在实质内容上，不会因 HTML 丰富度而膨胀。
- Watchdog + R7 gate（250626 的教训——headless 交付率约 1/5）： 等待约 60–90 秒；静默、未创建文件或缺少
```
diagram-box
```
  → kill，由 Claude 渲染 fallback。按可用顺序尝试低成本 CLI（探测
```
--version
```
  ）；耗尽 → Claude。R7 仍会在 write+commit 阶段阻止不合格内容，因此无论由谁渲染，质量都有硬性保障。
gate：
```
orca orchestration gate-create --question "Duyệt proposal này?"
```
→ 等待用户（同时发送 HTML preview URL）。
- 第三轴 lifecycle（best-effort、fail-open）： 用户批准 →
```
python3 harness/scripts/code-logger.py --task set <T-id> state=approved note="gate"
```
  （
```
<T-id>
```
  =
```
/propose
```
  生成的草稿 frontmatter 中的
```
task:
```
  字段；为空则跳过）。用户拒绝 →
```
--task set <T-id> state=rejected
```
  。命令采用 fail-open，不会阻塞流程。
审批后——先调用 skill
plan
（Skill tool →
/plan
），然后再拆分任务。
```
/propose
```
生成 SPEC（供用户阅读和审批）；
```
/plan
```
将其扩展为
```
llmwiki/wiki/sources/draft/DDMMYY-<名称>-PLAN.md
```
——这是供机器执行的内容：每个
```
### Task
```
都包含
```
**Files:**
```
（准确路径）、
```
**Interfaces:**
```
（Consumes/Produces——供相邻 task 使用的签名），以及 2–5 分钟的 TDD 步骤，包含真实代码、命令和预期输出。缺少这些内容时，R7 的 PLAN 分支会阻止提交。然后才为每个
```
### Task
```
执行
```
orca orchestration task-create
```
——spec 必须带有项目标记：
```
orca orchestration task-create --spec "$(python3 harness/scripts/orca-reconcile.py --stamp '<spec>')"
```
。 Orca 的 task ledger 是 runtime-global 的（Orca guide 已明确说明）；2026-07-20 的实测显示：来自多个项目的 18 个 terminal 会写入同一个 ledger，因此 repo A 中的
```
task-list
```
也会返回 repo B 的任务——orchestrator 可能错误 claim 其他项目的 task，破坏物理隔离的核心目标。Orca 没有项目字段（
```
task-create
```
没有 tag，
```
task-list
```
没有过滤器），因此该标记是准确归属项目的唯一方式——即使创建 task 的 terminal 已经死亡，该标记仍然有效（实测：旧 terminal 的存活率为 0/17）。对账方式：
```
orca-reconcile.py [--scope current|all]
```
。
- 为什么这是强制要求，而不只是“应该这样做”： 低成本 headless agent CLI 不会继承当前 session 的任何 context，也无法再次询问——它只能获得注入的内容；遇到模糊之处时，它会猜测然后沉默。Brief 过于简略正是实测“交付率约 1/5”的根本原因，并非模型很笨。
- PLAN 不需要
  .html
  ——HTML 与 SPEC 配套（供用户审批时查看），由
```
/propose
```
  生成。为 agent 阅读而绘制 diagram 只是浪费 token。 4b. 分派正确的工作类型——必须在选择 CLI 之前运行 gate。 下方的成本表只回答“哪个 model 最便宜”，却从未询问“这项工作是否能在无人参与的情况下完成”——而这正是约 1/5 交付率中缺失的一环。两个 gate，顺序固定：
- Gate 1——HITL/AFK。 如果 task 需要一个真实人员回答（设计决策、取舍、只有用户知道的信息、外部访问、手动检查），则属于 HITL → 在 ledger 中标记
```
ready-for-human
```
  ，不得 dispatch 给 headless CLI。只有 AFK（
```
ready-for-agent
```
  ）task 才能继续。硬性规则：被分配 HITL 工作的 agent 只能代替用户猜测，然后保持沉默——这正是 1/5 的原因，并非模型很笨。
- Gate 2——工作类型 → archetype。 为 task 标记类型：
```
research
```
  （提取事实）·
```
prototype
```
  （制作原型以获得反馈）·
```
grilling
```
  （逐项提问）·
```
build
```
  （按照 brief 执行）·
```
sweep
```
  （机械清理）。映射到 archetype（ADR-015）→ persona preamble。之后才查询成本表选择 CLI——成本表是最后一步，而不是第一步。
dispatch：
```
orca orchestration dispatch --task <id> --to <agent> --inject
```
- --inject
  注入 PLAN 中该 task 的 brief 原文（Files + Interfaces + Steps）以及 PLAN 的
  ## Global constraints
  。不得重新概括——概括正是 context 丢失的位置，而丢失的始终是 agent 最需要的内容。
- brief 首行声明工作类型： 用一句话直接说明当前 session 属于什么性质——“你正在解决一个决策，而不是执行 build”/“你正在做机械清理，不添加 feature”。工作类型决定的是 session 的形态，不只是 model 选择；知道自身任务的 agent 与收到一段描述的 agent 行为会截然不同。
- 第三轴 lifecycle（best-effort）： 分派任务时 →
```
python3 harness/scripts/code-logger.py --task set <T-id> state=dispatched note="<agent>"
```
  。这是持久 T-id（不可变 audit trail），独立于 Orca orchestration 的临时
```
task_xxxx
```
  。采用 fail-open。
- 按 archetype 选择 persona（Boris Cherny——五种人生角色）： 如果希望按照具体 posture 分派任务，应使用关键词——
```
/proto
```
```
/build
```
```
/sweep
```
```
/grow
```
```
/maintain
```
  。机制：
```
python3 harness/scripts/archetype.py --get /<kw>
```
  → 输出（a）该 archetype 建议的 CLI（Prototyper→低成本 opencode · Builder/Grower/Maintainer→Claude · Sweeper→opencode），以及（b）PREAMBLE persona（
```
llmwiki/personas/<archetype>.md
```
  ）——dispatch 前将该 preamble 注入
```
<task>
```
  ，确保 agy/opencode/kiro 进入正确角色（例如 Sweeper 禁止添加 feature）。archetype 与 CLI 的适配关系标记为
```
verified:false
```
  （
```
harness/archetypes.config.yaml
```
  ）。参见 ADR-015。
等待：
```
orca orchestration check --wait --types worker_done --timeout-ms 300000
```
6b. （可选）commit 前进行 senior QC——如果希望在最终提交前让一双 senior 眼睛检查 diff，可调用
```
/qc-code
```
（Skill tool →
```
qc-code
```
）：评审 4 个方面（security/performance/naming/logic），给出评分 + verdict，并为每个 logic bug 生成复现测试
```
qc-*
```
。Verdict 为“需要修复”→ commit 前先修复。可选，并非强制——LLM verdict 仅作 advisory（由人决定），真正的硬性 gate 是步骤 7 运行的
```
qc-*
```
测试。
检查：
```
verify-before-commit
```
会在每次 commit 前自动运行（包含步骤 3b：
```
qc-regression.py --run
```
，确定性运行
```
qc-*
```
测试，防止已复现的 bug 悄悄回归）。

Branches

分支

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	conditional_required	đầu vào là SỰ CỐ (bug, lỗi runtime, regression, "hôm qua còn chạy")	GỌI skill `orca-issue` thay vì propose	sự cố nặng cần fan-out → orca-issue escalate về W07, giữ 2 chốt cứng của nó	kết thúc (hoặc W07 khi escalate)
B02	conditional_required	task cần người sống trả lời (HITL)	nhãn `ready-for-human` trong ledger, KHÔNG dispatch CLI headless	—	chờ người, rồi W06
B03	recovery	CLI headless im lặng ~60–90s / không tạo file / thiếu `diagram-box`	kill + Claude tự tiếp quản theo spec; thử CLI rẻ kế tiếp theo thứ tự sẵn-có (probe `--version` )	cạn CLI → Claude	bước đang chạy (W03/W08)
B04	user_optional	muốn soi diff trước khi chốt	Bước 6b — `/qc-code` (verdict advisory + test `qc-*` )	verdict CẦN SỬA → sửa trước commit	W09
B05	user_optional	muốn dispatch theo posture ( `/proto` `/build` `/sweep` `/grow` `/maintain` )	`python3 harness/scripts/archetype.py --get /<kw>` → CLI gợi ý + inject PREAMBLE persona vào `<task>`	—	W07
B06	conditional_required	sắp đụng docker ( `--force-recreate` , `down` , recreate)	`docker inspect` mounts, so với compose; khác → DỪNG hỏi user	không backup + xác nhận → không đổi volume	bước đang chạy
B07	capability_optional	có `AGENTMEMORY_TOKEN`	search đầu session / remember sau decision + cuối session (Reference — AgentMemory)	không có → bỏ qua	W02 / W10

Chi tiết nhánh sự cố (nguyên văn):

ID	类型	Guard	行为	Skip / failure	汇合点
B01	条件必需	输入是事故（bug、runtime 错误、regression、“昨天还能运行”）	调用 skill `orca-issue` ，不要 propose	严重事故需要 fan-out → orca-issue 升级到 W07，同时保留其两个硬性 gate	结束（或升级时进入 W07）
B02	条件必需	task 需要真实人员回答（HITL）	在 ledger 中标记 `ready-for-human` ，不得 dispatch 给 headless CLI	—	等待人员，然后进入 W06
B03	恢复	Headless CLI 静默约 60–90 秒、未创建文件或缺少 `diagram-box`	kill + Claude 按 spec 接管；按可用顺序尝试下一个低成本 CLI（探测 `--version` ）	CLI 耗尽 → Claude	当前步骤（W03/W08）
B04	用户可选	希望在最终提交前检查 diff	步骤 6b—— `/qc-code` （advisory verdict + `qc-*` 测试）	Verdict 为“需要修复”→ commit 前修复	W09
B05	用户可选	希望按 posture 分派任务（ `/proto` `/build` `/sweep` `/grow` `/maintain` ）	`python3 harness/scripts/archetype.py --get /<kw>` → CLI 建议 + 将 PREAMBLE persona 注入 `<task>`	—	W07
B06	条件必需	即将操作 docker（ `--force-recreate` 、 `down` 、recreate）	通过 `docker inspect` 检查 mounts，并与 compose 对比；不一致 → 停止并询问用户	未备份且未获确认 → 不更改 volume	当前步骤
B07	能力可选	存在 `AGENTMEMORY_TOKEN`	在 session 开始时 search / 在 decision 后和 session 结束时 remember（参见 AgentMemory）	不存在 → 跳过	W02 / W10

事故分支详情：

Rẽ nhánh: SỰ CỐ ≠ tính năng

分支：事故 ≠ 功能

Đầu vào là sự cố (bug, lỗi runtime, regression, "hôm qua còn chạy") → GỌI skill
orca-issue
thay vì propose: vòng riêng triage → repro-first gate (chưa tái hiện chưa được sửa) → fix red→green → distill kép. Sự cố nặng cần fan-out thì orca-issue escalate ngược về đây để dispatch, nhưng 2 chốt cứng của nó vẫn giữ.

输入是事故（bug、runtime 错误、regression、“昨天还能运行”）→ 调用 skill
orca-issue
，不要 propose：使用独立的 triage → repro-first gate（未复现前不得修复）→ fix red→green → 双重 distill。如果严重事故需要 fan-out，orca-issue 会反向升级到这里执行 dispatch，但其两个硬性 gate 仍然保留。

Validation và stopping

验证与停止条件

Cổng người: gate W04 (duyệt SPEC) và Cổng 1 HITL ở W06. Cổng máy: R7 chặn SPEC/PLAN thiếu mục lúc write+commit;

verify-before-commit

qc-regression.py --run

trước mỗi commit. Watchdog CLI ~60–90s (B03);

check --wait

timeout 300000 ms. Đối soát task theo dự án:

orca-reconcile.py [--scope current|all]

人工 gate：W04（审批 SPEC）以及 W06 的 Gate 1 HITL。机器 gate：R7 在 write+commit 阶段阻止缺少必要章节的 SPEC/PLAN；每次 commit 前执行

verify-before-commit

qc-regression.py --run

。CLI watchdog：约 60–90 秒（B03）；

check --wait

timeout：300000 ms。按项目对账 task：

orca-reconcile.py [--scope current|all]

。

Examples

示例

Positive: "propose export CSV cho báo cáo" → sweep sạch →
```
/query
```
ra 2 trang liên quan →
```
/propose
```
sinh SPEC,
```
.html
```
render bằng
```
opencode run -m opencode/big-pickle
```
→ user duyệt gate →
```
/plan
```
sinh
```
DDMMYY-export-csv-PLAN.md
```
3 task → task-create có stamp → 2 task AFK
```
build
```
dispatch
```
--inject
```
, 1 task HITL ("chọn định dạng ngày") gắn
```
ready-for-human
```
→ worker_done → verify-before-commit xanh → output report.
Boundary/failure: "hôm qua login còn chạy, nay 500" → B01: không propose, gọi
```
orca-issue
```
(repro-first).
Boundary:
```
opencode run
```
render
```
.html
```
im lặng 90s, không tạo file → B03: kill, Claude render fallback; R7 vẫn gác chất lượng lúc write.

正向： “为报告提议 CSV 导出” → sweep 确认 base 最新 →
```
/query
```
返回 2 个相关页面 →
```
/propose
```
生成 SPEC，使用
```
opencode run -m opencode/big-pickle
```
渲染
```
.html
```
→ 用户通过 gate 审批 →
```
/plan
```
生成包含 3 个 task 的
```
DDMMYY-export-csv-PLAN.md
```
→ task-create 带有项目标记 → 2 个 AFK
```
build
```
task 使用
```
--inject
```
分派，1 个 HITL task（“选择日期格式”）标记为
```
ready-for-human
```
→ worker_done → verify-before-commit 通过 → 输出报告。
边界/失败： “昨天登录还能运行，现在出现 500” → B01：不要 propose，调用
```
orca-issue
```
（repro-first）。
边界：
```
opencode run
```
渲染
```
.html
```
时静默 90 秒且未创建文件 → B03：kill，由 Claude 渲染 fallback；R7 仍会在 write 阶段保障质量。

Reference — Gotchas orchestration CLI (bài học 230626)

参考——Orchestration CLI 易错点（230626 的教训）

2 id từ
task-create --json
: response có envelope
```
id
```
(uuid) VÀ
```
result.task.id
```
(
```
task_xxxx
```
). Mọi lệnh sau (
```
gate-create --task
```
,
```
dispatch --task
```
,
```
task-update --id
```
) PHẢI dùng
```
result.task.id
```
, KHÔNG dùng envelope id. Dùng nhầm: gate vẫn tạo/resolve được nhưng trỏ task ma → task thật kẹt ở
```
ready
```
.
Status hợp lệ của
task-update --status
:
```
ready
```
|
```
in_progress
```
|
```
completed
```
|
```
failed
```
. KHÔNG có
```
done
```
— truyền
```
done
```
trả
```
ok:false
```
lặng lẽ (không báo lỗi rõ).
Lấy id thật chắc ăn:
```
orca orchestration task-list --json
```
rồi match theo
```
spec
```
.

从
task-create --json
获取两个 id： response 同时包含 envelope
```
id
```
（uuid）和
```
result.task.id
```
（
```
task_xxxx
```
）。后续所有命令（
```
gate-create --task
```
、
```
dispatch --task
```
、
```
task-update --id
```
）必须使用
```
result.task.id
```
，不能使用 envelope id。使用错误 id 时，gate 仍可能创建或解析成功，但会指向一个不存在的 task，真实 task 将停留在
```
ready
```
状态。
task-update --status
的有效状态：
```
ready
```
|
```
in_progress
```
|
```
completed
```
|
```
failed
```
。不存在
```
done
```
——传入
```
done
```
会静默返回
```
ok:false
```
（不会给出清晰错误）。
可靠获取真实 id：
```
orca orchestration task-list --json
```
，然后按
```
spec
```
匹配。

Reference — An toàn container / DB (BẮT BUỘC trước khi đụng docker)

参考——容器/DB 安全（操作 docker 前强制执行）

Trước khi đụng container (docker compose / docker run)

操作容器前（docker compose / docker run）

bash

undefined

bash

undefined

BẮT BUỘC chạy trước bất kỳ --force-recreate, down, recreate nào:

docker inspect <container_name> --format '{{json .Mounts}}' | python3 -m json.tool


So sánh `Source` path với volume trong compose file sắp dùng. Nếu khác → DỪNG, hỏi user.

**Production DB của Cozyroom:** `/mnt/c/Users/olive/orca/workspaces/home-spotify/m/data/metadata.db`
Không bao giờ đổi volume mount mà không backup + xác nhận user.

> Bài học 2026-05-29: recreate container với compose sai path → mất toàn bộ DB người dùng.

docker inspect <container_name> --format '{{json .Mounts}}' | python3 -m json.tool


将 `Source` 路径与即将使用的 compose 文件中的 volume 进行比较。如果不一致 → 停止并询问用户。

**Cozyroom 的 Production DB：** `/mnt/c/Users/olive/orca/workspaces/home-spotify/m/data/metadata.db`
未经备份和用户确认，绝不能更改 volume mount。

> 2026-05-29 的教训：使用错误的 compose 路径重建容器 → 整个用户 DB 丢失。

Reference — Dispatch nhanh

参考——快速 Dispatch

⚠️ CLI agent headless KHÔNG đáng tin (bài học 250626 — orca-eval):
opencode run
/
agy -p
/
kiro run
chạy nền từ Claude Code thường không giao hàng (process thoát/treo, không tạo file — thực đo 1/5 task thành công). Quy tắc: đặt watchdog (~60–90s), nếu im lặng/không có file → kill + Claude tự tiếp quản theo spec (đừng chờ vô ích). Dùng OpenCode cho task boilerplate ĐỘC LẬP, đã verify được; task có dependency/nuance → Claude làm. Muốn dispatch THẬT cho agent → ưu tiên
orca terminal
interactive thay vì
-p
/
run
.

bash

undefined

⚠️ Headless CLI agent 不可靠（250626 的教训——orca-eval）： 从 Claude Code 后台运行
opencode run
/
agy -p
/
kiro run
通常无法交付（进程退出或挂起，未创建文件——实测仅 1/5 task 成功）。规则：设置 watchdog（约 60–90 秒），如果静默或没有文件 → kill + Claude 按 spec 自行接管（不要无效等待）。OpenCode 适用于已经验证为独立、无依赖的 boilerplate task；有 dependency 或 nuance 的 task → 由 Claude 完成。需要真正向 agent dispatch 时，优先使用
orca terminal
交互模式，而不是
-p
/
run
。

bash

undefined

OpenCode non-interactive (DEFAULT — dùng big-pickle miễn phí):

⚠ KHÔNG dùng --dangerously-skip-permissions khi dispatch từ Claude Code — auto-mode classifier sẽ DENY (bài học 120626)

opencode run -m opencode/big-pickle --dir "<project>" "<task>"

Antigravity non-interactive:

agy -p "<task>"

Kiro non-interactive:

kiro run --dir "<project>" "<task>"

GitHub Copilot Coding Agent (async — via GitHub issue):

gh issue create --title "<task>" --body "<task details>" --assignee "@me"

Then: gh copilot suggest "<task>" or trigger via VS Code Copilot Chat

Nếu dùng Orca terminal (interactive):

orca terminal list orca terminal create --worktree active --title "OpenCode" --command "opencode" orca terminal send --title "OpenCode" --text "<task>" orca terminal wait --for tui-idle && orca terminal read --title "OpenCode"

undefined

undefined

Reference — Phân công task theo chi phí

参考——按成本分派 Task

Task	Agent	Model
Search, grep, list, read	OpenCode	`opencode/big-pickle` ($0)
Viết boilerplate, CRUD	OpenCode	`opencode/big-pickle` ($0)
Wiki ingest/lint	OpenCode	`opencode/big-pickle` ($0)
Review diff, explain	agy	default
Architectural decisions	Claude Code	Opus 5 ( `claude-opus-5` ) — xem chain Claude ở `/orca-dispatch-reference`
Debug lỗi khó	Claude Code	Sonnet 5 ( `claude-sonnet-5` ) mặc định, nâng Opus 5 nếu đứng yên
Frontend UI boilerplate	Kiro	default
Cross-file refactor	Kiro	default
PR review + suggest fixes	Copilot	gpt-4o (GitHub)

Task	Agent	Model
搜索、grep、列出、读取	OpenCode	`opencode/big-pickle` ($0)
编写 boilerplate、CRUD	OpenCode	`opencode/big-pickle` ($0)
Wiki ingest/lint	OpenCode	`opencode/big-pickle` ($0)
审查 diff、解释	agy	default
架构决策	Claude Code	Opus 5 ( `claude-opus-5` )——参见 `/orca-dispatch-reference` 中的 Claude chain
疑难调试	Claude Code	默认 Sonnet 5 ( `claude-sonnet-5` )，卡住时升级到 Opus 5
前端 UI boilerplate	Kiro	default
跨文件重构	Kiro	default
PR review + 建议修复	Copilot	gpt-4o (GitHub)

Reference — Agent binaries

参考——Agent Binaries

Agent	Binary	CHECK
Antigravity	`agy`	`agy --version`
OpenCode	`opencode run -m opencode/big-pickle`	`opencode --version`
Kiro	`kiro run`	`kiro --version`
GitHub Copilot	`gh copilot suggest`	`gh copilot --version`
Orca	GUI only — dùng qua `orca terminal *` commands	`orca terminal list`

Agent	Binary	CHECK
Antigravity	`agy`	`agy --version`
OpenCode	`opencode run -m opencode/big-pickle`	`opencode --version`
Kiro	`kiro run`	`kiro --version`
GitHub Copilot	`gh copilot suggest`	`gh copilot --version`
Orca	仅 GUI——通过 `orca terminal *` 命令使用	`orca terminal list`

Reference — Antigravity Dispatch Reality (tested 2026-05-21, updated 2026-05-23)

参考——Antigravity Dispatch 实际情况（2026-05-21 测试，2026-05-23 更新）

Binary:

agy

—

%LOCALAPPDATA%\agy\bin\agy.exe

. NOT

antigravity

, NOT

~/.local/bin/agy

(Linux).

Tạo terminal:

bash

orca terminal create --worktree active --title "Antigravity" --command "agy"

Hook: Orca v1.4.21 fix Windows hook quoting —

antigravity-hook.cmd

no manual edit needed.

OpenCode:

opencode

— npm global at

%APPDATA%\npm\opencode.cmd

Dispatch status:

Bước	Trạng thái
`dispatch --inject`	Thử sau v1.4.21 — nếu fail, dùng `terminal send`
`terminal send` thủ công	OK
Antigravity đọc file/chạy lệnh	OK
`worker_done` về inbox	Cần retest

Binary：

agy

——

%LOCALAPPDATA%\agy\bin\agy.exe

。不是

antigravity

，也不是

~/.local/bin/agy

（Linux）。

创建 terminal：

bash

orca terminal create --worktree active --title "Antigravity" --command "agy"

Hook：Orca v1.4.21 已修复 Windows hook quoting——

antigravity-hook.cmd

无需手动编辑。

OpenCode：

opencode

——npm global 位于

%APPDATA%\npm\opencode.cmd

。

Dispatch 状态：

步骤	状态
`dispatch --inject`	在 v1.4.21 之后尝试——如果失败，使用 `terminal send`
手动 `terminal send`	OK
Antigravity 读取文件/运行命令	OK
`worker_done` 写入 inbox	需要重新测试

Reference — Slash Skill Installation per Agent CLI

参考——按 Agent CLI 安装 Slash Skill

Agent nhận dispatch: tự cài skill từ

llmwiki/skills/

trước khi bắt đầu.

收到 dispatch 的 agent：在开始前自行从
llmwiki/skills/
安装 skill。

Claude Code CLI

bash

mkdir -p .claude/commands/
cp llmwiki/skills/<loop>/<name>.md .claude/commands/<name>.md

bash

mkdir -p .claude/commands/
cp llmwiki/skills/<loop>/<name>.md .claude/commands/<name>.md

User-level:

mkdir -p ~/.claude/commands/ cp llmwiki/skills/<loop>/<name>.md ~/.claude/commands/<name>.md

undefined

mkdir -p ~/.claude/commands/ cp llmwiki/skills/<loop>/<name>.md ~/.claude/commands/<name>.md

undefined

OpenCode CLI

bash

mkdir -p ~/.agents/skills/<name>/
cp llmwiki/skills/<loop>/<name>.md ~/.agents/skills/<name>/SKILL.md

bash

mkdir -p ~/.agents/skills/<name>/
cp llmwiki/skills/<loop>/<name>.md ~/.agents/skills/<name>/SKILL.md

Restart OpenCode để discover skill mới.

undefined

undefined

Antigravity CLI

bash

mkdir -p ~/.agents/skills/<name>/
cp llmwiki/skills/<loop>/<name>.md ~/.agents/skills/<name>/SKILL.md

bash

mkdir -p ~/.agents/skills/<name>/
cp llmwiki/skills/<loop>/<name>.md ~/.agents/skills/<name>/SKILL.md

Kiro CLI

bash

mkdir -p ~/.kiro/skills/<name>/
cp llmwiki/skills/<loop>/<name>.md ~/.kiro/skills/<name>/SKILL.md

bash

mkdir -p ~/.kiro/skills/<name>/
cp llmwiki/skills/<loop>/<name>.md ~/.kiro/skills/<name>/SKILL.md

GitHub Copilot

bash

undefined

bash

undefined

Workspace-level steering via .github/copilot-instructions.md

Skills injected as context file:

mkdir -p .github/ cat llmwiki/skills/<loop>/<name>.md >> .github/copilot-instructions.md

Or per-skill steering file (Copilot Workspace):

mkdir -p .github/skills/ cp llmwiki/skills/<loop>/<name>.md .github/skills/<name>.md

undefined

mkdir -p .github/skills/ cp llmwiki/skills/<loop>/<name>.md .github/skills/<name>.md

undefined

Rules cho tất cả agent

所有 Agent 的规则

Copy skill files only — skip
```
README.md
```
,
```
index.md
```
,
```
log.md
```
.
File by file — no
```
cp -R
```
.

Scope:

.claude/commands/

(Claude Code);

~/.agents/skills/

(OpenCode/agy);

~/.kiro/skills/

(Kiro);

.github/

(Copilot).

Sau khi cài, report:

| Agent       | Skill   | Installed at                            |
|-------------|---------|------------------------------------------|
| claude-cli  | propose | .claude/commands/propose.md              |
| opencode    | propose | ~/.agents/skills/propose/SKILL.md        |
| antigravity | propose | ~/.agents/skills/propose/SKILL.md        |
| kiro        | propose | ~/.kiro/skills/propose/SKILL.md          |
| copilot     | propose | .github/skills/propose.md                |

只复制 skill 文件——跳过
```
README.md
```
、
```
index.md
```
、
```
log.md
```
。
逐个文件复制——不要使用
```
cp -R
```
。
Scope：
```
.claude/commands/
```
（Claude Code）；
```
~/.agents/skills/
```
（OpenCode/agy）；
```
~/.kiro/skills/
```
（Kiro）；
```
.github/
```
（Copilot）。

安装后报告：

| Agent       | Skill   | Installed at                            |
|-------------|---------|------------------------------------------|
| claude-cli  | propose | .claude/commands/propose.md              |
| opencode    | propose | ~/.agents/skills/propose/SKILL.md        |
| antigravity | propose | ~/.agents/skills/propose/SKILL.md        |
| kiro        | propose | ~/.kiro/skills/propose/SKILL.md          |
| copilot     | propose | .github/skills/propose.md                |

Reference — AgentMemory — Persistent Cross-Session Memory

参考——AgentMemory 持久化跨 Session 记忆

Service tại

https://agentmemory.giatbh.io.vn/

— lưu context giữa các session.

bash

BASE="https://agentmemory.giatbh.io.vn"
TOKEN="${AGENTMEMORY_TOKEN}"

服务地址：

https://agentmemory.giatbh.io.vn/

——在 session 之间保存 context。

bash

BASE="https://agentmemory.giatbh.io.vn"
TOKEN="${AGENTMEMORY_TOKEN}"

Health check

curl -sk -H "Authorization: Bearer $TOKEN" "$BASE/agentmemory/health"

Ghi memory (cuối session hoặc sau quyết định quan trọng)

curl -sk -X POST "$BASE/agentmemory/remember"
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{"content":"<nội dung>","category":"fact|preference|decision|context"}'

Tìm kiếm (đầu session hoặc trước khi propose)

curl -sk -H "Authorization: Bearer $TOKEN"
"$BASE/agentmemory/search?query=<từ+khóa>"


**Khi dùng:**
- **Đầu session**: search context trước khi bắt đầu
- **Sau decision**: lưu approach + lý do
- **Cuối session**: lưu tasks xong, commits, trạng thái

curl -sk -H "Authorization: Bearer $TOKEN"
"$BASE/agentmemory/search?query=<từ+khóa>"


**使用时机：**
- **Session 开始时**：开始前 search context。
- **做出 decision 后**：保存 approach + 原因。
- **Session 结束时**：保存已完成 task、commit 和状态。

Reference — Commands chính

参考——主要命令

bash

orca orchestration run --spec "Propose: <tính năng>. Query wiki, tạo draft, gate chờ duyệt."

Dispatch chi tiết:

llmwiki/skills/orchestrate/orca-dispatch-reference.md

bash

orca orchestration run --spec "Propose: <tính năng>. Query wiki, tạo draft, gate chờ duyệt."

详细 Dispatch 方式：
llmwiki/skills/orchestrate/orca-dispatch-reference.md

Delivery — Output Report (sau khi implement xong)

Delivery——输出报告（实现完成后）

Đây là báo cáo kết quả sau khi implement, KHÔNG phải propose plan. Propose plan phải được tạo ở Bước 2 TRƯỚC khi làm bất kỳ thứ gì.

After all implementation tasks complete, write an output report to the wiki.

这是实现完成后的结果报告，不是 propose plan。 Propose plan 必须在执行任何操作之前，于步骤 2 中创建。

所有 implementation task 完成后，将输出报告写入 wiki。

Steps

步骤

1. Build the filename:

Format:
```
DDMMYY-<ten>.md
```
```
DDMMYY
```
= today (e.g.,
```
020626
```
for 2 June 2026)

<ten>

= 2–4 kebab-case words summarising what was done (e.g.,

landing-page-coteccons

brand-kit-fintech

ingest-auth-spec

)

2. Write

llmwiki/wiki/draft/orca/DDMMYY-<ten>.md

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

1. 构建文件名：

格式：
```
DDMMYY-<ten>.md
```
```
DDMMYY
```
= 当天日期（例如，2026 年 6 月 2 日为
```
020626
```
）
```
<ten>
```
= 2–4 个 kebab-case 单词，概括完成的工作（例如
```
landing-page-coteccons
```
、
```
brand-kit-fintech
```
、
```
ingest-auth-spec
```
）

2. 写入

llmwiki/wiki/draft/orca/DDMMYY-<ten>.md

：

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

DDMMYY-<ten>

Type: draft Status: proposed Tags: <skill-name>, output-report Proposed: YYYY-MM-DD

Agent Task Assignment

Task	Agent	Status
<mô tả task 1>	<tên agent>	pending / in-progress / done
<mô tả task 2>	<tên agent>	pending / in-progress / done

Task	Agent	Status
<mô tả task 1>	<tên agent>	pending / in-progress / done
<mô tả task 2>	<tên agent>	pending / in-progress / done

What

Output

Files

File	Action
`path/to/file`	created / modified

File	Action
`path/to/file`	created / modified

Notes

Invoked via:
```
/<skill-name>
```
skill

Invoked via:
```
/<skill-name>
```
skill

Origin

Draft:
```
wiki/draft/orca/DDMMYY-<ten>.md
```
Commit: (filled by verify-before-commit)
Date promoted: (filled by verify-before-commit)


**3. Update wiki index & log:**
- `llmwiki/wiki/index.md` — append one row: `| [DDMMYY-<ten>](draft/orca/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md` — append: `## YYYY-MM-DD — <skill-name> — <ten>`

**4. Update agent statuses & sync push — BẮT BUỘC, không bỏ qua:**
- Mở lại file `llmwiki/wiki/draft/orca/DDMMYY-<ten>.md`
- Cập nhật cột **Status** trong bảng `## Agent Task Assignment` theo trạng thái thực tế của từng agent (pending → in-progress → done)
- Clone `rheinmir/setup` nhánh `orca`, copy các skill file đã sửa, rồi push ngược lên:
  ```bash
  git clone git@github.com:rheinmir/setup.git /tmp/rheinmir-setup-sync -b orca --depth 1
  cp /path/to/skill.md /tmp/rheinmir-setup-sync/skills/<skill-name>/SKILL.md
  cd /tmp/rheinmir-setup-sync
  git add .
  git commit -m "skill: sync update — DDMMYY-<ten>"
  git push origin orca
  rm -rf /tmp/rheinmir-setup-sync

Skip chỉ khi skill không tạo ra artifact hoặc quyết định nào.

Draft:
```
wiki/draft/orca/DDMMYY-<ten>.md
```
Commit: (filled by verify-before-commit)
Date promoted: (filled by verify-before-commit)


**3. 更新 wiki index 与 log：**
- `llmwiki/wiki/index.md`——追加一行：`| [DDMMYY-<ten>](draft/orca/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md`——追加：`## YYYY-MM-DD — <skill-name> — <ten>`

**4. 更新 agent 状态并同步 push——强制执行，不得跳过：**
- 重新打开 `llmwiki/wiki/draft/orca/DDMMYY-<ten>.md`
- 根据每个 agent 的实际状态更新 `## Agent Task Assignment` 表中的 **Status** 列（pending → in-progress → done）
- Clone `rheinmir/setup` 的 `orca` 分支，复制已修改的 skill 文件，然后反向 push：
  ```bash
  git clone git@github.com:rheinmir/setup.git /tmp/rheinmir-setup-sync -b orca --depth 1
  cp /path/to/skill.md /tmp/rheinmir-setup-sync/skills/<skill-name>/SKILL.md
  cd /tmp/rheinmir-setup-sync
  git add .
  git commit -m "skill: sync update — DDMMYY-<ten>"
  git push origin orca
  rm -rf /tmp/rheinmir-setup-sync

仅当 skill 没有产生 artifact 或 decision 时才可跳过。