[Tauri-EPO]

ELI5

orca orchestration task-create --help listed --spec, --deps, --parent and friends with nothing after them — you had to guess what each flag means or learn it from an error. Now every orchestration flag carries a one-line description, and the description lives in the command spec itself so a new flag can't ship undescribed by accident.

What Changed

Before, most options on orca orchestration <command> --help printed as a bare --flag with no description, and rows from the shared help tables were hand-padded, so descriptions started in different columns (entries written with a single space, such as --setup run|skip|inherit Setup policy…, printed as one long label).

• CommandSpec gains an optional flagHelp map. A spec can describe its own flags; flags it omits keep their description from the shared tables (FLAG_HELP_TEXT, command-scoped help), so commands that don't use it are unchanged.
• formatCommandHelp splits each row into label and description and starts every description in one column. Single-spaced shared entries are split correctly: a value spec is always bracketed (<id>) or alternation-separated (run|skip|inherit).
• Every orchestration command now describes every flag it accepts (30 commands, 69 distinct flags). Each description was written from what the handler does with the flag.
• The send/check/reply/inbox and gate specs moved to their own files to stay under max-lines; spec contents and order are unchanged apart from flagHelp.
• A ratchet test fails if an orchestration flag has no spec-level description, if a spec re-describes a global flag or --retry-request, or if a rendered orchestration option row has no description.

Relationship to #24194: complementary. It adds shared-table descriptions for --environment, --pairing-code, --wait-submit and --retry-request; this PR does not describe those, and the ratchet keeps orchestration specs from duplicating them. Until it lands, the rendered-row check exempts --pairing-code, --environment and --retry-request; whichever PR lands second can drop that exemption. Its diff applied on top of this branch passes both PRs' tests, and the new rows align in the same column.

Why

