Skip to content

README.md

Latest commit

 

History

History
342 lines (257 loc) · 15.4 KB

README.md

File metadata and controls

342 lines (257 loc) · 15.4 KB
Raw

Yield

Yield

Move repeatable coding-agent instructions from words into code.

In-repository workflows for TypeScript, Python, Go, and Rust.

npm version PyPI version crates.io version Go reference Build status MIT license

Website · Documentation · npm · PyPI · crates.io · pkg.go.dev · GitHub

Yield turns repeated instructions for coding agents into typed, resumable programs. The canonical workflow stays inside your repository beside the code and dependencies it uses. Generated SKILL.md files only help coding agents discover it.

Write the workflow in code. Use AgentTask only where a bounded step needs coding-agent judgment, then continue with structured data in normal code.

Verified with Cursor, Codex, and Claude Code. Registry-backed project paths are available for 73 more coding agents.

Move repeated instructions into code

A release skill often starts as prose:

Run the tests. Review the release. Stop if the review finds a critical issue. Ask me before publishing. Publish the package, then verify the registry.

Yield makes the order and stopping rules executable. The coding agent reviews what the deterministic check may miss; the program still owns the gate, approval, publish, and verification steps:

import { defineSkill } from "@operatorstack/yield"

type Review = { critical: number; summary: string }

defineSkill((ctx) => {
  // Yield runs commands itself and records their output and exit status.
  const tests = ctx.runCommand("test", "echo tests-ok", 300)

  // A failed requirement stops the workflow and keeps its evidence.
  ctx.require(tests.exit_code === 0, "the test command succeeds", tests)

  // Review gives TypeScript its compile-time type. The JSON schema checks the
  // coding agent's response at runtime before this workflow can continue.
  const review = ctx.agentTask<Review>(
    "review-release",
    "Review this release for correctness problems that the test command may miss. Report critical findings and a short summary.",
    { stdout: tests.stdout, stderr: tests.stderr },
    {
      type: "object",
      required: ["critical", "summary"],
      properties: {
        critical: { type: "integer", minimum: 0 },
        summary: { type: "string", minLength: 1 },
      },
    },
  )
  ctx.require(review.critical === 0, "the review has no critical findings", review)

  // Yield emits these fixed choices. A supported host may show native controls;
  // otherwise the coding agent asks through its normal interface.
  const approval = ctx.askUser("approve-publish", "Publish this package?", [
    { value: "yes", label: "Publish" },
    { value: "no", label: "Stop" },
  ])
  if (approval !== "yes") ctx.refused("the operator declined publication")

  // Publishing cannot start before approval. Verification is a separate step,
  // so completion requires evidence that the registry contains the release.
  const publish = ctx.runCommand("publish", "echo publish-ok", 600)
  ctx.require(publish.exit_code === 0, "the publish command succeeds", publish)

  const registry = ctx.runCommand("verify-registry", "echo registry-ok", 300)
  ctx.require(registry.exit_code === 0, "the registry contains the release", registry)

  return { published: true, summary: review.summary }
})

The example uses harmless commands so its fixture can run in any checkout. Replace them with the test, publish, and registry commands for your project. The complete tested source is in examples/release-checklist.

Yield releases Yield

This repository uses its own exact published SDK for stable releases. The canonical release-yield workflow dispatches the protected GitHub release controller, records the human authorization, waits through the npm, PyPI, and crates.io environments, and verifies the Go module and final GitHub release. It never publishes from the developer's computer.

The workflow starts by choosing Dry run only or Prepare release. Minor and major intent requires a separate confirmation before any GitHub operation. Dry-run-only returns the immutable version, tag, source SHA, Changesets, and workflow URL without publishing.

Every newly published canary runs the same contract tests in an isolated CI lane. Stable release execution remains pinned to an exact public version.

Create a workflow

1. Install Yield

Install the TypeScript SDK and its repository-local CLI in your project:

npm install --save-exact @operatorstack/yield
npm exec -- yskill --version

Public npm releases use trusted publishing. The initializer, SDK, and six runtime packages include SLSA v1 provenance.

2. Create the workflow

