Merge orchestration-skill-trigger into integration

This commit is contained in:
Jinwoo-H
2026-10-28 13:36:37 -04:00
8 changed files with 64 additions and 55 deletions
+5 -5
View File
@@ -148,16 +148,16 @@
{
"name": "orchestration",
"sourcePath": "skills/orchestration",
"packageDigest": "13530b8456bd56f4b06f95e848e9b99211eecaac2939aae49ed96da5a197c1f5",
"packageDigest": "d3ba9068909bbedcfc990c0637e77d9a75930a0b36a1e378157d72c6aa32db1f",
"files": [
{
"path": "SKILL.md",
"size": 3876,
"size": 4118,
"executable": false,
"classification": "text",
"exactSha256": "ce9a81cb2e6bbb8487107d2e088bf9fd6e0ba71ebc6bcc1929f827fde65fec6b",
"textNormalizedSha256": "ce9a81cb2e6bbb8487107d2e088bf9fd6e0ba71ebc6bcc1929f827fde65fec6b",
"identitySha256": "ce9a81cb2e6bbb8487107d2e088bf9fd6e0ba71ebc6bcc1929f827fde65fec6b"
"exactSha256": "b50c8ce4ea7317fad2ff9a0d8d56e16f4420d6ce6d6b1ea2534d60555a479c5f",
"textNormalizedSha256": "b50c8ce4ea7317fad2ff9a0d8d56e16f4420d6ce6d6b1ea2534d60555a479c5f",
"identitySha256": "b50c8ce4ea7317fad2ff9a0d8d56e16f4420d6ce6d6b1ea2534d60555a479c5f"
}
]
}
+1
View File
@@ -137,6 +137,7 @@
"9ca228137b9a442b98c761aa07adecc2265708132ab175ad7e22b163fdc0bd7f",
"a7e3350f037698ebbce36b2818d8383ec6e96c2a4825537caab39a83b4fb4b7f",
"abb639ec034ab3f50fddf3dc02c4a041876c34278f529ec2c044c0cda7b74059",
"b50c8ce4ea7317fad2ff9a0d8d56e16f4420d6ce6d6b1ea2534d60555a479c5f",
"b73c7c665aa233a782ba81982ebc954e220fdf1c1c6ca2b6bf38133c1cd76fc9",
"cd1b364bf35781bad06bf75ab1766afa8d6cec69cb2060529691d89871a2098a",
"ce9a81cb2e6bbb8487107d2e088bf9fd6e0ba71ebc6bcc1929f827fde65fec6b",
+3 -3
View File
@@ -24,7 +24,7 @@ Prefer `--json` for agent-driven calls. If the CLI is missing, say so explicitly
## Full Handoffs
A full handoff transfers ownership to another agent or worktree, then the original agent stops. Treat requests phrased as "hand off", "handoff", "handover", "give this to another agent", "give this to another worktree", "another agent", or "another worktree" as full handoffs unless the user explicitly asks to supervise, monitor, wait for results, track completion, coordinate a DAG, use decision gates, or manage ask/reply.
A full handoff transfers ownership to another agent or worktree, then the original agent stops. Treat requests phrased as "hand off", "handoff", "handover", "give this to another agent", "give this to another worktree", "another agent", or "another worktree" as full handoffs unless the user expects the result back ("have another agent review this and report") or explicitly asks to supervise, monitor, wait for results, track completion, coordinate a DAG, use decision gates, or manage ask/reply.
A handoff is done when the new worktree id and agent handle have been reported and the prompt was delivered: the launch's `prompt.outcome` is `journaled` or `handed-to-terminal`, or, for an agent that was already running, the send receipt reported `accepted: true`. Do not wait for the receiving agent to finish.
@@ -159,7 +159,7 @@ ORCA reference find STA-1234 --json
- Repeat create `--reference` to seed links before setup/agent startup. Do not combine it with legacy `--pr`, `--issue`, `--linear-issue`, `--gitlab-issue`, or `--gitlab-mr` flags. Legacy `worktree set --pr` still appends/selects; `linkedItems` remains the worktree output field.
- Find accepts a full URL or native issue key such as `STA-1234`; no bare numbers or custom shorthand. It searches stored links across sources, not conversation text (`ORCA search`). Narrow with `--worktree` or `--repo`; optionally `--include-archived`, `--limit` (default 50 workspaces). Check `truncated` before assuming complete coverage. Remote selectors refer to the execution host; never use local `current` for a paired host.
- Find returns all known agents in each matching workspace. `linked: true` requires recorded reference/session evidence; `linked: false` means ownership is unknown. Check `liveness` (`live`, `unverifiable`, `exited`) and choose the intended agent; never infer ownership merely from workspace membership.
- Send through the returned exact `terminal` handle or `mailbox` (`dispatch:<id>` / `orca_session_id:<id>`). A `run:<id>` targets a coordinator. Find does not send, and adding links from a shell records no agent ownership.
- Send through the returned exact `terminal` handle or `mailbox` (`dispatch:<id>` / `orca_session_id:<id>`). If it returns a `dispatch:<id>` mailbox, the agent is a supervised worker: use the mailbox, not terminal input. A `run:<id>` targets a coordinator. Find does not send, and adding links from a shell records no agent ownership.
```text
ORCA terminal send --terminal <terminal-from-find> --text "Status?" --enter --json
@@ -236,7 +236,7 @@ Terminal rules:
- A default send observes for 0 seconds, so a receipt that stops at `input_accepted` is expected and its warning means "unproven", not "failed". Pass `--wait-submit` when you need proof of submission.
- `--wait-submit <seconds>` only observes the same accepted prompt. A timeout returns queued/input-accepted truth without resending; after an ambiguous transport failure, repeat the exact command with the reported `--retry-request <id>`. Both text and `--json` receipts carry the same `warnings`.
- An older host reports a legacy `old-host` fallback for an ordinary send and refuses `--wait-submit` or `--retry-request` before input, because it cannot provide durable replay.
- For structured coordination, invoke the `orchestration` skill; it uses `orca orchestration ...` commands for messages, handoffs, task DAGs, dispatches, inbox/reply flows, and coordinator loops. A receiving agent can run `orca orchestration check --peek --format --json` to render its unread mail in agent-readable form; this checks the caller's inbox and does not remotely deliver input to another terminal.
- For structured coordination, invoke the `orchestration` skill; it uses `orca orchestration ...` commands for messages, task DAGs, dispatches, inbox/reply flows, and coordinator loops. A receiving agent can run `orca orchestration check --peek --format --json` to render its unread mail in agent-readable form; this checks the caller's inbox and does not remotely deliver input to another terminal.
- Start a fresh agent with `agent launch` in the current worktree, or `worktree create --agent` for a separate checkout (see Starting agents).
- Use `terminal wait --for tui-idle` for agent CLIs such as Claude Code, Gemini, Codex, OMP, Pi, and Grok; always pass `--timeout-ms`.
- For long output, use cursor reads. After a limited tail preview, page from `oldestCursor`; after a cursor read, continue with `nextCursor` while `limited` is true and `nextCursor !== latestCursor`.
+10 -8
View File
@@ -1,14 +1,16 @@
---
name: orchestration
description: >-
Coordinate supervised Orca workers, or work as a dispatched worker
(heartbeats, ask, worker_done): threaded messages, blocking ask/reply, task
dispatch, worker_done/escalation waits, task DAGs, decision gates,
coordinator loops, and decomposing work across agents. Use `orca-cli` for full
ownership handoffs — "hand off", "handoff", "handover", "give this to another
agent", "another worktree" — unless asked to supervise, monitor, or coordinate
a DAG, and for terminal control, lightweight terminal prompts, shell commands,
Orca worktree management, and reading or waiting on terminals.
Run work in separate Orca worker agents and get their results back. Use when
the user asks for Orca workers or supervision (monitor, task DAGs, ask/reply,
decision gates), or when the work needs something your own subagents cannot
give: a different agent (such as Codex from Claude) or its own Orca workspace.
Also use when you are a dispatched worker (a prompt with Task and Dispatch
IDs: heartbeats, ask, worker_done). Otherwise prefer your own subagents,
including for long or parallel work. Use `orca-cli` to hand work off with
nothing expected back ("hand off", "handover", "give this to another agent",
"another worktree"), and for terminal control, shell commands, worktree
management, and reading or waiting on terminals.
---
# Orca orchestration
+10 -9
View File
@@ -4,15 +4,16 @@ This file is a discovery stub, not the usage guide. The full, version-matched Or
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. Engage it as well
when you are a dispatched worker sending heartbeats, `ask` questions, or `worker_done`. 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.
Use Orca orchestration to run work in separate Orca worker agents and get their results
back: when the user asks for Orca workers or supervision (monitor, task DAGs, ask/reply,
decision gates), or when the work needs something your own subagents cannot give, such as a
different agent or its own Orca workspace. Use it as well when you are a dispatched worker
sending heartbeats, `ask` questions, or `worker_done`. Otherwise prefer your own subagents,
including for long or parallel work. Use the orca-cli skill instead to hand work off with
nothing expected back ("hand off", "handoff", "handover", "give this to another agent",
"another worktree"), 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 when the user asked for Orca orchestration.
<!-- shared: resolver -->
+20 -17
View File
@@ -1,14 +1,16 @@
---
name: orchestration
description: >-
Coordinate supervised Orca workers, or work as a dispatched worker
(heartbeats, ask, worker_done): threaded messages, blocking ask/reply, task
dispatch, worker_done/escalation waits, task DAGs, decision gates,
coordinator loops, and decomposing work across agents. Use `orca-cli` for full
ownership handoffs — "hand off", "handoff", "handover", "give this to another
agent", "another worktree" — unless asked to supervise, monitor, or coordinate
a DAG, and for terminal control, lightweight terminal prompts, shell commands,
Orca worktree management, and reading or waiting on terminals.
Run work in separate Orca worker agents and get their results back. Use when
the user asks for Orca workers or supervision (monitor, task DAGs, ask/reply,
decision gates), or when the work needs something your own subagents cannot
give: a different agent (such as Codex from Claude) or its own Orca workspace.
Also use when you are a dispatched worker (a prompt with Task and Dispatch
IDs: heartbeats, ask, worker_done). Otherwise prefer your own subagents,
including for long or parallel work. Use `orca-cli` to hand work off with
nothing expected back ("hand off", "handover", "give this to another agent",
"another worktree"), and for terminal control, shell commands, worktree
management, and reading or waiting on terminals.
---
# Orca Orchestration
@@ -17,15 +19,16 @@ This file is a discovery stub, not the usage guide. The full, version-matched Or
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. Engage it as well
when you are a dispatched worker sending heartbeats, `ask` questions, or `worker_done`. 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.
Use Orca orchestration to run work in separate Orca worker agents and get their results
back: when the user asks for Orca workers or supervision (monitor, task DAGs, ask/reply,
decision gates), or when the work needs something your own subagents cannot give, such as a
different agent or its own Orca workspace. Use it as well when you are a dispatched worker
sending heartbeats, `ask` questions, or `worker_done`. Otherwise prefer your own subagents,
including for long or parallel work. Use the orca-cli skill instead to hand work off with
nothing expected back ("hand off", "handoff", "handover", "give this to another agent",
"another worktree"), 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 when the user asked for Orca orchestration.
## Resolve the CLI for this session
+14 -12
View File
@@ -407,7 +407,7 @@ const ORCA_CLI_MARKDOWN = [
"",
"## Full Handoffs",
"",
"A full handoff transfers ownership to another agent or worktree, then the original agent stops. Treat requests phrased as \"hand off\", \"handoff\", \"handover\", \"give this to another agent\", \"give this to another worktree\", \"another agent\", or \"another worktree\" as full handoffs unless the user explicitly asks to supervise, monitor, wait for results, track completion, coordinate a DAG, use decision gates, or manage ask/reply.",
"A full handoff transfers ownership to another agent or worktree, then the original agent stops. Treat requests phrased as \"hand off\", \"handoff\", \"handover\", \"give this to another agent\", \"give this to another worktree\", \"another agent\", or \"another worktree\" as full handoffs unless the user expects the result back (\"have another agent review this and report\") or explicitly asks to supervise, monitor, wait for results, track completion, coordinate a DAG, use decision gates, or manage ask/reply.",
"",
"A handoff is done when the new worktree id and agent handle have been reported and the prompt was delivered: the launch's `prompt.outcome` is `journaled` or `handed-to-terminal`, or, for an agent that was already running, the send receipt reported `accepted: true`. Do not wait for the receiving agent to finish.",
"",
@@ -542,7 +542,7 @@ const ORCA_CLI_MARKDOWN = [
"- Repeat create `--reference` to seed links before setup/agent startup. Do not combine it with legacy `--pr`, `--issue`, `--linear-issue`, `--gitlab-issue`, or `--gitlab-mr` flags. Legacy `worktree set --pr` still appends/selects; `linkedItems` remains the worktree output field.",
"- Find accepts a full URL or native issue key such as `STA-1234`; no bare numbers or custom shorthand. It searches stored links across sources, not conversation text (`ORCA search`). Narrow with `--worktree` or `--repo`; optionally `--include-archived`, `--limit` (default 50 workspaces). Check `truncated` before assuming complete coverage. Remote selectors refer to the execution host; never use local `current` for a paired host.",
"- Find returns all known agents in each matching workspace. `linked: true` requires recorded reference/session evidence; `linked: false` means ownership is unknown. Check `liveness` (`live`, `unverifiable`, `exited`) and choose the intended agent; never infer ownership merely from workspace membership.",
"- Send through the returned exact `terminal` handle or `mailbox` (`dispatch:<id>` / `orca_session_id:<id>`). A `run:<id>` targets a coordinator. Find does not send, and adding links from a shell records no agent ownership.",
"- Send through the returned exact `terminal` handle or `mailbox` (`dispatch:<id>` / `orca_session_id:<id>`). If it returns a `dispatch:<id>` mailbox, the agent is a supervised worker: use the mailbox, not terminal input. A `run:<id>` targets a coordinator. Find does not send, and adding links from a shell records no agent ownership.",
"",
"```text",
"ORCA terminal send --terminal <terminal-from-find> --text \"Status?\" --enter --json",
@@ -619,7 +619,7 @@ const ORCA_CLI_MARKDOWN = [
"- A default send observes for 0 seconds, so a receipt that stops at `input_accepted` is expected and its warning means \"unproven\", not \"failed\". Pass `--wait-submit` when you need proof of submission.",
"- `--wait-submit <seconds>` only observes the same accepted prompt. A timeout returns queued/input-accepted truth without resending; after an ambiguous transport failure, repeat the exact command with the reported `--retry-request <id>`. Both text and `--json` receipts carry the same `warnings`.",
"- An older host reports a legacy `old-host` fallback for an ordinary send and refuses `--wait-submit` or `--retry-request` before input, because it cannot provide durable replay.",
"- For structured coordination, invoke the `orchestration` skill; it uses `orca orchestration ...` commands for messages, handoffs, task DAGs, dispatches, inbox/reply flows, and coordinator loops. A receiving agent can run `orca orchestration check --peek --format --json` to render its unread mail in agent-readable form; this checks the caller's inbox and does not remotely deliver input to another terminal.",
"- For structured coordination, invoke the `orchestration` skill; it uses `orca orchestration ...` commands for messages, task DAGs, dispatches, inbox/reply flows, and coordinator loops. A receiving agent can run `orca orchestration check --peek --format --json` to render its unread mail in agent-readable form; this checks the caller's inbox and does not remotely deliver input to another terminal.",
"- Start a fresh agent with `agent launch` in the current worktree, or `worktree create --agent` for a separate checkout (see Starting agents).",
"- Use `terminal wait --for tui-idle` for agent CLIs such as Claude Code, Gemini, Codex, OMP, Pi, and Grok; always pass `--timeout-ms`.",
"- For long output, use cursor reads. After a limited tail preview, page from `oldestCursor`; after a cursor read, continue with `nextCursor` while `limited` is true and `nextCursor !== latestCursor`.",
@@ -2336,14 +2336,16 @@ const ORCHESTRATION_MARKDOWN = [
"---",
"name: orchestration",
"description: >-",
" Coordinate supervised Orca workers, or work as a dispatched worker",
" (heartbeats, ask, worker_done): threaded messages, blocking ask/reply, task",
" dispatch, worker_done/escalation waits, task DAGs, decision gates,",
" coordinator loops, and decomposing work across agents. Use `orca-cli` for full",
" ownership handoffs — \"hand off\", \"handoff\", \"handover\", \"give this to another",
" agent\", \"another worktree\" — unless asked to supervise, monitor, or coordinate",
" a DAG, and for terminal control, lightweight terminal prompts, shell commands,",
" Orca worktree management, and reading or waiting on terminals.",
" Run work in separate Orca worker agents and get their results back. Use when",
" the user asks for Orca workers or supervision (monitor, task DAGs, ask/reply,",
" decision gates), or when the work needs something your own subagents cannot",
" give: a different agent (such as Codex from Claude) or its own Orca workspace.",
" Also use when you are a dispatched worker (a prompt with Task and Dispatch",
" IDs: heartbeats, ask, worker_done). Otherwise prefer your own subagents,",
" including for long or parallel work. Use `orca-cli` to hand work off with",
" nothing expected back (\"hand off\", \"handover\", \"give this to another agent\",",
" \"another worktree\"), and for terminal control, shell commands, worktree",
" management, and reading or waiting on terminals.",
"---",
"",
"# Orca orchestration",
@@ -3315,7 +3317,7 @@ export const BUNDLED_SKILL_GUIDES = [
},
{
name: "orchestration",
description: "Coordinate supervised Orca workers, or work as a dispatched worker (heartbeats, ask, worker_done): threaded messages, blocking ask/reply, task dispatch, worker_done/escalation waits, task DAGs, decision gates, coordinator loops, and decomposing work across agents. Use `orca-cli` for full ownership handoffs — \"hand off\", \"handoff\", \"handover\", \"give this to another agent\", \"another worktree\" — unless asked to supervise, monitor, or coordinate a DAG, and for terminal control, lightweight terminal prompts, shell commands, Orca worktree management, and reading or waiting on terminals.",
description: "Run work in separate Orca worker agents and get their results back. Use when the user asks for Orca workers or supervision (monitor, task DAGs, ask/reply, decision gates), or when the work needs something your own subagents cannot give: a different agent (such as Codex from Claude) or its own Orca workspace. Also use when you are a dispatched worker (a prompt with Task and Dispatch IDs: heartbeats, ask, worker_done). Otherwise prefer your own subagents, including for long or parallel work. Use `orca-cli` to hand work off with nothing expected back (\"hand off\", \"handover\", \"give this to another agent\", \"another worktree\"), and for terminal control, shell commands, worktree management, and reading or waiting on terminals.",
markdown: ORCHESTRATION_MARKDOWN,
aliases: [],
references: [{ name: "coordinator-loop", markdown: ORCHESTRATION_COORDINATOR_LOOP_REFERENCE_MARKDOWN }, { name: "legacy-contract-migration", markdown: ORCHESTRATION_LEGACY_CONTRACT_MIGRATION_REFERENCE_MARKDOWN }, { name: "low-level-topology", markdown: ORCHESTRATION_LOW_LEVEL_TOPOLOGY_REFERENCE_MARKDOWN }, { name: "messaging-and-gates", markdown: ORCHESTRATION_MESSAGING_AND_GATES_REFERENCE_MARKDOWN }, { name: "placement-and-remote", markdown: ORCHESTRATION_PLACEMENT_AND_REMOTE_REFERENCE_MARKDOWN }, { name: "recovery-and-cleanup", markdown: ORCHESTRATION_RECOVERY_AND_CLEANUP_REFERENCE_MARKDOWN }, { name: "worker-contract", markdown: ORCHESTRATION_WORKER_CONTRACT_REFERENCE_MARKDOWN }]
File diff suppressed because one or more lines are too long