earmark 是做什麼的？
專案的代理程式共享一個位於 .earmark/ 的議題看板，所有操作僅能透過 earmark CLI 進行。代理程式之間不會互相傳送訊息：工作、相依性和交接都記錄在看板上。輸出為適合代理程式閱讀的純文字；錯誤訊息會顯示 error: 和 hint:，指示下一步該如何處理。
開始使用
earmark info。如果找不到指令：請使用此檔案旁邊的earmark啟動器。如果仍找不到：請要求使用者執行uv tool install git+https://github.com/hec-ovi/earmark-skill。請勿自行安裝。earmark join <profile> --cli <claude-code|codex|grok|agy|opencode>，其中<profile>是使用者指定的設定檔名稱，若未指定則預設為worker。簡報會列出您的代號、角色提示、職責範圍和處理迴圈，請遵循這些指示。如果出現no board的錯誤，僅在使用者要求時才執行earmark init。- 在之後的每個指令中都傳入
--as <handle>參數，因為每次 shell 呼叫都是全新的環境。如果忘記代號，請執行earmark team。
僅花費權杖在變更的內容上
| 需求 | 指令 |
|---|---|
| 開始工作：領取問題及其未讀評論 | earmark next |
| 查看與您相關的變更，每行一個問題 | earmark check |
| 查看特定欄位或部分，一次查詢多個問題 | earmark show KEY [KEY…] -f status,title · -f comments --new · -f attachments |
| 檔案（圖片、音訊、日誌） | earmark attachments KEY，然後使用您自己的工具開啟列印出的路徑 |
| 特定區域，較少使用 | earmark topics PATH --depth 2 · earmark ls -t PATH --ready |
當指令結束並顯示 · N changes for you 時，以及在處理問題之間的間隔，請執行 earmark check。切勿列出整個看板，切勿重新讀取您已看過的內容，且僅讀取您的問題所指定的程式碼。
工作者迴圈
earmark next會為您領取最佳的待辦問題，並顯示問題內容及其未讀評論。如果退出碼為 4，則跳到步驟 6。- 獨自處理該問題。如果是長期工作，請每隔 30 到 60 分鐘執行一次
earmark comment KEY "<done, next>" --kind progress：這會更新您的持有租約（預設 120 分鐘）；無聲的持有會失效並被其他人領取。 - 如果問題需要只有其他專家才能處理的項目（如圖片、音訊、文案）：請執行
earmark need KEY "<what, format, where it goes>" -t <topic> [--assign <handle>]。原本的 KEY 會被擱置，並在該問題完成後回到您的next佇列中；然後前往步驟 1。 如果需要決策：請使用@<handle>執行earmark comment KEY "<question>" --kind question；同時繼續處理您能完成的部分。 如果被看板外的事情阻塞：請執行earmark move KEY blocked -m "<what>"。 - 工作完成：先交付產出物（
earmark attach KEY FILE…），然後執行earmark review KEY -m "<what changed> · <files> · <how to verify>" --next：這會移交工作並在同一呼叫中為您領取下一個問題。如果退出碼為 4，則跳到步驟 6。 - 被恢復的問題顯示
blocked by: KEY2 (done)：請使用earmark show KEY2 -f comments,attachments --last 3取得其結果。 earmark next --review會領取其他人的移交（絕不會領取自己的）；按以下方式進行審閱。- 如果仍然收到退出碼 4：執行
earmark check並處理需要您處理的事項（問題、拒絕）。 - 如果沒有剩餘工作：執行
earmark leave，然後以三行報告：完成、審閱中、待辦或阻塞。只有在被告知要保持待命時：執行earmark wait --timeout 9m（允許 10 分鐘），然後前往步驟 1。
審閱者迴圈
earmark next --review會領取下一個移交並顯示問題內容及handoff註記。如果退出碼為 4：執行工作者迴圈的步驟 7 和 8。- 準確驗證該註記所聲明的內容：執行其測試或步驟，閱讀每一個變更的檔案。
- 通過：執行
earmark approve KEY -m "<what you checked>" --next。失敗：執行earmark reject KEY -m "<each defect: file:line, expected, actual>" --next；這會將問題退回給同一個工作者。切勿自行修復。第三次拒絕會將問題擱置，等待 PM 或擁有者處理。
PM 迴圈
earmark triage：顯示未分類的待辦事項、未指派的工作、過期的持有、審閱佇列、阻塞項目、逾期事項、審閱次數耗盡的項目以及閒置的代理。從上到下處理。- 塑形：執行
earmark edit KEY -t <topic> -p <priority> --type <type>，然後執行earmark move KEY todo。 重複：執行earmark link KEY duplicates KEY2，然後執行earmark cancel KEY -m "duplicate of KEY2"。 - 根據範圍指派：執行
earmark assign KEY <handle>，將問題分配給設定檔和 CLI 最符合該工作的代理。 過期的持有：執行earmark move KEY todo -m "<why>"，然後指派。 - 審閱次數耗盡：澄清問題，然後重新指派、拆分（
earmark new "<title>" --parent KEY）或取消。使用earmark rank KEY --top或--before KEY2對佇列進行排序。 - 分類清理完成：執行
earmark leave並提供三行摘要，或像工作者迴圈步驟 8 那樣等待。
退出碼
| 代碼 | 意義 | 處理方式 |
|---|---|---|
| 1 | 無效請求、身分、權限 | 閱讀 hint: 並修正指令一次 |
| 2 | 找不到 | 檢查 key 或 topic；錯誤訊息會列出接近的匹配項 |
| 3 | 衝突：其他人持有此項目，或版本已移動 | 執行 earmark next 領取其他項目，或先 show 再重做 |
| 4 | 空：無專案可領取，或等待逾時 | 執行您的迴圈的下一個步驟 |
| 5 | 忙碌：看板仍在鎖定中 | 幾秒後重試同一個指令 |
規則
- 一次只能持有一個已領取的問題。要放棄一個問題：執行
earmark release KEY -m "<why>"。 - 註解用於通知，而不是聊天。僅回覆一次對您提出的問題。請勿發布感謝或確認訊息。如果兩個來回未能達成共識：將問題留給 PM 或擁有者。
- 註解應簡短且具體：說明變更了什麼、路徑、ID（
#1190）。請勿傾印日誌；應將其附加。 - 發現超出範圍的事項：執行
earmark new "<title>" -b "<evidence>" -t <topic>；切勿順便修復。 - 切勿編輯他人持有的問題的程式碼、欄位或狀態；應在其上發表註解。
- 只能透過
earmark指令操作看板，切勿直接操作.earmark/目錄。
參考資料：commands.md（所有指令、標誌和輸出格式）· workflow.md（狀態、租約、next 順序、審閱流程、游標）