orca-workflow

Skill: orca-workflow

🧭 调度后端——选择成本较低的 Agent/模型、并行运行多个 worker、opencode/orchestration 语法 → 查看 orca-dispatch-reference（唯一事实来源，请勿在此处重复语法）。

WHAT

目的与上下文

• 目的： 通过 Orca 完成提议 → gate → 调度 → 验证。每种引擎对应一个 Agent pool（claude、agy、opencode、kiro、copilot）。Claude 负责分析，其他 Agent 负责执行。等待时间过长时终止 opencode。
• 触发条件（何时使用）：
• “提议 ”、“功能请求”、“实现 ”
• “运行 lint”、“验证 wiki”
• “同步模板”、“upstream”
• 非目标： 不处理事故（bug、运行时错误、regression → orca-issue）；不重复编写后端调度语法（→ orca-dispatch-reference）；不重述 /propose、/plan、/query 的行为（唯一事实来源在子 skill 中）。

心智模型

功能需求 → R12 sweep → /query（wiki）→ /propose（SPEC .md + 低成本 .html 渲染）→ 人工审批 gate → /plan（机器可读的 PLAN）→ 创建带项目标记的任务 → HITL/AFK gate + 任务类型 → dispatch --inject 原文 → worker_done → [/qc-code] → 提交前验证 → 输出报告。Claude 负责分析，其他 Agent 负责执行；T-id（持久化 ledger）与 task_xxxx（Orca 临时 ID，全局运行时）相互独立。

输入与输出约定

	Field	Required?	含义
输入	功能描述（“提议 ”、“实现 ”）	是	事故 → 转到 orca-issue
输入	llmwiki/wiki/	否	缺失或为空 → 记录“暂无先例”
输入	用户在 gate 的审批	是	必须在 /plan 和调度之前
输入	可用的 Agent CLI（opencode/agy/kiro/gh copilot/orca）	否	若资源耗尽 → 由 Claude 自行处理
输出	SPEC 草稿 .md + .html（通过 /propose）	是	供审批者审阅的内容
输出	llmwiki/wiki/sources/draft/DDMMYY-<tên>-PLAN.md（通过 /plan）	审批后必需	供机器执行的内容
输出	带项目标记的 Orca 任务 + T-id 状态	是	通过 code-logger 记录 approved/rejected/dispatched（fail-open）
输出	输出报告 llmwiki/wiki/draft/orca/DDMMYY-<ten>.md + index + log	必需（无 artifact 时除外）	“完成” = worker_done + verify-before-commit 通过 + 报告中的 Status 已更新

规则与能力

• RULE-01 (MUST)：Caveman Mode：根据文件的读者选择详细程度。由机器或 AGENT 读取并执行的 Markdown 文件（SKILL.md、policy.yaml、AGENT.md、纯参考表）可以写得简短——这里的 Caveman Mode 能节省 token，且不会造成问题。但供人阅读或审阅的文档必须关闭 Caveman Mode 并完整撰写——包括 proposal、output-report、wiki 内容（concept/ADR/registry）、README、CONTRIBUTING 和 runbook，以及所有 HTML 页面。这些文件必须使用完整句子的散文，易于阅读；不要省略连词，不要写成残缺的缩写，也不要用表格堆砌内容来代替解释。2026-06-27 的教训：用户反馈“写文档时 Caveman Mode 压缩得太厉害”，随后澄清——机器读的文件可以简洁，人读的文件则需要完整。
• RULE-02 (MUST)：Claude：分析。其他：执行。等待过久时终止 opencode。
• RULE-03 (MUST)：流程问题登记册（problem-tree）——项目有 llmwiki/ 时，问题树登记册位于 llmwiki/html/problem-tree.html（框架仓库：fdk-problem-tree.html）。任何一轮中发现或解决流程／框架问题时，都要将节点更新到 JSON 区块 #tree-data（仅追加；已解决的问题必须填写 solvedBy；按 harness/skills/llmwiki 三大支柱确定范围——仅当 3/3 时才标为绿色）。即使忘记也不会丢失：SessionEnd hook（R17）会自动用代码记录待处理标签，下次再提炼。
• RULE-04 (MUST)：任务 spec 必须加盖项目标记：orca orchestration task-create --spec "$(python3 harness/scripts/orca-reconcile.py --stamp '<spec>')"（Orca 任务登记册是 runtime-global）。
• RULE-05 (MUST)：分配给某个 agent 的 HITL 工作如果只剩下替用户猜测然后沉默，那就是 1/5 分，不是模型不够聪明——HITL 不得分发给无头 CLI。
• RULE-06 (MUST)：--inject 会原样注入 PLAN 中的任务 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；运行无头 agent CLI 或交互式终端；写入 wiki 草稿和 T-id ledger；（可选）通过 HTTP 实现跨会话记忆；将 skill 同步推送到源仓库。

