npm - stageflow - Versions diffs - 0.3.0 → 0.9.0 - Mend

stageflow 0.3.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (164) hide show

package/README.md +44 -14
package/dist/agent/activity.d.ts +2 -0
package/dist/agent/cursorProvider.d.ts +1 -10
package/dist/agent/cursorProvider.js +18 -10
package/dist/agent/fakeAgent.js +11 -7
package/dist/agent/piAdapter.d.ts +2 -1
package/dist/agent/piAdapter.js +28 -25
package/dist/agent/port.d.ts +6 -1
package/dist/agent/port.js +3 -0
package/dist/cli/artifactCommand.d.ts +10 -0
package/dist/cli/artifactCommand.js +120 -0
package/dist/cli/envelopeCommand.d.ts +32 -0
package/dist/cli/envelopeCommand.js +285 -0
package/dist/cli/exportRunCommand.d.ts +10 -0
package/dist/cli/exportRunCommand.js +150 -0
package/dist/cli/handoffFormat.d.ts +22 -0
package/dist/cli/handoffFormat.js +61 -0
package/dist/cli/runCommand.d.ts +5 -1
package/dist/cli/runCommand.js +36 -5
package/dist/cli/runOutput.d.ts +4 -1
package/dist/cli/runOutput.js +36 -8
package/dist/cli/runsCommand.d.ts +22 -0
package/dist/cli/runsCommand.js +591 -0
package/dist/cli/skillsCommand.d.ts +16 -0
package/dist/cli/skillsCommand.js +459 -0
package/dist/cli/validateOutput.d.ts +2 -2
package/dist/cli/validateOutput.js +2 -2
package/dist/cli.js +110 -5
package/dist/config/loadPipeline.js +5 -1
package/dist/config/normalizePipelineStageEntry.d.ts +2 -0
package/dist/config/normalizePipelineStageEntry.js +25 -1
package/dist/config/pipelineStageKeys.js +1 -1
package/dist/config/resolveForkEmitContext.d.ts +2 -1
package/dist/config/resolveForkEmitContext.js +23 -1
package/dist/config/resolvePipelineDag.js +36 -4
package/dist/envelope/check.d.ts +2 -0
package/dist/envelope/check.js +51 -0
package/dist/envelope/cloneForks.d.ts +2 -0
package/dist/envelope/cloneForks.js +62 -0
package/dist/envelope/forkChoice.js +1 -1
package/dist/index.d.ts +3 -1
package/dist/index.js +3 -1
package/dist/mcp/catalogTools.d.ts +3 -0
package/dist/mcp/catalogTools.js +187 -0
package/dist/mcp/controlTools.d.ts +3 -0
package/dist/mcp/controlTools.js +147 -0
package/dist/mcp/deps.d.ts +11 -0
package/dist/mcp/deps.js +1 -0
package/dist/mcp/projectRun.d.ts +1 -40
package/dist/mcp/projectRun.js +1 -64
package/dist/mcp/resources.d.ts +5 -0
package/dist/mcp/resources.js +45 -0
package/dist/mcp/server.d.ts +16 -3
package/dist/mcp/server.js +159 -3
package/dist/mcp/toolResults.d.ts +7 -0
package/dist/mcp/toolResults.js +6 -0
package/dist/mcp/tools.d.ts +2 -7
package/dist/mcp/tools.js +52 -103
package/dist/mcp/waitRun.d.ts +46 -0
package/dist/mcp/waitRun.js +146 -0
package/dist/mcp/waitingGates.d.ts +12 -0
package/dist/mcp/waitingGates.js +83 -0
package/dist/package-meta.d.ts +1 -0
package/dist/package-meta.js +1 -0
package/dist/projection/projectRun.d.ts +44 -0
package/dist/projection/projectRun.js +71 -0
package/dist/prompt/priorEnvelope.d.ts +1 -1
package/dist/prompt/priorEnvelope.js +4 -1
package/dist/runstore/paths.js +2 -0
package/dist/runstore/pipelineDagSnapshot.d.ts +9 -0
package/dist/runstore/pipelineDagSnapshot.js +90 -1
package/dist/runstore/port.d.ts +13 -2
package/dist/runstore/port.js +4 -1
package/dist/runstore/runProjection.d.ts +1 -1
package/dist/runstore/runProjection.js +14 -3
package/dist/runstore/sqlite/SqliteRunStore.d.ts +3 -2
package/dist/runstore/sqlite/SqliteRunStore.js +35 -3
package/dist/runstore/stageInstanceId.d.ts +4 -0
package/dist/runstore/stageInstanceId.js +23 -0
package/dist/runstore/syntheticStageSnapshot.d.ts +1 -1
package/dist/runstore/syntheticStageSnapshot.js +2 -1
package/dist/runstore/trackProjection.js +28 -12
package/dist/runstore/workspaceLayout.d.ts +1 -0
package/dist/runstore/workspaceLayout.js +1 -1
package/dist/runtime/cloneSchedule.d.ts +18 -0
package/dist/runtime/cloneSchedule.js +233 -0
package/dist/runtime/envelopeRouting.d.ts +2 -1
package/dist/runtime/envelopeRouting.js +80 -13
package/dist/runtime/pipelineScheduler.d.ts +6 -2
package/dist/runtime/pipelineScheduler.js +166 -30
package/dist/runtime/resumeReconstruct.js +8 -3
package/dist/runtime/runChangeBus.d.ts +18 -0
package/dist/runtime/runChangeBus.js +83 -0
package/dist/runtime/runManager.d.ts +7 -0
package/dist/runtime/runManager.js +31 -2
package/dist/runtime/runRetryCoordinator.d.ts +2 -0
package/dist/runtime/runRetryCoordinator.js +4 -1
package/dist/runtime/stageAttemptBootstrap.d.ts +1 -0
package/dist/runtime/stageAttemptBootstrap.js +17 -9
package/dist/runtime/stageRunner.d.ts +1 -0
package/dist/runtime/stageRunner.js +17 -15
package/dist/runtime/stageWorker.js +11 -4
package/dist/server/bootstrap.d.ts +32 -0
package/dist/server/bootstrap.js +56 -0
package/dist/server/createHttpHost.d.ts +34 -0
package/dist/server/createHttpHost.js +70 -0
package/dist/server/http.d.ts +6 -13
package/dist/server/http.js +295 -374
package/dist/server/mcpHost.d.ts +22 -0
package/dist/server/mcpHost.js +21 -0
package/dist/server/operatorResults.d.ts +13 -0
package/dist/server/operatorResults.js +22 -0
package/dist/tools/emitStageEnvelope.d.ts +11 -2
package/dist/tools/emitStageEnvelope.js +22 -6
package/dist/types/envelope.d.ts +2 -0
package/dist/types/forkChoice.d.ts +22 -0
package/dist/types/pipeline.d.ts +8 -0
package/dist/ui/assets/{index-DefBlEvN.css → index-C3N7MXAC.css} +1 -1
package/dist/ui/assets/index-CSoGDA3A.js +118 -0
package/dist/ui/index.html +2 -2
package/package.json +2 -1
package/skills/install-suite.sh +107 -0
package/skills/stageflow/SKILL.md +26 -0
package/skills/stageflow/references/control-surface.md +28 -0
package/skills/stageflow/scripts/detect-host.mjs +54 -0
package/skills/stageflow/scripts/detect-host.test.mjs +97 -0
package/skills/stageflow-author/SKILL.md +58 -0
package/skills/stageflow-author/assets/examples/branch-decision/hotfix.yaml +10 -0
package/skills/stageflow-author/assets/examples/branch-decision/release-gate.pipeline.yaml +12 -0
package/skills/stageflow-author/assets/examples/branch-decision/run-tests.yaml +13 -0
package/skills/stageflow-author/assets/examples/branch-decision/ship.yaml +10 -0
package/skills/stageflow-author/assets/examples/linear-review/draft.yaml +9 -0
package/skills/stageflow-author/assets/examples/linear-review/publish.yaml +10 -0
package/skills/stageflow-author/assets/examples/linear-review/review-loop.pipeline.yaml +10 -0
package/skills/stageflow-author/assets/examples/linear-review/review.yaml +15 -0
package/skills/stageflow-author/assets/examples/non-sdlc-digest/gather.yaml +9 -0
package/skills/stageflow-author/assets/examples/non-sdlc-digest/research-digest.pipeline.yaml +10 -0
package/skills/stageflow-author/assets/examples/non-sdlc-digest/send.yaml +10 -0
package/skills/stageflow-author/assets/examples/non-sdlc-digest/summarize.yaml +9 -0
package/skills/stageflow-author/references/catalog-mapping.md +131 -0
package/skills/stageflow-author/references/catalog-write-conventions.md +29 -0
package/skills/stageflow-author/references/stage-prompt-template.md +55 -0
package/skills/stageflow-author/references/validate-and-report.md +38 -0
package/skills/stageflow-delegate/SKILL.md +18 -0
package/skills/stageflow-delegate/references/authoring-or-run.md +15 -0
package/skills/stageflow-delegate/references/example-walkthrough.md +30 -0
package/skills/stageflow-delegate/references/pattern-detection.md +44 -0
package/skills/stageflow-run/SKILL.md +182 -0
package/skills/stageflow-run/references/mcp-call.md +17 -0
package/skills/stageflow-run/references/native-question-ui.md +78 -0
package/skills/stageflow-run/references/task-and-pipeline-selection.md +52 -0
package/skills/stageflow-run/scripts/mcp-call.mjs +299 -0
package/skills/stageflow-run/scripts/mcp-call.test.mjs +271 -0
package/skills/stageflow-session-capture/SKILL.md +94 -0
package/skills/stageflow-session-capture/assets/example-pipeline/example.pipeline.yaml +7 -0
package/skills/stageflow-session-capture/assets/example-pipeline/implement.yaml +8 -0
package/skills/stageflow-session-capture/assets/example-pipeline/research.yaml +8 -0
package/skills/stageflow-session-capture/references/catalog-authoring.md +40 -0
package/skills/stageflow-session-capture/references/transcript-sources.md +25 -0
package/skills/stageflow-session-capture/scripts/check-provider-gate.mjs +43 -0
package/skills/stageflow-session-capture/scripts/locate-session-transcript.mjs +141 -0
package/skills/stageflow-session-capture/scripts/resolve-catalog-id.mjs +119 -0
package/skills/stageflow-setup/SKILL.md +110 -0
package/dist/ui/assets/index-CFSzDZje.js +0 -118

