feat(orca-skills): vendor Orca's orca-cli, computer-use, orchestration

REUSE.toml

@@ -57,6 +57,17 @@ precedence = "override"
 SPDX-FileCopyrightText = ["Vercel, Inc.", "2026 Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org>"]
 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

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

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 | <https://github.com/stablyai/orca> |
+| 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.

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.

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.

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.

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.