故障边界

• 输入是事故 → 转至 orca-issue，不要提案。
• R12 sweep：subrepo TARGET 落后于 remote → 在执行 git pull --rebase 前保持 blocked；离线 → fail-open。
• 用户在 gate 拒绝 → cancelled，T-id state=rejected。
• HITL 任务 → 不得分发，标签为 ready-for-human（等待人工处理）。
• 无头 CLI 沉默超过约 60–90s／未创建文件／缺少 diagram-box → 终止，由 Claude 接管（回退方案）。
• 容器 volume 与 compose 不同 → blocked，询问用户。
• task-update --status done → 静默返回 ok:false（有效状态：ready | in_progress | completed | failed）。

HOW

Quy trình chính

Bước	Loại	Đầu vào	Hành động	Đầu ra/thoát	Thất bại/tiếp theo
W01	xác định	không gian làm việc	Bước 0 — R12 (B) quét trước khi làm việc bằng pull-gate-sweep.sh một lần	cơ sở mới nhất	TARGET sau remote → pull --rebase rồi lặp
W02	phán đoán	tính năng	Bước 1 — GỌI /query để tổng hợp ngữ cảnh wiki	thông tin đã biết + lỗ hổng	trống → "chưa có tiền lệ"
W03	phán đoán	ngữ cảnh	Bước 2 — GỌI /propose (SPEC .md)；.html được chuyển sang CLI rẻ hơn để kết xuất, có watchdog	SPEC .md + .html	CLI im lặng → B03
W04	hiệu ứng	SPEC	Bước 3 — orca orchestration gate-create，chờ người dùng；ghi T-id đã duyệt/từ chối	phê duyệt	từ chối → đã hủy
W05	phán đoán	SPEC đã duyệt	Bước 4 — GỌI /plan → PLAN；task-create cho mỗi ### Task kèm spec được đóng dấu	task task_xxxx	R7 chặn PLAN → sửa PLAN
W06	phán đoán	task	Bước 4b — Cổng 1 HITL/AFK，Cổng 2 xác định kiểu việc → archetype，sau đó mới lập bảng chi phí	task AFK có kiểu + CLI	HITL → B02
W07	hiệu ứng	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 đã được dispatch	worker đang chạy	—
W08	xác định	dispatch	Bước 6 — orca orchestration check --wait --types worker_done --timeout-ms 300000	worker_done	hết thời gian chờ/im lặng → B03
W09	xác định	diff	Bước 7 — verify-before-commit（bao gồm qc-regression.py --run）	commit sạch	lỗi → sửa
W10	hiệu ứng	kết quả	Báo cáo đầu ra + cập nhật trạng thái agent + đồng bộ đẩy skill（mục Delivery）	bản nháp + chỉ mục + nhật ký	không có artifact → bỏ qua

Chi tiết từng bước（nguồn chân lý cho W01–W09）： 0. R12 (B) — 开工前扫描整个工作区（仅一次，在开工／多 Agent 扇出前）：orchestrator 运行 harness/poc-vendor-neutral/bin/pull-gate-sweep.sh — 扫描所有子仓库（从 .harness-workspace.yaml 获取；若缺失，则自动发现已接入 harness 的仓库），并行 fetch；远程有更新的子仓库 TARGET → 停下，在该仓库中运行 git pull --rebase，之后再派发（所有 Agent 共用新鲜基线）；子仓库 watch 仅发出警告。仅有 1 个仓库时 → sweep 自动退回 pull-gate.sh。离线 → fail-open。不要在每次编辑时阻塞（有意省略 per-edit PreToolUse）。R12 (C) 每个仓库的 gate2：使用 install-harness.sh --all-subrepos 安装所有子仓库；手动检查：pull-gate.sh gate2。

