oneshot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Oneshot Workflow Skill

Oneshot工作流技能

VCS Provider

VCS提供商

This skill uses VCS operations through Exarchos MCP actions (

create_pr

merge_pr

, etc.) when the synthesize path is taken. 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.

A lean, four-phase workflow type for changes that are too small to justify the full

feature

flow (

plan → plan-review → delegate → review → synthesize → completed

) but still deserve event-sourced auditability and a planning step. The workflow is direct-commit by default with an opt-in PR path; the choice between the two is resolved at the end of

implementing

via a pure event-sourced guard, not a heuristic.

Read this first if you have never run a oneshot: the workflow has a choice state at the end of
implementing
. Whether you land on
completed
(direct commit) or transition through
synthesize
(PR) is decided by two inputs: the
synthesisPolicy
set at init, and whether the user emitted a
synthesize.requested
event during implementing. Both inputs are persisted; the decision is replay-safe.

当走合成（synthesize）路径时，该技能通过Exarchos MCP操作（

create_pr

、

merge_pr

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

gh

glab

az

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

这是一种精简的四阶段工作流类型，适用于那些规模太小、无需完整

feature

流程（

plan → plan-review → delegate → review → synthesize → completed

）但仍需事件溯源可审计性和规划步骤的变更。该工作流默认直接提交，并提供可选的PR路径；两者的选择在

implementing

阶段结束时通过纯事件溯源防护机制决定，而非启发式判断。

如果从未运行过oneshot，请先阅读此内容：工作流在
implementing
阶段结束时有一个选择状态。最终进入
completed
（直接提交）还是过渡到
synthesize
（PR），由两个输入决定：初始化时设置的
synthesisPolicy
，以及用户在实施过程中是否触发了
synthesize.requested
事件。这两个输入都会被持久化；决策结果可安全重放。

When to use oneshot

何时使用oneshot

Reach for oneshot when all of the following are true:

The change is bounded — typically a single file, or a tightly-coupled cluster of 2-3 files
No subagent dispatch is needed — the work fits comfortably in a single in-session implement-and-verify loop
No design document is required — the goal is obvious from the task description, and a one-page plan is enough scaffolding
No two-stage review is required — either the change is trivial enough that direct-commit is acceptable, or a single PR review will suffice

Concrete examples that fit oneshot:

Fixing a typo in a README
Bumping a dependency version
Adding a missing null-check in one function
Tweaking a CI workflow YAML
Renaming a config key everywhere it's referenced
Adding a one-off helper script
Exploratory spikes that may or may not be kept

当所有以下条件都满足时，选择oneshot：

变更范围明确——通常是单个文件，或紧密关联的2-3个文件
无需子代理调度——工作内容可在单个会话的实施与验证循环内完成
无需设计文档——任务描述已明确目标，一页规划足够作为支撑
无需两阶段审核——要么变更足够微小，直接提交即可接受；要么单次PR审核就足够

适合oneshot的具体示例：

修复README中的拼写错误
升级依赖版本
在单个函数中添加缺失的空值检查
调整CI工作流YAML文件
重命名所有引用到的配置键
添加一次性辅助脚本
可能保留也可能丢弃的探索性实验

When NOT to use oneshot

何时不使用oneshot

Do not use oneshot for any of the following — use the full

feature

