mirror of
https://github.com/stablyai/orca.git
synced 2026-09-21 16:02:20 +00:00
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.
This commit is contained in:
Jinwoo-H
@@ -13,13 +13,6 @@ description: >-
|
||||
|
||||
Use this skill for desktop UI through `orca computer`. For a website or web app, use it only when the page is in an external desktop browser window that needs desktop-level control. Do not use it for page-only automation: use `orca-cli` for Orca's embedded pages and a page-automation tool such as Playwright or CDP for external pages.
|
||||
|
||||
## Done
|
||||
|
||||
An action is done when you read its verification class and reported it. Any `unverified`
|
||||
result is unproven: re-read the UI before the next step and never call it success. If an
|
||||
unverified action could have sent, submitted, bought, or deleted something, say the effect
|
||||
is unproven.
|
||||
|
||||
## Preconditions
|
||||
|
||||
- `ORCA` in every example, including the shell-specific ones, is the executable you used to run
|
||||
@@ -99,6 +92,7 @@ printf '%s' "$TEXT" | ORCA computer set-value --app <app> --element-index <index
|
||||
- `unverified (accessibility action unasserted)` means the accessibility call succeeded but no post-state assertion was made.
|
||||
- `unverified (synthetic input)` means input was fired into the void and is unverifiable.
|
||||
- Missing verification metadata is unverified, including responses from older runtimes.
|
||||
- Never report an unverified action as success. If it could have sent, submitted, bought, or deleted something, say the effect is unproven.
|
||||
- Prefer semantic actions: `set-value` for editable fields, `click` for controls, `perform-secondary-action` only for listed action names.
|
||||
- After any UI-changing action, use the returned state or rerun `get-app-state` before choosing the next element index.
|
||||
- Use `type-text` only after focusing a field and confirming the app has a focused text receiver; synthetic keyboard delivery is reported as unverified, so inspect the returned state before assuming text landed.
|
||||
@@ -161,7 +155,3 @@ Slack: the accessibility tree may be shallow while the screenshot contains usefu
|
||||
- `accessibility_error`: run `ORCA computer capabilities --json`; if the message names Accessibility permission, run `ORCA computer permissions --id accessibility --json`.
|
||||
- Empty tree or no screenshot: app may have no visible window, be minimized, or need permissions.
|
||||
- Permission errors: run `ORCA computer permissions --json`, or `ORCA computer permissions --id accessibility --json` / `--id screenshots --json` when the message names one permission, use the setup UI, then retry.
|
||||
|
||||
## Next Action
|
||||
|
||||
Confirm Orca status unless already checked, then run `ORCA computer capabilities --json`. For external browser targets such as Gmail, identify the desktop browser app/window that contains the page, then get that target app state with `ORCA computer get-app-state --app <app> --json`.
|
||||
|
||||
@@ -13,23 +13,6 @@ description: >-
|
||||
|
||||
`linear-tickets` is the legacy bundled name for `orca-linear`. This copy remains complete; its CLI commands are identical to `orca-linear` and always use `ORCA linear ...`.
|
||||
|
||||
**Result:** the current ticket's context loaded before you plan, or a ticket whose state,
|
||||
attachments, and comments reflect the work just done.
|
||||
|
||||
**Done:** the branch you took reached its outcome.
|
||||
|
||||
- Read: you have the issue's state, comments, and `inlineMedia`, and you say which you used.
|
||||
- Complete: the PR/MR link is attached, exactly one completion comment is posted, and status
|
||||
is moved or left unchanged with the reason in that comment.
|
||||
- Move status: the target state was named by the user or resolved deterministically, and the
|
||||
move does not regress the ticket.
|
||||
- Search: you report the matches and the `truncated` value you checked before quoting a count.
|
||||
- Follow-up: the parented issue exists and you report its identifier.
|
||||
|
||||
**Safe failure:** when a write is still unconfirmed after its one retry or read-back, the target
|
||||
state is ambiguous, or the installed CLI disagrees with this guide, stop and report. Leave Linear
|
||||
unchanged rather than guess.
|
||||
|
||||
Use `ORCA linear` when Linear is the source of task context or ticket updates.
|
||||
|
||||
`ORCA` is a placeholder for the executable you used to run `skills get`. Substitute it before
|
||||
@@ -195,7 +178,3 @@ If the retry or the read-back also fails, stop and report the uncertainty to the
|
||||
- `linear_write_unconfirmed`: follow the payload rules above — retry once when `error.data.writeId` is present, otherwise read back first.
|
||||
- `linear_invalid_workspace`: rerun with the workspace id returned by search or issue context.
|
||||
- `linear_body_too_large`: shorten the comment/body and retry once.
|
||||
|
||||
## Next Action
|
||||
|
||||
Confirm `ORCA status --json` unless already checked this turn, then read the current issue with `ORCA linear issue --current --full --json`. For completion, attach the PR/MR link, add one completion comment, and move status only when the target state is deterministic and non-regressive.
|
||||
|
||||
@@ -20,14 +20,6 @@ description: >-
|
||||
|
||||
Use `orca` when Orca's running editor/runtime is the source of truth. Use plain shell tools when Orca state does not matter.
|
||||
|
||||
## Outcome
|
||||
|
||||
**Result:** the Orca state you were asked to read or change, plus the receipt that proves it: a worktree id, an agent handle, or the command's JSON result.
|
||||
|
||||
**Done:** you reported that receipt. Handoffs have one more condition, under `## Full Handoffs`.
|
||||
|
||||
**Safe failure:** no receipt, or an unsatisfied wait, means unproven. Report it that way and stop. A timeout, a quiet terminal, or a lost host never proves that input landed or that a process exited.
|
||||
|
||||
## Start Here
|
||||
|
||||
`ORCA` in every example is the executable you used to run `skills get`. Keep using that executable. Substitute it before running anything; do not make a shell variable or run `ORCA` literally. This holds in POSIX shells, PowerShell, and cmd.exe.
|
||||
@@ -245,7 +237,3 @@ This guide covers worktrees, terminals, and handoffs on its own. At a gate below
|
||||
| Creating, editing, running, or inspecting scheduled automations | `references/automations.md` |
|
||||
| Publishing or revoking an artifact link, or publishing installed skills | `references/publishing.md` |
|
||||
| Mobile emulator taps, gestures, typing, buttons, camera, or permissions | invoke the `orca-emulator` skill |
|
||||
|
||||
## Next Action
|
||||
|
||||
Confirm `ORCA status --json` unless already checked this turn, then run the narrowest command for the job: `worktree ps/current/create`, `terminal list/read/wait/send`, or `worktree set --comment/--workspace-status`. For anything in the table above, load its row first.
|
||||
|
||||
@@ -12,16 +12,6 @@ license: Apache-2.0
|
||||
|
||||
# Orca Emulator (Android)
|
||||
|
||||
**Result:** an observed UI state change on an adb-connected Android emulator or device,
|
||||
driven from the CLI while the live stream stays visible in Orca's emulator pane.
|
||||
|
||||
**Done:** every action you report names the command and the evidence you read back: an
|
||||
accessibility-tree dump, a logcat excerpt, a returned payload, or a named error. No evidence
|
||||
means unverified; say so instead of done.
|
||||
|
||||
**Safe failure:** if a command is unknown or its output has an unexpected shape, trust
|
||||
`ORCA emulator --help` over this guide and tell the user the guide may be stale.
|
||||
|
||||
`ORCA` in every example, including tables and prose, is the executable you used to run
|
||||
`skills get`. Substitute it before running; do not make a shell variable or run `ORCA`
|
||||
literally. The examples work in POSIX shells, PowerShell, and cmd.exe.
|
||||
@@ -126,10 +116,5 @@ ORCA emulator logcat --lines 100 --json
|
||||
ORCA emulator kill --json
|
||||
```
|
||||
|
||||
## Next action
|
||||
|
||||
Run `ORCA emulator devices --json` to find a booted device, attach it, then drive it while
|
||||
reading back evidence for each action.
|
||||
|
||||
See also: `orca-emulator` for iOS simulators, `orca-cli` for terminals, worktrees, and the
|
||||
built-in browser, and `computer-use` for desktop UI outside the emulator.
|
||||
|
||||
@@ -12,16 +12,6 @@ license: Apache-2.0
|
||||
|
||||
# Orca Emulator (iOS)
|
||||
|
||||
**Result:** an observed UI state change on a booted Apple Simulator, driven from the CLI
|
||||
while the live stream stays visible in Orca's emulator pane.
|
||||
|
||||
**Done:** every action you report names the command and the evidence you read back: an
|
||||
accessibility-tree dump, a returned payload, or a named error. No evidence means unverified;
|
||||
say so instead of done.
|
||||
|
||||
**Safe failure:** if a command is unknown or its output has an unexpected shape, trust
|
||||
`ORCA emulator --help` over this guide and tell the user the guide may be stale.
|
||||
|
||||
`ORCA` in every example, including tables and prose, is the executable you used to run
|
||||
`skills get`. Substitute it before running; do not make a shell variable or run `ORCA`
|
||||
literally. The examples work in POSIX shells, PowerShell, and cmd.exe.
|
||||
@@ -113,10 +103,5 @@ ORCA emulator exec --command "ca-debug blended on" --json
|
||||
ORCA emulator kill --device "iPhone 16 Pro" --json
|
||||
```
|
||||
|
||||
## Next action
|
||||
|
||||
Confirm `ORCA status --json` and `ORCA emulator list --json`, attach a device, then drive it
|
||||
while reading back evidence for each action.
|
||||
|
||||
See also: `orca-emulator-android` for Android devices, `orca-cli` for terminals, worktrees,
|
||||
and the built-in browser, and `computer-use` for desktop UI outside the simulator.
|
||||
|
||||
@@ -10,23 +10,6 @@ description: >-
|
||||
|
||||
# Orca Linear
|
||||
|
||||
**Result:** the current ticket's context loaded before you plan, or a ticket whose state,
|
||||
attachments, and comments reflect the work just done.
|
||||
|
||||
**Done:** the branch you took reached its outcome.
|
||||
|
||||
- Read: you have the issue's state, comments, and `inlineMedia`, and you say which you used.
|
||||
- Complete: the PR/MR link is attached, exactly one completion comment is posted, and status
|
||||
is moved or left unchanged with the reason in that comment.
|
||||
- Move status: the target state was named by the user or resolved deterministically, and the
|
||||
move does not regress the ticket.
|
||||
- Search: you report the matches and the `truncated` value you checked before quoting a count.
|
||||
- Follow-up: the parented issue exists and you report its identifier.
|
||||
|
||||
**Safe failure:** when a write is still unconfirmed after its one retry or read-back, the target
|
||||
state is ambiguous, or the installed CLI disagrees with this guide, stop and report. Leave Linear
|
||||
unchanged rather than guess.
|
||||
|
||||
Use `ORCA linear` when Linear is the source of task context or ticket updates.
|
||||
|
||||
`ORCA` is a placeholder for the executable you used to run `skills get`. Substitute it before
|
||||
@@ -192,7 +175,3 @@ If the retry or the read-back also fails, stop and report the uncertainty to the
|
||||
- `linear_write_unconfirmed`: follow the payload rules above — retry once when `error.data.writeId` is present, otherwise read back first.
|
||||
- `linear_invalid_workspace`: rerun with the workspace id returned by search or issue context.
|
||||
- `linear_body_too_large`: shorten the comment/body and retry once.
|
||||
|
||||
## Next Action
|
||||
|
||||
Confirm `ORCA status --json` unless already checked this turn, then read the current issue with `ORCA linear issue --current --full --json`. For completion, attach the PR/MR link, add one completion comment, and move status only when the target state is deterministic and non-regressive.
|
||||
|
||||
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user