Generate a workflow with the CLI

Use orchard generate when an agent or human should create and save a workflow artifact from a repo-local command.

Setup

pnpm exec orchard init
pnpm exec orchard doctor --json

orchard doctor --json is the machine-readable readiness check for agents. It reports tooling and repo config readiness. There is no database, schema, or queue to provision — the in-process runtime needs none of that.

Generate and preview

pnpm exec orchard generate \
  --prompt "Create a PR summary workflow" \
  --artifact-name pr-summary \
  --json

pnpm exec orchard preview --uuid <uuid-from-generate-json> --json

orchard generate starts the built-in generate-workflow on the same in-process run path as orchard run. It generates a validated draft with Cursor (composer-2.5) and runs up to 3 revise/fix turns on validation failures. Prefer small, step-memoized units and a decomposed verify stage before the final output when the work is inherently multi-item (never one mega verify harnessCall with all findings). Pass optional --harness (cursor, codex, or claude) / --model to override step defaults for the whole run.

Before publication, an interactive terminal presents a compact workflow wireframe, its summary, and validation status. Choose approve to publish, or provide feedback to create a revised draft. Draft revisions and their feedback stay in the run's memory so the generator can revise the actual previous source. Ctrl-C exits the process: there is no orchard resume command, so an unapproved draft and its feedback history are lost with the process.

Only approval saves the canonical artifact and registers it in the manifest, including its sourceHash and workflow shape. orchard preview returns saved artifact metadata only when the manifest still matches the saved source.

For deliberate unattended use, pass --skip-approval; it publishes the first validated draft without a human gate. Do not use this flag when review is required. Without it, a non-interactive invocation cannot resolve the approval gate — there is no external channel to deliver a decision to that process — so the run stays parked until you stop it.

Generated artifact best practices

orchard generate rejects source that does not match Orchard's generated workflow contract before it spends time on a TypeScript dry run. When writing or repairing an artifact by hand, use the same shape:

• Export exactly registerWorkflow({ app, harness, cwd, queues }) as a named function and default-export that same binding. Return the WorkflowRef from workflow(...) directly; do not wrap it in { workflow, start }, adapter objects, or harness-specific entrypoints.
• Import Orchard primitives by their canonical names from @snevins/orchard-core (task, workflow, Steps, harnessCall, loopUntil, spawnAndAwaitTask, runReadOnlyParallelTasks). Do not alias them in generated artifacts.
• Pass queues to workflow({ queues, ... }). Register tasks referenced directly by Steps({ ... }) on queues.tasks. If a task waits on more child tasks, register those awaited children on `${queues.tasks}-workers` and pass run.queue to the helper that spawns them — static validation still enforces this queue shape even though the in-process runtime has no worker pool to protect. Do not derive any other queue names.
• Make every step id a stable literal. Inside loopUntil, use loopCtx.childStepName('<literal>') for spawnAndAwaitTask step names, and use iteration-scoped batch ids such as `research-round-${loopCtx.iteration}` for runReadOnlyParallelTasks.
• Keep all z.object(...) schemas .strict(), including nested object schemas used for harness outputs. Unknown keys should fail validation instead of being silently ignored.
• Use harnessCall/harnessCallWithTurn only inside task handlers, and pass a concrete Zod output schema. If the workflow needs local command output, run scoped node:child_process commands inside task handlers. Do not call harnesses, shell commands, network clients, or custom schedulers from top-level module code.
• For large structured prompt context, organize the data into row-like arrays and reference tables first, then encode those prompt blocks with @toon-format/toon. The harness response should still be JSON validated by Zod.

For copyable patterns, compare the examples in packages/examples/src: audit for bounded read-only fan-out, git-diff-fanout for deterministic diff grouping before read-only fan-out, review-revise-loop for loop-scoped child task ids, and question-research for TOON report handoff plus follow-up rounds.

Run

pnpm exec orchard run .orchard/workflows/pr-summary-<uuid>.ts \
  --harness codex \
  --model gpt-5.5 \
  --input-json '{"prompt":"Summarize this repo"}' \
  --json

orchard run prints the workflow's final state and result snapshot to stdout, and status lines to stderr as the run progresses. Nothing is persisted: once the process exits, that printed output is the only record of the run.