stageflow 0.2.0 → 0.8.0

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

@@ -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`.

package/skills/stageflow-author/references/catalog-write-conventions.md

@@ -0,0 +1,29 @@
+# Catalog write conventions
+
+Write pipeline and stage YAML with the native Write tool. `sf ui` does not need to be running. Do not call `createPipeline` or `createStage`.
+
+## Location
+
+Project root is the git top-level when `git rev-parse --show-toplevel` succeeds, otherwise the current directory.
+
+1. **Manifest present.** Read `stageflow.yaml` at that root. Write the colocated set under a declared `catalog.pipelines` root. A new subdirectory under that root is enough — catalog scan is recursive.
+2. **No manifest.** Write the colocated set as a flat layout at the project root (pipeline file and stage files beside each other).
+
+Do not write a `*.task.yaml`.
+
+## File shape
+
+One directory (or the project root) holds:
+
+| File | Required fields |
+|---|---|
+| `<pipeline-id>.pipeline.yaml` | `id` matching the filename stem; `stages:` object entries |
+| `<stage-id>.yaml` | `id`, `system_prompt`, `model`; `gate_kinds` when the step is gated |
+
+Each pipeline stage entry has `id` and `uses: ./<id>.yaml` (path relative to the pipeline file). Non-root stages add `needs: <parent-id>`. A deciding stage adds `fork:`. Filename stem matches `id` on every file.
+
+## Collisions
+
+Before writing, list `*.pipeline.yaml` files in the target directory (and existing pipeline files under the same catalog root) plus every `*.yaml` / `*.yml` stage file beside the target pipeline. Read each file's top-level `id:` and its filename stem.
+
+On a match for the candidate pipeline id or any stage id, ask the human for a different id. Write nothing until that id is free. Never replace an existing file silently. Proceed with a colliding name only when the human explicitly confirms overwrite.

package/skills/stageflow-author/references/stage-prompt-template.md

@@ -0,0 +1,55 @@
+# Stage prompt template
+
+Every external stage file has `id`, `system_prompt`, and `model`. Filename stem matches `id`. Default `model` is `anthropic/claude-sonnet-4-5`. When the human names a different model, write that string verbatim.
+
+## Base
+
+Use for every stage that is not a review point and does not decide a branch.
+
+```yaml
+id: <id>
+system_prompt: |
+  <one-line goal for this step>
+
+  Write any output this step produces via write_stage_artifact.
+
+  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
+```
+
+The prompt has no `ask_operator` line. It ends on the `emit_stage_envelope` instruction. Call `emit_stage_envelope` once per attempt.
+
+## Gated
+
+When the step is a review, approval, or sign-off, add `gate_kinds` and resolve the gate before emit. Match this sequence: `write_stage_artifact` → `ask_operator` → `emit_stage_envelope` on accept.
+
+```yaml
+id: <id>
+gate_kinds:
+  - artifact_backed
+system_prompt: |
+  <one-line goal>. Get operator acceptance before completing this stage.
+
+  1. Write the reviewable output via write_stage_artifact.
+  2. Call ask_operator with kind artifact_backed referencing that artifact path.
+  3. On reject or change text: revise the 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
+```
+
+Use the `gate_kinds` value that matches the human's review: `artifact_backed` for a file to accept, `confirm` for yes/no, `free_text` for an open reply, `multi_question` for a batch. `ask_operator` does not complete the stage.
+
+## Fork
+
+When the pipeline entry has `fork`, the success emit names immediate successors in `fork_choice`. Add this block to the base (or gated) prompt:
+
+```
+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. select: subset → one or more of those ids.
+```
+
+`fork_choice` on a failure emit is ignored. Leave `clone_forks` unset.

package/skills/stageflow-author/references/validate-and-report.md

@@ -0,0 +1,38 @@
+# Validate and report
+
+After the pipeline and stage files exist, validate them before telling the human authoring is complete.
+
+## Command
+
+Default — always available:
+
+```
+sf validate --pipeline <written-path> --strict
+```
+
+MCP `validate` is allowed only when [`../../stageflow/scripts/detect-host.mjs`](../../stageflow/scripts/detect-host.mjs) reports a host up. From this skill directory:
+
+```
+node ../stageflow/scripts/detect-host.mjs
+```
+
+| stdout | next |
+|---|---|
+| `up <baseUrl>` | MCP `validate` with `{ "pipeline": "<written-path>", "strict": true }` is allowed |
+| `down <baseUrl>` | stay on the CLI command |
+
+Do not write a second probe. MCP-vs-CLI policy: [`../../stageflow/references/control-surface.md`](../../stageflow/references/control-surface.md). Both paths return the same `ValidationResult` shape (`ok`, `summary`, `findings[]`).
+
+## Failure
+
+When `ok` is false or the CLI exits non-zero, print each finding (severity, code, path, message). Fix the offending pipeline or stage file. Re-validate. Repeat until `ok` is true. Never report authoring complete on a failing validate.
+
+## Success
+
+When validate exits 0 / `ok: true`, print:
+
+1. Pipeline id and pipeline path.
+2. Every stage path written in this invocation.
+3. Name `stageflow-run` if the human wants to execute the pipeline.
+
+Do not write a `*.task.yaml`. Do not start a run here.

package/skills/stageflow-delegate/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: stageflow-delegate
+description: Looks up a catalog pipeline for a repeating request, then reuses it or codifies it and runs. Use when this skill is opened for a repeating-pattern request.
+disable-model-invocation: true
+---
+
+# Stageflow delegate
+
+Look up the catalog once, then branch. A match runs; no match authors, then runs.
+
+Talking jobs cite [`../stageflow/references/control-surface.md`](../stageflow/references/control-surface.md). This job names `stageflow-run` for execution and does not choose MCP vs CLI.
+
+1. Look up the requested pattern. Follow [`references/pattern-detection.md`](references/pattern-detection.md) until you have a match, a disambiguation, or no match.
+2. Branch on that result. Follow [`references/authoring-or-run.md`](references/authoring-or-run.md). Name `stageflow-run` and stop.
+
+Act only when this skill is the one opened. Leave the harness's builtin subagents in place; never suggest disabling, replacing, or bypassing them.
+
+Worked pair: [`references/example-walkthrough.md`](references/example-walkthrough.md).

package/skills/stageflow-delegate/references/authoring-or-run.md

@@ -0,0 +1,15 @@
+# Authoring or run
+
+Take the lookup band. Open the named job and follow it. Do not start a run, write a throwaway task, or answer a gate from this skill.
+
+| band | open | then |
+|---|---|---|
+| match | [`stageflow-run`](../../stageflow-run/SKILL.md) for that pipeline | stop |
+| no match, and this session already did the matching work with readable history (this chat, or a path / paste the human supplied) | [`stageflow-session-capture`](../../stageflow-session-capture/SKILL.md) | when it reports a pipeline path, open [`stageflow-run`](../../stageflow-run/SKILL.md) for that path and stop |
+| no match, and no readable history | [`stageflow-author`](../../stageflow-author/SKILL.md) | when it reports a pipeline path, open [`stageflow-run`](../../stageflow-run/SKILL.md) for that path and stop |
+
+History is a coarse yes/no. Unsure → treat as no history.
+
+If the authoring job stops on a blocker (it names [`stageflow-setup`](../../stageflow-setup/SKILL.md), or prints `blocked: <reason>`), print that blocker and stop. Do not retry, log in, or work around it.
+
+**Done when** `stageflow-run` has been named, or an authoring blocker has been printed.

package/skills/stageflow-delegate/references/example-walkthrough.md

@@ -0,0 +1,30 @@
+# Example walkthrough
+
+Content walkthrough. No live harness session is required.
+
+Scratch catalog at first sight:
+
+| path | id | task `goal` (if readable) |
+|---|---|---|
+| `pipelines/hello.pipeline.yaml` | `hello` | Draft a one-page brief |
+| `pipelines/plan-review.pipeline.yaml` | `plan-review` | Prove a review loop |
+
+## First sight
+
+Request: "Every week I gather sources, summarize them, and send a digest. Make that a reusable pipeline and run it."
+
+[pattern-detection](pattern-detection.md) tokens include `gather`, `sources`, `summarize`, `send`, `digest`. Neither `hello` nor `plan-review` shares a distinctive topic token. Band: **no match**. This chat has not already done that work. [authoring-or-run](authoring-or-run.md) opens `stageflow-author`, then names `stageflow-run` on the written pipeline (id `research-digest`, path `pipelines/research-digest.pipeline.yaml`). One pipeline is authored. None is invented a second time.
+
+If this session had already gathered, summarized, and sent — with that history still in chat or a pointer the human supplied — the same no-match would open `stageflow-session-capture` instead, then `stageflow-run`.
+
+## Second sight
+
+Same catalog, plus `pipelines/research-digest.pipeline.yaml` (`id: research-digest`).
+
+Request: "Run the weekly research digest."
+
+Tokens include `research`, `digest`. Exact topic overlap on one candidate's kebab `id`. Band: **match**. [authoring-or-run](authoring-or-run.md) opens `stageflow-run` only. No second pipeline is written.
+
+## Ordinary request
+
+Request: "Fix the typo in README." This skill is not opened. The harness's builtin subagent does the edit. Builtin subagents stay available.

package/skills/stageflow-delegate/references/pattern-detection.md

@@ -0,0 +1,44 @@
+# Pattern detection
+
+Decide match vs first-sight from the catalog. Listings carry `path`, `id`, and `stages` — no `description` or `title`. Do not invent a list command.
+
+## Roots
+
+Project root is the git top-level when `git rev-parse --show-toplevel` succeeds, otherwise the current directory. Read `stageflow.yaml` there. Walk each `catalog.pipelines` root. Use `catalog.patterns.pipeline` (default `*.pipeline.yaml`). Skip a path whose repo-relative prefix is in `catalog.exclude`.
+
+Manifest missing or unreadable, a listed root missing, or zero pipeline files → **no match**. Not an error.
+
+**Done when** you have a candidate list, or a no-match.
+
+## Host
+
+From this skill directory:
+
+```
+node ../stageflow/scripts/detect-host.mjs
+```
+
+Script: [`../../stageflow/scripts/detect-host.mjs`](../../stageflow/scripts/detect-host.mjs). Stdout is `up <baseUrl>` or `down <baseUrl>`.
+
+| stdout | catalog |
+|---|---|
+| `up <baseUrl>` | MCP `list_pipelines`, then `describe_pipeline` on a shortlisted path |
+| `down <baseUrl>` | Read `*.pipeline.yaml` under the roots. When a paired `*.task.yaml` is readable, take its `goal` |
+
+A paired task is a `*.task.yaml` in the same directory as the pipeline, or one whose `id` / directory words overlap that pipeline. Skip `goal` when no such file is readable. Host-up listings do not include `goal`.
+
+**Done when** each candidate has `path`, `id`, and (when readable) a task `goal`.
+
+## Score
+
+Split the request, each kebab `id`, and each directory segment under the catalog root into lowercase tokens. Drop empty tokens and generic words (`pipeline`, `stage`, `task`, `run`, `the`, `a`, `an`). Add tokens from a readable task `goal`.
+
+| band | test | next |
+|---|---|---|
+| match | The request names one candidate's kebab `id`, or exactly one candidate has a strong overlap (a distinctive topic token shared with `id`, directory words, or `goal`) | reuse that pipeline |
+| ask once | Two or more candidates are plausible | print `id` + `path` for each; ask which; that answer is the match |
+| no match | Zero candidates, or the catalog was empty / unreadable | first-sight |
+
+Exact `id` beats keyword overlap. Do not guess among two-plus. Do not treat a weak shared word (`review`, `send`, `weekly`) as a match when more than one candidate could claim it.
+
+**Done when** the band is match, a human-chosen match, or no match.

package/skills/stageflow-run/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: stageflow-run
+description: >-
+  Starts a catalog pipeline from the harness, reports progress, and answers
+  every HITL gate in this chat. Triggers: run a pipeline, start <pipeline>,
+  check on my run, answer the pending question.
+compatibility: Requires the sf CLI on PATH. An MCP host (sf ui or sf mcp) is optional.
+disable-model-invocation: true
+---
+
+# Stageflow run
+
+Start a catalog pipeline, keep every HITL gate in this chat, and report the outcome. Author and session-capture own catalog YAML; this job owns the run and any throwaway `*.task.yaml`.
+
+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. Do not write a second probe.
+
+MCP tool shapes: [`docs/mcp.md`](../../docs/mcp.md). CLI flags and exit codes: [`docs/cli-reference.md`](../../docs/cli-reference.md). Direct tool calls: [`references/mcp-call.md`](references/mcp-call.md). Selection: [`references/task-and-pipeline-selection.md`](references/task-and-pipeline-selection.md).
+
+## Preconditions
+
+Run `sf --version`. **Done when** it prints a version. If `sf` is missing, stop and name `stageflow-setup`.
+
+## Probe
+
+```
+node ../stageflow/scripts/detect-host.mjs
+node ../stageflow/scripts/detect-host.mjs --base-url http://127.0.0.1:3847
+```
+
+| stdout | path |
+|---|---|
+| `up <baseUrl>` | [MCP path](#mcp-path) |
+| `down <baseUrl>` | [CLI path](#cli-path) |
+
+**Done when** you have `up` or `down` and the base URL.
+
+## Select
+
+Read [`references/task-and-pipeline-selection.md`](references/task-and-pipeline-selection.md). Follow it until you have a pipeline filesystem path and a task (catalog path, MCP inline object, or CLI throwaway file).
+
+If this chat already has a `runId` and the request is check, answer, or continue: skip start. Host up → [Wait](#wait). Host down and the human wants to answer → [Bridge](#bridge).
+
+**Done when** the target is named, or a live `runId` is in hand.
+
+## MCP tools
+
+Prefer this harness's native Stageflow MCP tools when their names are already in the tool list. When they are not, call [`scripts/mcp-call.mjs`](scripts/mcp-call.mjs) — see [`references/mcp-call.md`](references/mcp-call.md). Always use `mcp-call.mjs --stateless` for a bridge this skill started.
+
+Call only `list_pipelines`, `list_tasks`, `start_run`, `get_run`, `wait_run`, `list_waiting`, `answer_gate`, `get_health`.
+
+## MCP path
+
+### Start
+
+`start_run` with `pipeline` plus exactly one of `task_path` or inline `task`.
+
+| result | next |
+|---|---|
+| `{ "runId" }` | [Wait](#wait) |
+| `busy_capacity` / `busy_checkout` | [Report](#report) the included fields. Stop. Do not retry. |
+| other `isError` | [Report](#report) the payload. Stop. |
+
+**Done when** you have a `runId`, or a busy/error report is printed.
+
+### Wait
+
+`wait_run` with `{ "runId", "until": "any" }`. A shorter `timeout_ms` is fine when the harness tool timeout is tight.
+
+| `reason` | next |
+|---|---|
+| `waiting` or `already` with a waiting snapshot | [Gate](#gate) |
+| `terminal` | [Report](#report) |
+| `timeout` | call `wait_run` again |
+| `isError` with `code: "aborted"` | [Report](#report): the run continues, resumable later. Stop. |
+| other `isError` | [Report](#report) the payload. Stop. |
+
+**Done when** the run is waiting (hand to Gate), terminal, aborted, or a hard error is printed.
+
+### Gate
+
+1. `list_waiting` with `{ "runId" }`.
+2. Print the pending prompt text **verbatim** (and artifacts / sub-questions when present).
+3. Collect the human's reply in this chat. Map it to the prompt `kind`:
+
+| kind | `answer` |
+|---|---|
+| `free_text` | `{ "promptId", "kind": "free_text", "text" }` |
+| `confirm` | `{ "promptId", "kind": "confirm", "decision": "accept" \| "reject" }` |
+| `artifact_backed` | `{ "promptId", "kind": "artifact_backed", "decision": "accept" \| "reject" }` |
+| `multi_question` | `{ "promptId", "kind": "multi_question", "answers": { "<id>": { "kind", "text" \| "decision" } } }` |
+
+`promptId` is `pending_prompt.id` or `waiting_prompt_id`. Map yes/y/accept/approve to `accept`; no/n/reject/deny to `reject`. Ask once when the kind is `multi_question` and any sub-question is unanswered, or when confirm/artifact_backed is not a clear decision.
+
+4. `answer_gate` with `{ "runId", "stageId", "answer" }`.
+5. Return to [Wait](#wait).
+
+**Done when** `answer_gate` returns `{ "ok": true }` and Wait is re-entered. On `isError` (400 / 404 / 409), print the payload and ask for a corrected reply — do not open another surface.
+
+## CLI path
+
+Discovery without a host: read `stageflow.yaml` catalog roots as in [`references/task-and-pipeline-selection.md`](references/task-and-pipeline-selection.md).
+
+```
+sf run --task <path> --pipeline <path> --json
+```
+
+Add `--checkout`, `--git-sha`, `--ci-pr-url`, `--ci-job-url`, `--operator-cwd`, or `--operator-agent-dir` only when the human supplied them. Always pass `--json`. Omit `--include stages` unless the human asked for a stage projection — and then only together with `--json`.
+
+Parse the single JSON document.
+
+| exit | `outcome` | next |
+|---|---|
+| `0` | `succeeded` | [Report](#report) |
+| `1` | `failed` | [Report](#report) `reason` verbatim |
+| `1` | `busy` | [Report](#report) `busy_capacity` / `busy_checkout` and the included fields. Stop. |
+| `2` | `waiting` | [Bridge](#bridge) with this `runId` / `runDir` |
+
+**Done when** the outcome is reported, or a waiting exit has handed `runId` and `runDir` to Bridge.
+
+## Bridge
+
+A CLI waiting exit has no answer command. Keep the gate in this chat by joining a host on the same project root (git top-level when `git rev-parse --show-toplevel` succeeds, otherwise the current directory).
+
+1. Probe again with [`../stageflow/scripts/detect-host.mjs`](../stageflow/scripts/detect-host.mjs) (the host may have appeared).
+2. **Up:** use that host — native tools if present, otherwise `mcp-call.mjs` (omit `--stateless`). Continue at [Gate](#gate).
+3. **Down:** start `sf mcp --mcp-stateless` as a background process on that same project root. This is a disposable HITL bridge, not setup auto-start.
+4. Probe until stdout is `up <baseUrl>`, at most 8 times. **Done when** the host is up. If it stays down, [Report](#report) the parked `runId` / `runDir` and the bind/stderr text. Stop.
+5. Drive the rest with `mcp-call.mjs --stateless` only: [Gate](#gate) → [Wait](#wait) until terminal. A second wait on the same run reuses this process.
+6. When the run is terminal, stop the bridge process.
+
+If this chat ends before terminal, say the run stays in `.stageflow/` and to continue by re-invoking this skill (or starting a host and using MCP).
+
+**Done when** the run is terminal and the bridge this skill started is stopped, or a parked-run failure is reported.
+
+## Report
+
+Print one shape on every path:
+
+1. Current or last-known stage (MCP live snapshot, or "start/finish only" on a CLI-only stretch).
+2. Waiting prompt text verbatim when the run is parked.
+3. Outcome: `succeeded`, `failed`, `waiting`, or `busy`.
+4. Run id.
+5. Run folder (`runDir` / `.stageflow/`).
+
+MCP `get_run` / `wait_run` carry live stage state. `sf run --json` reports start and finish only — say that in chat when the CLI path ran without a host. A succeeded report names id and folder and does not keep waiting language. A failure names `reason` in this same shape.
+
+**Done when** that five-part report is printed.
+
+## Non-goals
+
+This job starts, watches, and answers runs. It does not require `sf ui`. The operator console is not the answer path. It does not register or invent an MCP tool.

package/skills/stageflow-run/references/mcp-call.md

@@ -0,0 +1,17 @@
+# mcp-call
+
+Use [`../scripts/mcp-call.mjs`](../scripts/mcp-call.mjs) when this harness has no native Stageflow MCP tools, and always for a self-started `sf mcp --mcp-stateless` bridge.
+
+```
+node scripts/mcp-call.mjs --base-url <url> --tool <name> --args '<json>' [--stateless]
+```
+
+Default `--base-url` is `http://127.0.0.1:3847`. `--args` defaults to `{}`.
+
+`--stateless` sends one `tools/call` and no session header. Use it for hosts started with `sf mcp --mcp-stateless`.
+
+Without `--stateless`: `initialize`, capture `Mcp-Session-Id`, reuse it for `tools/call`.
+
+Stdout is the tool JSON. Exit `0` on success, including `wait_run` with `reason: "timeout"` (keep polling). Exit `1` on transport failure or `isError: true`. Exit `2` on usage or malformed `--args` — that parse error happens before any network call.
+
+Allowed `--tool` names (see [`docs/mcp.md`](../../../docs/mcp.md)): `list_pipelines`, `list_tasks`, `start_run`, `get_run`, `wait_run`, `list_waiting`, `answer_gate`, `get_health`.

