stageflow 0.25.0 → 0.30.0

package/examples/generic-fan-in/README.md

@@ -0,0 +1,151 @@
+# generic-fan-in
+
+Dummy catalog for **manual operator-console testing** of generic multi-parent
+fan-in. `research` and `validation` run in parallel after `clarify`, pause on
+a free-text gate, then emit distinct payloads. `synthesize` waits for both and
+must copy `priorEnvelopesByStage` into `payload.received` so you can inspect
+what was handed across the join.
+
+Catalog wiring is outbound `route`: `research` and `validation` each list `to: synthesize`. Join rules (shipped runtime): the child waits until every parent is terminal; it **runs** if at least one parent succeeded (skipped siblings do not block); it stays **pending** if any parent failed (even when `on` lists `failed`); it force-skips only if every parent skipped. Including `failed` or `skipped` in `on:` opts that edge out of skip-cascade; it does not launch the Join from a failed parent.
+
+Wiring matches the fixture twins: [`diamond-fan-in.pipeline.yaml`](../../tests/fixtures/pipelines/diamond-fan-in.pipeline.yaml) and [`diamond-fan-in-accepted.pipeline.yaml`](../../tests/fixtures/pipelines/diamond-fan-in-accepted.pipeline.yaml). See [`docs/yaml-catalog.md#generic-fan-in`](../../docs/yaml-catalog.md#generic-fan-in).
+
+Two pipelines:
+
+| Pipeline | What it exercises |
+|----------|-------------------|
+| `generic-fan-in` | Default succeeded-only edges into `synthesize` |
+| `generic-fan-in-accepted` | Research edge `on: [succeeded, failed, skipped]` — still does **not** run the Join after research fails |
+
+## Prerequisites
+
+Use this repo's CLI (`npm run build` / `npm run dev`) or a Stageflow release
+that includes generic fan-in. A globally installed `sf` from npm may lag.
+
+- Node.js ≥ 20
+- From repo root: `npm run build` and `npm run ui:build`
+- Provider auth connected (`sf ui` → Settings → Providers). Stages use `cursor/auto`.
+
+Run state lives in `<repo>/.stageflow` even if you start the console from a subdirectory.
+
+## Terminal 1 — operator console
+
+From the **repository git root**:
+
+```bash
+npm run build
+npm run ui:build
+PI_CURSOR_SETTING_SOURCES=all STAGEFLOW_ACTIVITY_VERBOSE=1 node dist/cli.js ui
+```
+
+`npm run dev -- ui` runs the TypeScript CLI via tsx; use `node dist/cli.js ui` after `ui:build` so the console is served from `dist/ui`. Do not use a globally installed `sf` — Homebrew `sf` is an older build that cannot load this catalog.
+
+Open `http://127.0.0.1:3847`. Browse should list **generic-fan-in** and **generic-fan-in-accepted** (same names as the YAML files).
+
+## Terminal 2 — start a run (repo root)
+
+```bash
+node dist/cli.js validate --pipeline examples/generic-fan-in/generic-fan-in.pipeline.yaml --strict
+node dist/cli.js run \
+  --pipeline examples/generic-fan-in/generic-fan-in.pipeline.yaml \
+  --task examples/generic-fan-in/generic-fan-in.task.yaml
+```
+
+Exit code `2` means waiting on operator input. Leave this terminal; do the rest in the console.
+
+Start a **new run** for each scenario below. Do not reuse a finished run.
+
+---
+
+## Scenario A — both parents succeed (main envelope check)
+
+At **research**, answer exactly:
+
+```
+ok glaciers
+```
+
+At **validation**, answer exactly:
+
+```
+ok citations
+```
+
+Order of answers does not matter. `synthesize` starts only after both succeed.
+
+### What to verify
+
+1. Track is a diamond: `clarify` fans out to **research** and **validation**, then both wires inbound into **synthesize**.
+2. While only one parent is answered, select **synthesize**. It stays blocked. Copy / `blocked_by` lists the remaining parent, not only the first YAML parent.
+3. After `research` succeeds, select it and open **Files → Handoff envelope** (or `#/runs/<runId>/stages/research/envelope`). Payload should have `finding: glaciers`.
+4. After `validation` succeeds, open its handoff envelope. Payload should have `finding: citations`.
+5. **synthesize** runs once both parents succeeded. Open its handoff envelope. Confirm:
+   - `payload.received` has keys `research` then `validation` (YAML declaration order, not the order you answered).
+   - `received.research.finding` is `glaciers` and `received.validation.finding` is `citations`.
+   - Summary mentions both parent keys and their success status.
+6. From the repo root, you can also print the same records:
+
+```bash
+node dist/cli.js envelope get --run <runId> --stage research --json
+node dist/cli.js envelope get --run <runId> --stage validation --json
+node dist/cli.js envelope get --run <runId> --stage synthesize --json
+```
+
+`<runId>` is on the run detail URL (`#/runs/<runId>/…`) and in the run list.
+
+The synthesize payload is the join copy of `priorEnvelopesByStage`. That field is keyed; it is not a clone-list `priorEnvelopes` array, and `priorEnvelope` is null on the join.
+
+---
+
+## Scenario B — failed parent leaves the join pending
+
+New run of **generic-fan-in**. At research, answer:
+
+```
+fail
+```
+
+At validation, answer:
+
+```
+ok citations
+```
+
+### What to verify
+
+1. **research** is failed (open its handoff envelope — failure status, no finding).
+2. **validation** still finishes; its envelope is success with `citations`.
+3. **synthesize** stays **pending** (not skip-cascaded). A failed parent blocks the Join.
+4. Run outcome **failed**.
+5. Open synthesize anyway: there is no join envelope. The Join did not receive `priorEnvelopesByStage`.
+
+---
+
+## Scenario C — listing `failed` on `on:` still does not open the join
+
+New run:
+
+```bash
+node dist/cli.js run \
+  --pipeline examples/generic-fan-in/generic-fan-in-accepted.pipeline.yaml \
+  --task examples/generic-fan-in/generic-fan-in-accepted.task.yaml
+```
+
+At research, answer `fail`. At validation, answer `ok citations`.
+
+### What to verify
+
+1. **research** stays visibly **failed**. **validation** succeeds.
+2. **synthesize** stays **pending**. Listing `failed` on the research edge only opts that edge out of skip-cascade; it does not launch `synthesize`.
+3. Run outcome **failed**. Skipped siblings would not block a Join that has a succeeded parent; a **failed** parent still does.
+
+---
+
+## Envelope inspector (any scenario)
+
+On a completed stage, the first Files row is **Handoff envelope**. It opens the
+inspector (`#/runs/<runId>/stages/<stageId>/envelope`) with `summary`, `payload`,
+and artifact paths. Use that for the parent envelopes; use **synthesize** for the
+keyed join copy.
+
+CLI equivalent: `node dist/cli.js envelope get --run <runId> --stage <stageId> --json`.

package/examples/generic-fan-in/clarify.yaml

@@ -0,0 +1,18 @@
+id: clarify
+system_prompt: |
+  You are the root of a diamond pipeline. Call emit_stage_envelope exactly once.
+
+  Emit status success, artifacts [], payload { "brief": "diamond start" },
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - brief
+      properties:
+        brief:
+          type: string

package/examples/generic-fan-in/generic-fan-in-accepted.pipeline.yaml

@@ -0,0 +1,19 @@
+id: generic-fan-in-accepted
+stages:
+  - id: clarify
+    entry: true
+    route:
+      - to: research
+      - to: validation
+    uses: ./clarify.yaml
+  - id: research
+    route:
+      - to: synthesize
+        on: [succeeded, failed, skipped]
+    uses: ./research.yaml
+  - id: validation
+    route:
+      - to: synthesize
+    uses: ./validation.yaml
+  - id: synthesize
+    uses: ./synthesize.yaml

package/examples/generic-fan-in/generic-fan-in-accepted.task.yaml

@@ -0,0 +1,8 @@
+id: generic-fan-in-accepted
+goal: |
+  Dummy walkthrough for an accepted-failure diamond. research may succeed or
+  fail. validation must succeed. synthesize still runs when research fails and
+  must copy that failure envelope under received.research.
+context: |
+  Manual operator-console test. Reply fail at research and ok citations at
+  validation, then open synthesize to see the keyed failure + success pair.

package/examples/generic-fan-in/generic-fan-in.pipeline.yaml

@@ -0,0 +1,18 @@
+id: generic-fan-in
+stages:
+  - id: clarify
+    entry: true
+    route:
+      - to: research
+      - to: validation
+    uses: ./clarify.yaml
+  - id: research
+    route:
+      - to: synthesize
+    uses: ./research.yaml
+  - id: validation
+    route:
+      - to: synthesize
+    uses: ./validation.yaml
+  - id: synthesize
+    uses: ./synthesize.yaml

package/examples/generic-fan-in/generic-fan-in.task.yaml

@@ -0,0 +1,9 @@
+id: generic-fan-in
+goal: |
+  Dummy walkthrough for generic multi-parent fan-in. research and validation
+  run in parallel after clarify. Reply to each with ok <finding> or fail.
+  synthesize waits for both and must copy priorEnvelopesByStage into payload.received.
+context: |
+  Manual operator-console test. Distinct findings (for example glaciers and
+  citations) make it obvious which parent envelope landed under which key.
+  On fail of either parent, synthesize is skipped and the run fails.

package/examples/generic-fan-in/research.yaml

@@ -0,0 +1,45 @@
+id: research
+system_prompt: |
+  You are the research branch of a diamond join. Follow these steps exactly:
+
+  1. Call ask_operator with kind free_text. Ask the operator to reply with
+     exactly one of:
+       ok <finding>
+       fail
+     Tell them <finding> is one token (letters, digits, or hyphen). Examples:
+     ok glaciers
+     fail
+  2. Wait for the operator answer. Do not emit before you have that answer.
+  3. If the answer is fail (optionally with surrounding whitespace), emit
+     emit_stage_envelope with status failure, a short summary that research
+     failed, artifacts [], and no payload.
+  4. If the answer is ok followed by a finding token:
+     emit status success, artifacts [], payload { "finding": "<that token>" },
+     and a summary that includes the word research and the finding token.
+     Use the token after ok as-is; do not invent a different word.
+  5. If the answer is ok with no token, or anything else, emit status failure
+     explaining the reply was not ok <finding> or fail.
+
+  Rules:
+  - Never emit before the operator answers.
+  - Do not call ask_operator more than once.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - brief
+      properties:
+        brief:
+          type: string
+  output:
+    schema:
+      type: object
+      required:
+        - finding
+      properties:
+        finding:
+          type: string
+gate_kinds:
+  - free_text

package/examples/generic-fan-in/synthesize.yaml

@@ -0,0 +1,66 @@
+id: synthesize
+system_prompt: |
+  You are the diamond join. The prompt includes priorEnvelopesByStage — a
+  record keyed in YAML declaration order (research, then validation).
+  priorEnvelope is null. There is no clone-list priorEnvelopes field.
+
+  Call emit_stage_envelope exactly once. Do not call ask_operator.
+
+  1. Read priorEnvelopesByStage.research and priorEnvelopesByStage.validation.
+     Do not invent keys. Do not reorder keys.
+  2. For each parent, copy status, summary, and payload.finding when present.
+     If a parent is a failure envelope with no finding, omit finding.
+  3. Emit status success, artifacts [], and payload:
+     {
+       "received": {
+         "research": { "status": "…", "summary": "…", "finding": "…" },
+         "validation": { "status": "…", "summary": "…", "finding": "…" }
+       }
+     }
+     Include finding only when that parent payload had it.
+  4. Summary must mention both parent keys and their status values, for
+     example: received research=success glaciers; validation=success citations
+
+  Rules:
+  - Copy from priorEnvelopesByStage only. Do not use a single priorEnvelope.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - received
+      properties:
+        received:
+          type: object
+          required:
+            - research
+            - validation
+          properties:
+            research:
+              type: object
+              required:
+                - status
+                - summary
+              properties:
+                status:
+                  type: string
+                summary:
+                  type: string
+                finding:
+                  type: string
+            validation:
+              type: object
+              required:
+                - status
+                - summary
+              properties:
+                status:
+                  type: string
+                summary:
+                  type: string
+                finding:
+                  type: string

package/examples/generic-fan-in/validation.yaml

@@ -0,0 +1,45 @@
+id: validation
+system_prompt: |
+  You are the validation branch of a diamond join. Follow these steps exactly:
+
+  1. Call ask_operator with kind free_text. Ask the operator to reply with
+     exactly one of:
+       ok <finding>
+       fail
+     Tell them <finding> is one token (letters, digits, or hyphen). Examples:
+     ok citations
+     fail
+  2. Wait for the operator answer. Do not emit before you have that answer.
+  3. If the answer is fail (optionally with surrounding whitespace), emit
+     emit_stage_envelope with status failure, a short summary that validation
+     failed, artifacts [], and no payload.
+  4. If the answer is ok followed by a finding token:
+     emit status success, artifacts [], payload { "finding": "<that token>" },
+     and a summary that includes the word validation and the finding token.
+     Use the token after ok as-is; do not invent a different word.
+  5. If the answer is ok with no token, or anything else, emit status failure
+     explaining the reply was not ok <finding> or fail.
+
+  Rules:
+  - Never emit before the operator answers.
+  - Do not call ask_operator more than once.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - brief
+      properties:
+        brief:
+          type: string
+  output:
+    schema:
+      type: object
+      required:
+        - finding
+      properties:
+        finding:
+          type: string
+gate_kinds:
+  - free_text

package/examples/github-release/README.md

@@ -0,0 +1,78 @@
+# github-release
+
+Dogfood release automation: draft operator-facing GitHub release notes, then publish with `gh`. This is an **ops / release example** — not SDLC planning.
+
+Stageflow uses this catalog in `.github/workflows/publish.yml` and `release.yml` when publishing new npm versions.
+
+One GitHub Release is created for the current tag. The notes body includes **every CHANGELOG version since the last GitHub Release**, not only the latest `package.json` bump. A publish that jumps from `0.3.0` to `0.8.0` therefore includes headings for `0.4.0` through `0.8.0`. Intermediate versions are not tagged or published as extra GitHub Releases.
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `github-release.pipeline.yaml` | Two-stage linear pipeline |
+| `draft-release-notes.yaml` | Collect changelog, write `RELEASE_NOTES.md` artifact |
+| `publish-github-release.yaml` | `gh release create` from prior artifact |
+| `github-release.task.yaml` | Task bound at run time |
+
+CI helpers: `scripts/release-range.mjs` resolves previous from published GitHub Releases (git tags if `gh` is unavailable) and extracts the CHANGELOG slice.
+
+## Prerequisites
+
+- Node.js ≥ 20, Stageflow installed
+- **Cursor** (`cursor/composer-2-5`) — set `CURSOR_API_KEY` and install `pi-cursor-sdk` (`pi install npm:pi-cursor-sdk`, or `npm i --prefix ~/.pi/agent/npm pi-cursor-sdk`)
+- **`gh` CLI** and `GH_TOKEN` or `GITHUB_TOKEN` for publish stage
+- Git checkout of the Stageflow repo (stages read version/tags from the bound checkout)
+
+Optional env vars (set by publish workflow): `RELEASE_VERSION`, `RELEASE_TAG`, `RELEASE_PREVIOUS`, `RELEASE_CHANGELOG_SLICE`, `GITHUB_SHA`, `DRY_RUN=1` to skip actual release creation.
+
+`RELEASE_PREVIOUS` is the last published GitHub Release version, not `HEAD^` `package.json`. `RELEASE_CHANGELOG_SLICE` is a markdown file of CHANGELOG sections in that range (workflows write `changelog-slice.md` before `sf run`).
+
+## Commands
+
+From the **repository git root**:
+
+```bash
+sf validate --strict
+export CURSOR_API_KEY=…
+export GH_TOKEN=…
+CURRENT="$(node -p "require('./package.json').version")"
+PREVIOUS="$(node scripts/release-range.mjs previous --current "$CURRENT")"
+if [ -n "$PREVIOUS" ]; then
+  node scripts/release-range.mjs changelog --after "$PREVIOUS" --through "$CURRENT" > changelog-slice.md
+else
+  node scripts/release-range.mjs changelog --through "$CURRENT" > changelog-slice.md
+fi
+export RELEASE_VERSION="$CURRENT" RELEASE_TAG="v${CURRENT}" RELEASE_PREVIOUS="$PREVIOUS" RELEASE_CHANGELOG_SLICE="$PWD/changelog-slice.md"
+sf run \
+  --pipeline examples/github-release/github-release.pipeline.yaml \
+  --task examples/github-release/github-release.task.yaml \
+  --checkout "$PWD"
+```
+
+For a dry run (no GitHub release created):
+
+```bash
+DRY_RUN=1 sf run \
+  --pipeline examples/github-release/github-release.pipeline.yaml \
+  --task examples/github-release/github-release.task.yaml \
+  --checkout "$PWD"
+```
+
+## Repair published notes
+
+If a GitHub Release was published with only the latest version's notes, run **Repair GitHub Release notes** from the Actions tab (`workflow_dispatch`). It overwrites that release's body with every CHANGELOG section since the previous GitHub Release. It does not create tags.
+
+| Input | Effect |
+|-------|--------|
+| *(empty)* | Repair the latest GitHub Release (closes the current `v0.8.0` gap) |
+| `tag` | Repair one tag (`v0.8.0` or `0.8.0`) |
+| `all` | Repair every published GitHub Release |
+| `dry_run` | Print notes in the job log; do not edit GitHub |
+
+Use the branch that contains `scripts/release-range.mjs` (this change must be on the branch you run). Locally:
+
+```bash
+node scripts/release-range.mjs repair --dry-run true
+node scripts/release-range.mjs repair --tag v0.8.0
+```

package/examples/github-release/draft-release-notes.yaml

@@ -0,0 +1,64 @@
+id: draft-release-notes
+system_prompt: |
+  Do exactly one thing: write GitHub release notes for this publish.
+
+  The bound checkout is the Stageflow git repository (agent cwd). Read
+  RELEASE_VERSION, RELEASE_TAG, RELEASE_PREVIOUS, and
+  RELEASE_CHANGELOG_SLICE from the environment when they are set.
+
+  RELEASE_PREVIOUS is the last published GitHub Release (or last v* git
+  tag), not the previous package.json bump. If it is missing, read
+  version from package.json, use tag v<version>, and resolve previous
+  the same way: last GitHub Release, else latest v* git tag that is
+  strictly older than the current version. Do not use HEAD^ package.json
+  as previous.
+
+  Notes must cover every version after previous through current,
+  inclusive. A jump from 0.3.0 to 0.8.0 must include 0.4.0, 0.5.0,
+  0.6.0, 0.7.0, and 0.8.0 as separate headings. Do not collapse the
+  range into the latest version only.
+
+  Source of truth for those sections:
+  - If RELEASE_CHANGELOG_SLICE is set, read that file first (absolute
+    or repo-relative). Keep every ## [x.y.z] section it contains.
+  - Else read CHANGELOG.md and take every ## [x.y.z] heading where
+    version is greater than previous and less than or equal to current.
+  You may polish wording for GitHub (short summary, Features / Fixes /
+  Docs) but do not drop a version or invent commits, PRs, or features.
+  If CHANGELOG is missing a version in the range, fill that version
+  from git log v$PREVIOUS..HEAD (or the first commit of previous
+  through HEAD). You may also use gh to list merged PRs in that range.
+
+  Write RELEASE_NOTES.md via write_stage_artifact. Newest version first.
+  Not a raw git log dump. Not "bumped the version" as the only content.
+  Do not create a git tag. Do not call gh release create. Do not call
+  ask_operator. Do not stop after a chat reply.
+
+  Call emit_stage_envelope exactly once with status success, that artifact
+  path, a one-sentence summary, and a payload matching the stage schema.
+  included_versions lists every x.y.z heading in the notes, newest first.
+model: cursor/composer-2-5
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - version
+        - tag
+        - previous_version
+        - included_versions
+      properties:
+        version:
+          type: string
+        tag:
+          type: string
+        previous_version:
+          type: string
+        included_versions:
+          type: array
+          items:
+            type: string
+      additionalProperties: false

package/examples/github-release/github-release.pipeline.yaml

@@ -0,0 +1,11 @@
+id: github-release
+stages:
+  - id: draft-release-notes
+    entry: true
+    route:
+      - to: publish-github-release
+    uses: ./draft-release-notes.yaml
+  - id: publish-github-release
+    uses: ./publish-github-release.yaml
+    secrets:
+      - GITHUB_TOKEN

package/examples/github-release/github-release.task.yaml

@@ -0,0 +1,13 @@
+id: github-release
+goal: Draft operator-facing GitHub release notes for every version since the last GitHub Release, then publish them as one GitHub Release for the current tag.
+context: |
+  Bound checkout is the Stageflow repository. Current version, tag,
+  previous published GitHub Release, and optional changelog slice path
+  are in RELEASE_VERSION, RELEASE_TAG, RELEASE_PREVIOUS, and
+  RELEASE_CHANGELOG_SLICE when those env vars are set; otherwise read
+  them from package.json, git tags / GitHub Releases, and CHANGELOG.md.
+constraints: |
+  No HITL. Do not call ask_operator. Stage 1 writes notes that include
+  a heading for every CHANGELOG version after previous through current.
+  Stage 2 only publishes those notes with gh for the current tag. Do
+  not use GitHub auto-generated notes. Do not create extra tags.

package/examples/github-release/publish-github-release.yaml

@@ -0,0 +1,64 @@
+id: publish-github-release
+system_prompt: |
+  Do exactly one thing: publish the prior stage's release notes as a
+  GitHub Release.
+
+  Use the prior envelope for version, tag, previous_version, and the
+  RELEASE_NOTES.md artifact path. Read that file from the factory run
+  workspace (STAGEFLOW_RUN_WORKSPACE plus the run-relative artifact
+  path). Do not rewrite or regenerate the notes. Do not call
+  --generate-notes. Do not call ask_operator.
+
+  Target commit is GITHUB_SHA if set, otherwise git rev-parse HEAD.
+  Auth uses GIT_ASKPASS from a declared secrets: [GITHUB_TOKEN] grant
+  (file-backed helper — not ambient GH_TOKEN/GITHUB_TOKEN). gh is on PATH.
+
+  If DRY_RUN is 1, do not create the release. Write publish.md via
+  write_stage_artifact recording the gh command you would have run,
+  then emit success with published false and html_url empty.
+
+  Otherwise run:
+  gh release create "$TAG" --title "$TAG" --target "$SHA" --notes-file "$NOTES_PATH"
+  Confirm with gh release view. Write publish.md via write_stage_artifact
+  with the tag and html_url. If the release already exists, emit status
+  failure. Do not stop after a chat reply.
+
+  Call emit_stage_envelope exactly once with status, that artifact path,
+  a one-sentence summary, and a payload matching the stage schema.
+model: cursor/composer-2-5
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - version
+        - tag
+        - previous_version
+        - included_versions
+      properties:
+        version:
+          type: string
+        tag:
+          type: string
+        previous_version:
+          type: string
+        included_versions:
+          type: array
+          items:
+            type: string
+      additionalProperties: false
+  output:
+    schema:
+      type: object
+      required:
+        - tag
+        - published
+        - html_url
+      properties:
+        tag:
+          type: string
+        published:
+          type: boolean
+        html_url:
+          type: string
+      additionalProperties: false

package/examples/hello-world/README.md

@@ -0,0 +1,28 @@
+# hello-world
+
+Minimal single-stage pipeline. Domain-neutral — the stage id and prompts are yours to define.
+
+## What this demonstrates
+
+- **`task.input` ↔ entry `io.input.schema`** — `my-task.task.yaml` supplies a structured `input` object; the entry stage (`research.yaml`) declares matching `io.input.schema`.
+- **Unmet entry input** — if the entry stage declares `io.input` and the task omits `input`, `sf validate` of each file alone still succeeds; start-run / `preparePipeline` warn with `task.entry_input_unmet` and continue (existing product behavior).
+
+This catalog uses `io` only (no `verify` / `on_verify_fail`). For upgrading older field names, see [YAML catalog — Upgrading older catalogs](../../docs/yaml-catalog.md#upgrading-older-catalogs).
+
+## Prerequisites
+
+- Node.js ≥ 20, Stageflow installed (`npm i -g stageflow`)
+- A Pi-compatible provider connected via `sf ui` or `sf providers login`
+
+## Commands
+
+From the **repository git root**:
+
+```bash
+sf validate --pipeline examples/hello-world/hello.pipeline.yaml --strict
+sf run \
+  --pipeline examples/hello-world/hello.pipeline.yaml \
+  --task examples/hello-world/my-task.task.yaml
+```
+
+Use `sf ui` (from any subdirectory) to watch the run and inspect the stage envelope.

package/examples/hello-world/hello.pipeline.yaml

@@ -0,0 +1,4 @@
+id: hello
+stages:
+  - id: research
+    uses: ./research.yaml

package/examples/hello-world/my-task.task.yaml

@@ -0,0 +1,6 @@
+id: my-task
+goal: Draft a one-page brief on a topic of your choice
+context: Domain-neutral hello-world run
+constraints: Docs only; no implementation code
+input:
+  topic: Calendar apps for personal productivity