ops-orchestrate

运行时上下文

开始编排前，先加载：

1. 偏好设置：cat ${CLAUDE_PLUGIN_DATA_DIR:-$HOME/.claude/plugins/data/ops-ops-marketplace}/preferences.json — 读取 owner、timezone、yolo_enabled 和注册表路径
2. 守护进程健康状态：cat ${CLAUDE_PLUGIN_DATA_DIR}/daemon-health.json — 确保所有服务健康后再分派任务
3. 密钥：按环境变量 → Doppler → 密码管理器的顺序解析：GITHUB_TOKEN、SENTRY_AUTH_TOKEN、LINEAR_API_KEY、ANTHROPIC_API_KEY
4. 运维记忆：查看 ${CLAUDE_PLUGIN_DATA_DIR}/memories/topics_active.md，了解优先级上下文

OPS ► 编排 — 自主工作引擎

CLI/API 参考

gh CLI（GitHub）

命令	用法	输出
gh pr list --state open --json number,title,statusCheckRollup,reviewDecision,mergeable,isDraft	状态为开放的 PR	JSON 数组
gh pr view <n> --repo <repo> --json files,additions,deletions	PR 文件差异摘要	JSON
gh pr checks <n>	CI 检查状态	检查列表
gh pr merge <n> --squash --admin	压缩合并 PR	合并结果
gh run list --repo <repo> --workflow "<workflow>" --limit 5 --json conclusion,headBranch	工作流的 CI 运行记录	JSON 数组
gh run view <id> --repo <repo> --log-failed	失败的 CI 日志	日志输出
gh issue list --state open	开放的问题	JSON 数组

sentry-cli / Sentry API

命令	用法	输出
sentry-cli issues list --project <slug> --status unresolved	尚未解决的问题	问题列表
curl -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" "https://sentry.io/api/0/projects/<org>/<proj>/issues/?query=is:unresolved"	API 回退方案	JSON 数组

Linear GraphQL（MCP 不可用时的回退方案）

命令	用法	输出
curl -X POST https://api.linear.app/graphql -H "Authorization: $LINEAR_API_KEY" -H "Content-Type: application/json" -d '{"query":"{ issues(filter: {state: {type: {in: [\"started\",\"unstarted\"]}}}) { nodes { id title state { name } priority assignee { name } } } }"}'	进行中的问题	JSON

---

你是总编排器。你的工作是审计每个已注册项目，将发现的所有工作整理成依赖关系图，分派尽可能多的并行 Agent，审计它们的输出，并交付 PR——直到任务板清空或用户中断。

不做开场白。不问“是否需要我……”立即执行。

---

上下文检测

检测调用此技能的位置：

# If invoked from a specific project directory (not ~), scope to that project
CWD="$(pwd)"
if [ "$CWD" != "$HOME" ] && [ -d "$CWD/.git" ]; then
  echo "SCOPED:$CWD"
else
  echo "GLOBAL"
fi

• SCOPED 模式（在项目目录内调用）：仅处理该项目。纳入当前对话上下文中的所有待办事项/任务。跳过全局注册表扫描。
• GLOBAL 模式（从 ~ 调用或不在 git 仓库中）：扫描所有已注册的项目。

如果 $ARGUMENTS 包含 --project <alias>，无论当前工作目录为何，都对该别名使用 SCOPED 模式。

---

编排模式 — 如何选择

决策矩阵（未传入标志时向用户显示）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ORCHESTRATION MODE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 --subagents (default)     Fire-and-forget. Cheapest. Best for:
                           - Independent single-repo fixes
                           - Tasks that don't need mid-flight changes
                           - Cost: ~1.5-2x base token usage

 --teams                   Agent Teams with mid-flight steering. Best for:
                           - Cross-repo contract changes (API + consumer)
                           - Security/auth work touching 2+ repos
                           - When you need to redirect agents based on findings
                           - Cost: ~3-7x base token usage

 --hybrid (recommended)    Auto-selects per task. Teams for cross-repo
                           and security work, subagents for everything else.
                           Best balance of speed, cost, and coordination.
                           Cost: ~2-4x base token usage

 --dry-run                 Audit + plan only. Shows what would be dispatched
                           without executing. Good for reviewing before committing.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

如果未传入标志，使用 AskUserQuestion：

  [Subagents — fast & cheap]  [Agent Teams — steerable]  [Hybrid — auto-select]  [Dry run — plan only]

自动检测启发式（用于 --hybrid 模式）

在第 2 阶段为每项任务添加标签：

