@kontextmind/kxm 0.7.95 → 0.7.96

package/docs/reference/workflow-definitions.md

@@ -0,0 +1,286 @@
+# Workflow definition reference
+
+KXM has two kinds of workflow definition. A **webhook workflow definition** is JSON that the [hub](../glossary.md#hub) loads; a signed webhook starts a run, and one coordinator agent works through its ordered **stages**. A **Runtime workflow** is a `kxm.workflow.v1` YAML file in your project; `kxm run` starts it, and the local Runtime executes its **steps**. This page compares the two, documents every field of the JSON format, and summarizes the YAML format with links to its full reference.
+
+## Two workflow systems
+
+| | Webhook workflow definition | Runtime workflow |
+|---|---|---|
+| Format | JSON array of definitions | YAML file with `schema: kxm.workflow.v1` |
+| Location | Any JSON file named by `KXM_WEBHOOK_WORKFLOWS_FILE`, or inline in `KXM_WEBHOOK_WORKFLOWS` | `.kxm/workflows/<id>.yaml`, tracked in Git |
+| Loaded by | The hub, once at start | Every project load (`kxm init`, `kxm run`) |
+| Units | Stages, in order | Steps, connected by typed transitions |
+| Started by | A signed `POST /v1/webhooks/<id>`, or `kxm workflow start` | `kxm run <workflow> [prompt]` |
+| Who does the work | One coordinator agent, prompted with every stage, using the [workflow tools](tools.md#workflow-tools) | The Runtime: agent steps through a model producer, gate steps by running `.kxm/gates.yaml` commands |
+| Evidence | Keyed strings plus verified peer replies | Gate evidence the Runtime records itself |
+| External results | `kxm_workflow_wait`, then a signed signal | Recovery signals only; `wait` steps compile but are not matched yet |
+| Inspect with | `kxm_workflow_get`, `kxm workflow get`, `kxm dash` | `kxm runs status`, `kxm runs list` |
+| Validate with | `kxm gate validate` | `kxm init --dry-run`, `kxm run --dry-run` |
+
+Both kinds of run have IDs of the form `run_<32 hex>`. The journal, checkpoints and waits belong to webhook runs only.
+
+## Webhook workflow definitions
+
+### Load definitions
+
+The hub reads its definitions once, at start, from exactly one source:
+
+- `KXM_WEBHOOK_WORKFLOWS_FILE`: a path to a JSON file holding an array of definitions;
+- `KXM_WEBHOOK_WORKFLOWS`: the same array, inline.
+
+Setting both, or an invalid definition, stops the hub from starting. Restart the hub to load a change. Check a file first; the command parses the same source the hub loads and never prints secrets:
+
+```bash
+export JIRA_WEBHOOK_SECRET="replace-with-a-start-secret"
+export WORKFLOW_SIGNAL_SECRET="replace-with-a-signal-secret"
+kxm gate validate --file .kxm/assets/webhooks/workflows.json
+```
+
+Expected output for the [example](#example) below:
+
+```text
+validated 1 workflow(s) from file with 1 warning(s)
+```
+
+Keep the file out of `.kxm/config/workflows/`: any JSON there counts as legacy configuration and makes the whole project unloadable (`legacy_state_unsupported`). Do not point the hub at `.kxm/workflows/*.yaml` either; those are Runtime workflows and do not parse as JSON. Unknown fields are ignored, except inside `evidencePolicies`, where they are refused. Errors are plain messages rather than codes.
+
+### Definition fields
+
+| Field | Type and limits | Default | Effect |
+|---|---|---|---|
+| `id` | String, 64 characters, unique | Required | The URL segment in `/v1/webhooks/<id>` and the name `kxm workflow start` takes |
+| `source` | `jira`, `github` or `generic` | `generic` | Recorded on each run; does not change how requests are read |
+| `project` | String, 128 characters | Required | Hub project the run and its coordinator belong to |
+| `target` | Agent name or ID, 80 characters | Required | The coordinator. It must have registered at least once before a run starts; it may be offline |
+| `secretEnv` | Environment variable name | Use this or `secret` | Variable holding the start secret, read when the definitions are parsed |
+| `secret` | String, 16 to 512 characters | Use this or `secretEnv` | The start secret inline. Prefer `secretEnv` |
+| `signalSecretEnv`, `signalSecret` | As above | The start secret | Separate secret for result callbacks |
+| `event` | String, 128 characters | Any event | Only deliveries with this event start a run; others get 204 |
+| `filter.path`, `filter.equals` | Dotted payload path (256), exact string (512) | No filter | Only payloads whose value at the path equals the string start a run; others get 204 |
+| `delivery` | `followUp` or `steer` | `followUp` | Delivery mode of the coordinator's prompt |
+| `ttlMs` | Integer, 1,000 to 604,800,000 | The hub's `KXM_MESSAGE_TTL_MS` | Lifetime of the coordinator prompt and each resume message |
+| `promptTemplate` | String, 20,000 characters | Required | Task text with `{{dotted.path}}` placeholders filled from the payload |
+| `maxTransitions` | Integer, 1 to 200 | No global budget | Run-wide budget on declared transitions. Required when any stage has a back-edge |
+| `planHash` | `{ "stageId", "evidenceKey" }` | None | See [Plan hash and reproduction oracle](#plan-hash-and-reproduction-oracle) |
+| `reproOracle` | `{ "stageId", "evidenceKey" }` | None | As above |
+| `requirePlanHash` | Array of stage IDs | None | Stages that cannot checkpoint until the plan hash is captured |
+| `stages` | 1 to 32 stages | Required | In execution order |
+
+A placeholder whose value is an object is filled with its JSON; a missing value becomes empty. The hub adds the run ID, every stage with its required evidence and peer policies, and the coordinator's rules to the rendered template. The whole prompt must fit in 32,000 characters, or the start is refused.
+
+### Stage fields
+
+| Field | Type and limits | Default | Effect |
+|---|---|---|---|
+| `id` | String, 64 characters, unique in the definition | Required | The `stageId` in tool calls |
+| `label` | String, 128 characters | The `id` | Display name |
+| `instructions` | String, 4,000 characters | Required | What the coordinator does in this stage |
+| `requiredEvidence` | Up to 32 unique strings of 128 characters | `[]` | Evidence keys a passing checkpoint must cover |
+| `maxAttempts` | Integer, 1 to 20 | `3` | Warning or failed checkpoints allowed before the run fails |
+| `autoResumeLimit` | Integer, 1 to 20 | None | Attempts after which the stage escalates to an operator |
+| `area` | `harness`, `gates`, `implementation`, `workflow`, `documentation`, `security` or `other` | None | Default area for this stage's journal entries |
+| `evidencePolicies` | Map of required key to a policy | None | Keys that only verified peer replies can satisfy |
+| `on` | Map of outcome key to a transition | None | Declared transitions; see [Transitions and outcome keys](#transitions-and-outcome-keys) |
+| `maxTransitions` | Integer, 1 to 100 | None | Budget on transitions taken out of this stage |
+
+Evidence keys are compared after trimming, collapsing inner whitespace and lowercasing, so `Peer Reviews` and `peer reviews` are the same key; duplicates after normalizing are refused.
+
+### Evidence policy fields
+
+A policy turns one required key into a peer-reply requirement: only replies from eligible peers, requested with the run's exact `workflowContext` and cited in `evidenceRefs`, can satisfy it.
+
+| Field | Type and limits | Default | Effect |
+|---|---|---|---|
+| `kind` | `peer-reply` | Required | The only kind |
+| `minProducers` | Integer, 1 to 8 | Required | Unique eligible agents whose replies are needed; at most the number of eligible agents |
+| `eligibleAgents` | 1 to 16 unique agent names or IDs | Required | Who may produce the evidence. Must not include `target` |
+| `acceptedStatuses` | Exactly `["replied"]` | `["replied"]` | Only replied messages count |
+| `degradation.minProducers` | Integer, at least 1 and lower than `minProducers` | None | The lowest minimum an operator may approve; below 2 validates with a warning |
+
+The policy key must also appear in `requiredEvidence`. When a run starts, the hub resolves the eligible agents to stable agent IDs and snapshots them on the run. The start fails with 409 if an eligible agent never registered (`workflow_target_unavailable`), resolves to the coordinator (`workflow_evidence_policy_invalid`), or leaves fewer unique producers than `minProducers` (`workflow_evidence_policy_unresolvable`).
+
+An operator approves a degraded minimum for the current attempt with `kxm gate degrade`, which needs the admin token. The approval is journaled and does not pass the stage; the coordinator still cites the approved number of replies. [Peer provenance and quorum gates](../guides/provenance-gates.md) explains what quorum does and does not prove.
+
+### How a stage passes
+
+- An ordinary required key is satisfied by any non-empty string under that key, from the checkpoint itself, from earlier `kxm_workflow_wait` calls in this stage, or from the callback.
+- A peer-policy key is satisfied only by verified `evidenceRefs` from distinct eligible producers for this run, stage, requirement and attempt. Evidence strings never satisfy it, and replies requested for an earlier attempt do not count.
+- Evidence sent with a `warning` or `failed` checkpoint or callback is recorded in the journal but not kept for the next attempt.
+- A `passed` checkpoint missing any key is refused with `workflow_evidence_incomplete`, which lists the missing keys; it does not consume an attempt.
+
+The following diagram shows one stage's states.
+
+```mermaid
+stateDiagram-v2
+  state "failed or warning" as exhausted
+  [*] --> in_progress: first stage, when the run starts
+  [*] --> pending: every other stage
+  pending --> in_progress: previous stage passed, or a transition enters it
+  in_progress --> in_progress: warning or failed, attempts remain
+  in_progress --> pending: declared failure transition to another stage
+  in_progress --> waiting: kxm_workflow_wait, or autoResumeLimit reached
+  waiting --> in_progress: signed signal, then checkpointed
+  in_progress --> passed: passed with complete evidence
+  in_progress --> exhausted: last attempt not passed, run fails
+  waiting --> exhausted: wait expires, run fails
+  passed --> [*]
+  exhausted --> [*]
+```
+
+### Transitions and outcome keys
+
+Without an `on` map, a stage follows default edges: `passed` moves to the next pending stage (or completes the run after the last stage), and `warning` or `failed` retries the same stage until `maxAttempts`.
+
+Each `on` key is an outcome key, and each value is a stage ID, `$terminal`, or `{ "target": "<stage or $terminal>", "maxTransitions": <1 to 100> }`.
+
+- **Outcome keys.** The key is the checkpoint's or signal's status: `passed`, `warning` or `failed`. The checkpoint route also accepts an `outcome` field naming a custom key, but no KXM tool or command sends one.
+- **Forward targets.** A transition may target only the next stage, so a gate stage cannot be skipped. Targeting a later stage is refused when the definitions load.
+- **Back-edges.** A target at or before the current stage is a back-edge. Any back-edge requires the definition's `maxTransitions`.
+- **Budgets.** The per-edge `maxTransitions`, the stage's `maxTransitions` and the definition's `maxTransitions` all count transitions already taken. Exhausting any of them fails the run and journals a `transition_budget_exhausted` error.
+- **Entering a stage.** A transition resets the target stage's attempts and evidence. A stage left on a failure transition returns to `pending`.
+- **After a back-edge.** The default `passed` edge enters the first `pending` stage in definition order. Stages between the back-edge target and the stage that took it are still `passed` from before, so they are skipped, not re-run. To re-run them, declare `on.passed` on each stage explicitly, naming the next stage.
+- **Last attempt.** A failure transition is taken only while attempts remain; a stage's last failing attempt fails the run.
+- **`$terminal`.** Completes the run, whichever outcome led there. It takes no terminal status.
+
+Every transition taken is journaled as a `state-change` entry.
+
+### Waits, signals and escalation
+
+`kxm_workflow_wait` parks the active stage in `waiting` under a `signalKey` until a signed callback arrives or the wait expires (1 second to 30 days, default 24 hours; expiry fails the run). The coordinator can then reply to release its turn.
+
+The callback is `POST /v1/webhooks/<id>/runs/<runId>/signals/<signalKey>`, signed with HMAC-SHA256 of the raw body using the signal secret (or the start secret), with a delivery ID header. Its body carries `status`, `summary` and `evidence`. Evidence keys `workflow.run`, `workflow.stage` and `workflow.signal`, when present, must match the route (`workflow_signal_context_mismatch`). The signal checkpoints the stage with its status; if work remains, the hub sends the coordinator a resume message. See the [HTTP API](http-api.md#webhooks-and-signals) for headers and deduplication.
+
+When `autoResumeLimit` is set and a stage's attempts reach it without passing, the stage escalates instead of retrying: it waits for signal key `audit_escalation` for 24 hours and records a `kxm.terminal-receipt.v1` receipt. A signed `audit_escalation` signal, or `kxm role resume`, resumes it. Anyone holding the signal secret can clear an escalation.
+
+> [!IMPORTANT]
+> Inside a KXM project (a Git repository with `.kxm/project.yaml`), `kxm gate signal`, `kxm workflow signal`, `kxm workflow wait` and `kxm role resume` send every `run_…` ID to the local Runtime, and hub run IDs use the same form. To signal a hub run from the CLI, run `kxm gate signal` outside any KXM project. `kxm gate github watch` and the agent tools always reach the hub.
+
+### Plan hash and reproduction oracle
+
+Both take `{ "stageId", "evidenceKey" }`. When `stageId` passes, the hub records the SHA-256 of that stage's values for `evidenceKey`.
+
+- **`planHash`** records the approved plan. Stages listed in `requirePlanHash` refuse checkpoints with `plan_hash_required` until it exists.
+- **`reproOracle`** records a confirmed reproduction. A later checkpoint that cites the same key with different values is refused with `weakened_reproduction`, so a reproduction cannot be weakened to make a fix pass.
+
+### What else ends or records a run
+
+- **Early reply.** A coordinator reply while the run is `running` fails it, with an `error` journal entry. Reply only after the last checkpoint, or after `kxm_workflow_wait`.
+- **Prompt expiry.** If the coordinator's prompt expires while the run is `running`, the run fails.
+- **Retrospective.** When a run completes or fails, the hub writes a proposed retrospective (JSON and Markdown) under `.kxm/assets/retrospectives/`.
+- **Retention.** Finished runs and their journal are purged from the hub after 7 days. The retrospective files remain.
+
+### Limits
+
+| Item | Limit |
+|---|---|
+| Definitions | Unique `id`s; each ID 64 characters |
+| Stages per definition | 1 to 32 |
+| Required evidence per stage | 32 keys of 128 characters |
+| Peer policy | `minProducers` 1 to 8; `eligibleAgents` 1 to 16 |
+| Attempts | `maxAttempts` and `autoResumeLimit` 1 to 20 |
+| Transition budgets | Edge and stage 1 to 100; definition 1 to 200 |
+| Secrets | 16 to 512 characters |
+| Prompt | Template 20,000 characters; rendered prompt 32,000 |
+| Message lifetime (`ttlMs`) | 1 second to 7 days |
+| Signal wait | 1 second to 30 days |
+
+Checkpoint and journal limits are in [Protocol limits](configuration.md#workflows-and-context).
+
+### Example
+
+This definition plans with two independent peer reviews, implements, then waits for CI and loops back to implementation at most twice on a failed CI signal. It validates with one warning, for the degraded minimum of 1.
+
+`.kxm/assets/webhooks/workflows.json`:
+
+```json
+[
+  {
+    "id": "jira-development",
+    "source": "jira",
+    "project": "payments",
+    "target": "coordinator",
+    "secretEnv": "JIRA_WEBHOOK_SECRET",
+    "signalSecretEnv": "WORKFLOW_SIGNAL_SECRET",
+    "event": "jira:issue_updated",
+    "filter": { "path": "issue.fields.status.name", "equals": "In Progress" },
+    "delivery": "followUp",
+    "ttlMs": 86400000,
+    "maxTransitions": 6,
+    "planHash": { "stageId": "plan", "evidenceKey": "approved plan" },
+    "requirePlanHash": ["implement"],
+    "promptTemplate": "Deliver {{issue.key}}: {{issue.fields.summary}}",
+    "stages": [
+      {
+        "id": "plan",
+        "label": "Plan and review",
+        "instructions": "Produce a plan and collect two independent peer reviews.",
+        "requiredEvidence": ["approved plan", "peer reviews"],
+        "evidencePolicies": {
+          "peer reviews": {
+            "kind": "peer-reply",
+            "minProducers": 2,
+            "eligibleAgents": ["reviewer-claude", "reviewer-grok"],
+            "acceptedStatuses": ["replied"],
+            "degradation": { "minProducers": 1 }
+          }
+        },
+        "maxAttempts": 3,
+        "area": "workflow",
+        "on": { "passed": "implement" }
+      },
+      {
+        "id": "implement",
+        "label": "Implement",
+        "instructions": "Implement the approved plan.",
+        "requiredEvidence": ["diff"],
+        "maxAttempts": 3,
+        "autoResumeLimit": 2,
+        "area": "implementation",
+        "on": { "passed": "ci" }
+      },
+      {
+        "id": "ci",
+        "label": "Wait for CI",
+        "instructions": "Call kxm_workflow_wait and let kxm gate github watch report the checks.",
+        "requiredEvidence": ["github.check:ci"],
+        "maxAttempts": 3,
+        "area": "gates",
+        "on": {
+          "passed": "$terminal",
+          "failed": { "target": "implement", "maxTransitions": 2 }
+        },
+        "maxTransitions": 2
+      }
+    ]
+  }
+]
+```
+
+[Webhook workflows](../guides/webhook-workflows.md) walks through running a definition like this end to end.
+
+## Runtime workflows (`kxm.workflow.v1`)
+
+A Runtime workflow is a YAML file whose name is its ID. The [configuration file reference](config-reference.md#kxmworkflowsidyaml-kxmworkflowv1) documents every field and error code; this table summarizes the parts that differ most from webhook definitions.
+
+| Topic | Summary | Full reference |
+|---|---|---|
+| Top level | `schema`, `description`, `coordinator`, `limits` (`maxTransitions`, `maxRunDurationMs`, `maxAgentTimeMs`, `maxModelCost`, `currency`), `planHash`, `reproOracle`, `requirePlanHash`, and 1 to 128 `steps` | [Top-level fields](config-reference.md#top-level-fields) |
+| Step kinds | `agent`, `moa`, `gate`, `approval`, `wait`; `workflow` is reserved | [Step fields](config-reference.md#step-fields) |
+| Parallel work | `assignments` (allowed agents, counts, `distinctBy`) and `join` (`all`, `all-settled`, `quorum`, `first-success`) | [Assignments and join](config-reference.md#assignments-and-join) |
+| Evidence | `requiredEvidence` entries with a `kind` and an optional `producerPolicy` | [Evidence requirements](config-reference.md#evidence-requirements) |
+| Transitions | `on` is required on every step. `$terminal` needs `terminalStatus` (`completed`, `failed` or `cancelled`). Each back-edge needs its own `maxTransitions`, plus `limits.maxTransitions` | [Transitions and outcomes](config-reference.md#transitions-and-outcomes) |
+| Gate outcome keys | An `expect: pass` gate produces `passed` or `implementation-failure`; an `expect: fail` gate produces `passed` or `repro-missing`. Declare both produced outcomes | [Transitions and outcomes](config-reference.md#transitions-and-outcomes) |
+| `gate_outcome_impossible` | Refused at load when a gate step declares an outcome it never produces, such as `failed`, and omits one it produces. `gate_outcome_renamed` catches underscore spellings | [Transitions and outcomes](config-reference.md#transitions-and-outcomes) |
+| Agent steps | The model returns a JSON `outcome` from the step's declared keys; anything else becomes `failed`, so declare `failed` | [Transitions and outcomes](config-reference.md#transitions-and-outcomes) |
+| Not executed yet | Some valid fields make the Runtime hand the run off (`step_unsupported`, `gate_unsupported`, `limit_unsupported`) instead of executing | [Steps the Runtime does not execute yet](config-reference.md#steps-the-runtime-does-not-execute-yet) |
+
+`kxm workflow add --template <name>` writes a valid starting file from a built-in template (`implement-and-verify`, `dual-critic-review` or `spec-and-plan`). `kxm run <workflow>` creates a run and prints the commands that drive it with the model-free simulation (`kxm runs drive <runId> --simulated --wait`) or cancel it. See [`kxm run`](cli-reference.md#kxm-run) and [`kxm runs`](cli-reference.md#kxm-runs).
+
+## Related
+
+- [Webhook workflows](../guides/webhook-workflows.md): start, wait for and resume a webhook run
+- [Peer provenance and quorum gates](../guides/provenance-gates.md): evidence policies in practice
+- [Agent tools](tools.md#workflow-tools): the coordinator's workflow tools
+- [Hub HTTP API](http-api.md#webhooks-and-signals): signed start and signal requests
+- [Configuration file reference](config-reference.md#kxmworkflowsidyaml-kxmworkflowv1): every `kxm.workflow.v1` field
+- [Workflow catalog](workflow-catalog.md): the area, workflow and role taxonomy

package/docs/start/first-workflow.md

@@ -0,0 +1,287 @@
+# Run your first workflow
+
+A [workflow](../glossary.md#workflow) is a reviewed YAML file in `.kxm/workflows/` that the local [Runtime](../glossary.md#runtime) runs step by step. In this tutorial you add a workflow from a built-in template, review and commit it, and drive a run to a verified completion without calling any model. [Understand the workflow](#understand-the-workflow) then explains what you ran.
+
+## Before you begin
+
+- The `kxm` CLI. See [Install KXM](install.md#install-the-cli).
+- A KXM project whose `.kxm/` is committed to Git. Steps [1](quickstart-claude-code.md#1-initialize-the-project) and [2](quickstart-claude-code.md#2-ignore-runtime-state-and-commit-kxm) of the Claude Code quick start create one.
+- Nothing else. The drive in this tutorial is simulated, so it needs no model credentials, and runs work without a hub: the Runtime sends run summaries to the bound hub whenever one is running.
+
+## How a first run works
+
+A new workflow reaches a finished run through one human decision: your reviewed commit.
+
+```mermaid
+flowchart LR
+  A["Add .kxm/workflows/first.yaml"] -->|"kxm init"| B[Validated]
+  B -->|"kxm trust diff"| C[Expansion listed]
+  C -->|"you review and commit"| D[Trusted]
+  D -->|"kxm run"| E[Run created]
+  E -->|"kxm runs drive --simulated"| F[Run completed]
+  F -->|"kxm runs status"| G[Receipt verified]
+```
+
+## 1. Add a workflow from a template
+
+From the repository root:
+
+```bash
+kxm workflow add first --template spec-and-plan
+```
+
+Expected output:
+
+```text
+Added workflow 'first' to local (<repo-root>/.kxm/workflows/first.yaml)
+```
+
+The file name is the workflow ID, so this workflow is `first`. The `spec-and-plan` template writes this file, `.kxm/workflows/first.yaml`:
+
+```yaml
+schema: kxm.workflow.v1
+description: Plan a change, then review the plan. Both steps run as the
+  coordinator agent and only read the repository.
+coordinator: coordinator
+limits:
+  maxTransitions: 8
+steps:
+  - id: plan
+    kind: agent
+    agent: coordinator
+    maxAttempts: 3
+    repositories:
+      control: read
+    on:
+      passed: review-arch
+      failed:
+        target: $terminal
+        terminalStatus: failed
+  - id: review-arch
+    kind: agent
+    agent: coordinator
+    maxAttempts: 3
+    repositories:
+      control: read
+    on:
+      passed:
+        target: $terminal
+        terminalStatus: completed
+      failed:
+        target: plan
+        maxTransitions: 2
+```
+
+Each step's `on` map routes an outcome to the next step. A failed review sends the work back to `plan` at most twice:
+
+```mermaid
+flowchart LR
+  plan -->|passed| review[review-arch]
+  plan -->|failed| failed([failed])
+  review -->|passed| completed([completed])
+  review -->|failed, at most 2 times| plan
+```
+
+## 2. Validate the workflow
+
+```bash
+kxm init
+kxm workflow definitions
+```
+
+Expected output:
+
+```text
+validated KXM project at <repo-root>
+WORKFLOW DEFINITIONS:
+  default                  [local]          3 steps (roles: coordinator, implementer) Plan, implement, and verify a local change.
+  first                    [local]          2 steps (roles: coordinator) Plan a change, then review the plan. Both steps run as the coordinator agent and only read the repository.
+```
+
+If a file is invalid, `kxm init` exits 1 and prints one `<file>: <code>: <message>` line per problem.
+
+## 3. Review the change and commit it
+
+```bash
+kxm trust diff
+kxm trust check
+```
+
+Expected output of `kxm trust diff`:
+
+```text
+permission diff: sha256:<old-revision>… -> sha256:<new-revision>…
+EXPANSION  .kxm/workflows/first.yaml added (expansion)
+1 expansion(s) require explicit reviewed trust action
+```
+
+`kxm trust check` prints the same lines, adds `trust check failed: review every expansion above before merging`, and exits 1. A new workflow is an [expansion](../glossary.md#expansion) of what agents may do, so read it: which agents run each step, and what access each step has to each repository. When you agree with it, commit it yourself:
+
+```bash
+git add .kxm/workflows/first.yaml
+git commit -m "Add the first workflow"
+kxm trust check
+```
+
+Expected output:
+
+```text
+permission diff: sha256:<revision>… -> sha256:<revision>…
+no authority-bearing or prose changes
+```
+
+> [!IMPORTANT]
+> Your reviewed commit is the approval. `kxm trust` has only `diff` and `check`, and no command approves an expansion for you.
+
+## 4. Plan the run
+
+```bash
+kxm run first "Plan a hello script" --dry-run
+```
+
+Expected output:
+
+```text
+run plan: workflow first at sha256:<revision>… (no run created)
+```
+
+The hash is the project's configuration revision, the same one `kxm trust diff` prints; a run pins it. Keep secrets out of run prompts.
+
+## 5. Create the run
+
+```bash
+kxm run first "Plan a hello script"
+```
+
+Expected output:
+
+```text
+run created: run_<id> (home rtm_<id>…, config sha256:<revision>…)
+drive it model-free: kxm runs drive run_<id> --simulated --wait (or cancel: kxm runs cancel run_<id>)
+```
+
+`kxm run` starts the Runtime supervisor if it is not running. Check the new run, using the run ID from the output:
+
+```bash
+kxm runs status run_<id>
+```
+
+Expected output:
+
+```text
+run run_<id>: created (workflow first, updated <timestamp>)
+```
+
+## 6. Drive the run
+
+```bash
+kxm runs drive run_<id> --simulated --wait
+```
+
+Expected output, one line:
+
+```text
+{"budget":null,"closedAt":"<timestamp>","driveId":"drv_<id>","homeRuntimeId":"rtm_<id>","lastSequence":41,"logHash":"sha256:[redacted]","mode":"simulated","openedAt":"<timestamp>","openedSequence":4,"producer":{"closed":false,"id":"driver-simulated"},"projectId":"prj_<id>","runId":"run_<id>","schema":"kxm.drive-receipt.v1","settlement":{"kind":"terminal","reason":"","status":"completed"}}
+```
+
+The simulated producer answers every agent step with `passed` and calls no model or harness, so the run moves from `plan` to `review-arch` to `completed`. `--wait` blocks until the [drive receipt](../glossary.md#drive-receipt) is recorded, for 60 seconds by default (`--timeout-ms`, up to 600000), and exits 0 only for a verified completed run.
+
+## 7. Check the result
+
+```bash
+kxm runs status run_<id>
+kxm runs receipt run_<id>
+kxm runs list
+```
+
+Expected output:
+
+```text
+run run_<id>: completed (workflow first, updated <timestamp>)
+drive drv_<id>: completed (receipt verified)
+{"kind":"terminal","reason":"","status":"completed"}
+run_<id>  completed  first  <timestamp>
+```
+
+`receipt verified` means the Runtime checked the drive receipt against the run's event log.
+
+## 8. Stop the Runtime supervisor
+
+```bash
+kxm runtime stop
+```
+
+Expected output:
+
+```text
+runtime supervisor rtm_<id> stopping
+```
+
+You have added, reviewed, run and verified a workflow.
+
+## Understand the workflow
+
+### What the file says
+
+The file is a `kxm.workflow.v1` definition. `coordinator` names the agent that owns the run, and `limits.maxTransitions` caps the step-to-step moves one run may make. Each step has an `id`, a `kind` (`agent` here), the `agent` that performs it, a `maxAttempts` limit, access per repository (`none`, `read` or `write`, at most the agent's own), and an `on` map that routes each outcome to the next step or to `$terminal` with a `terminalStatus`. A transition back to an earlier step needs its own `maxTransitions`.
+
+[Workflow files](../reference/config-reference.md#kxmworkflowsidyaml-kxmworkflowv1) lists every field, its limits and its error codes, and the [worked example](../reference/config-reference.md#worked-example-a-minimal-two-step-project) shows a workflow written by hand. The [Workflow definition reference](../reference/workflow-definitions.md) compares the two kinds of workflow KXM runs.
+
+### Other templates
+
+`kxm workflow add` has three built-in templates. Add `--dry-run` to see the path without writing the file.
+
+| Template | Steps | Use it for |
+|---|---|---|
+| `spec-and-plan` | `plan`, then `review-arch`, both run by the `coordinator` agent with read-only access | A first workflow: it writes nothing and runs no test command |
+| `implement-and-verify` | `implement`, then the `test` gate; a failing gate sends the work back to `implement` | Changes checked by your test command |
+| `dual-critic-review` | `implement`, two reviews, then the `test` gate | Changes that need two reviews before the tests |
+
+### Simulated and live drives
+
+`--simulated` replaces model calls, not your commands. Gate steps run their command from `.kxm/gates.yaml` in both modes, so a failing test fails the gate even in a simulated drive.
+
+| | Simulated (`--simulated`) | Live (no flag) |
+|---|---|---|
+| Agent steps | Report `passed` without calling a model | Call the agent's harness in a one-shot, read-only mode |
+| Gate steps | Run the gate's command | Run the gate's command |
+| Needs | Nothing | An admitted route for each agent's model (`kxm routes admit`) |
+| Non-gate steps with `write` access | Run, but change no files | Refused: the run is handed off. Gate steps are exempt |
+| Cost | None | Model usage on your accounts |
+
+> [!WARNING]
+> Without `--simulated`, `kxm runs drive` calls live harnesses. An agent whose model is not an admitted route fails with `producer_route_not_admitted`. Read [Harness routing](../reference/harness-routing.md) before your first live drive. A live drive hands off any agent, panel, approval or wait step with `write` access; gate steps are exempt, and the read-only `spec-and-plan` template avoids the refusal.
+
+### Why not the `default` workflow
+
+`kxm init` also writes a `default` workflow that plans, implements and runs the test gate. It declares `limits.maxAgentTimeMs`, an agent-time budget the Runtime cannot enforce yet. A drive of it is refused with HTTP 409 `run_handoff_required` (reason `limit_unsupported`), and the run stays `preparing` until you cancel it with `kxm runs cancel <run-id>`. [Steps the Runtime does not execute yet](../reference/config-reference.md#steps-the-runtime-does-not-execute-yet) lists every setting that causes a handoff.
+
+### Two kinds of runs
+
+`kxm run` and `kxm runs` manage Runtime runs like this one. A hub workflow run is different: a signed webhook or `kxm workflow start` creates it, and `kxm workflow list` and the `kxm_workflow_*` tools show it. `kxm workflow list` never shows a Runtime run. See [Run webhook workflows](../guides/webhook-workflows.md).
+
+## Troubleshooting
+
+| Message or symptom | Cause | Fix |
+|---|---|---|
+| `run_handoff_required` naming `limits.maxAgentTimeMs` | You drove the `default` workflow | Cancel the run and use `first` |
+| `trust check failed: review every expansion above before merging` | The workflow is not committed | Review it, then commit it |
+| `workflow <id> does not exist in this project` | The ID is not a local workflow | Use an ID from `kxm workflow definitions` marked `[local]` |
+| `gate_outcome_impossible` from `kxm init` | A gate step routes failure on `failed` | Declare `implementation-failure` on the gate step |
+| `--wait` exits 1 with settlement `failed` | A step failed, for example a gate that kept failing (`budget_edge`) | Read the reason with `kxm runs receipt run_<id>`, then fix the step or the command |
+| A run stays `preparing` or `running` | The run was handed off | Run `kxm runs cancel run_<id>` |
+
+## Next steps
+
+- Let Claude do it in your next project. With the [Claude Code plugin](quickstart-claude-code.md) installed, the `kxm-project-setup` skill runs `kxm init`, then `kxm workflow add first --template spec-and-plan`, the trust checks and a simulated drive. It stops twice for you to review and commit `.kxm/`: after `kxm init`, and after it adds the workflow. Claude never commits `.kxm/` itself, and tokens, starting the hub and the plugin's configuration stay with you.
+
+  In Claude Code:
+
+  ```text
+  Set up KXM in this repository and run a first workflow.
+  ```
+
+- Learn from runs: `kxm improve report` proposes improvement candidates from live runs. It leaves simulated attempts out, so for now it reports `0 record(s)`. See [Continuous improvement](../guides/continuous-improvement.md).
+- Give agents project context: Claude calls `kxm_context` with its role and task before planning. See [Context and memory](../guides/context-and-memory.md).
+- Watch agents and workflows live with `kxm dash`: [Monitor KXM](../operations/monitoring.md#watch-live-work-with-kxm-dash).
+- Write richer workflows: [Workflow catalog](../reference/workflow-catalog.md) and [Workflow definition reference](../reference/workflow-definitions.md).