synthesize

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Synthesis Skill

合成技能

VCS Provider

版本控制系统（VCS）提供商

This skill uses VCS operations through Exarchos MCP actions (

create_pr

merge_pr

list_prs

check_ci

, etc.). These actions automatically detect and route to the correct VCS provider (GitHub, GitLab, Azure DevOps). No

gh

glab

az

commands needed — the MCP server handles provider dispatch.

Not to be confused with the integration merge. This skill calls
merge_pr
to land a user-facing PR on
main
via the VCS provider — a remote operation. The upstream sibling is
serialize_merge
(
@skills/merge-orchestrator/SKILL.md
): the integration-merge path that holds a single-writer lease and composes a local
git merge
of a subagent worktree branch onto the integration branch during the
delegate → merge-pending → delegate
HSM loop (raw
merge_orchestrate
is that composed executor / the non-integration path). Synthesize never invokes
serialize_merge
or
merge_orchestrate
; merge-pending never invokes
merge_pr
.

本技能通过Exarchos MCP操作（

create_pr

、

merge_pr

、

list_prs

、

check_ci

等）执行VCS操作。这些操作会自动检测并路由到正确的VCS提供商（GitHub、GitLab、Azure DevOps）。无需使用

gh

glab

az

命令——MCP服务器会处理提供商调度。

请勿与集成合并混淆。 本技能调用
merge_pr
通过VCS提供商将面向用户的PR合并到
main
分支——这是一项远程操作。对应的上游技能是
serialize_merge
（
@skills/merge-orchestrator/SKILL.md
）：集成合并路径在
delegate → merge-pending → delegate
的HSM循环中持有单写入者租约，并将子代理工作树分支本地
git merge
到集成分支（原生
merge_orchestrate
是该组合执行器/非集成路径）。合成技能绝不会调用
serialize_merge
或
merge_orchestrate
；merge-pending阶段绝不会调用
merge_pr
。

Overview

概述

Submit stacked PRs after review phase completes. The

prepare_synthesis

composite action consolidates readiness checks, stack verification, test validation, and quality signal analysis into a single call -- eliminating the multi-script coordination that historically caused synthesis failures.

Prerequisites:

All delegated tasks complete with reviews passed (spec + quality)
The integration branch already exists from delegation phase
Task branches present and pushed to remote

Do NOT proceed if either review is incomplete or failed -- return to

review

first.

Entry points: Synthesis is normally reached from the

review

phase of feature / debug / refactor workflows. It is also reachable from

oneshot

workflows via the opt-in path — when a user signals "let's open a PR for this" during

plan

implementing

, the

request_synthesize

event is appended, and

finalize_oneshot

then resolves the choice state and transitions the workflow to

synthesize

. See

@skills/oneshot/SKILL.md

for the opt-in mechanics and

synthesisPolicy

semantics.

在评审阶段完成后提交堆叠PR。

prepare_synthesis

复合操作将就绪检查、堆叠验证、测试验证和质量信号分析整合为一次调用——消除了过去导致合成失败的多脚本协调问题。

前提条件：

所有委托任务均已完成且评审通过（规格+质量）
集成分支已在委托阶段创建
任务分支已存在并推送到远程仓库

如果评审未完成或失败，请勿继续——先回到

review

阶段。

入口点： 合成阶段通常从功能/调试/重构工作流的

review

阶段进入。也可通过选择路径从

oneshot

工作流进入——当用户在

plan

或

implementing

阶段表示“为这个创建PR”时，会追加

request_synthesize

事件，

finalize_oneshot

会解析选择状态并将工作流转换到

synthesize

阶段。有关选择机制和

synthesisPolicy

语义，请参阅

@skills/oneshot/SKILL.md

。

Triggers

触发条件

Activate this skill when:

User runs
```
synthesize
```
command
All reviews have passed successfully
Ready to submit PRs
Oneshot workflow resolved to
```
synthesize
```
via
```
finalize_oneshot
```

满足以下条件时激活本技能：

用户运行
```
synthesize
```
命令
所有评审已成功通过
准备好提交PR
一次性工作流通过
```
finalize_oneshot
```
解析为
```
synthesize
```
阶段

Process

流程

Runbook: Follow the synthesis-flow runbook:
exarchos_orchestrate({ action: "runbook", id: "synthesis-flow" })
If runbook unavailable, use
describe
to retrieve action schemas:
exarchos_orchestrate({ action: "describe", actions: ["prepare_synthesis"] })