package/dist/ui/index.html CHANGED Viewed

@@ -13,8 +13,8 @@
     <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Figtree:wght@400;500;600;700&display=swap" />
     <link rel="icon" type="image/svg+xml" href="/stageflow-icon.svg" />
     <title>Stageflow</title>
-    <script type="module" crossorigin src="/assets/index-CFSzDZje.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-DefBlEvN.css">
+    <script type="module" crossorigin src="/assets/index-CSoGDA3A.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-C3N7MXAC.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "stageflow",
-  "version": "0.3.0",
+  "version": "0.9.0",
   "description": "Stageflow — CLI pipeline runtime for configurable stages on Pi",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/install-suite.sh ADDED Viewed

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SOURCE_DIR="$SCRIPT_DIR"
+DEST_ROOT="$(pwd)"
+SKILLS=(
+  stageflow
+  stageflow-setup
+  stageflow-session-capture
+  stageflow-author
+  stageflow-run
+  stageflow-delegate
+)
+TARGETS=(
+  .cursor/skills
+  .claude/skills
+  .agents/skills
+)
+usage() {
+  cat <<'EOF'
+Usage: install-suite.sh [--source-dir PATH] [--dest-cwd PATH]
+Copy the Stageflow harness skills suite into a project's
+.cursor/skills/, .claude/skills/, and .agents/skills/.
+Options:
+  --source-dir PATH   Canonical skills tree (default: this script's directory)
+  --dest-cwd PATH     Project root to install into (default: current directory)
+EOF
+}
+err() {
+  echo "install-suite: $*" >&2
+}
+parse_args() {
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --source-dir)
+        SOURCE_DIR="${2:?--source-dir requires a path}"
+        shift 2
+        ;;
+      --dest-cwd)
+        DEST_ROOT="${2:?--dest-cwd requires a path}"
+        shift 2
+        ;;
+      -h|--help)
+        usage
+        exit 0
+        ;;
+      *)
+        err "unknown argument: $1"
+        usage >&2
+        exit 1
+        ;;
+    esac
+  done
+}
+resolve_paths() {
+  if [ ! -d "$SOURCE_DIR" ]; then
+    err "source directory not found: $SOURCE_DIR"
+    exit 1
+  fi
+  SOURCE_DIR="$(cd "$SOURCE_DIR" && pwd)"
+  if [ ! -d "$DEST_ROOT" ]; then
+    err "destination directory not found: $DEST_ROOT"
+    exit 1
+  fi
+  DEST_ROOT="$(cd "$DEST_ROOT" && pwd)"
+  local expected="${SOURCE_DIR}/stageflow/SKILL.md"
+  if [ ! -f "$expected" ]; then
+    err "source directory missing stageflow/SKILL.md: ${expected}"
+    exit 1
+  fi
+}
+copy_suite() {
+  local target skill
+  for target in "${TARGETS[@]}"; do
+    mkdir -p "${DEST_ROOT}/${target}"
+    for skill in "${SKILLS[@]}"; do
+      rm -rf "${DEST_ROOT}/${target}/${skill}"
+      cp -R "${SOURCE_DIR}/${skill}" "${DEST_ROOT}/${target}/${skill}"
+    done
+  done
+}
+main() {
+  parse_args "$@"
+  resolve_paths
+  copy_suite
+  echo "Installed Stageflow skills suite"
+  echo "Source: ${SOURCE_DIR}"
+  for target in "${TARGETS[@]}"; do
+    echo "${DEST_ROOT}/${target}"
+  done
+}
+main "$@"

