@netnodeag/kraftwerk 0.2.0

package/README.md

@@ -0,0 +1,339 @@
+# kraftwerk
+
+Deterministic workflow-as-code over headless agent harnesses, in the spirit of
+[super-simple-software-factory](https://github.com/disler/super-simple-software-factory):
+**code owns the control flow, agents work inside bounded phases.**
+"Agent proposes, code disposes."
+
+No SDK dependency: every agent phase spawns one short-lived CLI process on the
+agent's **harness** and judges the result afterwards (typed JSON envelope +
+file gates). Failed checks are corrected in the same session, never by a cold
+restart. Every run leaves a `trace.jsonl` event log and ends with a
+time/token/cost summary table.
+
+## Consume
+
+Zero-setup consumer (YAML workflows only): a repo containing workflow
+folders under `workflows/` (or `src/workflows/`) IS a complete consumer —
+no package.json, no install:
+
+```bash
+npx @netnodeag/kraftwerk init      # scaffold kraftwerk.yml + workflows/ + example
+npx @netnodeag/kraftwerk run hello "Was ist kraftwerk?"
+```
+
+For a local checkout / programmatic consumer (TS workflows, custom gates,
+approval loops), add the dependency (the `kraftwerk` alias keeps imports
+short):
+
+```jsonc
+// package.json of your workflow project
+"dependencies": { "kraftwerk": "file:../kraftwerk" }   // or: "npm:@netnodeag/kraftwerk"
+```
+
+```ts
+import { defineAgent, Run, runCli, fileNonEmpty, envelopeContract } from "kraftwerk";
+```
+
+## CLI — kraftwerk
+
+Ships with the package (`npx @netnodeag/kraftwerk …` anywhere, `npm link` in
+the checkout for a global `kraftwerk`). Workflows are auto-discovered under
+`src/workflows/` (or `workflows/`): every folder with a `workflow.yml` and
+every top-level `.yml` file. Every command works from any subdirectory —
+the CLI walks up to the project root (marked by `kraftwerk.yml`, a
+workflows root, or `.git`).
+
+```bash
+kraftwerk init                          # make this repo a consumer: kraftwerk.yml, workflows/, example
+kraftwerk list                          # table: workflows, steps, agents (with harness/model); --json
+kraftwerk run tagline "https://..."     # run; --yes, --verbose
+kraftwerk run                           # interactive: pick workflow, type the request
+kraftwerk runs                          # past runs from output/*/trace.jsonl; runs show <id> for detail
+kraftwerk doctor                        # preflight: harness CLIs, docker, workflows, declared env vars
+kraftwerk validate                      # all discovered — schema + semantics + files, exit 1 on failure
+kraftwerk validate src/workflows/pitch  # specific paths
+kraftwerk create "was der Workflow tun soll"   # for LLM agents: prints a build brief
+kraftwerk runner build                  # build the Docker sandbox image (once)
+kraftwerk run --sandbox website-check "https://..."   # isolated container per run; --ssh forwards the agent
+kraftwerk runner ps / stop <run-id>     # see / stop running sandbox containers
+```
+
+### Project config — kraftwerk.yml
+
+Optional, at the project root (also the root marker for the walk-up); all
+fields optional: `workflows:` (workflows root) and `output:` (run-artifact
+directory, default `output/`).
+
+### Triggering from CI / cron / webhooks
+
+`run --json` is the machine mode: non-interactive, one JSON result object
+on stdout (`ok`, `runDir`, per-phase stats, totals), all narration on
+stderr. `KRAFTWERK_YES=1` equals `--yes`, `--quiet` silences narration.
+Exit codes: 0 ok, 2 usage/config error (unknown workflow, missing env),
+3 run failed (gate/blocked/harness), 1 unexpected.
+
+```bash
+KRAFTWERK_YES=1 npx @netnodeag/kraftwerk run tagline "https://..." --json > result.json
+```
+
+Workflows declare the env vars they need via top-level `requires:
+[MATOMO_TOKEN, ...]` — checked before anything spawns, listed by
+`kraftwerk list` and `kraftwerk doctor`.
+
+### Remote workflows — --from
+
+`list` and `run` accept `--from github:org/repo[@ref]` (or any git URL):
+the repo is shallow-cloned to `~/.cache/kraftwerk/remotes/` (refreshed per
+call, cached offline) and its workflows run locally — artifacts land in
+YOUR `output/`, not the cache. Share one workflow library across projects
+without vendoring:
+
+```bash
+npx @netnodeag/kraftwerk run --from github:NETNODEAG/workflows tagline "https://..."
+```
+
+Sandbox mode (`--sandbox`) runs the workflow in a `kraftwerk-runner`
+container (see `runner/Dockerfile`): workflow folder mounted read-only,
+the run directory bind-mounted straight into the host `output/` — trace
+and artifacts appear live, no copy-back. Env vars come from
+`<project>/runner.env` (plus `ANTHROPIC_API_KEY`/`OPENAI_API_KEY`
+pass-through); `--run-id` pins the run folder name for external triggers
+(the inspector uses this). `runner.json` in the run dir records
+container, exit code, and timing.
+
+`run` prompts for whatever is missing (workflow picker, request input);
+invalid workflows show up red in `list` with their validation error
+instead of breaking the listing. `create` is meant to be run BY an LLM
+agent (Claude Code, Codex): it prints a self-contained brief — schema
+example, gates, harness rules, verify ladder — that the agent follows to
+author the workflow folder and validate/smoke it with this CLI.
+
+## The agent — four axes
+
+```ts
+export const desloper = defineAgent({
+  id: "desloper",
+  name: "Lektorat",
+  harness: "codex",                 // WHERE it runs: claude (default) | codex | pi
+  model: "gpt-5.6-sol",             // WHAT thinks, in the harness's naming
+  effort: "high",                   // optional: low | medium | high | xhigh | max
+  tools: ["Read", "Write", "Edit"], // governance: capability boundary
+  persona: `Du bist Lektor:in ...`, // WHO: the system prompt
+  clis: {                           // optional: CLI grants — the hint is injected
+    git: "Versionierung; nach jedem Schritt committen", // into the persona ONCE
+  },
+  mcp: {                            // optional: MCP servers (governance, like tools)
+    calculator: { command: "node", args: ["/path/to/multiply-server.ts"] },
+  },
+});
+```
+
+The task arrives per phase, so one agent can serve several phases. Phases on
+the same harness share one resumed session (an agent sees the conversation so
+far but always speaks with its own persona); phases on different harnesses
+share state through the run files only.
+
+## Primitives
+
+| Primitive | What it does |
+| --------- | ------------ |
+| `defineAgent` ([src/agent.ts](src/agent.ts)) | persona + model/effort + tools + harness |
+| `Run.agentPhase({name, agent, prompt, gates})` ([src/run.ts](src/run.ts)) | spawn → parse envelope → run gates → correct in-session (bounded by `maxGateRetries`) |
+| `Run.codePhase(name, fn)` | deterministic step, timed and traced |
+| Gates ([src/gates.ts](src/gates.ts)) | post-execution file checks: `fileNonEmpty`, `slotsFilled`, `containsText` — or your own `Gate` |
+| Envelope ([src/envelope.ts](src/envelope.ts)) | every phase prompt ends with `envelopeContract(phase)`; `parseEnvelope` enforces it |
+| Stats ([src/stats.ts](src/stats.ts)) | per-phase attempts/time/tokens/cost, `run.printSummary()` renders the table |
+| `runCli(workflows)` ([src/cli.ts](src/cli.ts)) | registry CLI: `npm start -- <name> [--yes] [--verbose] "<request>"` |
+| `trace.jsonl` | every event: phase start/end, tool calls, envelopes, gate results, stats |
+
+## Harnesses
+
+One adapter per runtime ([src/harnesses/](src/harnesses)), all speaking the
+same interface ([src/harness.ts](src/harness.ts)):
+
+| | claude (default) | codex | pi |
+| --- | --- | --- | --- |
+| Process | `claude -p --output-format stream-json` | `codex exec --json` | `pi -p --mode json` |
+| Resume | `--resume <id>` | `exec resume <thread-id>` | `--session-id <id>` (create-or-continue) |
+| Auth | Claude Code login | ChatGPT login | Claude/ChatGPT OAuth **or** vendor API keys |
+| Models | Claude ids | GPT ids | `provider/id`, e.g. `deepseek/deepseek-chat`, `openrouter/...` |
+| Hermetic | `--setting-sources ""` | `--ignore-user-config` | `--no-context-files` |
+| MCP | `--mcp-config` + `--strict-mcp-config`, allowlist `mcp__<name>` | `-c mcp_servers.*` + `--approve-for-me` (headless approvals) | not supported (own extension system) |
+| CLIs | scoped allowlist `Bash(<name>:*)` | sandbox runs them anyway (hint only) | plain `bash` tool (no scoping) |
+| Quirks | — | no system-prompt flag (persona prepended to prompt); governance = workspace-write sandbox, not per-tool | `effort` maps 1:1 to `--thinking`; tool names lowercased |
+
+Prerequisites: **claude** — Claude Code installed + logged in. **codex** —
+`brew install --cask codex` + `codex login`. **pi** — `npm install -g
+@earendil-works/pi-coding-agent`; Anthropic models reuse the Claude
+subscription OAuth, other vendors need their key in the env (check with
+`pi auth check --provider deepseek`).
+
+## YAML workflows
+
+Linear workflows can be pure config — GitHub-Actions-flavored (`steps`,
+`runs-on`, `${{ request }}` / `${{ agent }}`). The canonical form is a
+**folder**: `workflow.yml` holds agents + steps, long prompts live as files
+next to it. Loaded with `loadWorkflow(path)` and registered like any other
+workflow:
+
+```
+src/workflows/tagline/
+  workflow.yml            # agents inline + steps
+  prompts/
+    analysieren.md        # referenced from a step, may use ${{ request }}
+    texten.md
+```
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json
+name: tagline
+description: "Tagline Generator (YAML)"
+workspace: |
+  Dateien: brand.md, tagline.md
+agents:
+  analyst:
+    runs-on: claude              # claude (default) | codex | pi
+    model: haiku                 # effort: low..max optional
+    tools: [Read, Write, Edit, WebFetch]
+    persona: |
+      Du analysierst Marken ...
+steps:
+  - name: analysieren
+    agent: analyst
+    prompt: prompts/analysieren.md   # single-line value = file in the folder
+    gates:
+      - file_non_empty: brand.md
+      - contains: { file: brand.md, text: "## Tonalitaet", label: Tonalitaet }
+```
+
+Running it needs no code at all — `kraftwerk run tagline "..."` discovers
+the folder. Programmatic registration works too:
+
+```ts
+const tagline = await loadWorkflow(path.join(import.meta.dirname, "workflows/tagline"));
+runCli({ [tagline.name]: tagline });
+```
+
+Single-line `prompt:`/`persona:`/`workspace:` values are file references
+inside the folder; multiline values stay inline (a plain single `.yml` file
+with everything inline works too). `${{ agent }}` interpolates the step's
+agent id — three jury steps can share one `prompts/assess.md` that writes
+`verdict-${{ agent }}.md` (see the pitch workflow). The engine appends the
+envelope contract to every step prompt itself.
+
+**Validation**: [`schema/workflow.schema.json`](schema/workflow.schema.json)
+(strict — unknown keys are errors, editors autocomplete via the
+`# yaml-language-server: $schema=…` line) plus semantic checks (agent
+references, duplicate steps, variables, referenced files):
+
+```bash
+kraftwerk validate                             # all discovered workflows
+kraftwerk validate src/workflows/tagline       # specific paths
+npm start -- validate <path>                   # runCli consumers (TS registry)
+```
+
+Gates: `file_non_empty: <file>`, `slots_filled: <file>`,
+`contains: {file, text, label?}`. Living examples:
+[`../agent-playground/src/workflows/tagline/`](../agent-playground/src/workflows/tagline/)
+and [`../agent-playground/src/workflows/pitch/`](../agent-playground/src/workflows/pitch/).
+v1 is deliberately linear — approval loops, AGENTS.md-style context files
+and skills stay on the roadmap; anything non-linear is a TS workflow.
+
+### MCP servers alongside the workflow
+
+A workflow folder can carry its own MCP servers; agents opt in by name
+(governance, like `tools`). Relative files resolve inside the folder,
+absolute paths and `url:` entries hook up external/remote servers:
+
+```yaml
+mcp:
+  calculator:
+    command: node                    # node >= 24 runs TypeScript directly
+    args: [mcp/multiply-server.ts]   # file inside the workflow folder
+  linear:
+    url: https://mcp.linear.app/mcp  # remote streamable HTTP
+agents:
+  rechner:
+    model: sonnet
+    tools: [Read, Write]
+    mcp: [calculator]                # this agent may use these servers
+```
+
+The stdio server is any MCP server (e.g. `@modelcontextprotocol/sdk` +
+`server.tool(...)` + `StdioServerTransport`, its deps in the consumer's
+`package.json`). On claude the servers are passed hermetically
+(`--strict-mcp-config`) and the allowlist gains `mcp__<name>`; on codex
+they become `-c mcp_servers.*` overrides and the phase runs with
+`--approve-for-me` so headless MCP calls get approved; `runs-on: pi` +
+`mcp` is rejected at validation time. Living example:
+[`../agent-playground/src/workflows/rechner/`](../agent-playground/src/workflows/rechner/).
+
+### CLI grants
+
+For existing command-line tools an MCP server is overkill — declare them
+once and grant per agent, so no step prompt has to repeat which CLIs
+exist or how to call them:
+
+```yaml
+clis:                      # command prefix -> one-line usage hint
+  my: "CLI fuer my.netnode.ch. Immer --json und -w <workspace-id> verwenden."
+  git: ""                  # empty hint = name only
+agents:
+  reporter:
+    tools: [Read, Write]
+    clis: [my, git]        # this agent may call these via Bash
+```
+
+The hint is injected into the agent's persona ONCE (that's the point —
+step prompts stay clean). Per harness: **claude** additionally scopes the
+Bash allowlist to `Bash(<name>:*)` — the granted prefixes run headless
+without approval, everything else keeps claude's default judgment
+(read-only commands auto-approve, mutating ones are denied). **codex**
+needs nothing (the workspace-write sandbox runs commands anyway).
+**pi** has no per-command scoping — a grant enables the plain `bash`
+tool.
+
+## Used by
+
+- [`../agent-playground/`](../agent-playground/) — the in-repo consumer with
+  the YAML example workflows (`tagline`, `pitch`, `rechner` with its own
+  MCP server, `website-check` with script steps).
+- `nn-content-workflow-2` (in the local `langgraph/` experiments folder,
+  outside this repo) — the netnode.ch content board and Matomo report
+  generator; the full ADW pattern including the engineer approval gate and
+  revision loop.
+
+To scaffold a new workflow, use the repo-root skill `/new-workflow`.
+
+## Developer
+
+Source is TypeScript under `src/`; the published package ships compiled
+JavaScript + type declarations under `dist/` (built by `tsc -p
+tsconfig.build.json`). The bin shim `bin/kraftwerk.js` runs the TS source
+via `tsx` whenever `src/` is present (dev checkout, `npm link`) — edits
+are always live, a stale `dist/` can never shadow them. Published
+installs contain no `src/`, so they take the compiled `dist/` path.
+`KRAFTWERK_DIST=1 kraftwerk …` forces `dist/` from the checkout, e.g. to
+verify a fresh build.
+
+```bash
+npm run typecheck   # tsc --noEmit over src/
+npm run validate    # validate the example workflows
+npm run build       # clean + compile src/ -> dist/ (JS + .d.ts)
+npm link            # global `kraftwerk` command from this checkout (no build needed)
+```
+
+### Publishing
+
+`prepublishOnly` runs the build automatically, so publishing is just:
+
+```bash
+npm publish         # runs npm run build first via prepublishOnly
+```
+
+The tarball is whitelisted via `files`: `bin/`, `dist/`, `runner/`
+(Dockerfile for sandboxed runs), `schema/` (workflow JSON schema) — no
+`src/`, examples, or inspector. Check with `npm pack --dry-run` before a
+release. Runtime deps stay regular `dependencies`; `tsx` and `typescript`
+are dev-only, so consumers install neither.

