SkillHub

team-dev

v0.1.4

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 Feish...

Sourced from ClawHub, Authored by Vint

Installation

Please help me install the skill `team-dev` from SkillHub official store. npx skills add VintLin/team-dev

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

Agent Use Case Command
Codex 后端逻辑、复杂 bug、多文件重构 codex exec --dangerously-bypass-approvals-and-sandbox -C "/path" "prompt"
Claude Code 前端、git 操作、快速任务 claude --dangerously-skip-permissions -p "prompt"
Gemini UI 设计、生成规范 gemini -p "prompt" 或 gemini -y -p "prompt" (YOLO 模式)
Cursor 前端产品化、IDE 协同、界面 polish；版本前差异分析（plan） cursor agent -f -p --workspace "/path" --model composer-1.5 "prompt"

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>