checkpoint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Workflow Checkpoint Skill

Overview

概述

Save and mutate persistent workflow state that survives context auto-summarization.

State files store: task details, worktree locations, PR URLs, and review status. This skill owns the write side of workflow state — initializing a workflow, updating fields, transitioning phases, and capturing a structured handoff. For the read/restore side (resuming after a break, reconciling against git, verifying a workflow exists), see

@skills/rehydrate/SKILL.md

保存并变更可持久化的工作流状态，使其在上下文自动总结后仍能保留。

状态文件存储：任务详情、工作树位置、PR URL和评审状态。本技能负责工作流状态的写入端——初始化工作流、更新字段、转换阶段以及捕获结构化交接。关于读取/恢复端（会话中断后恢复、与git协调、验证工作流是否存在），请参阅

@skills/rehydrate/SKILL.md

。

Triggers

触发条件

Activate this skill when:

Starting a new workflow (
```
ideate
```
)
Transitioning between workflow phases
Saving progress for later continuation (
```
checkpoint
```
)

在以下场景激活本技能：

启动新工作流（
```
ideate
```
）
工作流阶段之间转换
保存进度以便后续继续（
```
checkpoint
```
）

Phase Transitions

阶段转换

Valid transitions, guards, and prerequisites for all workflow types are documented in

references/phase-transitions.md

. CRITICAL: Phase mutation is a separate action from field mutation. When a transition has a guard,

action: "update"

the prerequisite fields first, then

action: "transition"

— guards read the most recent state, so updates land before guards evaluate. Attempting to mutate

phase

via

action: "update"

returns a

RESERVED_FIELD

error pointing at

transition

(see "Reserved fields" below).

所有工作流类型的有效转换、守卫条件和先决条件都记录在

references/phase-transitions.md

中。关键提示：阶段变更与字段变更是独立的操作。当转换存在守卫条件时，先使用

action: "update"

更新先决字段，再执行

action: "transition"

——守卫条件会读取最新状态，因此更新操作必须在守卫条件评估前完成。尝试通过

action: "update"

变更

phase

字段会返回

RESERVED_FIELD

错误，并指向

transition

操作（请参阅下方“保留字段”部分）。

Schema Discovery

架构发现

Use

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

for parameter schemas and

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

for phase transitions, guards, and playbook guidance. For the lightweight oneshot variant (with its

implementing → synthesize|completed

choice state driven by

synthesisPolicy

), call

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

— oneshot is a first-class playbook alongside feature/debug/refactor. Use

exarchos_event({ action: "describe", eventTypes: ["workflow.transition", "task.completed"] })

for event data schemas.

使用

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

获取参数架构，使用

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

获取阶段转换、守卫条件和工作手册指南。对于轻量级一次性变体（其

implementing → synthesize|completed

选择状态由

synthesisPolicy

驱动），请调用

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

——oneshot是与feature/debug/refactor并列的一等工作手册。使用

exarchos_event({ action: "describe", eventTypes: ["workflow.transition", "task.completed"] })

获取事件数据架构。

State Location

状态存储位置

Workflow state lives in the MCP event store, not the filesystem. Use

exarchos_workflow get

to read state and

exarchos_view pipeline

to discover active workflows. The pipeline view is repo-scoped by default — only the caller's repo; when the response reports

unscopedTotal

greater than

page.total

, workflows in other repos are hidden — re-query with

scope: "all"

to reveal them. Do not scan