运行手册： 遵循合成流程运行手册：
exarchos_orchestrate({ action: "runbook", id: "synthesis-flow" })
如果运行手册不可用，使用
describe
获取操作 schema：
exarchos_orchestrate({ action: "describe", actions: ["prepare_synthesis"] })

Step 1: Verify Readiness

步骤1：验证就绪状态

Call the

prepare_synthesis

composite action to validate all preconditions in a single operation:

typescript

exarchos:exarchos_orchestrate({
  action: "prepare_synthesis",
  featureId: "<id>"
})

This action performs:

Phase readiness -- Confirms workflow is in the correct phase with all reviews complete
Stack integrity -- Detects diverged branches, missing task branches, or broken parent chains and reconstructs automatically
Test verification -- Runs
```
npm run test:run && npm run typecheck
```
from the stack top
Benchmark regression -- If
```
state.verification.hasBenchmarks
```
is true, checks for performance regressions
Quality signals -- Queries
```
code_quality
```
view for regressions and actionable hints
Document readiness -- Touched doc-surfaces must carry corresponding doc updates (auto-waives when no doc surface is touched)
Gate events -- Auto-emits
```
gate.executed
```
events for each check (tests, benchmarks, CodeRabbit)

For the full breakdown of individual checks the composite action performs, see

references/synthesis-steps.md

On success: All checks passed. The response includes a readiness summary with any quality hints to present to the user. Proceed to Step 2.

On failure: The response identifies which check failed and provides remediation guidance. Follow the guidance -- typically returning to

review

delegate

If any quality hint has

confidenceLevel: 'actionable'

, present the

suggestedAction

to the user before proceeding.

调用

prepare_synthesis

复合操作，一次性验证所有前置条件：

typescript

exarchos:exarchos_orchestrate({
  action: "prepare_synthesis",
  featureId: "<id>"
})

该操作执行以下检查：

阶段就绪性——确认工作流处于正确阶段且所有评审已完成
堆叠完整性——检测分支偏离、缺失任务分支或父链断裂，并自动重建
测试验证——从堆叠顶部运行
```
npm run test:run && npm run typecheck
```
基准回归检查——如果
```
state.verification.hasBenchmarks
```
为true，检查性能回归
质量信号——查询
```
code_quality
```
视图获取回归信息和可操作提示
文档就绪性——被修改的文档表面必须有对应的文档更新（未修改文档表面时自动豁免）
网关事件——为每项检查（测试、基准、CodeRabbit）自动发送
```
gate.executed
```
事件

有关该复合操作执行的各项检查的详细说明，请参阅

references/synthesis-steps.md

。

成功时： 所有检查通过。响应包含就绪状态摘要以及需呈现给用户的质量提示。继续步骤2。

失败时： 响应会指出哪项检查失败并提供修复指导。遵循指导操作——通常回到

review

或

delegate

阶段。

如果任何质量提示的

confidenceLevel

为'actionable'，在继续之前需向用户呈现

suggestedAction

。

Step 2: Write and Validate PR Descriptions

步骤2：编写并验证PR描述

For each PR in the stack, write a structured description following

references/pr-descriptions.md

. Required sections: Summary, Changes, Test Plan, plus a footer. Projects can override required sections via

.exarchos/pr-template.md

Title format:

<type>: <what>

(max 72 chars)

Write the PR body to a temp file:

bash

cat > /tmp/pr-body.md <<'EOF'

对于堆叠中的每个PR，遵循

references/pr-descriptions.md

编写结构化描述。必填部分：摘要、变更内容、测试计划，以及页脚。项目可通过

.exarchos/pr-template.md

覆盖必填部分。

标题格式：

<type>: <what>

（最多72字符）

将PR正文写入临时文件：

bash

cat > /tmp/pr-body.md <<'EOF'

Summary

[2-3 sentences: what changed, why it matters]

[2-3句话：变更内容及其重要性]

Changes

Component -- Description of change

Component -- 变更描述

Test Plan

[Testing approach and coverage]

Results: Tests X pass · Build 0 errors Design: doc Related: #issue EOF


