diff --git a/REUSE.toml b/REUSE.toml index 2b6642a..8f9b0b0 100644 --- a/REUSE.toml +++ b/REUSE.toml @@ -57,6 +57,17 @@ precedence = "override" SPDX-FileCopyrightText = ["Vercel, Inc.", "2026 Mohamed Hammad "] SPDX-License-Identifier = "GPL-3.0-or-later OR MIT" +# Third-party-vendored, unmodified: Orca's skills (github:stablyai/orca, MIT, +# © Lovecast Inc.). Vendored verbatim under orca-skills/ — NOT adapted, so the +# upstream license is preserved as-is with no Spacecraft relicensing/dual-licensing +# (§4.2), same posture as the android-skills entry below. Single copyright holder, +# single license. See orca-skills/CREDITS.md for provenance. +[[annotations]] +path = "orca-skills/**" +precedence = "override" +SPDX-FileCopyrightText = "Lovecast Inc." +SPDX-License-Identifier = "MIT" + # Third-party-vendored, unmodified: Google's Android skills (github:android/skills, # Apache-2.0, © Google LLC). Vendored verbatim under android-skills/ — NOT adapted, so # the upstream license is preserved as-is with no Spacecraft relicensing/dual-licensing diff --git a/flake.nix b/flake.nix index 5c61d2f..d4e96f3 100644 --- a/flake.nix +++ b/flake.nix @@ -14,7 +14,7 @@ # A "cross-platform" skill is any top-level directory that contains a # SKILL.md and is not in the excluded list. A "Grok" skill is any # subdirectory of grok-skills/ that contains a SKILL.md. - excludedDirs = [ "grok-skills" "android-skills" "perplexity-skills" "Excluded" ".claude" ".git" "construct-cli" ]; + excludedDirs = [ "grok-skills" "android-skills" "orca-skills" "perplexity-skills" "Excluded" ".claude" ".git" "construct-cli" ]; hasSkillMd = parent: name: builtins.pathExists (parent + "/${name}/SKILL.md"); @@ -41,6 +41,15 @@ skillNamesIn (self + "/android-skills") else []; + # Vendored Orca skills — same open-standard SKILL.md format, merged into + # the canonical tree unconditionally (unlike the opt-in Android set): the + # `orca` CLI looks its skills up by exact leaf name, so they have to be + # present wherever an agent reads skills from, not behind a toggle. + orcaSkills = + if builtins.pathExists (self + "/orca-skills") then + skillNamesIn (self + "/orca-skills") + else + []; # ─────────────────────────────────────────────────────────────────── # System support @@ -56,14 +65,35 @@ cp -r ${source}/${name}/. $out/ ''; - # Combined derivation — one skill tree from one source. - mkCombined = pkgs: source: skillList: outName: + # Combined derivation — one flat skill tree from any number of sources. + # Each source is { source; names; }; leaves are copied in list order, so + # a name appearing twice would be silently overwritten rather than + # merged. Every caller below therefore relies on leaf names being + # disjoint across sources (see mkSkills). + mkMerged = pkgs: outName: sources: pkgs.runCommandLocal outName { } ('' mkdir -p $out - '' + nixpkgs.lib.concatMapStringsSep "\n" (n: '' - mkdir -p $out/${n} - cp -r ${source}/${n}/. $out/${n}/ - '') skillList); + '' + nixpkgs.lib.concatMapStringsSep "\n" ({ source, names }: + nixpkgs.lib.concatMapStringsSep "\n" (n: '' + mkdir -p $out/${n} + cp -r ${source}/${n}/. $out/${n}/ + '') names) sources); + + # Combined derivation — one skill tree from one source. + mkCombined = pkgs: source: skillList: outName: + mkMerged pkgs outName [ { inherit source; names = skillList; } ]; + + # The base tree every non-Grok consumer starts from: the cross-platform + # skills plus the vendored Orca ones. Leaf names don't collide — + # cross-platform skills are all spacecraft-* / gnu-* / microsoft-* / + # steelbore-*, and the three Orca leaves are distinct from those — so a + # flat merge is safe. `orca-skills/CREDITS.md` records that the generic + # Orca leaf names (`computer-use`, `orchestration`) are reserved and must + # not be claimed by a future Spacecraft skill. + baseSources = [ + { source = self; names = crossPlatformSkills; } + ] ++ nixpkgs.lib.optional (orcaSkills != []) + { source = self + "/orca-skills"; names = orcaSkills; }; # THE skill tree builder. Every consumer goes through this — the # `packages` outputs below and the Home-Manager module alike. @@ -79,22 +109,12 @@ if grok then mkCombined pkgs (self + "/grok-skills") grokSkills "construct-grok-skills" else if android && androidSkills != [] then - # Cross-platform + vendored Android in one tree. Leaf names don't - # collide (cross-platform skills are all spacecraft-* / gnu-* / - # microsoft-*; Android leaves are distinct), so a flat merge is safe. - pkgs.runCommandLocal "construct-skills-with-android" { } ('' - mkdir -p $out - '' + nixpkgs.lib.concatMapStringsSep "\n" (n: '' - mkdir -p $out/${n} - cp -r ${self}/${n}/. $out/${n}/ - '') crossPlatformSkills - + "\n" - + nixpkgs.lib.concatMapStringsSep "\n" (n: '' - mkdir -p $out/${n} - cp -r ${self + "/android-skills"}/${n}/. $out/${n}/ - '') androidSkills) + mkMerged pkgs "construct-skills-with-android" + (baseSources ++ [ + { source = self + "/android-skills"; names = androidSkills; } + ]) else - mkCombined pkgs self crossPlatformSkills "construct-skills"; + mkMerged pkgs "construct-skills" baseSources; in { # ─────────────────────────────────────────────────────────────────── @@ -117,6 +137,11 @@ name = "android-${n}"; value = mkSkillPackage pkgs (self + "/android-skills") n; }) androidSkills)) + // + (builtins.listToAttrs (map (n: { + name = "orca-${n}"; + value = mkSkillPackage pkgs (self + "/orca-skills") n; + }) orcaSkills)) // { # The whole trees, as buildable outputs. `skills` is what a consumer # points a mutable pointer at (see `mutablePointer` below): building @@ -374,7 +399,7 @@ # Convenience: list of detected skill names (useful for `nix eval`). # ─────────────────────────────────────────────────────────────────── lib = { - inherit crossPlatformSkills grokSkills androidSkills; + inherit crossPlatformSkills grokSkills androidSkills orcaSkills; # Build a skill tree with the CALLER's nixpkgs. Pass the result to both # your own flake output and `spacecraft.construct.package` so the two diff --git a/orca-skills/CREDITS.md b/orca-skills/CREDITS.md new file mode 100644 index 0000000..1ef4ad4 --- /dev/null +++ b/orca-skills/CREDITS.md @@ -0,0 +1,49 @@ +# Credits + +The `orca-skills/` directory vendors a three-skill subset of **Orca**'s +official skills collection **verbatim and unmodified**. Every skill under this +directory is third-party work; none of it is a Spacecraft Software original or +adaptation. This file is the §15.3 human-readable counterpart to the +machine-readable `MIT` metadata declared for `orca-skills/**` in the repo-root +[`REUSE.toml`](../REUSE.toml). + +## Orca skills + +| Field | Value | +|------------|-------| +| Name | Orca skills | +| Author(s) | Lovecast Inc. | +| License | MIT License (see [`LICENSE.txt`](LICENSE.txt) and [`../LICENSES/MIT.txt`](../LICENSES/MIT.txt)) | +| Source URL | | +| Scope | The three skills below, vendored verbatim — each `SKILL.md` byte-for-byte identical to upstream, including Orca's own frontmatter. No content was edited, relicensed, or adapted. | + +**Upstream provenance:** commit `fe95698b95e7687857d2421549366b8771c71e36` +(2026-08-18), vendored 2026-08-18. + +## Vendored skills (3) + +Upstream groups these under a top-level `skills/` directory; this directory +drops that one level so each skill's leaf directory sits directly under +`orca-skills/`. The mapping from upstream path to vendored directory: + +| Vendored dir | Upstream path | +|--------------|---------------| +| `orca-cli` | `skills/orca-cli` | +| `computer-use` | `skills/computer-use` | +| `orchestration` | `skills/orchestration` | + +Upstream ships five further skills — `linear-tickets`, `orca-emulator`, +`orca-emulator-android`, `orca-linear`, `orca-per-workspace-env` — which are +deliberately **not** vendored: they target Linear, Android emulators, and +per-workspace environment plumbing that this tree has no use for. Adding one +later is a matter of copying its directory and extending the table above. + +## Leaf-name note + +`computer-use` and `orchestration` are generic names, and unlike every other +vendored tree here they carry no vendor prefix. That is deliberate and +load-bearing: Orca's own installer and its `orca skills` subcommand look these +directories up **by exact leaf name**, so renaming them to `orca-computer-use` +or similar would vendor the content while breaking the tool that consumes it. +The names are therefore reserved — a future Spacecraft skill must not claim +either one. diff --git a/orca-skills/LICENSE.txt b/orca-skills/LICENSE.txt new file mode 100644 index 0000000..fbf46fc --- /dev/null +++ b/orca-skills/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Lovecast Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/orca-skills/README.md b/orca-skills/README.md new file mode 100644 index 0000000..ce18b05 --- /dev/null +++ b/orca-skills/README.md @@ -0,0 +1,26 @@ +# Orca skills (vendored) + +Third-party skills from [Orca](https://github.com/stablyai/orca), vendored +verbatim under the MIT License. See [`CREDITS.md`](CREDITS.md) for provenance +and [`LICENSE.txt`](LICENSE.txt) for the upstream license text. + +These are **not** Spacecraft Software skills. They are merged into the same +canonical install tree as the cross-platform skills because they use the same +open-standard `SKILL.md` format, so every agent on the machine reads them from +one place. + +## Contents + +| Skill | Purpose | +|-------|---------| +| `orca-cli` | Drive the `orca` CLI — worktrees, terminals, repos, automations, artifacts, and Orca's embedded browser | +| `computer-use` | Inspect and operate local desktop app windows via accessibility trees, screenshots, and UI actions | +| `orchestration` | Structured multi-agent coordination — threaded messages, task DAGs, decision gates, coordinator loops | + +## Updating + +Re-copy each `SKILL.md` from the upstream `skills/` directory at a new commit, +then update the provenance commit and date in [`CREDITS.md`](CREDITS.md). Do +not edit the vendored files in place — any local change makes this tree an +*adaptation* rather than a verbatim vendoring, which changes its licensing +posture under Standard §4.2. diff --git a/orca-skills/computer-use/SKILL.md b/orca-skills/computer-use/SKILL.md new file mode 100644 index 0000000..adc6c52 --- /dev/null +++ b/orca-skills/computer-use/SKILL.md @@ -0,0 +1,75 @@ +--- +name: computer-use +description: >- + Use Orca's computer-use CLI to inspect and operate local desktop app windows + through accessibility trees, screenshots, and safe UI actions. Use for + desktop app interaction: list apps/windows, get app state, read visible UI, + click controls, type, press keys, scroll, drag, set values, or perform + accessibility actions. Also use for browser windows, webviews, Orca app UI, + or other desktop UI. Triggers include "computer use", "orca computer", "read + Spotify", "read Slack", "control/click/read in a desktop app", and "get app + state". +--- + +# Computer Use + +This file is a discovery stub, not the usage guide. The full, version-matched computer-use +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's computer-use surface whenever you must inspect or operate a local desktop app +window — reading its accessibility tree, taking screenshots, or performing safe UI actions +(click controls, type, press keys, scroll, drag, set values). It also covers browser +windows, webviews, and Orca's own UI. Triggers include "computer use", "orca computer", +"read Spotify", "read Slack", "control/click/read in a desktop app", and "get app state". + +## 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 computer-use +``` + +That prints the complete, version-matched guide for the exact binary that will handle your +next commands — listing apps/windows, reading UI, and driving clicks, typing, and other +accessibility actions. 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 computer capabilities --json +ORCA computer list-apps --json +``` + +Then tell the user that updating Orca restores the full, version-matched guide via +`ORCA skills get computer-use`. Beyond these commands, ask the user rather than guessing a +command surface this older binary may not support. diff --git a/orca-skills/orca-cli/SKILL.md b/orca-skills/orca-cli/SKILL.md new file mode 100644 index 0000000..b2a3b83 --- /dev/null +++ b/orca-skills/orca-cli/SKILL.md @@ -0,0 +1,79 @@ +--- +name: orca-cli +description: >- + Use the public `orca` CLI to operate Orca-managed worktrees, folder contexts, + terminals, repos, automations, artifacts, skill sharing, worktree comments, and the browser + embedded inside the Orca app. Use when the user says "$orca-cli", "use orca cli", + "Orca worktree", "child worktree", "cardStatus", "spawn codex/claude in a worktree", + "read/wait/send Orca terminal", "terminal send", "full handoff", "handover", + "give this to another agent", "another worktree", "Orca browser", "orca artifacts", + "share HTML/Markdown", "public artifact link", "share skills", or "control the browser inside + Orca". Prefer this over raw `git worktree`, ad hoc + PTYs, Playwright, or Computer Use when the task touches Orca-managed state. + Use Computer Use for browser windows, webviews, or desktop UI outside Orca's + embedded browser. +--- + +# 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. diff --git a/orca-skills/orchestration/SKILL.md b/orca-skills/orchestration/SKILL.md new file mode 100644 index 0000000..fa2643a --- /dev/null +++ b/orca-skills/orchestration/SKILL.md @@ -0,0 +1,82 @@ +--- +name: orchestration +description: >- + Use Orca orchestration for structured multi-agent coordination: threaded + messages, blocking ask/reply flows, task dispatch, worker_done/escalation + waits, task DAGs, decision gates, coordinator loops, or decomposing work + across agents. Use `orca-cli` instead for full ownership handoffs, including + requests phrased as "hand off", "handoff", "handover", "give this to another + agent", or "another worktree" when the user did not explicitly ask to + supervise, monitor, wait for results, or coordinate a DAG. Use `orca-cli` for + ordinary terminal control, lightweight terminal prompts, shell commands, Orca + worktree management, reading or waiting on terminals, and automation of the + browser embedded inside Orca. Use Computer Use for browser windows, webviews, + Orca app UI, or desktop UI outside Orca's embedded browser. +--- + +# Orca Orchestration + +This file is a discovery stub, not the usage guide. The full, version-matched Orca +orchestration 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 orchestration whenever you need structured multi-agent coordination: threaded +messages, blocking ask/reply flows, task dispatch, worker_done/escalation waits, task DAGs, +decision gates, coordinator loops, or decomposing work across agents. Use the orca-cli skill +instead for full ownership handoffs ("hand off", "handoff", "handover", "give this to +another agent", "another worktree") when the user did not ask to supervise, monitor, wait +for results, or coordinate a DAG — and for ordinary terminal control, shell commands, +worktree management, and the built-in browser. Coordination requires real Orca runtime +state; never substitute a non-Orca subagent tool. + +## 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 orchestration +``` + +That prints the complete, version-matched guide for the exact binary that will handle your +next commands — task creation and dispatch, injected lifecycle preambles, worker_done +authority, decision gates, and coordinator loops. 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 orchestration task-list --json +ORCA terminal list --json +``` + +Then tell the user that updating Orca restores the full, version-matched guide via +`ORCA skills get orchestration`. Beyond these commands, ask the user rather than guessing a +command surface this older binary may not support.