Files
Jinwoo Hong fb322046e8 skills: rewrite and trim the seven non-orchestration guides (#19128)
* skills: rewrite the seven non-orchestration guides to one outcome-first standard

Every guide leads with Result / Done / Safe failure, states conditions instead of case lists, keeps one done bar and one autonomy envelope, and loads references at the point of use via `skills get <topic> --full`. orca-cli drops from 424 to 260 always-loaded lines with three references; orca-per-workspace-env from 794 to 397 with five.

Defects fixed in shipped guides: `emulator camera` (no such command), iOS `permissions` (backend refuses it), Android pane described as in development, `relayGracePeriodSeconds: 0` documented as immediate teardown (it is unbounded), doctor `ok: true` hiding `warn`, an SSH exemplar setting both `jumpHost` and `proxyCommand`, a provisioned-root fetch from `origin`, and the Linear unconfirmed-write rule keyed on four verbs when ten emit it.

The resolver ladder, placeholder rule, and older-binary fallback shared by every installable SKILL.md now come from one skill-stubs/_shared/cli-resolution.md fragment composed by the generator, which also bundles per-guide references into --full. New guards: every ORCA invocation and flag resolves against COMMAND_SPECS, descriptions carry no angle-bracket tokens, reference routing is checked both ways, and an always-loaded size ratchet (300 lines) that guides may leave but never join.

* skills: address review on the SSH recipe and the parity guard

- ssh-host create script: route the bootstrap ssh through the chosen jump host or proxy command, refuse both at once, use StrictHostKeyChecking=accept-new instead of a blind ssh-keyscan append, and pass gh_token/project_root/repo_url/repo_ref to the remote bash via printf %q so a quote in a value cannot break out of the command.
- per-workspace-env envelope: the step-10 workspace test the user asked for is no longer forbidden by the same paragraph.
- linear guides: name the full verb, ORCA linear list-issues.
- parity guard: a prefix reference such as ORCA linear --help or ORCA emulator --webcam now has its flags checked against every command under that prefix; only an exact path or an explicit ... was checked before.

* skills: tighten prose in the seven rewritten guides

Shorter outcome spines, one idea per sentence, no restated rationale after a rule. No rule, command, or pinned phrase changes; 47 net lines fewer across the guides and references.

* skills: route orca-cli and per-workspace-env gates through --reference

Both guides told agents to load --full at a gate because the per-reference
selector did not exist when they were written. Now that main serves
`skills get <topic> --reference references/<file>.md`, load only the
named file and keep --full as the fallback for an older CLI, matching the
orchestration kernel.

* skills: drop outcome-spine boilerplate from the CLI-wrapper guides

The Result/Done/Safe-failure preambles and Next Action closers restated
rules the body already carries. Agents stop fine without them, and for
a CLI wrapper the command surface is the guide. Keeps the one substantive
rule computer-use's Done block added (never report unverified as success)
inside Action Rules. orchestration and per-workspace-env keep theirs:
those are multi-step workflows where the done bar is load-bearing.

(cherry picked from commit 44a74baf73)

* skills: trim the guides and stubs to what agents actually need

- Drop the Result/Done/Safe-failure preambles and Next Action closers from
  the six CLI-wrapper guides; the one substantive rule (never report an
  unverified computer-use action as success) moves into Action Rules.
- Drop the 'guide may be stale, trust --help' lines: the guide is served by
  the binary that runs the commands, so it cannot be stale relative to it.
- Drop the status --json / open --json preflight from every guide; the stub
  no-guessing paragraph now says to start Orca only when a command reports
  it is not running.
- Cut the ORCA placeholder paragraph in each guide to one line that points
  back at the stub's resolution.
- Trim the orchestration, orca-cli, and computer-use descriptions to trigger
  phrases plus one line of scope.
- Remove the older-binary fallback section from every stub (and its two
  shared blocks); a binary without skills get gets one sentence.
- Remove the guide size ratchet test.

* skills: apply independent review cleanup

* skills: clarify guide loading and Linear command discovery

* skills: harden environment recipe examples

* test: complete branch rename journal doubles

* skills: clarify custom Codex launch and refresh model example

* test: deduplicate journal fix now present on main
2026-09-07 00:03:48 -04:00

7.6 KiB

SSH connection mode, including provisioned root

Load this when the recipe connects over SSH instead of starting orca serve, and when the user has explicitly asked for checkoutMode: provisioned-root.

SSH mode is a different shape, not the Orca-server templates relabeled. create runs no orca serve and emits no pairingCode. Orca connects over its SSH relay, brings up the git and filesystem providers, and imports the repo. The script only readies the host and prints the SSH details Orca dials.

The result shape

Orca rejects anything else. Required fields only; add optionals from the next section as the network needs them.

{
  "schemaVersion": 1,
  "connection": {
    "type": "ssh",
    "projectRoot": "/abs/path/to/repo/on/host",
    "target": {
      "label": "my-box",
      "host": "192.0.2.10",
      "port": 22,
      "username": "ubuntu"
    }
  }
}

label, host, port, and username are required. projectRoot is an absolute path on the host.

Which optional target fields to set

These describe how the user's desktop reaches the box; there is no orca serve URL in SSH mode.

  • A public IP or DNS name, or a Tailscale or VPN address, is the host; the SSH port is port, usually 22.
  • Key auth sets identityFile. Add "identitiesOnly": true when the agent holds many keys.
  • A bastion is reached through one of two fields: jumpHost takes a user@host ProxyJump target, and proxyCommand takes a full command such as an access proxy. Set one, never both. The schema accepts both, and the two consumers then disagree: one pushes -J and -o ProxyCommand= into the same argv, the other resolves proxyCommand and ignores jumpHost entirely.
  • A service port the workspace needs is an entry in portForwards. Each entry requires localPort, remoteHost, and remotePort, and takes an optional label. The entry schema is strict, so an invented key such as local or remote fails validation.
  • relayGracePeriodSeconds bounds how long Orca keeps the SSH relay alive after the workspace detaches. 0 means unbounded: the relay stays up until something explicitly terminates it, so it is the wrong value for a disposable runtime. Any other value must be between 60 and 604800 seconds. A value between 1 and 59, such as 30, is rejected and takes the whole recipe result with it. Omit the field unless the user asked for a specific reconnect grace window.

Toolchain and agent auth on a persistent host

A persistent host is its own base image. Run the install steps and the agent's device-auth login over SSH once, by hand, before wiring the recipe. The login is interactive, for example ssh -t user@host '<agent> login --device-auth', so the user runs it. The host then stays ready across workspaces.

Use Git credentials already configured on the SSH host. For GitHub HTTPS repos, verify gh auth status on that host and run gh auth setup-git there if Git has no credential helper. Installed gh alone is not authentication. SSH URLs use the host's SSH keys; other providers use their own credential setup. If credentials are missing, have the user configure them on the host. Do not forward a desktop token in the SSH command.

Before the first connection, verify the host key using the provider console or another trusted channel and record it in the desktop's known_hosts. Do not trust an unverified ssh-keyscan result. The noninteractive script below refuses unknown or changed keys.

The create script

#!/usr/bin/env bash
set -euo pipefail
# resolve from env→state→fallback (default unset optionals to ""): ssh_username, host,
#   ssh_port (default 22), identity_file, jump_host, proxy_command, project_root, repo_url, repo_ref
: "${identity_file:=}"; : "${jump_host:=}"; : "${proxy_command:=}"   # avoid set -u aborts on optionals
ssh_target="${ssh_username}@${host}"
if [ -n "$jump_host" ] && [ -n "$proxy_command" ]; then
  echo "set jump_host or proxy_command, not both" >&2; exit 1
fi
ssh_opts=(-p "$ssh_port" -o BatchMode=yes -o StrictHostKeyChecking=yes)
[ -n "$identity_file" ] && ssh_opts+=(-i "$identity_file")
[ -n "$jump_host" ] && ssh_opts+=(-J "$jump_host")
[ -n "$proxy_command" ] && ssh_opts+=(-o "ProxyCommand=$proxy_command")

# 1. ensure the repo is present and at the right commit on the host (NO orca serve here).
#    printf %q quotes every value for the remote shell, so a space or quote in a path or
#    ref cannot break out of the command.
remote_sync='set -euo pipefail
  export GIT_TERMINAL_PROMPT=0
  [ -d "$project_root/.git" ] || git clone "$repo_url" "$project_root"
  cd "$project_root" && git fetch origin "$repo_ref" && git checkout -B "$repo_ref" FETCH_HEAD'
ssh "${ssh_opts[@]}" "$ssh_target" "$(printf \
  'project_root=%q repo_url=%q repo_ref=%q bash -lc %q' \
  "$project_root" "$repo_url" "$repo_ref" "$remote_sync")" >&2

# 2. print the SSH connection block (NO pairingCode, NO orca serve). host/port/username tell Orca's
#    relay how to dial in; identityFile/jumpHost/proxyCommand/portForwards are emitted when set.
node -e 'const [host,port,user,idf,jh,pc,root]=process.argv.slice(1);
  const target={ label:"per-workspace-host", host, port:Number(port), username:user };
  if(idf) target.identityFile=idf; if(jh) target.jumpHost=jh; if(pc) target.proxyCommand=pc;
  // add target.portForwards=[{localPort,remoteHost,remotePort}] here if the workspace needs them
  console.log(JSON.stringify({ schemaVersion:1, connection:{ type:"ssh", projectRoot:root, target } }))' \
  "$host" "$ssh_port" "$ssh_username" "$identity_file" "$jump_host" "$proxy_command" "$project_root"

On a persistent host there is usually nothing to tear down, so set destroy: none and omit suspend and resume. Orca still disconnects and reconnects its own SSH relay on sleep, wake, and delete, which is separate from these scripts.

If the SSH host is instead an ephemeral, snapshot-capable VM — the user's hypervisor, or a cloud VM with image support — keep the base-image model from references/provider-vercel.md for provisioning, but still emit the connection.type:"ssh" block above instead of starting orca serve.

Provisioned root

For an explicitly requested one-VM-per-workspace checkout, the create script reads ORCA_RECIPE_RESULT_SCHEMA_VERSION, ORCA_REPO_URL, ORCA_REPO_REF, ORCA_REPO_REF_HEAD, and ORCA_REPO_BRANCH. Use ORCA_REPO_REF to fetch the selected source, but create ORCA_REPO_BRANCH at the exact ORCA_REPO_REF_HEAD commit, because resolving the symbolic ref again can race with an upstream update. ORCA_REPO_URL and ORCA_REPO_REF are a matched fetch pair, and the URL is the remote Orca resolved the base ref against, which is not necessarily named origin on the desktop. Fetch from the URL the pair supplies:

[ -n "${ORCA_REPO_REF_HEAD:-}" ] || { echo "missing pinned source commit" >&2; exit 1; }
git fetch "$ORCA_REPO_URL" "$ORCA_REPO_REF"
git cat-file -e "${ORCA_REPO_REF_HEAD}^{commit}"
git checkout -B "$ORCA_REPO_BRANCH" "$ORCA_REPO_REF_HEAD"

Return that primary checkout at projectRoot and emit schema version 2:

{
  "schemaVersion": 2,
  "checkoutMode": "provisioned-root",
  "connection": {
    "type": "ssh",
    "projectRoot": "/abs/repo",
    "target": { "label": "my-box", "host": "192.0.2.10", "port": 22, "username": "ubuntu" }
  }
}

Before declaring an SSH recipe done

The --provision self-test only sees what the scripts print, so smoke-test the exact emitted target as well: dial the host and port with the identity or proxy settings, run pwd, verify the repo path, and check the agent binary. If the recipe created a provider resource, also confirm destroy removes it.