Validate **before** creating the PR:
```typescript
exarchos:exarchos_orchestrate({
  action: "validate_pr_body",
  bodyFile: "/tmp/pr-body.md"
})

Do NOT call
create_pr
until validation passes. If validation fails, fix the body and re-validate.

[测试方法和覆盖范围]

Results: Tests X pass · Build 0 errors Design: doc Related: #issue EOF


在创建PR之前进行验证：
```typescript
exarchos:exarchos_orchestrate({
  action: "validate_pr_body",
  bodyFile: "/tmp/pr-body.md"
})

验证通过前请勿调用
create_pr
。如果验证失败，修改正文后重新验证。

Step 3: Submit and Merge

步骤3：提交并合并

Create PRs using the validated body and enable auto-merge. For each branch in the stack (bottom-up):

typescript

// Create PR via VCS MCP action
exarchos_orchestrate({
  action: "create_pr",
  base: "<parent-branch>",
  head: "<branch>",
  title: "<type>: <what>",
  body: "<pr-body>"
})

// Enable auto-merge
exarchos_orchestrate({
  action: "merge_pr",
  prId: "<number>",
  strategy: "squash"
})

After submission:

Apply benchmark label -- If

verification.hasBenchmarks

is true, apply label:

gh pr edit <number> --add-label has-benchmarks

Record PR URLs -- Capture URLs via

exarchos_orchestrate({ action: "list_prs", state: "open" })

Update state:

typescript

exarchos:exarchos_workflow({
  action: "update", featureId: "<id>", updates: {
    "artifacts": { "pr": ["<url1>", "<url2>"] },
    "synthesis": { "mergeOrder": ["<branch1>", ...], "prUrl": ["<url1>", ...], "prFeedback": [] }
  }
})

For merge ordering strategy, see

references/merge-ordering.md

Human checkpoint: Output "Stacked PRs enqueued: [URLs]. Waiting for CI/merge queue." then PAUSE for user input: "Merge stack? (yes/no/feedback)"

'yes' -- PRs merge; transition to completed via
```
cleanup
```
'feedback' -- Route to
```
shepherd [PR_URL]
```
to address comments, then return here
'no' -- Pause workflow; resume later with
```
rehydrate
```

使用已验证的正文创建PR并启用自动合并。对于堆叠中的每个分支（从下到上）：

typescript

// 通过VCS MCP操作创建PR
exarchos_orchestrate({
  action: "create_pr",
  base: "<parent-branch>",
  head: "<branch>",
  title: "<type>: <what>",
  body: "<pr-body>"
})

// 启用自动合并
exarchos_orchestrate({
  action: "merge_pr",
  prId: "<number>",
  strategy: "squash"
})

提交后：

添加基准标签——如果

verification.hasBenchmarks

为true，添加标签：

gh pr edit <number> --add-label has-benchmarks

记录PR URL——通过

exarchos_orchestrate({ action: "list_prs", state: "open" })

捕获URL

更新状态：

typescript

exarchos:exarchos_workflow({
  action: "update", featureId: "<id>", updates: {
    "artifacts": { "pr": ["<url1>", "<url2>"] },
    "synthesis": { "mergeOrder": ["<branch1>", ...], "prUrl": ["<url1>", ...], "prFeedback": [] }
  }
})

有关合并排序策略，请参阅

references/merge-ordering.md

。

人工检查点： 输出“堆叠PR已入队：[URL]。等待CI/合并队列处理。”然后暂停等待用户输入：“合并堆叠？(是/否/反馈)”

'是'——PR合并；通过
```
cleanup
```
转换到已完成阶段
'反馈'——路由到
```
shepherd [PR_URL]
```
处理评论，然后返回此阶段
'否'——暂停工作流；稍后通过
```
rehydrate
```
恢复

Event Emissions (REQUIRED)

事件发送（必填）

After PRs are created and auto-merge is enabled, emit the

stack.submitted

event:

typescript

exarchos:exarchos_event({ action: "append", stream: "<featureId>", event: {
  type: "stack.submitted",
  data: {
    branches: ["task-001-branch", "task-002-branch"],
    prNumbers: [101, 102]
  }
}})

During shepherd iterations (CI monitoring loop), emit after each assessment:

typescript

exarchos:exarchos_event({ action: "append", stream: "<featureId>", event: {
  type: "shepherd.iteration",
  data: {
    iteration: 1,
    prsAssessed: 2,
    fixesApplied: 0,
    status: "all-green"
  }
}})

These events are checked by

check-event-emissions

during workflow validation. Missing emissions will trigger warnings.

