Update Claude and Codex orchestrator workflows

skills/smart-router-orchestrator/README.md

@@ -27,23 +27,47 @@ is off, without the Smart Router Orchestrator workflow.
 User instructions take precedence, and easy tasks remain in the root.
 
 Claude loads the bundled roles as `ug-smart-router:<role>` in its temporary
-routing plugin. Both agents delegate without model or reasoning-effort overrides;
-the routing hook selects the model.
+routing plugin. Claude omits model overrides; its bundled roles default to Sonnet.
+Codex requests Luna without a reasoning effort override. The routing hook can
+replace the requested model.
 Role instructions belong in each task prompt because routing may replace the
 requested Claude role or Codex model. Hook approval in the native `/hooks` UI
 is still required where the harness prompts for it.
 
+## Task ownership
+
+Both workflows keep easy work in the root and delegate only when a child can own
+a useful assignment. Split work only when the deliverables are independent or a
+concrete risk needs independent verification. The agent-specific instructions
+differ in how they divide discovery and the final answer:
+
+- **Claude:** keep a connected investigation in the root when briefing and review
+  would repeat the same work. A delegated owner handles planning, discovery,
+  execution, checks, and an integration-ready result.
+- **Codex:** choose who will synthesize the final answer before delegating. When
+  the root must deliver a delegated read-only investigation's answer, one owner
+  acquires the complete evidence and the root synthesizes it. Implementation
+  owners handle the complete edit, test, and fix loop.
+
+Children return decisive evidence with compact citations and explicit unresolved
+items. Keep ownership stable, batch substantive follow-ups, and use native completion
+notifications or waits instead of status polling. Amendments update the retained
+findings without repeating the full report or restarting the same investigation.
+
 ## Model selection
 
 Separate role-model preferences are not used by the UG workflow. Existing
 `.model-orchestrator.json` project preferences,
 `$XDG_CONFIG_HOME/model-orchestrator/config.json` user preferences, and generated
 custom Claude agents are left untouched. The bundled workflow uses the router's
-model selection and requires no preference setup, locking, or recovery.
+model selection and requires no preference setup or locking.
 
 ## Attribution
 
