operatorstack · operator-stack-publisher · Aug 2, 2026 · Aug 2, 2026
diff --git a/README.md b/README.md
@@ -1,20 +1,26 @@
 # Yield
 
-Programmable skills for coding agents. **Turn `SKILL.md` workflows into
-resumable programs.**
+**Write one skill workflow. Run it from your coding agents.**
 
-> The skill yields the next typed operation. The coding agent performs it
-> and resumes the skill.
+Skill workflows are portable, executable processes that combine agent skills
+with deterministic code, state, and verification.
 
-Write control flow in TypeScript, Python, Go, or Rust. Yield user
-questions, agent tasks, and commands to the coding agent. Resume from the
-result. No custom agent runtime required — the agent only runs a CLI and
-follows envelopes.
+Write the workflow in TypeScript, Python, Go, or Rust. Combine agent judgment,
+real commands, human input, checks, and saved state. Yield generates the small
+adapter each coding agent expects.
 
-A skill keeps its thin `SKILL.md` (so it works wherever skills work today)
-and moves the part prose loses under context pressure — order, branching,
-retries, approval, state, completion — into a deterministic program. The
-model keeps reasoning, exploration, editing, and judgment.
+The split is small:
+
+| term | meaning |
+|---|---|
+| **skill** | one reusable capability |
+| **workflow** | order, branches, checks, and saved state |
+| **skill workflow** | an executable composition of skills, code, commands, and human input |
+| **adapter** | a generated `SKILL.md` that lets one coding agent discover the workflow |
+
+The canonical skill workflow stays beside your code. Generated adapters are
+disposable. The model keeps reasoning, exploration, editing, and judgment;
+normal code owns the repeatable control flow.
 
 ## Install
 
@@ -41,9 +47,9 @@ cargo install yieldskill \
 yskill --version
 ```
 
-## Create and register a workflow
+## Create and register a skill workflow
 
-Keep the real workflow beside the language dependencies it uses. Yield writes
+Keep the canonical workflow beside the language dependencies it uses. Yield writes
 small adapters into each coding agent's project skill directory; it does not
 copy the workflow or install its dependencies again.
 
@@ -53,20 +59,22 @@ npm exec -- yskill init skills/review \
   --language typescript \
   --description "Review changed code when the user wants a branch checked before shipping."
 
-# Detect installed agents, or pass --agent cursor,codex,claude-code
-npm exec -- yskill register skills/review
+# Replace the intentionally incomplete starter and fixture, then check it.
 npm exec -- yskill doctor skills/review --test
+
+# Detect installed agents, or pass --agent cursor,codex,claude-code.
+npm exec -- yskill register skills/review
 ```
 
 `yskill agents` lists the available agent IDs and project paths. Cursor,
 Codex, and Claude Code are verified. Remaining entries support explicit path
 registration from the pinned open registry; they are not presented as
 end-to-end verified.
 
-## How it works
+## How a skill workflow runs
 
 Deterministic re-execution: on every run/resume, `yskill` re-executes the
-skill program from the top, feeding recorded responses back in order. At
+skill workflow from the top, feeding recorded responses back in order. At
 the first unanswered operation the SDK emits a `yield.v1` request envelope
 and the process exits — no daemon. A replayed step that produces a
 different operation than the journal recorded is a divergence and fails
@@ -76,7 +84,7 @@ the run loudly; it never silently forks.
   (`.yield/runs/<id>.jsonl`), sequence and digest binding, response
   validation, and every refusal (stale, duplicate, wrong-run,
   schema-invalid, digest-mismatch, completion-unproven).
-- **The skill program** is an ordinary Go `main` using `sdk/yield`; every
+- **The skill workflow** is an ordinary program using one Yield SDK; every
   side effect crosses a yielded primitive.
 
 Five primitives, two exits:
@@ -89,13 +97,13 @@ Five primitives, two exits:
 | `Require` | a claim bound to evidence; failure makes completion structurally unreachable |
 | `Complete` / `Blocked` / `Refused` | honest terminals, always recorded |
 
