Repository navigation
orch: move spawn-adapter choreography (task_name translation, thread-cap recovery) from SKILL.md prose into the spawn helpers #900
Description
Symptom
skills/orch/SKILL.md carries two >1,500-character single-paragraph blocks of spawn choreography every orchestrator must hand-execute:
- The Codex
task_nameschema workaround (vstack#751): translate hyphenated agent names to underscores at spawn while preserving canonical names in all records, plus the worker-fallback decision tree and where to record runtime metadata. - The MultiAgentV2 thread-cap recovery (Codex Desktop: MultiAgentV2 silently bypasses agents.max_threads with no migration warning openai/codex#33447/#33039): dual-key config caveats, REVIEWER_SLOT_BUDGET derivation, and the demote-to-bounded-waves procedure.
Both encode workarounds for external constraints as agent-facing prose. Each orchestrator session re-reads, re-derives, and can re-fumble them (recording task_name in the wrong key, raising the silently-ignored legacy cap alone, etc.).
Proposal
Absorb the mechanics into the existing script layer so the prose collapses to intent:
- A spawn-adapter helper (or an extension of
list-review-agents/session-init) that takes the canonical agent name and emits/executes the correct spawn parameters: translatedtask_name, resolvedagent_type, fallback decision, and the runtime-metadata record shape — one call, one JSON result. Prose becomes: 'spawn via the adapter; canonical names everywhere, runtime detail is recorded for you.' - Slot-budget derivation as a helper query (read config keys, print effective cap + recommended REVIEWER_SLOT_BUDGET) rather than instructions to hand-read ~/.codex/config.toml with caveats about which key is silently ignored.
Payoff
Two of the densest instruction blocks in the largest SKILL.md (556 lines) become tool calls; the external-issue citations move to code comments where they rot harmlessly; new harness quirks get absorbed by editing one helper instead of re-teaching every orchestrator.
Context: same consumer-side audit as vstack#899 (standard: over-explained prose signals a tool gap). Filed with user approval (Brad, 2026-07-26).
Activity
bmethod commentedon Jul 27, 2026
Accepted, starting on this one now — smaller than #899, self-contained, and verifiable without a live runtime.
Shape I am building:
spawn-adapter spawn <canonical-agent-name> [--fallback-reason …]— one call returning the complete spawn decision as JSON: canonical identity, resolvedagent_type, translatedtask_name, and the exact runtime-metadata record shape. The canonical hyphenated name stays the identity everywhere orch records it; the underscore form becomes a field the tool fills in, not a rule each orchestrator re-applies.spawn-adapter slots— reads the config and prints the effective cap plus the recommendedREVIEWER_SLOT_BUDGET, including an explicit warning when only the legacyagents.max_threadskey is set. That silent-ignore trap is the single most re-fumbleable thing in the block and it becomes a diagnostic instead of a caveat someone has to remember.The external-issue citations (vstack#751, openai/codex#33447/#33039) move into code comments where they rot harmlessly, per your framing.