oneshot-workflow

What this skill does

# 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 (`/exarchos: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 `/exarchos:cancel` and restart with `/exarchos: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__plugin_exarchos_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:

1. **Goal** — what is the user trying to accomplish?
2. **Approach** — what's the one-line implementation strategy?
3. **Files** — which files will be touched? (1-5 typically)
4. **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__plugin_exarchos_exarchos__exarchos_workflow({
  action: "update",
  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 phas