npm exec -- yskill init skills/release \
  --language typescript \
  --description "Test, review, approve, publish, and verify a package."

The command creates one canonical workflow inside your repository:

skills/
└── release/
    ├── SKILL.md
    ├── fixtures/
    │   ├── responses.json
    │   └── test.json
    ├── main.ts
    ├── package.json
    └── skill.json

Replace the starter in skills/release/main.ts with your workflow. Update skills/release/fixtures/responses.json with deterministic answers for agent and user operations.

3. Test the workflow

npm exec -- yskill doctor skills/release --test

This 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 is the discovery step. This command detects installed verified agents and writes a small adapter for each one:

npm exec -- yskill register skills/release

Select verified agents explicitly when you do not want automatic detection:

npm exec -- yskill register skills/release \
  --agent cursor,codex,claude-code

If all three are selected, Yield creates these generated files:

.cursor/skills/release/SKILL.md   # Cursor
.agents/skills/release/SKILL.md   # Codex
.claude/skills/release/SKILL.md   # Claude Code

The adapters point back to skills/release. 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:

/release

Otherwise, ask the agent in plain language:

Use the release skill to publish this package.

The agent follows the generated adapter, runs the canonical workflow in skills/release, and asks for each required agent or user response.

Optional: install the developer helper

Package installation does not create skills or coding-agent adapters. After you understand the manual flow above, you can explicitly install the guided helper:

Language Command
TypeScript npm exec -- yskill helper install --language typescript
Python python -m yieldskill helper install --language python
Rust cargo install yieldskill --root .yield --locked, then .yield/bin/yskill helper install --root . --language rust
Go go run github.com/operatorstack/yield/cmd/yskill@latest helper install --root . --language go

The installer first prints one ordered plan with resolved paths, dependency preparation, workflow testing, registration for the selected agents, and final adapter verification. Review it before answering Apply this helper install plan? [y/N].

The helper is installed as skills/yield-workflow-builder. It can explain, create, convert, check, repair, upgrade, and register skill workflows. Before a mutation it shows the summary, relevant primitives, exact files, and exact commands, then asks for approval. Restart your coding agent after installation.

yskill bootstrap and npm create @operatorstack/yield@latest remain compatibility aliases for yskill helper install.

How Yield runs and resumes

  1. Your workflow 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 resumes from the journal and replays the program to the next operation.

If replay produces a different operation, the run fails instead of silently forking. Every side effect crosses one of these primitives:

Primitive Purpose
runCommand Execute a command and record its exit code and output.
agentTask Delegate one bounded judgment; an optional schema validates the result.
askUser Request an explicit human decision.
require Bind a required claim to recorded evidence.
blocked / refused Stop honestly when work cannot or must not continue.

See the primitive guides and runtime reference for the full contract.

Languages and coding agents

All four SDKs implement the same execution contract. The conformance suite runs the same program in every language and compares observable behavior.

Language SDK Example
TypeScript @operatorstack/yield release-checklist
Python yieldskill env-doctor
Go github.com/operatorstack/yield/sdk/yield investigate
Rust yieldskill data-migration

Cursor, Codex, and Claude Code are verified integrations. Yield also includes registry-backed project paths for 73 more coding agents. Those paths support explicit registration; they are not presented as end-to-end verified.

Run yskill agents to inspect the pinned registry and available project paths.

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 an agent performed only the requested work. runCommand is different: the Yield CLI executes the command, so the recorded exit code and output are observed facts.

Yield is not a daemon, hosted runtime, workflow DSL, marketplace, new agent loop, multi-agent orchestrator, or security sandbox.

Documentation and development

Run the main checks from the repository root:

npm run format:check
go test ./...
npm run test:release

Run npm run format to format the supported source files. Install the repository npm dependencies first. The command also needs Go, Rust, and uvx. Generated files and evaluation sources with byte-bound receipts stay unchanged until their generators or evaluations run.

The example library contains ten common workflows in all four SDKs, including code review, failure investigation, CI repair, dependency updates, database migration, security audit, and package release.

Yield is MIT licensed. This repository contains its canonical source and versioned technical documentation.