mirror of
https://github.com/stablyai/orca.git
synced 2026-09-23 08:02:31 +00:00
Brennan Benson
f8b430f725
* feat(skills): ship orca-cli as a first-generation hybrid stub Convert the installable orca-cli SKILL.md from a full fat guide into a hybrid discovery stub: a safe CLI resolver, an `orca skills get orca-cli` pointer, and a bounded read-only fallback for pre-guide binaries. The version-matched command reference now lives only in the Orca binary (embedded guide table, served by `orca skills get`), so the distributed file can no longer drift from the binary that runs the commands. - generator projects STUB_TOPICS from skill-stubs/<name>.md, reusing the guide's own frontmatter so the routing/description surface is unchanged; the embedded full guide (bundled-skill-guides.ts) is untouched. - manifest regenerated: orca-cli releaseRevision 32->33 as an append-only snapshot; existing fat installs classify `outdated` and get the targeted `npx skills update` nudge (no in-app writes). - tests: command-guidance assertions repointed to the guide source (their home now), plus stub-projection + safety coverage. Only orca-cli converts; the other skills stay fat. Per notes/skill-freshness-design.md, the E.3 pointer-compliance spike and the E.5 RC window remain before any further thinning. allowed-tools is intentionally not added yet (frontmatter kept byte-identical to the guide). * fix(skills): distinguish guide lookup failures * chore(skills): refresh released skill mapping
64 lines
3.0 KiB
Markdown
64 lines
3.0 KiB
Markdown
# Orca CLI
|
|
|
|
This file is a discovery stub, not the usage guide. The full, version-matched Orca CLI
|
|
reference is served by the `orca` binary itself — kept out of this file on purpose so it
|
|
can never drift from the binary that will actually run your commands.
|
|
|
|
Engage Orca whenever its running editor/runtime is the source of truth: Orca-managed
|
|
worktrees, folder contexts, terminals, repos, automations, worktree comments, and the
|
|
browser embedded inside the Orca app. Triggers include "$orca-cli", "Orca worktree",
|
|
"child worktree", "spawn codex/claude in a worktree", "read/wait/send Orca terminal",
|
|
"full handoff" / "handover" / "give this to another agent", and "control the browser
|
|
inside Orca". Use plain shell tools when Orca state does not matter.
|
|
|
|
## Resolve the CLI for this session
|
|
|
|
Choose the executable once and reuse it for every later command:
|
|
|
|
- If the `ORCA_CLI_COMMAND` environment variable is set, use its value. Orca exports this
|
|
for managed WSL sessions.
|
|
- Otherwise, in a dev checkout whose session exposes `ORCA_DEV_REPO_ROOT`, use `orca-dev`.
|
|
- Otherwise, on Linux outside an Orca-managed terminal, use `orca-ide`. Never run bare
|
|
`orca` there — outside Orca's terminals it normally resolves to the
|
|
GNOME Orca screen reader (`/usr/bin/orca`) and starts speech on the user's machine.
|
|
- Otherwise, use `orca`.
|
|
|
|
Below, `ORCA` is a placeholder for the executable you resolved. Substitute it before
|
|
running anything; do not create a shell variable or run `ORCA` literally. This works the
|
|
same way in POSIX shells, PowerShell, and cmd.exe.
|
|
|
|
If the selected executable cannot run, report its exact error and stop. Do not fall through
|
|
to another executable, which could silently target a different Orca build.
|
|
|
|
## Load the full guide before running Orca commands
|
|
|
|
```text
|
|
ORCA skills get orca-cli
|
|
```
|
|
|
|
That prints the complete, version-matched guide for the exact binary that will handle your
|
|
next commands — worktrees, handoffs, terminals, automations, and the built-in browser.
|
|
Read it first, then run the specific command you need.
|
|
|
|
Don't guess subcommands or flags from memory or from a cached copy of this stub. They
|
|
change between Orca releases, and this file deliberately no longer lists them. Confirm the
|
|
app is up with `ORCA status --json` (start it with `ORCA open --json` if needed), and
|
|
prefer `--json` for agent-driven calls.
|
|
|
|
## If an older Orca does not recognize `skills get`
|
|
|
|
Use this fallback only when the selected binary explicitly reports that `skills get` is an
|
|
unknown command. Another failure is not proof of an older binary; report it rather than
|
|
guessing or changing executables. For a confirmed pre-guide binary, use only this bounded,
|
|
read-only bootstrap to orient. Do not dead-end and do not invent commands:
|
|
|
|
```text
|
|
ORCA status --json
|
|
ORCA worktree ps --json
|
|
ORCA terminal list --json
|
|
```
|
|
|
|
Then tell the user that updating Orca restores the full, version-matched guide via
|
|
`ORCA skills get orca-cli`. Beyond these commands, ask the user rather than guessing a
|
|
command surface this older binary may not support.
|