From 06fbe60aa3681534c5f05a0c25b2f7dd364230c1 Mon Sep 17 00:00:00 2001 From: Josh Joseph <66833672+JJ27@users.noreply.github.com> Date: Fri, 9 Oct 2026 00:23:47 +0000 Subject: [PATCH 1/7] Port v0.4.21 orchestration workflow to UG --- skills/smart-router-orchestrator/README.md | 17 +- .../smart-router-orchestrator/SKILL.claude.md | 164 ++++++++++++++++-- .../smart-router-orchestrator/SKILL.codex.md | 164 ++++++++++++++++-- 3 files changed, 310 insertions(+), 35 deletions(-) diff --git a/skills/smart-router-orchestrator/README.md b/skills/smart-router-orchestrator/README.md index 8da51d8ee..2e3bb4669 100644 --- a/skills/smart-router-orchestrator/README.md +++ b/skills/smart-router-orchestrator/README.md @@ -33,6 +33,19 @@ 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 + +Give each cohesive task one owner for planning, discovery, implementation, checks, +and an integration-ready result. Split work only when the deliverables are +independent or a concrete risk needs independent verification. The root integrates +the evidence and checks specific acceptance gaps instead of repeating the child's +investigation or reserving parallel work for itself. + +Children return consolidated results 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. Preserve the full report until +the parent confirms receipt; later amendments retain its other findings and limits. + ## Model selection Separate role-model preferences are not used by the UG workflow. Existing @@ -43,7 +56,9 @@ model selection and requires no preference setup, locking, or recovery. ## Attribution -Migrated from the Databricks `model-orchestrator` plugin 0.4.10 by Arnav Singhvi. +Migrated from the Databricks `model-orchestrator` plugin by Arnav Singhvi, with +workflow updates through version 0.4.21 (source commit +`474b08e5809205d0aa9abbd059b82d5ab541ca92`). 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 diff --git a/skills/smart-router-orchestrator/SKILL.claude.md b/skills/smart-router-orchestrator/SKILL.claude.md index 21787f23b..ccd16473e 100644 --- a/skills/smart-router-orchestrator/SKILL.claude.md +++ b/skills/smart-router-orchestrator/SKILL.claude.md @@ -4,7 +4,7 @@ description: Smart Router Orchestrator coordinates substantive development with model: inherit argument-hint: "[task]" metadata: - version: "1.1.0" + version: "1.2.0" --- # Smart Router Orchestrator @@ -30,8 +30,9 @@ 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; +owns the delegation choice, cross-deliverable integration, conflicts, and +acceptance; a delegated owner owns task-level planning, discovery, execution, +checks, and the draft result. Smart routing selects child models; do not apply separate role-model preferences or reasoning-effort overrides. Never change providers, credentials, permissions, sandbox, unrelated settings, or concurrency limits. @@ -59,11 +60,27 @@ 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. +Before substantive work, identify the complete root work the child would replace. +For a cohesive task, give one owner the original request, acceptance criteria, +constraints, and authority to discover, check, and draft the result. Keep a +connected reasoning path with that owner even when it crosses directories or +layers; do not pre-solve it in the parent. Split only when each result is useful +and verifiable without first resolving the other child's findings, or a concrete +risk requires independent verification. Numbered questions, files, and languages +alone do not make independent deliverables. +Do not reserve broad discovery for the root merely to give it work while waiting. +A delegated owner replaces the broad discovery, execution, and checks assigned to +it. While the child owns that scope, root work is limited to cross-deliverable +integration and targeted acceptance-gap checks; do not create an automatic +parallel root scope. After a complete report arrives, consume it as the owner's +evidence and do not restart broad discovery or reread the same area; read or +execute only what is needed to check a concrete acceptance gap or contradiction. +When no such independent check is ready, finalize or use a native wait for other +assigned work; do not invent root work to fill the interval. Use the lightest +sufficient delegation and allow a natural zero-child outcome when the root can +cover the task. 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. +fix or require a fixed pipeline; size fan-out to the work. | Role | Scope | | --- | --- | @@ -75,11 +92,115 @@ a fixed pipeline. ## 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. Include role constraints +and these research rules so they survive routing. Start from the user's named +symbols, entrypoints, files, and result surfaces; locate each and trace the +relationships needed for the requested conclusion before expanding into adjacent +areas. Keep any unlocated target explicit rather than substituting a related +surface. Use filenames and counts to find unknown locations, then scoped symbols +and line windows; refine truncated queries, reuse evidence, and read whole files +when the flow requires it. Requested inventories still require full coverage. +Use workers for implementation, one writer per file; the root must not duplicate +their work. + +Each child assignment includes a return contract: own the bounded assignment through +its named checks, map every original acceptance item to an answer with the minimal +cited evidence, and mark unresolved items. For a cohesive delegation covering the +whole caller request, return an integration-ready draft that satisfies the original +caller contract, including its requested presentation, with concise separate notes +for unresolved issues or evidence gaps. For a partial delegation, return only the +assigned part in the presentation needed for the parent to integrate it, with +concise unresolved notes. Do not make the parent reconstruct the requested draft +from raw findings. Return one consolidated, decision-relevant result; do not +require duplicate full reports or mandatory verbosity. Keep broad searches and +full-source reading in the owning child context; the parent requests scoped +excerpts needed for integration or verification without hiding required proof. +Do not request an interim answer solely for a progress update; report the known +state while the child finishes and wait for its consolidated result. Do not return +raw search dumps unless they expose a blocker or plan-changing evidence. Preserve +every requested deliverable and verification step. + +Keep private inter-agent source references lossless but compact. When parent and +child share an unambiguous workspace root, declare that root once in the handoff +and cite relative paths with the necessary line numbers instead of repeating the +full root in every citation. Preserve complete evidence, quotations, conclusions, +and unresolved limits; this changes reference encoding, not coverage. Use qualified +roots when files span workspaces or a relative reference would be ambiguous. +For final output, preserve required paths and citation format. Where that format +permits, introduce one clickable file link for a local group or table of findings +from that file, retaining each finding's precise line numbers. Keep separate +anchored links when required or needed to avoid ambiguity. Use concise labels; +avoid repeating the same findings in an additional source catalog. Shorten path +repetition and exposition while preserving every requested inventory, distinct +piece of evidence, and qualification. Follow higher-priority handoff formats too. + +Assign one owner to each independent investigation question, including read-only +work. While that child owns its scope, the parent does not run a parallel broad +investigation there; parent work stays independent, integrative, or targeted to +correctness. The parent accepts sufficient cited evidence and reopens only an +explicit missing claim, contradiction, or required check. Transfer a missing +question once to one owner rather than repeatedly reopening completed scope. +Keep ownership stable while a report is pending. For a necessary transfer, reuse +evidence already delivered or accessible, identify the remaining gap, and stop +the prior owner's work on that question if it is still active. Request missing +handoff evidence only when needed and the owner can respond. If the owner has +failed or is unavailable, continue authorized work from available evidence and +record what is missing instead of waiting for a handoff; the recovery rules below +still apply. Reuse completed discovery. Narrow independent checks of a concrete +correctness or integration risk remain allowed. + +Batch independent coordination. Let an active owner finish before sending +non-blocking findings or requests for progress or extra checks. Send earlier +messages only for a concrete blocker, changed requirement, or time-sensitive +dependency. Elapsed time alone is not evidence of a stall. Give required user +updates from the last known state without asking the child for a status report. + +When only child completion remains, use automatic native completion notifications +if the host supports them. Otherwise use one native wait for the outstanding +children, with the longest supported duration allowed by the next user update or +actionable deadline. A wrapping execution call must cover that duration within +its own supported limits. For a host exposing the first-line `// @exec` pragma +and `tools.multi_agent_v1__wait_agent`, when 45 seconds fits both limits and the +next required update, the matching call is: + +```js +// @exec: {"yield_time_ms": 45000} +text(await tools.multi_agent_v1__wait_agent({ + targets: [""], timeout_ms: 45000 +})); +``` + +Use the actual returned child ID and the host's available wait tool. Shorten both +durations together if a bound is sooner. After an early outer yield, resume the +exact returned `cell_id` under the same bounds; do not start another inner wait, +fabricate IDs, or alter output limits to simulate progress. Do not insert status +queries or new investigation between empty wait results. Preserve independent +work, targeted acceptance checks, required updates, and immediate blocker handling. + +Preserve the owed deliverable across follow-ups. Do not send scope reminders +that merely restate an active assignment without new evidence or a changed +requirement. Substantive follow-ups remain owed; acknowledgment or progress is not the result. +Until the parent explicitly confirms receipt of the full report or access to its +artifact, put that report, with later requests folded in, in the final response +itself. An earlier child final is not proof of delivery. Reuse existing evidence. +The parent includes that confirmation in an existing substantive follow-up when +requesting an amendment; do not add a confirmation-only round trip. After that +confirmation, the child returns only the requested amendment; the parent integrates +it with the retained report, preserving every acceptance item. Require neither a +new file nor repetition of a report the parent has confirmed receiving or accessing. +Explicit cancellation, replacement of the assignment, or a caller request for +acknowledgment alone governs the remaining deliverable. + +Every follow-up names the user-required decision that remains unresolved, the +question and evidence to check, and the stop condition. A follow-up supplements +the original assignment unless explicitly rescoping it; batch independent +unresolved questions into one message per child, and transfer each missing question +once to a single owner. Accept a complete report without a status request or extra +confirmation; use the native wait when only completion is outstanding. Preserve +targeted correctness verification and every requested deliverable. Finalize once +the requested coverage and checks are complete; do not add unrequested +investigation. Research needs sources and a deadline or request budget. Name tools exactly, with verified capability/auth status; children discover deferred tools in their @@ -131,12 +252,21 @@ replacement for the same assignment. ## Integrate and verify +Build the final answer from the draft and amendments. Reconcile every original +acceptance item against the evidence before reopening sources. Preserve conditions, +exceptions, and limitations that change what the caller can conclude or do; make +these distinctions explicit rather than leaving them implicit in an excerpt or +table label. A scoped amendment updates that part of the retained report without +discarding its other findings. + 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 +redoing a broad child-owned scope. Accept sufficient cited evidence and run only +the targeted correctness or risk checks needed by the requested outcome. Keep any +additional check independent of the child work or tied to a concrete integration +risk. 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 diff --git a/skills/smart-router-orchestrator/SKILL.codex.md b/skills/smart-router-orchestrator/SKILL.codex.md index 21787f23b..ccd16473e 100644 --- a/skills/smart-router-orchestrator/SKILL.codex.md +++ b/skills/smart-router-orchestrator/SKILL.codex.md @@ -4,7 +4,7 @@ description: Smart Router Orchestrator coordinates substantive development with model: inherit argument-hint: "[task]" metadata: - version: "1.1.0" + version: "1.2.0" --- # Smart Router Orchestrator @@ -30,8 +30,9 @@ 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; +owns the delegation choice, cross-deliverable integration, conflicts, and +acceptance; a delegated owner owns task-level planning, discovery, execution, +checks, and the draft result. Smart routing selects child models; do not apply separate role-model preferences or reasoning-effort overrides. Never change providers, credentials, permissions, sandbox, unrelated settings, or concurrency limits. @@ -59,11 +60,27 @@ 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. +Before substantive work, identify the complete root work the child would replace. +For a cohesive task, give one owner the original request, acceptance criteria, +constraints, and authority to discover, check, and draft the result. Keep a +connected reasoning path with that owner even when it crosses directories or +layers; do not pre-solve it in the parent. Split only when each result is useful +and verifiable without first resolving the other child's findings, or a concrete +risk requires independent verification. Numbered questions, files, and languages +alone do not make independent deliverables. +Do not reserve broad discovery for the root merely to give it work while waiting. +A delegated owner replaces the broad discovery, execution, and checks assigned to +it. While the child owns that scope, root work is limited to cross-deliverable +integration and targeted acceptance-gap checks; do not create an automatic +parallel root scope. After a complete report arrives, consume it as the owner's +evidence and do not restart broad discovery or reread the same area; read or +execute only what is needed to check a concrete acceptance gap or contradiction. +When no such independent check is ready, finalize or use a native wait for other +assigned work; do not invent root work to fill the interval. Use the lightest +sufficient delegation and allow a natural zero-child outcome when the root can +cover the task. 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. +fix or require a fixed pipeline; size fan-out to the work. | Role | Scope | | --- | --- | @@ -75,11 +92,115 @@ a fixed pipeline. ## 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. Include role constraints +and these research rules so they survive routing. Start from the user's named +symbols, entrypoints, files, and result surfaces; locate each and trace the +relationships needed for the requested conclusion before expanding into adjacent +areas. Keep any unlocated target explicit rather than substituting a related +surface. Use filenames and counts to find unknown locations, then scoped symbols +and line windows; refine truncated queries, reuse evidence, and read whole files +when the flow requires it. Requested inventories still require full coverage. +Use workers for implementation, one writer per file; the root must not duplicate +their work. + +Each child assignment includes a return contract: own the bounded assignment through +its named checks, map every original acceptance item to an answer with the minimal +cited evidence, and mark unresolved items. For a cohesive delegation covering the +whole caller request, return an integration-ready draft that satisfies the original +caller contract, including its requested presentation, with concise separate notes +for unresolved issues or evidence gaps. For a partial delegation, return only the +assigned part in the presentation needed for the parent to integrate it, with +concise unresolved notes. Do not make the parent reconstruct the requested draft +from raw findings. Return one consolidated, decision-relevant result; do not +require duplicate full reports or mandatory verbosity. Keep broad searches and +full-source reading in the owning child context; the parent requests scoped +excerpts needed for integration or verification without hiding required proof. +Do not request an interim answer solely for a progress update; report the known +state while the child finishes and wait for its consolidated result. Do not return +raw search dumps unless they expose a blocker or plan-changing evidence. Preserve +every requested deliverable and verification step. + +Keep private inter-agent source references lossless but compact. When parent and +child share an unambiguous workspace root, declare that root once in the handoff +and cite relative paths with the necessary line numbers instead of repeating the +full root in every citation. Preserve complete evidence, quotations, conclusions, +and unresolved limits; this changes reference encoding, not coverage. Use qualified +roots when files span workspaces or a relative reference would be ambiguous. +For final output, preserve required paths and citation format. Where that format +permits, introduce one clickable file link for a local group or table of findings +from that file, retaining each finding's precise line numbers. Keep separate +anchored links when required or needed to avoid ambiguity. Use concise labels; +avoid repeating the same findings in an additional source catalog. Shorten path +repetition and exposition while preserving every requested inventory, distinct +piece of evidence, and qualification. Follow higher-priority handoff formats too. + +Assign one owner to each independent investigation question, including read-only +work. While that child owns its scope, the parent does not run a parallel broad +investigation there; parent work stays independent, integrative, or targeted to +correctness. The parent accepts sufficient cited evidence and reopens only an +explicit missing claim, contradiction, or required check. Transfer a missing +question once to one owner rather than repeatedly reopening completed scope. +Keep ownership stable while a report is pending. For a necessary transfer, reuse +evidence already delivered or accessible, identify the remaining gap, and stop +the prior owner's work on that question if it is still active. Request missing +handoff evidence only when needed and the owner can respond. If the owner has +failed or is unavailable, continue authorized work from available evidence and +record what is missing instead of waiting for a handoff; the recovery rules below +still apply. Reuse completed discovery. Narrow independent checks of a concrete +correctness or integration risk remain allowed. + +Batch independent coordination. Let an active owner finish before sending +non-blocking findings or requests for progress or extra checks. Send earlier +messages only for a concrete blocker, changed requirement, or time-sensitive +dependency. Elapsed time alone is not evidence of a stall. Give required user +updates from the last known state without asking the child for a status report. + +When only child completion remains, use automatic native completion notifications +if the host supports them. Otherwise use one native wait for the outstanding +children, with the longest supported duration allowed by the next user update or +actionable deadline. A wrapping execution call must cover that duration within +its own supported limits. For a host exposing the first-line `// @exec` pragma +and `tools.multi_agent_v1__wait_agent`, when 45 seconds fits both limits and the +next required update, the matching call is: + +```js +// @exec: {"yield_time_ms": 45000} +text(await tools.multi_agent_v1__wait_agent({ + targets: [""], timeout_ms: 45000 +})); +``` + +Use the actual returned child ID and the host's available wait tool. Shorten both +durations together if a bound is sooner. After an early outer yield, resume the +exact returned `cell_id` under the same bounds; do not start another inner wait, +fabricate IDs, or alter output limits to simulate progress. Do not insert status +queries or new investigation between empty wait results. Preserve independent +work, targeted acceptance checks, required updates, and immediate blocker handling. + +Preserve the owed deliverable across follow-ups. Do not send scope reminders +that merely restate an active assignment without new evidence or a changed +requirement. Substantive follow-ups remain owed; acknowledgment or progress is not the result. +Until the parent explicitly confirms receipt of the full report or access to its +artifact, put that report, with later requests folded in, in the final response +itself. An earlier child final is not proof of delivery. Reuse existing evidence. +The parent includes that confirmation in an existing substantive follow-up when +requesting an amendment; do not add a confirmation-only round trip. After that +confirmation, the child returns only the requested amendment; the parent integrates +it with the retained report, preserving every acceptance item. Require neither a +new file nor repetition of a report the parent has confirmed receiving or accessing. +Explicit cancellation, replacement of the assignment, or a caller request for +acknowledgment alone governs the remaining deliverable. + +Every follow-up names the user-required decision that remains unresolved, the +question and evidence to check, and the stop condition. A follow-up supplements +the original assignment unless explicitly rescoping it; batch independent +unresolved questions into one message per child, and transfer each missing question +once to a single owner. Accept a complete report without a status request or extra +confirmation; use the native wait when only completion is outstanding. Preserve +targeted correctness verification and every requested deliverable. Finalize once +the requested coverage and checks are complete; do not add unrequested +investigation. Research needs sources and a deadline or request budget. Name tools exactly, with verified capability/auth status; children discover deferred tools in their @@ -131,12 +252,21 @@ replacement for the same assignment. ## Integrate and verify +Build the final answer from the draft and amendments. Reconcile every original +acceptance item against the evidence before reopening sources. Preserve conditions, +exceptions, and limitations that change what the caller can conclude or do; make +these distinctions explicit rather than leaving them implicit in an excerpt or +table label. A scoped amendment updates that part of the retained report without +discarding its other findings. + 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 +redoing a broad child-owned scope. Accept sufficient cited evidence and run only +the targeted correctness or risk checks needed by the requested outcome. Keep any +additional check independent of the child work or tied to a concrete integration +risk. 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 From 884c9ae6439e8ffb580c69082604f32b56d507a1 Mon Sep 17 00:00:00 2001 From: Josh Joseph Date: Fri, 9 Oct 2026 18:57:15 +0000 Subject: [PATCH 2/7] Update Claude and Codex orchestrator workflows --- skills/smart-router-orchestrator/README.md | 30 +- .../smart-router-orchestrator/SKILL.claude.md | 263 +++++---------- .../smart-router-orchestrator/SKILL.codex.md | 318 ++++++++---------- 3 files changed, 243 insertions(+), 368 deletions(-) diff --git a/skills/smart-router-orchestrator/README.md b/skills/smart-router-orchestrator/README.md index 2e3bb4669..2750a935c 100644 --- a/skills/smart-router-orchestrator/README.md +++ b/skills/smart-router-orchestrator/README.md @@ -35,16 +35,23 @@ is still required where the harness prompts for it. ## Task ownership -Give each cohesive task one owner for planning, discovery, implementation, checks, -and an integration-ready result. Split work only when the deliverables are -independent or a concrete risk needs independent verification. The root integrates -the evidence and checks specific acceptance gaps instead of repeating the child's -investigation or reserving parallel work for itself. +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: -Children return consolidated results with compact citations and explicit unresolved +- **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. Preserve the full report until -the parent confirms receipt; later amendments retain its other findings and limits. +notifications or waits instead of status polling. Amendments update the retained +findings without repeating the full report or restarting the same investigation. ## Model selection @@ -56,9 +63,10 @@ model selection and requires no preference setup, locking, or recovery. ## Attribution -Migrated from the Databricks `model-orchestrator` plugin by Arnav Singhvi, with -workflow updates through version 0.4.21 (source commit -`474b08e5809205d0aa9abbd059b82d5ab541ca92`). The UG skill version is 1.2.0. +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 diff --git a/skills/smart-router-orchestrator/SKILL.claude.md b/skills/smart-router-orchestrator/SKILL.claude.md index ccd16473e..ca51b3c5e 100644 --- a/skills/smart-router-orchestrator/SKILL.claude.md +++ b/skills/smart-router-orchestrator/SKILL.claude.md @@ -38,49 +38,24 @@ 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. - ## 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 complete root work the child would replace. -For a cohesive task, give one owner the original request, acceptance criteria, -constraints, and authority to discover, check, and draft the result. Keep a -connected reasoning path with that owner even when it crosses directories or -layers; do not pre-solve it in the parent. Split only when each result is useful -and verifiable without first resolving the other child's findings, or a concrete -risk requires independent verification. Numbered questions, files, and languages -alone do not make independent deliverables. -Do not reserve broad discovery for the root merely to give it work while waiting. -A delegated owner replaces the broad discovery, execution, and checks assigned to -it. While the child owns that scope, root work is limited to cross-deliverable -integration and targeted acceptance-gap checks; do not create an automatic -parallel root scope. After a complete report arrives, consume it as the owner's -evidence and do not restart broad discovery or reread the same area; read or -execute only what is needed to check a concrete acceptance gap or contradiction. -When no such independent check is ready, finalize or use a native wait for other -assigned work; do not invent root work to fill the interval. Use the lightest -sufficient delegation and allow a natural zero-child outcome when the root can -cover the task. -Avoid serial chains when inputs exist. Do not add a reviewer or tester to a trivial -fix or require a fixed pipeline; size fan-out to the work. +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 | | --- | --- | @@ -93,114 +68,72 @@ fix or require a fixed pipeline; size fan-out to the work. ## Assign and coordinate Brief each owner on the outcome, context, scope, constraints, authority, -acceptance criteria, evidence, and delivery rule below. Include role constraints -and these research rules so they survive routing. Start from the user's named -symbols, entrypoints, files, and result surfaces; locate each and trace the -relationships needed for the requested conclusion before expanding into adjacent -areas. Keep any unlocated target explicit rather than substituting a related -surface. Use filenames and counts to find unknown locations, then scoped symbols -and line windows; refine truncated queries, reuse evidence, and read whole files -when the flow requires it. Requested inventories still require full coverage. +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. -Each child assignment includes a return contract: own the bounded assignment through -its named checks, map every original acceptance item to an answer with the minimal -cited evidence, and mark unresolved items. For a cohesive delegation covering the -whole caller request, return an integration-ready draft that satisfies the original -caller contract, including its requested presentation, with concise separate notes -for unresolved issues or evidence gaps. For a partial delegation, return only the -assigned part in the presentation needed for the parent to integrate it, with -concise unresolved notes. Do not make the parent reconstruct the requested draft -from raw findings. Return one consolidated, decision-relevant result; do not -require duplicate full reports or mandatory verbosity. Keep broad searches and -full-source reading in the owning child context; the parent requests scoped -excerpts needed for integration or verification without hiding required proof. -Do not request an interim answer solely for a progress update; report the known -state while the child finishes and wait for its consolidated result. Do not return -raw search dumps unless they expose a blocker or plan-changing evidence. Preserve -every requested deliverable and verification step. - -Keep private inter-agent source references lossless but compact. When parent and -child share an unambiguous workspace root, declare that root once in the handoff -and cite relative paths with the necessary line numbers instead of repeating the -full root in every citation. Preserve complete evidence, quotations, conclusions, -and unresolved limits; this changes reference encoding, not coverage. Use qualified -roots when files span workspaces or a relative reference would be ambiguous. -For final output, preserve required paths and citation format. Where that format -permits, introduce one clickable file link for a local group or table of findings -from that file, retaining each finding's precise line numbers. Keep separate -anchored links when required or needed to avoid ambiguity. Use concise labels; -avoid repeating the same findings in an additional source catalog. Shorten path -repetition and exposition while preserving every requested inventory, distinct -piece of evidence, and qualification. Follow higher-priority handoff formats too. - -Assign one owner to each independent investigation question, including read-only -work. While that child owns its scope, the parent does not run a parallel broad -investigation there; parent work stays independent, integrative, or targeted to -correctness. The parent accepts sufficient cited evidence and reopens only an -explicit missing claim, contradiction, or required check. Transfer a missing -question once to one owner rather than repeatedly reopening completed scope. -Keep ownership stable while a report is pending. For a necessary transfer, reuse -evidence already delivered or accessible, identify the remaining gap, and stop -the prior owner's work on that question if it is still active. Request missing -handoff evidence only when needed and the owner can respond. If the owner has -failed or is unavailable, continue authorized work from available evidence and -record what is missing instead of waiting for a handoff; the recovery rules below -still apply. Reuse completed discovery. Narrow independent checks of a concrete -correctness or integration risk remain allowed. - -Batch independent coordination. Let an active owner finish before sending -non-blocking findings or requests for progress or extra checks. Send earlier -messages only for a concrete blocker, changed requirement, or time-sensitive -dependency. Elapsed time alone is not evidence of a stall. Give required user -updates from the last known state without asking the child for a status report. - -When only child completion remains, use automatic native completion notifications -if the host supports them. Otherwise use one native wait for the outstanding -children, with the longest supported duration allowed by the next user update or -actionable deadline. A wrapping execution call must cover that duration within -its own supported limits. For a host exposing the first-line `// @exec` pragma -and `tools.multi_agent_v1__wait_agent`, when 45 seconds fits both limits and the -next required update, the matching call is: +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. -```js -// @exec: {"yield_time_ms": 45000} -text(await tools.multi_agent_v1__wait_agent({ - targets: [""], timeout_ms: 45000 -})); -``` +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. -Use the actual returned child ID and the host's available wait tool. Shorten both -durations together if a bound is sooner. After an early outer yield, resume the -exact returned `cell_id` under the same bounds; do not start another inner wait, -fabricate IDs, or alter output limits to simulate progress. Do not insert status -queries or new investigation between empty wait results. Preserve independent -work, targeted acceptance checks, required updates, and immediate blocker handling. - -Preserve the owed deliverable across follow-ups. Do not send scope reminders -that merely restate an active assignment without new evidence or a changed -requirement. Substantive follow-ups remain owed; acknowledgment or progress is not the result. -Until the parent explicitly confirms receipt of the full report or access to its -artifact, put that report, with later requests folded in, in the final response -itself. An earlier child final is not proof of delivery. Reuse existing evidence. -The parent includes that confirmation in an existing substantive follow-up when -requesting an amendment; do not add a confirmation-only round trip. After that -confirmation, the child returns only the requested amendment; the parent integrates -it with the retained report, preserving every acceptance item. Require neither a -new file nor repetition of a report the parent has confirmed receiving or accessing. -Explicit cancellation, replacement of the assignment, or a caller request for -acknowledgment alone governs the remaining deliverable. - -Every follow-up names the user-required decision that remains unresolved, the -question and evidence to check, and the stop condition. A follow-up supplements -the original assignment unless explicitly rescoping it; batch independent -unresolved questions into one message per child, and transfer each missing question -once to a single owner. Accept a complete report without a status request or extra -confirmation; use the native wait when only completion is outstanding. Preserve -targeted correctness verification and every requested deliverable. Finalize once -the requested coverage and checks are complete; do not add unrequested -investigation. +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 @@ -232,38 +165,20 @@ Report missing bundled definitions as requiring reload/restart; do not substitut 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. - ## Integrate and verify -Build the final answer from the draft and amendments. Reconcile every original -acceptance item against the evidence before reopening sources. Preserve conditions, -exceptions, and limitations that change what the caller can conclude or do; make -these distinctions explicit rather than leaving them implicit in an excerpt or -table label. A scoped amendment updates that part of the retained report without -discarding its other findings. - -Read child evidence, inspect worker diffs, and spot-check cited paths without -redoing a broad child-owned scope. Accept sufficient cited evidence and run only -the targeted correctness or risk checks needed by the requested outcome. Keep any -additional check independent of the child work or tied to a concrete integration -risk. Resolve conflicts and findings before handoff. Account for every required +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 diff --git a/skills/smart-router-orchestrator/SKILL.codex.md b/skills/smart-router-orchestrator/SKILL.codex.md index ccd16473e..94f799a73 100644 --- a/skills/smart-router-orchestrator/SKILL.codex.md +++ b/skills/smart-router-orchestrator/SKILL.codex.md @@ -31,56 +31,35 @@ Use the `smart-router` skill only when the user asks to change routing. Follow user overrides. Keep the active root model and reasoning effort. The root owns the delegation choice, cross-deliverable integration, conflicts, and -acceptance; a delegated owner owns task-level planning, discovery, execution, -checks, and the draft result. Smart routing selects child models; +acceptance; a delegated owner owns its complete discovery or implementation +assignment and its checks. Choose who synthesizes the final answer before +assigning the work. Smart routing selects child models; do not apply separate role-model preferences or reasoning-effort overrides. 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. - ## 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 complete root work the child would replace. -For a cohesive task, give one owner the original request, acceptance criteria, -constraints, and authority to discover, check, and draft the result. Keep a -connected reasoning path with that owner even when it crosses directories or -layers; do not pre-solve it in the parent. Split only when each result is useful -and verifiable without first resolving the other child's findings, or a concrete -risk requires independent verification. Numbered questions, files, and languages -alone do not make independent deliverables. -Do not reserve broad discovery for the root merely to give it work while waiting. -A delegated owner replaces the broad discovery, execution, and checks assigned to -it. While the child owns that scope, root work is limited to cross-deliverable -integration and targeted acceptance-gap checks; do not create an automatic -parallel root scope. After a complete report arrives, consume it as the owner's -evidence and do not restart broad discovery or reread the same area; read or -execute only what is needed to check a concrete acceptance gap or contradiction. -When no such independent check is ready, finalize or use a native wait for other -assigned work; do not invent root work to fill the interval. Use the lightest -sufficient delegation and allow a natural zero-child outcome when the root can -cover the task. -Avoid serial chains when inputs exist. Do not add a reviewer or tester to a trivial -fix or require a fixed pipeline; size fan-out to the work. +Choose direct execution or a delegated owner for each complete deliverable. +Direct execution fits work the root can finish from available evidence and a +small amount of checking. Knowing the task's vocabulary or file locations does +not mean its investigation is already done. For substantial discovery, consider +one owner for the complete investigation and answer, including its dependent +questions. Compare that owner's work plus acceptance with doing it in the root. +A natural zero-child outcome remains valid; an explicit no-delegation request +takes precedence. + +For a connected read-only investigation whose final answer the root must deliver, +assign the complete evidence acquisition to one owner and keep the final synthesis +in the root. The owner traces the relevant conditions and dependencies and returns +the decisive evidence for every caller requirement; it need not write a second +polished answer. The root does not retain a parallel source investigation. For +implementation, transfer the complete edit, test, and fix loop with the change. +Split only assignments that can each be accepted independently, or a required +independent check. Launch ready independent assignments together. +If spawning is unavailable or prohibited, continue within the caller's instructions. +Reuse complete instructions already received and recover only missing portions. | Role | Scope | | --- | --- | @@ -92,115 +71,88 @@ fix or require a fixed pipeline; size fan-out to the work. ## Assign and coordinate -Brief each owner on the outcome, context, scope, constraints, authority, -acceptance criteria, evidence, and delivery rule below. Include role constraints -and these research rules so they survive routing. Start from the user's named -symbols, entrypoints, files, and result surfaces; locate each and trace the -relationships needed for the requested conclusion before expanding into adjacent -areas. Keep any unlocated target explicit rather than substituting a related -surface. Use filenames and counts to find unknown locations, then scoped symbols -and line windows; refine truncated queries, reuse evidence, and read whole files -when the flow requires it. Requested inventories still require full coverage. -Use workers for implementation, one writer per file; the root must not duplicate -their work. - -Each child assignment includes a return contract: own the bounded assignment through -its named checks, map every original acceptance item to an answer with the minimal -cited evidence, and mark unresolved items. For a cohesive delegation covering the -whole caller request, return an integration-ready draft that satisfies the original -caller contract, including its requested presentation, with concise separate notes -for unresolved issues or evidence gaps. For a partial delegation, return only the -assigned part in the presentation needed for the parent to integrate it, with -concise unresolved notes. Do not make the parent reconstruct the requested draft -from raw findings. Return one consolidated, decision-relevant result; do not -require duplicate full reports or mandatory verbosity. Keep broad searches and -full-source reading in the owning child context; the parent requests scoped -excerpts needed for integration or verification without hiding required proof. -Do not request an interim answer solely for a progress update; report the known -state while the child finishes and wait for its consolidated result. Do not return -raw search dumps unless they expose a blocker or plan-changing evidence. Preserve -every requested deliverable and verification step. +Brief each owner on the caller's deliverables, context, authority, role constraints, +acceptance criteria, and established evidence. Preserve the caller's scope without +adding optional inventories, background surveys, or speculative requirements. +Include the following execution contract in the actual child assignment; do not +assume the child inherits this skill. The root uses the same contract when working +directly. + +> Start from supplied evidence and entrypoints. Before each tool call, identify +> what it can settle that retained evidence cannot. Obtain the smallest sufficient +> evidence: locate with file names or symbols, +> then inspect the relevant definition and connected conditions or callers. +> Read the complete function or configuration block needed to support the claim; +> read a whole file when its flow is required. Batch independent queries and +> combine overlapping windows. Reuse established facts and citation spans. +> Preserve explicit searches, exhaustive coverage, required checks, and material +> qualifications. Continue for an uncovered requirement, contradiction, or +> required validation; related names alone do not expand the assignment. +> Return the complete assigned evidence or change, with decisive cited excerpts, +> their relevant conditions, validation evidence, and explicit unresolved items. +> For an evidence assignment, place each finding beside its supporting excerpt +> and necessary interpretation. Cover every caller requirement without a second +> reader-facing narrative; the parent must be able to answer from this handoff +> without repeating discovery. Preserve requested quotations and inventories. +> Do not turn a terminal answer into a progress update. + +Pass known locations, decisions, and validation commands with the assignment. +Do not rewrite the task as a larger investigation or attach a second overlapping +checklist. Use workers for implementation and one writer per file. The parent +must not repeat work that remains assigned to a child. + +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. An evidence owner +returns the complete findings and support needed for the root's final synthesis; +an implementation owner returns the completed change and validation. Preserve +decisive excerpts, citations, relevant conditions, and explicit unresolved issues. +Use one finding-with-evidence handoff rather than both a polished draft answer +and an evidence report. Raw search transcripts alone are not a complete handoff. +The brief must request this evidence, rather than asking for conclusions and links +alone. Preserve requested quotations and complete caller coverage. +Check that each important claim follows from its evidence before returning; a +nearby symbol or default is not proof of an entire execution path. Continue only +for a missing caller requirement, material contradiction, or required validation. +A terminal reply delivers the finished result, not a progress update; if blocked, +state completed coverage, the dependency, and explicit partial status. Preserve +the requested presentation and all required checks. Keep private inter-agent source references lossless but compact. When parent and -child share an unambiguous workspace root, declare that root once in the handoff -and cite relative paths with the necessary line numbers instead of repeating the -full root in every citation. Preserve complete evidence, quotations, conclusions, -and unresolved limits; this changes reference encoding, not coverage. Use qualified -roots when files span workspaces or a relative reference would be ambiguous. -For final output, preserve required paths and citation format. Where that format -permits, introduce one clickable file link for a local group or table of findings -from that file, retaining each finding's precise line numbers. Keep separate -anchored links when required or needed to avoid ambiguity. Use concise labels; -avoid repeating the same findings in an additional source catalog. Shorten path -repetition and exposition while preserving every requested inventory, distinct -piece of evidence, and qualification. Follow higher-priority handoff formats too. - -Assign one owner to each independent investigation question, including read-only -work. While that child owns its scope, the parent does not run a parallel broad -investigation there; parent work stays independent, integrative, or targeted to -correctness. The parent accepts sufficient cited evidence and reopens only an -explicit missing claim, contradiction, or required check. Transfer a missing -question once to one owner rather than repeatedly reopening completed scope. -Keep ownership stable while a report is pending. For a necessary transfer, reuse -evidence already delivered or accessible, identify the remaining gap, and stop -the prior owner's work on that question if it is still active. Request missing -handoff evidence only when needed and the owner can respond. If the owner has -failed or is unavailable, continue authorized work from available evidence and -record what is missing instead of waiting for a handoff; the recovery rules below -still apply. Reuse completed discovery. Narrow independent checks of a concrete -correctness or integration risk remain allowed. - -Batch independent coordination. Let an active owner finish before sending -non-blocking findings or requests for progress or extra checks. Send earlier -messages only for a concrete blocker, changed requirement, or time-sensitive -dependency. Elapsed time alone is not evidence of a stall. Give required user -updates from the last known state without asking the child for a status report. - -When only child completion remains, use automatic native completion notifications -if the host supports them. Otherwise use one native wait for the outstanding -children, with the longest supported duration allowed by the next user update or -actionable deadline. A wrapping execution call must cover that duration within -its own supported limits. For a host exposing the first-line `// @exec` pragma -and `tools.multi_agent_v1__wait_agent`, when 45 seconds fits both limits and the -next required update, the matching call is: - -```js -// @exec: {"yield_time_ms": 45000} -text(await tools.multi_agent_v1__wait_agent({ - targets: [""], timeout_ms: 45000 -})); -``` - -Use the actual returned child ID and the host's available wait tool. Shorten both -durations together if a bound is sooner. After an early outer yield, resume the -exact returned `cell_id` under the same bounds; do not start another inner wait, -fabricate IDs, or alter output limits to simulate progress. Do not insert status -queries or new investigation between empty wait results. Preserve independent -work, targeted acceptance checks, required updates, and immediate blocker handling. - -Preserve the owed deliverable across follow-ups. Do not send scope reminders -that merely restate an active assignment without new evidence or a changed -requirement. Substantive follow-ups remain owed; acknowledgment or progress is not the result. -Until the parent explicitly confirms receipt of the full report or access to its -artifact, put that report, with later requests folded in, in the final response -itself. An earlier child final is not proof of delivery. Reuse existing evidence. -The parent includes that confirmation in an existing substantive follow-up when -requesting an amendment; do not add a confirmation-only round trip. After that -confirmation, the child returns only the requested amendment; the parent integrates -it with the retained report, preserving every acceptance item. Require neither a -new file nor repetition of a report the parent has confirmed receiving or accessing. -Explicit cancellation, replacement of the assignment, or a caller request for -acknowledgment alone governs the remaining deliverable. - -Every follow-up names the user-required decision that remains unresolved, the -question and evidence to check, and the stop condition. A follow-up supplements -the original assignment unless explicitly rescoping it; batch independent -unresolved questions into one message per child, and transfer each missing question -once to a single owner. Accept a complete report without a status request or extra -confirmation; use the native wait when only completion is outstanding. Preserve -targeted correctness verification and every requested deliverable. Finalize once -the requested coverage and checks are complete; do not add unrequested -investigation. +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. + +Use the owner's current state to choose the next action: + +| Owner state | Parent action | +| --- | --- | +| Running | Work on an independent deliverable or handle a concrete dependency. Otherwise wait for completion. | +| Returned | Check requested coverage and decisive evidence. Accept supported conclusions and integrate the answer. | +| Correction assigned | Send the missing claim, evidence to check, and completion condition together. That claim remains owned by the child until its amendment returns. | +| Unavailable | Explicitly take over using retained evidence and record unresolved gaps. | + +During a pending correction, do not concurrently reconstruct that same claim. +Required independent verification remains a separate, explicitly scoped check. +Return only the amendment on a follow-up; do not regenerate an accepted report. +Send early messages only for a changed requirement, blocker, or time-sensitive +dependency. An elapsed timeout alone is not such a dependency. + +Use one pending completion wait for the actual returned child IDs. Start with +the longest documented wait that fits the next required update or actionable +deadline; omit short readiness probes before it. Where the host requires polling +and supports a tool-side loop, keep those readiness checks inside that operation +and return on completion, a concrete error, or the update deadline. Never busy-loop. +Match the outer tool's wait duration to the pending inner operation. If the outer +call yields, resume its exact returned cell ID before starting another wait. +Do not re-enter investigation or alter output limits because a wait yielded. +Preserve required progress updates, immediate blocker handling, and acceptance. Research needs sources and a deadline or request budget. Name tools exactly, with verified capability/auth status; children discover deferred tools in their @@ -218,20 +170,6 @@ supported; no recursive teams. Return architectural, API, security, scope, or ambiguous decisions to the root for integration, conflict resolution, and final verification. -### Claude Code adapter - -Use native `Agent` (`Task` on older hosts) with `subagent_type="ug-smart-router:"`. -**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. - -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 @@ -252,25 +190,39 @@ replacement for the same assignment. ## Integrate and verify -Build the final answer from the draft and amendments. Reconcile every original -acceptance item against the evidence before reopening sources. Preserve conditions, -exceptions, and limitations that change what the caller can conclude or do; make -these distinctions explicit rather than leaving them implicit in an excerpt or -table label. A scoped amendment updates that part of the retained report without -discarding its other findings. - -Read child evidence, inspect worker diffs, and spot-check cited paths without -redoing a broad child-owned scope. Accept sufficient cited evidence and run only -the targeted correctness or risk checks needed by the requested outcome. Keep any -additional check independent of the child work or tied to a concrete integration -risk. 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 -remaining limitations. Do not claim cost or speed improvements without measurements. +Maintain one mapping from the caller's required deliverables to their current +owner and returned evidence. Use it to check coverage; it need not be an extra +user-facing checklist or a new artifact. A completed child covers its assignment, +not automatically the entire request. + +Collect ready child results without publishing each as a separate full answer. +Progress updates report progress and concrete dependencies. At finalization, +assemble one complete answer from all accepted results and necessary amendments. +Earlier progress text does not substitute for content required in the final answer. +Preserve the caller's requested presentation, evidence, conditions, and exceptions. + +Review the returned evidence before deciding whether another tool call is needed. +For each important conclusion, check that the quoted source conditions, actual diff, +or validation result support its scope and that the caller's requirement is covered. +A bare conclusion or citation without sufficient supporting evidence is a gap; +ask the owner for that evidence or retrieve the specific missing source window. +When the returned evidence is sufficient, accept it without fetching the same +implementation again. Retrieving every cited file is not a default review phase. +Reopen a concrete contradiction, missing condition, changed input, or required check. +Keep explicitly required independent verification and substantive tests. Add another +reviewer only for a distinct risk or a requested independent check. Integrate accepted +components without repeating their discovery or generating a second full draft. + +Before delivery, check the assembled answer against the complete caller request +and every accepted handoff. Correct missing or conflicting components with their +owners. If a component cannot be completed, state the exact gap and explicit +partial status; do not imply that the latest returned component completes the task. +For an empty or unrelated result, clarify once with the same child and verify the +amendment. If it remains unusable, report the unmet assignment without respawning. +Account for each required child and report unavailable tools or substitutions. + +Finish with the concrete result, verification performed, and material remaining +limitations. Do not claim cost or speed improvements without measurements. Use runtime evidence to identify the model that ran; submitting a delegation alone does not prove that its routing hook executed. From 11f1158eaad453f236e13862d9711b45de212465 Mon Sep 17 00:00:00 2001 From: Josh Joseph Date: Fri, 9 Oct 2026 19:38:13 +0000 Subject: [PATCH 3/7] Preserve original orchestrator workflows in UG --- skills/smart-router-orchestrator/README.md | 9 +- .../smart-router-orchestrator/SKILL.claude.md | 69 ++++++-------- .../smart-router-orchestrator/SKILL.codex.md | 91 ++++++++++--------- 3 files changed, 81 insertions(+), 88 deletions(-) diff --git a/skills/smart-router-orchestrator/README.md b/skills/smart-router-orchestrator/README.md index 2750a935c..6290756e3 100644 --- a/skills/smart-router-orchestrator/README.md +++ b/skills/smart-router-orchestrator/README.md @@ -27,8 +27,9 @@ 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:` 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 with max reasoning effort. 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. @@ -59,14 +60,14 @@ 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 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. +separate refinements. 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 diff --git a/skills/smart-router-orchestrator/SKILL.claude.md b/skills/smart-router-orchestrator/SKILL.claude.md index ca51b3c5e..d3a1bbf26 100644 --- a/skills/smart-router-orchestrator/SKILL.claude.md +++ b/skills/smart-router-orchestrator/SKILL.claude.md @@ -1,42 +1,31 @@ --- 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.2.0" + --- # Smart Router Orchestrator -## Activation - -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; -installed skill files and old context do not enable it. Use that context without -running a separate pre-delegation check. Do not set flags or create a session to -activate this workflow. - -Turning Smart Router off through its skill stops this workflow and supersedes -earlier orchestration instructions. Do not start new automatic delegation or use -Smart Router Orchestrator role models as a fallback. Continue in the root unless the user -explicitly requests a subagent; honor that request using the native tool and normal harness -model selection, without this workflow. Keep routing off -and collect results from existing children. Turning Smart Router back on restores -this workflow only if the session was launched with `ENABLE_SMART_ROUTER_ORCHESTRATOR=1`. -Use the `smart-router` skill only when the user asks to change routing. - -## Workflow +installed skill files and old context do not enable it. Follow user overrides. Keep the active root model and reasoning effort. The root owns the delegation choice, cross-deliverable integration, conflicts, and acceptance; a delegated owner owns task-level planning, discovery, execution, -checks, and the draft result. Smart routing selects child models; -do not apply separate role-model preferences or reasoning-effort overrides. +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. +Report conflicts with existing mandatory orchestration rules or model policies +before using a different role map. ## Delegation gate @@ -57,13 +46,13 @@ 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 | -| --- | --- | -| 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 | +| 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 @@ -154,16 +143,17 @@ verification. ### Claude Code adapter Use native `Agent` (`Task` on older hosts) with `subagent_type="ug-smart-router:"`. -**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. +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 @@ -186,6 +176,3 @@ respawning. Report unavailable models, tools, and substitutions. Finish with the concrete result, verification actually performed, and material remaining limitations. Do not claim cost or speed improvements without measurements. - -Use runtime evidence to identify the model that ran; submitting a delegation -alone does not prove that its routing hook executed. diff --git a/skills/smart-router-orchestrator/SKILL.codex.md b/skills/smart-router-orchestrator/SKILL.codex.md index 94f799a73..ec72847c0 100644 --- a/skills/smart-router-orchestrator/SKILL.codex.md +++ b/skills/smart-router-orchestrator/SKILL.codex.md @@ -1,43 +1,32 @@ --- 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.2.0" + --- # Smart Router Orchestrator -## Activation - -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; -installed skill files and old context do not enable it. Use that context without -running a separate pre-delegation check. Do not set flags or create a session to -activate this workflow. - -Turning Smart Router off through its skill stops this workflow and supersedes -earlier orchestration instructions. Do not start new automatic delegation or use -Smart Router Orchestrator role models as a fallback. Continue in the root unless the user -explicitly requests a subagent; honor that request using the native tool and normal harness -model selection, without this workflow. Keep routing off -and collect results from existing children. Turning Smart Router back on restores -this workflow only if the session was launched with `ENABLE_SMART_ROUTER_ORCHESTRATOR=1`. -Use the `smart-router` skill only when the user asks to change routing. - -## Workflow +installed skill files and old context do not enable it. Follow user overrides. Keep the active root model and reasoning effort. The root owns the delegation choice, cross-deliverable integration, conflicts, and acceptance; a delegated owner owns its complete discovery or implementation assignment and its checks. Choose who synthesizes the final answer before -assigning the work. Smart routing selects child models; -do not apply separate role-model preferences or reasoning-effort overrides. +assigning the work. Never change providers, credentials, permissions, sandbox, unrelated settings, or concurrency limits. -Report conflicts with existing mandatory orchestration rules or model policies. +Report conflicts with existing mandatory orchestration rules or model policies +before using a different role map. ## Delegation gate @@ -61,13 +50,13 @@ independent check. Launch ready independent assignments together. If spawning is unavailable or prohibited, continue within the caller's instructions. Reuse complete instructions already received and recover only missing portions. -| 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 | +| Role | Scope | Codex default | +| --- | --- | --- | +| explorer | Read code and callers; map existing patterns/tests; no edits | Luna, max | +| researcher | Verify external/API facts with primary sources; no edits | Luna, max | +| worker | Implement one bounded change in explicitly owned files | Luna, max | +| tester | Independently run checks and report failures; edit tests only if assigned | Luna, max | +| reviewer | Review the actual diff for correctness, regressions, security, and missing tests; no edits | Luna, max | ## Assign and coordinate @@ -172,21 +161,40 @@ verification. ### 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 +By default, every initial native `spawn_agent` call must explicitly carry +`model="gpt-5.6-luna"` and `reasoning_effort="max"`. +This also applies when a routing hook replaces the model: do not omit these +fields and inherit the root's defaults. +Attempt this model even if absent from the tool's partial preview. Do not retry +another spelling, invent aliases, or substitute a successor. Send the role scope +and contract in `message`; use `fork_turns="none"` if overrides require fresh context. Use the host's native follow-up, message, wait, and close tools. Do not choose a custom -role that pins a model or effort. +role that pins a different 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. +### Recover a Codex delegation + +Before every retry, check these conditions in order: + +1. Did `spawn_agent` return a child ID for this assignment? If yes, **never spawn + a replacement**, even after closing it. An error from wait, notification, or + the child provider is a child failure, not a rejected spawn. Report it unmet. +2. Is the error permission, authentication, or capacity related? Stop. No alias + retry, inherited fallback, or changes to permissions, credentials, or limits. +3. Did `spawn_agent` itself reject the model/effort before returning any child ID? + Only this selection failure (or a schema without overrides) permits recovery. + +Allow fallback only for the bundled defaults. Honor explicit settings and +conversation/policy constraints; never change roles or configuration to evade them. + +If eligible, disclose the failure and **attempt one native spawn omitting both +`model` and `reasoning_effort`**, with the same contract and fresh context (`fork_turns="none"` +when exposed). A routing hook may select a model; otherwise harness defaults or +inheritance apply. Do not assume routing ran or fallback will succeed. If forbidden +or unsuccessful, stop retrying and report the error and unmet assignment. ## Integrate and verify @@ -223,6 +231,3 @@ Account for each required child and report unavailable tools or substitutions. Finish with the concrete result, verification performed, and material remaining limitations. Do not claim cost or speed improvements without measurements. - -Use runtime evidence to identify the model that ran; submitting a delegation -alone does not prove that its routing hook executed. From 88eb583486185d7b2a9256b8b643ed4aaf9b48de Mon Sep 17 00:00:00 2001 From: Josh Joseph Date: Fri, 9 Oct 2026 19:50:13 +0000 Subject: [PATCH 4/7] Restore UG activation guidance and skill metadata --- skills/smart-router-orchestrator/README.md | 2 +- .../smart-router-orchestrator/SKILL.claude.md | 24 ++++++++++++++++++- .../smart-router-orchestrator/SKILL.codex.md | 24 ++++++++++++++++++- 3 files changed, 47 insertions(+), 3 deletions(-) diff --git a/skills/smart-router-orchestrator/README.md b/skills/smart-router-orchestrator/README.md index 6290756e3..4e89038ba 100644 --- a/skills/smart-router-orchestrator/README.md +++ b/skills/smart-router-orchestrator/README.md @@ -67,7 +67,7 @@ model selection and requires no preference setup or locking. 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. +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 diff --git a/skills/smart-router-orchestrator/SKILL.claude.md b/skills/smart-router-orchestrator/SKILL.claude.md index d3a1bbf26..8adea92a8 100644 --- a/skills/smart-router-orchestrator/SKILL.claude.md +++ b/skills/smart-router-orchestrator/SKILL.claude.md @@ -10,13 +10,32 @@ description: >- model: inherit argument-hint: "[task]" +metadata: + version: "1.2.0" --- # Smart Router Orchestrator +## Activation + +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; -installed skill files and old context do not enable it. +installed skill files and old context do not enable it. Use that context without +running a separate pre-delegation check. Do not set flags or create a session to +activate this workflow. + +Turning Smart Router off through its skill stops this workflow and supersedes +earlier orchestration instructions. Do not start new automatic delegation or use +Smart Router Orchestrator role models as a fallback. Continue in the root unless the user +explicitly requests a subagent; honor that request using the native tool and normal harness +model selection, without this workflow. Keep routing off +and collect results from existing children. Turning Smart Router back on restores +this workflow only if the session was launched with `ENABLE_SMART_ROUTER_ORCHESTRATOR=1`. +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 the delegation choice, cross-deliverable integration, conflicts, and @@ -176,3 +195,6 @@ respawning. Report unavailable models, tools, and substitutions. Finish with the concrete result, verification actually performed, and material remaining limitations. Do not claim cost or speed improvements without measurements. + +Use runtime evidence to identify the model that ran; submitting a delegation +alone does not prove that its routing hook executed. diff --git a/skills/smart-router-orchestrator/SKILL.codex.md b/skills/smart-router-orchestrator/SKILL.codex.md index ec72847c0..5a5dd8c72 100644 --- a/skills/smart-router-orchestrator/SKILL.codex.md +++ b/skills/smart-router-orchestrator/SKILL.codex.md @@ -10,13 +10,32 @@ description: >- model: inherit argument-hint: "[task]" +metadata: + version: "1.2.0" --- # Smart Router Orchestrator +## Activation + +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; -installed skill files and old context do not enable it. +installed skill files and old context do not enable it. Use that context without +running a separate pre-delegation check. Do not set flags or create a session to +activate this workflow. + +Turning Smart Router off through its skill stops this workflow and supersedes +earlier orchestration instructions. Do not start new automatic delegation or use +Smart Router Orchestrator role models as a fallback. Continue in the root unless the user +explicitly requests a subagent; honor that request using the native tool and normal harness +model selection, without this workflow. Keep routing off +and collect results from existing children. Turning Smart Router back on restores +this workflow only if the session was launched with `ENABLE_SMART_ROUTER_ORCHESTRATOR=1`. +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 the delegation choice, cross-deliverable integration, conflicts, and @@ -231,3 +250,6 @@ Account for each required child and report unavailable tools or substitutions. Finish with the concrete result, verification performed, and material remaining limitations. Do not claim cost or speed improvements without measurements. + +Use runtime evidence to identify the model that ran; submitting a delegation +alone does not prove that its routing hook executed. From 3b2ddb4ee82e034f88e849e98da9db7a6cda25dd Mon Sep 17 00:00:00 2001 From: Josh Joseph Date: Fri, 9 Oct 2026 20:15:49 +0000 Subject: [PATCH 5/7] Let routed Codex models use their default reasoning effort --- skills/smart-router-orchestrator/README.md | 4 ++-- skills/smart-router-orchestrator/SKILL.codex.md | 15 +++++++-------- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/skills/smart-router-orchestrator/README.md b/skills/smart-router-orchestrator/README.md index 4e89038ba..9c3158f96 100644 --- a/skills/smart-router-orchestrator/README.md +++ b/skills/smart-router-orchestrator/README.md @@ -28,8 +28,8 @@ User instructions take precedence, and easy tasks remain in the root. Claude loads the bundled roles as `ug-smart-router:` in its temporary routing plugin. Claude omits model overrides; its bundled roles default to Sonnet. -Codex requests Luna with max reasoning effort. The routing hook can replace the -requested model. +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. diff --git a/skills/smart-router-orchestrator/SKILL.codex.md b/skills/smart-router-orchestrator/SKILL.codex.md index 5a5dd8c72..ca5311192 100644 --- a/skills/smart-router-orchestrator/SKILL.codex.md +++ b/skills/smart-router-orchestrator/SKILL.codex.md @@ -71,11 +71,11 @@ Reuse complete instructions already received and recover only missing portions. | Role | Scope | Codex default | | --- | --- | --- | -| explorer | Read code and callers; map existing patterns/tests; no edits | Luna, max | -| researcher | Verify external/API facts with primary sources; no edits | Luna, max | -| worker | Implement one bounded change in explicitly owned files | Luna, max | -| tester | Independently run checks and report failures; edit tests only if assigned | Luna, max | -| reviewer | Review the actual diff for correctness, regressions, security, and missing tests; no edits | Luna, max | +| explorer | Read code and callers; map existing patterns/tests; no edits | Luna | +| researcher | Verify external/API facts with primary sources; no edits | Luna | +| worker | Implement one bounded change in explicitly owned files | Luna | +| tester | Independently run checks and report failures; edit tests only if assigned | Luna | +| reviewer | Review the actual diff for correctness, regressions, security, and missing tests; no edits | Luna | ## Assign and coordinate @@ -181,9 +181,8 @@ verification. ### Codex adapter By default, every initial native `spawn_agent` call must explicitly carry -`model="gpt-5.6-luna"` and `reasoning_effort="max"`. -This also applies when a routing hook replaces the model: do not omit these -fields and inherit the root's defaults. +`model="gpt-5.6-luna"`. Omit `reasoning_effort` so the model selected by +routing uses its supported default. Attempt this model even if absent from the tool's partial preview. Do not retry another spelling, invent aliases, or substitute a successor. Send the role scope and contract in `message`; use `fork_turns="none"` if overrides require fresh context. Use the From 25da00429ae0bd945fd91eec3c3ce2240bf43d39 Mon Sep 17 00:00:00 2001 From: Josh Joseph Date: Fri, 9 Oct 2026 20:29:49 +0000 Subject: [PATCH 6/7] Remove stray blockquote formatting from Codex skill --- .../smart-router-orchestrator/SKILL.codex.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/skills/smart-router-orchestrator/SKILL.codex.md b/skills/smart-router-orchestrator/SKILL.codex.md index ca5311192..0f0932ec6 100644 --- a/skills/smart-router-orchestrator/SKILL.codex.md +++ b/skills/smart-router-orchestrator/SKILL.codex.md @@ -86,23 +86,23 @@ Include the following execution contract in the actual child assignment; do not assume the child inherits this skill. The root uses the same contract when working directly. -> Start from supplied evidence and entrypoints. Before each tool call, identify -> what it can settle that retained evidence cannot. Obtain the smallest sufficient -> evidence: locate with file names or symbols, -> then inspect the relevant definition and connected conditions or callers. -> Read the complete function or configuration block needed to support the claim; -> read a whole file when its flow is required. Batch independent queries and -> combine overlapping windows. Reuse established facts and citation spans. -> Preserve explicit searches, exhaustive coverage, required checks, and material -> qualifications. Continue for an uncovered requirement, contradiction, or -> required validation; related names alone do not expand the assignment. -> Return the complete assigned evidence or change, with decisive cited excerpts, -> their relevant conditions, validation evidence, and explicit unresolved items. -> For an evidence assignment, place each finding beside its supporting excerpt -> and necessary interpretation. Cover every caller requirement without a second -> reader-facing narrative; the parent must be able to answer from this handoff -> without repeating discovery. Preserve requested quotations and inventories. -> Do not turn a terminal answer into a progress update. +Start from supplied evidence and entrypoints. Before each tool call, identify +what it can settle that retained evidence cannot. Obtain the smallest sufficient +evidence: locate with file names or symbols, +then inspect the relevant definition and connected conditions or callers. +Read the complete function or configuration block needed to support the claim; +read a whole file when its flow is required. Batch independent queries and +combine overlapping windows. Reuse established facts and citation spans. +Preserve explicit searches, exhaustive coverage, required checks, and material +qualifications. Continue for an uncovered requirement, contradiction, or +required validation; related names alone do not expand the assignment. +Return the complete assigned evidence or change, with decisive cited excerpts, +their relevant conditions, validation evidence, and explicit unresolved items. +For an evidence assignment, place each finding beside its supporting excerpt +and necessary interpretation. Cover every caller requirement without a second +reader-facing narrative; the parent must be able to answer from this handoff +without repeating discovery. Preserve requested quotations and inventories. +Do not turn a terminal answer into a progress update. Pass known locations, decisions, and validation commands with the assignment. Do not rewrite the task as a larger investigation or attach a second overlapping From 586963201be2ff77a5d316c5f95e337f9bfdf593 Mon Sep 17 00:00:00 2001 From: Josh Joseph Date: Fri, 9 Oct 2026 21:15:08 +0000 Subject: [PATCH 7/7] Recover full orchestrator instructions from truncated hooks --- skills/smart-router-orchestrator/SKILL.claude.md | 4 ++++ skills/smart-router-orchestrator/SKILL.codex.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/skills/smart-router-orchestrator/SKILL.claude.md b/skills/smart-router-orchestrator/SKILL.claude.md index 8adea92a8..222b7ca7a 100644 --- a/skills/smart-router-orchestrator/SKILL.claude.md +++ b/skills/smart-router-orchestrator/SKILL.claude.md @@ -19,6 +19,10 @@ metadata: ## 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; diff --git a/skills/smart-router-orchestrator/SKILL.codex.md b/skills/smart-router-orchestrator/SKILL.codex.md index 0f0932ec6..6f67909fb 100644 --- a/skills/smart-router-orchestrator/SKILL.codex.md +++ b/skills/smart-router-orchestrator/SKILL.codex.md @@ -19,6 +19,10 @@ metadata: ## Activation +If this workflow is truncated and the full instructions are not already in +context, read `SKILL.codex.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;