package/bin/kraftwerk.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// kraftwerk bin shim. Dev checkouts (src/ present, e.g. via npm link) run
+// the TypeScript source through tsx so edits are always live — a stale
+// dist/ can never shadow them. Published installs ship no src/, so they
+// take the compiled dist/ path. KRAFTWERK_DIST=1 forces dist/ (e.g. to
+// verify a build from the checkout).
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const src = path.join(here, "../src/cli/kraftwerk.ts");
+const dist = path.join(here, "../dist/cli/kraftwerk.js");
+
+if (existsSync(src) && process.env.KRAFTWERK_DIST !== "1") {
+  const { register } = await import("tsx/esm/api");
+  register();
+  await import(src);
+} else if (existsSync(dist)) {
+  await import(dist);
+} else {
+  console.error("kraftwerk: neither src/ nor dist/ found — broken install?");
+  process.exit(1);
+}

package/dist/agent.d.ts

@@ -0,0 +1,49 @@
+import type { HarnessId, McpServerConfig } from "./harness.js";
+/**
+ * An agent is exactly four things:
+ *
+ *   persona     — WHO it is: the system prompt (role, voice, editorial rules)
+ *   model       — WHAT thinks: the model id + optional effort level
+ *   governance  — WHAT it may do: the allowed tools (capability boundary)
+ *   harness     — WHERE it runs: the agent runtime (claude -p, codex exec, pi)
+ *
+ * Nothing else. The task an agent works on comes from the phase prompt at
+ * call time (`run.agentPhase({ agent, prompt, gates })`), so one agent can
+ * serve several phases. How an agent is executed (headless process, session
+ * resume, envelope, gates) is entirely the framework's business — see
+ * harness.ts, harnesses/, and run.ts.
+ */
+export type EffortLevel = "low" | "medium" | "high" | "xhigh" | "max";
+export interface AgentDefinition {
+    /** Stable id, used in logs and trace.jsonl. */
+    id: string;
+    /** Human-readable role name, shown when the phase starts. */
+    name: string;
+    /** Model id in the harness's naming, e.g. "claude-opus-5" or "gpt-5.6-sol". */
+    model: string;
+    /** Reasoning effort for this agent. Omit for the model's default. */
+    effort?: EffortLevel;
+    /** System prompt: role, voice, and the rules this agent always applies. */
+    persona: string;
+    /** Governance: the only tools this agent is allowed to use. */
+    tools: string[];
+    /**
+     * CLIs this agent may call via Bash: command prefix -> one-line usage
+     * hint. The hints are injected into the persona ONCE, so step prompts
+     * never repeat them. On claude each name additionally becomes a scoped
+     * `Bash(<name>:*)` allowlist entry; codex runs commands in its sandbox
+     * anyway (hint only); pi has no per-command scoping and gets the plain
+     * bash tool instead.
+     */
+    clis?: Record<string, string>;
+    /**
+     * MCP servers this agent may use, keyed by server name (part of the
+     * governance boundary, like tools). Stdio servers can live right next to
+     * the workflow; `url` entries point at remote streamable-HTTP servers.
+     * Supported on the claude and codex harnesses, not on pi.
+     */
+    mcp?: Record<string, McpServerConfig>;
+    /** Which runtime executes this agent. Default: "claude". */
+    harness?: HarnessId;
+}
+export declare function defineAgent(agent: AgentDefinition): AgentDefinition;

