stageflow 0.32.0 → 0.35.0

package/dist/workshop/workshopTranscriptTurn.js

@@ -0,0 +1,46 @@
+import { mutationSnapshotsFromProposals, } from "./sessionMutations.js";
+export function assistantTranscriptTextFromEvents(events) {
+    const parts = [];
+    for (const event of events) {
+        if (event.type === "message" && event.role === "assistant") {
+            parts.push(event.text);
+        }
+    }
+    return parts.join("\n\n").trim();
+}
+export function proposalPayloadsFromEvents(events) {
+    const proposals = [];
+    for (const event of events) {
+        if (event.type === "proposal") {
+            proposals.push(event.proposal);
+        }
+    }
+    return proposals;
+}
+export function transcriptMessagesForTurn(userMessage, attachments, events, options) {
+    const messages = [
+        {
+            role: "user",
+            text: userMessage,
+            ...(attachments.length > 0 ? { attachments: [...attachments] } : {}),
+        },
+    ];
+    for (const event of events) {
+        if (event.type === "message" && event.role !== "assistant") {
+            messages.push({ role: event.role, text: event.text });
+        }
+    }
+    const assistantText = assistantTranscriptTextFromEvents(events);
+    const proposals = proposalPayloadsFromEvents(events);
+    const mutations = proposals.length > 0
+        ? mutationSnapshotsFromProposals(proposals, options?.autoApply === true)
+        : [];
+    if (assistantText.length > 0 || mutations.length > 0) {
+        messages.push({
+            role: "assistant",
+            text: assistantText,
+            ...(mutations.length > 0 ? { mutations } : {}),
+        });
+    }
+    return messages;
+}

package/examples/README.md

