Recipe Drafter (describe a workflow, get a validated recipe)

What it is

Audience: AI agents (with or without repo access) and Omniscio users curious how the "Create from description" flow works.

Where to find it

This is the drafter behind the "Create from description" recipe flow, and it has no screen of its own: a caller — an agent, a script, or the recipe-creation UI — sends a description and gets a draft recipe back, along with its reasoning, warnings and any remaining validation errors.

How it behaves

What it does

You give Omniscio a natural-language description of an automation — "every Monday morning, check three repos for failing CI and DM me a digest" or "audit each prompt in audit-reports/refactor-prompts/ with a 4-stage pipeline" — and Omniscio returns a draft RecipeConfig plus its reasoning, warnings, and any remaining validation errors. The draft is NOT saved to disk; the caller decides whether to save it (via RECIPE_SAVE_CONFIG), edit it, or retry.

When the drafter refuses

• Chitchat / non-recipe requests ("what's the weather?", "1+1?")
• Requests that need capabilities Omniscio doesn't have (live web scraping, arbitrary code execution)

The output is { recipe: null, source: "refused", reasoning: "..." } — caller surfaces the reasoning.

Cost & rate behavior

• Each turn is one Sonnet Messages API call. Typical one-shot ≈ $0.05–0.15. Refinement loop ≈ $0.20–0.50.
• maxDrafterCostUsd halts the loop when crossed.
• The drafter does NOT cache; identical NL inputs produce a fresh call each time. (Caching is a future feature.)
• Auth: Messages API needs an API key. OAuth-only accounts get auto-fallback to the first API key account. No API key in the vault → handler returns an error envelope.

For agents

How it works

1. Drafter reads the bundled pattern library (audit-pipeline, fan-out-consolidate, red-team-gate, validate-then-act).
2. One Sonnet call. The system prompt has all four patterns inlined plus a brief recipe-schema cheat sheet.
3. The model returns one JSON object on the last line of its response: { source, patternId?, parameters?, recipe?, reasoning }.
4. Omniscio takes the JSON:
   • source: "pattern" → call instantiatePattern(patternId, parameters) to materialize the recipe.
   • source: "synthesized" → use the inline recipe directly.
   • source: "refused" → drafter declined (e.g. "what's the weather?"). Returns recipe: null.
5. The validators (runSemanticChecks + runWarningChecks) check the candidate.
6. If blocking errors AND remaining budget, the drafter sends a refinement message containing the previous draft + the errors and asks for a fix. Up to 3 refinement turns.
7. Omniscio returns the latest draft + cost + token totals.

IPC surface

Channel: recipe:create-from-nl

// Input
{
  "description": "audit each prompt in audit-reports/refactor-prompts/ with a 4-stage pipeline",
  "existingDraft": null,                     // optional — pass a recipe to enter edit mode
  "hints": {                                  // all optional
    "targetProjectId": "<uuid>",
    "expectedStepCount": 5,
    "preferredPatternId": "audit-pipeline",
    "suggestedBudget": { "costUsd": 25, "minutes": 240 }
  },
  "maxDrafterCostUsd": 1.0                    // optional — default $1.00
}

// Output (success envelope)
{
  "recipe": { /* RecipeConfig | null */ },
  "source": "pattern" | "synthesized" | "refused",
  "patternId": "audit-pipeline",
  "reasoning": "Matched audit-pipeline because the user described a 4-stage lane fan-out...",
  "warnings": [],                             // ValidationError[] — non-blocking
  "validationErrors": [],                     // ValidationError[] — blocking; if non-empty, recipe is best-effort
  "drafterCostUsd": 0.08,
  "drafterTokensUsed": 4200
}

Iteration mode

Pass the previous output's recipe as existingDraft and a change description:

{
  "description": "change maxConcurrent to 3 and add a $20 cost cap",
  "existingDraft": <previous recipe>
}

The drafter receives an edit-mode prompt: "Apply the user request to the existing draft. Keep unchanged fields intact."

Failure modes

• DRAFTER_OUTPUT_PARSE_FAILED — model returned text without a recoverable JSON object on the final line.
• PATTERN_NOT_FOUND — model picked a patternId that doesn't exist. Usually a hallucination on small models.
• SYNTHESIZED_RECIPE_MISSING — model said source: "synthesized" but didn't include a recipe field.
• PATTERN_INSTANTIATION_FAILED — model passed bad parameters (wrong type, missing required, out-of-range).
• STEP_CAP_EXCEEDED / SUBRECIPE_NOT_FOUND / PROJECT_NOT_FOUND / etc. — semantic validation errors. The drafter retries automatically; if the cap is hit before all errors clear, they surface in validationErrors.

Prompts and tools

System prompts live in Main only and are NEVER returned over IPC. The reasoning field is the model's explanation, not the prompt.

Tools given to the model: NONE — v1 is a single-shot JSON-out call. Tool-use (Anthropic tool calls for list_patterns, validate_recipe, etc.) is a v2 consideration.

Related

• Pattern library: use-recipes.md, docs/developing/RECIPE_AUTHORING_GUIDE.md
• Roadmap: 2026-04-22-recipe-robustness-roadmap.md Phase 3 item #12
• Design doc: 2026-04-22-recipe-nl-create-ipc-design.md