package/dist/agent.js

@@ -0,0 +1,3 @@
+export function defineAgent(agent) {
+    return agent;
+}

package/dist/cli/create-brief.d.ts

@@ -0,0 +1,4 @@
+export declare function renderCreateBrief({ spec, workflowsRoot, }: {
+    spec: string;
+    workflowsRoot?: string;
+}): string;

package/dist/cli/create-brief.js

@@ -0,0 +1,146 @@
+/**
+ * `kraftwerk create "<spec>"` — printed for an LLM agent (Claude Code,
+ * Codex, ...), veloop-style: the command does not scaffold anything itself,
+ * it emits a self-contained brief the agent follows end to end with the
+ * kraftwerk CLI. Everything the agent needs (schema essentials, an example
+ * workflow.yml, gates, variables, harness rules, verify ladder) is inline —
+ * no other files required reading.
+ */
+import { SCHEMA_URL } from "../config.js";
+export function renderCreateBrief({ spec, workflowsRoot, }) {
+    const root = workflowsRoot ?? "src/workflows";
+    return `# Create a new kraftwerk workflow
+
+**Requirements:** ${spec}
+
+You are scaffolding a YAML workflow for kraftwerk. A workflow is a
+FOLDER \`${root}/<name>/\` containing \`workflow.yml\` (agents + gated steps)
+and \`prompts/*.md\`. Deterministic code owns the control flow; agents work
+inside bounded steps and are judged afterwards (envelope + file gates, with
+in-session correction). The kraftwerk CLI discovers the folder automatically —
+nothing to register.
+
+## Steps
+
+1. Orient: run \`kraftwerk list\` to see existing workflows (avoid name
+   collisions, match local conventions).${workflowsRoot ? "" : ` No workflows root exists yet —
+   create \`src/workflows/\` first.`}
+2. Design from the requirements — keep it minimal and concrete:
+   - **Steps** in order, two kinds: agent steps (\`agent\` + \`prompt\`) and
+     deterministic script steps (\`run\`: a bash script — use these whenever
+     no judgment is needed: fetching, measuring, converting). Only linear
+     sequences fit YAML; if the requirements demand loops or human approval
+     gates, STOP and tell the user this needs a TypeScript workflow instead.
+   - **Agents**: one per role — persona (WHO), model + optional effort (WHAT
+     thinks), tools (governance), \`runs-on\` (WHERE: claude | codex | pi).
+   - **Gates** per step: what file evidence proves the step worked?
+3. Write \`${root}/<name>/workflow.yml\`. Complete example of every feature:
+
+   \`\`\`yaml
+   # yaml-language-server: $schema=${SCHEMA_URL}
+   name: tagline                # CLI name: kraftwerk run tagline "..."
+   description: "One-liner shown in kraftwerk list"
+   requires: [BRAND_API_TOKEN]  # optional: env vars checked before the run starts
+   workspace: |
+     Files: brand.md (analysis), tagline.md (result).
+   mcp:                         # optional: MCP servers stored with the workflow
+     calculator:
+       command: node            # stdio server; relative files resolve in the folder
+       args: [mcp/multiply-server.ts]
+     linear:
+       url: https://mcp.linear.app/mcp   # remote streamable HTTP
+   clis:                        # optional: CLI grants, command prefix -> usage hint
+     git: "Version control: commit after every step"
+   agents:
+     analyst:
+       name: Brand analyst      # display name (optional)
+       model: haiku             # model id in the harness's naming
+       tools: [Read, Write, Edit, WebFetch]
+       persona: |
+         You analyze brands based on their website ...
+     writer:
+       runs-on: codex           # optional: claude (default) | codex | pi
+       model: gpt-5.6-sol
+       effort: high             # optional: low | medium | high | xhigh | max
+       tools: [Read, Write, Edit]
+       clis: [git]              # optional: CLI grant — hint lands in the persona
+       mcp: [calculator]        # optional: MCP grant (governance, like tools)
+       persona: prompts/writer-persona.md   # single line = file in this folder
+   steps:
+     - name: measure                        # deterministic step: bash, no agent
+       run: scripts/measure.sh              # single line = file; or inline multiline bash
+       gates:
+         - file_non_empty: metrics.md
+     - name: analyze
+       agent: analyst
+       prompt: prompts/analyze.md           # or inline multiline text
+       gates:
+         - file_non_empty: brand.md
+         - contains: { file: brand.md, text: "## Tone of voice", label: tone }
+     - name: write
+       agent: writer
+       prompt: prompts/write.md
+       gates:
+         - file_non_empty: tagline.md
+         - slots_filled: tagline.md         # no unfilled {{...}} slots
+   \`\`\`
+
+4. Write the \`prompts/*.md\` files. Rules:
+   - Available variables: \`\${{ request }}\` (the CLI argument) and
+     \`\${{ agent }}\` (the step's agent id — lets several steps share one
+     prompt file, e.g. writing \`verdict-\${{ agent }}.md\`).
+   - Tell the agent exactly which files to read and write (relative names —
+     they land in the run directory). The \`workspace:\` text must describe
+     the file layout, because steps on different harnesses share state only
+     through these files.
+   - Do NOT mention envelopes — the engine appends that contract itself.
+   Script steps (\`run:\`) execute with bash in the run directory: env vars
+   \`REQUEST\`, \`RUN_DIR\`, \`PHASE\` are set and \`\${{ request }}\` is
+   interpolated. Non-zero exit fails the run; gates apply but there is no
+   correction loop (fix the script). A script MAY end its stdout with the
+   same fenced \`\`\`json envelope agents emit (\`{"phase": "$PHASE",
+   "status": "ok", "artifacts": [...], "summary": "..."}\`); otherwise the
+   engine synthesizes one. Keep scripts in \`scripts/*.sh\` inside the folder.
+5. MCP servers (only if the requirements need custom tools): store the
+   server next to the workflow (e.g. \`mcp/multiply-server.ts\` using
+   \`@modelcontextprotocol/sdk\` — its deps must be in the consumer's
+   package.json; \`command: node\` runs TypeScript directly on node >= 24),
+   declare it under top-level \`mcp:\`, grant it per agent via
+   \`mcp: [name]\`. External servers: absolute \`command\` path or
+   \`url:\` for remote streamable HTTP. Works on claude and codex;
+   \`runs-on: pi\` rejects MCP at validation time.
+   For EXISTING command-line tools use \`clis:\` instead of an MCP
+   server: top-level map command prefix -> one-line usage hint, granted
+   per agent via \`clis: [name]\`. The hint is injected into the persona
+   once — NEVER repeat CLI usage in step prompts. claude scopes its Bash
+   allowlist to \`Bash(<name>:*)\`; codex runs commands in its sandbox
+   anyway; pi gets the plain bash tool.
+6. Harness rules:
+   - **claude** (default): any Claude model id; needs only the local login.
+   - **codex**: ChatGPT login; models from the codex line (e.g.
+     \`gpt-5.6-sol\`); a WebFetch/WebSearch grant in \`tools\` enables sandbox
+     network access; persona is prepended to the prompt (no system-prompt flag).
+   - **pi**: \`provider/id\` models (\`anthropic/...\` uses the Claude login;
+     \`deepseek/...\`, \`openrouter/...\` need the vendor key — check with
+     \`pi auth check --provider <p>\`).
+   - Expensive models only where judgment matters; cheap models elsewhere.
+7. Validate: \`kraftwerk validate ${root}/<name>\` — fix until it passes
+   (strict schema: unknown keys are errors; semantic checks cover agent
+   references, variables, referenced files).
+8. Smoke: \`kraftwerk run <name> "<realistic request>"\` with all agents on a
+   cheap model first (\`haiku\`, or codex which is free on subscription) —
+   check every gate passes and the summary table renders. Then set the
+   intended models.
+9. Confirm to the user: workflow name, steps, roster (model/harness per
+   agent), gates, and the artifact files a run produces.
+
+## Notes
+
+- Keep it minimal — only the steps/agents/gates the requirements actually
+  call for. One agent serving several steps is normal (same persona, new
+  task); several agents sharing one prompt file via \`\${{ agent }}\` too.
+- Gates verify claims post-execution, never predictions. Prefer several
+  small gates with precise failure texts (they drive the correction loop).
+- If anything essential is unclear (target audience, output files, model
+  budget), ask the user before writing files.`;
+}

