CNL recipes — pick the shape, then adapt

Full runnable versions live in examples/. Two composition rules apply to all of them:

Wrap independent work in parallel — the engine fans out ALL subtasks at once over RPC; width is nearly free for I/O-bound work.
Prompt-chaining beats mega-prompts — pass {data:task_id} forward through small focused tasks instead of one giant prompt.

1. Single task (`examples/01-simple-search.yaml`)

The smallest valid workflow: one agent, one prompt. Use for smoke tests and one-shot calls.

tasks:
  - type: "task"
    id: "single_task"
    agent: brave-agent
    prompt: "{input}"

2. Parallel research + synthesis (`examples/02-parallel-research.yaml`)

The most common production pattern. Independent searches from different engines fan out at once; one LLM task synthesizes with {data:...} references.

tasks:
  - type: "parallel"
    id: "research_phase"
    subtasks: [ …brave-agent…, …tavily-agent…, …exa-agent… ]
  - type: "task"
    id: "synthesis"
    agent: llm-agent
    prompt: "Synthesize: {data:brave_search} {data:tavily_research} {data:exa_deep}"

3. Hierarchical branches (`examples/03-hierarchical.yaml`)

parallel → sequential → parallel nesting, unlimited depth. Use when branches have internal pipelines (e.g. search → per-branch analysis) that should still run side by side.

4. Consensus validation (`examples/04-validate-consensus.yaml`)

Produce something, then have several validators vote (aggregation: consensus | majority | all_pass | any_pass). Use for quality gates on generated content.

  - type: "validate"
    id: "quality_gate"
    validators:
      - { agent: llm-agent, validation_rule: "claims are sourced" }
      - { agent: llm-agent, validation_rule: "no speculation stated as fact" }
    aggregation: "majority"

5. Per-item batch (`examples/05-batch-items.yaml`)

Same pipeline for every item in a list (items: static or items_from: a prior task). {item} / {item.field} inside the pipeline; data chains automatically between the pipeline's tasks. Add track: true for resumable long lists.

6. Bounded harness mission (`examples/06-harness-mission.yaml`)

Open-ended, goal-driven work = ONE type: harness task with a mission (purpose, effort, max_turns, success_criteria) — not ten hand-planned small tasks. The loop runtime plans, uses tools, and self-checks inside the fence you declare. Reach for it when the steps can't be enumerated up front.

Choosing between `dynamic`, `batch`, and `harness`

Know the list already → batch.
An agent must generate the list first, then each item gets the same treatment → dynamic (generator + executors, cap with max).
The steps themselves are unknown and the agent must decide as it goes → harness.

Debate (no example file — shape only)

Two or more debaters argue positions, optional judge decides, rounds: 1-5. Use for decisions with genuine trade-offs.

  - type: "debate"
    id: "build_vs_buy"
    debaters:
      - { agent: llm-agent, position: "build in-house" }
      - { agent: llm-agent, position: "buy off the shelf" }
    judge: { agent: llm-agent }
    rounds: 2