Recipes and task classes¶

A recipe is the reusable definition of how a class of work is done. It supplies the workflow, the verification posture and the artifacts a run must produce. You pick a recipe per run; the workflow inside it never changes per kickoff.

Three files, three jobs¶

Every directory under recipes/ contains the same trio:

recipes/code-fix/
  task_class.yaml        when this recipe applies
  workflow.yaml          nodes, lanes, gates, phases
  artifact_contract.yaml what a run must produce

They are separate on purpose: classification can be evaluated without loading a workflow, and the artifact contract can be checked without running one.

task_class.yaml — the match rule¶

name: code_fix
description: "Single-patch code change: bug fix, small feature, refactor of a single function"

artifact_contract_ref: artifact_contract.yaml
default_workflow: workflow.yaml

matches:
  keywords: [fix, bug, patch, update, refactor]
  path_globs: ["**/*"]
  regex: []

default_gates:
  - scope_gate
  - budget_gate
  - deployment_gate

risk_class: medium

matches decides whether the classifier may select this class. Keywords, path globs and regular expressions are scored together.
default_workflow and artifact_contract_ref bind the other two files.
default_gates apply unless the workflow declares its own gate list.
risk_class drives how much verification the run is expected to carry.

workflow.yaml — the graph¶

Nodes, their lanes, edges between them, phases, retries and gate declarations. The schema is in workflow.yaml; the contract it compiles to is in Architecture: artifact graph.

artifact_contract.yaml — the deliverable¶

Declares the ports a run must fill: which artifact, produced by which node, with what required fields. A run that finishes without filling a required port is not a success. See Artifact contract.

Choosing a recipe¶

Two ways to select one:

mini-ork run code-fix ./kickoff.md     # explicit
mini-ork run ./kickoff.md              # classified

Explicit selection is the right default while you are learning the system: it removes classification as a variable. Use classification once your kickoffs reliably describe their own work.

What ships¶

The catalogue is wide because recipes encode verification posture, not merely subject matter. Grouped by purpose:

Code delivery¶

Recipe	Use it for
`code-fix`	One patch: a bug fix, a small feature, a refactor of one function
`docs`	Documentation-only edits, verified by grep assertions and link integrity
`db-migration`	Schema migrations audited across integrity, rollback, perf, compatibility and edge cases
`refactor-audit`	Multi-lens audit of a codebase for scale, security, performance and shape
`framework-edit`	Verifier-gated edits to the mini-ork framework itself; produces a diff for review
`self-migrate`	Close one bash↔Python seam as a single verifier-gated unit

Multi-epic and long-horizon¶

Recipe	Use it for
`epic-runner`	Schedule waves of child runs from an epic dependency graph
`bdd-first-delivery`	Decompose into sub-epics, write specs first, implement in parallel
`spec-driven-delivery`	Deliver every feature in a directory of spec files, with a traceability ledger
`goal-loop`	A bounded, goal-agnostic loop: watch → hunt → fix → verify per wave
`recursive-validate-impl`	One feature with machine-checkable DoD probes and replanning
`doc-to-features-loop`	Extract features from a document and drive each through implementation

Audits and panels¶

Recipe	Use it for
`bug-audit-cmgk`, `bug-audit-fe-be`	Ranked findings from heterogeneous lenses; report-only
`audit-judge-panel`	Two-lane judge panel verifying an auditor's findings
`audit-judge-panel-3l`, `-4l`	Three- and four-family panels with a synthesizer
`schema-judge-panel`	Five-lens review of database or architecture plans
`ui-audit`	Accessibility, performance, visual consistency, interaction, edge cases
`silent-catch-audit`	JavaScript/TypeScript swallowed-exception audit
`registry-audit`	Row-by-row audit of a markdown feature registry
`session-task-judge`	Judge pending session tasks for impact vs staleness

Writing and research¶

Recipe	Use it for
`blog-post`	Five-lens collaborative drafting, one model family per lens
`blog-cohesion`	Polish an existing draft across five structural lenses
`chapter-review`, `chapter-validation-10lens`	Multi-axis review or ten-slice validation of long-form prose
`research-synthesis`	Four research lenses plus a synthesizer, with dissent preserved
`frontier-llm-research`	Evidence-led survey over a dated paper corpus
`rsi-technique-review`, `verification-technique-review`, `coord-technique-review`	Literature-driven planning for a specific engine subsystem
`author-style-imitation-review`	Distil and rank style-imitation techniques with citation grounding

Smoke tests and meta¶

Recipe	Use it for
`obs-smoke`	Exercise every observability emit point end to end
`orch-smoke`, `orch-smoke-default-on`	Prove the per-run orchestrator is engaged
`skill-smoke`	Prove a skill grant reaches one node and not another
`recipe-creator`	Author a complete new recipe from a natural-language epic
`recursive-self-improve`	Time-budgeted self-improvement with verifier-gated promotion
`harness-bridge`	Bridge a run to an external agent harness

The authoritative list is the directory itself:

ls recipes/

Inspecting a recipe¶

Static evaluation catches malformed definitions before a run spends anything:

mini-ork recipe-eval code-fix
mini-ork recipe-eval --json            # machine-readable

Every finding carries a Fix: hint. Typical findings: a node references an undefined lane, an artifact port has no producer, a gate name is not registered.

Validate a project against a specific recipe before running:

mini-ork validate ./kickoff.md --recipe code-fix
mini-ork validate --recipe code-fix --strict

validate also checks the environment the recipe needs — providers, vault entries, binaries. --strict turns warnings into a nonzero exit, which is what CI should use.

Writing your own¶

A minimal recipe needs the three files and, for a real run, a workflow whose nodes name lanes that exist in agents.yaml. Start from the closest shipped recipe and run mini-ork recipe-eval after every edit.

For a guided build, use the meta-recipe:

mini-ork run recipe-creator ./my-recipe-epic.md

The developer-facing contract is in Extending mini-ork.

Relationship to gates¶

A recipe does not decide whether a result is acceptable on its own — gates do. The recipe says which gates are required and what evidence counts. That split is why the same code-fix workflow can run with stricter gates without editing the nodes. See Verification and gates.