package/skills/stageflow/SKILL.md ADDED Viewed

@@ -0,0 +1,26 @@
+---
+name: stageflow
+description: >-
+  Routes Stageflow work to one job: setup (install, catalog, or provider),
+  session-capture (reuse this chat or a past session), author (a loop the human
+  can explain), run (start, watch, or answer a pipeline), or delegate (a
+  repeating pattern). Use when the user mentions Stageflow, sf, a pipeline,
+  HITL, or a repeating Stageflow workflow.
+compatibility: Requires the Stageflow CLI (sf). An MCP host (sf ui or sf mcp) is optional.
+---
+# Stageflow
+Read [references/control-surface.md](references/control-surface.md) before talking to a run. Probe with [scripts/detect-host.mjs](scripts/detect-host.mjs). Do not restate that policy here.
+Read the matching job `SKILL.md` and follow it. Do not invent job behavior in this router.
+| Reach this job when | Read |
+|---|---|
+| Install is missing, there is no catalog, or a provider is not logged in | [../stageflow-setup/SKILL.md](../stageflow-setup/SKILL.md) |
+| The request should reuse a past session or this chat | [../stageflow-session-capture/SKILL.md](../stageflow-session-capture/SKILL.md) |
+| The request describes a loop the human can explain | [../stageflow-author/SKILL.md](../stageflow-author/SKILL.md) |
+| The request needs to start, watch, or answer a run | [../stageflow-run/SKILL.md](../stageflow-run/SKILL.md) |
+| The request repeats a known pattern, or could become one | [../stageflow-delegate/SKILL.md](../stageflow-delegate/SKILL.md) |
+If none of those fit, name the five jobs in one line and ask which.