@@ -14,7 +14,7 @@ Upgrading older YAML: [`sf migrate-yaml`](../docs/cli-reference.md#sf-migrate-ya
 
 - **Route `if`** — `detect-changes` emits `author_diagrams` and skips `author-diagrams` when the PR diff has no diagram-relevant types
 - **Multi-type output** — one pipeline authors 1–5 Archify diagram specs (`architecture`, `workflow`, `sequence`, `dataflow`, `lifecycle`)
-- **Skill binding** — `skill: archify` on the pipeline stage entry; GHA provisions the skill via `sf skills install`
+- **Skill binding** — `skill: archify` on the stage file; GHA provisions the skill via `sf skills install`
 - **Deterministic handoff** — agents emit JSON specs; GHA runs `sf envelope get --format handoff` and Archify `deliver` outside the agent
 - **Real automation** — [`.github/workflows/archify-pr-diagrams.yml`](../.github/workflows/archify-pr-diagrams.yml) posts sticky PR comments with browser-viewable HTML artifacts
 

package/examples/archify-on-pr/README.md

@@ -10,7 +10,7 @@ for GHA to deliver as HTML.
 |------|------|
 | `archify-on-pr.pipeline.yaml` | detect-changes Route `if` → author-diagrams; `verify` + `on_verify_fail` on detect |
 | `detect-changes.yaml` | Thin copy/emit from `ci-context.json` → `changes.json` + envelope |
-| `author-diagrams.yaml` | Writes `{type}.spec.json` per selected type (skill: archify on pipeline entry) |
+| `author-diagrams.yaml` | Writes `{type}.spec.json` per selected type (`skill: archify` on the stage file) |
 | `archify-on-pr.task.yaml` | Task bound at run time |
 | `../../scripts/prepare-ci-context.sh` | Deterministic PR/git context + diagram type selection before `sf run` |
 | `../../scripts/validate-detect-envelope.mjs` | Verify helper: `changes.json` / envelope match `ci-context.json` |

package/examples/archify-on-pr/archify-on-pr.pipeline.yaml

@@ -16,4 +16,3 @@ stages:
       include_failed_checks: true
   - id: author-diagrams
     uses: ./author-diagrams.yaml
-    skill: archify

package/examples/archify-on-pr/author-diagrams.yaml

@@ -1,4 +1,5 @@
 id: author-diagrams
+skill: archify
 system_prompt: |
   Author Archify diagram specs for every diagram type selected by detect-changes.
 

package/examples/conditional-fork/branch-a.yaml

@@ -3,7 +3,7 @@ system_prompt: |
   You are branch-a. Call emit_stage_envelope exactly once with status success,
   a short summary that acknowledges branch-a ran, and artifacts []. Do not call
   ask_operator.
-model: anthropic/claude-sonnet-4-5
+model: cursor/composer-2-5
 io:
   input:
     schema:

package/examples/conditional-fork/decide.yaml

@@ -29,7 +29,8 @@ io:
   output:
     schema:
       type: object
-      required: [branch]
+      required:
+        - branch
       properties:
         branch:
           type: string

package/examples/feature-loop/{implement.yaml → feature-implement.yaml}

@@ -1,4 +1,4 @@
-id: implement
+id: feature-implement
 system_prompt: |
   You are one sequential implementation clone among others. Work the way
   a compound-engineering ce-work run would: execute only your assigned

package/examples/feature-loop/feature-loop.pipeline.yaml

@@ -65,14 +65,14 @@ stages:
     clone_cap: 8
     clone_mode: parallel
     route:
-      - to: plan
+      - to: feature-plan
     on_verify_fail:
       mode: repair
       max_attempts: 3
       retry_safety: idempotent
       include_failed_checks: true
-  - id: plan
-    uses: ./plan.yaml
+  - id: feature-plan
+    uses: ./feature-plan.yaml
     route:
       - to: align
     on_verify_fail:
@@ -85,14 +85,14 @@ stages:
     clone_cap: 8
     clone_mode: sequential
     route:
-      - to: implement
+      - to: feature-implement
     on_verify_fail:
       mode: repair
       max_attempts: 3
       retry_safety: idempotent
       include_failed_checks: true
-  - id: implement
-    uses: ./implement.yaml
+  - id: feature-implement
+    uses: ./feature-implement.yaml
     route:
       - to: verify
     on_verify_fail:
@@ -103,14 +103,14 @@ stages:
   - id: verify
     uses: ./verify.yaml
     route:
-      - to: review
+      - to: feature-review
     on_verify_fail:
       mode: repair
       max_attempts: 3
       retry_safety: idempotent
       include_failed_checks: true
-  - id: review
-    uses: ./review.yaml
+  - id: feature-review
+    uses: ./feature-review.yaml
     route:
       - to: address-feedback
     on_verify_fail:
@@ -123,7 +123,7 @@ stages:
     route:
       - to: publish
       - type: loop
-        to: review
+        to: feature-review
         max_replays: 2
         on_max_replays: wait_for_human
         replay_session: new_session

package/examples/feature-loop/{plan.yaml → feature-plan.yaml}

@@ -1,4 +1,4 @@
-id: plan
+id: feature-plan
 system_prompt: |
   You are one planning clone among others. Write an implementation-ready
   plan for only the story in your assignment envelope. Work the way a

package/examples/feature-loop/{review.yaml → feature-review.yaml}

@@ -1,4 +1,4 @@
-id: review
+id: feature-review
 system_prompt: |
   Review the entire implementation as one change — every story's edits
   together, not per-story. Work the way a compound-engineering

package/examples/feedback-loop/{implement.yaml → feedback-implement.yaml}

@@ -1,4 +1,4 @@
-id: implement
+id: feedback-implement
 system_prompt: |
   Produce the work described by the upstream plan envelope.
   Keep the deliverable short (a brief outline or draft).

package/examples/feedback-loop/feedback-loop-wait-human.pipeline.yaml

@@ -1,23 +1,23 @@
 id: feedback-loop-wait-human
 stages:
-  - id: plan
+  - id: feedback-plan
     entry: true
     route:
-      - to: implement
-    uses: ./plan.yaml
-  - id: implement
+      - to: feedback-implement
+    uses: ./feedback-plan.yaml
+  - id: feedback-implement
     route:
-      - to: review
-    uses: ./implement.yaml
-  - id: review
+      - to: feedback-review
+    uses: ./feedback-implement.yaml
+  - id: feedback-review
     route:
       - to: submit
       - type: loop
-        to: implement
+        to: feedback-implement
         max_replays: 1
         on_max_replays: wait_for_human
         replay_session: resume
-    uses: ./review.yaml
+    uses: ./feedback-review.yaml
   - id: submit
     uses: ./submit.yaml
     replay_safe: false

package/examples/feedback-loop/feedback-loop.pipeline.yaml

@@ -1,23 +1,23 @@
 id: feedback-loop
 stages:
-  - id: plan
+  - id: feedback-plan
     entry: true
     route:
-      - to: implement
-    uses: ./plan.yaml
-  - id: implement
+      - to: feedback-implement
+    uses: ./feedback-plan.yaml
+  - id: feedback-implement
     route:
-      - to: review
-    uses: ./implement.yaml
-  - id: review
+      - to: feedback-review
+    uses: ./feedback-implement.yaml
+  - id: feedback-review
     route:
       - to: submit
       - type: loop
-        to: implement
+        to: feedback-implement
         max_replays: 2
         on_max_replays: require_continue
         replay_session: resume
-    uses: ./review.yaml
+    uses: ./feedback-review.yaml
   - id: submit
     uses: ./submit.yaml
     replay_safe: false

package/examples/feedback-loop/{plan.yaml → feedback-plan.yaml}

@@ -1,4 +1,4 @@
-id: plan
+id: feedback-plan
 system_prompt: |
   Create a short plan for the task goal.
   List the sections you will produce and any open questions.

package/examples/feedback-loop/{review.yaml → feedback-review.yaml}

@@ -1,4 +1,4 @@
-id: review
+id: feedback-review
 system_prompt: |
   Review the upstream work against the task goal.
   On success you MUST include feedback_loop in emit_stage_envelope:

package/examples/generic-fan-in/{research.yaml → fan-in-research.yaml}

@@ -1,4 +1,4 @@
-id: research
+id: fan-in-research
 system_prompt: |
   You are the research branch of a diamond join. Follow these steps exactly:
 

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

@@ -3,14 +3,14 @@ stages:
   - id: clarify
     entry: true
     route:
-      - to: research
+      - to: fan-in-research
       - to: validation
     uses: ./clarify.yaml
-  - id: research
+  - id: fan-in-research
     route:
       - to: synthesize
         on: [succeeded, failed, skipped]
-    uses: ./research.yaml
+    uses: ./fan-in-research.yaml
   - id: validation
     route:
       - to: synthesize

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

@@ -3,13 +3,13 @@ stages:
   - id: clarify
     entry: true
     route:
-      - to: research
+      - to: fan-in-research
       - to: validation
     uses: ./clarify.yaml
-  - id: research
+  - id: fan-in-research
     route:
       - to: synthesize
-    uses: ./research.yaml
+    uses: ./fan-in-research.yaml
   - id: validation
     route:
       - to: synthesize

package/examples/hello-world/{research.yaml → hello-research.yaml}

@@ -1,4 +1,4 @@
-id: research
+id: hello-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).

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

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