workflow instead (

ideate

Cross-cutting refactors that touch many files or modules
Multi-file features that benefit from subagent decomposition
Anything that needs design exploration or competing approaches weighed
Anything that needs spec-review + quality-review (two-stage)
Anything that needs to coordinate with another agent team
Changes that should land in stages (stacked PRs)
Anything where you'd want a written design doc to look back at

If you start a oneshot and discover the change is bigger than expected, the right move is

cancel

and restart with

ideate

. Don't try to grow a oneshot into a feature workflow mid-stream; the playbooks have different shapes and you'll fight the state machine.

以下情况请勿使用oneshot——请改用完整的

feature

工作流（

ideate

）：

涉及多个文件或模块的跨领域重构
可通过子代理分解的多文件功能
需要设计探索或权衡多种方案的工作
需要规范审核+质量审核（两阶段）的工作
需要与其他代理团队协调的工作
需要分阶段落地的变更（堆叠PR）
需要留存书面设计文档以供后续参考的工作

如果启动oneshot后发现变更规模超出预期，正确的做法是

cancel

并重新用

ideate

启动。不要尝试在中途将oneshot扩展为feature工作流；两者的流程结构不同，强行修改会与状态机冲突。

Synthesis policy — three options

合成策略——三种选项

The

synthesisPolicy

field on a oneshot workflow declares the user's intent up front about whether the change should be turned into a PR. It takes one of three values, persisted on

state.oneshot.synthesisPolicy

Policy	Behavior	When to use
`always`	Always transition `implementing → synthesize` at finalize, regardless of events. A PR is always created.	The user wants a paper trail / review for every change in this workflow, even small ones.
`never`	Always transition `implementing → completed` at finalize, regardless of events. No PR is created — commits go directly to the current branch.	The user is iterating on personal/scratch work and explicitly opts out of PRs.
`on-request` (default)	Direct-commit by default. The user can opt in to a PR mid-implementing by calling `request_synthesize` ; if any `synthesize.requested` event is on the stream at finalize, the workflow transitions to `synthesize` instead of `completed` .	The common case: start with the assumption of direct-commit, but leave the door open for the user to change their mind once they see the diff.

The default is

on-request

because it's the least surprising: the user gets the lightweight path until they explicitly ask for the heavy one.

Policy wins over event. If

synthesisPolicy: 'never'

is set and a

synthesize.requested

event is somehow on the stream (e.g. the user called the action on a workflow they thought was

on-request

), the guard still routes to

completed

. Policy is the user's declared intent and overrides runtime signal.

oneshot工作流的

synthesisPolicy

字段用于提前声明用户是否希望将变更转为PR。它有三个可选值，会被持久化到

state.oneshot.synthesisPolicy

：

策略	行为	使用场景
`always`	最终确定时始终从 `implementing` 过渡到 `synthesize` ，不受事件影响。始终创建PR。	用户希望此工作流中的每一项变更都有记录/审核，即使是微小变更。
`never`	最终确定时始终从 `implementing` 过渡到 `completed` ，不受事件影响。不创建PR——提交直接推送到当前分支。	用户正在进行个人/临时工作，明确选择不使用PR。
`on-request` （默认）	默认直接提交。用户可在实施过程中调用 `request_synthesize` 选择启用PR；如果最终确定时事件流中存在任何 `synthesize.requested` 事件，工作流将过渡到 `synthesize` 而非 `completed` 。	常见场景：默认采用轻量路径，但保留用户看到差异后改变主意的可能性。

默认值为

on-request

，因为它最符合预期：用户先使用轻量路径，直到明确要求使用更复杂的路径。

策略优先级高于事件。如果设置了

synthesisPolicy: 'never'

，但事件流中存在

synthesize.requested

事件（例如用户在以为是

on-request

的工作流上调用了该操作），防护机制仍会路由到

completed

。策略是用户明确声明的意图，会覆盖运行时信号。

Lifecycle

生命周期

text

     plan ──────► implementing ──┬── [synthesisOptedOut] ──► completed
                                 │
                                 └── [synthesisOptedIn]  ──► synthesize ──► completed

Four phases. The fork after

implementing

is a UML choice state, implemented via two mutually-exclusive HSM transitions whose guards are pure functions of

state.oneshot.synthesisPolicy

and the

synthesize.requested

event count.

Phase	What happens	Exit criteria
`plan`	Lightweight one-page plan: goal, approach, files to touch, tests to add. No design doc. No subagent dispatch.	`artifacts.plan` set → transition to `implementing`
`implementing`	In-session loop, verification scaled to risk. Defaults to the low tier (static analysis suffices); higher-blast changes add tests covering the changed behavior (test-after) under the `check_test_adequacy` kill-probe. Commit as you go.	Tests pass + typecheck clean + finalize_oneshot called
`synthesize`	Reached only when `synthesisOptedIn` is true. Hands off to the existing synthesis flow — see `@skills/synthesize/SKILL.md` . PR created via `exarchos_orchestrate({ action: "create_pr" })` , auto-merge enabled, CI gates apply.	PR merged → `completed`
`completed`	Terminal. For direct-commit path, commits are already on the branch — there's nothing more to do. For synthesize path, the PR merge event terminates the workflow.	—

cancelled

is also reachable from any phase via the universal cancel transition, same as every other workflow type.

text

     plan ──────► implementing ──┬── [synthesisOptedOut] ──► completed
                                 │
                                 └── [synthesisOptedIn]  ──► synthesize ──► completed

四个阶段。

implementing

之后的分支是UML的选择状态，通过两个互斥的HSM过渡实现，其防护机制是

state.oneshot.synthesisPolicy

和

synthesize.requested

事件数量的纯函数。

阶段	操作内容	退出条件
`plan`	轻量级一页规划：目标、方案、涉及文件、需添加的测试。无需设计文档。无需子代理调度。	设置 `artifacts.plan` → 过渡到 `implementing`
`implementing`	会话内循环，验证级别与风险匹配。默认采用低级（仅静态分析即可）；影响范围较大的变更需添加覆盖变更行为的测试（事后测试），并受 `check_test_adequacy` 终止探针检查。边做边提交。	测试通过 + 类型检查无问题 + 调用finalize_oneshot
`synthesize`	仅当 `synthesisOptedIn` 为true时进入。移交至现有合成流程——详见 `@skills/synthesize/SKILL.md` 。通过 `exarchos_orchestrate({ action: "create_pr" })` 创建PR，启用自动合并，应用CI检查。	PR合并 → `completed`
`completed`	终止状态。对于直接提交路径，提交已在分支上——无需额外操作。对于合成路径，PR合并事件会终止工作流。	—

与其他所有工作流类型相同，从任何阶段都可通过通用取消过渡进入

cancelled

状态。

Step-by-step

分步指南

Step 1 — Init

步骤1 — 初始化

Call

exarchos_workflow

with

action: 'init'

workflowType: 'oneshot'

, and an optional

synthesisPolicy

typescript

exarchos:exarchos_workflow({
  action: "init",
  featureId: "fix-readme-typo",
  workflowType: "oneshot",
  synthesisPolicy: "on-request" // optional — defaults to 'on-request'
})

If the user has been clear up front ("I want a PR for this"), pass

synthesisPolicy: "always"

. If they've been clear ("don't open a PR, just commit it"), pass

synthesisPolicy: "never"

. Otherwise, omit the field and rely on the

on-request

default — you can always escalate later in the implementing phase.

The init returns the new workflow state; the workflow lands in

plan

调用

exarchos_workflow

，设置

action: 'init'

、

workflowType: 'oneshot'

，并可选设置

synthesisPolicy

：

typescript

exarchos:exarchos_workflow({
  action: "init",
  featureId: "fix-readme-typo",
  workflowType: "oneshot",
  synthesisPolicy: "on-request" // 可选——默认值为'on-request'
})

如果用户提前明确要求（"我想为此创建PR"），则设置

synthesisPolicy: "always"

。如果用户明确表示（"不要开PR，直接提交"），则设置

synthesisPolicy: "never"

。否则省略该字段，依赖

on-request

默认值——可在实施阶段后期再升级。

初始化会返回新的工作流状态；工作流进入

plan

阶段。

Step 2 — Plan phase

步骤2 — 规划阶段

Produce a one-page plan. This is intentionally lightweight — no design doc, no parallelization analysis, no decomposition into N tasks. The plan should answer four questions in 5-10 lines each:

Goal — what is the user trying to accomplish?
Approach — what's the one-line implementation strategy?
Files — which files will be touched? (1-5 typically)
Tests — which test cases will be added? (named, not described)

Persist the plan, then transition to

implementing

. Field mutation and phase mutation are separate actions:

update

writes the plan artifacts (

phase

is a reserved field

update

cannot touch), then

transition

advances the phase — guards read the most recent state, so the plan lands before the

oneshot-plan-set

guard evaluates:

typescript

exarchos:exarchos_workflow({
  action: "update",
  featureId: "fix-readme-typo",
  updates: {
    "artifacts.plan": "<plan text>",
    "oneshot.planSummary": "<one-line summary>"
  }
})

exarchos:exarchos_workflow({
  action: "transition",
  featureId: "fix-readme-typo",
  target: "implementing"
})

The plan goes on

artifacts.plan

for parity with the

feature

workflow; the human-readable one-liner goes on

oneshot.planSummary

for the pipeline view. Only

artifacts.plan

is enforced by the

oneshot-plan-set

guard —

planSummary

is an optional pipeline-view label and is not a substitute for a real plan artifact.

生成一页规划。这是故意设计得轻量的——无需设计文档、无需并行化分析、无需分解为多个任务。规划应回答四个问题，每个问题用5-10行描述：

目标——用户想要完成什么？
方案——一行描述实现策略？
文件——会涉及哪些文件？（通常1-5个）
测试——会添加哪些测试用例？（只需命名，无需详细描述）

保存规划，然后过渡到

implementing

阶段。字段更新和阶段更新是独立操作：

update

写入规划工件（

phase

是保留字段，

update

无法修改），然后

transition

推进阶段——防护机制会读取最新状态，因此规划会在

oneshot-plan-set

防护机制评估前保存：

typescript

exarchos:exarchos_workflow({
  action: "update",
  featureId: "fix-readme-typo",
  updates: {
    "artifacts.plan": "<规划文本>",
    "oneshot.planSummary": "<一行摘要>"
  }
})

exarchos:exarchos_workflow({
  action: "transition",
  featureId: "fix-readme-typo",
  target: "implementing"
})

规划存储在

artifacts.plan

中，与

feature

工作流保持一致；人类可读的一行摘要存储在

oneshot.planSummary

中，用于流水线视图。

oneshot-plan-set

防护机制仅强制要求

artifacts.plan

——

planSummary

是可选的流水线视图标签，不能替代真正的规划工件。

Step 3 — Implementing phase

步骤3 — 实施阶段

Run an in-session loop, with verification scaled to the change's risk (the ladder in

@skills/_shared/references/verification.md

). A oneshot defaults to the low tier — static analysis suffices for a trivial fix. When the change touches a higher-blast surface (schema/type/API/shared contract, or it crosses an I/O boundary), it is a higher-tier task: cover the new/changed behavior with tests (test-after is fine) and expect the

