@gobing-ai/spur 0.3.41 → 0.3.43

package/plugins/sp/skills/spur-cli/references/team.md

@@ -0,0 +1,133 @@
+---
+name: spur-cli-team
+description: "spur-cli noun reference: operate `spur team` as the team coordination surface - assign agents to tasks, inspect grouped status, materialize and tear down team rosters, and start/stop supervised agent processes. The lifecycle layer over `spur agent` specs."
+see_also:
+  - spur-cli
+---
+
+# spur team - team coordination and supervision
+
+`spur team` is the CLI for **coordinating team agent assignments and supervision**. It sits above
+`spur agent` specs: `up` / `down` materialize and tear down rosters, `start` / `stop` manage
+supervised processes (requiring `spur serve`), `assign` wires tasks to agents, and `status` reports
+the live picture.
+
+This is a **companion reference**, not an orchestrator. It documents *what each verb is and how to
+use it well*.
+
+## Verb map
+
+| Verb | Purpose | Key flags |
+| ---- | ------- | --------- |
+| `assign <task-id> <agent-id>` | Set the assignee on a task file | - |
+| `status` | List agent specs and their run status; `--by-team` groups by team | `--by-team` `--server <url>` `--json` |
+| `up <team>` | Materialize a team roster into specs; best-effort start | `--check` `--server <url>` `--json` |
+| `down <team>` | Tear down a team: stop members; `--purge` removes generated specs | `--purge` `--server <url>` `--json` |
+| `start <agent-id>` | Start a supervised agent process (requires `spur serve`) | `--server <url>` `--json` |
+| `stop <agent-id>` | Stop a supervised agent process (requires `spur serve`) | `--server <url>` `--json` |
+
+All verbs accept `--json` for machine consumption. `--server <url>` (default:
+`http://localhost:3000/api`) targets the supervisor API started by `spur serve`. **Exit codes:** `0`
+success, `1` error, `2` invalid usage.
+
+## `assign` - wire a task to an agent
+
+```bash
+spur team assign 0040 worker-1
+```
+
+Sets the `assignee` field on the task file `<task-id>` to `<agent-id>`. This is the traceability edge
+between the task corpus and the team roster - it records *who* is responsible, not *what* they run.
+
+## `status` - agent specs and run state
+
+```bash
+spur team status                    # flat list
+spur team status --by-team          # grouped by team:<id> membership
+spur team status --json             # machine-readable
+```
+
+Lists agent specs and their live run status. When `spur serve` is reachable, enriches each spec with
+the supervisor's process status (`running` / `stopped` / etc.); otherwise falls back to local spec
+metadata. `--by-team` groups specs by their `agent.team.<id>` tag.
+
+### Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--by-team` | Group specs by their `agent.team.<id>` membership (0258 R4). |
+| `--server <url>` | Server API URL for live run status (default: `http://localhost:3000/api`). |
+| `--json` | Output machine-readable JSON. |
+
+## `up` - materialize a team roster
+
+```bash
+spur team up alpha                  # materialize + best-effort start
+spur team up alpha --check          # dry-run: show add/prune diff, no writes
+spur team up alpha --json
+```
+
+Materializes a team roster (defined by specs sharing `agent.team.<team>`) into `.spur/agents/`
+specs - adding missing specs and pruning stale `spur:generated` ones. When `spur serve` is
+reachable, best-effort starts each member. `--check` is a dry-run that shows the add/prune diff
+without writing.
+
+### Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--check` | Dry-run: show the add/prune diff without writing. |
+| `--server <url>` | Server API URL (default: `http://localhost:3000/api`). |
+| `--json` | Output machine-readable JSON. |
+
+## `down` - tear down a team
+
+```bash
+spur team down alpha                # stop members
+spur team down alpha --purge        # also delete spur:generated specs
+spur team down alpha --json
+```
+
+Stops all members of `<team>` via the supervisor. `--purge` also deletes specs marked `spur:generated`
+(never manual or `ref:` specs) - use it to fully clean up a materialized roster.
+
+### Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--purge` | Also delete `spur:generated` specs (never manual / `ref:`). |
+| `--server <url>` | Server API URL (default: `http://localhost:3000/api`). |
+| `--json` | Output machine-readable JSON. |
+
+## `start` / `stop` - supervised process control
+
+```bash
+spur team start worker-1            # start supervised process
+spur team stop worker-1             # stop supervised process
+spur team start worker-1 --json
+```
+
+Start or stop a supervised agent process. **Requires `spur serve`** to be running - these verbs go
+through the server's supervisor API (`POST /api/team/start`, `POST /api/team/stop`), not local
+process spawning. The started process runs `spur agent loop --agent <id>` under supervision.
+
+### Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--server <url>` | Server API URL (default: `http://localhost:3000/api`). |
+| `--json` | Output machine-readable JSON. |
+
+## What this skill is NOT
+
+- **Not the agent runner.** `start` launches `spur agent loop` under supervision; the loop's
+  execution primitives are documented in **[agent.md](agent.md)**.
+- **Not the message transport.** Team agents communicate via `spur message`; see
+  **[message.md](message.md)**.
+
+## See also
+
+- **`spur agent` (see [agent.md](agent.md))** - the execution primitives `team start` supervises.
+- **`spur message` (see [message.md](message.md))** - the durable inbox team members drain.
+- **`spur serve` (see [serve.md](serve.md))** - the local server `start`/`stop`/`status` require.
+- **`sp:spur-cli`** SKILL.md - the facade that routes to this reference.

