CodewrightConsequence-aware terminal workflows

Workflow Recipes Specification v0.1

Draft

The authoring format for workflows: diagnostic decision trees that live under workflows/<category>/<slug>.yaml and are validated by packages/workflow-schema (pnpm workflows:validate runs in CI). It is a companion to the recipe spec, which remains the normative spec for single-command recipes; workflows reference recipes, never the other way around.

Status

The core system is live: the schema and validator, authored workflows, the website's workflow browser, the public API routes, MCP tools, and the CLI interpreter (see "What exists today" below). The format itself is still v0.1 — field names and semantics may change in a future version, so it carries a Draft badge.

Why workflow recipes are a different shape

A recipe in recipes/answers one question with one linear sequence of platform commands: inspect, act, verify. That model is a poor fit for diagnostics like "I can't push my branch," where the right next step depends on what actually happened. A workflow recipe is a decision tree whose nodes are either a reference to an existing single-command recipe by id, or an ad hoc diagnostic step — a read-only command used only to decide which branch to take next.

A separate workflows/ source tree

Workflows live in their own workflows/ directory with their own schema package (packages/workflow-schema, mirroring packages/recipe-schema's shape) rather than a new type field inside the existing recipe schema — the two have different blast radius, different validation rules, and independent lifecycles. The two trees share one lookup contract: a workflow node that references a recipe id must resolve against the compiled recipes/ index, and the validator rejects any workflow whose recipe_iddoesn't.

Schema shape

File location: workflows/<category>/<slug>.yaml, mirroring recipes' naming convention. The excerpt below is an abridged version of the authored workflows/git/cant-push-branch.yaml.

id: git.cant_push_branch # required, unique among workflows

version: 1 # required, integer

title: I can't push my branch # required, imperative/plain, <= 60 chars

category: git # required, same category list as recipes

tags: [git, push, diagnostics] # required

entry: check_push_error # required, id of the first node in `nodes`

nodes:

check_push_error:

kind: diagnostic # diagnostic | recipe_ref | outcome

run: git push

purpose: Attempt the push and capture how it fails

risk: read_only # diagnostic steps are read_only or low only

branches:

- when: { match: "has no upstream branch" }

goto: set_upstream

- when: { match: "\\[rejected\\].*non-fast-forward" }

goto: diverged_history

- when: { default: true } # exactly one default branch per node

goto: unknown_failure

set_upstream:

kind: recipe_ref

recipe_id: git.set_upstream_and_push # references recipes/git/*.yaml by id

branches:

- when: { outcome: success }

goto: resolved

- when: { default: true }

goto: unknown_failure

resolved:

kind: outcome

outcome: success

summary: The branch now has an upstream and the push succeeded.

Node kinds
  • diagnostic — an ad hoc read-only (or low-risk at most) command run purely to decide which branch to take. Anything that changes state belongs in a referenced recipe instead.
  • recipe_ref— points at an existing recipe by id; the workflow never duplicates that recipe's steps. Branching keys off outcome: success or outcome: failure.
  • outcome — a terminal node: success, needs_human, or needs_human_choice.
Branch rules
  • Every non-terminal node declares at least one branch and exactly one default: true branch, evaluated last.
  • Every goto must reference a node id that exists in the same workflow.
  • match conditions are anchored regular expressions evaluated against combined stdout+stderr, first match wins.
  • Every path from entry must reach an outcome node — unreachable or non-terminating nodes are rejected by the validator.

What exists today

  • Schema + validator — packages/workflow-schema validates every workflow (schema conformance, unique ids, branch-graph reachability and termination, recipe-id resolution) via pnpm workflows:validate, which runs in CI.
  • Authored workflows — the workflows/ tree ships diagnostic workflows across git, docker, network, and node, browsable on this site at /workflows.
  • Public API — GET /api/v1/workflows, /workflows/search, and /workflows/{id}, documented in the API reference.
  • MCP tools — search_workflows and get_workflow expose the library to MCP-compatible agents; see the MCP server docs.
  • CLI interpreter — codewright diagnose <workflow_id> drives a workflow from its entry node to a terminal outcome, running recipe_ref nodes through the same confirm/execute/verify path as codewright run; see the CLI docs.