herdr-issue/skills/herdr-issue/SKILL.md

name, description

name	description
herdr-issue	Run Gitea issues through Herdr: one Claude agent per issue in its own worktree and tab, watch the issue to closure, then offer the next unblocked issues. Use only when the user runs /herdr-issue or explicitly asks to drive a Gitea issue or repo link with Herdr.

herdr-issue

把 Gitea 議題交給 Herdr 裡的 Claude agent 實作。所有確定性的工作都在 scripts/ 裡，你只在「要做決定」的時刻出手。腳本都要在該 repo 的 clone 裡執行；S 代表 ~/.claude/skills/herdr-issue/scripts。

使用者身分

Gitea 一律以 tea 的預設 login（tea login list 中 default 為 true 的那個）操作：lib.sh 會取出它並讓所有 tea 呼叫加上 --login，避免在 clone 裡 tea 依 remote URL 挑到別的帳號。start.sh 也會把該使用者的名稱與 email 設成 worktree 的 git commit 身分。git 走 HTTPS 的帳密由 scripts/git-credential.sh（git credential helper）提供，用同一個 login 的 token：腳本內的 git 自動套用，start.sh 也會把它寫進 clone 的本地設定（只對該 Gitea 主機），所以 agent 在 worktree 裡 push／fetch 不會再出現 could not read Username。要換人先 tea login default <name>，或設 HERDR_ISSUE_LOGIN。

語言規則

本技能的所有回覆、提問、通知與輸出訊息一律使用繁體中文（程式碼、指令、識別字除外）。

前置檢查

1. test "${HERDR_ENV:-}" = 1，不成立就說明不在 Herdr 裡並停止。
2. 解析輸入：
   • 議題連結 https://gitea.jsc.idv.tw/<owner>/<repo>/issues/<N> → 流程 A。
   • #N → 用目前 clone 的 origin 推出 owner/repo，流程 A。
   • repo 連結 https://gitea.jsc.idv.tw/<owner>/<repo> → 流程 B。
3. 目前目錄必須是該 repo 的 clone（腳本會比對 origin）。不是就告訴使用者要在哪個目錄執行並停止。
4. 提醒一句：這個 session 要保持開著，監看與下一步推薦都靠它。

流程 A：啟動一個議題

1. S/start.sh <owner/repo> <N>。它會建 worktree ../<repo>-issue-N（分支已存在就接續）、開 tab #N、啟動 issue-N agent、送提示詞（scripts/prompt.txt）並等 agent 進入 working 或 blocked，確認有反應後才掛 in-progress 標籤。最後一行是 JSON，state 欄位是 agent 當時的狀態（blocked 表示一開始就卡在對話框，watch-issue.sh 會通知）。失敗（agent 啟動不了、送出後沒反應）時它已自己回滾：關 tab、移除 worktree、刪掉本次新建的分支，議題等同沒啟動過。把 stderr 的錯誤照實轉述，不要重跑，跳過第 2 步直接做「推薦下一步」；這個議題會重新出現在「可執行」清單，要重試由使用者再勾。
2. 在背景執行 S/watch-issue.sh <owner/repo> <N>（Bash 的 run_in_background）。它會阻塞到議題關閉，期間 agent blocked 或消失會彈 Herdr 通知；關閉後自己關 tab、清 worktree 與分支、拿掉標籤、往上檢查規格與總覽能不能關。結束時你會被叫醒。
3. 做一次「推薦下一步」。

阻擋規則

議題之間的阻擋只認 Gitea 原生的 issue dependencies（議題頁右側的「依賴」），不看內文。有任何一個 open 的依賴（跨 repo 也算）就是被阻擋：ready.sh 不會列出它，start.sh 會拒絕啟動。依賴的議題一關閉就解鎖，不看 PR 有沒有合併。讀依賴失敗時 ready.sh 整個停下並印出錯誤，不猜。

流程 B：從 repo 挑議題

1. S/ready.sh <owner/repo>。
2. 「可執行」是空的就直接說「目前沒有可執行的議題」，不出多選題，但「執行中」和「掛 in-progress 但沒 agent」照常轉述。否則用多選問題列出「可執行」的議題，每項標題帶規格標籤；同一規格的議題在描述裡註明「同規格，PR 可能互相衝突」。「掛 in-progress 但沒有 agent」的議題另列一題，說明重跑會接續先前分支。
3. 勾選的每一個議題各走流程 A 的第 1、2 步。其中一個 start.sh 失敗不影響其餘的，繼續啟動下一個；全部跑完後把失敗的議題與原因一併轉述，再做一次「推薦下一步」。

推薦下一步

S/ready.sh <owner/repo> 再跑一次（剛啟動的議題已經在執行中，會被排除），結果用多選問題呈現，格式同流程 B（可執行為空就直說，不出題）。沒勾就什麼都不做。

被 watch-issue.sh 叫醒時

把它印出的清理摘要（PR 狀態、分支去留、規格與總覽是否關閉）用兩三句轉述，然後「推薦下一步」。

腳本一覽

腳本	給誰	做什麼
ready.sh	你	列出可執行、執行中、掛 in-progress 但沒 agent 的議題（被阻擋的不列）
start.sh	你	檢查沒被阻擋後建 worktree、開 tab、啟動 agent、送提示詞並確認 agent 有反應、掛標籤；失敗自動回滾
watch-issue.sh	你（背景）	等議題關閉，清理，往上關規格與總覽
tick.sh	子 agent	勾議題內文第 k 個核取方塊
pr-wait.sh	子 agent（背景）	等 PR 衝突、關閉或合併

TLS／憑證錯誤：lib.sh 的 tea 包裝會自動重試（預設 5 次、間隔 3 秒），輪詢中的 watch-issue.sh、pr-wait.sh 因此不會被一次性的連線問題打斷；另外一律忽略 TLS 憑證檢查：lib.sh 會把 tea 設定檔（~/.config/tea/config.yml）所有 login 的 insecure 設為 true，git 則用 GIT_SSL_NO_VERIFY 與 worktree 的 http.sslVerify=false。

環境變數：HERDR_ISSUE_TLS_RETRIES（TLS 重試次數，預設 5）、HERDR_ISSUE_INTERVAL（pr-wait 輪詢秒數，預設 300）、HERDR_ISSUE_WATCH_INTERVAL（watch-issue 輪詢秒數，預設 5）、HERDR_ISSUE_BLOCKED_AFTER（blocked 多久才通知，預設 60 秒）、HERDR_ISSUE_MODEL（預設 claude-sonnet-5-5）。