check_test_adequacy

kill-probe to reject tests that cannot actually fail.

For each higher-tier behavior in the plan:

Implement the behavior.
Add the tests its tier requires (scoped tests for the change; an integration test across the seam at high tier), named
```
Method_Scenario_Outcome
```
.
Refactor while the tests stay green.

Granular per-behavior red-green is available as an explicit opt-in, never a requirement.

Commit each logical change as a single atomic commit. Do not batch multiple unrelated changes into one commit — keeping commits atomic matters even more in oneshot, where there's no separate review phase to catch bundled changes.

There is no subagent dispatch in oneshot. The main agent does the work directly. There is no separate review phase. Quality is maintained by the tier-scaled verification (static analysis plus, above the low tier, the

check_test_adequacy

kill-probe) and (if the user opts in) the synthesize PR review.

运行会话内循环，验证级别与变更风险匹配（详见

@skills/_shared/references/verification.md

中的验证阶梯）。oneshot默认采用低级——微小修复只需静态分析。当变更影响范围较大（涉及 schema/类型/API/共享契约，或跨越I/O边界）时，属于更高层级任务：需添加覆盖新/变更行为的测试（事后测试即可），且

check_test_adequacy

终止探针会标记无法实际失败的测试。

对于规划中的每个高层级行为：