package/skills/stageflow-run/references/task-and-pipeline-selection.md

@@ -0,0 +1,52 @@
+# Task and pipeline selection
+
+Resolve one pipeline filesystem path and one task before `start_run` or `sf run`. Ask a disambiguating question on more than one match. Do not guess.
+
+## Named
+
+If the human named a pipeline or task, match that string against catalog `id` and `path`. One match → use it. Several → print id + path and ask which. Zero → say so and offer the catalog list.
+
+## Unnamed
+
+Print a short pick list (id + path). Ask which.
+
+## MCP catalog
+
+`list_pipelines` and `list_tasks` (native tools, or [`mcp-call.md`](mcp-call.md)). Listing objects carry `path` and `id`.
+
+## CLI catalog
+
+There is no CLI list command. Read `stageflow.yaml` at the project root (git top-level when `git rev-parse --show-toplevel` succeeds, otherwise the current directory).
+
+Walk each `catalog.pipelines` / `catalog.tasks` root. Match `catalog.patterns.pipeline` (default `*.pipeline.yaml`) and `catalog.patterns.task` (default `*.task.yaml`). Skip paths whose repo-relative prefix is in `catalog.exclude`.
+
+## Task input
+
+### MCP
+
+An existing `task_path` from `list_tasks`, or an inline `task` object built from the stated goal:
+
+```json
+{ "id": "<slug>", "goal": "<goal>", "context": "optional", "constraints": "optional", "checkout": "optional" }
+```
+
+`start_run` accepts that object. Do not write a scratch file on the MCP path.
+
+### CLI
+
+`sf run` accepts `--task <path>` only. Reuse a catalog `*.task.yaml`, or write a throwaway file at the project root:
+
+```
+.scratch/stageflow-run/<id>.task.yaml
+```
+
+```yaml
+id: <slug>
+goal: <human goal>
+```
+
+Add `context`, `constraints`, or `checkout` only when the human gave them. Pass that path as `--task`.
+
+## Optional run flags
+
+`--checkout`, `--git-sha`, `--ci-pr-url`, `--ci-job-url` only when the human supplied them.