package/plugins/sp/skills/spur-cli/references/workflows/authoring-workflows.md

@@ -0,0 +1,226 @@
+---
+name: authoring-workflows
+description: Author a workflow — mode selection in depth, per-mode real YAML shapes, built-in actions and guards, template variables, and the validate-and-dry-run verification core.
+see_also:
+  - spur-cli
+  - operations
+---
+
+# Authoring Workflows
+
+How to write a workflow definition that validates and runs. Start with mode, then the schema shape for
+that mode, then the actions/guards and template vars, then prove it with validate-and-dry-run.
+
+## Mode selection in depth
+
+The two kinds are not interchangeable. They differ at the schema level:
+
+| | `state-machine` | `transition-flow` |
+| --- | --- | --- |
+| Unit of progress | a **state** the run currently occupies | a **node** the run advances through |
+| Where work happens | `state.onEnter` / `state.onExit` action lists | `node.action` (one action per node) |
+| How the next step is chosen | top-level `transitions[]`, each `{from, to, guard?}`; first guard that passes wins | `edges[]`, each `{from, to, condition?}`; first condition that passes wins; an edge with no condition is unconditional |
+| Looping | first-class — point a transition back to an earlier state | possible but the model is DAG-forward; loops read awkwardly |
+| Node types | none | `type: action \| gate \| parallel \| decision` |
+| Terminal | `terminalStates: [...]` | `terminalNodes: [...]` |
+| `kind` | optional (default) | **required**: `kind: transition-flow` |
+
+**Decide by the dominant shape of the process:**
+
+- A **loop with retries** — implement → check → fix → check until pass — is a state-machine. One thing
+  is active; a guard decides whether to advance or loop back.
+- A **pipeline** — read → validate → transform → write, possibly with a gate or fan-out — is a
+  transition-flow. Each node does one thing and hands off along an edge.
+- When genuinely torn, choose **state-machine** (simpler, the default kind) and record why.
+
+## Per-mode shapes
+
+Copy these real shapes; do not reconstruct from memory. Both quote `$schema` (leading `@` is reserved).
+
+### State-machine
+
+```yaml
+$schema: "@gobing-ai/ts-dual-workflow-engine/schemas/state-machine-workflow.schema.json"
+kind: state-machine            # optional, but include it for legibility
+name: approval
+description: Implement → check → fix until the check passes or the bound is exhausted
+iterationBound: 2              # bounds any loop; required when a transition points backward
+initialState: implement
+terminalStates: [done, failed]
+failureStates: [failed]          # optional; ⊆ terminalStates → status failed (0425)
+vars:
+  reviewer: robin              # ${vars.reviewer}
+env:
+  allow: [APP_ENV]             # only allow-listed names resolve via ${env.APP_ENV}
+states:
+  - id: implement
+    description: Implement the requested task
+    onEnter:
+      - kind: note
+        options:
+          message: "Implementing task: ${task}"
+  - id: check
+    onEnter:
+      - kind: shell
+        options:
+          command: bun run check
+  - id: fix
+    onEnter:
+      - kind: note
+        options:
+          message: "Please fix the issues found"
+  - id: done
+  - id: failed
+transitions:
+  - from: implement
+    to: check
+  # Declaration order matters: the action-ok guard is tried first, so a passing
+  # check short-circuits to done before the unconditional fix edge is considered.
+  - from: check
+    to: done
+    guard: { kind: action-ok }
+  - from: check
+    to: fix
+  - from: fix
+    to: check
+```
+
+Required keys: `name`, `initialState`, `states`, `transitions`. Each state needs an `id`; `onEnter`/
+`onExit` are optional action lists. Each transition needs `from`/`to`; `guard` and `trigger` are
+optional (a transition with no guard is unconditional).
+
+### Transition-flow
+
+```yaml
+$schema: "@gobing-ai/ts-dual-workflow-engine/schemas/transition-flow-workflow.schema.json"
+kind: transition-flow          # REQUIRED — a missing kind parses as state-machine
+name: import-file
+description: Read → validate → done pipeline
+initialNode: read
+terminalNodes: [done]
+vars:
+  file: events.jsonl           # ${vars.file}
+nodes:
+  - id: read
+    type: action
+    action:
+      kind: note
+      options:
+        message: "reading ${vars.file}"
+  - id: validate
+    type: gate
+  - id: done
+edges:
+  - from: read
+    to: validate
+  - from: validate
+    to: done
+    condition: { kind: always }
+```
+
+Required keys: `kind` (`transition-flow`), `name`, `initialNode`, `nodes`, `edges`. Each node needs an
+`id`; `type` (`action`/`gate`/`parallel`/`decision`) and `action` are optional. Each edge needs
+`from`/`to`; `condition` is optional (no condition = unconditional edge).
+
+## Built-in actions and guards
+
+The default host (`createDefaultWorkflowEngineHost()`) registers these. Anything else needs a custom
+runner (see [validation-and-extension.md](validation-and-extension.md)).
+
+| Capability | Kind | Use |
+| ---------- | ---- | --- |
+| Action | `note` | Record a message in the run's result data; the safe no-op for shaping/dry-running |
+| Action | `shell` | Run a shell command via the runtime `ProcessExecutor`; the action "succeeds" or "fails" by exit code |
+| Guard | `always` | Unconditional pass — the default edge condition / fallback transition |
+| Guard | `action-ok` | Pass iff the prior action on this state/node succeeded — useful for a single hard shell check |
+
+Order matters for both guards and conditions: **the first that passes wins.** Put the discriminating
+guard before the unconditional fallback (`always` / no-guard edge). For multi-condition gates (doctor
++ task check, quality gate + attempt cap), prefer a **soft probe** shell that writes PASS|FAIL and
+always exits 0, then branch with ordered status-file guards — see shipped `basic.yaml` /
+`task-pipeline.yaml` (more reliable than `action-ok` alone when more than one condition decides the edge).
+
+## Template variables
+
+Actions receive resolved templates. Available substitutions:
+
+| Template | Source |
+| -------- | ------ |
+| `${vars.NAME}` | Workflow `vars` merged with per-run `vars` (run overrides win) |
+| `${env.NAME}` | Environment values **explicitly listed in `env.allow`** (else empty) |
+| `${runId}` / `${run}` | Current run id |
+| `${workflow}` / `${task}` | Workflow name |
+| `${state}` / `${node}` | Current state or node id |
+| `${iteration}` | Current transition count |
+| `${runtime}` | Execution mode (`state-machine` or `transition-flow`) |
+
+`env.allow` is an allowlist: a `${env.X}` whose `X` is not listed resolves to empty, not an error — a
+common silent surprise. Add the name to `env.allow` for it to resolve.
+
+### Shell commands take vars by name, never by template
+
+**In a `shell` command — action *or* transition guard — reference a var as `$NAME`, not
+`${vars.NAME}`.**
+
+| Where | Spelling | Why |
+| ----- | -------- | --- |
+| `shell` action `command:` | `$NAME` | Value arrives as process env |
+| `shell` guard `command:` | `$NAME` | Same |
+| Everything else (`agent.run` `input:`, `note` `message:`, `description:`, paths in non-shell options) | `${vars.NAME}` | Engine template resolution; never shell-interpreted |
+
+`${vars.NAME}` in a shell command is resolved by the engine **into the command string** before the
+shell runs, so any backtick, `$(…)`, or quote in the value is parsed as shell code. That was a live
+arbitrary-execution defect in both actions (task 0432) and guards (task 0435) — and in a guard it is
+especially quiet, because the injected side effect fires while the comparison still returns an
+ordinary boolean. Spur's runners hand resolved vars to the subprocess as environment instead, and a
+shell variable expansion is never re-parsed for metacharacters, so `$NAME` is always data.
+
+```yaml
+# WRONG — value becomes part of the command
+command: 'test "${vars.profile}" = auto'
+# RIGHT — value arrives as env
+command: 'test "$profile" = auto'
+```
+
+This only works where Spur's runners are registered (`registerSpurBuiltins`, and the lifecycle
+adapter's host). A bare `createDefaultWorkflowEngineHost()` keeps the engine's env-less runners,
+where `$NAME` would expand to empty — register the Spur runners on any new host.
+
+## Error policy (`onError`)
+
+`onError` is a current **library/runtime capability**, not a normal quoted-`$schema` YAML authoring
+field. The TypeScript schema accepts it and the drivers resolve it at three levels with precedence
+`action.onError ?? workflow.defaultOnError ?? runOptions.onError ?? 'fail'`, but the bundled JSON
+schemas used by `spur workflow validate <file> --json` when `$schema` is present do not yet list
+`onError` / `defaultOnError`.
+
+- **`fail`** — the run halts immediately with `status: 'failed'` on the first action error.
+- **`continue`** — logs a non-fatal warning and advances to the next guard/edge evaluation. A node
+  with no outbound edges that fails under `continue` still terminates as `done`.
+
+For CLI-authored YAML, keep the default fail-fast behavior and model best-effort behavior explicitly
+with guards/branches until the JSON schemas catch up. Use YAML-level `onError` only when you
+intentionally validate with `--no-schema` and own the compatibility tradeoff.
+
+## The validate-and-dry-run core
+
+Authoring is not done until the workflow is proven. The core (full steps in
+[operations.md](operations.md#sub-procedure-validate-and-dry-run)):
+
+1. `spur workflow validate <file> --json` — schema + semantic. Fix until clean.
+2. `spur workflow run <file> --run-id dryrun-<unique> --json` — **`status` is authoritative for
+   pass/fail** (`done` success / `failed` failure); then assert `finalState === <expected>`.
+   Use a fresh `--run-id` (duplicates raise `RunCollisionError`).
+3. Read the trace; on a stall or wrong terminal, fix the specific guard/target/bound and re-run.
+
+A `shell` action runs for real during the dry-run — keep it idempotent and side-effect-light while
+verifying shape, or stand in a `note` action until the path is proven, then swap the real command in.
+
+## Authoring checklist
+
+- [ ] Mode chosen deliberately (loop → state-machine; pipeline → transition-flow); recorded the reason.
+- [ ] `kind: transition-flow` set for flows; `$schema` quoted.
+- [ ] Initial + terminal states/nodes declared; every transition/edge target exists.
+- [ ] Guards/conditions ordered so the specific case precedes the fallback.
+- [ ] `iterationBound` set for any loop; `env.allow` lists every `${env.X}` used.
+- [ ] Validates clean AND dry-run reaches the expected terminal state.

package/plugins/sp/skills/spur-cli/references/workflows/operations.md

@@ -0,0 +1,211 @@
+---
+name: operations
+description: Named operation procedures (validate/run/list/trace/continue/cancel/clean/add/refine), the mode-selection gate, and the shared find-existing-workflow and validate-and-dry-run cores that back the spur workflow slash commands.
+see_also:
+  - spur-cli
+---
+
+# Operations
+
+The skill's operations as discrete procedures. The deterministic ones (`validate`, `run`, `list`,
+`trace`, `continue`, `cancel`, `clean`) are direct CLI verbs — documented briefly here for completeness,
+but you run them straight (no slash command). The agent-driven ones (`add`, `refine`) convert fuzzy
+intent into a reliable sequence and are what the slash commands delegate to; their full steps live below.
+
+A workflow you have not watched run is a workflow you do not trust. So both `add` and `refine` end in
+the same verification core ([validate-and-dry-run](#sub-procedure-validate-and-dry-run)) — that shared
+core is why a tuned workflow is re-checked exactly like a freshly authored one. `add` and `refine` also
+share the [find-existing-workflow](#sub-procedure-find-existing-workflow) core so the workflow catalog
+never diverges no matter which operation touches it. `add` additionally runs the
+[mode-selection gate](#sub-procedure-mode-selection-gate) — the one decision unique to this skill.
+
+## Workflow location convention
+
+Authored workflows default to a project-local directory, grouped by purpose:
+
+```
+.spur/workflows/<name>.yaml          # project workflows (the convention)
+```
+
+A `--file <path>` argument overrides the default. Keep one workflow per file, named for what it does
+(`approval.yaml`, `import-file.yaml`), not for its mode. The canonical example
+(`.spur/workflows/basic.yaml`) lives here; copy real schema shapes from it rather than from a
+half-remembered snippet.
+
+## Sub-procedure: mode-selection gate
+
+The decision unique to workflows — run this **before authoring anything new**. The two kinds use
+different schemas and a different mental model; switching later is a rewrite. Inputs: the described
+process (one or two sentences). Steps:
+
+1. **Classify the process shape** against the discriminators (SKILL.md → "Choose the execution mode
+   first"):
+
+   | Signal in the description | → mode |
+   | ------------------------- | ------ |
+   | "loop until", "retry", "keep checking", one thing active at a time, can go back a step | **state-machine** |
+   | "then", "pipeline", "for each", fan-out, gate/decision, action-per-step, mostly forward | **transition-flow** |
+   | Genuinely ambiguous | **state-machine** (the simpler default) — and say so |
+
+2. **Honor an explicit `--kind`** — if the caller passed `--kind`, use it; skip to step 4 and just
+   record the rationale for the record.
+3. **Recommend + confirm** — surface the recommended mode, the **reason** (which discriminator
+   decided it), and the **rejected alternative** (what the other mode would have implied). Require
+   confirmation before authoring. This is the human-in-the-loop gate; do not silently pick a mode the
+   user did not see.
+4. **Lock the mode** — for transition-flow, the YAML **must** set `kind: transition-flow` (a missing
+   `kind` parses as state-machine and fails confusingly). For state-machine, `kind` is optional but
+   include it for legibility.
+
+Output contract: `{ mode, reason, rejectedAlternative }` + the confirmed mode to author in.
+
+## Sub-procedure: find-existing-workflow
+
+Reconciliation core — run this **before authoring anything**. Authoring without checking the existing
+workflows breeds redundant, diverged definitions (two near-identical approval flows, an import flow
+re-implemented under a new name). Inputs: the clarified process intent. Steps:
+
+1. **Enumerate existing workflows** — list `.spur/workflows/*.yaml` (and any `--file`-adjacent
+   directory); read each one's `name`, `kind`, and the states/nodes it defines so matches are found by
+   *substance*, not just by filename.
+2. **Classify the strongest match** against the new intent:
+
+   | Match | Meaning | Action |
+   | ----- | ------- | ------ |
+   | Same process, same shape | A workflow already does this | **STOP — do not add.** It exists; if behavior is off, hand to [refine](#refine). |
+   | Same process, extra steps needed | An existing flow is close but missing a state/node/branch | **EXTEND** via [refine](#refine) — add to the existing flow, don't fork it. |
+   | Adjacent / overlapping concern | A related flow exists but the new intent is distinct | **ADD new** — the genuinely new branch. |
+   | No real match | New process | **ADD new.** |
+
+3. **Recommend + confirm** — report the strongest match, the classification, and the recommended
+   action (extend-via-refine / add-new). Require confirmation before authoring. Never silently
+   duplicate an existing workflow, and never silently edit one the user did not name.
+
+Output contract: `{ match: workflow-name|none, classification, recommendation, evidence }` + the
+confirmed action to take.
+
+## Sub-procedure: validate-and-dry-run
+
+The shared verification core. Inputs: a workflow file path + the expected terminal state. Steps:
+
+1. **Validate** — `spur workflow validate <file> --json`. Runs the structural Zod schema **and**
+   semantic invariants (referenced states/nodes exist, terminal reachable, `${...}` templates resolve).
+   On error, surface root-cause + fix (see [validate](#validate--list-direct-cli)); stop until clean.
+   The most common errors are an unquoted `$schema` (`@` is YAML-reserved) and a missing
+   `kind: transition-flow` on a flow definition.
+2. **Dry-run** — `spur workflow run <file> --dry-run --run-id dryrun-<unique> --json`. Use a throwaway, unique
+   `--run-id` (a duplicate raises `RunCollisionError`). **`status` is authoritative for pass/fail**
+   (`done` = success, `failed` = failure; CLI exit is non-zero unless `status === 'done'`). Then
+   assert `finalState === <expected>` to confirm *which* terminal was reached. A `status: 'failed'`
+   (including a declared failure terminal such as `failed`/`cancelled`) or a wrong success
+   `finalState` means the workflow does not behave as intended — read the trace.
+3. **Read the trace** — confirm the run entered the intended states/nodes and took the intended
+   transitions/edges. A run that stalls short of the expected terminal points at a guard/condition that
+   never passed, a mistyped target, or an exhausted `iterationBound`. Fix the **specific** definition
+   flaw, never restructure to mask it.
+4. **Report** — `{ valid, ranToExpectedTerminal, tracePath }`. The workflow is verified only when the
+   definition validates AND the dry-run reaches the expected terminal state.
+
+> A `shell` action runs real commands during the dry-run. Keep authored-workflow shell actions
+> idempotent and side-effect-light, or stub them with a `note` action while verifying shape, then
+> swap the real command in once the path is proven. Never point a dry-run at a destructive command.
+
+## validate / list / trace / continue / cancel / clean (direct CLI)
+
+Deterministic single-verb CLI calls. Run them straight; the skill interprets results when asked.
+
+- `spur workflow validate <file> [--no-schema] --json` — structural schema + semantic check. Classify
+  any error as **schema** (violates the state-machine/transition-flow JSON schema — often an unquoted
+  `$schema`, or a flow missing `kind: transition-flow`) vs. **semantic** (a transition references a
+  state that doesn't exist, a terminal state is unreachable, a `${vars.x}` with no matching var, an
+  `${env.X}` not in `env.allow`). The `validate-and-dry-run` core calls this as step 1. `--no-schema`
+  skips only the `$schema` ref resolution, keeping the structural + semantic checks.
+- `spur workflow list --json` — available **workflow YAML definition files** on disk (not run history).
+- `spur workflow trace [run-id] [--workflow <n>] [--status <s>] [--since <iso>] [--last <n>] --json` —
+  persisted run history (list filters) or a single-run timeline when `run-id` is given. Use this to
+  inspect prior outcomes; do **not** use `list` for that.
+- `spur workflow continue [run-id] [--yes] --json` — resume a paused HITL run (omit id → most recent
+  paused).
+- `spur workflow cancel <run-id> --json` — mark one non-terminal run failed (SIGTERM async worker
+  process group when live).
+- `spur workflow clean [--older-than <min>] [--force] [--dry-run] --json` — bulk-finalize stale
+  `running`/`pending` runs (default age threshold 30 minutes; `--force` ignores age).
+
+## run (direct CLI — dry-run / execution / async)
+
+`spur workflow run` is a direct CLI verb; there is no slash command for it. The skill drives it as the
+dry-run step of the harness loop, and operators run it directly to execute a real workflow. Procedure:
+
+1. `spur workflow run <file> [--run-id <id>] [--vars <json>] [--dry-run] [--async] [--no-plan] --json`.
+2. Sync path: **`status` is authoritative for pass/fail** (`done` | `failed` | `paused` | …).
+   Exit code is non-zero unless `status === 'done'`. Read `finalState` only to identify which
+   terminal was reached (e.g. `failed` vs `cancelled` after a failure-terminal finalize). Do not
+   treat `status: 'done'` + a failure-named `finalState` as success — declared `failureStates`
+   finalize as `status: 'failed'` (0425).
+3. `--dry-run`: walk transitions without executing actions (preferred for the authoring harness loop).
+4. `--async`: spawn a detached worker, exit immediately with `runId`; monitor via
+   `spur workflow trace <run-id>`. Cancel with `spur workflow cancel <run-id>`.
+5. On `failed`, read the run trace (states/nodes entered, transitions taken) to locate the offending
+   step — a failed action, a declared failure terminal, a guard with no passing transition, or an
+   exhausted `iterationBound`.
+6. A failed run is data, not an exception — the run record is preserved. Fix the definition (for the
+   dry-run loop) or the environment/action (for a real run), then re-run with a fresh `--run-id`.
+
+Output contract (sync): `status` (authoritative pass/fail) + `finalState` + parsed trace + the
+offending-step diagnosis on failure. Async: `{ runId, status: 'started', workflowName }`.
+
+## add
+
+Turn a described process into a validated, dry-run-verified workflow in the right mode. Procedure:
+
+1. **Clarify intent** — restate the process as one or two sentences: the steps, the success terminal,
+   the loop/branch points. If ambiguous (which step retries? what ends it?), state the interpretation
+   taken.
+2. **Mode-selection gate** — run [mode-selection gate](#sub-procedure-mode-selection-gate). This is
+   mandatory and gating: surface the recommended mode with its reason and the rejected alternative,
+   and **confirm before authoring**. Honor an explicit `--kind`.
+3. **Reconcile against existing workflows** — run [find-existing-workflow](#sub-procedure-find-existing-workflow).
+   If the process is already covered, **stop and hand to refine (or extend the existing flow) on
+   confirmation** — do not author a redundant workflow. Only the "no real match" / "add-new" branch
+   proceeds to author below.
+4. **Author the YAML** — use the **real schema shape** for the chosen mode
+   ([authoring-workflows.md → Per-mode shapes](authoring-workflows.md#per-mode-shapes)). Set `name`,
+   `description` (the WHY), the initial + terminal states/nodes, the steps with their actions, the
+   transitions/edges with guards/conditions in the right declaration order, `iterationBound` for any
+   loop, `env.allow` for any `${env.X}`, and a quoted `$schema`. For transition-flow, set
+   `kind: transition-flow`.
+5. **Place the file** — default `.spur/workflows/<name>.yaml` (a `--file` arg overrides), named for
+   what the workflow does.
+6. **Verify** — run the [validate-and-dry-run core](#sub-procedure-validate-and-dry-run) with the
+   expected terminal state. Not done until the definition validates AND the dry-run reaches it.
+
+Output contract: YAML workflow content + chosen mode + reason + destination path + validate result +
+dry-run result (status, finalState, expected). Done only when validate passes AND the dry-run reaches
+the expected terminal state.
+
+## refine
+
+Adjust an existing workflow with the smallest change that meets the intent. Procedure:
+
+1. **Locate the target** — if a workflow file is named, load it. If the user describes a *process*
+   instead ("the approval flow never reaches done"), run
+   [find-existing-workflow](#sub-procedure-find-existing-workflow) to resolve which file they mean
+   before editing. Read its current shape and mode.
+2. **Identify the dimension** from `--intent`:
+   - stuck run (never reaches terminal) → a guard/condition that never passes, a wrong transition
+     target, or an exhausted `iterationBound`
+   - missing step → add a state/node + its transition/edge in the correct declaration order
+   - runaway loop → set or raise `iterationBound`
+   - missing variable/env → add to `vars` or `env.allow`
+   See [authoring-workflows.md](authoring-workflows.md) for each mechanism's real shape. **Do not
+   switch mode** in a refine — a mode change is a rewrite; hand it back to `add`.
+3. **Apply the smallest change.** Preserve declaration order semantics (the first passing
+   guard/condition wins). Add a one-line rationale comment for any non-obvious choice such as an
+   `iterationBound`. No drive-by restructuring.
+4. **Preview if `--dry-run`** — emit a unified diff of the YAML change and stop (no write). This is a
+   skill-level output; the CLI has no dry-run for edits.
+5. **Verify** — run the [validate-and-dry-run core](#sub-procedure-validate-and-dry-run). A refine that
+   fixes a stuck run must prove it: the run that previously stalled now reaches the expected terminal.
+
+Output contract: diff of the change + validate result + dry-run result (status, finalState, expected).
+With `--dry-run`, the diff only.