package/skills/stageflow/references/control-surface.md ADDED Viewed

@@ -0,0 +1,28 @@
+# Control surface
+Prefer MCP when a Stageflow host is up. Otherwise use the CLI. This file is the only copy of that rule; job skills cite it instead of restating it.
+## Probe
+Run [../scripts/detect-host.mjs](../scripts/detect-host.mjs). Do not write a second probe.
+```bash
+node ../scripts/detect-host.mjs
+node ../scripts/detect-host.mjs --base-url http://127.0.0.1:3847
+```
+The script `GET`s `{baseUrl}/api/health` (default `http://127.0.0.1:3847`, 1500 ms timeout). **up** means HTTP 200 and parseable JSON. Non-200, non-JSON, or timeout is **down**. This probe is Stageflow host up/down only — it does not detect a coding-agent question UI. Gate presentation lives in [`../../stageflow-run/references/native-question-ui.md`](../../stageflow-run/references/native-question-ui.md).
+Stdout is one line: `up <baseUrl>` or `down <baseUrl>`. Exit `0` when up, `1` when down, `2` on usage error.
+Start a host with `sf ui` or `sf mcp` when the user wants MCP. Do not auto-start one.
+## When the host is up
+Use MCP tools over the Streamable HTTP endpoint at `{baseUrl}/mcp`. Tool names and payloads live in [docs/mcp.md](../../../docs/mcp.md). Typical talking-job tools: `list_pipelines`, `list_tasks`, `start_run`, `get_run`, `wait_run`, `list_waiting`, `answer_gate`, `get_envelope`, `read_artifact`, `validate`, `get_health`.
+## When the host is down
+Use the `sf` CLI. Command names and flags live in [docs/cli-reference.md](../../../docs/cli-reference.md). Typical talking-job commands: `sf run`, `sf runs waiting`, `sf runs answer`, `sf runs wait`, `sf validate`, `sf envelope get`, `sf artifact read`, `sf providers`.
+Probe before each mutating `sf runs` verb. If the probe is **up** or the command refuses because a host is up, continue that gate via MCP — do not start a second mutating writer, and do not start `sf mcp` as a disposable bridge.