实现该行为。
添加该层级要求的测试（针对变更的范围测试；高层级需跨边界的集成测试），命名格式为
```
Method_Scenario_Outcome
```
。
在测试保持通过的前提下进行重构。

细粒度的逐行为红-绿测试是可选的显式操作，而非强制要求。

每个逻辑变更作为单独的原子提交。不要将多个无关变更批量提交到一个提交中——即使在oneshot中，保持提交原子性也至关重要，因为这里没有单独的审核阶段来发现捆绑的变更。

oneshot中无子代理调度。主代理直接完成工作。无单独的审核阶段。质量通过层级匹配的验证（静态分析，以及高于低级时的

check_test_adequacy

终止探针）和（如果用户选择启用）合成PR审核来保证。

Mid-workflow: opting in to a PR

工作流中途：选择启用PR

If at any point during

plan

implementing

the user decides they want a PR after all (policy is

on-request

, default), they can opt in by calling the

request_synthesize

orchestrate action:

typescript

exarchos:exarchos_orchestrate({
  action: "request_synthesize",
  featureId: "fix-readme-typo",
  reason: "user requested review of the parser changes"
})

The trigger for this is conversational, not a magic keyword. Listen for phrases like:

"actually, let's open a PR for this"
"I want a review on this before it lands"
"make this a PR"
"let's get eyes on this"
"synthesize this"

When you hear any of those, call

request_synthesize

immediately. The handler appends a

synthesize.requested

event to the workflow's event stream; the

synthesisOptedIn

guard reads the stream at finalize and routes accordingly.

request_synthesize

is accepted from both

plan

and

implementing

phases — call it whenever you know you want the PR path, even before

implementing

starts. Terminal phases (

synthesize

completed

cancelled

) are rejected.

Duplicate calls are routing-idempotent but not event-idempotent: each call appends a new

synthesize.requested

event, but the guard treats any count >= 1 as "opted in", so the routing decision is the same whether you call once or five times. The event stream will contain each duplicate for audit purposes.

Calling

request_synthesize

does not transition the phase. The workflow stays in its current phase. The decision is only acted on when you call

finalize_oneshot

in step 4.

如果在

plan

或

implementing

阶段的任何时候，用户决定需要PR（策略为

on-request

，即默认值），他们可通过调用

request_synthesize

编排操作来选择启用：

typescript

exarchos:exarchos_orchestrate({
  action: "request_synthesize",
  featureId: "fix-readme-typo",
  reason: "user requested review of the parser changes"
})

触发此操作的是对话内容，而非魔法关键词。留意以下类似表述：

"实际上，我们为此开个PR吧"
"我希望在落地前对此进行审核"
"把这个做成PR"
"让大家看看这个"
"synthesize this"

听到这些表述时，立即调用

request_synthesize

。处理器会将

synthesize.requested

事件追加到工作流的事件流中；

synthesisOptedIn

防护机制会在最终确定时读取事件流并相应路由。

request_synthesize

可在

plan

和

implementing

阶段调用——只要确定需要PR路径，即使在

implementing

开始前也可调用。终止阶段（

synthesize

、

completed

、

cancelled

）会拒绝该操作。

重复调用路由幂等但事件不幂等：每次调用都会追加新的

synthesize.requested

事件，但防护机制会将任何数量>=1的情况视为“已选择启用”，因此路由决策与调用一次或五次相同。事件流会保留所有重复调用，以供审计。

调用

request_synthesize

不会改变阶段。工作流仍处于当前阶段。只有在步骤4调用

finalize_oneshot

时，才会执行该决策。

Step 4 — Finalize (the choice point)

步骤4 — 最终确定（选择点）

When the implementing loop is done — tests pass, typecheck clean, all commits made — call

finalize_oneshot

to resolve the choice state:

typescript

exarchos:exarchos_orchestrate({
  action: "finalize_oneshot",
  featureId: "fix-readme-typo"
})

The handler:

Reads the current state and verifies

workflowType === 'oneshot'

and

phase === 'implementing'

Hydrates
```
_events
```
from the event store so the guard sees the same view the HSM will see during the actual transition.

Evaluates

guards.synthesisOptedIn

against the state. The guard inspects

state.oneshot.synthesisPolicy

and the

_events

array.

Calls
```
handleSet
```
with the resolved target phase (
```
synthesize
```
or
```
completed
```
). The HSM re-evaluates the guard at the transition boundary, so any race between the read and the transition is caught safely.

