docs(yield): define skill workflows

labs/22-yield/README.md

@@ -1,35 +1,33 @@
 # Lab 22 — 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.
+A skill workflow is a portable, executable process that combines agent skills
+with deterministic code, state, and verification.
 
-A skill keeps its thin `SKILL.md` (so it works wherever skills work today)
-and moves its control flow — order, branching, retries, approval, state,
-completion — into a deterministic Go program. The model keeps reasoning,
-exploration, editing, and judgment. No daemon, no new agent loop, no host
-integration: the agent only runs a CLI and follows envelopes.
+The canonical skill workflow stays beside the repository code and language
+dependencies it uses. Generated `SKILL.md` adapters let each coding agent
+discover it. The model keeps reasoning, exploration, editing, and judgment;
+normal code owns order, branching, retries, approval, state, and completion.
 
 ## Execution model
 
 Deterministic re-execution (no resumable coroutines needed): on every
-run/resume, `yskill` re-executes the skill program from the top, feeding
+run/resume, `yskill` re-executes the 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 exits. A replayed step that
 produces a different operation than the journal recorded is a divergence
 and fails the run loudly — it never silently forks.
 
 Two processes:
 
-- **`yskill` (supervisor)** — owns the append-only run log
+- **`yskill` (Yield runtime)** — owns the append-only run log
   (`.yield/runs/<id>.jsonl`), sequence and digest binding, response
   validation, and every refusal. `run_command` operations are executed by
   yskill itself, so command results enter the log as observed fact rather
   than the agent's transcription.
-- **skill program (subprocess)** — an ordinary Go `main` using
-  `yield/sdk/yield`; every side effect crosses a yielded primitive
+- **skill workflow (subprocess)** — an ordinary program using one Yield SDK;
+  the Go form uses `yield/sdk/yield`. Every side effect crosses a yielded primitive
   (`AskUser`, `AgentTask`, `RunCommand`, `Require`, `Complete`, plus the
   `Blocked`/`Refused` terminals).
 
@@ -42,18 +40,18 @@ yield/
 ├── internal/protocol/     yield.v1 envelopes, digests, schema validation (bound to ir/ by test)
 ├── internal/runlog/       append-only JSONL event log
 ├── internal/guard/        every refusal: stale/dup/wrong-run/schema/digest/unproven
-├── internal/engine/       supervisor: subprocess execution, command evidence, terminals
+├── internal/engine/       runtime: subprocess execution, command evidence, terminals
 ├── internal/conformance/  the SAME program in 4 languages; identical observable traces
 ├── sdk/yield/             Go SDK          — examples/investigate
 ├── sdk/typescript/        TypeScript SDK  — examples/release-checklist (node main.ts)
 ├── sdk/python/            Python SDK      — examples/env-doctor (import yieldskill)
 ├── sdk/rust/              Rust SDK        — examples/data-migration (crate yieldskill)
-├── examples/library/      10 workflows × 4 languages, all fixture-tested
+├── examples/library/      10 skill workflows × 4 languages, all fixture-tested
 └── docs/locus*            certified lifecycle + SDK-contract models, verdicts, discharge
 ```
 
 Skills declare their runner in `skill.json` (`{"run": ["python3", "main.py"]}`);
-a bare `main.go` falls back to `go run .`. One supervisor drives all four
+a bare `main.go` falls back to `go run .`. One Yield runtime drives all four
 languages because they all speak the yield.v1 IR — the SDK execution
 contract is Locus-certified (trace-refinement) and the in-SDK per-step
 divergence check is a *decided* design comparison, not a convention

labs/22-yield/distribution/release-notes/2026-08-02-skill-workflows.md

@@ -0,0 +1,8 @@
+# Skill workflows for coding agents
+
+- Name the public category: a skill workflow combines agent skills with code,
+  checks, state, and human input.
+- Separate the canonical workflow users edit from generated agent adapters.
+- Align the README, quickstart, examples, SDK package descriptions, reference
+  docs, and CLI help around the same terms.
+- Keep runtime APIs and the `yield.v1` execution contract unchanged.

labs/22-yield/public-readme/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
 ```

labs/22-yield/yield/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

labs/22-yield/yield/docs/README.md

@@ -1,28 +1,35 @@
 # Yield documentation
 
-You already know the workflow. You may be repeating it in a prompt:
+You already know the skill workflow. You may be repeating it in a prompt:
 
 > Run the checks. Review the diff. Stop if anything critical remains. Ask me
 > before publishing. If the session ends, start again without losing our place.
 
-Yield lets you keep the useful words and put the order in normal code. The
-coding agent still investigates, reviews, edits, and explains. Your program
+Yield lets you keep the useful words and put the repeatable flow in normal
+code. The coding agent still investigates, reviews, edits, and explains. Your program
 decides which operation comes next, what evidence must exist, and when the run
 is finished.
 