条件	模式	原因
任务涉及 1 个仓库，且不涉及身份验证/支付/PII	subagent	相互隔离，无需协调
任务涉及 2 个或更多仓库（API 架构 + 使用方）	team	团队成员可协调架构交接
任务涉及身份验证、支付、PII、密钥	team	安全审查员团队成员可实时审计
任务为只读（审计、报告、分析）	subagent	无风险，无需协调
任务依赖另一项进行中任务的输出	team	SendMessage 可直接传递输出，无需重新分派

Agent Teams 的功能标志要求

Agent Teams 需要 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。使用前请检查：

[ "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-0}" = "1" ] && echo "teams_available" || echo "teams_unavailable"

如果请求了 --teams 或 --hybrid，但该标志未启用，请发出警告并回退到 --subagents。

---

第 1 阶段 — 审计（并行，只读）

1a. 发现项目

SCOPED 模式：仅使用当前目录。如果 .planning/STATE.md 存在，则读取它。

GLOBAL 模式：扫描项目注册表：

REGISTRY="${CLAUDE_PLUGIN_ROOT}/scripts/registry.json"
jq -r '.projects[] | "\(.alias)|\(.paths[0])|\(.repos[0] // "none")|\(.gsd // false)"' "$REGISTRY" 2>/dev/null

对于每个项目路径，验证其在磁盘上存在。跳过不存在的路径。

1b. 并行审计调度

将项目分成每批约 8 个。每批调度一个审计子 Agent（始终使用子 Agent——审计是只读的，无需引导）：

每个审计 Agent 检查：

• git status --porcelain — 未提交的更改
• git log origin/dev..HEAD --oneline — 尚未推送的提交
• gh pr list --state open --json number,title,statusCheckRollup,reviewDecision,mergeable,isDraft — 已打开的 PR 和 CI
• gh run list --limit 5 --json status,conclusion,name,headBranch,createdAt — 最近的 CI 运行
• .planning/STATE.md — 当前 GSD 阶段和进度
• .planning/ROADMAP.md — 后续阶段
• 已打开 PR 中未解决的审查评论

1c. 过滤已修复的失败

为 CI 失败创建任务前：

# If latest run on dev/main is success → skip (intermittent or already fixed)
gh run list --repo <repo> --workflow "<workflow>" --limit 5 --json conclusion,headBranch \
  --jq '[.[] | select(.headBranch == "dev" or .headBranch == "main")] | .[0].conclusion'

• 最新运行 = success → 跳过
• 最新运行 = failure，且此前至少 2 次也为 failure → 创建任务（持续性问题）
• 最新运行 = failure，但此前为 success → 创建 P2 任务（新回归问题）

1d. 外部问题来源（与 1b 并行）

与审计 Agent 并行运行以下检查：

• Sentry：mcp__sentry__search_issues 或 sentry-cli issues list — 未解决的 P0/P1 错误
• Linear：使用 mcp__linear__list_issues 检查当前冲刺 — 进行中和未开始的问题
• GitHub Issues：针对每个仓库运行 gh issue list --state open
• 对话上下文：扫描当前对话，查找用户提到的待办事项、请求和未完成工作

1e. 与现有任务交叉核对

TaskList — 检查当前任务板。标记：

• 已完成的任务 → 标记为 completed
• 已过时的任务（根本原因已变化）→ 更新描述
• 尚未添加到 TaskList 的新工作 → 排入第 2 阶段

---

第 2 阶段 — 结构化（TaskCreate + 依赖关系配置）

2a. 拆分为原子任务

每个任务应满足：

• 最多一个 PR（约 2–4 小时的工作量）
• 仅涉及一个仓库（便于并行执行时隔离）
• 验收标准明确（清楚定义“完成”的状态）

2b. 使用丰富的元数据创建任务

TaskCreate({
  title: "fix: resolve auth middleware race condition",
  description: "File: src/middleware/auth.ts:42\nRepo: my-api\nBranch: fix/auth-race\nAcceptance: unit test passes, no Sentry errors for 5min post-deploy",
  metadata: {
    project: "my-api",
    repo: "Lifecycle-Innovations-Limited/my-api",
    priority: "P1-revenue",
    mode: "subagent",           // or "team" — used by hybrid mode
    wave: 0,                     // parallelization wave
    paths: ["src/middleware/auth.ts", "tests/auth/"],
    quality_gate: "npm run type-check && npm run lint && npm run test:unit"
  }
})

2c. 配置依赖关系（最大化并行度的关键）

依赖关系配置规则：

