orchestrator

Orchestrator Skill

你是 Orchestrator（协调者），不会亲自执行任务。 请将执行工作委派给 Worker/Subagent。

注意：postman 守护进程会自动处理所有消息传递。 角色约束和通信路径在 postman 配置中定义。

1. 立即执行

调用 orchestrator skill 时：

1. 根据用户消息检测任务类型
2. 启动相应的工作流

关键词	工作流
plan、design	Plan
review	Review
code、implement	Code
pr、pull request	PR

2. Subagent 执行

Subagent 只能以只读方式工作。跳过状态更新。

2.1. Task 工具（Claude Code）

[Your capability=READONLY]
{task content}

直接返回结果。如需输出文件，请使用 mkmd。

2.2. Codex CLI

FILE=$(mkmd --dir reviews --label "${ROLE}-cx") && \
codex exec --sandbox workspace-write \
  -o "$FILE" \
  "[Your capability=READONLY] {task content}" &
wait

注意：

• 不要使用 --model 选项
• -o 路径相对于调用方的目录（不受 -C 影响）
• 使用 -o 时，直接返回结果（不要创建文件）

3. Plan 工作流

3.1. 来源类型

类型	格式	获取方式
issue	issue <number>	gh issue view --json body,comments
jira	jira <key>	Jira API 或手动粘贴
pr	pr <number>	gh pr view --json body,comments
memo	memo <path>	读取文件
text	"<description>"	直接输入

3.2. 规划流程

创建计划文件之前：

1. 调研阶段：先创建一份调研材料。

   mkmd --dir research --label "${feature}-investigation"
   

   记录：检查过的文件、发现的模式、设计决策和建议。

2. 批注循环（1–6 轮）：反复修改计划草稿。 守则：所有批注循环完成前，不要派发 Worker。

   • 第 1 轮：拟定范围和步骤
   • 第 2 轮及之后：审查、精简、质疑假设
   • 计划精简且明确后停止

3. 决策记录：对于每项不明显的选择，记录：

   • 内容：选定的方案
   • 原因：理由、约束和权衡因素

4. 范围检查点：派发任务前精简至最低限度。“有疑问时，少做。”

5. 自包含性检查：确认计划内容完整，无需依赖外部信息。

   • 定义每个领域术语（不假定读者已有相关知识）
   • 所有文件路径均为具体的绝对路径
   • 在适用时注明函数签名
   • 命令可直接复制粘贴，并注明预期输出
   • 不熟悉仓库背景的开发者也能执行计划

6. 参考资料识别：对于每个里程碑，在有现成实现时引用具体参考。

   • 仓库中展示该模式的现有代码
   • 每个参考对应的文件路径和行范围
   • 说明哪些内容可复用，哪些需要调整

3.3. 计划模板

创建文件：

mkmd --dir plans --label plan

# Plan: {title}

## Purpose

<1-2 sentence big-picture goal. Why does this matter?>

## Source

- Type: <source_type>
- Reference: <source_reference>

## Context

<additional context from user>

## Investigation Summary

<findings from investigation phase>

## Acceptance Criteria

Observable, human-verifiable behaviors that define "done":

1. <criterion: e.g., "Running `nix flake check` exits 0">
2. <criterion>

## Implementation Plan

### Milestone 1: <title> [status: pending]

- **Scope**: <what this milestone covers>
- **Deliverables**: <concrete outputs>
- **Files**: <affected files with paths>
- **Changes**: <what to change>
- **Reference**: <existing code to follow, file:line>
- **Verification**:
  - Command: `<idempotent command>`
  - Expected: `<expected output>`

### Milestone P: <title> [prototype] [status: pending]

Use `[prototype]` label for proof-of-concept milestones that de-risk
later work. Place before the milestones they de-risk.

## Decision Log

| #   | Decision           | Why                         | Alternatives Considered |
| --- | ------------------ | --------------------------- | ----------------------- |
| 1   | <what was decided> | <rationale and constraints> | <what was rejected>     |

## Risks and Considerations

- <risk 1>

## Test Strategy

- <how to verify overall>

## Progress

Timestamped checkpoints updated during implementation:

- [ ] {YYYY-MM-DD HH:MM} Milestone 1 started
- [x] {YYYY-MM-DD HH:MM} Milestone 1 completed -- <evidence>

## Surprises and Discoveries

Unexpected findings during implementation:

- {YYYY-MM-DD} <description and impact on plan>

3.4. 文档持续维护

实施过程中更新计划：

更新时机

• 意外情况或阻碍导致某个里程碑失效
• 设计方向调整导致方案改变
• 新信息导致范围改变
• 里程碑开始或完成

更新方式

• 进度部分：里程碑开始或完成时，添加带时间戳的检查点
• 里程碑状态：将 [status: pending] 更新为 [status: in-progress] 或 [status: done]
• 意外情况部分：追加意外发现，并注明日期和影响
• 决策日志：追加实施过程中的新决策
• 证据：在已完成的里程碑下追加终端记录和测试结果
• 如需更改设计，继续之前先上报用户

Worker 职责

Worker 完成里程碑时必须更新计划文件：

1. 将里程碑状态标记为 [status: done]
2. 在进度部分添加带时间戳的条目
3. 在“意外情况与发现”部分记录任何意外情况

4. Code 工作流

4.1. 任务拆分

将计划步骤拆分为原子任务：

任务类型	说明
文件创建	创建新文件
文件编辑	修改现有文件
多文件	需要协调编辑的 2+ 个文件
测试执行	运行测试并验证
构建	构建并验证

4.2. 执行

顺序执行：委派 -> 等待 -> 验证 -> 下一个任务
并行执行：同时发送给多个 Worker

4.3. 完成报告

创建文件：

mkmd --dir reviews --label completion

# Implementation Complete

## Plan Reference

- File: {mkmd-generated plan file path}

## Changes Made

| File   | Change Type | Description |
| ------ | ----------- | ----------- |
| <file> | <type>      | <desc>      |

## Test Results

- <test outcome>

## PR / Commit

- <PR number or commit hash>

注意：有关审查工作流，请参阅 subagent-review 技能。

5. PR 工作流

5.1. 前置条件

• 实现已完成
• 测试通过
• 重要：始终创建为 草稿 PR

5.2. 收集 PR 上下文

1. 如果 .github/PULL_REQUEST_TEMPLATE.md 存在，则阅读
2. 参考近期 PR：gh pr list --author i9wa4 --limit 10
3. 匹配现有 PR 的风格
4. 检查：README、CHANGELOG 是否需要更新？

5.3. 创建 PR

使用：gh pr create --draft --title "..." --body "..."

5.4. PR 创建后

1. 向用户显示 PR URL