For an agent driving the CLI this is not cosmetic: with only --help to go on, coordinators discover flag semantics by trial and error. In a 12-hour orchestration session (#17391), lanes repeatedly burned turns probing orchestration flags whose meaning the help never states. The structural cause was that help text lived in hand-maintained side tables in help.ts, so every new flag started undescribed; carrying the description in the spec removes the whack-a-mole.

Linked Issue

Fixes #17391

Visual Proof

N/A — CLI help text; the ratchet test enumerates the coverage. Rendered orca orchestration worker-start --help options after the change (the three bare rows are left to #24194):

  --pairing-code
  --environment
  --task <task_id>            Existing task to assign to the worker
  --on <saved-environment>    Saved environment whose Orca server runs the worker
  --worktree <placement>      current, an existing worktree selector, new-child, or new-top-level
  --setup <run|skip|inherit>  Setup policy for a new worktree (default run)
  --retry-of <dispatch_id>    Prior Dispatch this attempt replaces; needs --task
  --run <run_id>              Run to act in instead of the caller's bound Run
  --from <handle>             Caller identity; defaults to this terminal or agent session
  --retry-request

Testing

• I manually tested these changes locally (verification is by the test suite)
• Automated tests added/updated, or explained why not below

Rebuilt on main (de8bffe) on 2026-10-02, Windows 11, Node 24.19, pnpm 12.8:

• pnpm test src/cli: 1463 passed, 45 skipped, 14 failed. The same 14 tests fail on an untouched main on this machine (recovery-command executable resolution, client-recovery timeouts); no new failures.
• pnpm tc:cli: exit 0.
• oxlint, oxfmt --check, pnpm run check:code-quality:changed, check:max-lines-ratchet, verify:bundled-skill-guides: pass. No max-lines disable or per-file bump.
• Not run locally: pnpm build and the full pnpm test.

AI Disclosure

Implemented by a Codex lane under my orchestration (strict TDD), reviewed and re-verified locally by me with Claude Code assistance.

Review

• Blast radius: help rendering only; allowedFlags validation, parsing, and RPC surfaces untouched. No wire-visible change, so no client/host compatibility concern.
• Cross-platform: pure string formatting, no path or shell handling.
• Accuracy: descriptions were written against the handlers, not guessed; the --agent/--terminal exclusivity note was deliberately left to the usage line where it already lives.
• Maintainability: the ratchet test converts "someone remembers the side table" into a failing test.

Agent skill upstream boundary

• Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Checklist

• This PR is small and focused
• I explained what changed and why (including ELI5)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

Author

X: @EnricoPin

[greptile-apps]

Greptile Summary

This PR adds per-command flag descriptions to command specifications, backfills orchestration help, and restructures orchestration message specifications.

• Adds structured label and description resolution with shared-column rendering.
• Adds orchestration-wide flag-help coverage and precedence tests.
• Moves message command specifications into a dedicated module.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/cli/command-flag-help-layout.ts	Adds structured flag-help parsing for the aligned command-help renderer.
src/cli/help.ts	Renders option descriptions in a column derived from resolved labels.
src/cli/specs/orchestration-flag-help.ts	Centralizes descriptions for shared orchestration flags.
src/cli/specs/orchestration-message-specs.ts	Moves message command specifications and adds their per-flag descriptions.
src/cli/specs/orchestration-worker-specs.ts	Backfills structured help for orchestration worker flags.
src/cli/specs/orchestration.ts	Backfills orchestration command flag descriptions and composes extracted message specifications.
src/cli/specs/orchestration.test.ts	Adds coverage, alignment, and precedence tests for orchestration flag help.

_{Reviews (2): Last reviewed commit: "feat(cli): describe orchestration flags" | Re-trigger Greptile}

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: fa4f8838-5b17-445c-8088-6cf043887879

📥 Commits

Reviewing files that changed from the base of the PR and between 78494921cd9566927d535248bc5d31eac02ae841 and 0296c39.

📒 Files selected for processing (12)

• src/cli/command-flag-help-layout.test.ts
• src/cli/command-flag-help-layout.ts
• src/cli/command-spec.ts
• src/cli/handlers/orchestration-worker-cli.test.ts
• src/cli/help.ts
• src/cli/index.test.ts
• src/cli/specs/orchestration-flag-help.test.ts
• src/cli/specs/orchestration-flag-help.ts
• src/cli/specs/orchestration-gate-specs.ts
• src/cli/specs/orchestration-message-specs.ts
• src/cli/specs/orchestration-worker-specs.ts
• src/cli/specs/orchestration.ts

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

• src/cli/index.test.ts
• src/cli/specs/orchestration-worker-specs.ts
• src/cli/handlers/orchestration-worker-cli.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The CLI now supports optional per-command flag descriptions in CommandSpec. The help formatter resolves these descriptions before shared help text and aligns descriptions in the output. Orchestration command specifications now include descriptions for worker, run, task, dispatch, request, ask, message, gate, and reset flags. Help-output tests now allow variable horizontal spacing.

Priority: ➖ Normal

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 0296c

This change adds per-flag descriptions to the orchestration CLI help and aligns them in columns. It does not change command behavior, and no merge-blocking issue was found.

Security Architecture Review

Security architecture risk: ⚪ Minimal · up to 0296c

The new descriptions affect help output, not accepted arguments or command authority. Existing caller-identity controls are preserved, and no material security risk was identified in the reviewed change.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The reviewed flagHelp contract propagates through shared CLI help presentation, not through additional runtime requests or privileges. Its fanout therefore concerns displayed help rather than expanded access to orchestration resources.

Trust Boundaries and Controls

• observed — Caller-role identity flags remain subject to the existing pre-dispatch session check. Extracting the specifications preserves those roles; it does not establish a new identity or trust boundary.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	Issue #17391 requires one-line help descriptions for orchestration flags and a spec-carried source. The PR adds flagHelp, precedence handling, aligned rendering, and descriptions for most orchestrat…	Add non-empty descriptions for pairing-code, environment, and retry-request in the applicable orchestration specs or shared definitions. Verify that their rendered orchestration help rows contain descriptions. Keep the worker-start …
Docstring Coverage	⚠️ Warning	Docstring coverage is 26.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 15 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Out of Scope Changes check	✅ Passed	The changes stay within the help-description objective in issue #17391. The new layout helpers, precedence tests, alignment tests, orchestration flag coverage tests, and movement of message and gate s…
Title check	✅ Passed	The title clearly summarizes the main change: adding per-flag help descriptions to command specifications and backfilling orchestration commands.
Description check	✅ Passed	The description is complete and directly related to the changes. It includes the user impact, implementation details, rationale, linked issue, visual-proof status, testing results, AI disclosure, revi…

Full details: Linked Issues check

Explanation

Issue #17391 requires one-line help descriptions for orchestration flags and a spec-carried source. The PR adds flagHelp, precedence handling, aligned rendering, and descriptions for most orchestration flags. However, orchestration-flag-help.test.ts explicitly excludes pairing-code, environment, and retry-request because they still have no shared descriptions. Issue #17391 names pairing-code and environment as missing descriptions, and its only stated exception is the worker-start exclusivity behavior.

Resolution

Add non-empty descriptions for pairing-code, environment, and retry-request in the applicable orchestration specs or shared definitions. Verify that their rendered orchestration help rows contain descriptions. Keep the worker-start exclusivity behavior out of scope.

• Fix all pre-merge checks with AI

---

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.}

[pullfrog]

ℹ️ No critical issues — minor suggestions inline.

Reviewed changes

• Spec-level flagHelp: CommandSpec gains an optional flagHelp?: Record<string, string>, consulted first by the help renderer with the existing special-case and global maps kept as fallback.
• Orchestration backfill: every orchestration flag now carries a one-line description, sharing a base map via orchestrationFlagHelp() with per-spec overrides; message specs were extracted to orchestration-message-specs.ts.
• Ratchet + precedence tests: a ratchet test asserts every orchestration flag has spec-level help, and a precedence test pins spec-level over global.

ℹ️ Nitpicks

• The four orchestration special cases still in src/cli/help.ts (orchestration worker-read cursor, orchestration worker-list terminal-state, orchestration task-create task-title/display-name) are now unreachable because spec-level flagHelp covers those flags. Remove them so the old side table doesn't drift silently.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 85ebfaba-288c-4fd9-a869-0a51d1413615

📥 Commits

Reviewing files that changed from the base of the PR and between 212c0e4 and 932b2bdf1c90a8163bbfd2fbd5ea4ca7a08c1fde.

📒 Files selected for processing (9)

• src/cli/command-flag-help-layout.ts
• src/cli/command-spec.ts
• src/cli/help.ts
• src/cli/index.test.ts
• src/cli/specs/orchestration-flag-help.ts
• src/cli/specs/orchestration-message-specs.ts
• src/cli/specs/orchestration-worker-specs.ts
• src/cli/specs/orchestration.test.ts
• src/cli/specs/orchestration.ts

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

• src/cli/command-spec.ts
• src/cli/specs/orchestration-flag-help.ts
• src/cli/specs/orchestration-worker-specs.ts
• src/cli/specs/orchestration.ts
• src/cli/specs/orchestration-message-specs.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 6 remain after this review.

[pullfrog]

ℹ️ No critical issues — one alignment regression in the legacy help fallback; prior feedback is otherwise addressed cleanly.

Reviewed changes

• Dynamic column alignment: new resolveFlagHelp in src/cli/command-flag-help-layout.ts splits labels from descriptions, and formatCommandHelp now pads labels to a computed description column instead of relying on hand-spaced strings.
• Single-space normalization: every orchestration spec-level flagHelp dropped its manual double space, and the ratchet test now also rejects a \s{2,} after a <...> placeholder.
• Prior feedback addressed: worker-list --terminal-state re-enumerates the valid states; worker-start gained a --terminal/--worktree reuse note and clearer placement wording.
• Test updates: linear / worker-read / task-create assertions moved to \s+ regex matching, and a new test pins worker-start descriptions to a single column.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[Tauri-EPO]

Rebased onto main at 9d29e6878e, after #16904. Head is now ccf33da62868656d7969087700230724a1f6b935.

Four conflicts, all resolved in favour of main's behaviour:

• help.ts — kept the formatSkillsCommandFlagHelp delegation, renamed the fallback chain to formatLegacyCommandFlagHelp.
• specs/orchestration-worker-specs.ts — kept main's worker-list usage and flags, and described the new --include-remote, --cursor and --limit.
• specs/orchestration.ts — kept the send/check/reply/inbox extraction; the notes #16904 and #17487 added to send and check moved with those specs, unchanged.
• specs/orchestration.test.ts — add/add, concatenated: main's three describe blocks plus this PR's help-coverage block.

worker-start also gained --spec, --task-title, --deps and --parent in #16904; the ratchet test required descriptions for those too, so they are in.

help.ts crossed the 300-line max-lines budget after the rebase, so the fallback flag-help chain moved into legacy-command-flag-help.ts. No disable, no per-file bump.

Verified on Windows 11 / Node 24 / pnpm 12: pnpm tc:cli and pnpm tc:node exit 0; oxlint on all changed files exits 0; check:code-quality:changed reports 0 new findings across 12 changed files; vitest run src/cli gives 1145 passed / 13 failed / 30 skipped, and the same 13 fail identically on a clean checkout of main at 9d29e6878e (Windows argv-quoting expectations and EACCES on AF_UNIX sockets in the Windows temp directory). Not re-run locally: pnpm build and the full pnpm test.

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Team

Run ID: 382925c1-7efe-4b4d-ac8f-0c9ec4f9eb08

📥 Commits

Reviewing files that changed from the base of the PR and between 8cd0abf and ccf33da62868656d7969087700230724a1f6b935.

📒 Files selected for processing (12)

• src/cli/command-flag-help-layout.ts
• src/cli/command-spec.ts
• src/cli/handlers/orchestration-worker-cli.test.ts
• src/cli/help.ts
• src/cli/index.test.ts
• src/cli/legacy-command-flag-help.ts
• src/cli/specs/orchestration-flag-help.ts
• src/cli/specs/orchestration-message-specs.ts
• src/cli/specs/orchestration-worker-specs.ts
• src/cli/specs/orchestration.test.ts
• src/cli/specs/orchestration.ts
• src/cli/specs/skills.test.ts

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

• src/cli/command-spec.ts
• src/cli/specs/orchestration-flag-help.ts
• src/cli/index.test.ts
• src/cli/specs/orchestration-message-specs.ts
• src/cli/specs/orchestration.ts
• src/cli/help.ts
• src/cli/specs/orchestration-worker-specs.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 2 remain after this review.

[pullfrog]

✅ No new issues found.

Reviewed changes

• Unpadded legacy help parsed: resolveFlagHelp now falls back to a single-space label pattern after the two-space split, so single-spaced legacy entries (--include-visual-layouts, --setup run|skip|inherit, --parent-worktree <selector>, --workspace-mode, --missed-run-grace-minutes) split into label + description instead of inflating the description column.
• Layout tests added: command-flag-help-layout.test.ts pins the split shapes, asserts no legacy label swallows prose across every command spec, and checks terminal list / worktree create render into a single description column.
• Help assertions tightened: index.test.ts, skills.test.ts, and orchestration-worker-cli.test.ts narrowed \s+ to [ \t]+ for the dynamically-aligned output.

This resolves the prior alignment concern — verified the split behavior against all fifteen single-spaced entries in legacy-command-flag-help.ts, and ran the touched suites (command-flag-help-layout, orchestration, index, skills, orchestration-worker-cli) green locally.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

This run re-reviewed the branch after it was rebuilt onto main (de8bffe240); no incremental diff could be computed because the previous revision was not in the shallow checkout, so I re-derived the delta against the prior pullfrog review (78494921cd) and read the full PR diff. The content is functionally the same as the version already approved, restructured and reworded.

• Layout padding moved into a row formatter: formatFlagHelpRows now computes the description column from described labels only, so a long bare label (--pairing-code/--environment) no longer pushes sibling descriptions right. This is a strict improvement over the inline padding it replaced.
• Gate and message specs extracted: gate-create/-resolve/-list moved to orchestration-gate-specs.ts and send/check/reply/inbox to orchestration-message-specs.ts; orchestration.ts spreads both arrays. Spec contents and order are preserved.
• Shared base map narrowed: orchestrationFlagHelp now carries only from, run, and dispatch-capability; global flags and --retry-request fall back to the shared table, with the ratchet refusing a spec-level duplicate.
• Orchestration descriptions and notes rewritten: flag and note wording across run/task/dispatch/worker/ask/reset specs was tightened, and identityFlagRoles was filled in where callers had been omitted.

Verified locally: command-flag-help-layout, orchestration-flag-help, skills, and orchestration-worker-cli suites pass (23 tests), and pnpm tc:cli exits 0. All prior pullfrog threads are already resolved, and no unresolved concern anchors to the new lines.

  ^{｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}