Primitive 01 / Machine

RunCommand

Run a real command and save what happened. Use it for facts the machine can observe.

01 / When

Use it when success depends on real output.

Yield runs the command and records what happened. The coding agent does not transcribe its result.

Useful for

Run the test suiteContinue only when tests pass.
Check the typesStop code with invalid types.
Build the artifactRequire a buildable output.
Preview the migrationSee changes before applying them.
Run the deployRecord the real deploy result.
Probe service healthVerify the service responds.

Choose the boundary.Use RunCommand for observable facts. Use AgentTask only when output needs interpretation.

02 / Code

Bind the command result to the claim.

RunCommand · TypeScript

import { defineSkill } from "@operatorstack/yield"

defineSkill((ctx) => {
  const test = ctx.runCommand("test", "npm test", 300)
  ctx.require(test.exit_code === 0, "tests pass", test)
  return { passed: true }
})

Other language versions

Python

from yieldskill import define_skill

def program(ctx):
    test = ctx.run_command("test", "pytest", 300)
    ctx.require(test.exit_code == 0, "tests pass", test)
    return {"passed": True, "output": test.stdout}

define_skill(program)

Go

package main

import "github.com/operatorstack/yield/sdk/yield"

func main() {
  yield.Main(func(ctx *yield.Context) (yield.Outcome, error) {
    test := ctx.RunCommand("test", "go test ./...", 300)
    ctx.Require(test.ExitCode == 0, "tests pass", test)
    return ctx.Complete(map[string]any{"passed": true})
  })
}

Rust

use yieldskill::{define_skill, Context, SkillResult};

fn program(ctx: &mut Context) -> SkillResult {
  let test = ctx.run_command("test", "cargo test", 300);
  ctx.require(test.exit_code == 0, "tests pass", None);
  Ok(serde_json::json!({ "passed": true }))
}

fn main() { define_skill(program); }

03 / Run

See the request become recorded evidence.

CursorYield run · command

› /test-workflow

Running the workflow’s test command.

Yield CLI performs this operation.

npm testexit 0

✓ 24 tests passed

completed in 1.8s

Saved response

{
  "exit_code": 0,
  "stdout": "24 tests passed",
  "stderr": "",
  "timed_out": false
}

04 / Shape

Three inputs. One recorded result.

Operation ID: A stable name used during replay.
Command: The command string Yield executes.
Timeout: Optional maximum duration in seconds.
Result: exit_code, stdout, stderr, and timed_out.

05 / Saved

The response becomes part of the run.

Yield records the command result and replays it when the workflow starts again. The command is not repeated unless the program reaches a new operation.

Common mistake

Do not ask the model whether a command passed. Run it, check the exit code, then ask the model only if the output needs interpretation.