> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plungeai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# plungeai-workflows

> Build, validate, test, and save PlungeAI (Ocean Studio) workflows in CNL YAML.


Build, validate, test, and save PlungeAI (Ocean Studio) workflows in CNL YAML. Use when the user wants to create or edit a PlungeAI/Ocean workflow, orchestrate PlungeAI agents, write CNL YAML, run a multi-agent pipeline on PlungeAI, or turn research in this chat into a saved Studio workflow. Triggers: "PlungeAI workflow", "Ocean Studio workflow", "CNL", "build a workflow", "save this as a workflow", "plungeai agents".

[Download zip](https://skills.plungeai.com/plungeai-workflows.zip) · [View raw SKILL.md](https://skills.plungeai.com/plungeai-workflows/SKILL.md)

Author CNL workflow YAML for the PlungeAI platform, prove it works, and save it
so it appears in Ocean Studio and every connected app.

## Prerequisites (check first, once)

- Preferred: the `plungeai` MCP server is connected (tools named `plungeai_*`
  are available). Confirm identity with `plungeai_whoami`.
- Otherwise: you can still author correct YAML and hand the user a paste-ready
  block (see [`references/channels.md`](/skills/plungeai-workflows/references/channels), Channels 2-3).

## The loop

1. **Understand the goal.** One sentence: input → steps → deliverable. Ask only
   if the goal is genuinely ambiguous.
2. **Discover agents — never from memory.** `plungeai_list_agents
   {search: "<capability in plain words>"}` per capability. Take ids verbatim
   from results (kebab-case). Unknown or inactive ids are refused at execution.
   Fetch a full card with `{agent_id}` before using an unfamiliar agent — cards
   carry parameters and "Not for → use X instead" redirects.
3. **Author the YAML.** Load [`references/cnl-spec.md`](/skills/plungeai-workflows/references/cnl-spec) and pick a shape from
   [`references/recipes.md`](/skills/plungeai-workflows/references/recipes). Independent steps go in `parallel`; chained steps in
   `sequential` with `{data:task_id}`; goal-driven open-ended work is ONE
   `type: harness` task, not many small tasks. Long prompts use block scalars
   (`prompt: |`) — never hard-wrap a value.
4. **Test ad-hoc BEFORE saving.** `plungeai_execute_workflow {workflow_yaml,
   input}` (`mode: "async"` + `plungeai_get_workflow_status` for long runs).
   Read the actual output — does it satisfy the user's goal? Iterate the YAML,
   not the save.
5. **Save.** `plungeai_workflow {action: "create", name, yaml, description}`.
   The platform re-validates server-side; a refusal lists field errors — fix
   exactly those and retry. On success it syncs live to Studio and peer apps.
   Iterations on a saved workflow: `action: "update"` (plus `"save_version"`
   before big changes).
6. **Learn-back (offer it).** If real research happened in this chat, offer:
   `plungeai_learn {source: "<distilled findings>"}` to save it as a reusable
   platform skill that future runs can inject.

## Hard rules (the top causes of refused YAML)

- Agent ids ONLY from a live `plungeai_list_agents` search. `brave-agent`,
  never `brave-search`.
- These do NOT exist: `$variable`, `depends_on`, `outputs:`, `parallel: true`,
  `schedule:` (scheduling is configured in Studio, not YAML).
- `parallel` / `sequential` / `batch` / `dynamic` / `debate` / `validate`
  blocks never carry `agent:` — agents go on the inner tasks.
- `type: task` reads `prompt:` (or `query:`) — not input/instructions/message.
  `goal:` belongs to `type: harness` only.
- Every `id` unique; data flows automatically — never hand-wire results.
- Search agents (brave-agent, tavily-agent, …) take SEARCH TERMS — short
  queries, not instructions. Synthesis, analysis, and "based on the research
  above…" prompts belong on `llm-agent`.

## When something fails

- **create refused** → the message names field + problem; fix exactly that,
  retry once.
- **"agent not active/unknown"** → re-search the registry; the catalog is live.
- **execution succeeded but output is wrong** → improve prompts/structure and
  re-run ad-hoc; only save after the output is right.
- **no MCP tools available** → Channels 2-3 in [`references/channels.md`](/skills/plungeai-workflows/references/channels).

## References (load on demand)

- [`references/cnl-spec.md`](/skills/plungeai-workflows/references/cnl-spec) — full CNL v6 reference (all 10 task types, validation errors)
- [`references/recipes.md`](/skills/plungeai-workflows/references/recipes) — canonical patterns + when to use each
- [`references/channels.md`](/skills/plungeai-workflows/references/channels) — MCP (`https://mcp.plungeai.com/v1`) / Studio paste / raw HTTP API
- `examples/*.yaml` — six validated, runnable workflows

## More

- [`references/overview.md`](/skills/plungeai-workflows/references/overview) — the platform-level view: parallelism facts
  (measured, not guessed), placeholders and date tokens, execution/results/
  follow-up semantics, failure semantics.
- [`references/api.md`](/skills/plungeai-workflows/references/api) — the One API `/v1/workflows/*` HTTP surface: inline vs
  saved execution, SSE streaming events, result redemption, cancel, trace
  correlation, legacy aliases.
- [`references/mcp.md`](/skills/plungeai-workflows/references/mcp) — the full MCP tool set for workflows:
  `plungeai_execute_workflow`, `plungeai_get_workflow_status`,
  `plungeai_list_workflows`, `plungeai_workflow` (CRUD + versioning),
  `plungeai_build_workflow`, `plungeai_executions`, and `plungeai_templates`
  (`action: "use"` — instantiating a gallery template as a workflow; browsing
  is `plungeai-discovery`'s).

## Reference pages

<CardGroup cols={2}>
<Card title="Workflows plane — /v1/workflows" icon="file-text" href="/skills/plungeai-workflows/references/api">
Run multi-agent CNL workflows: inline (send the workflow document in the request), saved (reference a workflow id saved in Ocean Studio), each with an…
</Card>
<Card title="Getting a workflow into PlungeAI — three channels" icon="file-text" href="/skills/plungeai-workflows/references/channels">
Connect once (self-service ozk key from Dashboard → One API → Keys, https://dashboard.plungeai.com):
</Card>
<Card title="CNL Workflow Reference (engine v6) — PlungeAI" icon="file-text" href="/skills/plungeai-workflows/references/cnl-spec">
CNL (Cognitive Natural Language) is PlungeAI's YAML workflow language: you declare tasks and how they compose (parallel, sequential, batch, debate, harness…
</Card>
<Card title="Workflows — execute_workflow, get_workflow_status, list_workflows, workflow, build_workflow, executions" icon="file-text" href="/skills/plungeai-workflows/references/mcp">
Workflows are CNL YAML run by the platform engine.
</Card>
<Card title="Workflows — CNL orchestration: what it is and how to run it" icon="file-text" href="/skills/plungeai-workflows/references/overview">
A workflow is a YAML document (CNL — Cognitive Natural Language) that the engine executes as a DAG of agent calls: parallel fan-out, sequential pipelines…
</Card>
<Card title="CNL recipes — pick the shape, then adapt" icon="file-text" href="/skills/plungeai-workflows/references/recipes">
Full runnable versions live in examples/. Two composition rules apply to all of them:
</Card>
</CardGroup>

## Examples

<AccordionGroup>
<Accordion title="01-simple-search.yaml">

```yaml 01-simple-search.yaml
name: "Simple Single Task"
version: "2.0.0"
description: "Single search task — the smallest valid CNL workflow."

tasks:
  - type: "task"
    id: "single_task"
    agent: brave-agent
    prompt: "simple search test"

input: "electric vehicles 2026"
```

</Accordion>
<Accordion title="02-parallel-research.yaml">

```yaml 02-parallel-research.yaml
name: "Parallel Research With Synthesis"
version: "2.0.0"
description: "Three parallel searches from different engines, then LLM synthesis. The most common production pattern."

tasks:
  - type: "parallel"
    id: "research_phase"
    subtasks:
      - type: "task"
        id: "brave_search"
        agent: brave-agent
        prompt: "{input} — latest news, trends, and analysis"
      - type: "task"
        id: "tavily_research"
        agent: tavily-agent
        prompt: "{input} — cited sources and detailed reporting from the last 12 months"
      - type: "task"
        id: "exa_deep"
        agent: exa-agent
        operationType: "search"
        prompt: "{input} — academic papers, institutional research, and expert analyses"

  - type: "task"
    id: "synthesis"
    agent: llm-agent
    prompt: |
      Synthesize the parallel research into a comprehensive report on {input}.
      Sources:
      Brave: {data:brave_search}
      Tavily: {data:tavily_research}
      Exa: {data:exa_deep}

      Identify common themes, contradictions, and the three strongest insights.

input: "quantum computing commercial applications"
```

</Accordion>
<Accordion title="03-hierarchical.yaml">

```yaml 03-hierarchical.yaml
name: "3-Level Hierarchical Nesting"
version: "2.0.0"
description: "parallel → sequential → parallel nesting. Demonstrates unlimited nesting depth with data flowing automatically."

tasks:
  - type: "parallel"
    id: "level_1_parallel"
    subtasks:
      - type: "task"
        id: "simple_task"
        agent: brave-agent
        prompt: "{input} — quick overview"
      - type: "sequential"
        id: "level_2_sequential"
        subtasks:
          - type: "task"
            id: "deep_search"
            agent: tavily-agent
            prompt: "{input} — deep research with citations"
          - type: "parallel"
            id: "level_3_parallel"
            subtasks:
              - type: "task"
                id: "business_angle"
                agent: llm-agent
                prompt: "From the research, extract business implications for {input}"
              - type: "task"
                id: "technical_angle"
                agent: llm-agent
                prompt: "From the research, extract technical implications for {input}"

  - type: "task"
    id: "final_report"
    agent: llm-agent
    prompt: "Combine all prior branches into a comprehensive report on {input}."

input: "autonomous vehicle regulation"
```

</Accordion>
<Accordion title="04-validate-consensus.yaml">

```yaml 04-validate-consensus.yaml
workflow:
  name: "Consensus Validation With 3 Validators"
  version: "2.0.0"
  description: "Three LLM validators run in consensus on a single piece of content. Use when correctness must be triple-checked before publishing."
  tasks:
    - type: validate
      id: fact_check
      aggregation: consensus
      validators:
        - agent: llm-agent
          validation_rule: "Check if the numerical claims are plausible and internally consistent"
        - agent: llm-agent
          validation_rule: "Check for logical consistency — identify any contradictions"
        - agent: llm-agent
          validation_rule: "Check completeness — are all key financial metrics covered"
      success_criteria: "Content must be factually plausible, logically consistent, and comprehensive"

input: "Tesla reported Q4 2025 revenue of $25.7B. The automotive segment contributed $21.3B while energy generation and storage added $2.8B. Gross margins improved to 19.8% from 17.6% year-over-year. The company delivered 495,000 vehicles in Q4, a 12% increase from Q3."
```

</Accordion>
<Accordion title="05-batch-items.yaml">

```yaml 05-batch-items.yaml
name: "Per-Item Batch Pipeline"
version: "1.0.0"
description: "Run the same two-step pipeline for every item in a list, then roll up."

tasks:
  - type: "batch"
    id: "per_company"
    items:
      - "Cloudflare"
      - "Vercel"
      - "Fly.io"
    tasks:
      - type: "task"
        id: "research"
        agent: brave-agent
        prompt: "{item} — company overview, funding, latest news"
      - type: "task"
        id: "brief"
        agent: llm-agent
        prompt: "From the research above, write a 5-bullet analyst brief on {item}"

  - type: "task"
    id: "rollup"
    agent: llm-agent
    prompt: "Combine the briefs into one comparison table: {data:per_company}"

input: "edge platforms"
```

</Accordion>
<Accordion title="06-harness-mission.yaml">

```yaml 06-harness-mission.yaml
name: "Bounded Research Mission"
version: "1.0.0"
description: "A goal-driven harness run with an inline mission, effort preset, and turn cap."

tasks:
  - type: "harness"
    id: "market_scan"
    goal: "Map the top 5 vendors for {input}, with pricing and one differentiator each."
    mission:
      mission: "You are a market analyst. Research thoroughly, cite sources, stay on topic."
      effort: "standard"
      max_turns: 12
      success_criteria:
        - "5 vendors named with pricing"
        - "every claim has a source URL"

  - type: "output"
    id: "deliver"
    format: "markdown"

input: "workflow orchestration platforms"
```

</Accordion>
</AccordionGroup>