-Migrated from the Databricks `model-orchestrator` plugin 0.4.10 by Arnav Singhvi.
+Migrated from the Databricks `model-orchestrator` plugin by Arnav Singhvi. The base
+workflow came from version 0.4.21 (source commit
+`474b08e5809205d0aa9abbd059b82d5ab541ca92`); the Claude and Codex workflows now carry
+separate refinements. The UG skill version is 1.2.0.
 Originally adapted from
 [donvito/codex-astra-luna-orchestrator](https://github.com/donvito/codex-astra-luna-orchestrator/tree/21710352ec201f8634874d8298e0eca694e298a8)
 under Apache-2.0; see [LICENSE.upstream](LICENSE.upstream). UG changes add shared

skills/smart-router-orchestrator/SKILL.claude.md

@@ -1,16 +1,28 @@
 ---
 name: smart-router-orchestrator
-description: Smart Router Orchestrator coordinates substantive development with native subagents when ENABLE_SMART_ROUTER_ORCHESTRATOR=1 and Unity Gateway smart routing is enabled. Follow UG's activation context. Skip easy tasks and explicit no-subagent requests.
+
+description: >-
+  Delegate substantive coding, debugging, reviews, repository questions,
+  research, and verification to cheaper native subagents, in
+  parallel where the work splits. Use by default for development tasks when
+  UG activates orchestration; skip easy tasks the root can finish faster
+  itself and explicit no-subagent requests.
+
 model: inherit
 argument-hint: "[task]"
 metadata:
-  version: "1.1.0"
+  version: "1.2.0"
+
 ---
 
 # Smart Router Orchestrator
 
 ## Activation
 
+If this workflow is truncated and the full instructions are not already in
+context, read `SKILL.claude.md` from the skill directory shown in the activation
+context before proceeding.
+
 UG's prompt and compaction hooks activate this workflow only in an eligible
 smart-routing session launched with `ENABLE_SMART_ROUTER_ORCHESTRATOR=1` while routing is on.
 Follow the latest UG activation context and successful Smart Router toggles;
@@ -30,56 +42,110 @@ Use the `smart-router` skill only when the user asks to change routing.
 ## Workflow
 
 Follow user overrides. Keep the active root model and reasoning effort. The root
-owns planning, architecture, decomposition, integration, conflicts, and final
-verification; children execute bounded tasks. Smart routing selects child models;
-do not apply separate role-model preferences or reasoning-effort overrides.
+owns the delegation choice, cross-deliverable integration, conflicts, and
+acceptance; a delegated owner owns task-level planning, discovery, execution,
+checks, and the draft result.
 Never change providers, credentials, permissions, sandbox, unrelated settings,
 or concurrency limits.
-Report conflicts with existing mandatory orchestration rules or model policies.
-
-Before delegating, describe the task split in at most one short sentence, then
-launch ready work. Explain adapter details only
-when requested or needed to explain a failure or blocker. Keep later updates
-focused on findings, blockers, and results.
+Report conflicts with existing mandatory orchestration rules or model policies
+before using a different role map.
 
 ## Delegation gate
 
-Delegate to save the root's context and overall cost: cheaper children return
-concise results instead of raw tool output. Give them the bulk of broad searches,
-multi-area investigations, implementation, external research, and verification.
-Keep latency low by running independent children in parallel and easy work in the
-root.
-Users need not mention this skill or request agents.
-
-Keep a task in the root when briefing, waiting for, and integrating a child would
-take longer: a self-contained answer, mechanical edit, explanation or review of a
-small file already read, small single-scope change with obvious verification, or
-quick check. These save little cost and add little root context.
-An explicit request not to delegate takes precedence. If spawning is unavailable
-or policy prevents it, explain and continue locally within the user's instructions.
-Do not invent work to increase the agent count.
-
-Before substantive work, identify the root's share and independent pieces worth
-delegating. Launch ready pieces together and do the root's share while they run.
-Avoid serial chains when inputs exist. Do not add a reviewer or tester to a trivial
-fix or split a small change across workers. Size fan-out to the work; do not require
-a fixed pipeline.
-
-| Role | Scope |
-| --- | --- |
-| explorer | Read code and callers; map existing patterns/tests; no edits |
-| researcher | Verify external/API facts with primary sources; no edits |
-| worker | Implement one bounded change in explicitly owned files |
-| tester | Independently run checks and report failures; edit tests only if assigned |
-| reviewer | Review the actual diff for correctness, regressions, security, and missing tests; no edits |
+Start with the smallest plan that can deliver the caller's complete request.
+The skill being available does not itself require a child. Keep a connected
+investigation in the root when it already has the necessary context or when
+briefing plus review would repeat the same work. Delegate when a child can own
+an independently useful deliverable and replace enough root work to justify
+its execution and acceptance. Name that displaced work before spawning; broad
+scope, many files, or a cheaper model alone is insufficient. A natural zero-child
+outcome is valid. An explicit no-delegation request takes precedence.
+
+Choose ownership before solving the task. Do not split by numbered questions,
+files, or languages alone, and do not reserve a connected branch merely to keep
+the parent busy. Launch ready independent assignments together. Keep required
+independent checks, but do not add an automatic reviewer or manager stage.
+If spawning is unavailable or prohibited, continue locally within the caller's
+instructions. Reuse complete instructions already received; recover only missing
+or truncated portions instead of rereading them as a setup ritual.
+
+| Role | Scope | Claude default |
+| --- | --- | --- |
+| explorer | Read code and callers; map existing patterns/tests; no edits | Sonnet |
+| researcher | Verify external/API facts with primary sources; no edits | Sonnet |
+| worker | Implement one bounded change in explicitly owned files | Sonnet |
+| tester | Independently run checks and report failures; edit tests only if assigned | Sonnet |
+| reviewer | Review the actual diff for correctness, regressions, security, and missing tests; no edits | Sonnet |
 
 ## Assign and coordinate
 
-Give each independent lane an owner and outcome. Brief children on context,
-file scope, constraints, authority, acceptance criteria, and evidence. Include
-role constraints and research rules in each task prompt so routing preserves
-them. Use workers for implementation, one writer per file; the root must not
-duplicate their work.
+Brief each owner on the outcome, context, scope, constraints, authority,
+acceptance criteria, evidence, and delivery rule below. Pass established findings,
+decisions, relevant locations, and known validation commands so the child need
+not rediscover solved work. Include role constraints and these research rules so
+they survive routing.
+
+Tie each investigation step to an unresolved caller requirement. Start at the
+named entrypoints and locate their definitions or call sites. Batch independent
+lookups, inspect the relevant function and its connected call path, and expand
+only when that evidence leaves a specific relationship unresolved. A related
+name or directory is not by itself a reason to investigate it. Use filename-only
+search to locate files, then scoped matches and source windows; refine truncated
+results instead of dumping more broad output. Read a whole file when its flow
+requires it. Reuse established facts and check referenced evidence directly.
+Before another tool call, identify what it can settle that the retained evidence
+cannot. Once the requested claims are supported and required checks pass,
+produce the result. Requested inventories still require full coverage; retain
+unlocated targets, unresolved gaps, conditions, and qualifications explicitly.
+Use workers for implementation, one writer per file; the root must not duplicate
+their work.
+
+Assign common prerequisites to one discovery owner and share its concise cited
+findings with dependent owners. Merge assignments that would reconstruct the same
+investigation; preserve targeted checks rather than banning shared file reads.
+
+Keep the assigned research or edit/test/fix loop with its owner. Return the
+integration-ready answer or change, decisive evidence, validation results, and
+unresolved issues, not routine logs or search dumps unless needed for verification
+or requested. Cover every assigned caller requirement and material qualification
+without speculative scope expansion, arbitrary caps, or a duplicate checklist.
+Check coverage and important claims before returning. A terminal reply delivers
+the result, not a progress update; if blocked, state completed coverage, the
+dependency, and explicit partial status. Preserve the requested presentation and
+all required checks; do not make the parent reconstruct the answer from raw facts.
+
+Keep private inter-agent source references lossless but compact. When parent and
+child share an unambiguous workspace root, declare it once and cite relative paths
+with necessary line numbers; this changes reference encoding, not coverage. Preserve
+complete evidence, quotations, conclusions, unresolved limits, distinct evidence,
+and qualifications; use qualified roots when files span workspaces. Preserve
+required paths and citation formats in final output, use concise clickable anchored
+links where permitted, avoid repeating findings in a second source catalog, and
+follow higher-priority handoff formats.
+
+Keep each missing claim with its investigator until the correction returns or the
+root explicitly takes over; stop prior work when transferring ownership. Do not
+investigate the same unresolved claim concurrently under a correctness label.
+If its owner fails or is unavailable, continue from available evidence and record
+what remains. Preserve required independent checks.
+
+Let an active owner finish; send early messages only for a blocker, changed
+requirement, or time-sensitive dependency, not to request an interim answer for
+status. When only completion remains, use native completion notifications where
+supported, otherwise the host's documented wait within the next required update
+or actionable deadline. Use the longest supported wait fitting that bound and
+coordinate any wrapping execution limit with it.
+
+Use actual returned child IDs; do not fabricate IDs or start duplicate waits.
+Empty timeouts alone do not justify status queries or new investigation. Preserve
+independent work, acceptance checks, required updates, and immediate blocker
+handling; elapsed time alone does not prove a stall.
+
+Continue substantive corrections with the same available owner. Name the missing
+decision, evidence to check, and stop condition; batch independent questions.
+Follow-ups supplement the original assignment unless explicitly rescoped. Return
+only the amendment, or reconstruct a missing deliverable from existing evidence.
+Do not add confirmation-only rounds or repeat the entire report.
 
 Research needs sources and a deadline or request budget. Name tools exactly,
 with verified capability/auth status; children discover deferred tools in their
@@ -100,43 +166,35 @@ verification.
 ### Claude Code adapter
 
 Use native `Agent` (`Task` on older hosts) with `subagent_type="ug-smart-router:<role>"`.
-**Omit `model`**: the routing hook selects it. Include role scope and task contract
-in `prompt`, because routing may replace the requested agent definition. Run
-independent children in the background when supported. Use native result/wait
-tools and resume the same agent for follow-ups when available.
+**Omit `model`**: role frontmatter selects the configured alias or full ID. Include
+role scope and task contract in `prompt`; run independent children in the
+background when supported. Use native result/wait tools and resume the same
+agent for follow-ups when available.
 
 Omitted role tool lists inherit parent tools, including deferred MCP tools;
 parent permissions and hooks still apply. Read-only scope is instructional.
-Report missing bundled definitions as requiring reload/restart; do not substitute
-custom agents with saved model preferences. Managed forced-model policy takes
-precedence; report conflicts without clearing it.
-
-### Codex adapter
-
-Use native `spawn_agent` without `model` or `reasoning_effort` overrides. The routing
-hook selects the model. Use fresh task context (`fork_turns="none"` when exposed)
-so the hook can supply a model override; full-history forks require the inherited
-model. Send the needed context, role scope, and contract in `message`; use the
-host's native follow-up, message, wait, and close tools. Do not choose a custom
-role that pins a model or effort.
-
-Native spawning needs no role TOMLs or global `[agents]` defaults. Never simulate
-delegation with nested CLIs. Read-only role scope is instructional unless the host
-enforces per-child restrictions.
-
-If spawning fails, report the error and continue authorized work in the root.
-Do not retry with model aliases or changed permissions, credentials, or limits.
-Once a child ID is returned, collect that child's result rather than spawning a
-replacement for the same assignment.
+Configured agents have distinct names. Report missing definitions as requiring
+reload/restart; do not substitute built-ins. Per-call model overrides are alias-only
+on the tested host; custom IDs belong in definitions. Managed forced-model policy
+takes precedence; report conflicts without clearing it.
 
 ## Integrate and verify
 
-Read child evidence, inspect worker diffs, and spot-check cited paths without
-redoing their scope. Run the smallest independent checks of the requested outcome.
-Resolve conflicts and findings before handoff. Account for every required child;
-a launch or success-shaped summary alone is not completion. For empty or unrelated
-results, or an already-supplied task request, clarify once with the same child.
-Verify its evidence; if still unusable, report the unmet assignment without
+Parent acceptance is the default review. Add a reviewer only for a distinct risk,
+an explicit request, or a required independent check, not as an automatic stage.
+Inspect actual changes and verify important claims against cited evidence and the
+caller contract; a completion message alone is not proof. Reopen a named gap,
+contradiction, changed input, or required check from the smallest useful source
+window instead of repeating broad discovery. Preserve substantive correctness
+checks, conditions, exceptions, limitations, citations, and requested presentation.
+
+Integrate the owner's draft and narrow amendments without restarting the
+investigation or regenerating the full narrative. Deliver the complete answer;
+if blocked, report completed coverage and explicit partial status. Resolve
+conflicts and findings before handoff. Account for every required
+child; a launch or success-shaped summary alone is not completion. For empty or
+unrelated results, or an already-supplied task request, clarify once with the same
+child. Verify its evidence; if still unusable, report the unmet assignment without
 respawning. Report unavailable models, tools, and substitutions.
 
 Finish with the concrete result, verification actually performed, and material