stageflow 0.25.0 → 0.27.0

package/examples/route-wiring-smoke-test/09-multi-loop-targets.pipeline.yaml

@@ -0,0 +1,102 @@
+id: route-demo-multi-loop-targets
+# Two DIFFERENT stages (review, qa) each declare their own loop entry back
+# to the SAME ancestor (implement). review's loop point is dormant in this
+# run (always continues); qa's is the one that actually fires, demonstrating
+# that a loop target doesn't have to be the looping stage's immediate
+# parent -- implement is two hops back from qa (implement -> review -> qa).
+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: qa
+      - type: loop
+        to: implement
+        max_replays: 1
+        on_max_replays: require_continue
+        replay_session: resume
+    system_prompt: |
+      Review the implementation in one or two sentences.
+      On success you MUST include feedback_loop in your envelope:
+      {"action":"continue"} or {"action":"send_back","target":"implement"}.
+      For this smoke test, ALWAYS continue -- never send back. This loop
+      point exists in the wiring but stays dormant this run; qa (below) is
+      the one that actually exercises a loop-back to implement.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], payload: {}, and feedback_loop: {"action":"continue"}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+
+  - id: qa
+    route:
+      - to: done
+      - type: loop
+        to: implement
+        max_replays: 1
+        on_max_replays: require_continue
+        replay_session: resume
+    system_prompt: |
+      QA the reviewed implementation in one or two sentences.
+      On success you MUST include feedback_loop in your envelope:
+      {"action":"continue"} or {"action":"send_back","target":"implement"}.
+      For this smoke test: on your FIRST attempt, send_back to implement.
+      On your SECOND attempt (after the replay), continue. This demonstrates
+      looping back to an ancestor two stages back (implement), independently
+      of review's own dormant loop point above -- both target the same
+      stage from different points in the chain.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], payload: {}, and the matching feedback_loop action.
+    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

package/examples/route-wiring-smoke-test/10-uses-dialect-fork.pipeline.yaml

@@ -0,0 +1,23 @@
+id: route-demo-uses-dialect-fork
+# Every other pipeline in this catalog uses inline stage bodies
+# (system_prompt/model directly on the stage entry). This one uses the
+# `uses:` external-stage-file dialect instead — to confirm route/entry
+# work identically regardless of where the stage body lives. Both
+# listed branches always run after decide succeeds.
+stages:
+  - id: decide
+    entry: true
+    route:
+      - to: branch-a
+      - to: branch-b
+    uses: ./stages/decide.yaml
+  - id: branch-a
+    route:
+      - to: finish
+    uses: ./stages/branch-a.yaml
+  - id: branch-b
+    route:
+      - to: finish
+    uses: ./stages/branch-b.yaml
+  - id: finish
+    uses: ./stages/finish.yaml

package/examples/route-wiring-smoke-test/11-sequential-io-handoff.pipeline.yaml

@@ -0,0 +1,37 @@
+id: route-demo-sequential-io
+stages:
+  - id: draft
+    entry: true
+    route:
+      - to: review
+    system_prompt: |
+      Draft a titled document in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {"title": "Smoke draft"}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+          required: [title]
+          properties:
+            title:
+              type: string
+  - id: review
+    system_prompt: |
+      Review the titled document 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
+          required: [title]
+          properties:
+            title:
+              type: string
+      output:
+        schema:
+          type: object

package/examples/route-wiring-smoke-test/12-complex-io-schemas.pipeline.yaml

@@ -0,0 +1,138 @@
+id: route-demo-complex-io
+schemas:
+  finding:
+    type: object
+    required: [id, severity]
+    properties:
+      id:
+        type: string
+        minLength: 1
+      severity:
+        type: string
+        enum: [low, medium, high]
+      detail:
+        type: string
+        nullable: true
+  report:
+    type: object
+    required: [title, status, findings, score, metadata]
+    properties:
+      title:
+        type: string
+        minLength: 1
+        maxLength: 200
+        pattern: "^[A-Za-z0-9].+"
+      status:
+        type: string
+        enum: [draft, review, final]
+      findings:
+        type: array
+        minItems: 1
+        items:
+          $ref: "#/schemas/finding"
+      score:
+        type: integer
+        minimum: 0
+        maximum: 100
+      notes:
+        type: string
+      metadata:
+        type: object
+        required: [source]
+        properties:
+          source:
+            type: string
+          version:
+            type: integer
+            minimum: 1
+  analyzed:
+    type: object
+    required: [title, status, findings, score, metadata, summary]
+    properties:
+      title:
+        type: string
+        minLength: 1
+        maxLength: 200
+        pattern: "^[A-Za-z0-9].+"
+      status:
+        type: string
+        enum: [draft, review, final]
+      findings:
+        type: array
+        minItems: 1
+        items:
+          $ref: "#/schemas/finding"
+      score:
+        type: integer
+        minimum: 0
+        maximum: 100
+      notes:
+        type: string
+      metadata:
+        type: object
+        required: [source]
+        properties:
+          source:
+            type: string
+          version:
+            type: integer
+            minimum: 1
+      summary:
+        type: string
+        minLength: 1
+stages:
+  - id: draft
+    entry: true
+    route:
+      - to: analyze
+    system_prompt: |
+      Draft a findings report in one or two sentences.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and a payload matching #/schemas/report. Copy this example:
+      {"title":"Smoke report","status":"draft","findings":[{"id":"f1","severity":"low","detail":"none"}],"score":80,"metadata":{"source":"smoke-test"}}
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          $ref: "#/schemas/report"
+  - id: analyze
+    route:
+      - to: summarize
+    system_prompt: |
+      Keep the report fields and add a summary string.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and a payload matching #/schemas/analyzed. Copy this example:
+      {"title":"Smoke report","status":"review","findings":[{"id":"f1","severity":"low","detail":"none"}],"score":80,"metadata":{"source":"smoke-test"},"summary":"One low finding; score 80."}
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/report"
+      output:
+        schema:
+          $ref: "#/schemas/analyzed"
+  - id: summarize
+    system_prompt: |
+      Summarize using title, summary, and score from the prior payload. 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
+          required: [title, summary, score]
+          properties:
+            title:
+              type: string
+              minLength: 1
+            summary:
+              type: string
+              minLength: 1
+            score:
+              type: number
+              minimum: 0
+              maximum: 100
+      output:
+        schema:
+          type: object