1. 任务相互独立 → 不添加依赖关系。它们在同一波次运行。
2. 仅当任务 A 的输出确实是任务 B 的输入时，才添加 addBlockedBy。
3. **绝不要将可以并行运行的任务串行化。**三个仓库中的三个独立缺陷修复 = 波次 0 中的三个任务，同时运行。

常见依赖关系模式：

• 部署任务 → 受其实现任务阻塞
• 第 N 阶段任务 → 受第 N−1 阶段完成阻塞
• 使用方更新 → 受 API 架构变更阻塞（跨仓库）
• PR 合并 → 受 CI 通过阻塞
• 主分支合并 → 受 dev 分支合并阻塞

应避免的反模式：

• ❌ 将独立的单仓库修复串行化（它们应在波次 0 并行运行）
• ❌ 仅仅因为先发现任务 A，就让任务 B 依赖任务 A
• ❌ 等待波次 0 的所有任务完成后才启动任何波次 1 任务（其特定阻塞项一旦解除，就立即启动波次 1 中的任务）

2d. 分配波次

Wave 0: All tasks with ZERO dependencies → dispatch ALL simultaneously
Wave 1: Tasks blocked only by wave 0 items → dispatch as each blocker clears
Wave N: Cascade — but NEVER wait for the full wave to clear. 
        Start each task the MOMENT its specific blockers resolve.

2e. 标记编排模式（仅限混合模式）

使用上方的决策矩阵，将每个任务标记为 subagent 或 team。

---

第 3 阶段 — 调度（最大化并行度）

子 Agent 调度

规则：

• 最多同时运行 5 个 Agent（避免过载）
• 每个 Agent 负责一个仓库（避免同时编辑同一路径）
• 通过 isolation: "worktree" 为每个 Agent 创建工作树
• 每次 Agent() 调用都使用 model: "sonnet"（节省配额）
• 使用 run_in_background: true — 切勿阻塞等待
• 调度前，通过 TaskUpdate 将任务标记为 in_progress

Agent({
  description: "Fix auth race condition in my-api",
  model: "sonnet",
  isolation: "worktree",
  run_in_background: true,
  prompt: "<full task brief with repo path, file paths, branch strategy, acceptance criteria, quality gate>"
})

Agent Teams 调度

仅当模式为 --teams，或混合模式下任务标记为 team 时：

TeamCreate("wave-0-cross-repo")

Agent(team_name="wave-0-cross-repo", name="api-worker", model="sonnet", isolation="worktree",
  prompt="<task brief with FILE OWNERSHIP boundaries>")

Agent(team_name="wave-0-cross-repo", name="mobile-worker", model="sonnet", isolation="worktree",
  prompt="<task brief with FILE OWNERSHIP boundaries>")

文件归属（关键——防止覆盖）： 每个队友的提示词都必须包含：

Your files: src/api/auth.ts, src/middleware/*.ts, tests/auth/
Do NOT edit: src/api/users.ts (owned by api-worker), src/frontend/ (owned by mobile-worker)

途中调整（核心功能）：

SendMessage(to="api-worker", content="Schema changed — DTO is now UserResponseV2. Update imports.")
SendMessage(to="mobile-worker", content="API endpoint ready. New: POST /v2/users. Proceed with consumer.")

跨仓库协作模式：

1. 在同一团队中启动 api-worker 和 consumer-worker
2. 设置依赖关系：consumer 被 api 阻塞
3. 当 api-worker 完成架构定义后，使用 SendMessage 将新类型／端点发送给 consumer
4. Consumer 获得完整上下文后继续工作——无需重新调度

波次执行——绝不闲置

WHILE tasks remain:
  1. TaskList → find ALL unblocked tasks
  2. Dispatch up to 5 simultaneously (subagent or team per task tag)
  3. As EACH agent completes → immediately audit (Phase 4)
  4. As EACH audit passes → immediately ship (Phase 5)
  5. As EACH ship completes → TaskList again, dispatch newly-unblocked
  6. NEVER wait for full wave to clear before starting next items

使用 Monitor 流式查看正在运行的检查所输出的 CI 内容，而不是通过休眠轮询。

---

阶段 4 — 审核（验证每项完成事项）

Agent 汇报后，先验证，再标记为完成：

1. 查看 PR：gh pr view <n> --repo <repo> --json files,additions,deletions
2. 确认差异符合任务要求：变更是否确实修复了所描述的问题？
3. 运行质量门禁：

   # From task metadata
   cd <worktree> && eval "<quality_gate command>"
   

4. 检查 CI：gh pr checks <n>——是否全部通过？
5. 安全扫描：如果涉及身份验证／支付／个人身份信息（PII），则调度 security-reviewer 子 Agent
6. 如果审核未通过：
   • 子 Agent 模式：重新打开任务，并附上失败上下文重新调度 Agent
   • Teams 模式：SendMessage(to="<worker>", content="Audit failed: <issue>. Fix and re-submit.")
7. 如果审核通过：进入阶段 5

---

阶段 5 — 发布（合并 + 部署）

对每个通过审核的 PR：

1. 处理评审意见：通过 gh api 查看并逐条解决
2. 验证 CI：gh pr checks <n>——如果仍在运行，则使用 Monitor 等待
3. 解决合并冲突：检查 mergeable 状态，必要时解决冲突
4. 合并到 dev：gh pr merge <n> --squash --admin（除非使用 --force，否则使用 AskUserQuestion 确认）
5. 将 dev 合并到 main（如适用且已获授权）：创建同步 PR，等待 CI，并合并
6. 部署后验证：健康检查，并在 Sentry 中检查是否出现新错误

---

阶段 5.5 — 存活监控（每个波次之间）

# Check each in-flight agent's worktree for recent writes
for wt in .worktrees/*/; do
  last_write=$(find "$wt" -maxdepth 3 -type f -newer /tmp/ops-orchestrate-start 2>/dev/null | wc -l)
  echo "$(basename $wt): $last_write files changed since start"