package/skills/stageflow/scripts/detect-host.mjs ADDED Viewed

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+const DEFAULT_BASE_URL = "http://127.0.0.1:3847";
+const TIMEOUT_MS = 1500;
+function usage() {
+  return "Usage: detect-host.mjs [--base-url URL]";
+}
+function parseArgs(argv) {
+  let baseUrl = DEFAULT_BASE_URL;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      console.log(usage());
+      process.exit(0);
+    }
+    if (arg === "--base-url") {
+      const value = argv[i + 1];
+      if (!value) {
+        console.error("detect-host: --base-url requires a URL");
+        console.error(usage());
+        process.exit(2);
+      }
+      baseUrl = value.replace(/\/$/, "");
+      i += 1;
+      continue;
+    }
+    console.error(`detect-host: unknown argument: ${arg}`);
+    console.error(usage());
+    process.exit(2);
+  }
+  return { baseUrl };
+}
+async function probe(baseUrl) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(`${baseUrl}/api/health`, { signal: ac.signal });
+    if (res.status !== 200) return "down";
+    JSON.parse(await res.text());
+    return "up";
+  } catch {
+    return "down";
+  } finally {
+    clearTimeout(timer);
+  }
+}
+const { baseUrl } = parseArgs(process.argv.slice(2));
+const status = await probe(baseUrl);
+console.log(`${status} ${baseUrl}`);
+process.exit(status === "up" ? 0 : 1);

package/skills/stageflow/scripts/detect-host.test.mjs ADDED Viewed

@@ -0,0 +1,97 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "detect-host.mjs");
+function run(baseUrl) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [script, "--base-url", baseUrl], {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("close", (status) => {
+      resolve({ status, stdout, stderr });
+    });
+  });
+}
+function listen(handler) {
+  return new Promise((resolve) => {
+    const server = createServer(handler);
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      resolve({ server, baseUrl: `http://127.0.0.1:${addr.port}` });
+    });
+  });
+}
+test("classifies reachable 200 JSON /api/health as up", async () => {
+  const { server, baseUrl } = await listen((req, res) => {
+    if (req.url === "/api/health") {
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ ok: true }));
+      return;
+    }
+    res.writeHead(404);
+    res.end();
+  });
+  try {
+    const result = await run(baseUrl);
+    assert.equal(result.status, 0);
+    assert.equal(result.stdout.trim(), `up ${baseUrl}`);
+  } finally {
+    server.close();
+  }
+});
+test("classifies non-200 /api/health as down", async () => {
+  const { server, baseUrl } = await listen((_req, res) => {
+    res.writeHead(503, { "content-type": "application/json" });
+    res.end(JSON.stringify({ ok: false }));
+  });
+  try {
+    const result = await run(baseUrl);
+    assert.equal(result.status, 1);
+    assert.equal(result.stdout.trim(), `down ${baseUrl}`);
+  } finally {
+    server.close();
+  }
+});
+test("classifies 200 non-JSON /api/health as down", async () => {
+  const { server, baseUrl } = await listen((_req, res) => {
+    res.writeHead(200, { "content-type": "text/plain" });
+    res.end("ok");
+  });
+  try {
+    const result = await run(baseUrl);
+    assert.equal(result.status, 1);
+    assert.equal(result.stdout.trim(), `down ${baseUrl}`);
+  } finally {
+    server.close();
+  }
+});
+test("classifies a hung /api/health as down", async () => {
+  const { server, baseUrl } = await listen(() => {});
+  try {
+    const result = await run(baseUrl);
+    assert.equal(result.status, 1);
+    assert.equal(result.stdout.trim(), `down ${baseUrl}`);
+  } finally {
+    server.close();
+  }
+});