创建PR并启用自动合并后，发送

stack.submitted

事件：

typescript

exarchos:exarchos_event({ action: "append", stream: "<featureId>", event: {
  type: "stack.submitted",
  data: {
    branches: ["task-001-branch", "task-002-branch"],
    prNumbers: [101, 102]
  }
}})

在shepherd迭代（CI监控循环）期间，每次评估后发送事件：

typescript

exarchos:exarchos_event({ action: "append", stream: "<featureId>", event: {
  type: "shepherd.iteration",
  data: {
    iteration: 1,
    prsAssessed: 2,
    fixesApplied: 0,
    status: "all-green"
  }
}})

这些事件会在工作流验证期间被

check-event-emissions

检查。缺失事件会触发警告。

Post-Merge Cleanup

合并后清理

After PRs merge, invoke cleanup:

typescript

exarchos:exarchos_workflow({
  action: "cleanup", featureId: "<id>", mergeVerified: true,
  prUrl: ["<url>", ...], mergedBranches: ["<branch>", ...]
})

Then sync:

git fetch --prune

and reclaim worktrees.

Worktree GC cadence — after synthesize (INV-12). Once a workflow reaches synthesis its governed worktrees are no longer needed, so this is the point to reclaim them. Use the governed garbage-collector
prune_worktrees
rather than ad-hoc
git worktree remove
: dry-run first (the default — reports candidates
reclaimable bytes, deletes nothing), then re-invoke with
dryRun: false
to apply.
typescript
exarchos:exarchos_orchestrate({ action: "prune_worktrees", repoRoot: "<repo-root>" })            // dry-run (default)
exarchos:exarchos_orchestrate({ action: "prune_worktrees", repoRoot: "<repo-root>", dryRun: false }) // apply
The
next_actions
projection surfaces this same
prune_worktrees
dry-run affordance once the workflow is parked in synthesis. The full apply flow lands in
@skills/cleanup/SKILL.md
.

PR合并后，调用清理操作：

typescript

exarchos:exarchos_workflow({
  action: "cleanup", featureId: "<id>", mergeVerified: true,
  prUrl: ["<url>", ...], mergedBranches: ["<branch>", ...]
})

然后同步：

git fetch --prune

并回收工作树。

工作树GC节奏——合成之后（INV-12）。 一旦工作流进入合成阶段，其管控的工作树不再需要，因此此时是回收它们的时机。使用管控垃圾回收器
prune_worktrees
而非临时的
git worktree remove
：先执行试运行（默认设置——报告候选对象+可回收字节数，不删除任何内容），然后使用
dryRun: false
重新调用以执行清理。
typescript
exarchos:exarchos_orchestrate({ action: "prune_worktrees", repoRoot: "<repo-root>" })            // 试运行（默认）
exarchos:exarchos_orchestrate({ action: "prune_worktrees", repoRoot: "<repo-root>", dryRun: false }) // 执行清理
当工作流停留在合成阶段时，
next_actions
投影会提供相同的
prune_worktrees
试运行功能。完整的执行流程在
@skills/cleanup/SKILL.md
中。

Idempotency

幂等性

create_pr

is the single authority for "PR already exists" — do NOT pre-check

synthesis.prUrl

artifacts.pr

before deciding whether to create. Just call

create_pr

: it either returns the existing open PR for this

(head, base)

via its remote-recovery guard, or refuses with

PR_ALREADY_OWNED

when the workflow already owns a PR. Branch on that structured response instead of pre-checking.

The post-merge cleanup case is distinct from create-time idempotency and is NOT governed by

create_pr

: if the PR is already merged, transition to

completed

via

action: "transition"

target: "completed"

(the runtime rejects

updates.phase

; the canonical

transition

action runs the HSM guard and emits

workflow.transition

). This

completed

transition is normally owned by

cleanup

via

action: "cleanup"

; the bare phase-only transition is a manual-cleanup escape hatch.

create_pr

是判断“PR已存在”的唯一权威——在决定是否创建PR之前，请勿预先检查

synthesis.prUrl

artifacts.pr

。直接调用

create_pr

即可：它要么通过远程恢复防护返回此

(head, base)

对应的现有开放PR，要么在工作流已拥有PR时返回

PR_ALREADY_OWNED

拒绝请求。根据该结构化响应进行分支处理，而非预先检查。

合并后清理场景与创建时的幂等性不同，不受

