| name | thread-orchestration |
| description | 大任务的主动拆解与多 thread 并行编排。 Use when: 任务涉及 2+ 个独立可交付子任务，需要不同猫参与、不同 thread 并行推进。 Not for: 单一任务（直接做）、已有 thread 之间的被动协调（用 cross-thread-sync）、单 session 内 subagent 并行（CLI 内置能力）、发现跨 scope 问题但已有归属 thread（用 cross_post_message，不要新建 thread）。 Output: 子 thread 创建 + 选猫 + 各 thread 交付 + 主 thread 汇聚报告。 GOTCHA: projectPath 是子 thread 的工作区/真相源归属，不是外部目标仓；社区 PR review 目标可以是 clowder-ai，但工作区仍可能应继承 cat-cafe。
|
| triggers | ["拆任务","分 thread","并行推进","开多个 thread","thread orchestration","任务分解"] |
Thread Orchestration — 多 Thread 并行编排
核心理念：一个 thread 对应一个独立可交付的工作单元。主 thread 是指挥部，子 thread 是战场。
何时触发
发现跨 scope 的问题/信息？
→ 先 list_threads keyword=<关键词> 查有没有已有 thread
→ 有已有 thread → 不要新建！用 cross_post_message 投递（cross-thread-sync skill）
→ 没有已有 thread + 需要独立追踪 → 本 skill：propose_thread
任务可以拆成多个独立子任务？
→ 子任务之间有代码依赖？ → 串行（先完成依赖项）
→ 子任务独立？ → 本 skill：开 thread 并行推进
只有一个任务？ → 不需要本 skill，直接做
F128/F193 环（KD-E4）：propose_thread（新建）和 cross_post_message（投递）是一个环。
默认走投递（cross_post_message），只有确认没有已有 thread 时才走新建（propose_thread）。
新建 thread 的阈值高于投递——新建会增加operator的认知负担。
五步流程
Step 1: 拆解 — 识别独立可交付单元
判定标准：两个子任务能否由不同猫在不同 worktree 里同时做？能 → 独立。
拆解时明确每个子任务的：
- Scope: 改哪些文件/模块
- 交付物: 代码 + 测试 + 文档（具体到文件）
- 验收条件: 怎么算完（测试绿 / lint 过 / review 通过）
Step 2: 提议 Thread — 每个子任务一个提议（用户审批后才创建）
重要：cat 不直接创建 thread。 调用 cat_cafe_propose_thread 创建一个提议卡片，等用户在 source thread 里点"批准"，后端才真正创建 thread。
→ cat_cafe_propose_thread(
title: "简洁描述任务目标",
reason: "为什么这个子任务值得自己一个 thread（必填）",
preferredCats: ["执行猫", "review猫"],
projectPath: "/abs/path/to/repo", // 子 thread 的工作区/真相源归属；不是外部目标仓
reportingMode: "final-only" // 可选回报契约: none/final-only(默认)/state-transitions/blocking-ack，见下表
)
返回值：{ proposalId, status: "pending" } —— 不是 threadId。Thread 还未存在，不要尝试 cross_post 到一个尚未批准的 proposal。
命名规则：[优先级/批次] 动词 + 对象
- 例："P1 功能完善：Web UI + Semantic Scholar + API 降级"
- 例："P2 工程质量：CI/CD + Linting"
提议后：继续主 thread 的工作，等用户批准。批准后用户会在新 thread 里出现，此时再 cross_post 给被分配的猫。
projectPath — 项目归属
不传 projectPath = 继承当前/parent thread 的项目。若当前 thread 本身是 default / 未分类 / eval / lobby，而子 thread 要做 repo 或实现工作，必须显式传绝对路径；只有纯 eval/meta/无需项目归属的 thread 才可留空并进入未分类。
先问：子 thread 的工作区真相源在哪？ projectPath 决定新 thread 的 cwd / 归属 project，不等于它要处理的外部 GitHub 仓库、PR 或 issue。例：从 cat-cafe 守门 thread 分发 clowder-ai#NNN 的 review / triage / intake 任务时，GitHub target 是 clowder-ai，但子 thread 的 projectPath 通常应继承或显式使用 cat-cafe，因为家里的 SOP、skills、feature docs、Direction Card 真相源都在这里。
只有当子 thread 明确要在公开仓 checkout 内执行目标仓操作（例如 conflict rebase、public-only hotfix、release target validation），才把 projectPath 设为 clowder-ai，并在 handoff 里写明原因。
reportingMode — 回报契约分型（F128 Phase Y → Phase AA）
决定子 thread 是否/如何回报主 thread。不传 = final-only（做完把结果带回来）。
Phase AA 更新（2026-06-07）：默认从 none 改为 final-only。大多数 propose 是"开一个子 thread 做事，做完把结果带回来"。选择模式前先问自己：这个子 thread 做完后，源 thread 是否需要结果回来？
| Mode | 语义 | 何时用 |
|---|
final-only（默认） | 子 thread 自治，完成时回报一次 summary | Feature work fork / 大多数情况——要最终结果、不要过程噪音 |
none（autonomous，显式 opt-in） | 球权完全释放，子 thread 自治；主 thread 不背回执责任。遇 operator 决策 / 阻塞 / 不可逆 / 跨 feature 冲突仍按家规主动 cross_post | Repo Inbox / PR triage / 分发——踢出去就让下游自闭环 |
state-transitions | 每个 phase boundary（阶段完成 / 重要决策 / 状态切换）回报 | Bug 调查 / Research——主 thread 要跟过程 |
blocking-ack | 子 thread 遇阻塞点（at each blocker，非每步）才等主 thread ack 再继续；持球在子 thread（被阻塞方）自己 hold_ball + 发 [BLOCKING]，主 thread 不背 polling | 等 review / 等 operator / blocking handoff |
场景化选择指南（AC-AA2）：
- 做完后源 thread 需要结果回来？→
final-only（默认，不用填）
- 交给下游自治闭环，源 thread 不需要回来？→
none（显式写 reportingMode: 'none'）
- 需要阶段性状态推送？→
state-transitions
- 遇阻塞必须等源 thread ack？→
blocking-ack
约束：
- mode 是 thread contract，创建后不可动态切换（要换就 propose 新 thread）。
none ≠ 禁止上报——关键事件永远按家规 cross_post。即使 none 下主动上报也必须携带 targetCats 或行首 @sourceHandle，避免消息存了但没人醒。#ideate（并行 wake-all）与 reportingMode 正交：#ideate 只决定并行 vs 串行接龙；report-back owner 由 reportingMode 决定。#ideate + none 不指定汇总 owner；#ideate + final-only/state-transitions 才指定第一棒为汇总 owner。- 下面 Step 5「汇聚」铁律默认针对需回报的 mode（
final-only / state-transitions / blocking-ack）；none 模式下子 thread 自闭环，不走 Step 5 强制回报。
- 回报时路由必须包含 routing credentials：server 会自动注入
threadId + targetCats/@sourceHandle 到首条消息 header（AC-AA6），照着发即可。
Step 3: 选猫 — 按任务性质匹配能力
| 任务性质 | 适合的猫 | 理由 |
|---|
| 代码实现 | 架构猫（自己）或快速编码猫 | 产出代码 |
| 代码 Review | Maine Coon系（审查专长） | 跨家族 review |
| UI/体验/文案 | Siamese系（审美专长） | 设计视角 |
| 架构决策 | Ragdoll Opus 4.5 / Maine Coon GPT | 深度思考 |
| 确定性执行 | 狸花猫 | 零信任验证 |
铁律：同一子任务的实现和 review 不能是同一只猫（no self-review）。
用户批准 proposal 后，新 thread 出现在 sidebar。此时在新 thread 里发任务描述 + 分工提议。必须包含主 thread ID，这是子 thread 识别归属的唯一可靠来源：
→ cat_cafe_cross_post_message(
threadId: "<sub_thread_id>",
content: "## 主 Thread\nID: <main_thread_id>\n标题: <main_thread_title>\n\n## 任务描述\n...\n## 分工提议\n...\n@codex 请确认"
)
回报要求按 reportingMode：final-only（默认）/ state-transitions / blocking-ack 下 server enrich 会自动注入对应的 report-back 规则 + 路由凭证（threadId + @handle）进首条消息，无需手写"完成后请回报"；none（autonomous/opt-in）则不要写强制回报指令——下游自闭环。
铁律：每个子 thread 的第一条消息必须包含 ## 主 Thread header（定位父 thread 用）。是否要求回报由 reportingMode 决定，不再无条件汇报。
Step 4: 并行执行 — Worktree 隔离
每个 thread 的代码改动应使用独立 worktree，避免文件冲突。
thread 内的执行遵循已有 skill：
- 写代码 →
tdd
- 完成后自检 →
quality-gate
- 请 review →
request-review + cross-cat-handoff（五件套）
- 收到反馈 →
receive-review
加速手段：thread 内可用 CLI 内置的 subagent 并行模式加速实现，但 review 必须由其他猫完成。
Step 5: 汇聚 — 确认门禁 + 串行推进（仅需回报 mode）
前提：Step 5 适用于 final-only / state-transitions / blocking-ack。none（autonomous，显式 opt-in）下子 thread 自闭环——不通知、不等确认、自主 commit，跳过整个 Step 5。
铁律（需回报 mode）：子 thread 达到里程碑时，必须立刻通知主 thread 并等待确认。
5a: 待 commit — 通知主 thread 等确认
子 thread 完成开发 + 自检后，不要直接 commit，而是：
→ cat_cafe_cross_post_message(
threadId: "<main_thread_id>", ← 从首条消息的 ## 主 Thread → 路由目标 获取
targetCats: ["<source_cat_id>"], ← 唤醒源猫（或 content 行首 @sourceHandle）
content: "@sourceHandle ## [子任务名] — 待确认 commit\n\n| 子项 | 状态 | 关键产出 |\n|------|------|---------|\n| ... | ✅ | 一句话 |\n\n验证：测试 X/X pass, lint 0 errors\n请确认是否 commit + push"
)
等主 thread 确认后再 commit。 主 thread 可能会要求修改后再 commit。
5b: 确认后 — 串行触发
如果有串行依赖（B 依赖 A），主 thread 确认 A commit 后：
- A commit + push（或 merge 到 main）
- 主 thread 通知 B 的子 thread："A 已合入，可以开始"
- B 从 main 拉取 A 的改动后开工
A 完成 → 通知主 thread → 确认 commit → A merge
↓
主 thread 通知 B → B 拉 main → B 开工
5c: 全部完成 — 汇总报告
所有子 thread 完成后，主 thread 汇总：
## 编排汇总
| 子 Thread | 任务 | 状态 | PR |
|-----------|------|------|----|
| thread-xxx | ... | ✅ merged | #xx |
| thread-yyy | ... | ✅ merged | #yy |
下一步：[无 / 集成测试 / 部署]
不要让 team lead 自己去子 thread 查进度。
依赖管理
| 场景 | 处理 |
|---|
| 子任务完全独立 | 并行，各自 worktree |
| B 依赖 A 的产出 | A 先做，A merge 到 main 后 B 从 main 拉 |
| A 和 B 改同一文件 | 不要并行！串行处理，或重新拆分 scope |
| 多个 thread 都要改共享状态 | 走 cross-thread-sync 的 Claim 协议 |
Quick Reference
拆解 → 提议 thread → 等用户批准 → 选猫(含主 Thread ID) → 并行执行 → 待 commit 通知 → 确认 → 串行触发 → 汇总
主 thread = 指挥部（拆 + 提议 + 确认 + 收）
子 thread = 战场（做 + review；等确认仅需回报 mode）— 仅在用户批准 proposal 后存在
Proposal = 卡片（cat 提议 → 用户审核/编辑/批准 → 后端创建 thread）
第一条消息 = 必须含 ## 主 Thread（ID + 标题）
reportingMode = 回报契约（final-only 默认 / none 自闭环 / state-transitions / blocking-ack）
projectPath = 项目归属（default parent 发 repo/实现子任务时必填；不传=继承 parent）
Worktree = 隔离（不冲突）
汇报 = 按 reportingMode（none 自闭环不回报；需回报 mode 才及时 + 等确认，不让 team lead 追也不越权 commit）
Common Mistakes
| 错误 | 后果 | 修法 |
|---|
| 在主 thread 里直接改代码 | 子 thread 看不到过程，审计困难 | 代码改动必须在子 thread + worktree |
| 需回报 mode 下子 thread 完成不通知主 thread | team lead 要自己查 | final-only/state-transitions 完成/阻塞时 cross-post 回主 thread；none 自闭环不适用 |
| 多 thread 在同一 worktree 改代码 | 文件冲突 | 每个 thread 用独立 worktree |
| 只拉同家族猫 | 缺少多元视角 | 按任务性质跨家族选猫 |
| 拆得太细（1 个小文件 = 1 个 thread） | 编排开销 > 收益 | 相关小任务合并到同一 thread |
| 忘记在子 thread 发任务描述 | 被拉的猫不知道干啥 | 建 thread 后立刻发 scope + 分工 |
| 子 thread 第一条消息没写主 Thread ID | 猫汇报到错误的 thread | 第一条消息必须含 ## 主 Thread header |
| 需回报 mode 下完成直接 commit 不等确认 | team lead 失去控制权 | final-only/state-transitions 待 commit 通知主 thread 等确认；none 自主 commit |
| 把 propose 返回的 proposalId 当成 threadId 用 | cross_post 到不存在的 thread | propose 不创建 thread，只有 user 批准后才有 threadId。等批准事件再发首条消息 |
| 提议一个 proposal 后立刻假设 thread 存在 | 后续操作全失败 | 必须等用户在 proposal 卡片上点"批准"。批准前继续主 thread 工作 |
把 projectPath 当成外部目标仓，给社区 PR review thread 填 clowder-ai | 子 thread 进入错误 workspace，家里 SOP/skills/feature docs 不在工作区，球路污染 | projectPath 填工作区真相源；clowder-ai#NNN 放在标题/正文/gh 命令里，只有明确目标仓 checkout 操作才填 clowder-ai |
和其他 Skill 的区别
| Skill | 层级 | 方向 | 核心区别 |
|---|
| thread-orchestration | 跨 thread | 主动拆解 → 分发 → 汇聚 | 全生命周期编排；先确认没有已有 thread 再新建 |
| CLI subagent 并行 | session 内 | subagent 并行（CLI 内置） | 不涉及 thread、不涉及其他猫 |
cross-thread-sync | 跨 thread | 被动发现 → 通知 → 协调 | 响应式，不主动建 thread；发现跨 scope 问题的默认路径 |
cross-cat-handoff | 猫对猫 | 一次性交接 | 点对点，不涉及多 thread 编排 |
F128/F193 环决策（KD-E4）：发现跨 scope 问题 → list_threads 查已有 thread → 有 → cross-thread-sync（投递） / 没有 → thread-orchestration（新建）。默认投递，新建阈值更高。
下一步
- 子 thread 内写代码 →
worktree → tdd
- 子 thread 完成自检 →
quality-gate
- 子 thread 请 review →
request-review
- 子 thread merge →
merge-gate
- 子 thread 之间有冲突 →
cross-thread-sync
