Orca (orca CLI) runs a scripted plan → code → review flow autonomously,
using its own coding/review agents. Delegate to it instead of implementing
the task yourself when that fits better.
When to use
- The user asks for it (
/orca, "use an orca flow to …"). - The task is well-defined and self-contained, with clear acceptance criteria (a feature or bugfix) — suited to an autonomous plan → code → review flow.
- NOT for exploratory/interactive work, or edits small enough to just make yourself.
1. Choose the flow and where the run goes
Run orca list --json and git status --porcelain. If orca is not found,
stop and point the user to https://github.com/VirtusLab/orca#getting-set-up.
Skip a question only if the user named the flow, or said where the run goes, explicitly. Otherwise ask both in one AskUserQuestion call:
Flow (header Flow). Put every flow in the question text, one per line
as name — description, and say: pick one of the options, or type any other
flow name under "Other". Options: implement.sc first, marked
"(Recommended)", then up to 3 more, by origin: project, global,
built-in.
Where the run goes (header Where). On a clean tree, the options are:
- New branch (Recommended) — no flag.
- Current branch — the flow commits onto it:
--skip-branch. - New worktree — a separate checkout under
.orca/worktrees/, this one stays untouched:--worktree.
With local (uncommitted or untracked) changes, list up to 10 changed files in the question text (then "+N more"), and offer:
- New branch, keep local changes (Recommended) — for local files the flow
should use, e.g. a spec:
--keep-changes. - New branch, stash local changes — the run starts from the last commit: no flag.
- Current branch, keep local changes:
--skip-branch. - New worktree — local changes are NOT included, it starts from the last
commit:
--worktree.
Without --keep-changes or --skip-branch, a headless run stashes local
changes. With either, if the flow fails before its first commit, kept changes
to tracked files are lost.
If the user picks the worktree while there are local changes, ask with
AskUserQuestion (header Changes): "Commit first" — so the worktree has
them — or "Run without them". To commit:
git add -A && git commit -m "<short summary>".
Don't pre-create a branch or worktree: the flow creates its own.
2. Get the prompt
Prompt given with the invocation (may be empty):
$ARGUMENTS
If empty, write one from the task discussed in the conversation. If there is none, ask for it in plain text, phrased after the chosen flow's description (e.g. an issue reference, a PR or branch to review, or a description of the change).
Orca's agents don't see this conversation: write the prompt so it stands on its own — goal, acceptance criteria, relevant files, and the path of any spec.
3. Run
Capture the output in a temporary file, so the user can follow it
(tail -f). Runs are long, so use two separate commands:
-
Create the file, and give the user its path before starting the run:
mktemp -t orca-run.XXXXXX.log -
Start the run with Bash
run_in_background: true, using the literal path from step 1 and the flags chosen above. The prompt goes on stdin, so quotes and$in it need no escaping:orca run <flow> <flags> > <path> 2>&1 <<'ORCA_PROMPT' <prompt> ORCA_PROMPT echo "orca exit code: $?" >> <path>
When it finishes, read the file's tail to check the result; repeat its path in your final report.
Add these flags only if the user asks:
--verbose— print a stack trace if the flow aborts.--honor-pin— run the flow's own pinned orca version instead of forcing this shell's.--branch <name>— create the run's branch under this name. Refused with--skip-branch, and when the branch already exists.--draft— open the run's PR as a draft.
After it runs
Exit codes: 0 success, 1 action failure, 2 usage error — orca run
propagates the flow's own exit code. On success the flow has committed its
work on a branch; report that branch (and any PR) to the user, and the
worktree path for a --worktree run. The code flows end by opening a PR when
the repository is on GitHub. A new-branch run then leaves you on the branch
it started from — the work is on the feature branch behind the PR, not the
one you are standing on.
Whenever the output has an "Open review findings" block, show it to the user verbatim. Say the review left nothing open only when a code flow exited 0 without one: a failed run may have stopped before printing it.
If a run is interrupted, re-run the same orca run command: flows are
resumable and pick up from the last committed stage. A re-run stashes local
changes, even with --keep-changes.
orca continue (list sessions with --list, resume one by selector —
an id from --list, session name, or branch, e.g. orca continue <branch>)
reattaches to a recorded harness session, but requires a real terminal and
errors without one — don't invoke it headlessly; tell the user to run it
themselves instead.