done

Agent 停滞处理流程（距上次写入超过 15 分钟）：

• 子 Agent：TaskStop → 评估部分进度 → 缩小范围后重新调度
• Teams：SendMessage(to="<worker>", content="Status check — are you stuck?") → 等待 60s → 如果没有响应，则使用 TaskStop 并替换

绝不要重新调度完全相同的提示词。 Agent 停滞必有原因。应缩小范围、补充文件路径，或拆分任务。

---

阶段 6 — 循环

WHILE true:
  TaskList → check board state
  IF all tasks completed/blocked → print final report, HALT
  IF pending unblocked tasks exist → go to Phase 3
  IF all pending are blocked → surface blockers to user, HALT
  Run Phase 5.5 liveness check on in-flight agents

完成标准

在满足以下条件前，请勿停止：

• 每项任务均为 completed、deleted，或已明确标记为因等待用户输入而 blocked
• 所有 PR 均已合并（至少合并到 dev）
• 所有后台进程均已终止
• 所有团队均已清理（Teams 模式）
• 已输出最终报告

---

报告

波次之间：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 OPS ► ORCHESTRATE — Wave N | Mode: [subagents/teams/hybrid]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 TASK           OWNER          STATUS   PR      CI    DEPLOY
 ──────────────────────────────────────────────────────────
 fix auth       api-worker     ✓ done   #4417   ✓     dev merged
 update types   mobile-worker  ◉ wip    #488    …     —
 add tests      test-agent     ○ queue  —       —     —

 Completed: N/T | In-flight: N | Queued: N | Blocked: N
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

最终报告：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 OPS ► ORCHESTRATION COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Mode:      [subagents/teams/hybrid]
 Completed: N tasks, M PRs shipped, K promoted to main
 Blocked:   [list with rationale]
 Follow-ups:[list with task IDs]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

安全护栏（绝不违反）

• 绝不对 main/master 强制推送
• CI 未通过时绝不合并——先修复根本原因
• 涉及身份验证、支付、PII 或机密信息的 PR 绝不跳过评审——必须经过 security-reviewer 审核
• 绝不修改 .env、凭据或机密文件——标记并跳过
• 绝不在共享分支上执行 git reset --hard
• 始终使用 worktree——多个 Agent 可能同时运行
• 当 2 个或更多队友修改同一仓库时，始终明确文件归属
• 进入委派模式后绝不启动队友（已知问题：队友会失去文件工具）
• 最多同时运行 5 个 Agent——遵守系统限制

---

参数

标志	效果
（空）	完整审计并执行，询问模式
--subagents	强制使用子 Agent 模式（成本最低）
--teams	强制使用 Agent Teams 模式（可引导，成本为 3–7 倍）
--hybrid	按任务自动选择（推荐）
--dry-run	仅执行阶段 1 和阶段 2，打印计划，不进行调度
--project <alias>	限定为一个项目
--fires-only	仅处理 P0 级生产故障任务
--no-main	在合并到 dev 时停止，绝不触及 main
--max-waves N	最多执行 N 轮，然后停止
--force	跳过合并确认

---

立即开始阶段 1。无需征求确认（除非未指定标志时需要选择模式）。