package/examples/mcp-hitl-tour/{review.yaml → mcp-hitl-review.yaml}

@@ -1,4 +1,4 @@
-id: review
+id: mcp-hitl-review
 system_prompt: |
   Review brief.md against the task goal.
   On every success you MUST emit feedback_loop send_back — never continue:

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

@@ -39,9 +39,9 @@ stages:
   - id: polish
     uses: ./polish.yaml
     route:
-      - to: review
-  - id: review
-    uses: ./review.yaml
+      - to: mcp-hitl-review
+  - id: mcp-hitl-review
+    uses: ./mcp-hitl-review.yaml
     route:
       - to: ship
       - type: loop

package/examples/oss-issue-contribution/oss-explain-fix.yaml

@@ -1,4 +1,5 @@
 id: oss-explain-fix
+skill: ce-explain
 system_prompt: |
   Compose fix-explainer.html teaching the operator how the verified working-tree
   change fixes the issue, grounded in real quoted diff lines. This stage is a

package/examples/oss-issue-contribution/oss-explain-issue.yaml

@@ -1,4 +1,5 @@
 id: oss-explain-issue
+skill: ce-explain
 system_prompt: |
   Produce one self-contained teaching artifact, issue-explainer.html, that
   explains this issue from the real checkout. This stage is a side teaching

package/examples/oss-issue-contribution/oss-issue-contribution.pipeline.yaml

@@ -13,7 +13,6 @@ stages:
       include_failed_checks: true
   - id: oss-explain-issue
     uses: ./oss-explain-issue.yaml
-    skill: ce-explain
     on_verify_fail:
       mode: repair
       max_attempts: 3
@@ -85,7 +84,6 @@ stages:
       include_failed_checks: true
   - id: oss-explain-fix
     uses: ./oss-explain-fix.yaml
-    skill: ce-explain
     on_verify_fail:
       mode: repair
       max_attempts: 3

package/examples/stageflow.yaml

@@ -21,6 +21,7 @@ catalog:
     - mcp-hitl-tour
     - feature-loop
     - ship-feature