package/skills/stageflow-author/SKILL.md ADDED Viewed

@@ -0,0 +1,58 @@
+---
+name: stageflow-author
+description: >-
+  Turns a described structure or repeatable loop into a reusable Stageflow
+  pipeline and one stage YAML per step in the project catalog. Use when a
+  human explains steps, sequencing, a decision point, or a review they want
+  to reuse.
+compatibility: Requires the sf CLI on PATH
+disable-model-invocation: true
+---
+# Stageflow author
+Turn a structure a human can explain into one pipeline YAML file and one stage YAML file per step. `stageflow-run` owns starting a run and any throwaway task.
+Talking jobs cite [`../stageflow/references/control-surface.md`](../stageflow/references/control-surface.md). Probe with [`../stageflow/scripts/detect-host.mjs`](../stageflow/scripts/detect-host.mjs) only when choosing MCP `validate` — see [`references/validate-and-report.md`](references/validate-and-report.md). Do not write a second probe.
+Shape reference: [`assets/examples/linear-review/`](assets/examples/linear-review/), [`assets/examples/branch-decision/`](assets/examples/branch-decision/), [`assets/examples/non-sdlc-digest/`](assets/examples/non-sdlc-digest/).
+## Provider gate
+Run before any catalog write:
+```
+sf providers status
+```
+A provider counts when a row's second column is `configured`. **Done when** at least one row is `configured`. If none are, or the command fails, stop. Write nothing. Name `stageflow-setup`. Do not run `sf providers login`.
+## Elicit
+Ask until you can name every step, how they sequence, any decision point, and any review or sign-off. Confirm that mapped summary with the human before writing.
+**Done when** the human agrees the step list, sequencing, decisions, and review points.
+## Map
+Read [`references/catalog-mapping.md`](references/catalog-mapping.md). Apply those rules to the confirmed structure. Read [`references/stage-prompt-template.md`](references/stage-prompt-template.md) for each stage's `system_prompt`, `model`, and `gate_kinds`.
+**Done when** you have a pipeline id, one stage id per step, `needs` / `fork` wiring, and a prompt plan per stage.
+## Locate
+Read [`references/catalog-write-conventions.md`](references/catalog-write-conventions.md). Resolve the write directory and check every candidate pipeline and stage id against files already there.
+**Done when** every id is free, or the human has given a different id.
+## Write
+Write one external stage YAML per step and one pipeline YAML that wires them with `uses: ./<id>.yaml`. Use the native Write tool. Do not call `createPipeline` or `createStage`. Do not write a `*.task.yaml`.
+**Done when** the pipeline file and every stage file exist on disk.
+## Validate and report
+Read [`references/validate-and-report.md`](references/validate-and-report.md). Follow it to the end.
+**Done when** that file's success report is printed.

package/skills/stageflow-author/assets/examples/branch-decision/hotfix.yaml ADDED Viewed

@@ -0,0 +1,10 @@
+id: hotfix
+system_prompt: |
+  Take the failing results from the prior envelope and repair the work they
+  describe.
+  Write the repair notes via write_stage_artifact (for example hotfix.md).
+  When finished, call emit_stage_envelope exactly once with status, summary,
+  artifacts, and a payload describing what you repaired.
+model: anthropic/claude-sonnet-4-5

package/skills/stageflow-author/assets/examples/branch-decision/release-gate.pipeline.yaml ADDED Viewed

@@ -0,0 +1,12 @@
+id: release-gate
+stages:
+  - id: run-tests
+    uses: ./run-tests.yaml
+    fork:
+      select: one
+  - id: hotfix
+    uses: ./hotfix.yaml
+    needs: run-tests
+  - id: ship
+    uses: ./ship.yaml
+    needs: run-tests

package/skills/stageflow-author/assets/examples/branch-decision/run-tests.yaml ADDED Viewed

@@ -0,0 +1,13 @@
+id: run-tests
+system_prompt: |
+  Assess whether the current work is ready to ship.
+  Write the results via write_stage_artifact (for example results.md).
+  When finished, call emit_stage_envelope exactly once with status, summary,
+  artifacts, and a payload the next stage can use.
+  On a success emit, include fork_choice naming immediate successor id(s) that
+  should run. Name only ids listed as this stage's children. select: one →
+  exactly one id: hotfix when the results fail, ship when they pass.
+model: anthropic/claude-sonnet-4-5