1. query：调用 query 技能（Skill 工具 → query，或 /query），从 wiki/ 综合功能相关上下文 — 不要零散地手动阅读，使用正确的 wiki-loop query（综合 [[wikilinks]]，返回已知信息和缺口）。项目没有 wiki/（或 query 返回空）→ 记录“暂无先例”，然后进入步骤 2。
2. propose — 不要重新描述；调用 propose 技能（Skill 工具 → /propose，与步骤 1 调用 query 的模式一致）。所有 R7 要求（成对的 .md+.html、## Plan、## Agent Task Assignment、glass-style docs-site-macos、详细正文）都写在子技能中 — 修改 propose 行为只需修改 llmwiki/skills/dev-loop/propose.md，不要在此处修改（唯一事实来源，见 [[ADR-003-skill-as-single-source-of-truth]]）。
   • **分离 Claude 思考／廉价 CLI 渲染：**Claude（通过 /propose）只产出 SUBSTANCE = 可完整渲染的 .md（Plan + 正文 + ## Render brief = 以数据形式描述的图表步骤 + 每个 task 的正文段落）。.html 部分是对 ## Render brief 的机械式 RENDER → 根据成本表派发给一个廉价 CLI（OpenCode big-pickle → agy → kiro，$0）。渲染免费，因此应使用 Full docs-site-macos 的丰富呈现，不要删减 — Claude token 只花在 substance 上，不会因 HTML 丰富而增加。
   • **Watchdog + R7 gate（250626 的经验 — 无头模式交付约 1/5）：**等待约 60–90 秒；无响应／未创建文件／缺少 diagram-box → 终止，回退到由 Claude 渲染。按顺序尝试可用的廉价 CLI（探测 --version）；全部耗尽 → Claude。R7 仍会在写入和提交时拦截，因此无论由谁渲染，质量都有保障。
3. gate：orca orchestration gate-create --question "Duyệt proposal này?" → 等待用户（附上 html 的预览 URL）
   • **生命周期支柱 3（尽力而为，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，不阻塞流程。
4. 批准后 — 必须先调用 plan 技能（Skill 工具 → /plan），再拆分任务。/propose 生成 SPEC（供人阅读并审批）；/plan 将其扩展为 llmwiki/wiki/sources/draft/DDMMYY-<tên>-PLAN.md — 供机器阅读并执行：每个 ### Task 都包含 **Files:**（精确路径）、**Interfaces:**（Consumes/Produces — 相邻 task 的签名），以及以 TDD 方式编写的 2–5 分钟步骤，包含真实代码、命令和预期输出。缺少这些内容时，R7 的 PLAN 分支会拦截。然后才为每个 ### Task 运行 orca orchestration task-create — spec 必须盖上项目印章： orca orchestration task-create --spec "$(python3 harness/scripts/orca-reconcile.py --stamp '<spec>')". Orca 的任务账本是全局运行时账本（Orca 指南明确说明）；2026-07-20 的测量结果：多个项目的 18 个终端同时写入同一本账本，因此仓库 A 中的 task-list 会返回仓库 B 的工作 — 一个 orchestrator 可能误领其他项目的任务，破坏物理层隔离偏差这一目标。Orca 没有项目字段（task-create 没有 tag，task-list 没有筛选器），因此这个印章是准确归属任务的唯一方式 — 即使创建任务的终端已关闭，它仍然有效（实测：旧终端中仍存活的有 0/17）。对账：orca-reconcile.py [--scope current|all]。
   • 为什么这是强制要求，而不是“建议”：无头模式下运行的廉价 CLI Agent 不会继承当前会话的任何上下文，也无法追问 — 它只知道我们提供给它的内容；遇到模糊之处，它会猜测并保持沉默。简略的 brief 正是实测“交付约 1/5”（250626 的经验）的原因，而不是模型不够聪明。
   • PLAN 不需要 .html — HTML 与 SPEC 绑定（即审批时供人查看的内容），由 /propose 生成。为了让 Agent 阅读而绘制图表，只是在浪费 token。 4b. 分派正确类型的工作 — 选择 CLI 前先运行关卡。下方成本表只回答“哪个模型最便宜”。它从未询问“这项工作是否可以不依赖人来完成” — 这正是约 1/5 这一数据背后缺失的环节。两个关卡，顺序不可颠倒：
   • **关卡 1 — HITL/AFK。**任务需要一个真实的人来回答（设计决策、权衡、只有用户知道的信息、外部访问、人工检查），即为 HITL → 在账本中标注 ready-for-human，不要派发给无头 CLI。只有 AFK（ready-for-agent）任务才能继续。硬性规则：把 HITL 任务交给 Agent，它只能代替用户猜测，然后保持沉默 — 这就是 1/5 的原因，不是模型不够聪明。
   • **关卡 2 — 工作类型 → archetype。**为 task 标注工作类型：research（找出事实）· prototype（供人反馈的粗糙版本）· grilling（逐个提问）· build（按 brief 执行）· sweep（机械式清理）。映射到 archetype（ADR-015）→ persona 前置提示词。之后才由成本表选择 CLI — 它是最后一步，不是第一步。
