name: dev-team description: "Multi-agent development team orchestration. Use when managing coding agents (Codex, Claude Code, Gemini, Cursor) for automated software development: (1) Spawning agents for tasks, (2) Monitoring agent status, (3) Managing git worktrees, (4) Automated code review, (5) Handling notifications via Feishu."

Dev Team

One-person dev team orchestration using Levi as the orchestrator.

Main Agent Rules (入口摘要)

主 Agent 是編排器（orchestrator），不是預設主力編碼器。

關鍵準則：

• PR 優先：正式開發預設使用 --completion-mode pr
• 禁止 SubAgent 在 main/master 上直接開發（spawn-agent.sh 已攔截）
• 主 Agent 使用最小上下文：優先看狀態機與聚合結果，而不是全量日誌
• 階段化編排：明確 --phase build|review|fixup
• 自動化負責推進與收口（check/review/fixup/cleanup/prune），人工保留最終產品決策與 GitHub approve
• SubAgent DONE 不等於任務完成：合併前必須做 post-task review（DoD + 真實驗證 + 指標門禁）

  7w4.net收錄了海量優質技能外掛。

詳細說明見：

• references/AGENTS.md（主 Agent 行動準則）
• （已合併入 references/AGENTS.md）編排模型與狀態機
• （已合併入 references/AGENTS.md）主 Agent 最小上下文操作手冊

Quick Start

首次使用

# 執行設定檢查
scripts/setup-check.sh

啟動內建 dev-board 控制面板

dev-team 已內建 scripts/dev-board/，可直接啟動：

./scripts/run-dev-board.sh

預設地址：http://localhost:4310

Spawn an Agent

正式功能開發（推薦 PR 流程）：

scripts/spawn-agent.sh \
  --agent auto \
  --phase build \
  --repo-path ./scripts/dev-board \
  --branch feat/auth-timeout-fix \
  --description "修復登入超時錯誤" \
  --completion-mode pr \
  --prompt-file /tmp/task-prompt.txt

本地 smoke / 臨時探索（僅無 PR 場景使用 session）：

scripts/spawn-agent.sh \
  --agent auto \
  --repo-path ./scripts/dev-board \
  --branch fix/auth-error \
  --description "修復登入超時錯誤" \
  --phase build \
  --completion-mode session \
  --prompt-file /tmp/task-prompt.txt

Check Agent Status

cat assets/active-tasks.json

Monitor Agents

scripts/check-agents.sh

Mandatory: Post-task Review Gate (合併前必做)

當 SubAgent 報告完成（例如 TASK_*_DONE）後，主 Agent 必須執行：

# 1) 看任務狀態與日誌摘要
scripts/check-agents.sh

# 2) 稽核 subagent 提交內容（示例）
git -C <subagent-worktree> show --name-only --oneline -n 1 <commit>

# 3) 在目標倉庫執行任務 DoD 規定的真實驗證命令（示例）
# 例如：真實 ingestion/validate、真實 API 呼叫、非 mock 鏈路

通過標準： - DoD 條款全部滿足 - 至少 1 條真實鏈路驗證通過（非 mock） - 指標達到任務閾值（如 successRate/evidenceBindingRate/citationNonEmptyRate/fallbackRate）

不通過處理： - 不合並 - 立即派發 fixup（同分支或新分支） - 在 docs 中記錄“未通過項 + 修復輸入”

Supported Agents

Scripts

spawn-agent.sh

建立新任務並啟動代理。

引數： - --agent (必需): codex | claude | gemini | cursor | auto（推薦） - --repo (必需二選一): 倉庫名（位於 skill 上級目錄時使用） - --repo-path (必需二選一，推薦): 倉庫絕對/相對路徑；用於 skill 根目錄外的倉庫 - --branch (必需): 分支名 - --description (必需): 任務描述 - --prompt (三選一): 代理提示詞（短文本時可用） - --prompt-file (三選一，推薦): 從檔案讀取提示詞，避免 shell 轉義問題（尤其包含反引號、$()、多行內容） - --prompt-b64 (三選一): Base64 提示詞，適合指令碼自動化呼叫 - --agent-model (可選): 指定模型（例如 --agent cursor --agent-model composer-1.5） - --cursor-mode (可選): dev|plan（僅 cursor 生效，預設 dev） - plan 時會自動使用模型 gpt-5.3-codex - --phase (可選): build|review|fixup（預設 build）；會受 config/user.json.agentPolicy 限制 - --completion-mode (可選): pr(預設) | session；本地測試倉庫無 PR 時建議用 session - --auto-merge (可選，pr 模式): 當 CI 與 review 滿足條件後觸發 gh pr merge --auto - --merge-method (可選，pr 模式): squash|merge|rebase，預設 squash - --cleanup-after-seconds (可選): 臨時 worktree 清理 TTL；session 模式預設 3600

check-agents.sh

監控所有執行中的代理。