package/skills/stageflow-author/assets/examples/branch-decision/ship.yaml ADDED Viewed

@@ -0,0 +1,10 @@
+id: ship
+system_prompt: |
+  Take the passing results from the prior envelope and produce the shippable
+  package.
+  Write the package notes via write_stage_artifact (for example ship.md).
+  When finished, call emit_stage_envelope exactly once with status, summary,
+  artifacts, and a payload describing what you shipped.
+model: anthropic/claude-sonnet-4-5

package/skills/stageflow-author/assets/examples/linear-review/draft.yaml ADDED Viewed

@@ -0,0 +1,9 @@
+id: draft
+system_prompt: |
+  Produce a concise draft of the document described in the task.
+  Write the draft via write_stage_artifact (for example draft.md).
+  When finished, call emit_stage_envelope exactly once with status, summary,
+  artifacts, and a payload the next stage can use.
+model: anthropic/claude-sonnet-4-5

package/skills/stageflow-author/assets/examples/linear-review/publish.yaml ADDED Viewed

@@ -0,0 +1,10 @@
+id: publish
+system_prompt: |
+  Take the accepted draft and review from prior envelopes and produce the
+  version that goes out.
+  Write that version via write_stage_artifact (for example published.md).
+  When finished, call emit_stage_envelope exactly once with status, summary,
+  artifacts, and a payload describing what you produced.
+model: anthropic/claude-sonnet-4-5

package/skills/stageflow-author/assets/examples/linear-review/review-loop.pipeline.yaml ADDED Viewed

@@ -0,0 +1,10 @@
+id: review-loop
+stages:
+  - id: draft
+    uses: ./draft.yaml
+  - id: review
+    uses: ./review.yaml
+    needs: draft
+  - id: publish
+    uses: ./publish.yaml
+    needs: review

package/skills/stageflow-author/assets/examples/linear-review/review.yaml ADDED Viewed

@@ -0,0 +1,15 @@
+id: review
+gate_kinds:
+  - artifact_backed
+system_prompt: |
+  Review the draft from the prior stage and get operator acceptance before
+  completing this stage.
+  1. Write a concise review via write_stage_artifact (for example review.md).
+  2. Call ask_operator with kind artifact_backed referencing that artifact path
+     so the operator can review it.
+  3. On reject or change text: revise the review artifact and call ask_operator
+     again with artifact_backed in this same stage. Do not complete yet.
+  4. Call emit_stage_envelope with an advancing success status only after the
+     operator accepts. Never emit before accept.
+model: anthropic/claude-sonnet-4-5

package/skills/stageflow-author/assets/examples/non-sdlc-digest/gather.yaml ADDED Viewed

@@ -0,0 +1,9 @@
+id: gather
+system_prompt: |
+  Collect the sources named in the incoming goal for this week's digest.
+  Write the collected notes via write_stage_artifact (for example sources.md).
+  When finished, call emit_stage_envelope exactly once with status, summary,
+  artifacts, and a payload the next stage can use.
+model: anthropic/claude-sonnet-4-5

package/skills/stageflow-author/assets/examples/non-sdlc-digest/research-digest.pipeline.yaml ADDED Viewed

@@ -0,0 +1,10 @@
+id: research-digest
+stages:
+  - id: gather
+    uses: ./gather.yaml
+  - id: summarize
+    uses: ./summarize.yaml
+    needs: gather
+  - id: send
+    uses: ./send.yaml
+    needs: summarize

package/skills/stageflow-author/assets/examples/non-sdlc-digest/send.yaml ADDED Viewed

@@ -0,0 +1,10 @@
+id: send
+system_prompt: |
+  Address the digest from the prior envelope to the named recipients and
+  record what went out.
+  Write that record via write_stage_artifact (for example sent.md).
+  When finished, call emit_stage_envelope exactly once with status, summary,
+  artifacts, and a payload describing who received the digest.
+model: anthropic/claude-sonnet-4-5

package/skills/stageflow-author/assets/examples/non-sdlc-digest/summarize.yaml ADDED Viewed

@@ -0,0 +1,9 @@
+id: summarize
+system_prompt: |
+  Turn the gathered notes from the prior envelope into a short weekly digest.
+  Write the digest via write_stage_artifact (for example digest.md).
+  When finished, call emit_stage_envelope exactly once with status, summary,
+  artifacts, and a payload the next stage can use.
+model: anthropic/claude-sonnet-4-5