create_pr

管控：如果PR已合并，通过

action: "transition"

、

target: "completed"

转换到已完成阶段（运行时拒绝

updates.phase

；标准的

transition

操作会运行HSM防护并发送

workflow.transition

事件）。这种

completed

转换通常由

cleanup

通过

action: "cleanup"

操作处理；单纯的阶段转换是手动清理的逃生舱口。

Direct Edits to Stack Branches

对堆叠分支的直接编辑

You can make direct edits to stack branches at any time — edit files, then stage and amend (

git add <files> && git commit --amend

). Push with the explicit-SHA lease, never a bare

--force-with-lease

bash

git push --force-with-lease=<ref>:<expected-sha>

A bare lease anchors to the (possibly stale) local remote-tracking ref and can clobber a concurrent push.

<expected-sha>

is the remote SHA the loop last observed via

assess_stack

, or read fresh with

git ls-remote --heads origin <ref>

您可随时对堆叠分支进行直接编辑——编辑文件，然后暂存并修正提交（

git add <files> && git commit --amend

）。使用显式SHA租约推送，绝不要使用裸

--force-with-lease

：

bash

git push --force-with-lease=<ref>:<expected-sha>

裸租约会锚定到（可能过时的）本地远程跟踪引用，可能会覆盖并发推送。

<expected-sha>

是循环最后一次通过

assess_stack

观察到的远程SHA，或通过

git ls-remote --heads origin <ref>

读取最新值。

Completion Output

完成输出

When the PR is created and checks pass, report:

markdown

undefined

当PR创建且检查通过后，报告：

markdown

undefined

Synthesis Complete

合成完成

PR: [URL] Tests: X pass | Build: 0 errors

undefined

PR: [URL] Tests: X pass | Build: 0 errors

undefined

Anti-Patterns

反模式

Don't	Do Instead
Skip review phase	Always run `review` first
Force push stack branches	Use normal push
Delete worktrees before merge	Wait for merge confirmation
Create PR with failing tests	Ensure review phase passes first
Run readiness scripts manually	Use `prepare_synthesis` composite action

请勿	正确做法
跳过评审阶段	始终先运行 `review`
强制推送堆叠分支	使用常规推送
合并前删除工作树	等待合并确认
创建测试失败的PR	确保评审阶段先通过
手动运行就绪脚本	使用 `prepare_synthesis` 复合操作

Handling Failures

故障处理

See

references/troubleshooting.md

for test failures, PR check failures, merge queue rejections, and MCP tool errors.

有关测试失败、PR检查失败、合并队列拒绝和MCP工具错误的处理，请参阅

references/troubleshooting.md

。

Phase Transitions and Guards

阶段转换与防护

For the full transition table, consult

@skills/checkpoint/references/phase-transitions.md

Quick reference: The

synthesize

→

completed

transition requires guard

pr-url-exists

— set

synthesis.prUrl

artifacts.pr

in the same

set

call as

phase

完整的转换表请参阅

@skills/checkpoint/references/phase-transitions.md

。

快速参考：

synthesize

→

completed

转换需要

pr-url-exists

防护——在设置

phase

的同一

set

调用中设置

synthesis.prUrl

或

artifacts.pr

。

Schema Discovery

Schema 发现

Use

exarchos_workflow({ action: "describe", actions: ["update", "init"] })

for parameter schemas and

exarchos_workflow({ action: "describe", playbook: "feature" })

for phase transitions, guards, and playbook guidance. Use

exarchos_orchestrate({ action: "describe", actions: ["prepare_synthesis"] })

for orchestrate action schemas.

使用

exarchos_workflow({ action: "describe", actions: ["update", "init"] })

获取参数schema，使用

exarchos_workflow({ action: "describe", playbook: "feature" })

获取阶段转换、防护和工作手册指南。使用

exarchos_orchestrate({ action: "describe", actions: ["prepare_synthesis"] })

获取编排操作schema。

Completion Criteria

完成标准

```
prepare_synthesis
```
readiness check passed
PR descriptions written per
```
references/pr-descriptions.md
```
PRs created and auto-merge enabled
PR links provided to user
State updated with PR URLs and merge order

```
prepare_synthesis
```
就绪检查通过
PR描述按照
```
references/pr-descriptions.md
```
编写
PR已创建且自动合并已启用
PR链接已提供给用户
状态已更新PR URL和合并顺序