stageflow 0.25.0 → 0.30.0

package/examples/route-if-tour/route-if-tour.task.yaml

@@ -0,0 +1,4 @@
+id: route-if-tour
+goal: Follow each stage prompt and emit the exact JSON payload it names.
+context: Route-if tour — routing is decided by those payloads, not by picking a next stage.
+constraints: Docs only; no implementation code. One-sentence summaries. Use the prompt's payload verbatim. Never emit fork_choice.

package/examples/route-wiring-smoke-test/01-core-routing.pipeline.yaml

@@ -0,0 +1,168 @@
+id: route-demo-core
+stages:
+  - id: plan
+    entry: true
+    route:
+      - to: implement
+    system_prompt: |
+      Draft a one-sentence plan.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: implement
+    route:
+      - to: review
+    system_prompt: |
+      Implement the plan in one or two sentences.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  # Loop: continue forward to qa, or send back to implement (driven by
+  # the feedback_loop envelope action, independent of listed route targets).
+  - id: review
+    route:
+      - to: qa
+      - type: loop
+        to: implement
+        max_replays: 2
+        on_max_replays: require_continue
+        replay_session: resume
+    system_prompt: |
+      Review the change in one or two sentences. Prefer continue so the rest of the pipeline runs.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], payload: {}, and feedback_loop: {"action":"continue"}.
+      To send work back instead, use feedback_loop: {"action":"send_back","target":"implement"}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  # Listed route targets always run after qa succeeds.
+  - id: qa
+    route:
+      - to: ship
+      - to: request-changes
+    system_prompt: |
+      Record the QA outcome in one sentence. Ship and request-changes both run next.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  # Listed route targets always run after ship succeeds.
+  - id: ship
+    route:
+      - to: notify-slack
+      - to: notify-email
+      - to: update-changelog
+    system_prompt: |
+      Ship the change in one sentence. Slack, email, and changelog notifications all run next.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: request-changes
+    route:
+      - to: close
+    system_prompt: |
+      Note the requested changes in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: notify-slack
+    route:
+      - to: close
+    system_prompt: |
+      Pretend to notify Slack in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: notify-email
+    route:
+      - to: close
+    system_prompt: |
+      Pretend to notify email in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: update-changelog
+    route:
+      - to: close
+    system_prompt: |
+      Pretend to update the changelog in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  # Fan-in of request-changes plus the three notify stages. On the happy
+  # path all four parents run. The join waits until every parent is
+  # terminal, then runs if at least one succeeded (skipped arms do not
+  # block; their envelopes are omitted). Stays pending if a parent failed.
+  # Does not run if every parent skipped.
+  - id: close
+    system_prompt: |
+      Close out the run in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object

package/examples/route-wiring-smoke-test/02-on-gating.pipeline.yaml

@@ -0,0 +1,44 @@
+id: route-demo-on-gate
+stages:
+  - id: run-tests
+    entry: true
+    route:
+      - to: ship
+        on: [succeeded]
+      - to: hotfix
+        on: [failed]
+    system_prompt: |
+      Run a tiny smoke-test check and succeed so ship runs next. (A failure envelope would route to hotfix instead.)
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+  - id: ship
+    system_prompt: |
+      Ship the release in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+  - id: hotfix
+    system_prompt: |
+      Apply a hotfix in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object

package/examples/route-wiring-smoke-test/03-two-entry-points.pipeline.yaml

@@ -0,0 +1,28 @@
+id: route-demo-two-entries
+stages:
+  - id: news-digest
+    entry: true
+    system_prompt: |
+      Gather a one-sentence news digest.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+  - id: weather-report
+    entry: true
+    system_prompt: |
+      Gather a one-sentence weather report.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object

package/examples/route-wiring-smoke-test/04-entry-false-equivalent-to-omitted.pipeline.yaml

@@ -0,0 +1,27 @@
+id: route-demo-entry-false
+stages:
+  - id: draft
+    entry: false
+    system_prompt: |
+      Write one sentence as a standalone stage explicitly marked entry false.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+  - id: review
+    system_prompt: |
+      Write one sentence as another independent stage.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object

package/examples/route-wiring-smoke-test/05-fork-choice.pipeline.yaml