5. dispatch：orca orchestration dispatch --task <id> --to <agent> --inject
   • **--inject 将 PLAN 中该 task 的 brief（Files + Interfaces + Steps）连同 PLAN 的 ## Global constraints 原文注入。**不要重新概述 — 概述正是上下文丢失的环节，而且丢失的总是 Agent 所需的信息。
   • **brief 的第一行要说明工作类型：**用一句话直说当前会话要做什么 — “你正在解决一个决策问题，不是在构建功能”／“你正在做机械式清理，不要添加功能”。工作类型决定会话的形态，不只是选择模型；知道自己在做什么的 Agent，行为与只拿到一大段描述的 Agent 截然不同。
   • **生命周期支柱 3（尽力而为）：**派发工作时 → python3 harness/scripts/code-logger.py --task set <T-id> state=dispatched note="<agent>"。这是持久的 T-id（不可变的审计追踪），独立于 orca orchestration 的临时 task_xxxx。Fail-open。
   • 按 archetype 选择 persona（Boris Cherny — 生命周期中的 5 种角色）：如需按特定 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) persona PREAMBLE（llmwiki/personas/<archetype>.md）— 派发前将该前置提示词注入 <task> 以便 agy/opencode/kiro 进入正确角色（例如，禁止 Sweeper 添加功能）。各 CLI 与 archetype 的适配关系标记为 verified:false（harness/archetypes.config.yaml）。参见 ADR-015。
6. 等待：orca orchestration check --wait --types worker_done --timeout-ms 300000 6b. （可选）提交前由资深人员进行 QC — 如需资深人员在定稿前检查 diff，可调用 /qc-code（Skill 工具 → qc-code）：审查 4 个方面（安全性／性能／命名／逻辑），给出评分和 verdict，并为每个逻辑错误生成可复现的测试 qc-*。Verdict 为 NEEDS FIX → 提交前修复。可选，不是强制要求 — LLM 的 verdict 仅供参考（由人决定），硬性保障是步骤 7 中运行的 qc-* 测试。
7. 检查：verify-before-commit 会在每次提交前自动运行（包括步骤 3b：qc-regression.py --run 运行确定性的 qc-* 测试 — 防止已复现的 bug 悄然回归）。

分支