package/dist/cli/doctor.d.ts

@@ -0,0 +1 @@
+export declare function runDoctor(cwd: string): Promise<void>;

package/dist/cli/doctor.js

@@ -0,0 +1,87 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import chalk from "chalk";
+import { resolveProject } from "../config.js";
+import { discoverWorkflows } from "../discover.js";
+import { missingEnv } from "../yaml.js";
+const ICONS = {
+    ok: chalk.green("✔"),
+    warn: chalk.yellow("⚠"),
+    fail: chalk.red("✖"),
+    info: chalk.dim("•"),
+};
+function report(level, label, detail) {
+    console.log(`${ICONS[level]} ${label}${detail ? chalk.dim(` — ${detail}`) : ""}`);
+}
+function cliVersion(command) {
+    const r = spawnSync(command, ["--version"], { encoding: "utf8", timeout: 10_000 });
+    if (r.status !== 0)
+        return undefined;
+    return (r.stdout || r.stderr).trim().split("\n")[0];
+}
+export async function runDoctor(cwd) {
+    let failures = 0;
+    // Runtime.
+    const [major] = process.versions.node.split(".").map(Number);
+    if (major >= 20)
+        report("ok", `node ${process.versions.node}`);
+    else {
+        report("fail", `node ${process.versions.node}`, "kraftwerk needs node >= 20");
+        failures++;
+    }
+    // Project.
+    const project = await resolveProject(cwd);
+    report("info", `Project root: ${project.root}`, project.configPath ? path.basename(project.configPath) : "no kraftwerk.yml (fallback: workflows folder or .git)");
+    const found = project.workflowsRoot ? await discoverWorkflows(cwd) : [];
+    if (!project.workflowsRoot) {
+        report("warn", "no workflows root", "expected src/workflows/ or workflows/ — `kraftwerk init` scaffolds one");
+    }
+    else {
+        const valid = found.filter((e) => e.workflow);
+        const broken = found.filter((e) => !e.workflow);
+        report(broken.length ? "fail" : "ok", `${valid.length} workflow(s) valid, ${broken.length} broken`, path.relative(cwd, project.workflowsRoot) || ".");
+        for (const b of broken) {
+            report("fail", path.basename(b.path), b.error?.split("\n")[0]);
+            failures++;
+        }
+    }
+    // Harnesses: hard requirement only if a discovered workflow runs on them.
+    const needed = new Set();
+    for (const e of found) {
+        for (const a of e.workflow?.meta.agents ?? [])
+            needed.add(a.harness ?? "claude");
+    }
+    for (const harness of ["claude", "codex", "pi"]) {
+        const version = cliVersion(harness);
+        const isNeeded = needed.has(harness);
+        if (version) {
+            report("ok", `${harness} CLI`, version);
+        }
+        else if (isNeeded) {
+            report("fail", `${harness} CLI missing`, "needed by a discovered workflow");
+            failures++;
+        }
+        else {
+            report("info", `${harness} CLI not installed`, "no discovered workflow needs it");
+        }
+    }
+    // Docker (only needed for --sandbox).
+    const docker = spawnSync("docker", ["info"], { stdio: "ignore", timeout: 15_000 });
+    report(docker.status === 0 ? "ok" : "info", docker.status === 0 ? "docker reachable" : "docker not reachable", docker.status === 0 ? undefined : "only needed for --sandbox");
+    // Declared env vars.
+    for (const e of found) {
+        const requires = e.workflow?.meta.requires ?? [];
+        if (requires.length === 0)
+            continue;
+        const missing = missingEnv(requires);
+        if (missing.length === 0)
+            report("ok", `${e.workflow.name}: requires satisfied`, requires.join(", "));
+        else
+            report("warn", `${e.workflow.name}: env missing`, missing.join(", "));
+    }
+    if (failures > 0) {
+        console.log(chalk.red(`\n${failures} problem(s) found.`));
+        process.exit(1);
+    }
+    console.log(chalk.green("\nAll set."));
+}

package/dist/cli/init.d.ts

@@ -0,0 +1 @@
+export declare function runInit(cwd: string): Promise<void>;