-## Four languages, one protocol
+## Four languages, one execution contract
 
-Write the skill program in Go, TypeScript, Python, or Rust — the
-runtime doesn't care. Every SDK implements the same certified
-execution contract over the canonical `ir/yield.v1` schemas, and the
-conformance suite (`internal/conformance`) runs the *same program* in all
-four languages and asserts identical observable protocol behavior.
+Write the skill workflow in Go, TypeScript, Python, or Rust. Every SDK
+implements the same certified execution contract, and the conformance suite
+(`internal/conformance`) runs the same program in all four languages and
+asserts identical observable behavior. The language-neutral schemas are
+documented in the [runtime reference](docs/reference/sdk-parity.md).
 
 | language | SDK | example |
 |---|---|---|
@@ -107,28 +115,29 @@ four languages and asserts identical observable protocol behavior.
 Skills declare their language and runner in `skill.json`:
 `{"version": 1, "language": "typescript", "run": ["node", "main.ts"]}`.
 
-## Ten workflows, every language
+## Ten skill workflows, every language
 
-The [example library](examples/library/) recreates ten common coding-agent
-workflows independently in all four SDKs: branch review, failure
+The [example library](examples/library/) implements ten common skill workflows
+independently in all four SDKs: branch review, failure
 investigation, web QA, package release, issue triage, CI repair, dependency
 upgrade, database migration, security audit, and iOS publishing.
 
-Each language has the same workflow, a thin `SKILL.md`, and a scripted
+Each language has the same skill workflow, a thin adapter, and a scripted
 fixture. Start from the work you already do instead of starting from a
 framework tutorial.
 
 ## Documentation
 
-Start with the [ten-minute TypeScript quickstart](docs/quickstart.md), then
-use the documentation by job:
+Start with [what a skill workflow is](docs/skill-workflows.md), then build one
+with the [ten-minute TypeScript quickstart](docs/quickstart.md). Continue with
+the documentation for your job:
 
 - [primitive guides](docs/primitives/README.md) — commands, model work,
   human input, evidence gates, and outcomes;
 - [tutorials](docs/tutorials/README.md) — review, approval, environment
   repair, bounded debugging, and migration;
 - [examples](docs/examples.md) — working programs in all four languages;
-- [coding-agent setup](docs/agent-setup.md) — register one workflow with the
+- [coding-agent setup](docs/agent-setup.md) — register one skill workflow with the
   agents used by the project;
 - [evaluations](evals/README.md) — first-party workflow conformance and runtime
   invariant results, including the exact claim boundary;
@@ -151,7 +160,7 @@ YSKILL="$PWD/yskill" bash ./examples/library/test-all.sh
 ./yskill test examples/env-doctor         # Python 3.10+
 ./yskill test examples/data-migration     # Rust (cargo)
 ./yskill run  examples/investigate        # prints the first operation envelope
