skills: prefer agent-first worktree launch; avoid empty shell tabs

[ryushione]

Summary

• Document agent-first worktree creation in skills/orca-cli and skills/orchestration so ordinary agent workers do not gain a separate fallback shell.
• Prefer worktree create --agent <id> for known TUI agents; repo-configured setup/default-terminal tabs remain intentional and may still add tabs or splits.
• Use startupTerminal.handle as the sole destination when returned; re-list only when the handle is missing or stale, and never dual-send.
• Clarify that orchestration check --unread --inject renders the inbox for the agent that runs it; use dispatch --inject or terminal send for remote delivery.
• Add regression tests for the guidance and safe handling of configured default terminals.

This is skill guidance and static tests only; no product runtime code changes. It aligns with the CLI contract that --agent launches the selected agent in the first terminal.

Why

The two-step create-then-launch path can leave a fallback shell when no configured default terminal supplies the primary surface. Agent-first creation avoids that extra worker shell while preserving setup/default terminals that may run real commands. Custom argv, such as Codex model or effort flags, still requires the two-step fallback.

Test plan

• pnpm vitest run config/scripts/orca-cli-skill-guidance.test.mjs config/scripts/orchestration-skill-guidance.test.mjs — 13 tests passed
• Worktree provisioning oracles — 3 tests passed
• Orchestration injection contracts — 2 tests passed
• pnpm typecheck
• Two-round adversarial review/fix loop; both final reviewers clean
• Performance audit clean

[ryushione]

Smoke results (local Orca runtime)

Agent-first create (worktree create --agent <id> --setup skip):

Agent	Tabs after create	createdWithAgent	Orchestration pong
omp	1 (OMP ready)	omp	yes — pong from omp
pi	1 (Pi ready)	pi	yes — pong from pi
claude	1 (Claude Code)	claude	yes — pong from claude

Anti-pattern control (bare create + terminal create --command grok):

Worktree	Tabs
orch-ab-manual	2 (..rch-ab-manual shell + grok)
orch-ab-agent (--agent grok)	1 (grok)

Matches the skill guidance: --agent → one first-terminal agent tab; bare create + second terminal → empty shell leftover.

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request updates Orca CLI and orchestration skill documentation with agent-first worktree creation guidance, startup terminal handle acquisition and recovery rules, bare-create behavior, Codex handoff constraints, and compatibility fallbacks. Terminal messaging guidance now specifies single live agent handles and clarifies that unread-mail injection renders in the executing terminal without remotely waking another terminal. New tests validate the documented agent-first, handle, and injection guidance.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers summary, rationale, and tests, but omits required Screenshots, AI Review Report, Security Audit, and Notes sections.	Add the missing template sections: Screenshots, AI Review Report, Security Audit, and Notes, and confirm the required cross-platform review coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise and accurately reflects the main change: preferring agent-first worktree launch to avoid extra shell tabs.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[AmethystLiang]

Thanks for documenting the agent-first workflow. I verified the underlying terminal and orchestration behavior and tightened the guidance:

• preserves configured setup/default-terminal surfaces
• uses the returned startup handle, with missing/stale recovery only
• distinguishes caller-local inbox checks from remote task/prompt delivery
• adds focused regression coverage

Typecheck and the affected guidance, runtime, and orchestration tests pass.

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: f0a54744-c429-4bc5-9be5-e606cd1d48aa

📥 Commits

Reviewing files that changed from the base of the PR and between 3a73fc0 and 5f7ede4.

📒 Files selected for processing (4)

• config/scripts/orca-cli-skill-guidance.test.mjs
• config/scripts/orchestration-skill-guidance.test.mjs
• skills/orca-cli/SKILL.md
• skills/orchestration/SKILL.md

🚧 Files skipped from review as they are similar to previous changes (1)

• skills/orchestration/SKILL.md

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Preserve the requested agent in the compatibility fallback.

This fallback always launches codex, so requests for claude, omp, pi, grok, or another agent silently start the wrong worker. Use the originally requested agent ID/command instead.

Proposed fix

- If an older installed CLI rejects `--agent`, `--prompt`, or `--setup`, create the worktree normally, then run `orca terminal create --worktree <selector> --command "codex"` and `orca terminal send` if a prompt is needed.
+ If an older installed CLI rejects `--agent`, `--prompt`, or `--setup`, create the worktree normally, then run `orca terminal create --worktree <selector> --command "<requested-agent>"` and `orca terminal send` if a prompt is needed.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	- If an older installed CLI rejects `--agent`, `--prompt`, or `--setup`, create the worktree normally, then run `orca terminal create --worktree <selector> --command "codex"` and `orca terminal send` if a prompt is needed. This can leave a fallback shell when no default tabs are configured; close it only after confirming it is unused.
	- If an older installed CLI rejects `--agent`, `--prompt`, or `--setup`, create the worktree normally, then run `orca terminal create --worktree <selector> --command "<requested-agent>"` and `orca terminal send` if a prompt is needed. This can leave a fallback shell when no default tabs are configured; close it only after confirming it is unused.

🧰 Tools

🪛 SkillSpector (2.3.7)

[warning] 282: [RP1] null: npx commands without a version suffix (e.g. @1.0.0) create a rug-pull risk if the upstream server is compromised and publishes a malicious update.

Remediation: Pin the version: npx @scope/server@1.2.3

(MCP Rug Pull (RP1))