> For the index of every page in Orbital's docs, read https://docs.runorbital.dev/llms.txt.

# One-shot implementation

> The smallest workflow that delivers real work, from worktree to pull request

In this example you run the smallest workflow that delivers real work. It takes an isolated checkout, implements once, reviews once, publishes a pull request and puts the checkout away. There is no repair loop and no waiting on the pull request.

About five minutes to set up.

```toml title="one-shot.toml"
version = 3
entry = "steps.checkout"
description = "Implement one change in an isolated checkout, review it once and publish it"

[inputs.work]
label = "Work"
hint = "The change to make, in plain words or as a ticket URL"

[styles.quick]
effort = "low"

[steps.checkout]
kind = "action"
do = "worktree.create"
next = "steps.implement"

[steps.implement]
style = "implementer"
prompt = "Implement the change described by {{ inputs.work }}. Follow the conventions already in the repository. Do not commit or push."
outputs.implementation_summary = "text"
next = "steps.review"

[steps.review]
style = "reviewer"
prompt = "Review the change in the working folder. The implementer reported: {{ context.implementation_summary }}. Choose pass when the change is complete and correct, or reject when it is not. Do not change files."
outputs.verdict = { kind = "choice", options = ["pass", "reject"] }
routes = [
  { if = "verdict == 'pass'",   to = "steps.publish.commit" },
  { if = "verdict == 'reject'", to = "steps.rejected" },
]

[steps.publish]
style = "quick"

[steps.publish.commit]
kind = "action"
do = "git.commit"
message = { write = "A commit message that says why the change exists" }
next = "steps.publish.push"

[steps.publish.push]
kind = "action"
do = "git.push"
next = "steps.publish.open"

[steps.publish.open]
kind = "action"
do = "github.pr.open"
title = { write = "A short title naming the change" }
body = { write = "Why the change exists, what it changes and how it was checked" }
next = "steps.cleanup"

[steps.cleanup]
kind = "action"
do = "worktree.remove"
routes = [{ if = "git.worktree.clean", to = "steps.published" }]
next = "steps.retained"

[steps.published]
kind = "terminal"

[steps.rejected]
kind = "terminal"
outcome = "failed"
label = "Checkout kept for inspection"

[steps.retained]
kind = "terminal"
outcome = "failed"
label = "Checkout retained to preserve local work"
```

![checkout → implement → review. A passing review commits, pushes and opens a pull request, then cleans up; a rejected review keeps the checkout.](/one-shot.svg?v=5abb76da02)

Use it when the change is small enough that a rejected review means you want to look at it yourself.

## Before you start

You need:

- a project whose primary folder is a Git repository with a GitHub remote you can push to, because the run works in a worktree and opens a pull request;
- Git credentials that can push, and a GitHub token Orbital can use: a `gh auth login`, or a token in **Settings > GitHub**;
- a signed-in harness;
- the workflow: [download the archive](/one-shot.zip), or just [one-shot.toml](/examples/one-shot/one-shot.toml).

## 1. Add the workflow

1. Unpack the archive into your workflow library, `~/.orbital/workflows/`. Keep every relative path.

2. Check it:

   ```sh
   orbital validate ~/.orbital/workflows/one-shot.toml
   ```

![The workflow editor showing a workflow as steps joined by arrows, with an Inspector panel on the right and a Problems bar.](/screenshots/workflow-editor.webp?v=85a9c6275a)

*The editor draws the workflow's steps; the Problems bar lists what validation rejects.*

## 2. Read how it works

`checkout` is an `action` step that does `worktree.create`. It makes one isolated checkout per repository folder on a generated branch, so the run never touches your working copy. `cleanup` is the matching `worktree.remove`.

`implement` and `review` take the shipped `implementer` and `reviewer` styles. `review` declares a `verdict` choice output with the options `pass` and `reject`, and its routes answer both, so it needs no `next`. A rejection ends the run at a failed terminal and skips cleanup on purpose. Removal would refuse anyway with uncommitted work in the checkout, and the point of a rejection is that you want to read the diff.

No agent publishes the change. The `publish` group holds three actions: `publish.commit` commits every change in the checkout, `publish.push` pushes the branch and `publish.open` opens the pull request. The commit message, the title and the body are each a `write`, a short model session with no tools that reads the run's context and returns only that text. The group's `style = "quick"` reaches the actions inside it, so each write runs at low effort. A write appears in the run history and does not count toward `max_visits`. [Push and open pull requests without an agent](/workflows/use-actions/) describes every action.

Cleanup routes on `git.worktree.clean`. Removal measures every checkout first and removes none if any would lose dirty files or unpushed work. So the fallback ends at a failed terminal that names what happened, rather than pretending the run succeeded.

## 3. Start the run

Choose **New task** and pick the project on the repository. Choose the `one-shot` workflow, set work to a description or ticket URL, and write the goal.

## What you get

| Review | Result |
| --- | --- |
| Passes | A pull request is opened, and the run ends Succeeded with the checkout removed. |
| Rejects | The run ends Failed with the checkout intact for you to inspect. |
| Passes, but removal is refused | The run ends Failed and keeps the checkout. |

## Related

- [Implementer with a local step](/examples/workflows/local-step/): add a local check before the end
- [Ticket to merge](/examples/workflows/ticket/): follow the pull request through to merge
- [Worktrees and delivery](/projects/worktrees-and-delivery/): how the `worktree.create` and `worktree.remove` actions make and remove checkouts