~/.claude/workflow-state/*.state.json

— that path is legacy and may be stale or empty.

工作流状态存储在MCP事件存储中，而非文件系统。使用

exarchos_workflow get

读取状态，使用

exarchos_view pipeline

发现活跃工作流。流水线视图默认按仓库范围限定——仅显示调用者的仓库；当响应报告

unscopedTotal

大于

page.total

时，说明其他仓库中的工作流被隐藏——使用

scope: "all"

重新查询以显示这些工作流。请勿扫描

~/.claude/workflow-state/*.state.json

——该路径为遗留路径，内容可能过时或为空。

State Operations

状态操作

For full MCP tool signatures, error handling, and anti-patterns, see

references/mcp-tool-reference.md

有关MCP工具的完整签名、错误处理和反模式，请参阅

references/mcp-tool-reference.md

。

Initialize State

初始化状态

At the start of

ideate

, use

exarchos:exarchos_workflow

with

action: "init"

with:

```
featureId
```
: the workflow identifier (e.g.,
```
"user-authentication"
```
)

workflowType

: one of

"feature"

"debug"

"refactor"

"oneshot"

```
synthesisPolicy
```
(optional, oneshot only): one of
```
"always"
```
,
```
"never"
```
,
```
"on-request"
```
(default
```
"on-request"
```
) — silently ignored for non-oneshot types

This creates a new workflow state entry. The initial phase depends on

workflowType

```
feature
```
→ starts in
```
plan
```
```
debug
```
→ starts in
```
triage
```
```
refactor
```
→ starts in
```
explore
```
```
oneshot
```
→ starts in
```
plan
```

在

ideate

开始时，使用

exarchos:exarchos_workflow

并设置

action: "init"

，同时传入：

```
featureId
```
：工作流标识符（例如
```
"user-authentication"
```
）

workflowType

：可选值为

"feature"

、

"debug"

、

"refactor"

、

"oneshot"

```
synthesisPolicy
```
（可选，仅适用于oneshot）：可选值为
```
"always"
```
、
```
"never"
```
、
```
"on-request"
```
（默认值为
```
"on-request"
```
）——非oneshot类型会自动忽略该参数

此操作会创建一个新的工作流状态条目。初始阶段取决于

workflowType

：

```
feature
```
→ 从
```
plan
```
阶段开始
```
debug
```
→ 从
```
triage
```
阶段开始
```
refactor
```
→ 从
```
explore
```
阶段开始
```
oneshot
```
→ 从
```
plan
```
阶段开始

Workflow Types at a Glance

工作流类型概览

feature

— full

plan → plan-review → delegate → review → synthesize

for real features with subagent dispatch and review

debug

—

triage → investigate → (thorough | hotfix)

for bug workflows with track selection

```
refactor
```
—
```
explore → brief → (polish | overhaul)
```
for code improvements, polish for small and overhaul for multi-task
```
oneshot
```
—
```
plan → implementing → (completed | synthesize)
```
for trivial changes; direct-commit by default with an opt-in PR path resolved via a choice-state guard driven by
```
synthesisPolicy
```
and the
```
synthesize.requested
```
event

See

@skills/oneshot/SKILL.md

for the lightweight variant's full prose, including the choice-state mechanics and

finalize_oneshot

trigger.

```
feature
```
— 完整的
```
plan → plan-review → delegate → review → synthesize
```
流程，适用于包含子Agent调度和评审的真实功能开发
```
debug
```
—
```
triage → investigate → (thorough | hotfix)
```
流程，适用于包含跟踪选择的Bug修复工作流
```
refactor
```
—
```
explore → brief → (polish | overhaul)
```
流程，适用于代码优化，polish用于小型优化，overhaul用于多任务优化
```
oneshot
```
—
```
plan → implementing → (completed | synthesize)
```
流程，适用于微小变更；默认直接提交，通过由
```
synthesisPolicy
```
和
```
synthesize.requested
```
事件驱动的选择状态守卫条件提供可选PR路径

有关轻量级变体的完整说明，包括选择状态机制和

finalize_oneshot

触发条件，请参阅

@skills/oneshot/SKILL.md

。

Update State (fields only)

更新状态（仅字段）

Use

exarchos:exarchos_workflow

with

action: "update"

with

featureId

and

updates

. This action mutates non-phase fields only —

phase

workflowType

featureId

createdAt

, and

version

are reserved (see "Reserved fields" below).

Set artifact path:

updates: { "artifacts.spec": "docs/specs/2026-01-05-feature.md" }

Mark task complete (by index):

updates: { "tasks[0].status": "complete", "tasks[0].completedAt": "<timestamp>" }

Add worktree:

updates: { "worktrees.wt-001": { "branch": "feature/001-types", "taskId": "001", "status": "active" } }

Worktree status values:

'active' | 'merged' | 'removed'

使用

exarchos:exarchos_workflow

并设置

action: "update"

，同时传入

featureId

和

updates

。此操作仅变更非阶段字段——

phase

、

workflowType

、

featureId

、

createdAt

和

version

为保留字段（请参阅下方“保留字段”部分）。

设置工件路径：

updates: { "artifacts.spec": "docs/specs/2026-01-05-feature.md" }

标记任务完成（按索引）：

updates: { "tasks[0].status": "complete", "tasks[0].completedAt": "<timestamp>" }

添加工作树：

updates: { "worktrees.wt-001": { "branch": "feature/001-types", "taskId": "001", "status": "active" } }

工作树状态值：

'active' | 'merged' | 'removed'

Transition Phase

阶段转换

Use

exarchos:exarchos_workflow

with

action: "transition"

with

featureId

and

target

Advance phase:
```
target: "delegate"
```

Transitions are HSM-validated and emit a

workflow.transition

event. Guarded transitions read state after the most recent

update

, so any

updates: {...}

that the guard depends on must land first.

使用

exarchos:exarchos_workflow

并设置

action: "transition"

，同时传入

featureId

和

target

：

推进阶段：
```
target: "delegate"
```

转换会经过HSM验证，并触发

workflow.transition

事件。带守卫条件的转换会读取最近一次

update

后的状态，因此守卫条件依赖的所有

updates: {...}

必须先完成更新。

Editing the

tasks

array

编辑

tasks

数组

The dot-path parser used by

set updates

recognizes only numeric array brackets (

tasks[0]

tasks[1]

, …). Keyed forms like

tasks[id=T-001]

are NOT supported and now throw an

INVALID_INPUT

error with a clear message — earlier versions silently wrote to a bogus top-level key, returning

success: true

while the actual task was untouched. Three patterns are supported:

Replace the whole array (use this when the plan is being revised wholesale):

typescript

exarchos_workflow({
  action: "update",
  featureId: "<id>",
  updates: { tasks: [
    { id: "T-001", title: "...", status: "pending" },
    { id: "T-002", title: "...", status: "pending" },
  ]},
})

Edit one task by its array index:

typescript

exarchos_workflow({
  action: "update",
  featureId: "<id>",
  updates: { "tasks[0].status": "complete", "tasks[0].completedAt": "<ts>" },
})

First read

tasks

(

action: "get", query: "tasks"

) to find the index of the task you want to edit, then set by that index.

Append a new task by writing to the next-free index. If the array currently has length

, write to

tasks[N]

typescript

// Suppose tasks already contains T-001 and T-002 (length 2). To append:
exarchos_workflow({
  action: "update",
  featureId: "<id>",
  updates: { "tasks[2]": { id: "T-003", title: "Follow-up", status: "pending" } },
})

The parser allows writing one slot past the current length (

MAX_ARRAY_GAP = 1

); writing further out (

tasks[5]

against a length-2 array) throws

INVALID_INPUT

. Read the current

tasks

length before appending.

set updates

使用的点路径解析器仅支持数字数组括号（

tasks[0]

、

tasks[1]

等）。不支持键值形式如

tasks[id=T-001]

，否则会抛出

INVALID_INPUT

错误并显示明确消息——早期版本会静默写入错误的顶级键，返回

success: true

但实际任务未被修改。支持以下三种模式：

替换整个数组（当计划被全面修订时使用）：

typescript

exarchos_workflow({
  action: "update",
  featureId: "<id>",
  updates: { tasks: [
    { id: "T-001", title: "...", status: "pending" },
    { id: "T-002", title: "...", status: "pending" },
  ]},
})

按数组索引编辑单个任务：

typescript

exarchos_workflow({
  action: "update",
  featureId: "<id>",
  updates: { "tasks[0].status": "complete", "tasks[0].completedAt": "<ts>" },
})

先读取

tasks

（

action: "get", query: "tasks"

）找到要编辑的任务索引，再按该索引进行设置。

通过写入下一个可用索引追加新任务。如果数组当前长度为

，则写入

tasks[N]

：

typescript

// 假设tasks已包含T-001和T-002（长度为2）。要追加任务：
exarchos_workflow({
  action: "update",
  featureId: "<id>",
  updates: { "tasks[2]": { id: "T-003", title: "Follow-up", status: "pending" } },
})

解析器允许写入当前长度之后的一个位置（

MAX_ARRAY_GAP = 1

）；写入更远的位置（如针对长度为2的数组写入

tasks[5]

）会抛出

INVALID_INPUT

错误。追加前请读取当前

tasks

的长度。

Integration Points

集成点

When to Update State

状态更新时机

Event	State Update
`ideate` starts	`init` the workflow (initial phase `plan` )
Design & Rationale authored	`update: { "artifacts.spec": "<path>" }` (no transition — `plan` is the initial phase)
Decomposition added	`update: { "artifacts.plan": "<path>", "tasks": [...] }` , then `transition target: "plan-review"`
Plan-review gaps found	`update: { "planReview.gaps": [...] }` , auto-loop to plan
Plan-review approved	`update: { "planReview.approved": true }` , then `transition target: "delegate"`
Task dispatched	Set task `status = "in_progress"` , `startedAt`
Task complete	Set task `status = "complete"` , `completedAt`
Worktree created	Add to `worktrees` object
Review complete	Update `reviews` object
PR created	Set `artifacts.pr` , `synthesis.prUrl`
PR feedback	Append to `synthesis.prFeedback`

事件	状态更新操作
`ideate` 启动	`init` 工作流（初始阶段为 `plan` ）
设计与原理文档编写完成	`update: { "artifacts.spec": "<path>" }` （无需转换阶段—— `plan` 是初始阶段）
分解任务完成	`update: { "artifacts.plan": "<path>", "tasks": [...] }` ，然后执行 `transition target: "plan-review"`
计划评审发现问题	`update: { "planReview.gaps": [...] }` ，自动循环回到plan阶段
计划评审通过	`update: { "planReview.approved": true }` ，然后执行 `transition target: "delegate"`
任务分派	设置任务 `status = "in_progress"` 、 `startedAt`
任务完成	设置任务 `status = "complete"` 、 `completedAt`
工作树创建	添加到 `worktrees` 对象
评审完成	更新 `reviews` 对象
PR创建	设置 `artifacts.pr` 、 `synthesis.prUrl`
PR反馈	追加到 `synthesis.prFeedback`

Oneshot-specific state updates

仅适用于Oneshot的状态更新

Oneshot is a first-class workflow type with a compressed lifecycle and an opt-in PR path. The rows below mirror the feature-workflow table above.

Phase	State updates	Events emitted
`plan` (oneshot)	`oneshot.planSummary` , `artifacts.plan` , optional `oneshot.synthesisPolicy`	`workflow.transition`
`implementing` (oneshot)	`tasks[].status` , `artifacts.tests`	`task.*` , optional `synthesize.requested` (via `request_synthesize` )
`synthesize` (oneshot)	`synthesis.prUrl` , `artifacts.pr`	`workflow.transition` , `stack.submitted`
`completed` (oneshot)	—	`workflow.transition` (to `completed` )

The

implementing → synthesize | completed

fork is a choice state resolved by

finalize_oneshot

, which reads the

synthesisOptedIn

guard (

synthesisPolicy

synthesize.requested

events). See

@skills/oneshot/SKILL.md

for the full opt-in mechanics.

Oneshot是一等工作流类型，具有压缩的生命周期和可选PR路径。以下表格与上方功能工作流表格对应。

阶段	状态更新	触发的事件
`plan` （oneshot）	`oneshot.planSummary` 、 `artifacts.plan` 、可选的 `oneshot.synthesisPolicy`	`workflow.transition`
`implementing` （oneshot）	`tasks[].status` 、 `artifacts.tests`	`task.*` 、可选的 `synthesize.requested` （通过 `request_synthesize` 触发）
`synthesize` （oneshot）	`synthesis.prUrl` 、 `artifacts.pr`	`workflow.transition` 、 `stack.submitted`
`completed` （oneshot）	—	`workflow.transition` （转换到 `completed` 阶段）

implementing → synthesize | completed

分支是由

finalize_oneshot

解析的选择状态，它会读取

synthesisOptedIn

守卫条件（

synthesisPolicy

synthesize.requested

事件）。有关完整的可选加入机制，请参阅

@skills/oneshot/SKILL.md

。

Automatic State Updates

自动状态更新

Skills should update state at key moments:

ideate/SKILL.md:

markdown

After authoring the Design & Rationale section of the unified docs/specs/ artifact:
- `action: "update"` — `updates: { "artifacts.spec": "<path>" }`
  (no transition — `plan` is the initial phase; continue to decomposition in the same phase)

plan/SKILL.md:

markdown

After saving plan:
1. `action: "update"` — `updates: { "artifacts.plan": "<path>", "tasks": [...] }`
2. `action: "transition"` — `target: "plan-review"`

delegate/SKILL.md:

markdown

On task dispatch:
- Update task status to "in_progress"
- Add worktree to state if created

On task complete:
- Update task status to "complete"
- Check if all tasks done, suggest checkpoint

技能应在关键节点更新状态：

ideate/SKILL.md:

markdown

在统一文档/docs/specs/的设计与原理部分编写完成后：
- `action: "update"` — `updates: { "artifacts.spec": "<path>" }`
  （无需转换阶段——`plan`是初始阶段；继续在同一阶段进行任务分解）

plan/SKILL.md:

markdown

保存计划后：
1. `action: "update"` — `updates: { "artifacts.plan": "<path>", "tasks": [...] }`
2. `action: "transition"` — `target: "plan-review"`

delegate/SKILL.md:

markdown

任务分派时：
- 将任务状态更新为"in_progress"
- 如果创建了工作树，添加到状态中

任务完成时：
- 将任务状态更新为"complete"
- 检查所有任务是否完成，建议执行checkpoint

State Schema

状态架构

See

docs/schemas/workflow-state.schema.json

for full schema.

Key sections:

```
version
```
: Schema version (currently "1.1")
```
featureId
```
: Unique workflow identifier
```
workflowType
```
: Required. One of "feature", "debug", "refactor", or "oneshot"
```
phase
```
: Current workflow phase
```
artifacts
```
: Paths to design, plan, PR
```
tasks
```
: Task list with status
```
worktrees
```
: Active git worktrees
```
planReview
```
: Plan-review delta analysis results (
```
gaps
```
,
```
approved
```
)
```
reviews
```
: Review results
```
synthesis
```
: Merge/PR state

完整架构请参阅

docs/schemas/workflow-state.schema.json

。

关键部分：

```
version
```
：架构版本（当前为"1.1"）
```
featureId
```
：唯一的工作流标识符
```
workflowType
```
：必填项。可选值为"feature"、"debug"、"refactor"或"oneshot"
```
phase
```
：当前工作流阶段
```
artifacts
```
：设计文档、计划、PR的路径
```
tasks
```
：包含状态的任务列表
```
worktrees
```
：活跃的git工作树
```
planReview
```
：计划评审差异分析结果（
```
gaps
```
、
```
approved
```
）
```
reviews
```
：评审结果
```
synthesis
```
：合并/PR状态

Reserved fields

保留字段

exarchos:exarchos_workflow

with

action: "update"

rejects two classes of paths with

RESERVED_FIELD

Top-level immutable keys —
```
phase
```
,
```
workflowType
```
,
```
featureId
```
,
```
createdAt
```
,
```
version
```
. Set once at init; never mutated directly.
Underscore-prefixed paths — any dot-path whose top-level key, or any segment, begins with
```
_
```
(e.g.
```
_version
```
,
```
_checkpoint.summary
```
,
```
_eventHints
```
). These are projection or event-store metadata.

Alternate write paths:

```
phase
```
→
```
exarchos:exarchos_workflow
```
with
```
action: "transition"
```
and
```
target: "<phase>"
```
. Transitions are HSM-validated and emit transition events.
Underscore-prefixed paths → emit a typed event via
```
exarchos:exarchos_event
```
with
```
action: "append"
```
(e.g.
```
checkpoint
```
,
```
state.patched
```
). The projection folds the event into the field on the next read.
```
workflowType
```
,
```
featureId
```
,
```
createdAt
```
,
```
version
```
→ not migratable. If you need a different workflow type, init a new workflow.

RESERVED_FIELD

error envelope now carries a typed

data

block:

json

{
  "success": false,
  "error": {
    "code": "RESERVED_FIELD",
    "message": "Cannot update reserved field: phase",
    "data": {
      "rejectedPath": "phase",
      "rule": "`phase` is top-level immutable — set once at init, never directly mutated thereafter.",
      "alternateWritePath": "Use `exarchos:exarchos_workflow` with `action: \"transition\"` and `target: \"<phase>\"` — phase changes are HSM-validated and emit transition events."
    }
  }
}

Read the full descriptor — including the regex catch-all for underscore paths — via

exarchos:exarchos_workflow

with

action: "describe"

and

actions: ["update"]

. The returned

reservedFields

block is the single source of truth.

使用

exarchos:exarchos_workflow

并设置

action: "update"

时，会拒绝两类路径并返回

RESERVED_FIELD

错误：

顶级不可变键 —
```
phase
```
、
```
workflowType
```
、
```
featureId
```
、
```
createdAt
```
、
```
version
```
。在初始化时设置一次；之后不得直接修改。
下划线前缀路径 — 任何顶级键或任意段以下划线开头的点路径（例如
```
_version
```
、
```
_checkpoint.summary
```
、
```
_eventHints
```
）。这些是投影或事件存储的元数据。

替代写入路径：

```
phase
```
→ 使用
```
exarchos:exarchos_workflow
```
并设置
```
action: "transition"
```
和
```
target: "<phase>"
```
。转换会经过HSM验证，并触发转换事件。
下划线前缀路径 → 通过
```
exarchos:exarchos_event
```
并设置
```
action: "append"
```
触发类型化事件（例如
```
checkpoint
```
、
```
state.patched
```
）。投影会在下次读取时将事件合并到字段中。
```
workflowType
```
、
```
featureId
```
、
```
createdAt
```
、
```
version
```
→ 不可迁移。如果需要不同的工作流类型，请初始化新的工作流。

RESERVED_FIELD

错误信封现在包含一个类型化的

data

块：

json

{
  "success": false,
  "error": {
    "code": "RESERVED_FIELD",
    "message": "Cannot update reserved field: phase",
    "data": {
      "rejectedPath": "phase",
      "rule": "`phase` is top-level immutable — set once at init, never directly mutated thereafter.",
      "alternateWritePath": "Use `exarchos:exarchos_workflow` with `action: \"transition\"` and `target: \"<phase>\"` — phase changes are HSM-validated and emit transition events."
    }
  }
}

通过

exarchos:exarchos_workflow

并设置

action: "describe"

和

actions: ["update"]

读取完整描述符——包括下划线路径的正则匹配规则。返回的

reservedFields

块是唯一的事实来源。

Structured Handoff Output

结构化交接输出

When capturing a handoff (the

checkpoint

command surface), emit this structured summary so the agent that resumes sees the same contract you operated under before context clears. The

### House Rules

block mirrors the

rehydrate

output (see

@skills/rehydrate/SKILL.md

) for correctness-signal symmetry — an agent producing a checkpoint sees the same house rules an agent rehydrating would.

markdown

undefined

当捕获交接（

checkpoint

命令界面）时，输出此结构化摘要，以便恢复工作流的Agent能看到与上下文清除前相同的约定。

### House Rules

块与

rehydrate

输出（请参阅

@skills/rehydrate/SKILL.md

）保持一致，以确保正确性信号对称——生成checkpoint的Agent看到的规则与恢复工作流的Agent看到的规则相同。

markdown

undefined

Checkpoint Saved

已保存检查点

Feature: <feature-id> Phase: <current-phase>

功能: <feature-id> 阶段: <current-phase>

Progress

进度

Tasks: X/Y complete
Current: <what's in progress>
Next: <suggested next action>

任务: X/Y 已完成
当前: <进行中的工作>
下一步: <建议的下一个操作>

House Rules (apply every action this turn forward)

规则（后续所有操作均需遵守）

Skill: <phasePlaybook.skillRef or "(no playbook for this phase)"> Tools: <phasePlaybook.tools rendered as bullets> Required model-emitted events: <phasePlaybook.events rendered as bullets — e.g.

task.progressed

phase.advanced

> Auto-emitted events (runtime fires these): <phasePlaybook.autoEmittedEvents rendered as bullets> Transition: <phasePlaybook.transitionCriteria> | Guard: <phasePlaybook.guardPrerequisites> Validation scripts: <phasePlaybook.validationScripts joined>

技能: <phasePlaybook.skillRef 或 "此阶段无工作手册"> 工具: <phasePlaybook.tools 以项目符号形式呈现> 模型必须触发的事件: <phasePlaybook.events 以项目符号形式呈现 — 例如

task.progressed

phase.advanced

> 自动触发的事件（运行时触发）: <phasePlaybook.autoEmittedEvents 以项目符号形式呈现> 转换条件: <phasePlaybook.transitionCriteria> | 守卫条件: <phasePlaybook.guardPrerequisites> 验证脚本: <phasePlaybook.validationScripts 拼接显示>

Event Emission Hints

事件触发提示

<_eventHints.missing rendered as bullets, or "(none — phase machinery satisfied)">

<_eventHints.missing 以项目符号形式呈现，或显示"(无 — 阶段机制已满足)">

Resume Instructions

恢复说明

To continue this workflow in a new session, run

rehydrate

— or start the harness fresh, and the SessionStart hook will auto-discover active workflows.

Discipline reminder: every task transition this turn forward MUST land on the workflow event stream via
exarchos_event.append
or
delegate
subagent emission. Direct
Edit
/
Bash
/
git
actions on task branches without corresponding events will desync the workflow tracker (see RCA
docs/rca/2026-05-08-rehydrate-behavioral-gap.md
).

undefined

要在新会话中继续此工作流，请运行

rehydrate

命令——或重新启动工具，SessionStart钩子会自动发现活跃工作流。

纪律提醒: 后续的每一次任务转换都必须通过
exarchos_event.append
或
delegate
子Agent触发，写入工作流事件流。直接在任务分支上执行
Edit
/
Bash
/
git
操作而不触发相应事件会导致工作流跟踪器不同步（请参阅RCA文档
docs/rca/2026-05-08-rehydrate-behavioral-gap.md
）。

undefined

Auto-Checkpoint Triggers

自动Checkpoint触发条件

Suggest a checkpoint when:

After
delegate
completes — all tasks done, before review
After a PR is created — in
```
synthesize
```
, before the feedback loop
After 3+ feedback iterations — context-accumulation risk
When the user mentions context issues — proactive save

在以下场景建议执行checkpoint：

delegate
完成后 — 所有任务完成，评审前
PR创建后 — 在
```
synthesize
```
阶段，反馈循环前
3次以上反馈迭代后 — 存在上下文累积风险
用户提及上下文问题时 — 主动保存

Best Practices

最佳实践

Update often - State should reflect reality at all times
Use MCP tools - Prefer checkpoint MCP tools over manual JSON editing
Reconcile on resume - Always verify state matches git state (see
```
@skills/rehydrate/SKILL.md
```
)
Checkpoint at boundaries - Save state before likely context exhaustion
Read state, don't remember - After summarization, read from state (see
```
@skills/rehydrate/SKILL.md
```
)

频繁更新 - 状态应始终反映实际情况
使用MCP工具 - 优先使用checkpoint MCP工具，而非手动编辑JSON
恢复时协调 - 始终验证状态与git状态是否匹配（请参阅
```
@skills/rehydrate/SKILL.md
```
）
在边界处执行Checkpoint - 在可能出现上下文耗尽前保存状态
读取状态，而非记忆 - 总结后从状态中读取信息（请参阅
```
@skills/rehydrate/SKILL.md
```
）

Troubleshooting

故障排除

MCP Tool Call Failed

MCP工具调用失败

If an Exarchos MCP tool returns an error:

Check the error message — it usually contains specific guidance
Verify the workflow state exists: call
```
exarchos:exarchos_workflow
```
with
```
action: "get"
```
and the featureId
If "version mismatch": another process updated state — retry the operation

If state is corrupted: call

exarchos:exarchos_workflow

with

action: "cancel"

and

dryRun: true

如果Exarchos MCP工具返回错误：

查看错误消息——通常包含具体指导
验证工作流状态是否存在：调用
```
exarchos:exarchos_workflow
```
并设置
```
action: "get"
```
和对应的featureId
如果出现“版本不匹配”：其他进程已更新状态——重试操作

如果状态损坏：调用

exarchos:exarchos_workflow

并设置

action: "cancel"

和

dryRun: true

Checkpoint Missing

Checkpoint缺失

checkpoint

is invoked with no active workflow:

Discovery first: call
```
exarchos:exarchos_workflow
```
with
```
action: "list"
```
to enumerate active workflows; if the list is empty the checkpoint command's "no active workflow" report is correct — exit cleanly

list

returns a candidate, verify it: call

exarchos:exarchos_workflow

with

action: "get"

and that

featureId

If a workflow exists but checkpoint fails: check disk space and permissions on the event store

如果调用

checkpoint

时没有活跃工作流：

先进行发现：调用
```
exarchos:exarchos_workflow
```
并设置
```
action: "list"
```
枚举活跃工作流；如果列表为空，则checkpoint命令报告的“无活跃工作流”正确——正常退出
如果
```
list
```
返回候选工作流，验证它：调用
```
exarchos:exarchos_workflow
```
并设置
```
action: "get"
```
和对应的
```
featureId
```
如果工作流存在但checkpoint失败：检查事件存储的磁盘空间和权限

Example Workflow

示例工作流

Start new workflow: Use

exarchos:exarchos_workflow

with

action: "init"

with

featureId: "user-authentication"

workflowType: "feature"

After authoring the Design & Rationale section (

plan

is already the initial phase — no transition):

action: "update"

featureId: "user-authentication"

updates: { "artifacts.spec": "docs/specs/2026-01-05-user-auth.md" }

Save progress before a break: Use
```
checkpoint
```
to capture a structured handoff; resume later with
```
rehydrate
```
(see
```
@skills/rehydrate/SKILL.md
```
).

启动新工作流：使用

exarchos:exarchos_workflow

并设置

action: "init"

，传入

featureId: "user-authentication"

，

workflowType: "feature"

设计与原理部分编写完成后（

plan

已经是初始阶段——无需转换阶段）：

action: "update"

，

featureId: "user-authentication"

，

updates: { "artifacts.spec": "docs/specs/2026-01-05-user-auth.md" }

暂停前保存进度：使用
```
checkpoint
```
捕获结构化交接；后续使用
```
rehydrate
```
恢复（请参阅
```
@skills/rehydrate/SKILL.md
```
）。

checkpoint

Original

Translation

Workflow Checkpoint Skill

Workflow Checkpoint Skill

Overview

概述

Triggers

触发条件

Phase Transitions

阶段转换

Schema Discovery

架构发现

State Location

状态存储位置

State Operations

状态操作

Initialize State

初始化状态

Workflow Types at a Glance

工作流类型概览

Update State (fields only)

更新状态（仅字段）

Transition Phase

阶段转换

Editing the tasks array

编辑tasks数组

Integration Points

集成点

When to Update State

状态更新时机

Oneshot-specific state updates

仅适用于Oneshot的状态更新

Automatic State Updates

自动状态更新

State Schema

状态架构

Reserved fields

保留字段

Structured Handoff Output

结构化交接输出

Checkpoint Saved

已保存检查点

Progress

进度

House Rules (apply every action this turn forward)

规则（后续所有操作均需遵守）

Event Emission Hints

事件触发提示

Resume Instructions

恢复说明

Auto-Checkpoint Triggers

自动Checkpoint触发条件

Best Practices

最佳实践

Troubleshooting

故障排除

MCP Tool Call Failed

MCP工具调用失败

Checkpoint Missing

Checkpoint缺失

Example Workflow

示例工作流

Editing the
`tasks`
array

编辑
`tasks`
数组