+    - triggers-readiness
   tasks:
     - generic-fan-in
     - stage-mcp
@@ -42,9 +43,14 @@ catalog:
     - mcp-hitl-tour
     - feature-loop
     - ship-feature
+    - triggers-readiness
+  triggers:
+    - triggers
+    - triggers-readiness/triggers
   patterns:
     pipeline: "*.pipeline.yaml"
     task: "*.task.yaml"
+    trigger: "*.trigger.yaml"
   exclude:
     - route-wiring-smoke-test/rejected
     - stage-mcp/stage-mcp-dead.pipeline.yaml

package/examples/triggers/sample-github-pr.trigger.yaml

@@ -0,0 +1,12 @@
+id: sample-github-pr
+pipeline: hello
+task: my-task
+kind: event
+enabled: false
+event:
+  source: github.pull_request
+  match:
+    action: opened
+  config:
+    repo: tejasghutukade/software-factory
+    secretRef: GITHUB_TOKEN

package/examples/triggers/sample-inbox-email.trigger.yaml

@@ -0,0 +1,14 @@
+id: sample-inbox-email
+pipeline: hello
+task: my-task
+kind: event
+enabled: false
+event:
+  source: email.message
+  match:
+    subject: Invoice
+  config:
+    host: imap.example.com
+    port: 993
+    user: notifications@example.com
+    secretRef: EMAIL_PASSWORD

package/examples/triggers/sample-manual-hello.trigger.yaml

@@ -0,0 +1,5 @@
+id: sample-manual-hello
+pipeline: hello
+task: my-task
+kind: manual
+enabled: false

package/examples/triggers/sample-nightly-hello.trigger.yaml

@@ -0,0 +1,8 @@
+id: sample-nightly-hello
+pipeline: hello
+task: my-task
+kind: schedule
+enabled: false
+schedule:
+  cron: "0 2 * * *"
+  timezone: America/New_York

package/examples/triggers/sample-signed-webhook.trigger.yaml

@@ -0,0 +1,11 @@
+id: sample-signed-webhook
+pipeline: hello
+task: my-task
+kind: event
+enabled: false
+event:
+  source: webhook
+  config:
+    secretRef: WEBHOOK_SECRET
+    header: x-hub-signature-256
+    scheme: hex

package/examples/triggers-readiness/README.md

@@ -0,0 +1,48 @@
+# Triggers readiness smoke catalog
+
+Self-contained catalog for [Triggers readiness](../../docs/triggers-readiness.md). One trigger per checklist row, all targeting the minimal `readiness` pipeline.
+
+| Trigger id | Kind | Default `enabled` | How to test |
+|------------|------|-------------------|-------------|
+| `readiness-manual` | manual | **true** | Triggers → **Fire** (or `sf trigger fire --run readiness-manual` via API id) |
+| `readiness-schedule` | schedule | false | Enable in UI; cron `*/5 * * * *` UTC; needs Host scheduler |
+| `readiness-github-pr` | event (`github.pull_request`) | false | Set `event.config.repo`, enable; needs `GITHUB_TOKEN` on Host |
+| `readiness-webhook` | event (`webhook`) | false | Set `WEBHOOK_SECRET` on Host, enable; `POST /api/triggers/readiness-webhook/webhook` |
+| `readiness-email` | event (`email.message`) | false | Edit IMAP `config`, set `EMAIL_PASSWORD`, enable; restart Host after create |
+| `readiness-dynamic-manual` | manual (no `task`) | false | UI **Fire** disabled; `sf trigger fire readiness-dynamic-manual --task-inline '{"id":"t","goal":"Dynamic smoke"}'` |
+
+## Validate and run pipeline (no trigger)
+
+From the repository root:
+
+```bash
+sf validate --strict \
+  --pipeline examples/triggers-readiness/readiness.pipeline.yaml \
+  --task examples/triggers-readiness/readiness.task.yaml
+sf run \
+  --pipeline examples/triggers-readiness/readiness.pipeline.yaml \
+  --task examples/triggers-readiness/readiness.task.yaml
+```
+
+## Docker Compose
+
+The image copies this tree to `/opt/stageflow/catalog/triggers-readiness` and registers it via `STAGEFLOW_ENSURE_PROJECT_ROOTS`. After `docker compose up --build -d`, open **Triggers** — you should see six `readiness-*` triggers.
+
+Optional `.env` for event triggers:
+
+```bash
+GITHUB_TOKEN=…          # readiness-github-pr
+WEBHOOK_SECRET=…        # readiness-webhook (use a long random string)
+EMAIL_PASSWORD=…        # readiness-email (after you point config at a real mailbox)
+```
+
+Webhook smoke (replace secret and use the trigger id from the console if namespaced):
+
+```bash
+BODY='{"hello":"triggers"}'
+SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')
+curl -sS -X POST "http://127.0.0.1:3847/api/triggers/readiness-webhook/webhook" \
+  -H "Content-Type: application/json" \
+  -H "x-hub-signature-256: $SIG" \
+  -d "$BODY"
+```