功能： - 檢查 tmux 會話是否存活 - 檢查 PR 是否已建立（completionMode=pr） - 跟蹤 PR 狀態機（waiting_checks / checks_failed / waiting_review / changes_requested / merge_ready / merge_queued / merged） - 檢查 required CI checks（gh pr checks --required） - 檢查 reviewDecision（gh pr view --json reviewDecision） - 可選自動觸發 gh pr merge --auto（任務級 autoMerge 或 config/user.json.pr.autoMerge） - 失敗自動重試（按配置延遲，最多3次；依賴任務記錄中的命令後設資料） - 寫入通知到 notifications.json (由 OpenClaw 傳送飛書通知) - 結束後可自動觸發 cleanup-worktrees.sh 與 prune-history.sh（避免 worktree / active-tasks 膨脹）

注意： - session exit mode 僅表示會話結束，不代表質量達標。 - 質量達標必須由主 Agent 的 post-task review 判定。

review-agent.sh

多 reviewer 程式碼審查（預設三審：codex + gemini + claude）。

引數： - --repo (必需): 倉庫名 - --branch (必需): 分支名或 PR 號 - --reviewers: 審查者 (預設: codex,gemini,claude；預設要求至少 3 個) - --allow-fewer-reviewers: 除錯用，允許少於 3 個 reviewer - --no-post: 只生成本地審查產物，不回寫 PR 評論

行為（新版）： - 每個 reviewer 生成結構化審查結論（Verdict / Findings / Validation / Next Steps） - 自動抓取 gh pr diff 並注入 reviewer prompt（截斷版） - 每個 reviewer 單獨在 PR 下發表評論（正文帶 [dev-team][reviewer=...] 標識） - 會按 config/user.json.agentPolicy 過濾停用/階段不允許的 reviewer - 生成聚合結果 assets/logs/reviews/review-<pr>-<ts>.aggregate.json - 聚合策略會結合 reviewer 權重、severity 和 reviewer 角色偏好，輸出： - waiting_human_approve - review_changes_requested - review_human_attention - 寫回 assets/active-tasks.json： - checks.reviewAggregate - checks.reviewSummary - checks.fixupSuggested - checks.fixupTarget（用於後續優先回原 subagent 返工）

aggregate-reviews.sh

聚合多 reviewer 的審查產物，輸出單一決策（通過 / 需修改 / 人工關注）。

示例：

./scripts/aggregate-reviews.sh --file assets/logs/reviews/review-1-1234567890.json

request-fixup.sh

根據 review-agent 聚合結果，為原 PR 負責 subagent 生成返工 prompt，並優先發回原 subagent（如會話仍存活）。

引數： - --branch <branch> 或 --pr <number>：定位任務 - --dry-run：只生成返工 prompt，不執行 - --spawn-if-dead：原 subagent 會話已退出時，按同 branch 重新派工（謹慎使用）

行為： - 讀取 checks.reviewAggregate / checks.reviewAggregateFile - 若 fixupSuggested=true，生成結構化返工 prompt（按 severity 排序） - 寫回 checks.fixupRequestedAt / checks.fixupRequestMode - 預設優先回原 subagent（同 branch owner）處理

Agent Adaptation & Policy

• 統一 agent 適配與全流程使用建議：references/agent-adapters.md
• 可配置 agent 啟用開關與階段允許列表：config/user.json -> agentPolicy
• 推薦器支援階段引數（會過濾停用 agent）：

./scripts/recommend-agent.sh --description "前端看板最佳化" --phase build
./scripts/recommend-agent.sh --description "PR 程式碼稽核" --phase review

cleanup-worktrees.sh

清理已合併的 worktree。

補充說明： - 對 completionMode=session 且 cleanupMode=session_ttl 的任務，會在 cleanupEligibleAt 到期後自動清理 worktree - 清理後任務狀態會寫回為 cleaned（保留歷史記錄）

prune-history.sh

歸檔 assets/active-tasks.json 中過舊的已完成任務（done/failed/cancelled/cleaned/...），避免登錄檔無限增長。

常用引數： - --keep-days <days>: 僅歸檔早於 N 天的記錄（當前預設配置為 0，更偏熱資料） - --keep-count <n>: 無論時間如何，至少保留最近 N 條非失敗/取消終態記錄（當前預設配置為 12） - --keep-fail-cancel-days <days>: failed/cancelled 獨立歸檔天數（預設可更激進） - --keep-fail-cancel-count <n>: 至少保留最近 N 條 failed/cancelled - --dry-run: 預覽歸檔數量，不落盤

自動化建議： - cleanup-worktrees.sh 執行後自動觸發 prune-history.sh（可在 config/user.json.archive 配置） - 也可單獨配置每日歸檔 cron

說明： - cleanup-worktrees.sh 會清理孤兒 worktree（任務已歸檔但同級目錄仍殘留） - session_ttl 會受全域性 TTL 上限約束，避免歷史任務長時間佔用磁碟

setup-check.sh

首次使用檢查指令碼，驗證配置完整性。

recommend-agent.sh

根據任務描述/提示詞關鍵詞、當前執行負載、CLI 健康狀態推薦最合適的 agent（含理由）。

