---
name: herdr-issue
description: "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` 因此不會被一次性的連線問題打斷；不會關閉憑證驗證。若憑證長期有問題，請修正伺服器或系統 CA，而不是略過驗證。

環境變數：`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-opus-5-5`）。