<p align="center">
<a href="https://yield.operatorstack.systems/">
<img src="https://raw.githubusercontent.com/operatorstack/yield/main/assets/yield-mark.svg" width="96" alt="Yield" />
</a>
</p>
<h1 align="center">Yield for Rust</h1>
<p align="center"><strong>Move repeatable coding-agent instructions from words into Rust.</strong></p>
<p align="center">
Build typed, resumable workflows that stay beside the code they operate on.
</p>
<p align="center">
<a href="https://crates.io/crates/yieldskill"><img alt="crates.io version" src="https://img.shields.io/crates/v/yieldskill?style=flat-square" /></a>
<a href="https://docs.rs/yieldskill"><img alt="docs.rs" src="https://img.shields.io/docsrs/yieldskill?style=flat-square" /></a>
<a href="https://github.com/operatorstack/yield/actions/workflows/verify.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/operatorstack/yield/verify.yml?branch=main&style=flat-square&label=build" /></a>
<a href="https://github.com/operatorstack/yield/blob/main/LICENSE"><img alt="MIT license" src="https://img.shields.io/crates/l/yieldskill?style=flat-square" /></a>
</p>
<p align="center">
<a href="https://yield.operatorstack.systems/">Website</a> ·
<a href="https://yield.operatorstack.systems/docs/">Documentation</a> ·
<a href="https://crates.io/crates/yieldskill">crates.io</a> ·
<a href="https://docs.rs/yieldskill">docs.rs</a> ·
<a href="https://github.com/operatorstack/yield">GitHub</a>
</p>
The crate and library names are both `yieldskill`. The installed command is
`yskill`.
## Create a workflow
### 1. Install Yield
Yield supports Rust on macOS, Linux, and Windows. Install the public crate:
```bash
cargo install yieldskill --root .yield --locked
.yield/bin/yskill --version
```
The crate contains the matching `yskill` runtime for your platform. You do not
need Go, Node.js, or a separate CLI download.
### 2. Create the workflow
Create a Rust workflow inside your repository:
```bash
.yield/bin/yskill init skills/data-migration \
--language rust \
--description "Dry-run, approve, apply, and verify a database migration."
```
Replace `skills/data-migration/src/main.rs` with this tested workflow:
```rust
use serde_json::json;
use yieldskill::{define_skill, Context, SkillResult};
fn program(ctx: &mut Context) -> SkillResult {
let dry_run = ctx.run_command("dry-run", "echo 'plan: add index users_email_idx'", 300);
ctx.require(
dry_run.exit_code == 0,
"the dry run succeeds",
Some(&json!({ "exit_code": dry_run.exit_code })),
);
let review = ctx.agent_task(
"summarize-plan",
"Summarize the migration plan for the operator: what changes, what is irreversible, what the rollback is.",
Some(json!({ "plan": dry_run.stdout })),
Some(json!({
"type": "object",
"required": ["summary"],
"properties": { "summary": { "type": "string", "minLength": 1 } }
})),
);
let approval = ctx.ask_user(
"approve-apply",
"Apply the migration to the live database?",
&[("apply", "Apply now"), ("abort", "Abort")],
);
if approval != "apply" {
return Err(ctx.refused("the operator declined to apply the migration"));
}
let apply = ctx.run_command("apply", "echo apply-ok", 600);
ctx.require(
apply.exit_code == 0,
"the migration applies cleanly",
Some(&json!({ "exit_code": apply.exit_code })),
);
let verify = ctx.run_command("verify", "echo verify-ok", 300);
ctx.require(
verify.exit_code == 0,
"post-apply verification passes",
Some(&json!({ "exit_code": verify.exit_code })),
);
Ok(json!({
"applied": true,
"summary": review["summary"],
}))
}
fn main() {
define_skill(program);
}
```
The generated `Cargo.toml` pins the public `yieldskill` crate to the installed
CLI version. The generated `skill.json` runs the named Rust binary.
### 3. Test the workflow
Use deterministic fixture responses during tests. Save this as
`skills/data-migration/fixtures/responses.json`:
```json
{
"summarize-plan": {
"summary": "Adds users_email_idx concurrently; no data rewrite; rollback is DROP INDEX. The only irreversible step is index creation time."
},
"approve-apply": { "value": "apply" }
}
```
Then test the workflow:
```bash
.yield/bin/yskill doctor skills/data-migration --root . --test
```
Yield runs commands for real and supplies agent and user responses from the
fixture. A successful test reaches `completed` without leaving a run journal.
### 4. Register the skill
Registration lets installed coding agents discover the workflow:
```bash
.yield/bin/yskill register skills/data-migration --root .
```
Select the verified agents explicitly when you do not want automatic
detection:
```bash
.yield/bin/yskill register skills/data-migration --root . \
--agent cursor,codex,claude-code
```
The generated adapters point back to `skills/data-migration`. They do not copy
the workflow or install its dependencies again.
### 5. Run the skill
Start a new coding-agent session so it discovers the registered skill. Where
slash skills are supported, run:
```text
/data-migration
```
Otherwise, ask the agent in plain language:
```text
Use the data-migration skill to apply this migration safely.
```
The agent follows the adapter, starts the canonical Rust workflow, and asks for
each required agent or user response.
## How Yield runs and resumes
1. Your Rust function emits one typed operation.
2. Yield records the request and exits. It does not run a daemon.
3. The coding agent, user, or CLI supplies the result.
4. Yield replays the function from its journal until it reaches the next
operation.
Replay must produce the same operation sequence. Yield reports divergence
instead of giving a recorded response to a different operation.
## Where AgentTask fits
`ctx.agent_task()` delegates one bounded judgment to the coding agent. Pass
important evidence explicitly, as this workflow passes its dry-run output.
With its schema, Yield checks the returned JSON shape before the workflow
continues; it does not prove the summary is correct. Host workspace and
conversation access are host-dependent.
| `ctx.run_command()` | Execute a command and record its exit code and output. |
| `ctx.agent_task()` | Delegate one bounded judgment; an optional schema validates the result. |
| `ctx.ask_user()` | Request an explicit human decision. |
| `ctx.require()` | Bind a required claim to recorded evidence. |
| `ctx.blocked()` / `ctx.refused()` | Stop honestly when work cannot or must not continue. |
See the [primitive guides](https://yield.operatorstack.systems/docs/primitives/)
and [CLI reference](https://github.com/operatorstack/yield/blob/main/docs/reference/cli.md)
for the complete contract.
## Guarantees and limits
Yield provides deterministic control flow, typed requests and responses,
persistent run state, replay with divergence detection, stale and duplicate
response rejection, and evidence-bound completion.
Schema validity is not truth. Yield cannot prove that a coding agent performed
only the requested work. `run_command` is different: the Yield CLI executes the
command, so its recorded exit code and output are observed facts.
Programs must remain deterministic between operations. Do not read clocks,
random values, environment variables, or changing files to choose the next
operation. Cross those boundaries through a Yield operation instead.
Yield is not a daemon, hosted runtime, workflow DSL, marketplace, coding-agent
loop, multi-agent orchestrator, or security sandbox.
## Optional developer helper
Installing `yieldskill` does not create skills or coding-agent adapters. After
learning the manual workflow above, install guided assistance explicitly:
```bash
.yield/bin/yskill helper install --root . --language rust
```
Review the plan and restart the coding agent after installation. The helper
can teach, create, convert, check, repair, upgrade, and register workflows.
`yskill bootstrap` remains a compatibility alias.
## Coding agents and source
Cursor, Codex, and Claude Code are verified integrations. Yield also provides
registry-backed project paths for other coding agents; those paths are not
presented as end-to-end verified.
- [Read the documentation](https://yield.operatorstack.systems/docs/)
- [Explore tested examples](https://github.com/operatorstack/yield/tree/main/examples)
- [View the Rust source](https://github.com/operatorstack/yield/tree/main/sdk/rust)
- [Read the API documentation](https://docs.rs/yieldskill)
- [Report an issue](https://github.com/operatorstack/yield/issues)
Yield is available under the
[MIT license](https://github.com/operatorstack/yield/blob/main/LICENSE).