package/skills/stageflow-author/references/catalog-mapping.md ADDED Viewed

@@ -0,0 +1,131 @@
+# Catalog mapping
+Turn the confirmed step list into one pipeline id and one stage id per step. Ids follow `STAGE_ID_PATTERN`: start with a letter, then lowercase letters, digits, and single hyphens (`^[a-z][a-z0-9]*(-[a-z0-9]+)*$`).
+Derive each id from the human's name for that step or loop:
+1. Lowercase.
+2. Replace each run of non-alphanumeric characters with `-`.
+3. Collapse repeated hyphens; trim leading and trailing hyphens.
+4. If the first character is a digit, prefix `x`.
+5. If the result is empty, use `x`.
+6. Cap at 64 characters; trim a trailing hyphen after the cut.
+7. Keep the result only when it matches the pattern.
+Collision handling lives in [`catalog-write-conventions.md`](catalog-write-conventions.md).
+## Sequencing
+`needs` is a single parent stage id. Fan-in (one stage needing two parents) is out of catalog shape.
+| Human says | Pipeline shape |
+|---|---|
+| Steps in order | Each later stage `needs` the previous id. No `fork` field. |
+| Steps happen together | Sibling stages share one `needs` (the same parent). No `fork` field. |
+| Exactly one branch runs | Deciding stage gets `fork: { select: one }`. Each branch `needs` the decider. |
+| Either, both, or a subset may run | Deciding stage gets `fork: { select: subset }`. Each branch `needs` the decider. |
+Default `select` is `one` unless the human says more than one branch can run.
+Map linear chains, sibling fan-out, and single-level `fork`. A runtime clone count is not knowable from a static description — stay on those three shapes. Leave `clonable` and `clone_forks` unset.
+A review, approval, or sign-off step is a gated stage: put `gate_kinds` on that stage file and follow [`stage-prompt-template.md`](stage-prompt-template.md).
+## Worked examples
+### Review loop (linear)
+Three sequential steps; the middle one is a sign-off.
+```yaml
+id: review-loop
+stages:
+  - id: draft
+    uses: ./draft.yaml
+  - id: review
+    uses: ./review.yaml
+    needs: draft
+  - id: publish
+    uses: ./publish.yaml
+    needs: review
+```
+`review` carries `gate_kinds: [artifact_backed]`. Full set: [`../assets/examples/linear-review/`](../assets/examples/linear-review/).
+### Release gate (fork, select one)
+One deciding step, then exactly one successor.
+```yaml
+id: release-gate
+stages:
+  - id: run-tests
+    uses: ./run-tests.yaml
+    fork:
+      select: one
+  - id: hotfix
+    uses: ./hotfix.yaml
+    needs: run-tests
+  - id: ship
+    uses: ./ship.yaml
+    needs: run-tests
+```
+Full set: [`../assets/examples/branch-decision/`](../assets/examples/branch-decision/).
+### Research digest (linear, non-software)
+Weekly gather → summarize → send. Same `needs` chain as the review loop; ids and prompts stay in that domain.
+```yaml
+id: research-digest
+stages:
+  - id: gather
+    uses: ./gather.yaml
+  - id: summarize
+    uses: ./summarize.yaml
+    needs: gather
+  - id: send
+    uses: ./send.yaml
+    needs: summarize
+```
+Full set: [`../assets/examples/non-sdlc-digest/`](../assets/examples/non-sdlc-digest/).
+### Sibling fan-out
+"After intake, collect quotes and collect notes at the same time":
+```yaml
+stages:
+  - id: intake
+    uses: ./intake.yaml
+  - id: collect-quotes
+    uses: ./collect-quotes.yaml
+    needs: intake
+  - id: collect-notes
+    uses: ./collect-notes.yaml
+    needs: intake
+```
+No `fork` field. Both siblings run.
+### Fork, select subset
+"Email, post, or both could go out":
+```yaml
+stages:
+  - id: choose-channels
+    uses: ./choose-channels.yaml
+    fork:
+      select: subset
+  - id: email
+    uses: ./email.yaml
+    needs: choose-channels
+  - id: post
+    uses: ./post.yaml
+    needs: choose-channels
+```
+The success emit names one or more of those successor ids in `fork_choice`.