ID	类型	条件	行为	跳过 / 失败	汇合点
B01	必需条件分支	输入是故障（bug、运行时错误、回归问题、“昨天还好好的”）	调用 skill orca-issue，而不是提出方案	严重故障需要扇出处理 → orca-issue 升级至 W07，并保留其 2 个硬性关卡	结束（或升级时转至 W07）
B02	必需条件分支	任务需要真人回复（HITL）	在 ledger 中标记 ready-for-human，不要分派给无头 CLI	—	等待人工处理，然后转至 W06
B03	恢复分支	无头 CLI 静默约 60–90s / 未创建文件 / 缺少 diagram-box	终止进程 + Claude 按规范自行接管；按现有顺序尝试下一个成本低的 CLI（探测 --version）	CLI 用尽 → Claude	正在运行的步骤（W03/W08）
B04	用户可选分支	想在定稿前检查 diff	步骤 6b — /qc-code（裁定仅供参考 + 测试 qc-*）	裁定为“需要修改” → 提交前先修改	W09
B05	用户可选分支	想按工作姿态分派（/proto /build /sweep /grow /maintain）	python3 harness/scripts/archetype.py --get /<kw> → CLI 建议 + 将 PREAMBLE persona 注入 <task>	—	W07
B06	必需条件分支	即将操作 docker（--force-recreate、down、重建）	检查 docker inspect 挂载，并与 compose 比较；不一致 → 停下并询问用户	没有备份和确认 → 不更改 volume	正在运行的步骤
B07	可选能力分支	存在 AGENTMEMORY_TOKEN	在会话开始时搜索 / 决策后及会话结束时记忆（参考 — AgentMemory）	不存在 → 跳过	W02 / W10

故障分支详情（原文）：

分支：故障 ≠ 功能

输入是故障（bug、运行时错误、回归问题、“昨天还好好的”）→ 调用 skill orca-issue，而不是提出方案：独立的分诊流程 → 先复现关卡（尚未复现前不得修复）→ 红转绿修复 → 双重提炼。严重故障需要扇出处理时，orca-issue 会升级回此处进行分派，但仍保留其 2 个硬性关卡。

验证与停止

人工关卡：W04 关卡（批准 SPEC）和 W06 的 HITL 关卡 1。机器关卡：R7 在写入和提交时拦截缺少条目的 SPEC/PLAN；每次提交前运行 verify-before-commit + qc-regression.py --run。CLI 看门狗约 60–90s（B03）；check --wait 超时为 300000 ms。按项目核对任务：orca-reconcile.py [--scope current|all]。

示例

• 正向示例：“为报告提出 CSV 导出功能” → 完成清理 → /query 找到 2 个相关页面 → /propose 生成 SPEC，使用 opencode run -m opencode/big-pickle 将 .html 渲染出来 → 用户批准关卡 → /plan 生成包含 3 个任务的 DDMMYY-export-csv-PLAN.md → task-create 创建并附带 stamp → 2 个 AFK build 任务通过 --inject 分派，1 个 HITL 任务（“选择日期格式”）标记为 ready-for-human → worker_done → verify-before-commit 检查通过 → 输出报告。
• 边界/失败：“昨天登录还正常，今天返回 500” → B01：不提出方案，调用 orca-issue（先复现）。
• 边界情况：opencode run 渲染 .html 时静默 90s，且未创建文件 → B03：终止进程，由 Claude 渲染作为回退；R7 仍会在写入时把关质量。

参考 — 编排 CLI 的注意事项（230626 经验总结）

• task-create --json 返回的 2 个 id：响应包含外层 id（uuid）和 result.task.id（task_xxxx）。后续所有命令（gate-create --task、dispatch --task、task-update --id）都必须使用 result.task.id，不能使用外层 id。用错时，gate 仍可创建/解析，但会指向虚假任务 → 真实任务卡在 ready。
• task-update --status 的有效状态：ready | in_progress | completed | failed。没有 done — 传入 done 会静默返回 ok:false（没有明确的错误提示）。
• 确保获取真实 id：运行 orca orchestration task-list --json，然后按 spec 匹配。

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

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

# 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

比较 Source 路径与即将使用的 compose 文件中的 volume。如果不同 → 停止，询问用户。

Cozyroom 生产数据库： /mnt/c/Users/olive/orca/workspaces/home-spotify/m/data/metadata.db 未经备份并获得用户确认，绝不更改 volume 挂载。

经验教训 2026-05-29：使用路径错误的 compose 重新创建容器 → 所有用户数据库丢失。

参考 — 快速分派