@@ -0,0 +1,110 @@
+id: route-demo-fork-choice
+stages:
+  # Listed route targets always run after triage succeeds.
+  - id: triage
+    entry: true
+    route:
+      - to: quick-fix
+      - to: big-project
+    system_prompt: |
+      Categorize this work in one sentence. Both the quick-fix and big-project follow-ups run next.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: big-project
+    system_prompt: |
+      Kick off planning for the big project in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  # Listed route targets always run after quick-fix succeeds.
+  - id: quick-fix
+    route:
+      - to: notify-team
+      - to: update-docs
+      - to: schedule-followup
+    system_prompt: |
+      Apply the quick fix in one sentence. Notify-team, update-docs, and schedule-followup all run next.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: notify-team
+    route:
+      - to: close
+    system_prompt: |
+      Notify the team the quick fix shipped, in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: update-docs
+    route:
+      - to: close
+    system_prompt: |
+      Update the docs for the quick fix in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: schedule-followup
+    route:
+      - to: close
+    system_prompt: |
+      Schedule a follow-up review in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  # Fan-in of notify-team, update-docs, and schedule-followup — all three
+  # run on the happy path.
+  - id: close
+    system_prompt: |
+      Close out the run in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object

package/examples/route-wiring-smoke-test/06-fan-out-fan-in.pipeline.yaml

@@ -0,0 +1,82 @@
+id: route-demo-fan-out-fan-in
+# Unconditional parallel fan-out: kickoff's route lists three targets, so
+# all three always run, feeding one join that waits for all of them.
+# Multiple forward `to:` entries always fan out this way.
+stages:
+  - id: kickoff
+    entry: true
+    route:
+      - to: research
+      - to: analysis
+      - to: review-notes
+    system_prompt: |
+      Kick off three independent workstreams in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: research
+    route:
+      - to: synthesize
+    system_prompt: |
+      Workstream 1 (research). Produce one short finding.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: analysis
+    route:
+      - to: synthesize
+    system_prompt: |
+      Workstream 2 (analysis). Produce one short finding.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: review-notes
+    route:
+      - to: synthesize
+    system_prompt: |
+      Workstream 3 (review notes). Produce one short finding.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  # Fan-in: waits for research, analysis, and review-notes — all three,
+  # every time, since none of them are skipped.
+  - id: synthesize
+    system_prompt: |
+      Combine all three workstreams' findings into one summary sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object

package/examples/route-wiring-smoke-test/07-loop-human-decision.pipeline.yaml

@@ -0,0 +1,82 @@
+id: route-demo-loop-human-decision
+# Covers the loop config variants 01-core-routing doesn't: on_max_replays:
+# wait_for_human (vs. require_continue) and replay_session: new_session (vs.
+# resume). max_replays: 1 plus review's prompt (always send_back) makes this
+# reliably exhaust its replay budget and PARK the run waiting for a human
+# decision -- a genuine "waiting for input" state, not a bug. Use
+# `npx tsx src/cli.ts runs waiting` / `npx tsx src/cli.ts runs answer` (or the
+# UI's own decide flow) to unstick it:
+# `npx tsx src/cli.ts runs answer --run <runId> --stage review`.
+stages:
+  - id: plan
+    entry: true
+    route:
+      - to: implement
+    system_prompt: |
+      Draft a one-sentence plan.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: implement
+    route:
+      - to: review
+    system_prompt: |
+      Implement the plan in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: review
+    route:
+      - to: submit
+      - type: loop
+        to: implement
+        max_replays: 1
+        on_max_replays: wait_for_human
+        replay_session: new_session
+    system_prompt: |
+      Review the upstream work against the task goal in one or two sentences.
+      On success you MUST include feedback_loop in your envelope:
+      - {"action":"continue"} when the work is good enough to submit
+      - {"action":"send_back","target":"implement"} when another pass is needed
+      For this smoke test: ALWAYS send_back to implement, never continue.
+      This is deliberate -- with max_replays: 1, your second send_back will
+      exhaust the replay budget and park the run waiting for a human
+      decision (on_max_replays: wait_for_human), which is exactly what this
+      pipeline exists to demonstrate.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], payload: {}, and feedback_loop: {"action":"send_back","target":"implement"}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: submit
+    replay_safe: false
+    system_prompt: |
+      Submit the approved change in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object

package/examples/route-wiring-smoke-test/08-skip-fallback-and-multi-on-gate.pipeline.yaml

@@ -0,0 +1,77 @@
+id: route-demo-skip-and-multi-on
+stages:
+  # Listed route targets always run after decide succeeds — both arms.
+  - id: decide
+    entry: true
+    route:
+      - to: risky-step
+      - to: safe-step
+    system_prompt: |
+      Run both the risky-step and safe-step follow-ups. One sentence is enough.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  # Leaf: does not route onward. done is only on the safe-step arm, so
+  # it does not wait on this sibling.
+  - id: risky-step
+    system_prompt: |
+      The risky path. A leaf — no child runs from here. One sentence is enough.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: safe-step
+    route:
+      - to: notify-either-way
+    system_prompt: |
+      The safe path. Routes onward to notify-either-way, then done. One sentence is enough.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: notify-either-way
+    route:
+      - to: done
+    system_prompt: |
+      Runs after safe-step succeeds. One sentence is enough.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: done
+    system_prompt: |
+      Close out the run in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object