stageflow 0.2.0 → 0.8.0

package/skills/stageflow-session-capture/references/catalog-authoring.md

@@ -0,0 +1,40 @@
+# Catalog authoring
+
+Write pipeline and stage YAML with the native Write tool. Confirm with `sf validate --pipeline <path> --strict`. Do not call `createPipeline` / `createStage` or any MCP catalog-write tool. `stageflow-author` is expected to follow this same shape; this file does not define that skill.
+
+## Catalog roots
+
+Read `stageflow.yaml` at the project root (git top-level when `git rev-parse --show-toplevel` succeeds, otherwise the current directory). Write new files under a declared `catalog.pipelines` root. A new subdirectory under an existing root is enough — catalog scan is recursive. If the manifest is missing or unreadable, stop and name `stageflow-setup`. Do not scaffold the manifest.
+
+Resolve collision-safe ids with `scripts/resolve-catalog-id.mjs` (`--text`, `--dir` = the write directory, `--kind pipeline|stage`). Print is `{"id":"..."}`.
+
+## External stage file
+
+Required fields: `id`, `system_prompt`, `model`. Filename stem must match `id` (`research.yaml` → `id: research`).
+
+Every `system_prompt` ends with a mandatory `emit_stage_envelope` footer, for example:
+
+```
+When finished, call emit_stage_envelope once with status, summary, artifacts,
+and a payload the next stage can use.
+```
+
+Omit `gate_kinds`. A human-review checkpoint from the source session stays as prose in the stage approach, not a HITL gate.
+
+Worked example: `assets/example-pipeline/research.yaml` and `assets/example-pipeline/implement.yaml`.
+
+## Pipeline file
+
+`id` plus `stages:` entries with `id`, `uses:` (path relative to the pipeline file), and `needs:` for every non-root stage. Linear chain: each stage `needs` the previous id.
+
+Worked example: `assets/example-pipeline/example.pipeline.yaml`.
+
+Write stages and the pipeline only. `stageflow-run` owns the throwaway task at run time.
+
+## Validate
+
+```
+sf validate --pipeline <pipeline-path> --strict
+```
+
+On failure, delete the files this invocation wrote and report the finding. Do not leave a half-written catalog.

package/skills/stageflow-session-capture/references/transcript-sources.md

