plungeai-workflows

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 (opens in a new tab) · View raw SKILL.md (opens in a new tab)

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, 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 and pick a shape from references/recipes.md. 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. kind files it as workflow (default), agent, bot or campaign; a bot or agent is exactly ONE type: harness task on agent: one-agent (author it with plungeai-bot-agent). 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: (a schedule is a scheduler job — Studio, plungeai_schedule, /v1/schedules — never 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 one-agent.

Saved bots — policy, files, chats, groups (every door)

A saved kind: bot carries a stored policy (permission presets incl. hand_off, admin locks, budget_usd_run / budget_usd_month) that the engine applies on EVERY door. Keys and meaning: plungeai-bot-agent. The control verbs:

Setting locks needs a team admin (REST 403 lock_admin_required; nothing in that body is written). Run steering and files live in plungeai-results-traces; schedules and triggers in plungeai-scheduling; all REST bodies in plungeai-api-setup (references/bots-and-door.md).

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.

References (load on demand)

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

More

• references/overview.md — the platform-level view: parallelism facts (measured, not guessed), placeholders and date tokens, execution/results/ follow-up semantics, failure semantics.
• references/api.md — the One API /v1/workflows/* HTTP surface: inline vs saved execution, SSE streaming events, result redemption, cancel, trace correlation, legacy aliases.
• references/mcp.md — the full MCP tool set for workflows (incl. the bot verbs above): 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

Examples

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"

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: one-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"

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: one-agent
                prompt: "From the research, extract business implications for {input}"
              - type: "task"
                id: "technical_angle"
                agent: one-agent
                prompt: "From the research, extract technical implications for {input}"

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

input: "autonomous vehicle regulation"

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: one-agent
          validation_rule: "Check if the numerical claims are plausible and internally consistent"
        - agent: one-agent
          validation_rule: "Check for logical consistency — identify any contradictions"
        - agent: one-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."

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: one-agent
        prompt: "From the research above, write a 5-bullet analyst brief on {item}"

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

input: "edge platforms"

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"
    agent: "one-agent"
    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"