Possible outcomes:

`synthesisPolicy`	`synthesize.requested` event present?	Resolved target	Path
`always`	(any)	`synthesize`	PR path
`never`	(any)	`completed`	direct-commit path
`on-request` (default)	yes	`synthesize`	PR path
`on-request` (default)	no	`completed`	direct-commit path

当实施循环完成——测试通过、类型检查无问题、所有提交已完成——调用

finalize_oneshot

来解析选择状态：

typescript

exarchos:exarchos_orchestrate({
  action: "finalize_oneshot",
  featureId: "fix-readme-typo"
})

处理器会：

读取当前状态，验证

workflowType === 'oneshot'

且

phase === 'implementing'

。

从事件存储中加载
```
_events
```
，使防护机制看到与HSM在实际过渡时相同的视图。

根据状态评估

guards.synthesisOptedIn

。防护机制会检查

state.oneshot.synthesisPolicy

和

_events

数组。

调用
```
handleSet
```
并传入解析后的目标阶段（
```
synthesize
```
或
```
completed
```
）。HSM会在过渡边界重新评估防护机制，因此读取和过渡之间的任何竞争都会被安全捕获。

可能的结果：

`synthesisPolicy`	是否存在 `synthesize.requested` 事件	解析后的目标	路径
`always`	（任意）	`synthesize`	PR路径
`never`	（任意）	`completed`	直接提交路径
`on-request` （默认）	是	`synthesize`	PR路径
`on-request` （默认）	否	`completed`	直接提交路径

Step 5a — Direct-commit path (terminal)

步骤5a — 直接提交路径（终止）

If finalize resolved to

completed

, you're done. The commits made during implementing are already on the current branch. Push them if they aren't already pushed:

bash

git push

The workflow is now in

completed

and will not appear in the default pipeline view. Report completion:

markdown

undefined

如果最终确定解析为

completed

，则工作完成。实施过程中创建的提交已在当前分支上。如果尚未推送，则推送：

bash

git push

工作流现在处于

completed

状态，不会出现在默认流水线视图中。报告完成：

markdown

undefined

Oneshot Complete (direct-commit)

Oneshot完成（直接提交）

Workflow: <featureId> Plan: <one-line summary> Tests added: N Commits: <hash list> Path: direct-commit

undefined

工作流：<featureId> 规划：<一行摘要> 添加测试数量：N 提交：<哈希列表> 路径：直接提交

undefined

Step 5b — Synthesize path

步骤5b — 合成路径

If finalize resolved to

synthesize

, hand off to the standard synthesis flow — see

@skills/synthesize/SKILL.md

. The same

prepare_synthesis

validate_pr_body

create_pr

machinery used by the

feature

workflow applies. After the PR merges, the workflow transitions

synthesize → completed

via the existing

mergeVerified

guard, same as every other workflow type.

You do not need to run

delegate

review

for an opt-in oneshot synthesize. Those phases do not exist in the oneshot playbook. The PR review is the only review. Report completion:

markdown

undefined

如果最终确定解析为

synthesize

，则移交至标准合成流程——详见

@skills/synthesize/SKILL.md

。

feature

工作流使用的

prepare_synthesis

validate_pr_body

create_pr

机制同样适用。PR合并后，工作流会通过现有的

mergeVerified

防护机制从

synthesize

过渡到

completed

，与其他所有工作流类型相同。

对于选择启用的oneshot合成，无需运行

delegate

或

review

。这些阶段不存在于oneshot流程中。PR审核是唯一的审核环节。报告完成：

markdown

undefined

Oneshot Complete (synthesize)

Oneshot完成（合成）

Workflow: <featureId> PR: <url> Tests: X pass | Build: 0 errors Path: synthesize → PR review → merge

undefined

工作流：<featureId> PR：<链接> 测试：X通过 | 构建：0错误路径：合成→PR审核→合并

undefined

Example invocations

示例调用

Example A — Direct-commit (default

on-request

policy, no opt-in)

示例A — 直接提交（默认

on-request

策略，未选择启用）

text

User: "Quick fix — there's a typo in the README, 'recieve' should be 'receive'.
       Use oneshot."

Agent:
  1. exarchos_workflow init { featureId: "fix-readme-typo", workflowType: "oneshot" }
     → workflow created in 'plan' phase, synthesisPolicy defaults to 'on-request'
  2. Produces a 4-line plan: goal=fix typo, approach=sed, files=[README.md],
     tests=[readme has no occurrence of 'recieve']
  3. exarchos_workflow update {
       featureId: "fix-readme-typo",
       phase: "implementing",                   // top-level
       updates: {
         "artifacts.plan": "...",
         "oneshot.planSummary": "..."
       }
     }
  4. edits README, fixes typo (low tier — a docs one-liner; static analysis
        suffices, no test-first ceremony)
  5. verifies: greps README for 'recieve' → 0 matches
  6. git commit -m "docs: fix 'recieve' typo in README"
  7. exarchos_orchestrate finalize_oneshot { featureId: "fix-readme-typo" }
     → guard sees policy='on-request' + no synthesize.requested event
     → resolves to 'completed'
  8. git push
     "Done. Workflow completed via direct-commit path."