+A **skill workflow** is a portable, executable process that combines agent
+skills with deterministic code, state, and verification. The canonical
+workflow is the source you edit. Generated adapters let coding agents discover
+and start it.
+
 ## Start here
 
-1. [Build and run your first skill](quickstart.md) — a TypeScript workflow you
-   can test in about ten minutes.
-2. [Register it with your coding agents](agent-setup.md) — keep one workflow
+1. [Understand skill workflows](skill-workflows.md) — the canonical workflow,
+   generated adapter, and execution boundary.
+2. [Build and run your first skill workflow](quickstart.md) — a TypeScript
+   workflow you can test in about ten minutes.
+3. [Register it with your coding agents](agent-setup.md) — keep one workflow
    and generate the small discovery adapters each agent needs.
-3. [Learn the primitives](primitives/README.md) — commands, model work, human
+4. [Learn the primitives](primitives/README.md) — commands, model work, human
    input, gates, and honest outcomes.
-4. [Follow a complete tutorial](tutorials/README.md) — review, approval,
+5. [Follow a complete tutorial](tutorials/README.md) — review, approval,
    environment repair, bounded debugging, and migration.
-5. [Browse the examples](examples.md) — working programs in Go, TypeScript,
-   Python, and Rust.
-6. [Convert an existing prose skill](convert-existing-skill.md) — use Yield's
+6. [Browse the examples](examples.md) — working skill workflows in Go,
+   TypeScript, Python, and Rust.
+7. [Convert an existing prose skill](convert-existing-skill.md) — use Yield's
    verified converter after you understand one ordinary workflow.
 
 ## The split to remember
@@ -42,6 +49,7 @@ next unanswered operation.
 
 ## Reference
 
+- [Skill workflow concepts](skill-workflows.md)
 - [CLI commands](reference/cli.md)
 - [Coding-agent registration](agent-setup.md)
 - [Run, pause, resume, and replay](reference/execution-model.md)

labs/22-yield/yield/docs/agent-setup.md

@@ -1,10 +1,10 @@
-# Use one Yield workflow from your coding agents
+# Run one skill workflow from your coding agents
 
-Yield workflows belong beside the application and language dependencies they
-use. `yskill register` creates only the small `SKILL.md` adapters required for
-agent discovery.
+The canonical skill workflow belongs beside the application and language
+dependencies it uses. `yskill register` creates only the small `SKILL.md`
+adapters required for agent discovery.
 
-## Register an existing workflow
+## Register an existing skill workflow
 
 ```bash
 # Detect installed verified agents
@@ -39,8 +39,9 @@ snapshot of the open `vercel-labs/skills` registry and are labelled
 `registry`: path generation is tested, but the product itself has not been run
 end to end by Yield.
 
-Generated adapters are safe to commit. Regenerate them after changing the
-canonical workflow. Yield refuses to overwrite a user-owned skill with the
+Generated adapters are safe to commit. They are disposable discovery files,
+not copies of the workflow. Regenerate them after changing the canonical skill
+workflow. Yield refuses to overwrite a user-owned skill with the
 same name. Names must also be unique across languages because coding agents use
 one project-level skill namespace.
 
@@ -50,29 +51,29 @@ Replace the bracketed values, then paste this into the coding agent already
 open in the project:
 
 ```text
-Set up a Yield workflow named [skill-name] in skills/[skill-name].
+Set up a Yield skill workflow named [skill-name] in skills/[skill-name].
 
 1. Detect whether this project uses TypeScript, Python, Go, or Rust.
 2. Install that language's Yield package using the project's existing package
    manager. Do not install a second global runtime.
 3. Run yskill init with the detected language and this description:
    [what the workflow does and when it should run]
-4. Replace the starter program and fixture with the requested workflow. The
+4. Replace the starter program and fixture with the requested skill workflow. The
    starter is intentionally blocked and must not pass tests unchanged.
 5. Run yskill doctor with --test before registration.
-6. Keep the workflow beside the project's language dependencies.
+6. Keep the canonical workflow beside the project's language dependencies.
 7. Run yskill register for the coding agent you are currently using.
 8. Use the launcher from the installed language package for every yskill
    command: npm exec -- yskill, python -m yieldskill, or yskill.
 9. Run yskill doctor with --agent and --test.
 10. Report the commands, generated adapter path, and every changed file.
 
-Do not move the workflow into an agent discovery directory and do not copy its
+Do not move the skill workflow into an agent discovery directory and do not copy its
 dependencies into an adapter.
 
 ## Questions and agent results
 
-Yield emits a typed operation. The coding agent may show that operation using
+The skill workflow emits a typed operation. The coding agent may show that operation using
 its native question UI. Yield does not render the UI. After collecting an
 answer, the adapter uses `yskill respond`; it does not create `response.json`.