Oneshot Workflow Skill

VCS Provider

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.

When to use 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

When NOT to use 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.

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.

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.

Step-by-step

Step 1 — Init

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

Step 2 — Plan phase

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.

Step 3 — Implementing phase

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.

Mid-workflow: opting in to a 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.

Step 4 — Finalize (the choice point)

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

Step 5a — Direct-commit path (terminal)

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.

Step 5b — Synthesize path

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.

Example invocations

Example A — Direct-commit (default

on-request

policy, no opt-in)

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."

Example B — Mid-implementing opt-in (

on-request

→ user changes mind)

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

Example C —

synthesisPolicy: 'always'

(PR mandatory)

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

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.

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.

Schema discovery

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.

TDD is still mandatory

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.

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

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

oneshot-workflow

NPX Install

Tags

SKILL.md Content

Oneshot Workflow Skill

VCS Provider

When to use oneshot

When NOT to use oneshot

Synthesis policy — three options

Lifecycle

Step-by-step

Step 1 — Init

Step 2 — Plan phase

Step 3 — Implementing phase

Mid-workflow: opting in to a PR

Step 4 — Finalize (the choice point)

Step 5a — Direct-commit path (terminal)

Step 5b — Synthesize path

Example invocations

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

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

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

State management

Phase Transitions and Guards

Schema discovery

TDD is still mandatory

Anti-patterns

Completion criteria

oneshot-workflow

NPX Install

Tags

SKILL.md Content

Oneshot Workflow Skill

VCS Provider

When to use oneshot

When NOT to use oneshot

Synthesis policy — three options

Lifecycle

Step-by-step

Step 1 — Init

Step 2 — Plan phase

Step 3 — Implementing phase

Mid-workflow: opting in to a PR

Step 4 — Finalize (the choice point)

Step 5a — Direct-commit path (terminal)

Step 5b — Synthesize path

Example invocations

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

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

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

State management

Phase Transitions and Guards

Schema discovery

TDD is still mandatory

Anti-patterns

Completion criteria

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

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

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