text

用户："快速修复——README里有个拼写错误，'recieve'应该改成'receive'。用oneshot。"

代理：
  1. 调用exarchos_workflow init { featureId: "fix-readme-typo", workflowType: "oneshot" }
     → 创建工作流，进入'plan'阶段，synthesisPolicy默认值为'on-request'
  2. 生成4行规划：目标=修复拼写错误，方案=sed命令，文件=[README.md]，测试=[readme中无'receive'以外的拼写]
  3. 调用exarchos_workflow update {
       featureId: "fix-readme-typo",
       phase: "implementing",                   // 顶级字段
       updates: {
         "artifacts.plan": "...",
         "oneshot.planSummary": "..."
       }
     }
  4. 编辑README，修复拼写错误（低级——文档单行修改；仅静态分析即可，无需测试前置流程）
  5. 验证：在README中搜索'receive'以外的拼写→0匹配
  6. git commit -m "docs: fix 'recieve' typo in README"
  7. 调用exarchos_orchestrate finalize_oneshot { featureId: "fix-readme-typo" }
     → 防护机制看到policy='on-request'且无synthesize.requested事件
     → 解析为'completed'
  8. git push
     "完成。工作流通过直接提交路径结束。"

Example B — Mid-implementing opt-in (

on-request

→ user changes mind)

示例B — 实施中途选择启用（

on-request

→用户改变主意）

text

User: "Add input validation to the parseConfig helper. Oneshot."

Agent:
  1. exarchos_workflow init { workflowType: "oneshot" }
     → 'plan' phase, default 'on-request'
  2. plans (goal: validate input, files: [parser.ts, parser.test.ts])
  3. transitions to 'implementing'
  4. adds the null-input validation to parseConfig
  5. adds a test for the null-input case (test-after)
  6. refactors: extracts validateInput helper (tests stay green)
  7. commits

User: "Actually, this is touching the parser — I want a review on it before
       it lands."

Agent:
  8. exarchos_orchestrate request_synthesize {
       featureId, reason: "user requested review of parser changes"
     }
     → appends synthesize.requested event
  9. exarchos_orchestrate finalize_oneshot { featureId }
     → guard sees policy='on-request' + 1 synthesize.requested event
     → resolves to 'synthesize'
 10. hands off to @skills/synthesize/SKILL.md → prepare_synthesis →
     validate_pr_body → create_pr → merge

text

用户："给parseConfig助手添加输入验证。用oneshot。"

代理：
  1. 调用exarchos_workflow init { workflowType: "oneshot" }
     → 'plan'阶段，默认'on-request'
  2. 规划（目标：验证输入，文件：[parser.ts, parser.test.ts]）
  3. 过渡到'implementing'
  4. 给parseConfig添加空输入验证
  5. 添加空输入案例的测试（事后测试）
  6. 重构：提取validateInput助手（测试保持通过）
  7. 提交

用户："实际上，这个改动涉及解析器——我希望在落地前进行审核。"

代理：
  8. 调用exarchos_orchestrate request_synthesize {
       featureId, reason: "user requested review of parser changes"
     }
     → 追加synthesize.requested事件
  9. 调用exarchos_orchestrate finalize_oneshot { featureId }
     → 防护机制看到policy='on-request'且有1个synthesize.requested事件
     → 解析为'synthesize'
 10. 移交至@skills/synthesize/SKILL.md → prepare_synthesis →
     validate_pr_body → create_pr → merge

Example C —

synthesisPolicy: 'always'

(PR mandatory)

示例C —

synthesisPolicy: 'always'

（强制PR）

text

User: "I want a PR for any change to the auth module, even small ones.
       Use oneshot but always make a PR."

Agent:
  1. exarchos_workflow init {
       workflowType: "oneshot",
       synthesisPolicy: "always"
     }
  2-7. plan + implement + verify + commits, identical to Example A
  8. exarchos_orchestrate finalize_oneshot { featureId }
     → guard sees policy='always' (short-circuits — no event check needed)
     → resolves to 'synthesize'
  9. synthesis flow → PR

text

用户："对auth模块的任何变更，即使是微小变更，我都想要PR。用oneshot但始终创建PR。"

代理：
  1. 调用exarchos_workflow init {
       workflowType: "oneshot",
       synthesisPolicy: "always"
     }
  2-7. 规划+实施+验证+提交，与示例A完全相同
  8. 调用exarchos_orchestrate finalize_oneshot { featureId }
     → 防护机制看到policy='always'（短路——无需检查事件）
     → 解析为'synthesize'
  9. 合成流程→PR

State management

状态管理

Track oneshot-specific state under the

oneshot

key on the workflow state:

typescript

exarchos:exarchos_workflow({
  action: "update",
  featureId: "<id>",
  updates: {
    "oneshot": {
      "synthesisPolicy": "on-request",
      "planSummary": "Fix off-by-one in pagination helper"
    }
  }
})

The

synthesisPolicy

field is optional and defaults to