示例：

./scripts/recommend-agent.sh \
  --description "dev-board 前端 UI 產品化改版，最佳化篩選與日誌面板" \
  --prompt-file /tmp/task-prompt.txt \
  --format json

list-agent-models.sh

列出 agent 模型（當前主要用於 Cursor）。

示例：

./scripts/list-agent-models.sh cursor

enqueue-task.sh / list-queue.sh / claim-task.sh

Queue/Claim 模式（推薦演進路徑，現已提供最小可用版本）：

• enqueue-task.sh：主 Agent 新增任務到佇列（assets/tasks.json）
• list-queue.sh：檢視佇列（支援狀態/階段過濾）
• claim-task.sh：認領一個 queued 任務並呼叫 spawn-agent.sh 派工
• sync-queue-status.sh：根據 assets/active-tasks.json 回寫佇列任務狀態（running/done/cleaned/...）
• prune-queue-history.sh：歸檔 assets/tasks.json 中過舊終態佇列任務到 assets/logs/archives/queue-history-YYYY-MM.jsonl

示例：

./scripts/enqueue-task.sh \
  --repo-path ./scripts/dev-board \
  --branch feat/dev-board-action-history \
  --description "dev-board 操作歷史列表" \
  --phase build \
  --completion-mode pr \
  --prompt-file /tmp/task.txt

./scripts/list-queue.sh --status queued
./scripts/claim-task.sh --agent auto

Task Registry

位置：assets/active-tasks.json

編碼約定： - 所有任務與通知 JSON 檔案統一使用 UTF-8 儲存 - 寫入時使用 ensure_ascii=False，中文會以可讀形式儲存（不再顯示 \\uXXXX）

歸檔約定： - assets/active-tasks.json 儲存熱資料（執行中 + 近期終態任務） - 歷史記錄歸檔到 assets/logs/archives/task-history-YYYY-MM.jsonl

任務狀態以指令碼實現為準，詳見 references/state-machine.md。

補充欄位（新任務會記錄）： - requestedAgent: 使用者請求的 agent（可能是 auto） - agentModel: 實際使用模型（如 composer-1.5） - agentSelectionReason: 自動派工的簡要理由（關鍵詞/健康回退等）

References

• 狀態機: references/state-machine.md
• CLI / tmux: references/cli-reference.md
• Prompt 模板: references/prompt-templates.md（推薦 Subagent Task Contract）
• 完成後驗收清單: references/post-task-review-checklist.md
• 初始化 / Cron: references/initialization.md

Troubleshooting

1) Claude 子任務啟動失敗（常見於複雜 prompt）

常見根因： - 在 shell 中直接使用 --prompt "..."，內容包含反引號、$() 等，導致 shell 提前展開，實際傳給指令碼的 prompt 被汙染。

修復方式（推薦順序）： 1. 使用 --prompt-file（首選） 2. 自動化呼叫使用 --prompt-b64 3. 僅短 prompt 使用 --prompt

2) Cursor agent 無法使用 / 很少被選中

如果 cursor agent status 顯示 Not logged in，spawn-agent 會在啟動前直接失敗並提示：

cursor agent login

你提到常用模型 composer 1.5，當前已在 config/agents.json 中設為 Cursor 預設模型（composer-1.5）。 如需覆蓋：

./scripts/spawn-agent.sh --agent cursor --agent-model composer-1.5 ...

Cursor plan 模式（用於版本前差異分析）：

./scripts/spawn-agent.sh \
  --agent cursor \
  --cursor-mode plan \
  --repo-path /path/to/repo \
  --branch feat/version-plan \
  --description "版本規劃與差異分析" \
  --completion-mode session \
  --prompt-file /tmp/plan.txt

說明： - 該模式等價於 cursor agent --mode plan（只讀規劃，不改程式碼） - spawn-agent 會強制模型為 gpt-5.3-codex

3) PR / CI / review 流程不推進

必要前置條件： 1. 倉庫已配置 GitHub origin remote 2. gh auth status 有效（token 未過期） 3. subagent 的 prompt 明確要求： - 提交 commit - git push -u origin <branch> - gh pr create ...

如果缺一項，check-agents.sh 無法推進 PR 狀態機。

tmux

tmux new-session -d -s <name> -c <dir> "command"
tmux send-keys -t <session> "text" Enter
tmux list-sessions
tmux kill-session -t <session>

這個 Skill 質量不錯，是一個功能完整的 AI 開發團隊自動化工具。它能自動派發任務、監控進度、審查程式碼、處理修復，配套的視覺化面板讓狀態一目瞭然。最關鍵的是它有嚴格的質量門禁，不會讓不達標的程式碼輕易通過。不過它依賴多個外部 AI 工具（codex、gemini 等），配置起來有點門檻，部分功能可能因為工具版本不同而出現相容問題。對普通使用者來說，需要一定的技術基礎才能用好。總體適合有一定開發經驗、想用 AI 協作提升效率的團隊。