⚠️ 无头 CLI Agent 不可靠（经验教训 250626 — orca-eval）： 从 Claude Code 后台运行的 opencode run / agy -p / kiro run 通常无法交付（进程退出或挂起，未创建文件——实测仅 1/5 个任务成功）。规则：设置看门狗（约 60–90 秒），如果没有响应或没有文件 → 终止进程 + Claude 根据规范自行接手（不要白等）。OpenCode 仅用于已验证可行的独立样板代码任务；有依赖或需要细致处理的任务 → 由 Claude 完成。要真正分派给 Agent → 优先使用交互式 orca terminal，而不是 -p / run。

# 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"

参考 — 按成本分配任务

任务	Agent	模型
搜索、grep、列出、读取	OpenCode	opencode/big-pickle（$0）
编写样板代码、CRUD	OpenCode	opencode/big-pickle（$0）
Wiki 导入/检查	OpenCode	opencode/big-pickle（$0）
审查 diff、解释	agy	默认
架构决策	Claude Code	Opus 5（claude-opus-5）——参见 /orca-dispatch-reference 中的 Claude 链
调试棘手错误	Claude Code	默认使用 Sonnet 5（claude-sonnet-5），停滞时升级到 Opus 5
前端 UI 样板代码	Kiro	默认
跨文件重构	Kiro	默认
PR 审查 + 建议修复	Copilot	gpt-4o（GitHub）

参考 — Agent 二进制文件

Agent	二进制文件	检查
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

参考 — Antigravity 分派实况（2026-05-21 测试，2026-05-23 更新）

二进制文件：agy — %LOCALAPPDATA%\agy\bin\agy.exe。不是 antigravity，也不是 ~/.local/bin/agy（Linux）。

创建终端：

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

Hook：Orca v1.4.21 修复了 Windows hook 引号问题——无需手动编辑 antigravity-hook.cmd。

OpenCode：opencode — npm 全局安装于 %APPDATA%\npm\opencode.cmd。

分派状态：

步骤	状态
dispatch --inject	v1.4.21 后测试——如果失败，使用 terminal send
手动执行 terminal send	正常
Antigravity 读取文件/运行命令	正常
worker_done 返回 inbox	需要重新测试

参考 — 各 Agent CLI 的 Slash Skill 安装

收到分派的 Agent：开始前自行从 llmwiki/skills/ 安装 skill。

Claude Code CLI

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

OpenCode CLI

mkdir -p ~/.agents/skills/<name>/
cp llmwiki/skills/<loop>/<name>.md ~/.agents/skills/<name>/SKILL.md
# Restart OpenCode để discover skill mới.

Antigravity CLI

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

Kiro CLI

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

GitHub Copilot

# 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

所有 Agent 的规则

• 仅复制 skill 文件——跳过 README.md、index.md、log.md。
• 逐个文件操作——不要使用 cp -R。
• 范围：.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                |
  

参考 — AgentMemory — 跨会话持久记忆

服务位于 https://agentmemory.giatbh.io.vn/ — 用于保存各会话之间的上下文。

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>"

使用时机：

• 会话开始时：开始前搜索上下文
• 决策后：保存方案及理由
• 会话结束时：保存已完成的任务、提交记录和状态

参考 — 主要命令

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

分派详情：llmwiki/skills/orchestrate/orca-dispatch-reference.md

---

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

这是实现后的结果报告，不是计划提案。 计划提案必须在第 2 步中，在开展任何工作之前创建。

所有实现任务完成后，将输出报告写入 wiki。

步骤

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 |

## What
<One sentence — what this skill invocation produced or decided>

## Output
<Key artefacts, files created/modified, or decisions made>

## Files
| File | Action |
|------|--------|
| `path/to/file` | created / modified |

## Notes
- 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. 更新 wiki 索引和日志：

• 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 状态并同步推送 — 必须执行，不可跳过：

• 重新打开文件 llmwiki/wiki/draft/orca/DDMMYY-<ten>.md
• 根据每个 Agent 的实际状态（pending → in-progress → done）更新 ## Agent Task Assignment 表格中的 Status 列
• 克隆 rheinmir/setup 的 orca 分支，复制已修改的 skill 文件，然后推送回去：

  git clone [email protected]: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 未创建任何产物或未作出任何决策时，才可跳过。