package/examples/triggers-readiness/readiness-emit.yaml

@@ -0,0 +1,18 @@
+id: readiness-emit
+system_prompt: |
+  You are a trigger smoke-test stage. Reply with one short acknowledgment, then call emit_stage_envelope once with
+  status: success, a non-empty summary, artifacts: [], and payload: { "trigger_test": true }.
+io:
+  input:
+    schema:
+      type: object
+      additionalProperties: true
+  output:
+    schema:
+      type: object
+      required:
+        - trigger_test
+      properties:
+        trigger_test:
+          type: boolean
+      additionalProperties: false

package/examples/triggers-readiness/readiness.pipeline.yaml

@@ -0,0 +1,4 @@
+id: readiness
+stages:
+  - id: readiness-emit
+    uses: ./readiness-emit.yaml

package/examples/triggers-readiness/readiness.task.yaml

@@ -0,0 +1,6 @@
+id: readiness-task
+goal: Acknowledge a triggers-readiness smoke run
+context: Fired from the triggers-readiness catalog bundle (Docker or examples/)
+constraints: One stage only; emit a success envelope
+input:
+  source: triggers-readiness

package/examples/triggers-readiness/stageflow.yaml

@@ -0,0 +1,13 @@
+version: 1
+model: cursor/auto
+catalog:
+  pipelines:
+    - .
+  tasks:
+    - .
+  triggers:
+    - triggers
+  patterns:
+    pipeline: "*.pipeline.yaml"
+    task: "*.task.yaml"
+    trigger: "*.trigger.yaml"

package/examples/triggers-readiness/triggers/readiness-dynamic-manual.trigger.yaml

@@ -0,0 +1,4 @@
+id: readiness-dynamic-manual
+pipeline: readiness
+kind: manual
+enabled: false

package/examples/triggers-readiness/triggers/readiness-email.trigger.yaml

@@ -0,0 +1,12 @@
+id: readiness-email
+pipeline: readiness
+task: readiness-task
+kind: event
+enabled: false
+event:
+  source: email.message
+  config:
+    host: imap.example.com
+    port: 993
+    user: notifications@example.com
+    secretRef: EMAIL_PASSWORD

package/examples/triggers-readiness/triggers/readiness-github-pr.trigger.yaml

@@ -0,0 +1,12 @@
+id: readiness-github-pr
+pipeline: readiness
+task: readiness-task
+kind: event
+enabled: false
+event:
+  source: github.pull_request
+  match:
+    action: opened
+  config:
+    repo: tejasghutukade/stageflow
+    secretRef: GITHUB_TOKEN

package/examples/triggers-readiness/triggers/readiness-manual.trigger.yaml

@@ -0,0 +1,5 @@
+id: readiness-manual
+pipeline: readiness
+task: readiness-task
+kind: manual
+enabled: true

package/examples/triggers-readiness/triggers/readiness-schedule.trigger.yaml

@@ -0,0 +1,8 @@
+id: readiness-schedule
+pipeline: readiness
+task: readiness-task
+kind: schedule
+enabled: false
+schedule:
+  cron: "*/5 * * * *"
+  timezone: UTC

package/examples/triggers-readiness/triggers/readiness-webhook.trigger.yaml

@@ -0,0 +1,11 @@
+id: readiness-webhook
+pipeline: readiness
+task: readiness-task
+kind: event
+enabled: false
+event:
+  source: webhook
+  config:
+    secretRef: WEBHOOK_SECRET
+    header: x-hub-signature-256
+    scheme: hex

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "stageflow",
-  "version": "0.32.0",
+  "version": "0.35.0",
   "description": "Stageflow — CLI pipeline runtime for configurable stages on Pi",
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "bin": {
     "sf": "./dist/cli.js",
     "stageflow": "./dist/cli.js"