scode-harness-shellout specification
Dependencies: none
NOTE: This file is binding on the skill's text. It is deliberately sparse: it records only requirements that have been stated as such, not a description of everything the skill does. Absence of an entry means the behavior is not yet specified, not that it is unspecified on purpose. When the skill and this file disagree, that is a bug in one of them; fix the skill or change this file in the same change, never leave them apart.
Requirements
- The skill depends on no other skill, and its text refers to no other skill: no pointer upward or sideways into a consumer ("escalate per the caller's rules", "see the gate", a named skill or one of its files). Where the text needs a fact only a caller has — the model and effort, the run id, the tree, the deadline, whether the run will be resumed — it names that fact as an input the caller supplies and stops there.
- Loading the skill is side-effect free. Invoking it activates nothing for the session, writes nothing, and claims
nothing about later spawns; its
SKILL.mdsays so in its first paragraph. A current delegation request can use its mechanics without establishing a session-wide mode. No harness-level switch turns off description-based selection: Codex'sallow_implicit_invocation: falseinagents/openai.yamlis also read by Muse Code, which then refuses to load the skill for the model at all (verified on Muse Code 1.0.2), and a skill that other skills load by name cannot carry it. Loading alone does not authorize a launch. - The description and
SKILL.mdrecognize direct requests to start or use named-model agents (including "astra agent", "opus agent", and "neon agent"), agents from another provider or harness, and models unsupported by native delegation. The user need not name the skill; requiring that has repeatedly prevented the intended shell-out path from being discovered. Mere model mentions and questions about models do not authorize delegation. For a direct request with no selected launch mechanism, prefer native delegation when it supports the requested model, effort, and required resume behavior. Otherwise choose the external mechanism by the rule below. Preserve a mechanism selected by the user or caller, including an external mechanism when native delegation is available. Do not silently substitute a native model or report native limitations as proof that the requested agent cannot run externally. - This skill is the one place that decides which CLI runs a model externally; callers that only know a route is external
pass
externaland let it decide. The rule: a harness the user names for the launch, or a harness preference the user has stated, comes first; then the family's own harness for families that have one with a harness file here (GPT, Claude, Muse, and Gemini, whose bare line names such asneonalso go toagy -p); thenomp -p, the default for every other model; thenopencode run. Every candidate is filtered on being installed and able to serve the model. A harness the user named for the launch is never replaced; a standing preference that cannot serve the model falls through. Only mechanisms with a harness file here are candidates, so a family whose vendor ships a harness this skill has no file for is treated like every other model until that file exists. The rule picks a CLI only; it never substitutes a model. - omp's provider is
openrouterunless the user has stated another. There is no discovery of which other providers serve a model: the default keeps the choice predictable and unattended runs free of provider questions. SKILL.mdis the public surface and is kept lean: what a caller needs on every load stays in it, and anything a caller does not need on every load lives in a sidecar read on demand.SKILL.mdnames the trigger for each sidecar, and that table is keyed on the launch-mechanism strings it reads a file for:codex exec,claude -p,muse exec,agy -p,opencode run, andomp -peach name one file underharness/, andnativenames nothing, because this skill has no shell-out mechanics to apply to a native delegation. A caller may also holdexternal, which resolves to one of the six before the table is consulted.- Launch commands live only in the harness files.
SKILL.mdcarries no launch line, so that every launch goes through the file that carries the observed-behavior notes for that harness. - Codex and Claude harness files describe access to the recorded tool conversation when the caller needs it. Distinguish raw command output from the result delivered to the agent, preserve session identity across resumes, and state the tool/version limits of observed output representations. The caller decides how to use those records.
- Multiple concurrent orchestrators must not conflict through anything this skill puts on disk. Every scratch file, prompt, result file, event log, and stderr log it prescribes is named by the run id the caller supplies, in scratch space private to the session; nothing uses a fixed path.
- The skill is meant to work on modern Linux and macOS. Commands, paths, and tools it prescribes must be available on both; nothing may rely on one without an equivalent for the other. No other platform is of concern, and the skill's text need not accommodate one.
- Waiting prefers the parent harness's automatic process-completion delivery where available, otherwise bounded waits on known handles with batched checks and compact observations. A log or status file alone is not notification delivery. Prefer monitoring without model turns; a small-context watcher is allowed when it can notify the caller without being polled and is expected to reduce total cost, including launch overhead and polling usage. Wait expiry alone never terminates a child. Reducing wakeups must preserve monitoring intervals, caller-required resource checks, responsiveness, and hard deadlines.