---
name: plungeai-workflows
description: "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\"."
---

# PlungeAI Workflow Builder

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.
   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`.

## 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:
  `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).