@@ -0,0 +1,25 @@
+# Transcript sources
+
+Best-effort lookup for a past session when the human did not pass a file or paste. Current-session capture uses in-context history and does not read a file.
+
+## Probe (one pass)
+
+`scripts/locate-session-transcript.mjs` walks these stores and returns the newest `.jsonl` by mtime.
+
+| Source | Path under `--home` | Scope |
+|---|---|---|
+| Claude Code | `.claude/projects/<cwd-encoded>/**/*.jsonl` | cwd-encoded: replace `/`, `\`, and `:` in `--cwd` with `-` |
+| Codex | `.codex/sessions/**/rollout-*.jsonl` | global date tree (`YYYY/MM/DD`) |
+| Pi | `.pi/agent/sessions/**/*.jsonl` | global |
+
+`--path <file>` skips probing: readable file → `{"ok":true,"path":"...","source":"explicit"}`; otherwise `{"ok":false,"reason":"unreadable"}`.
+
+No match → `{"ok":false,"reason":"not_found"}`. Show a found path to the human before extracting.
+
+## Unsupported stores
+
+Cursor (`~/.cursor/chats/**/store.db`) and OpenCode (`~/.local/share/opencode/opencode.db`) are undocumented SQLite. Do not open or parse them. Those harnesses resolve as `not_found` unless the human points at a file or pastes text.
+
+## Point-or-paste
+
+When lookup returns `not_found` or `unreadable`, ask the human for a file path or pasted history and use that directly.

package/skills/stageflow-session-capture/scripts/check-provider-gate.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+
+function parseArgs(argv) {
+  let sfBin = "sf";
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--sf-bin") {
+      const value = argv[i + 1];
+      if (!value) {
+        console.error("check-provider-gate: --sf-bin requires a path");
+        process.exit(1);
+      }
+      sfBin = value;
+      i += 1;
+    }
+  }
+  return { sfBin };
+}
+
+function print(payload, code) {
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+  process.exit(code);
+}
+
+const { sfBin } = parseArgs(process.argv.slice(2));
+const result = spawnSync(sfBin, ["providers", "status"], { encoding: "utf8" });
+
+if (result.error || result.status === null) {
+  print({ ok: false, reason: "sf_not_found" }, 1);
+}
+
+const lines = (result.stdout ?? "").split(/\r?\n/);
+for (const line of lines) {
+  if (line.length === 0) continue;
+  const fields = line.split("\t");
+  if (fields[1] === "configured") {
+    print({ ok: true }, 0);
+  }
+}
+
+print({ ok: false, reason: "no_provider_configured" }, 1);

package/skills/stageflow-session-capture/scripts/locate-session-transcript.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+import { accessSync, constants, readdirSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function parseArgs(argv) {
+  let explicitPath;
+  let home = os.homedir();
+  let cwd = process.cwd();
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const value = argv[i + 1];
+    if (arg === "--path") {
+      if (!value) {
+        console.error("locate-session-transcript: --path requires a file");
+        process.exit(1);
+      }
+      explicitPath = value;
+      i += 1;
+      continue;
+    }
+    if (arg === "--home") {
+      if (!value) {
+        console.error("locate-session-transcript: --home requires a directory");
+        process.exit(1);
+      }
+      home = value;
+      i += 1;
+      continue;
+    }
+    if (arg === "--cwd") {
+      if (!value) {
+        console.error("locate-session-transcript: --cwd requires a directory");
+        process.exit(1);
+      }
+      cwd = value;
+      i += 1;
+    }
+  }
+  return { explicitPath, home, cwd };
+}
+
+function print(payload, code) {
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+  process.exit(code);
+}
+
+function isReadableFile(filePath) {
+  try {
+    accessSync(filePath, constants.R_OK);
+    return statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function encodeClaudeProject(cwd) {
+  return cwd.replace(/[/\\:]/g, "-");
+}
+
+function walkFiles(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walkFiles(full));
+    } else if (entry.isFile()) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+function newestMatch(dir, accept) {
+  let best;
+  for (const filePath of walkFiles(dir)) {
+    if (!accept(filePath)) continue;
+    let mtimeMs;
+    try {
+      mtimeMs = statSync(filePath).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (!best || mtimeMs > best.mtimeMs) {
+      best = { path: filePath, mtimeMs };
+    }
+  }
+  return best;
+}
+
+const { explicitPath, home, cwd } = parseArgs(process.argv.slice(2));
+
+if (explicitPath !== undefined) {
+  if (!isReadableFile(explicitPath)) {
+    print({ ok: false, reason: "unreadable" }, 1);
+  }
+  print({ ok: true, path: explicitPath, source: "explicit" }, 0);
+}
+
+const probes = [
+  {
+    source: "claude-code",
+    dir: path.join(home, ".claude", "projects", encodeClaudeProject(cwd)),
+    accept: (filePath) => filePath.endsWith(".jsonl"),
+  },
+  {
+    source: "codex",
+    dir: path.join(home, ".codex", "sessions"),
+    accept: (filePath) => {
+      const base = path.basename(filePath);
+      return base.startsWith("rollout-") && base.endsWith(".jsonl");
+    },
+  },
+  {
+    source: "pi",
+    dir: path.join(home, ".pi", "agent", "sessions"),
+    accept: (filePath) => filePath.endsWith(".jsonl"),
+  },
+];
+
+let winner;
+for (const probe of probes) {
+  const match = newestMatch(probe.dir, probe.accept);
+  if (!match) continue;
+  if (!winner || match.mtimeMs > winner.mtimeMs) {
+    winner = { path: match.path, mtimeMs: match.mtimeMs, source: probe.source };
+  }
+}
+
+if (!winner) {
+  print({ ok: false, reason: "not_found" }, 1);
+}
+
+print({ ok: true, path: winner.path, source: winner.source }, 0);

package/skills/stageflow-session-capture/scripts/resolve-catalog-id.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+const ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const TOP_LEVEL_ID = /^id:\s*(?:"([^"]+)"|'([^']+)'|([^\s#]+))\s*(?:#.*)?$/m;
+const KINDS = new Set(["pipeline", "stage"]);
+const MAX_LEN = 64;
+
+function parseArgs(argv) {
+  let text;
+  let dir;
+  let kind;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const value = argv[i + 1];
+    if (arg === "--text") {
+      text = value;
+      i += 1;
+      continue;
+    }
+    if (arg === "--dir") {
+      dir = value;
+      i += 1;
+      continue;
+    }
+    if (arg === "--kind") {
+      kind = value;
+      i += 1;
+    }
+  }
+  return { text, dir, kind };
+}
+
+function trimToMax(value) {
+  let out = value;
+  if (out.length > MAX_LEN) {
+    out = out.slice(0, MAX_LEN);
+  }
+  out = out.replace(/-+$/g, "");
+  return out;
+}
+
+function slugify(text) {
+  let slug = text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (/^[0-9]/.test(slug)) {
+    slug = `x${slug}`;
+  }
+  if (!slug) {
+    slug = "x";
+  }
+  slug = trimToMax(slug);
+  if (!ID_PATTERN.test(slug) || slug.length === 0) {
+    slug = "x";
+  }
+  return slug;
+}
+
+function readTopLevelId(filePath) {
+  let raw;
+  try {
+    raw = readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+  const match = raw.match(TOP_LEVEL_ID);
+  if (!match) return null;
+  return match[1] ?? match[2] ?? match[3] ?? null;
+}
+
+function existingIds(dir) {
+  const ids = new Set();
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return ids;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const name = entry.name;
+    if (!name.endsWith(".yaml") && !name.endsWith(".yml")) continue;
+    const id = readTopLevelId(path.join(dir, name));
+    if (id) ids.add(id);
+  }
+  return ids;
+}
+
+function uniqueId(base, taken) {
+  if (!taken.has(base)) return base;
+  for (let n = 2; n < 10_000; n += 1) {
+    const suffix = `-${n}`;
+    const candidate = trimToMax(`${base.slice(0, MAX_LEN - suffix.length)}${suffix}`);
+    if (ID_PATTERN.test(candidate) && !taken.has(candidate)) {
+      return candidate;
+    }
+  }
+  return `${base}-x`;
+}
+
+const { text, dir, kind } = parseArgs(process.argv.slice(2));
+
+if (!KINDS.has(kind)) {
+  console.error("resolve-catalog-id: --kind must be pipeline or stage");
+  process.exit(1);
+}
+
+if (typeof text !== "string" || text.length === 0 || typeof dir !== "string") {
+  console.error("resolve-catalog-id: --text, --dir, and --kind are required");
+  process.exit(1);
+}
+
+const id = uniqueId(slugify(text), existingIds(dir));
+process.stdout.write(`${JSON.stringify({ id })}\n`);

package/skills/stageflow-setup/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: stageflow-setup
+description: >-
+  Installs Stageflow, scaffolds a starter catalog with sf init, then hard-stops
+  for provider login. Use when this project has no Stageflow install, sf is not
+  found, there is no catalog, first time running Stageflow here, the user asks
+  to set up Stageflow, or a provider is not logged in. Install, scaffold, and
+  provider-gate only — does not author pipelines or stages, capture a session,
+  or manage an MCP host.
+disable-model-invocation: true
+---
+
+# Stageflow setup
+
+Install the CLI, scaffold a catalog, then hard-stop until a provider is configured. Report `ready to author` or `blocked: <reason>`.
+
+Author pipelines and stages with `stageflow-author`. Capture a chat or past session with `stageflow-session-capture`. Start, watch, or answer a run with `stageflow-run`. Codify a repeating pattern with `stageflow-delegate`.
+
+This job does not author catalog YAML, capture a session, or manage an MCP host. Its surface is the `sf` CLI. Talking jobs cite [`../stageflow/references/control-surface.md`](../stageflow/references/control-surface.md) for MCP-vs-CLI; do not run the host probe in that file from this job.
+
+## Detect-before-mutate
+
+Re-derive readiness every invocation. Do not write a setup-complete marker.
+
+Set `SF=sf`. After an EACCES fallback this invocation, set `SF='npx stageflow'` and use that prefix for every later CLI call.
+
+Probe, in order:
+
+1. `sf --version` — success means the CLI is on PATH. (After EACCES this invocation, use `$SF --version` instead.)
+2. `stageflow.yaml` exists at the catalog root: git top-level when `git rev-parse --show-toplevel` succeeds, otherwise the current directory.
+3. `$SF providers status` — a provider counts only when a row's second column is `configured`.
+
+**Done when all three pass:** print `ready to author` and stop. Do not run `npm i -g stageflow` or `sf init`.
+
+If any probe fails, repair only the failed phases below, in order. A failure prints `blocked: <reason>` and stops — do not guess the next phase.
+
+## Install
+
+Skip this phase when probe 1 passed.
+
+1. Run `node --version`. **Done when** the major version is `>=20`. If Node is missing or older, stop:
+
+   `blocked: node: Node >=20 is required. Install Node 20 or newer, then re-invoke stageflow-setup.`
+
+   Do not install or switch Node versions.
+
+2. Run `npm i -g stageflow`. Never `sudo`.
+
+   - Success → keep `SF=sf`. **Done when** `sf --version` prints a version.
+   - `EACCES` or a permission error → set `SF='npx stageflow'`. Use that prefix for the rest of this invocation only. Tell the operator a later invocation will re-check the global install. Then continue to Scaffold.
+   - Any other error (network, registry) → stop. Do not fall back to `npx`.
+
+     `blocked: install: npm i -g stageflow failed. Command: npm i -g stageflow. Error: <verbatim>`
+
+## Scaffold
+
+Skip `$SF init` when probe 2 passed.
+
+1. From the consumer project directory, run `$SF init` only when `stageflow.yaml` is missing. `sf init` creates `stageflow.yaml`, `pipelines/hello.pipeline.yaml`, and `tasks/hello.task.yaml`, and skips any path that already exists. Create catalog files only with this command.
+
+2. After `$SF init`, run `$SF validate --strict`. Print findings verbatim. **Done when** exit code is `0`. If it fails:
+
+   `blocked: scaffold: sf validate --strict failed. <verbatim findings>`
+
+3. If `git rev-parse --show-toplevel` fails after a create, tell the operator the catalog is not git-tracked. Do not run `git init`.
+
+## Provider hard-stop
+
+Run this phase only after Install and Scaffold have succeeded or were already satisfied. Never print `ready to author` while no provider is `configured`.
+
+1. Run `$SF providers status`. **Done when** any row is `configured` — go to Completion. If a non-interactive login just succeeded, name that provider id.
+
+2. If none are configured, run `$SF providers list`. For each id (first column), test whether the environment has `<ID>_API_KEY` with `ID` uppercased (`anthropic` → `ANTHROPIC_API_KEY`). Test presence only — do not read or print the value.
+
+3. On the first match, run:
+
+   `$SF providers login <id> --type api_key --api-key-env <VAR>`
+
+   Re-run `$SF providers status`. If that id is `configured`, go to Completion and name the provider. If the login fails, print the error verbatim, then continue to the walkthrough.
+
+4. On no match, a failed login, or a session that cannot complete OAuth (no attached terminal, CI-shaped), stop. Print the commands; do not start a browser or device flow.
+
+   `blocked: provider: no provider configured.`
+
+   Then print these commands for the human (substitute real ids from `list`):
+
+   ```
+   $SF providers list
+   $SF providers login <id> --type api_key --api-key-env <ID>_API_KEY
+   $SF providers login <id> --type oauth
+   ```
+
+   Point at `docs/providers.md` for `pi_home` vs `sf_owned`. Leave the storage mode to the human.
+
+## Completion
+
+First line is exactly one of:
+
+- `ready to author` — CLI present, catalog present, at least one provider `configured`.
+- `blocked: <reason>` — name the phase (`node`, `install`, `scaffold`, or `provider`) and the next command.
+
+If a non-interactive login just wired a provider, add a following line:
+
+`provider: <id>`
+
+If this invocation used the `npx` fallback, add a following line:
+
+`CLI: npx stageflow (EACCES on npm i -g stageflow; this session only — a later invocation will re-check the global install)`
+
+A later job calls this skill as preflight. It does not re-implement the provider gate.