'on-request'

per the schema in

servers/exarchos-mcp/src/workflow/schemas.ts

. Setting it explicitly is recommended when the user has stated a preference.

在工作流状态的

oneshot

键下跟踪oneshot特定状态：

typescript

exarchos:exarchos_workflow({
  action: "update",
  featureId: "<id>",
  updates: {
    "oneshot": {
      "synthesisPolicy": "on-request",
      "planSummary": "Fix off-by-one in pagination helper"
    }
  }
})

synthesisPolicy

字段是可选的，根据

servers/exarchos-mcp/src/workflow/schemas.ts

中的 schema，默认值为

'on-request'

。当用户已明确偏好时，建议显式设置该字段。

Phase Transitions and Guards

阶段过渡与防护机制

For the full transition table for oneshot, consult

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

Note: The engine's
exarchos_workflow describe playbook="oneshot"
output and the HSM definitions in
hsm-definitions.ts
are the canonical sources for transition behavior.
phase-transitions.md
is a prose reference that can drift — when discrepancies arise, prefer engine
describe
output.

Quick reference for oneshot:

From	To	Guard
`plan`	`implementing`	`oneshotPlanSet` (requires non-empty `artifacts.plan` )
`implementing`	`synthesize`	`synthesisOptedIn`
`implementing`	`completed`	`synthesisOptedOut`
`synthesize`	`completed`	`mergeVerified`
(any)	`cancelled`	universal — always allowed

synthesisOptedIn

and

synthesisOptedOut

are pure functions of

state.oneshot.synthesisPolicy

and

state._events

. They are mutually exclusive across all 4 meaningful combinations —

always

and

never

each map to one outcome (ignoring the event flag), and

on-request

branches on whether a

synthesize.requested

event is present or absent. Exactly one guard returns true at any given time.

关于oneshot的完整过渡表，请查阅

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

。

注意：引擎的
exarchos_workflow describe playbook="oneshot"
输出和
hsm-definitions.ts
中的HSM定义是过渡行为的权威来源。
phase-transitions.md
是 prose 参考文档，可能会有偏差——当出现差异时，以引擎
describe
输出为准。

oneshot快速参考：

来源阶段	目标阶段	防护机制
`plan`	`implementing`	`oneshotPlanSet` （要求 `artifacts.plan` 非空）
`implementing`	`synthesize`	`synthesisOptedIn`
`implementing`	`completed`	`synthesisOptedOut`
`synthesize`	`completed`	`mergeVerified`
（任意）	`cancelled`	通用——始终允许

synthesisOptedIn

和

synthesisOptedOut

是

state.oneshot.synthesisPolicy

和

state._events

的纯函数。在所有4种有意义的组合中，它们是互斥的——

always

和

never

分别对应一种结果（忽略事件标志），而

on-request

会根据是否存在

synthesize.requested

事件分支。任何时候都只有一个防护机制返回true。

Schema discovery

Schema发现

Use

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

for parameter schemas (including the

synthesisPolicy

enum) and

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

for the phase transitions, guard names, and playbook prose. Use

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

for the orchestrate action schemas.

使用

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

获取参数schema（包括

synthesisPolicy

枚举），使用

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

获取阶段过渡、防护机制名称和流程说明。使用

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

获取编排操作schema。

Verification scales with risk

验证级别随风险调整

The verification ladder from

@skills/_shared/references/verification.md

applies to oneshot. A oneshot defaults to the cheap (low) tier — a one-line fix or config tweak leans on static analysis (typecheck + lint), no test-first ceremony — unless risk signals say otherwise. Specifically:

A low-risk change (docs/config/rename-only, near-zero blast radius) needs only static analysis to pass; add a focused test only if behavior is non-obvious.
If the change touches a higher-blast surface (schema/type/API/shared contract, or it crosses an I/O boundary), it is not a low-tier task: cover the new/changed behavior with tests (test-after is fine), and expect the
```
check_test_adequacy
```
kill-probe to flag tests that cannot actually fail.
Commits stay atomic — one logical change per commit, regardless of tier.

The temptation in a oneshot is to assume everything is "just one line" and skip verification entirely. Resist that for anything past the low tier. The point of oneshot is auditability at the right cost — not zero verification, and not the full feature ceremony on a trivial edit.

@skills/_shared/references/verification.md

中的验证阶梯适用于oneshot。oneshot默认采用低成本（低级）验证——单行修复或配置调整依赖静态分析（类型检查+ lint），无需测试前置流程——除非风险信号表明需要更高级别。具体来说：

低风险变更（仅文档/配置/重命名，影响范围极小）只需静态分析通过；只有当行为不明显时才需添加针对性测试。
如果变更影响范围较大（涉及schema/类型/API/共享契约，或跨越I/O边界），则不属于低级任务：需添加覆盖新/变更行为的测试（事后测试即可），且
```
check_test_adequacy
```
终止探针会标记无法实际失败的测试。
提交保持原子性——无论级别如何，每个提交对应一个逻辑变更。