-./yskill init my-skill --description "Run this workflow when ..."
+./yskill init my-skill --description "Run this skill workflow when ..."
 ./yskill register my-skill --agent codex # write a thin project adapter
 ./yskill doctor my-skill --agent codex   # verify package + adapter wiring
 ```

diff --git a/UPSTREAM.json b/UPSTREAM.json
@@ -2,20 +2,20 @@
   "files": {
     ".gitignore": "803c5f79d6da7f2c5a1dc0ce27c53b8e5c059309b165782831c4c472af058a4c",
     "LICENSE": "fff261ce507eabd57666c283a621f33e183a3aedebda04c4ecbc6309a62f5edf",
-    "README.md": "da05508b2bae74f3cea3b88945a0346b8f454739a134ba412603fab42530f099",
+    "README.md": "6f6c0266295ee7c60fadb134896af498917395b846eb71fda7b104fe2599a536",
     "cmd/yskill/agents.go": "386b04a9eefd3ee4d0e30dc1398abefd1b3d8f3fb129bb3fc389794a062967a1",
     "cmd/yskill/agents_test.go": "144d91a1b0dff4eb1d523c49a8e9f4e300a1864c493835c549cd16c6b3be8caa",
-    "cmd/yskill/main.go": "3e516a829e39d79ced5c7048ef899c5110491db074996742e4a75e490bd185b7",
+    "cmd/yskill/main.go": "5eefea8fdd3e040a940bde80aac793fb97c61c18586bd993dab0395f57e5a81f",
     "cmd/yskill/main_test.go": "c0eb629add322c920834af069d22698466884333bde3b6467219230211cb065f",
     "cmd/yskill/registry/README.md": "fab385921ee7972f76deb94a3b7ae41184735598ea4145c9d8ccdde2c2b876c4",
     "cmd/yskill/registry/VERCEL_SKILLS_LICENSE": "779258e329008bdb9330e6c1daad644ff867f164d11c4cc4404350479f3e92ee",
     "cmd/yskill/registry/agents.json": "6edfee31cdc0390516adbb107fc97fc3531eb02e1a28b9d62b5b86fdccaed7c1",
     "cmd/yskill/scaffold.go": "3841fb9c769b0be024355cdf4063c068b4cc8dd918bc2bbef10a7ff7bcbf786e",
     "cmd/yskill/skillmeta.go": "12b0c25689bf825d676404af7b3fb74fb92db3d9e222d4e553d8800d86aea45e",
-    "docs/README.md": "63bfd77584e84be09fe55bfcf2e1792d67d9690f9ebf302e6756a77c4c0cfbf5",
-    "docs/agent-setup.md": "2c0899154fcc17e8144e2e056daf0bb1437d3089f4064b478f9f242ff7920ef9",
+    "docs/README.md": "b4103bc38ca5b3b313d6cc7eae5f11276c03a8bd6123cfa101cb7372ff43fa72",
+    "docs/agent-setup.md": "d34804f3ab6cab940e6f1e9de0c01086b8ec34acb52fe090b7f78bcb3952d91c",
     "docs/convert-existing-skill.md": "0dd538e908a1f2d3a1958e4b2cc1efede2a8e7a73341e32c1a75fec69a9acb8a",
-    "docs/examples.md": "3c19bacae7ec7b31bf93417e61d01cd1872f26228fedf0ed6decfce7c41ed274",
+    "docs/examples.md": "f6ef194f1d321692873b5cf35751f369d8215084c5a754b4a6725480ab9b2e37",
     "docs/locus-conformance.md": "a71fd5a72678dcad344afc71cd7a788090ef008a8e5e82d925da5a3db41af6a0",
     "docs/locus-converter.md": "b8d1bdb63cb0283ace524f572fb13f0d1cb535b130c5ea3e112d2efae55a8681",
     "docs/locus-yield.md": "c29d0c5801f32591828fc348385fb25c1850b39afc22770098eae0614fc3a417",
@@ -31,25 +31,26 @@
     "docs/locus/yield-diag-correlated.json": "9427e2135066d6a89999178b3c6467799153ceb155543e3d9777b39a27193c73",
     "docs/locus/yield-diag-portable.json": "71f2880721196f42c82cc152c49dff6d0fd4ac71a84586c468f66442bc305051",
     "docs/locus/yield-protocol.json": "82c3490000357d66bc1f35623176a9b0279800340684047d46696d2eb43677d2",
-    "docs/primitives/README.md": "4181e5a4115fff00edef8b0266aa1ecb1bd3443acd0e0272246e650efd13acc9",
+    "docs/primitives/README.md": "fac74f3b860746c17d56bc55b07a2c6ddcce46d2c2cd471f237baa64b3bdeaa3",
     "docs/primitives/agent-task.md": "89ec69ec7d83c4b78b8d71ee877dfc2b5cabb4fe5bee3f2ee1a524da40349b2d",
     "docs/primitives/ask-user.md": "e76e59b5cb9105d1c55edb4d250162aeb4afe3aa424aee305fff476fc49fdf6e",
     "docs/primitives/outcomes.md": "a584976fada6af3772894736e686f5deb466d3cc8fd1ecacf49f6b9042d6a232",
     "docs/primitives/require.md": "1ea8c3a9ea11aa61e2baee01cf83fca8c872e846a47d7ef230cf6b76d04c90d8",
     "docs/primitives/run-command.md": "af9bcc617f90fd2ee0086aeabb5c98854542efe81636a020699c2f688f8b3b8c",
-    "docs/quickstart.md": "4f76f73d9b622eecbeed04300a5ad1b8c4f7b611e7ed72ed6b58eff1a44142b1",
-    "docs/reference/cli.md": "f3469fadc7a461745008fa792515eb5df771084ed175a17868d8fdcecbc9dd5d",
-    "docs/reference/execution-model.md": "b221051da602953ebd9e1cc5e7f848de8f59721b36a1793211e6374745f74507",
+    "docs/quickstart.md": "b16fd9933b8edec8765fee3b47e63393345ea439a4f5c3d1f8d7202fd13a70e1",
+    "docs/reference/cli.md": "ab3ed6eb9de3469d41af27a721018c111cb9767f8c500a667d560155572af425",
+    "docs/reference/execution-model.md": "58365a7870a081f4ed9e9ba144aae77aa5a1d8676d2bbf6979483be4a06eca80",
     "docs/reference/guarantees.md": "fce2006ad46a83c4ae34d221a83d68bc06a776e7c4f54d938bdcdac91977aa50",
     "docs/reference/sdk-parity.md": "b8c3d6d6efad246b9212db760bb72cba7182b04da321cfd667783000ae75f733",
-    "docs/tutorials/README.md": "d574e869782a1a5e39113b275744cb8cd74b7f63f69c8e30520559d32c21f8d1",
+    "docs/skill-workflows.md": "c0049f6b7db00fc45f15d649e56e381962ddf637dd5d20309a4f79801a28d80d",
+    "docs/tutorials/README.md": "f35641cab5aa9739b22a7f9c75a5fe7966b26f492879a70545c4cb6a780129b3",
     "docs/tutorials/approval.md": "d0144288e12488627fce085d3053b1c9b79cc1dac2d45157c214062de3375a9c",
     "docs/tutorials/bounded-debugging.md": "903b876fb13fa5bff6789c500f56c1b97c5ae1bc0059147d845a8f327d553340",
     "docs/tutorials/code-review.md": "275d9be9eeb8b10c840a58cb861258803af7629a54c4379d0d0336a9e8678898",
     "docs/tutorials/data-migration.md": "6699fc47cda84c4f46a3703ca4a69bcced7cc4a9df339a308e807ea3a99578bd",
     "docs/tutorials/environment-repair.md": "289c9b261e3768c2c58d60d9ef7a09e85f89038438a08febb4b9c12ebada88d1",
     "evals/.gitignore": "0d5020173666118bafe31c857b96aa325809f41d159ca51324ceaf239e043347",
-    "evals/README.md": "db8461f9a2cc17cde6597149a16fd68b4450985b4f4b40b097b1e7059d2cbe34",
+    "evals/README.md": "e8972b1f0bdc79df96f3bfdd81017462187b122221ab66c423f6d55a33e0fffd",
     "evals/agent/README.md": "7936e06915bfc1ae755a9529d4a6c632a8d866b9c804e95af49a66cad6eb5038",
     "evals/agent/cases.json": "98ae0ab3f099bd957739368de7bdb5b8b43997776ed6a11e406f81fd523c3130",
     "evals/agent/fixtures/long/SKILL.md": "8826f89f40c17085c92d246043e3794565a230d578cc07de3b5f3c26ba661efe",
@@ -66,7 +67,7 @@
     "evals/package.json": "84ac7bd7d1c0d1db2233dab54754296195b267e5e907d9f6c402d0d44d569adb",
     "evals/results/README.md": "65b74bfab83dfc51fc5b8a3a4824c37b722fb3a358a5dcfb217dc2af199f4801",
     "evals/results/latest-agent.json": "1484174819ae29bbcffeb615036fa165518669525e6d664123f6a38ca3614b69",
-    "evals/results/latest.json": "80281e8fc80cc39e03168ff6052986a6c896a06ef776318cbb832996d7386b0d",
+    "evals/results/latest.json": "4a62df2905d90a948c62b4dc0711a0d22e6b4448787f3f8be86c4f006421b531",
     "evals/scripts/run.mjs": "17a62cd0f7fda73d84a9bfa21c9c3253ba52a4a23eece09523cfea244e3f9940",
     "evals/scripts/validate.mjs": "42d51ea75f9418e45dd1797d1fe02cbc046752d3e3c37d41bc8d3a47d5865d4d",
     "examples/convert-skill/SKILL.md": "e6376f34365d4ac030d316db55e91f0c606a501668099f4ecf1e27d43ec806a2",
@@ -87,7 +88,7 @@
     "examples/investigate/fixtures/responses.json": "b17bde7104427926d120d14e2f989186a1834b78a0a039384f34a2847cbd787e",
     "examples/investigate/main.go": "2e1a21e347791a0ecfc740f862631e7e6af6d518fb26fc4b0062d9170bcae44b",
     "examples/investigate/skill.json": "cd9f5e46c623597dad1224735a03d1363b8a426f541bd00321752d1cf7d9b116",
-    "examples/library/README.md": "aa8fbdd41179d866b18763784d9396516cc88f858d95f0de113e676a4dc33e9f",
+    "examples/library/README.md": "e3b87f40a42fa7fe86e882d069be5a38411a8ae1b469aa86823c5e650ad24507",
     "examples/library/catalog.json": "1572538febe5f6cb610ac68df3fe5be5ee1aff1cf3e83398ab0d310d37088f82",
     "examples/library/go/audit-security/SKILL.md": "3ca2a8ffdb4504854cc45879e4c8bb795fc073560c1994eaf20f3d42d00d62f1",
     "examples/library/go/audit-security/fixtures/responses.json": "d738404c2e2912705de936c5948c4520ae4145bae0068d478f7689aae9aaedaa",
@@ -305,26 +306,27 @@
     "release-notes/2026-08-01-remove-stray-analysis-traces.md": "0567f78ee97ffd23b3f26b5c39606e9ff6659c50a3fdef04ed9b3aa86cfa99af",
     "release-notes/2026-08-02-cross-agent-registration.md": "8f4296fae36468bda08370bad8d13b7fc1e893b682f8c73015311ab01ace853f",
     "release-notes/2026-08-02-dx-hardening.md": "801d85ad760545140415000a95cbd6a681c32462f0578c1ac1ce802893bee303",
-    "sdk/python/README.md": "415fde10711137e0baf30874844a0482cebbf60fb59cb751eba56dedfebb0ce8",
-    "sdk/python/pyproject.toml": "142249ed41c8ea58560e2b54400a2a778d2ac4b327112b2909ded69d9bd99bdb",
+    "release-notes/2026-08-02-skill-workflows.md": "8cd0cded1922387ef8e81b3e084c12e440f729aa778672f9ec91ffa153df5297",
+    "sdk/python/README.md": "a40fb44353cfa2633b7307280c501d490a815aa00c4ba5d8b86c5a6e778742f4",
+    "sdk/python/pyproject.toml": "0a36d0a22a29da6b8c42e3a5a91aed1b6f6d0813712a9e582ab08e8ce4290de6",
     "sdk/python/test_cli.py": "b7a2fe9a72299aa86f6012129e00f9c2dc0f6e5c29241373fb956321fae5f0b4",
     "sdk/python/yieldskill/__init__.py": "c43dbb2a25ed7e8537521561a16e2e5fc7921d60f913b22ac298255bd44fe60e",
     "sdk/python/yieldskill/__main__.py": "2f2978db2ba5bf8034466902e0c0f5fa61d0961b262d776598ba0d9bb47d6b62",
     "sdk/python/yieldskill/_cli.py": "ab8978c5c053ba3007ba38ae22038a869cb0a5222762edd0fbea749623024b66",
-    "sdk/rust/Cargo.toml": "39c19c2b7800c9b9d1f7387548f56ad3feb8c7712255e101d967bab82466fe8b",
+    "sdk/rust/Cargo.toml": "da29a554401a316f6a0e7ba53d166f4c3741ac9aefe1e3f2d66af1bfa3a2d88a",
     "sdk/rust/src/lib.rs": "581882dca50cf4e27a8f2e05b013b2bc091802b6a20d89d58ffbcdf5c23372a7",
     "sdk/typescript/bin/runtime.mjs": "909da102e8ed8ccc917cd17d88acc65869a0a2bdb6f875f76d763383999a2b57",
     "sdk/typescript/bin/runtime.test.mjs": "db9c2dc1054d7f03139d69d3ffdb1e6fe5b65a71f4bdcca50fdefb2562831a2b",
     "sdk/typescript/bin/yskill.mjs": "4ac8b13afc26fdc5b9192e6443dc121b83c7abfb9a4b80768f8344b8faaa4197",
-    "sdk/typescript/package.json": "8a2b618ac94a00ef8a85ce2e97112b97db8a90505539b97f6b4afd4d383d6df5",
+    "sdk/typescript/package.json": "b8805c31ce1bbf4b063efa5f69cfad8e1b0ec402607d7afceea6398057d95a6e",
     "sdk/typescript/scripts/build.mjs": "1ba086bbdddb61226f3b6363e1fda0ffdd129ce90ea9da28ba71ecfb0f478e6d",
     "sdk/typescript/src/index.ts": "bc91d43b8f6698a3139fd482077942a22beab950db74164d94422ecb38631a0b",
     "sdk/yield/yield.go": "c9b4c7ab9a36b28f383e141fc084bd8b3b693c63c5a22722d8ae7ef3253f76ff"
   },
   "generator": "operatorstack/yield:project",
   "schema_version": 1,
   "source": {
-    "commit": "6d6739a7d41f276c2ee7619c588443a7f319b4a5",
+    "commit": "43b26da2291cfb8d8d3bb3cef8e3e45b4cc70270",
     "path": "labs/22-yield",
     "repository": "operatorstack/intelligence-flow"
   }

diff --git a/cmd/yskill/main.go b/cmd/yskill/main.go
@@ -24,17 +24,17 @@ import (
 	"github.com/operatorstack/yield/internal/runlog"
 )
 
-const usage = `yskill — turn SKILL.md workflows into resumable programs
+const usage = `yskill — run and resume skill workflows
 
 Usage:
-  yskill init <dir>                          scaffold a skill (or wrap an existing prose skill)
+  yskill init <dir>                          scaffold a skill workflow (or wrap an existing prose skill)
          [--language typescript|python|go|rust] [--description text]
-  yskill register <skill-dir>                expose one workflow to coding agents
+  yskill register <skill-dir>                expose one skill workflow to coding agents
          [--agent cursor,codex,...|auto] [--root repo]
-  yskill register-all <skills-dir>           expose every immediate workflow
+  yskill register-all <skills-dir>           expose every immediate skill workflow
          [--agent cursor,codex,...|auto] [--root repo] [--dry-run] [--prune]
   yskill agents                              list supported coding agents and paths
-  yskill doctor <skill-dir>                  check package, workflow, and adapters
+  yskill doctor <skill-dir>                  check package, skill workflow, and adapters
          [--agent cursor,codex,...|auto] [--root repo] [--test]
   yskill run <skill-dir> [--input file]      start a run; prints the first operation envelope
   yskill resume <run-id> --response file     feed a response; prints the next operation