stageflow 0.25.0 → 0.30.0

package/examples/hello-world/research.yaml

@@ -0,0 +1,18 @@
+id: research
+system_prompt: |
+  Summarize the task goal for the given topic and list open questions.
+  The topic arrives as task input (and as this stage's io.input payload).
+model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - topic
+      properties:
+        topic:
+          type: string
+      additionalProperties: false
+  output:
+    schema:
+      type: object

package/examples/mcp-hitl-tour/README.md

@@ -0,0 +1,113 @@
+# mcp-hitl-tour
+
+MCP-first walkthrough: **HITL**, an ungated **fan-out/join**, a small **Clone
+Chain**, a **guaranteed feedback loop** that parks for `decide_feedback_loop`,
+and **artifacts** you can read back with `read_artifact`.
+
+Domain-neutral — it writes a short brief. Use it to see how an operator-host
+MCP client starts a run, asks the operator at each HITL gate, inspects a
+stage, and decides the loop.
+
+This DAG does **not** exclusive-route. Exclusive Route `if` into a shared join
+can leave the unused arm `pending`, so the join never becomes runnable. Here
+both arms always run; `polish` waits for two successes, not a skip.
+
+```
+start_run → wait_run → answer_gate (intake) → wait_run
+         → review send_back → polish replay → review send_back
+         → decide_feedback_loop → wait_run until terminal
+         → get_run / list_stage_events / get_envelope / read_artifact
+```
+
+## What it exercises
+
+| Stage | Why it is here |
+|-------|----------------|
+| `intake` | `gate_kinds: [free_text]` — MCP `answer_gate`. Emits `payload.audience`. Writes `intake.md`. |
+| Fan-out | Intake lists `emit-angles` and `draft-short` with **no** `if`. Both always run. |
+| `emit-angles` → `draft-angle` → `gather` | Sequential Clone Chain, `clone_cap: 2`. Clone workers write `angle.md`. |
+| `draft-short` | Parallel short take. Writes `short.md`. |
+| `polish` | Join of `gather` and `draft-short`. Writes `brief.md`. Loop target. |
+| `review` | Always `send_back` polish. `{ type: loop }`, `max_replays: 1`, `on_max_replays: wait_for_human` — one replay, then operator HITL. |
+| `ship` | `replay_safe: false`. Writes `ship.md`. |
+
+`describe_pipeline` should show `entry`, clone fields, `feedback_loop`,
+`gate_kinds` on intake, and `replay_safe` on ship. It should **not** show
+inbound `if` on the intake children.
+
+```
+intake (free_text HITL)
+  ├─ emit-angles → draft-angle×2 → gather ─┐
+  └─ draft-short ──────────────────────────┴→ polish ► review ⇄ polish ► ship
+```
+
+## Prerequisites
+
+- This Stageflow checkout, built (`npm run build && npm run ui:build`)
+- Provider auth connected
+- An MCP client (Cursor on **another** project is fine) pointed at `http://127.0.0.1:3847/mcp`
+
+Host the catalog from **this git root** so `list_pipelines` includes this example:
+
+```bash
+cd /path/to/stageflow
+node dist/cli.js ui
+```
+
+## MCP walkthrough
+
+From a consumer Cursor chat with Stageflow MCP loaded:
+
+1. `describe_pipeline` `{ "pipeline": "examples/mcp-hitl-tour/mcp-hitl-tour.pipeline.yaml" }`
+2. `start_run` with
+   - `pipeline`: `examples/mcp-hitl-tour/mcp-hitl-tour.pipeline.yaml`
+   - `task_path`: `examples/mcp-hitl-tour/mcp-hitl-tour.task.yaml`
+3. `wait_run` `{ "runId": "…", "until": "waiting" }`
+4. Present the intake prompt to the operator. `answer_gate` — `stageId` is
+   `intake`, `kind` is `free_text`, `text` is `operators` or `executives`,
+   `promptId` from the pending prompt. Do not invent the reply.
+5. `wait_run` `{ "runId": "…", "until": "waiting" }` — review sends the brief
+   back once (polish replays), then parks (`waiting_kind` is
+   `feedback_loop_decision`)
+6. Present the loop decision to the operator. `decide_feedback_loop` with
+   `decision: "continue"` (or `extend` / `abandon`)
+7. `wait_run` `{ "runId": "…", "until": "terminal" }`
+8. `get_run` — artifact paths, `total_cost_usd` when the store has it
+9. `read_artifact` `intake.md` / `short.md` / `angles-brief.md` / `brief.md` /
+   `ship.md` (use the paths `get_run` returned)
+10. `list_stage_events` `{ "runId": "…", "stageId": "intake" }`
+11. `get_envelope` `{ "runId": "…", "stageId": "intake" }` — `payload.audience`
+    matches the gate reply
+
+The exhaust task (`mcp-hitl-tour-exhaust.task.yaml`) is the same walkthrough.
+
+## Validate
+
+```bash
+node dist/cli.js validate --pipeline examples/mcp-hitl-tour/mcp-hitl-tour.pipeline.yaml --strict
+```
+
+## Layout
+
+```
+examples/mcp-hitl-tour/
+  mcp-hitl-tour.pipeline.yaml
+  mcp-hitl-tour.task.yaml
+  mcp-hitl-tour-exhaust.task.yaml
+  intake.yaml
+  emit-angles.yaml
+  draft-angle.yaml
+  gather.yaml
+  draft-short.yaml
+  polish.yaml
+  review.yaml
+  ship.yaml
+```
+
+## References
+
+- [MCP](../../docs/mcp.md)
+- [HITL](../../docs/hitl.md)
+- [YAML catalog — Generic fan-in](../../docs/yaml-catalog.md#generic-fan-in)
+- [YAML catalog — Clone Chain](../../docs/yaml-catalog.md#clone-chain)
+- [YAML catalog — Feedback loops](../../docs/yaml-catalog.md#feedback-loops)

package/examples/mcp-hitl-tour/draft-angle.yaml

@@ -0,0 +1,33 @@
+id: draft-angle
+system_prompt: |
+  Draft one clone angle. Your io.input is a single Angle (id, title, topic).
+  Write 5–8 sentences. Do not cover the other clone's title.
+
+  1. Call write_stage_artifact with path angle.md for this id and title.
+  2. Emit success with artifacts [angle.md] and payload
+     { "id": "<input id>", "title": "<input title>" }.
+io:
+  input:
+    schema:
+      $ref: "#/schemas/Angle"
+  output:
+    schema:
+      type: object
+      required: [id, title]
+      properties:
+        id:
+          type: string
+        title:
+          type: string
+verify:
+  - id: angle-declared
+    type: artifact
+    basename: angle.md
+    when:
+      - emit
+  - id: angle-on-disk
+    type: artifact
+    path: angle.md
+    nonempty: true
+    when:
+      - after

package/examples/mcp-hitl-tour/draft-short.yaml

@@ -0,0 +1,32 @@
+id: draft-short
+system_prompt: |
+  Write one short take on the intake topic for payload.audience.
+
+  This arm always runs alongside the Clone Chain. Do not skip clone work;
+  just write this one-page take.
+
+  1. Call write_stage_artifact with path short.md (one page, headings allowed).
+  2. Emit success with artifacts [short.md] and payload { "kind": "short" }.
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required: [kind]
+      properties:
+        kind:
+          type: string
+verify:
+  - id: short-declared
+    type: artifact
+    basename: short.md
+    when:
+      - emit
+  - id: short-on-disk
+    type: artifact
+    path: short.md
+    nonempty: true
+    when:
+      - after

package/examples/mcp-hitl-tour/emit-angles.yaml

@@ -0,0 +1,45 @@
+id: emit-angles
+system_prompt: |
+  Split the intake topic into exactly two short angles for sequential clone
+  workers. Do not write the briefs here.
+
+  1. Read payload.topic from the intake envelope.
+  2. Invent two non-overlapping angles (id kebab-case, title, same topic).
+  3. Call write_stage_artifact with path angles.md listing both ids and titles.
+  4. Emit exactly one success envelope with artifacts [angles.md] and payload:
+     {
+       "items": [
+         { "id": "…", "title": "…", "topic": "<intake topic>" },
+         { "id": "…", "title": "…", "topic": "<intake topic>" }
+       ],
+       "summary": "two angles"
+     }
+
+  Emit exactly two items. Never zero, never more than two.
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/schemas/Angle"
+        summary:
+          type: string
+verify:
+  - id: angles-declared
+    type: artifact
+    basename: angles.md
+    when:
+      - emit
+  - id: angles-on-disk
+    type: artifact
+    path: angles.md
+    nonempty: true
+    when:
+      - after

package/examples/mcp-hitl-tour/gather.yaml

@@ -0,0 +1,31 @@
+id: gather
+system_prompt: |
+  You are the Clone Chain join. Summarize each clone instance's angle.md into
+  one note. Do not invent angles that were not cloned.
+
+  1. Call write_stage_artifact with path angles-brief.md.
+  2. Emit success with artifacts [angles-brief.md] and payload
+     { "kind": "angles" }.
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required: [kind]
+      properties:
+        kind:
+          type: string
+verify:
+  - id: angles-brief-declared
+    type: artifact
+    basename: angles-brief.md
+    when:
+      - emit
+  - id: angles-brief-on-disk
+    type: artifact
+    path: angles-brief.md
+    nonempty: true
+    when:
+      - after

package/examples/mcp-hitl-tour/intake.yaml

@@ -0,0 +1,62 @@
+id: intake
+gate_kinds:
+  - free_text
+system_prompt: |
+  You are the HITL intake for an MCP operator-host walkthrough.
+
+  The topic arrives as task input (io.input.topic). Do not invent a different topic.
+
+  Follow these steps exactly:
+
+  1. Call ask_operator with kind free_text. Ask which audience the brief is
+     for. Tell the operator to reply with exactly one of: operators or
+     executives.
+     - operators: concrete, how-it-works language
+     - executives: short, stakes-and-tradeoffs language
+  2. Wait for the operator answer. Do not call emit_stage_envelope before you
+     have that answer.
+  3. Call write_stage_artifact with path intake.md. Write the topic, the chosen
+     audience, and one sentence that both a clone-chain draft and a short
+     draft will run, then join at polish.
+  4. Call emit_stage_envelope exactly once with:
+     - status: success
+     - a non-empty summary
+     - artifacts: [intake.md]
+     - payload: { "topic": "<task topic>", "audience": "operators" } or
+       { "topic": "<task topic>", "audience": "executives" }, matching the
+       operator reply exactly
+
+  Rules:
+  - Never emit before the operator answers.
+  - Never invent other audience values.
+  - Do not emit fork_choice. Both successor stages always run.
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - topic
+      properties:
+        topic:
+          type: string
+  output:
+    schema:
+      type: object
+      required: [topic, audience]
+      properties:
+        topic:
+          type: string
+        audience:
+          type: string
+verify:
+  - id: intake-declared
+    type: artifact
+    basename: intake.md
+    when:
+      - emit
+  - id: intake-on-disk
+    type: artifact
+    path: intake.md
+    nonempty: true
+    when:
+      - after

package/examples/mcp-hitl-tour/mcp-hitl-tour-exhaust.task.yaml

@@ -0,0 +1,13 @@
+id: mcp-hitl-tour-exhaust
+goal: |
+  Same walkthrough as mcp-hitl-tour: send the brief back until the loop parks
+  for a human decision after intake HITL.
+context: |
+  Pair with mcp-hitl-tour.pipeline.yaml. Answer intake with exactly operators
+  or executives. Every review success MUST emit send_back target polish —
+  never continue — until waiting_kind is feedback_loop_decision.
+constraints: |
+  Docs only. First review: send_back polish. After the polish replay, second
+  review: send_back polish again so MCP can call decide_feedback_loop.
+input:
+  topic: Local-first notes apps for small teams

package/examples/mcp-hitl-tour/mcp-hitl-tour.pipeline.yaml

@@ -0,0 +1,54 @@
+id: mcp-hitl-tour
+model: cursor/auto
+schemas:
+  Angle:
+    type: object
+    required: [id, title, topic]
+    properties:
+      id:
+        type: string
+      title:
+        type: string
+      topic:
+        type: string
+stages:
+  - id: intake
+    uses: ./intake.yaml
+    entry: true
+    route:
+      - to: emit-angles
+      - to: draft-short
+  - id: emit-angles
+    uses: ./emit-angles.yaml
+    clone_cap: 2
+    clone_mode: sequential
+    route:
+      - to: draft-angle
+  - id: draft-angle
+    uses: ./draft-angle.yaml
+    route:
+      - to: gather
+  - id: gather
+    uses: ./gather.yaml
+    route:
+      - to: polish
+  - id: draft-short
+    uses: ./draft-short.yaml
+    route:
+      - to: polish
+  - id: polish
+    uses: ./polish.yaml
+    route:
+      - to: review
+  - id: review
+    uses: ./review.yaml
+    route:
+      - to: ship
+      - type: loop
+        to: polish
+        max_replays: 1
+        on_max_replays: wait_for_human
+        replay_session: resume
+  - id: ship
+    uses: ./ship.yaml
+    replay_safe: false

package/examples/mcp-hitl-tour/mcp-hitl-tour.task.yaml

@@ -0,0 +1,16 @@
+id: mcp-hitl-tour
+goal: |
+  Produce a short operator-readable brief on the given topic. At intake, the
+  operator chooses audience (operators or executives). Both a Clone Chain
+  draft and a short draft always run, then join at polish. Review always
+  sends the brief back once so the operator decides the loop.
+context: |
+  MCP operator-host walkthrough. Answer the intake free_text gate with exactly
+  operators or executives. Every review success MUST emit send_back target
+  polish — never continue — until waiting_kind is feedback_loop_decision.
+constraints: |
+  Docs only; no implementation code; no git push. First review: send_back
+  polish. After the polish replay, second review: send_back polish again so
+  the operator can call decide_feedback_loop.
+input:
+  topic: Local-first notes apps for small teams

package/examples/mcp-hitl-tour/polish.yaml

@@ -0,0 +1,33 @@
+id: polish
+system_prompt: |
+  Produce the canonical brief.md the reviewer will read.
+
+  Both parents always ran: start from short.md and from angles-brief.md plus
+  the clone angle.md files. Match the intake audience. On a feedback replay,
+  read Feedback Loop Context and revise brief.md to address the send-back.
+
+  1. Call write_stage_artifact with path brief.md.
+  2. Emit success with artifacts [brief.md] and payload { "polished": true }.
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required: [polished]
+      properties:
+        polished:
+          type: boolean
+verify:
+  - id: brief-declared
+    type: artifact
+    basename: brief.md
+    when:
+      - emit
+  - id: brief-on-disk
+    type: artifact
+    path: brief.md
+    nonempty: true
+    when:
+      - after

package/examples/mcp-hitl-tour/review.yaml

@@ -0,0 +1,17 @@
+id: review
+system_prompt: |
+  Review brief.md against the task goal.
+  On every success you MUST emit feedback_loop send_back — never continue:
+
+  {"action":"send_back","target":"polish"}
+
+  This walkthrough always takes one polish replay, then parks for a human
+  feedback decision (MCP decide_feedback_loop). Do not continue to ship from
+  this stage.
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/mcp-hitl-tour/ship.yaml

@@ -0,0 +1,25 @@
+id: ship
+system_prompt: |
+  Ship the approved brief. Call write_stage_artifact with path ship.md
+  summarizing the final brief in a few sentences. Emit success with
+  artifacts [ship.md]. This stage is replay_safe: false — it runs only after
+  review continues.
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+verify:
+  - id: ship-declared
+    type: artifact
+    basename: ship.md
+    when:
+      - emit
+  - id: ship-on-disk
+    type: artifact
+    path: ship.md
+    nonempty: true
+    when:
+      - after