在oneshot中，容易误以为所有变更都是“单行修改”而完全跳过验证。对于低级以上的变更，要抵制这种诱惑。oneshot的意义是以合适的成本实现可审计性——不是零验证，也不是对微小修改采用完整的feature流程。

Anti-patterns

反模式

Don't	Do Instead
Skip the plan phase ("it's obvious")	Write the four-line plan anyway — it's the artifact future-you reads
Apply full red-green-refactor ceremony to a trivial one-liner	Match verification to risk: low-tier leans on static analysis; higher-blast changes add tests covering the changed behavior
Skip verification entirely because "it's a oneshot"	Even low-tier must pass static analysis; higher-blast changes still need tests covering the changed behavior
Use oneshot for multi-file refactors	Use `ideate` and the full feature workflow
Try to grow a oneshot into a feature workflow mid-stream	Cancel and restart with `ideate`
Call `request_synthesize` without listening for the user's intent	Wait for the user to ask for a PR, then call it
Bundle unrelated changes into one commit "since it's a oneshot"	Keep commits atomic — there's no review phase to catch bundling
Forget to call `finalize_oneshot` at the end	The workflow stays in `implementing` forever otherwise — call it explicitly

不要做	应该做
跳过规划阶段（“这很明显”）	仍要写四行规划——这是未来的你会查看的工件
对微小单行修改采用完整的红-绿-重构流程	验证级别与风险匹配：低级依赖静态分析；影响范围较大的变更添加覆盖变更行为的测试
因为“这是oneshot”而完全跳过验证	即使低级也必须通过静态分析；影响范围较大的变更仍需添加覆盖变更行为的测试
对多文件重构使用oneshot	使用 `ideate` 和完整的feature工作流
尝试在中途将oneshot扩展为feature工作流	取消并重新用 `ideate` 启动
未倾听用户意图就调用 `request_synthesize`	等待用户要求PR后再调用
因为“这是oneshot”而将无关变更捆绑到一个提交中	保持提交原子性——这里没有审核阶段来发现捆绑的变更
结束时忘记调用 `finalize_oneshot`	否则工作流会永远停留在 `implementing` 阶段——要显式调用

Completion criteria

完成标准

exarchos_workflow init

called with

workflowType: "oneshot"

One-page plan persisted to
```
artifacts.plan
```
Phase transitioned to
```
implementing
```
All planned behaviors implemented and verified to their risk tier, with atomic commits
```
finalize_oneshot
```
called and resolved to either
```
completed
```
or
```
synthesize
```
If direct-commit path: commits pushed
If synthesize path: PR created via
```
@skills/synthesize/SKILL.md
```
and merged

已调用

exarchos_workflow init

并设置

workflowType: "oneshot"

一页规划已保存到
```
artifacts.plan
```
已过渡到
```
implementing
```
阶段
所有规划的行为已按对应风险级别实现并验证，提交为原子提交
已调用
```
finalize_oneshot
```
并解析为
```
completed
```
或
```
synthesize
```
如果是直接提交路径：已推送提交
如果是合成路径：已通过
```
@skills/synthesize/SKILL.md
```
创建PR并合并

oneshot

Original

Translation

Oneshot Workflow Skill

Oneshot工作流技能

VCS Provider

VCS提供商

When to use oneshot

何时使用oneshot

When NOT to use oneshot

何时不使用oneshot

Synthesis policy — three options

合成策略——三种选项

Lifecycle

生命周期

Step-by-step

分步指南

Step 1 — Init

步骤1 — 初始化

Step 2 — Plan phase

步骤2 — 规划阶段

Step 3 — Implementing phase

步骤3 — 实施阶段

Mid-workflow: opting in to a PR

工作流中途：选择启用PR

Step 4 — Finalize (the choice point)

步骤4 — 最终确定（选择点）

Step 5a — Direct-commit path (terminal)

步骤5a — 直接提交路径（终止）

Oneshot Complete (direct-commit)

Oneshot完成（直接提交）

Step 5b — Synthesize path

步骤5b — 合成路径

Oneshot Complete (synthesize)

Oneshot完成（合成）

Example invocations

示例调用

Example A — Direct-commit (default on-request policy, no opt-in)

示例A — 直接提交（默认on-request策略，未选择启用）

Example B — Mid-implementing opt-in (on-request → user changes mind)

示例B — 实施中途选择启用（on-request→用户改变主意）

Example C — synthesisPolicy: 'always' (PR mandatory)

示例C — synthesisPolicy: 'always'（强制PR）

State management

状态管理

Phase Transitions and Guards

阶段过渡与防护机制

Schema discovery

Schema发现

Verification scales with risk

验证级别随风险调整

Anti-patterns

反模式

Completion criteria

完成标准

Example A — Direct-commit (default
`on-request`
policy, no opt-in)

示例A — 直接提交（默认
`on-request`
策略，未选择启用）

Example B — Mid-implementing opt-in (
`on-request`
→ user changes mind)

示例B — 实施中途选择启用（
`on-request`
→用户改变主意）

Example C —
`synthesisPolicy: 'always'`
(PR mandatory)

示例C —
`synthesisPolicy: 'always'`
（强制PR）