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 + 真实验证 + 指标门禁）

详细说明见：

• 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 协作提升效率的团队。