oneshot-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Oneshot Workflow Skill

Oneshot工作流Skill

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 (

ideate → 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流程时，该Skill通过Exarchos MCP操作（

create_pr

、

merge_pr

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

gh

glab

az

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

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

feature

工作流（

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

）的变更，但这类变更仍需具备事件溯源的可审计性和规划步骤。该工作流默认直接提交，同时提供可选的PR流程；两种路径的选择会在

implementing

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

如果您从未运行过oneshot，请先阅读此内容： 该工作流在
implementing
阶段结束时存在一个选择状态。最终进入
completed
（直接提交）还是过渡到
synthesize
（PR），由两个输入决定：初始化时设置的
synthesisPolicy
，以及用户在implementing阶段是否触发了
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 one TDD loop in a single session
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个文件
无需调度子Agent——工作内容可在单次会话的一个TDD循环内完成
无需设计文档——任务描述已明确目标，一页纸的规划即可作为足够的框架
无需两阶段评审——要么变更足够微小，直接提交即可接受；要么仅需一次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

）：

涉及多个文件或模块的跨领域重构
可通过子Agent拆分任务的多文件功能开发
需要进行设计探索或权衡多种方案的工作
需要规范评审+质量评审（两阶段）的工作
需要与其他Agent团队协作的工作
需要分阶段落地的变更（堆叠PR）
需要留存书面设计文档以供后续查阅的工作

如果您启动了Oneshot后发现变更规模超出预期，正确的做法是调用

/cancel

取消，然后用

/ideate

重新开始。请勿尝试在中途将Oneshot扩展为feature工作流；两者的流程模板结构不同，强行扩展会与状态机产生冲突。

Synthesis policy — three options

Synthesis策略——三种选项

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` （默认）	默认直接提交。用户可在implementing阶段通过调用 `request_synthesize` 选择进入PR流程；如果最终阶段的事件流中存在 `synthesize.requested` 事件，工作流会过渡到 `synthesize` 而非 `completed` 。	常见场景：默认采用直接提交方式，但允许用户在看到差异后改变主意，选择PR流程。

默认值为

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 TDD loop. Write a failing test, make it pass, refactor. Commit as you go. The TDD iron law applies — no production code without a failing test first.	Tests pass + typecheck clean + finalize_oneshot called
`synthesize`	Reached only when `synthesisOptedIn` is true. Hands off to the existing synthesis flow — see `@skills/synthesis/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`	制定轻量的一页纸规划：目标、实现方案、涉及文件、需添加的测试。无需设计文档，无需调度子Agent。	设置 `artifacts.plan` → 过渡到 `implementing`
`implementing`	会话内的TDD循环。编写失败的测试，让测试通过，重构代码。边开发边提交。TDD铁律适用——未编写失败测试，不得编写生产代码。	测试通过 + 类型检查无问题 + 调用finalize_oneshot
`synthesize`	仅当 `synthesisOptedIn` 为true时进入此阶段。移交至已有的synthesize流程——详见 `@skills/synthesis/SKILL.md` 。通过 `exarchos_orchestrate({ action: "create_pr" })` 创建PR，启用自动合并，执行CI校验。	PR合并 → `completed`
`completed`	终端阶段。如果是直接提交路径，提交已推送到分支——无需额外操作。如果是synthesize路径，PR合并事件会终止工作流。	—

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

cancelled

状态。

Step-by-step

分步指南

Step 1 — Init

步骤1 — 初始化

Call

exarchos_workflow

with

action: 'init'

workflowType: 'oneshot'

, and an optional

synthesisPolicy

typescript

mcp__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

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

如果用户预先明确要求（“我要为此创建PR”），则传入

synthesisPolicy: "always"

。如果用户明确表示（“不要开PR，直接提交”），则传入

synthesisPolicy: "never"

。否则，省略该字段，使用默认的

on-request

——您可在implementing阶段随时升级为PR流程。

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

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 and transition to

implementing

in a single set call.

phase

is a top-level argument of

set

, not a field inside

updates

typescript

mcp__exarchos__exarchos_workflow({
  action: "set",
  featureId: "fix-readme-typo",
  phase: "implementing",
  updates: {
    "artifacts.plan": "<plan text>",
    "oneshot.planSummary": "<one-line summary>"
  }
})

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个）
测试——会添加哪些测试用例？（只需命名，无需描述）

通过一次set调用持久化规划并过渡到

implementing

阶段。

phase

是

set

的顶级参数，而非

updates

中的字段：

typescript

mcp__exarchos__exarchos_workflow({
  action: "set",
  featureId: "fix-readme-typo",
  phase: "implementing",
  updates: {
    "artifacts.plan": "<plan text>",
    "oneshot.planSummary": "<one-line summary>"
  }
})

规划内容存储在

artifacts.plan

中，与

feature

工作流保持一致；便于人类阅读的一句话摘要存储在

oneshot.planSummary

中，用于流水线视图。只有

artifacts.plan

会被

oneshot-plan-set

守卫机制强制校验——

planSummary

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

Step 3 — Implementing phase

步骤3 — 实现阶段

Run an in-session TDD loop. Same iron law as every other workflow:

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

For each behavior in the plan:

[RED] Write a failing test. Run the test. Confirm it fails for the right reason.
[GREEN] Write the minimum production code to make the test pass. Run the test. Confirm it passes.
[REFACTOR] Clean up while keeping the test green.

Commit each red-green-refactor cycle as a single 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 TDD loop and (if the user opts in) the synthesize PR review.

执行会话内的TDD循环。与其他所有工作流遵循相同的铁律：

未编写失败测试，不得编写生产代码

针对规划中的每个行为：

[RED] 编写一个失败的测试。运行测试，确认测试因预期原因失败。
[GREEN] 编写最少的生产代码使测试通过。运行测试，确认测试通过。
[REFACTOR] 在保持测试通过的前提下清理代码。

将每个红-绿-重构周期作为单个提交。不要将多个无关变更批量提交到一个commit中——在Oneshot中保持提交原子性更为重要，因为Oneshot没有单独的评审阶段来发现捆绑的变更。

Oneshot中不支持子Agent调度。主Agent直接完成工作。没有单独的评审阶段。质量通过TDD循环和（如果用户选择）synthesize 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

mcp__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

编排操作来选择进入PR流程：

typescript

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

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

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

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

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

mcp__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

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

处理器会执行以下操作：

读取当前状态，验证

workflowType === 'oneshot'

且

phase === 'implementing'

。

从事件存储中加载
```
_events
```
，使守卫机制看到与HSM在实际转换时相同的视图。

根据状态评估

guards.synthesisOptedIn

。守卫机制会检查

state.oneshot.synthesisPolicy

和

_events

数组。

使用解析后的目标阶段（
```
synthesize
```
或
```
completed
```
）调用
```
handleSet
```
。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.

如果最终确认解析为

completed

，则工作完成。实现阶段的提交已推送到当前分支。如果尚未推送，执行以下命令：

bash

git push

工作流现在处于

completed

状态，不会出现在默认的流水线视图中。

Step 5b — Synthesize path

步骤5b — Synthesize路径

If finalize resolved to

synthesize

, hand off to the standard synthesis flow — see

@skills/synthesis/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.

如果最终确认解析为

synthesize

，则移交至标准的synthesize流程——详见

@skills/synthesis/SKILL.md

。

feature

工作流使用的

prepare_synthesis

validate_pr_body

create_pr

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

mergeVerified

守卫机制从

synthesize

过渡到

completed

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

对于选择进入的Oneshot synthesize流程，您无需运行

/delegate

或

/review

。这些阶段在Oneshot流程模板中不存在。PR评审是唯一的评审环节。

Example invocations

调用示例

Example A — Direct-commit (default

on-request

policy, no opt-in)

示例A — 直接提交（默认

on-request

策略，未选择PR）

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 set {
       featureId: "fix-readme-typo",
       phase: "implementing",                   // top-level
       updates: {
         "artifacts.plan": "...",
         "oneshot.planSummary": "..."
       }
     }
  4. [RED] writes test that greps README for 'recieve' and expects 0 matches
        — fails (1 match exists)
  5. [GREEN] edits README, fixes typo
        — test passes
  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。”

Agent：
  1. 调用exarchos_workflow init { featureId: "fix-readme-typo", workflowType: "oneshot" }
     → 创建工作流并进入'plan'阶段，synthesisPolicy默认值为'on-request'
  2. 生成4行规划：目标=修复拼写错误，方案=使用sed命令，文件=[README.md]，测试=[README中不存在'recieve']
  3. 调用exarchos_workflow set {
       featureId: "fix-readme-typo",
       phase: "implementing",                   // 顶级参数
       updates: {
         "artifacts.plan": "...",
         "oneshot.planSummary": "..."
       }
     }
  4. [RED] 编写测试脚本，在README中查找'recieve'并期望匹配数为0
        ——测试失败（存在1个匹配项）
  5. [GREEN] 编辑README，修复拼写错误
        ——测试通过
  6. 执行git commit -m "docs: fix 'recieve' typo in README"
  7. 调用exarchos_orchestrate finalize_oneshot { featureId: "fix-readme-typo" }
     → 守卫机制检测到策略为'on-request'且无synthesize.requested事件
     → 解析为'completed'
  8. 执行git push
     “完成。工作流通过直接提交路径结束。”

Example B — Mid-implementing opt-in (

on-request

→ user changes mind)

示例B — 实现中途选择PR（

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. [RED] writes test for null-input case
  5. [GREEN] adds null check
  6. [REFACTOR] extracts validateInput helper
  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/synthesis/SKILL.md → prepare_synthesis →
     validate_pr_body → create_pr → merge

text

用户：“给parseConfig辅助函数添加输入验证。用Oneshot。”

Agent：
  1. 调用exarchos_workflow init { workflowType: "oneshot" }
     → 进入'plan'阶段，默认策略为'on-request'
  2. 制定规划（目标：验证输入，文件：[parser.ts, parser.test.ts]）
  3. 过渡到'implementing'阶段
  4. [RED] 编写空输入场景的测试
  5. [GREEN] 添加空值检查
  6. [REFACTOR] 提取validateInput辅助函数
  7. 提交代码

用户：“实际上，这修改了解析器——我希望在落地前对此进行评审。”

Agent：
  8. 调用exarchos_orchestrate request_synthesize {
       featureId, reason: "user requested review of parser changes"
     }
     → 追加synthesize.requested事件
  9. 调用exarchos_orchestrate finalize_oneshot { featureId }
     → 守卫机制检测到策略为'on-request'且存在1个synthesize.requested事件
     → 解析为'synthesize'
 10. 移交至@skills/synthesis/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 + TDD + 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。”

Agent：
  1. 调用exarchos_workflow init {
       workflowType: "oneshot",
       synthesisPolicy: "always"
     }
  2-7. 规划 + TDD + 提交，与示例A完全相同
  8. 调用exarchos_orchestrate finalize_oneshot { featureId }
     → 守卫机制检测到策略为'always'（直接短路——无需检查事件）
     → 解析为'synthesize'
  9. 进入synthesize流程 → 创建PR

State management

状态管理

Track oneshot-specific state under the

oneshot

key on the workflow state:

typescript

mcp__exarchos__exarchos_workflow({
  action: "set",
  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

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

根据

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

中的 schema，

synthesisPolicy

字段是可选的，默认值为

'on-request'

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

Phase Transitions and Guards

阶段转换与守卫机制

For the full transition table for oneshot, consult

@skills/workflow-state/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/workflow-state/references/phase-transitions.md

。

注意： 引擎的
exarchos_workflow describe playbook="oneshot"
输出以及
hsm-definitions.ts
中的HSM定义是转换行为的权威来源。
phase-transitions.md
是文字参考文档，可能会出现偏差——当出现不一致时，以引擎的
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", "set"] })

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", "set"] })

查看参数schema（包括

synthesisPolicy

枚举）；使用

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

查看阶段转换、守卫名称和流程模板说明；使用

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

查看编排操作的schema。

TDD is still mandatory

TDD仍然是强制要求

The iron law from

@rules/tdd.md

applies to oneshot. There is no exemption for "small" changes. Specifically:

Every behavior change starts with a failing test
Every test must fail before its implementation is written
Tests must be run after each change to verify state
Commits stay atomic — one logical change per commit

The temptation in a oneshot is to skip the test "because it's just one line". Resist that. The test is what makes the change auditable, and auditability is the entire reason oneshot exists alongside the lighter "bypass workflows entirely" path.

@rules/tdd.md

中的铁律同样适用于Oneshot。“微小”变更也不例外。具体要求：

每个行为变更都从编写失败的测试开始
每个测试必须在编写实现代码前失败
每次变更后必须运行测试以验证状态
提交保持原子性——每个提交对应一个逻辑变更

在Oneshot中，很容易因为“只是一行代码”而跳过测试。请抵制这种诱惑。测试是变更具备可审计性的保障，而可审计性正是Oneshot与更轻量的“完全绕过工作流”路径并存的根本原因。

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
Skip the TDD loop in implementing	Always RED → GREEN → REFACTOR, even for one-liners
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

请勿做	正确做法
跳过规划阶段（“这很明显”）	无论如何都要编写四行规划——这是未来的您会查阅的工件
在实现阶段跳过TDD循环	始终遵循RED → GREEN → REFACTOR流程，即使是一行代码的变更
将Oneshot用于多文件重构	使用 `/ideate` 和完整的feature工作流
尝试在中途将Oneshot扩展为feature工作流	取消并使用 `/ideate` 重新开始
未倾听用户意图就调用 `request_synthesize`	等待用户要求创建PR后再调用
因为“这是Oneshot”就将无关变更捆绑到一个提交中	保持提交原子性——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 via TDD 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/synthesis/SKILL.md
```
and merged

调用

exarchos_workflow init

时指定

workflowType: "oneshot"

一页纸规划已持久化到
```
artifacts.plan
```
已过渡到
```
implementing
```
阶段
所有规划的行为已通过TDD实现，且提交保持原子性
已调用
```
finalize_oneshot
```
并解析为
```
completed
```
或
```
synthesize
```
如果是直接提交路径：提交已推送
如果是synthesize路径：已通过
```
@skills/synthesis/SKILL.md
```
创建PR并合并

oneshot-workflow

Original

Translation

Oneshot Workflow Skill

Oneshot工作流Skill

VCS Provider

VCS 提供商

When to use oneshot

何时使用Oneshot

When NOT to use oneshot

何时不使用Oneshot

Synthesis policy — three options

Synthesis策略——三种选项

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 — 直接提交路径（终端）

Step 5b — Synthesize path

步骤5b — Synthesize路径

Example invocations

调用示例

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

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

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

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

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

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

State management

状态管理

Phase Transitions and Guards

阶段转换与守卫机制

Schema discovery

Schema发现

TDD is still mandatory

TDD仍然是强制要求

Anti-patterns

反模式

Completion criteria

完成标准

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

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

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

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

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

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