stageflow 0.3.0 → 0.9.0

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,182 @@
+---
+name: stageflow-run
+description: >-
+  Starts a catalog pipeline from the harness, reports progress, and answers
+  every HITL gate on the host native question UI when it can, otherwise 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, present HITL on the host native question UI when it can, 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). Gate presentation: [`references/native-question-ui.md`](references/native-question-ui.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 → [CLI wait](#cli-wait).
+
+**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). Use `--stateless` only when the **user** started the host with `--mcp-stateless`. Do not start `sf mcp` from this skill.
+
+Call only these Stageflow MCP tools: `list_pipelines`, `list_tasks`, `start_run`, `get_run`, `wait_run`, `list_waiting`, `answer_gate`, `get_health`. Host question tools already in this harness's tool list (`AskQuestion`, `AskUserQuestion`, `ask_user`) are for [Gate](#gate) presentation, not Stageflow MCP.
+
+## 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
+
+Read [`references/native-question-ui.md`](references/native-question-ui.md) before presenting a pending prompt.
+
+1. `list_waiting` with `{ "runId" }`.
+2. Print the pending prompt text **verbatim** (and artifacts / sub-questions when present).
+3. Present the decision as that reference directs:
+   - If a host question tool is already in this harness's tool list and the gate is representable, invoke that picker. For `multi_question`, one picker call with one question per sub-item when **every** sub-question is representable, then one `answer_gate`; otherwise the **whole** gate in this chat.
+   - Otherwise collect the reply in this chat.
+4. Map the reply to the prompt `kind` (picker Accept/Reject → `accept`/`reject`):
+
+| 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/Accept to `accept`; no/n/reject/deny/Reject to `reject`. Each `multi_question` sub-answer keeps that sub's `kind` (`confirm` → `decision`, `free_text` → `text`). Collect every sub-answer before `answer_gate`.
+
+5. `answer_gate` with `{ "runId", "stageId", "answer" }`.
+6. 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 collect a corrected reply the same way (picker if still representable; otherwise this chat).
+
+## 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` | [CLI wait](#cli-wait) with this `runId` / `runDir` |
+
+**Done when** the outcome is reported, or a waiting exit has handed `runId` to CLI wait.
+
+## CLI wait
+
+Host down after `sf run` exit `2`, or when this chat already has a `runId` and the host is down. Do not start `sf mcp`. Presentation follows [`references/native-question-ui.md`](references/native-question-ui.md). Submit with `sf runs answer --json`.
+
+1. Probe again with [`../stageflow/scripts/detect-host.mjs`](../stageflow/scripts/detect-host.mjs) (the host may have appeared). Probe before each `sf runs answer`.
+2. **Up:** use that host — native tools if present, otherwise `mcp-call.mjs` (omit `--stateless` unless the user started the host with `--mcp-stateless`). Continue at [Gate](#gate).
+3. **Down:**
+
+```
+sf runs waiting --run <runId> --json
+```
+
+Print the pending prompt **verbatim**. Present it as native-question-ui directs (picker or chat). Map the reply with the [Gate](#gate) kind table.
+
+```
+sf runs answer --run <runId> --stage <stageId> --answer '<json>' --json
+```
+
+Success is `{ "ok": true }` exit `0` even if the run parks again. Do not treat answer as terminal.
+
+```
+sf runs wait --run <runId> --json --until any
+```
+
+A shorter `--timeout-ms` is fine when the harness timeout is tight. Default `60000`, max `240000`. Branch on JSON `reason`, not wait exit `0`:
+
+| `reason` | next |
+|---|---|
+| `waiting` or `already` with a waiting snapshot | `sf runs waiting` then answer |
+| `terminal` | [Report](#report) |
+| `timeout` | call `sf runs wait` again |
+
+Wait abort (exit `130`, `{ "error", "code": "aborted" }`) → [Report](#report): the run continues, resumable later. Stop. Do not reuse `sf run` exit `2` for wait.
+
+4. If `sf runs answer` refuses because the host came up, continue that gate via MCP [Gate](#gate). Do not dual-write.
+
+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, aborted, or a hard error is printed.
+
+## 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` and `sf runs wait` / `sf runs show` `--json` carry live stage state. `sf run --json` reports start and finish only — say that in chat when the CLI path ran without a later wait/show. 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. It does not start `sf mcp`. It does not retry, abandon, or rerun stages.

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

@@ -0,0 +1,17 @@
+# mcp-call
+
+Use [`../scripts/mcp-call.mjs`](../scripts/mcp-call.mjs) when the Stageflow host is up and this harness has no native Stageflow MCP tools. Do not start `sf mcp` from this skill.
+
+```
+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 the **user** started with `sf mcp --mcp-stateless`, not a skill-started process.
+
+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/native-question-ui.md

@@ -0,0 +1,78 @@
+# Native question UI
+
+Present a waiting HITL gate on the coding-agent host's structured question tool when that tool can represent the gate. Otherwise collect the reply in this chat. Submit with `answer_gate` when the Stageflow host is up, or `sf runs answer --json` when it is down. This file is presentation only — it does not change MCP tools, `detect-host.mjs`, or the operator console.
+
+Read `pending_prompt` from `list_waiting` or `sf runs waiting --json` (not only `waiting_questions` strings).
+
+## Detect a picker
+
+Inspect **this harness's current tool list**. A picker is a tool that collects a structured choice (question text plus labeled options), not a free-form chat reply.
+
+Do not run `detect-host.mjs` for this. That script is Stageflow host up/down (MCP vs CLI). It does not detect a question UI.
+
+| If this name is in the tool list | Use it |
+|---|---|
+| `AskQuestion` | Cursor question cards |
+| `AskUserQuestion` | Claude Code questions |
+| `ask_user` | Pi questions |
+
+If none of those (or another options-based question tool already in the list) is present, collect in chat. Do not invent a tool name or call shape. Codex and OpenCode stay in chat until an options-based question tool appears in the list.
+
+Pass the pending message as the question text and the mapped labels as that tool's options. One question per call except `multi_question`: one call with one question per representable sub-item when the tool accepts a questions array (Cursor `AskQuestion` does). Do not invent placeholder options such as Type in Other — host Other is the custom-text escape. If the picker returns a custom or Other value, map that text the same as a chat reply.
+
+**Done when** you know picker or chat for this gate.
+
+## Representable vs chat
+
+| Gate | Picker | Chat |
+|---|---|---|
+| `confirm` | Accept and Reject | Host has no picker |
+| `artifact_backed` | Accept and Reject (decision only) | Host has no picker |
+| `free_text` with a harvested closed set | Those names as options | Open-ended, or harvest is ambiguous |
+| `free_text` with no closed set | — | Always |
+| `multi_question` | One picker call with one question per sub-item when **every** sub-question is representable; then one submit | Any sub-question is open or unmappable — the **whole** gate in chat |
+
+Map picker Accept / yes / approve → `accept`. Reject / no / deny → `reject`. Always include `promptId` (`pending_prompt.id` or `waiting_prompt_id`).
+
+| Item | Submit |
+|---|---|
+| Top-level or sub `confirm` | `{ "kind": "confirm", "decision": "accept" \| "reject" }` |
+| Top-level `artifact_backed` | `{ "kind": "artifact_backed", "decision": "accept" \| "reject" }` plus optional `text` after a reject follow-up |
+| Top-level or sub `free_text` (including harvested) | `{ "kind": "free_text", "text": "<selected label>" }` |
+
+Never submit a `confirm` item as `free_text`. For `multi_question`, wrap sub-answers in the Gate `answers` object and submit once (`answer_gate` or `sf runs answer --json`).
+
+When in doubt, chat.
+
+**Done when** the path (picker or chat) is chosen from this table.
+
+## Harvest
+
+Harvest only from `pending_prompt.message` (or a `multi_question` item `message`) when it names a **hard closed set**:
+
+- `reply with exactly one of:`
+- `choose one of:`
+- `exactly one of`
+
+Split the names after that directive (commas, `or`, newlines). Those literal names are the picker options.
+
+Do **not** harvest loose example lists (`you might try`, `e.g.`, `for example` without `exactly one of`). A listed example set that is not a hard closed directive stays in chat.
+
+Submit the selected label as `text` for `free_text` items. If the prompt also lists aliases for the same choice (for example `minimal` and `prototype~1`), keep every listed name on the card; do not rewrite the label at submit — the stage maps synonyms.
+
+**Done when** the option list is the prompt's literal closed set, or the gate stayed in chat.
+
+## Artifact-backed
+
+1. Print the pending message and artifact paths (from `list_waiting`) in this chat. Do not put artifact bodies on the card. Do not call `read_artifact` unless the human asked to open a file.
+2. Open the picker with Accept and Reject.
+3. Accept → submit immediately (`decision: "accept"`).
+4. Reject → one chat follow-up for optional notes, then submit `decision: "reject"` and `text` when they typed notes.
+
+**Done when** the operator has seen the paths in chat and the decision is on the picker (or chat if there is no picker).
+
+## Errors
+
+On MCP `answer_gate` `isError` (400 / 404 / 409) or CLI `sf runs answer` exit `1`, print the payload. Collect a corrected reply on the picker if the gate is still representable; otherwise chat. Then submit again.
+
+**Done when** `{ "ok": true }` or the error payload has been printed and a corrected reply is in hand.

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.