package/examples/route-wiring-smoke-test/13-ref-io-handoff.pipeline.yaml

@@ -0,0 +1,84 @@
+id: route-demo-ref-io
+schemas:
+  empty:
+    type: object
+  doc:
+    type: object
+    required: [title, body]
+    properties:
+      title:
+        type: string
+        minLength: 1
+      body:
+        type: string
+      extras:
+        type: array
+        items:
+          type: string
+  analyzed:
+    type: object
+    required: [title, body, verdict]
+    properties:
+      title:
+        type: string
+        minLength: 1
+      body:
+        type: string
+      extras:
+        type: array
+        items:
+          type: string
+      verdict:
+        type: string
+        enum: [approve, request-changes]
+  title-only:
+    type: object
+    required: [title]
+    properties:
+      title:
+        type: string
+        minLength: 1
+  done:
+    type: object
+stages:
+  - id: draft
+    entry: true
+    route:
+      - to: review
+    system_prompt: |
+      Draft a document in one or two sentences.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and a payload matching #/schemas/doc: {"title":"Smoke doc","body":"A short body."}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/doc"
+  - id: review
+    route:
+      - to: ship
+    system_prompt: |
+      Keep the document fields and add a verdict of approve or request-changes.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and a payload matching #/schemas/analyzed: {"title":"Smoke doc","body":"A short body.","verdict":"approve"}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/doc"
+      output:
+        schema:
+          $ref: "#/schemas/analyzed"
+  - id: ship
+    system_prompt: |
+      Ship using title from the prior payload. 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:
+          $ref: "#/schemas/title-only"
+      output:
+        schema:
+          $ref: "#/schemas/done"

package/examples/route-wiring-smoke-test/14-if-eq-gating.pipeline.yaml

@@ -0,0 +1,50 @@
+id: route-demo-if-eq
+stages:
+  - id: triage
+    entry: true
+    route:
+      - to: page
+        if:
+          field: severity
+          op: eq
+          value: high
+      - to: notify
+    system_prompt: |
+      Triage in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {"severity": "low"}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+          required: [severity]
+          properties:
+            severity:
+              type: string
+  - id: page
+    system_prompt: |
+      Page on-call 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
+    system_prompt: |
+      Notify the team 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/15-if-all-gated.pipeline.yaml

@@ -0,0 +1,37 @@
+id: route-demo-if-all-gated
+stages:
+  - id: triage
+    entry: true
+    route:
+      - to: page
+        if:
+          field: severity
+          op: eq
+          value: high
+    system_prompt: |
+      Triage in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {"severity": "low"}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+          required: [severity]
+          properties:
+            severity:
+              type: string
+  - id: page
+    system_prompt: |
+      Page on-call 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/16-if-composition.pipeline.yaml

@@ -0,0 +1,65 @@
+id: route-demo-if-composition
+stages:
+  - id: triage
+    entry: true
+    route:
+      - to: page
+        if:
+          not:
+            all:
+              - field: severity
+                op: eq
+                value: low
+              - field: customer.tier
+                op: in
+                value: [bronze]
+      - to: notify
+    system_prompt: |
+      Triage in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {"severity": "low", "customer": {"tier": "bronze"}}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+          required: [severity, customer]
+          properties:
+            severity:
+              type: string
+            customer:
+              type: object
+              required: [tier]
+              properties:
+                tier:
+                  type: string
+  - id: page
+    system_prompt: |
+      Page on-call 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
+          required: [severity]
+          properties:
+            severity:
+              type: string
+      output:
+        schema:
+          type: object
+  - id: notify
+    system_prompt: |
+      Notify the team 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/17-if-join.pipeline.yaml

@@ -0,0 +1,80 @@
+id: route-demo-if-join
+# Two-parent Join gated by inbound `if`s. Each parent evaluates `if` against
+# its own output payload. Both match → assemble runs with both envelopes.
+# Either misses → assemble is skipped; the run still succeeds.
+stages:
+  - id: kickoff
+    entry: true
+    route:
+      - to: write
+      - to: draw
+    system_prompt: |
+      Kick off write and draw 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: write
+    route:
+      - to: assemble
+        if:
+          field: ready
+          op: eq
+          value: true
+    system_prompt: |
+      Write the first half in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {"ready": true}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+          required: [ready]
+          properties:
+            ready:
+              type: boolean
+
+  - id: draw
+    route:
+      - to: assemble
+        if:
+          field: complete
+          op: eq
+          value: true
+    system_prompt: |
+      Draw the second half in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {"complete": true}.
+    model: cursor/auto
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+          required: [complete]
+          properties:
+            complete:
+              type: boolean
+
+  - id: assemble
+    system_prompt: |
+      Combine both parents' work 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