Skip to content
Orbital
Menu
DocsExamplesReference
Examples
Implement a featureDeliver an epicReview pull requestsImprove a codebaseTriage issuesResearch report
Workflow files
One-shot implementationImplementer with a local stepOuter loop over an epicTicket to merge

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.

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.

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

Before you start

Section titled “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, or just one-shot.toml.

1. Add the workflow

Section titled “1. Add the workflow”

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

  2. Check it:

    Terminal window
    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.
    The editor draws the workflow's steps; the Problems bar lists what validation rejects.

2. Read how it works

Section titled “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 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

Section titled “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

Section titled “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.
Section titled “Related”