[Upstream Orca] maintain all eight Skills against latest hybrid-stub architecture

[TsekaLuk]

Why this is separate

Pebble inherited all eight official Orca skills at v1.4.124-rc.8, then renamed and adapted them for Pebble. Upstream has since replaced the large standalone SKILL.md files with a hybrid stub + version-matched CLI guide architecture. Syncing only the current skills/*/SKILL.md text would miss the new skill-stubs/, skill-guides/, CLI delivery, and release-ledger contracts.

• Fork baseline: v1.4.124-rc.8
• Upstream audited head: 58ef46d
• Upstream skill architecture entry points: skill-guides/, skill-stubs/, skills/

Skill mapping and drift

Pebble skill	Orca upstream	Fork lines	Current upstream lines	Upstream commits after fork
computer-use	computer-use	141	75	3
linear-tickets	linear-tickets	185	80	6
orchestration	orchestration	221	82	9
pebble-cli	orca-cli	307	78	6
pebble-emulator	orca-emulator	156	73	3
pebble-emulator-android	orca-emulator-android	141	73	2
pebble-linear	orca-linear	182	78	6
pebble-per-workspace-env	orca-per-workspace-env	730	81	1

The line-count reduction is architectural, not feature deletion: current upstream skills are small routing stubs, while detailed guidance is version-matched and delivered by the CLI.

Required semantic work

• Port the hybrid stub contract using Pebble names and pebble CLI commands.
• Add Pebble equivalents of all eight skill-stubs/*.md files.
• Add Pebble equivalents of all eight versioned skill-guides/*.md files.
• Identify the Orca CLI commands that resolve/version skill guides and implement the same contract in Pebble CLI/Go runtime where ownership moved.
• Preserve npx skills add https://github.com/nebutra/pebble --skill ... --global.
• Translate every orca, orca://, Orca daemon, Electron IPC, and Orca filesystem assumption.
• Keep local, SSH, remote-runtime, WSL, macOS, Linux, Windows, Claude, Codex, Cursor, OpenCode, Pi, Grok, Droid, and Copilot routing explicit.
• Add installer/update tests proving installed stubs and version-matched guides stay in sync with the released Pebble CLI.
• Add a recurring upstream audit step so this issue is refreshed whenever Orca changes skills/, skill-stubs/, or skill-guides/.

Upstream commits requiring review

• c97d3a497 Replace post-worker_done polling with idle behavior (#7509)
• 7b7a21e3c Give agents access to inline Linear ticket screenshots and media (#7484)
• 3dd3cc9f6 Clarify Orca orchestration tool boundary and sidebar lineage (#7522)
• eaddccf7c skills: prefer agent-first worktree launch; avoid empty shell tabs (#7957)
• 667e04e72 fix: use dynamic agent name in orca-cli worktree fallback command (#8341)
• be258e23e Add Grok orchestration group routing (#8058)
• 3090ff0ed fix(runtime): explain full worktree id selectors (#7432) (#7892)
• 11f116f6b docs(computer-use): clarify get-app-state JSON tree field (#7788)
• 42cf64cdc fix(linux): stop Orca terminals from launching the GNOME Orca screen reader via bare orca (#8347)
• 26934b11b fix(orchestration): complete tasks on worker_done + coordinator UX fixes (#8030)
• 67cd462b2 Add Cursor orchestration group routing (#8436)
• 31f643ca4 Add version-matched skill guides to the CLI (#8624)
• a6df23c76 Tighten orchestration worktree isolation policy (#9482)
• f8b430f72 feat(skills): ship orca-cli as a first-generation hybrid stub (#9238)
• be066fe8e feat(linear): expose issue activity history (#9667)
• 42a4f017b feat(linear): add MCP-compatible issue listing (#9672)
• 87af1c867 feat(linear): add complete issue relations (#9674)
• a10a2ba53 feat(linear): add MCP-style save issue (#9670)
• 1a9e819c4 feat(skills): land remaining hybrid stubs (#9846)
• 43ae014a6 Enable accessibility tree (ax) command on iOS emulator sessions (#10007)
• 4a9affd6e fix(emulator): iOS ax via plain-JSON serve-sim helper (supersedes #10007) (#10029)

Completion evidence

• Each of the eight mappings records ported, already-present, superseded, or not-applicable.
• Every port links Pebble tests and commits.
• Installed skill smoke tests run against a packaged Pebble CLI, not repository source only.

[TsekaLuk]

Resolution: hybrid skills architecture already landed

Pebble now matches the upstream hybrid stub + versioned CLI guide contract (semantic port, not cherry-pick).

Evidence on tree

Contract	Location
Full guides (8)	skill-guides/*.md
Installable stubs (~29 lines each)	skills/*/SKILL.md
Generator	config/scripts/generate-bundled-skill-guides.mjs
Offline CLI retrieval	pebble skills get <name> — TS CLI + Go pebble-control + bundled_skill_guides_generated.go
Docs	docs/upstream-semantic-sync.md
Landing commit	05830a06f feat: add bundled skills semantic sync

Install surface preserved

npx skills add https://github.com/nebutra/pebble --skill pebble-cli --global
pebble skills get pebble-cli

Naming

Orca orca-cli / orca-* → Pebble pebble-cli / pebble-* (plus legacy linear-tickets).

Recurring audit

Twice-weekly / on-demand: .github/workflows/upstream-semantic-sync.yml + config/scripts/upstream-semantic-sync.mjs (skills/stubs/guides paths classified in reports).

Closing this issue as done. New skill/guide deltas from upstream should open as scoped follow-ups (or ride the next [Upstream Sync] range issue), not keep this open forever.

[TsekaLuk]

Closed: hybrid skill-stub + skill-guides + CLI retrieval already on tree (see previous comment).