@conductor-oss/conductor-skills 1.4.2

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@conductor-oss/conductor-skills",
+  "version": "1.4.2",
+  "description": "Conductor workflow orchestration skill for AI coding agents — Claude Code, Cursor, Codex, Gemini, Cline, Copilot, and more.",
+  "bin": {
+    "conductor-skills": "bin/conductor-skills.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "commands/",
+    ".claude-plugin/",
+    "install.sh",
+    "install.ps1",
+    "VERSION",
+    "README.md",
+    "LICENSE.txt"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "validate": "python3 scripts/validate_plugin.py",
+    "test": "python3 scripts/validate_plugin.py"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/conductor-oss/conductor-skills.git"
+  },
+  "homepage": "https://github.com/conductor-oss/conductor-skills",
+  "bugs": {
+    "url": "https://github.com/conductor-oss/conductor-skills/issues"
+  },
+  "license": "Apache-2.0",
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "ai-agent",
+    "ai-skill",
+    "conductor",
+    "conductor-oss",
+    "orkes",
+    "workflow",
+    "orchestration",
+    "microservices"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/conductor/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: conductor
+description: "Create, run, monitor, manage, and review Conductor workflows and tasks. Use when the user wants to define workflows, start executions, check status, pause/resume/terminate/retry workflows, signal tasks, schedule recurring runs, or review/optimize an existing workflow. Uses the `conductor` CLI or falls back to bundled REST API script. Requires a reachable Conductor server — auto-detected for a local `conductor server start`, otherwise set `CONDUCTOR_SERVER_URL`."
+allowed-tools: Bash(conductor *), Bash(npx *conductor*), Bash(python3 *conductor_api.py*), Bash(npm install *), Bash(chmod *), Bash(* --version), Bash(* --help), Bash(echo *), Read, Write, Edit, Grep, Glob
+---
+
+# Conductor Workflows
+
+## What this skill does
+
+When asked what you can help with, enumerate these nine areas — every one is covered by this skill and the references it links to:
+
+1. **Create** workflow definitions (any task type: SIMPLE, HTTP, SWITCH, FORK_JOIN, DO_WHILE, WAIT, SUB_WORKFLOW, LLM_*, MCP, etc.)
+2. **Run** executions — sync or async, with file or inline input, by version, with correlation ID
+3. **Monitor** — search by status / name / time, fetch execution details, diagnose failures
+4. **Manage** — pause, resume, terminate, restart, retry, rerun, skip-task, jump
+5. **Signal** — advance WAIT / HUMAN tasks (sync or async) with structured output
+6. **Schedule** — Quartz-cron schedules (part of OSS, not Orkes-only)
+7. **Scaffold workers** in Python, JavaScript / TypeScript, Java, Go (referral to upstream SDKs for C# / Ruby / Rust)
+8. **Visualize** — render any workflow as a Mermaid flowchart + UI link
+9. **Review & optimize** — walk the 19-rule checklist in [references/optimization.md](references/optimization.md) and report CRITICAL / WARN / INFO
+
+Plus Orkes-only: **secrets** and **webhooks**.
+
+## Rules
+
+1. **Worker gate (most important).** Every time you create *or* update a workflow, list its `SIMPLE` tasks and verify each has a registered task definition (`conductor taskDef list`). For any unregistered SIMPLE task, **tell the user** the workflow will hang on that step and offer to (a) create the task definition or (b) scaffold a worker (see [references/workers.md](references/workers.md)). This applies to every workflow create/update — not just first-time setup.
+2. **Never use `python3 -c` to construct, parse, format, or post-process Conductor data.** Write JSON to files via the Write tool or heredoc; format command output yourself in plain text. You can read JSON — don't spawn Python to interpret it. (Validation utilities run from script files are fine.)
+3. **CLI resolution order — STOP and ASK before any global install.**
+   1. If `conductor` is on PATH, use it directly.
+   2. Otherwise prefer `npx @conductor-oss/conductor-cli ...` for one-off use (no system change).
+   3. **NEVER run `npm install -g @conductor-oss/conductor-cli` without first asking the user.** Phrase it explicitly: *"OK to globally install `@conductor-oss/conductor-cli` via npm? It modifies your global node_modules."* Wait for a yes.
+   4. Only after `conductor` and `npm` are both unavailable, fall back to `scripts/conductor_api.py`. If the user has stated upfront that Node/npm cannot be installed, note that constraint and go straight to the fallback — no need to retry npm. See [references/setup.md](references/setup.md).
+4. **Use `--json` flags** when available; format the parsed result yourself.
+5. **Never echo auth tokens, keys, or secrets.** Set them via env vars (`CONDUCTOR_AUTH_KEY`, `CONDUCTOR_AUTH_SECRET`, or `CONDUCTOR_AUTH_TOKEN`). Confirm credentials by name in output, never by value.
+
+## Slash commands
+
+Three structured procedures are exposed as slash commands. The skill itself handles everything else through natural language.
+
+| Command | Purpose |
+|---------|---------|
+| `/conductor` | Menu — lists subcommands, shows examples of natural-language requests |
+| `/conductor-setup` | First-time setup (CLI install, server, auth) |
+| `/conductor-optimize` | Review an existing workflow against the optimization checklist |
+| `/conductor-scaffold-worker` | Generate a worker stub in any supported language |
+
+Anything else (run, status, schedule, pause, retry, signal, visualize, create) is fluid through plain English — no command needed.
+
+## Setup check
+
+If the user has nothing set up, walk them through **[references/setup.md](references/setup.md)** Steps 1–4. To verify a working environment:
+
+```bash
+conductor --version          # CLI present?
+conductor workflow list      # Server reachable?
+```
+
+## Commands
+
+Full verb-to-CLI lookup is in **[references/cli-index.md](references/cli-index.md)**. Python fallback equivalents (when neither `conductor` nor `npx` is available) are in **[references/fallback-cli.md](references/fallback-cli.md)**. Schedules (OSS) are in **[references/schedules.md](references/schedules.md)**. Enterprise commands (secrets, webhooks) are in **[references/orkes.md](references/orkes.md)**.
+
+## Creating workflows
+
+1. Consult **[references/workflow-definition.md](references/workflow-definition.md)** for task types, the `${...}` expression syntax, and the `$.var` rule for JS-evaluated tasks (INLINE, DO_WHILE, SWITCH/javascript).
+2. Write the JSON to a file with the Write tool, then `conductor workflow create file.json`.
+3. **Run the worker gate** (Rule 1).
+
+For inputs to workflow start: use `-i '{"...":"..."}'` for small inline JSON, `-f input.json` for larger payloads.
+
+## Examples
+
+Operational:
+
+- [Create and run](examples/create-and-run-workflow.md) — define, register, execute end-to-end.
+- [Monitor and retry](examples/monitor-and-retry.md) — search failures, distinguish retryable from terminal, batch retry.
+- [Signal a WAIT task](examples/signal-wait-task.md) — human-in-the-loop signaling.
+- [Review and optimize a workflow](examples/review-workflow.md) — apply the optimization checklist.
+
+Design patterns:
+
+- [FORK_JOIN parallel branches](examples/fork-join.md)
+- [DO_WHILE loop with iteration counter](examples/do-while-loop.md)
+- [SUB_WORKFLOW composition](examples/sub-workflow.md)
+
+AI / LLM patterns:
+
+- [Minimum LLM workflow](examples/llm-chat.md) — single `LLM_CHAT_COMPLETE` task.
+- [AI agent with MCP tools](examples/ai-agent-mcp.md) — `LIST_MCP_TOOLS` → plan → `CALL_MCP_TOOL` → summarize.
+- [Autonomous agent loop (ReAct)](examples/ai-agent-loop.md) — `DO_WHILE` think/act/observe until done.
+- [RAG — retrieval-augmented Q&A](examples/llm-rag.md) — `LLM_SEARCH_INDEX` then grounded `LLM_CHAT_COMPLETE`.
+
+Raw definitions in [examples/workflows/](examples/workflows/) — pass any directly to `conductor workflow create`:
+
+| File | Pattern |
+|------|---------|
+| `weather-notification.json` | Two HTTP tasks in sequence, output chaining |
+| `fork-join.json` | Parallel branches with JOIN + JQ merge |
+| `do-while-loop.json` | DO_WHILE with iteration counter (self-reference pattern) |
+| `child-normalize.json` | Reusable child workflow (JQ transform) |
+| `parent-pipeline.json` | SUB_WORKFLOW composing the child above |
+| `llm-chat.json` | Single LLM_CHAT_COMPLETE — summarize text |
+| `ai-agent-mcp.json` | 4-task AI agent: list tools → plan → call → summarize |
+| `ai-agent-loop.json` | DO_WHILE agent loop, ReAct pattern |
+| `llm-rag.json` | RAG: vector search + grounded LLM answer |
+
+## Reviewing workflows
+
+When the user asks to **review**, **optimize**, **simplify**, or **audit** a workflow:
+
+1. Load the definition (file path, or `conductor workflow get {name}`).
+2. For each `SIMPLE` task, also load its task definition (`conductor taskDef get {name}`) — timeouts and retry config live there, not on the workflow task.
+3. Walk the checklist in **[references/optimization.md](references/optimization.md)**, grouping findings as **CRITICAL** / **WARN** / **INFO**.
+4. Offer fixes one at a time. Don't apply changes silently.
+
+Worked example: [examples/review-workflow.md](examples/review-workflow.md).
+
+## Visualizing workflows
+
+When the user asks to visualize a workflow, or after creating one, generate a Mermaid flowchart. Construct mappings (FORK_JOIN, SWITCH, DO_WHILE, etc.) and rules are in **[references/visualization.md](references/visualization.md)**. If a server is reachable, also offer the UI link `{BASE_URL}/workflowDef/{name}` (resolve `BASE_URL` from `CONDUCTOR_SERVER_URL` by stripping `/api`).
+
+## Workers
+
+When the user asks to write a worker:
+
+1. Ask which language (Python, JS/TS, Java, Go, C#, Ruby, Rust).
+2. Install the SDK and scaffold from the pattern in **[references/workers.md](references/workers.md)**.
+3. The worker's task type **must** match the `name` of the SIMPLE task in the workflow.
+4. Note in code that workers must be idempotent — Conductor may redeliver on failure or timeout.
+
+## Output
+
+- Render workflow data as structured summaries (`workflowId`, `status`, `startTime`, `endTime`, failed-task name + reason + retry count).
+- Render searches as a table (`workflowId`, `name`, `status`, `startTime`).
+- For more on output, error decoding, and stuck-workflow diagnosis, see **[references/troubleshooting.md](references/troubleshooting.md)**.
+
+## References at a glance
+
+| File | Purpose |
+|------|---------|
+| [setup.md](references/setup.md) | Install CLI, configure server, auth, profiles |
+| [cli-index.md](references/cli-index.md) | Verb → CLI command lookup |
+| [fallback-cli.md](references/fallback-cli.md) | Python fallback equivalents (subset of CLI) |
+| [workflow-definition.md](references/workflow-definition.md) | JSON schema, all task types, expression syntax |
+| [workers.md](references/workers.md) | SDK examples in 7 languages |
+| [api-reference.md](references/api-reference.md) | REST endpoints |
+| [visualization.md](references/visualization.md) | Mermaid mappings + UI link |
+| [schedules.md](references/schedules.md) | Cron schedules (OSS) — schema, format, patterns |
+| [orkes.md](references/orkes.md) | Enterprise (Orkes): secrets, webhooks |
+| [optimization.md](references/optimization.md) | Workflow review/optimize checklist |
+| [troubleshooting.md](references/troubleshooting.md) | Common errors + diagnosis flow |

package/skills/conductor/examples/ai-agent-loop.md

@@ -0,0 +1,119 @@
+# Example: Autonomous Agent Loop (ReAct Pattern)
+
+An LLM-driven agent that **thinks**, **acts**, and **observes** in a loop until it decides it's done. Built with `DO_WHILE` wrapping an LLM_CHAT_COMPLETE → SWITCH → CALL_MCP_TOOL inner sequence.
+
+Use this when the answer requires multiple tool calls in sequence — e.g., "look up the customer, then their last order, then refund the matching line item." A single-shot agent ([ai-agent-mcp.md](ai-agent-mcp.md)) only plans once; an agent loop replans every iteration with the accumulated tool results in context.
+
+## Pipeline
+
+```
+DO_WHILE {
+  think  (LLM_CHAT_COMPLETE)  →  emits { done, method?, arguments?, answer? }
+  act    (SWITCH on done)     →  CALL_MCP_TOOL if not done, NOOP if done
+} until think says done == true
+```
+
+The whole loop is one workflow task. Each iteration is a durable checkpoint — a crash mid-tool-call resumes from the last completed iteration **without replaying earlier LLM calls**.
+
+## Workflow
+
+See [workflows/ai-agent-loop.json](workflows/ai-agent-loop.json). Key tasks:
+
+```json
+{
+  "name": "agent_loop",
+  "taskReferenceName": "loop",
+  "type": "DO_WHILE",
+  "loopCondition": "if ($.loop['iteration'] < 10 && $.loop[$.loop['iteration']].think.output.result.done != true) { true; } else { false; }",
+  "loopOver": [
+    {
+      "name": "think",
+      "taskReferenceName": "think",
+      "type": "LLM_CHAT_COMPLETE",
+      "inputParameters": {
+        "llmProvider": "openai",
+        "model": "gpt-4o-mini",
+        "messages": [
+          {"role": "system", "message": "You are an agent. Tools: ${workflow.input.tools}. Previous results: ${loop.output}. Decide next step. Respond as JSON: { done: bool, method?: string, arguments?: object, answer?: string }."},
+          {"role": "user", "message": "${workflow.input.task}"}
+        ],
+        "temperature": 0.1,
+        "maxTokens": 500
+      }
+    },
+    {
+      "name": "act",
+      "taskReferenceName": "act",
+      "type": "SWITCH",
+      "evaluatorType": "javascript",
+      "expression": "$.done ? 'finish' : 'call_tool'",
+      "inputParameters": {
+        "done": "${think.output.result.done}"
+      },
+      "decisionCases": {
+        "call_tool": [{
+          "name": "execute",
+          "taskReferenceName": "execute",
+          "type": "CALL_MCP_TOOL",
+          "inputParameters": {
+            "mcpServer": "${workflow.input.mcpServer}",
+            "method": "${think.output.result.method}",
+            "arguments": "${think.output.result.arguments}"
+          }
+        }],
+        "finish": [{"name": "done", "taskReferenceName": "done", "type": "NOOP"}]
+      }
+    }
+  ],
+  "inputParameters": {
+    "loop": "${loop.output}"
+  }
+}
+```
+
+Then a single task after the loop pulls out the final answer:
+
+```json
+{
+  "name": "final_answer",
+  "taskReferenceName": "final",
+  "type": "INLINE",
+  "inputParameters": {
+    "evaluatorType": "graaljs",
+    "expression": "function e() { var i = $.loop_output['iteration']; return $.loop_output[i].think.output.result.answer; } e();",
+    "loop_output": "${loop.output}"
+  }
+}
+```
+
+## Run
+
+```bash
+conductor workflow create examples/workflows/ai-agent-loop.json
+conductor workflow start -w autonomous_agent -i '{
+  "task": "Find user 42 and refund their last order.",
+  "mcpServer": "http://localhost:3001/mcp",
+  "tools": "search_user, get_orders, refund_order"
+}' --sync
+```
+
+## The `$.loop_ref` self-reference pattern
+
+`"loop": "${loop.output}"` in `inputParameters` wires the loop task's own output back into its `loopCondition` scope. This looks like a typo — referencing a task before it has output — but it's the canonical pattern. Conductor resolves it lazily at each iteration, exposing `iteration` and all prior iterations' task outputs (`$.loop[1].think.output...`, `$.loop[2].think.output...`).
+
+See [do-while-loop.md](do-while-loop.md) for more detail on this pattern.
+
+## Critical guardrails
+
+- **Cap iterations.** The condition above includes `$.loop['iteration'] < 10` as a hard cap. Without it, a buggy "I'm not done yet" reply spins forever and burns LLM budget. The optimization checklist ([../references/optimization.md](../references/optimization.md)) flags unbounded loops as **CRITICAL** (rule B5).
+- **Set a workflow timeout** (`timeoutSeconds` + `timeoutPolicy: TIME_OUT_WF`). A 10-iteration cap with no per-iteration timeout can still hang on a slow tool call.
+- **Token budget per iteration is enforced by `maxTokens`** — the loop itself has no token budget. For cost control, multiply: 10 iterations × 500 max tokens × $/token.
+
+## When to use the loop vs the single-shot
+
+| Use single-shot ([ai-agent-mcp.md](ai-agent-mcp.md)) | Use the loop |
+|------------------------------------------------------|--------------|
+| Answer always needs exactly one tool call | Answer needs an unknown number of tool calls |
+| You can constrain the model to pick ONE action | Tasks chain — output of one tool informs the next |
+| You want strict, audit-friendly determinism | Some exploration is acceptable |
+| Latency matters (one LLM call + one tool call) | Total budget tolerates 5–10 LLM round trips |

package/skills/conductor/examples/ai-agent-mcp.md

@@ -0,0 +1,129 @@
+# Example: AI Agent with MCP Tools
+
+A 4-task agent that discovers tools from an MCP server, plans an action with an LLM, calls the chosen tool, then summarizes the result for the user. This is the canonical "first AI agent" pattern from the [Orkes docs](https://docs.conductor-oss.org/devguide/ai/first-ai-agent.html).
+
+## Pipeline
+
+```
+LIST_MCP_TOOLS → LLM_CHAT_COMPLETE (plan) → CALL_MCP_TOOL → LLM_CHAT_COMPLETE (summarize)
+```
+
+The agent is **linear, deterministic, durable**: every task is a Conductor checkpoint. If the tool call or the summarizer crashes, the workflow resumes from the last completed task — no replay of the planning LLM call.
+
+## Prerequisites
+
+1. **An MCP server** reachable from Conductor. For local dev: `mcp-testkit --transport http` listens on `http://localhost:3001/mcp`.
+2. **An LLM provider** with its API key set on the Conductor server:
+   ```bash
+   export OPENAI_API_KEY=sk-...
+   # or
+   export ANTHROPIC_API_KEY=sk-ant-...
+   ```
+   Conductor auto-enables providers when their API key is set — no separate registration in OSS.
+
+## Workflow
+
+See [workflows/ai-agent-mcp.json](workflows/ai-agent-mcp.json). Key tasks:
+
+```json
+{
+  "name": "discover_tools",
+  "taskReferenceName": "discover",
+  "type": "LIST_MCP_TOOLS",
+  "inputParameters": {
+    "mcpServer": "http://localhost:3001/mcp"
+  }
+},
+{
+  "name": "plan_action",
+  "taskReferenceName": "plan",
+  "type": "LLM_CHAT_COMPLETE",
+  "inputParameters": {
+    "llmProvider": "openai",
+    "model": "gpt-4o-mini",
+    "messages": [
+      {"role": "system", "message": "You are an AI agent. Available tools: ${discover.output.tools}. Pick exactly one tool and respond as JSON with fields `method` and `arguments`."},
+      {"role": "user", "message": "${workflow.input.task}"}
+    ],
+    "temperature": 0.1,
+    "maxTokens": 500
+  }
+},
+{
+  "name": "execute_tool",
+  "taskReferenceName": "execute",
+  "type": "CALL_MCP_TOOL",
+  "inputParameters": {
+    "mcpServer": "http://localhost:3001/mcp",
+    "method": "${plan.output.result.method}",
+    "arguments": "${plan.output.result.arguments}"
+  }
+},
+{
+  "name": "summarize_result",
+  "taskReferenceName": "summarize",
+  "type": "LLM_CHAT_COMPLETE",
+  "inputParameters": {
+    "llmProvider": "openai",
+    "model": "gpt-4o-mini",
+    "messages": [
+      {"role": "user", "message": "The user asked: \"${workflow.input.task}\". Tool returned: ${execute.output.content}. Reply in one short paragraph."}
+    ],
+    "maxTokens": 500
+  }
+}
+```
+
+## Run
+
+```bash
+conductor workflow create examples/workflows/ai-agent-mcp.json
+conductor workflow start -w my_first_agent -i '{"task": "What is the weather in San Francisco?"}' --sync
+```
+
+Or hit the REST API directly for synchronous execution:
+
+```bash
+curl -s -X POST 'http://localhost:8080/api/workflow/execute/my_first_agent/1' \
+  -H 'Content-Type: application/json' \
+  -d '{"task": "What is the weather in San Francisco?"}' | jq
+```
+
+## Output
+
+```
+${plan.output.result}       → the LLM's chosen action (parsed JSON: method + arguments)
+${execute.output.content}   → raw output from the MCP tool
+${summarize.output.result}  → final natural-language answer for the user
+```
+
+## Adding human-in-the-loop
+
+Insert a `HUMAN` task between `plan` and `execute` to require approval before any tool call:
+
+```json
+{
+  "name": "approve",
+  "taskReferenceName": "approve",
+  "type": "HUMAN",
+  "inputParameters": {
+    "plannedAction": "${plan.output.result}",
+    "userTask": "${workflow.input.task}"
+  }
+}
+```
+
+The workflow pauses indefinitely until signaled. Approve via:
+
+```bash
+conductor task signal-sync --workflow-id {id} --task-ref approve --status COMPLETED --output '{"approved": true}'
+```
+
+See [signal-wait-task.md](signal-wait-task.md) for the signaling pattern.
+
+## Patterns
+
+- **Two LLM calls, two purposes.** First call plans (deterministic, low-temperature, JSON-shaped output). Second call summarizes (natural language for the user). Splitting them lets you swap models per role — small model for planning, larger for summary, or vice versa.
+- **JSON-shaped LLM output.** `${plan.output.result.method}` works because Conductor parses the LLM response as JSON when the model emits one. Make the system prompt require JSON. Use `temperature: 0.1` to keep it deterministic.
+- **Durable checkpoints.** Each task is a save point. A crashed MCP call resumes without re-running the planner.
+- **Tool surface from `LIST_MCP_TOOLS`.** The agent learns its capabilities at runtime — change the MCP server's exposed tools and the workflow adapts without redeploy.

package/skills/conductor/examples/create-and-run-workflow.md

@@ -0,0 +1,50 @@
+# Example: Create and Run a Workflow
+
+> "Create a workflow that calls a weather API and sends a notification, then run it."
+
+## Steps
+
+1. Verify CLI: `conductor --version`. Verify `CONDUCTOR_SERVER_URL` (or that a local server is running). See [setup.md](../references/setup.md).
+2. Consult [workflow-definition.md](../references/workflow-definition.md) for task types.
+3. Write the definition to a file and register it.
+4. Start the workflow.
+5. Check execution status.
+6. Run the worker gate (Rule 1 in [SKILL.md](../SKILL.md)) — for this example, no SIMPLE tasks, so nothing to scaffold.
+
+## Definition
+
+See [workflows/weather-notification.json](workflows/weather-notification.json). Two HTTP tasks: fetch weather, then post a notification using the result.
+
+```json
+{
+  "name": "send_notification", "taskReferenceName": "send_notification", "type": "HTTP",
+  "inputParameters": {
+    "http_request": {
+      "uri": "https://api.notify.example.com/send",
+      "method": "POST",
+      "body": {
+        "to": "${workflow.input.notifyEmail}",
+        "message": "Weather in ${workflow.input.city}: ${fetch_weather.output.response.body.temperature}°F"
+      }
+    }
+  }
+}
+```
+
+## Run
+
+```bash
+conductor workflow create examples/workflows/weather-notification.json
+conductor workflow start -w weather_notification -i '{"city": "San Francisco", "notifyEmail": "user@example.com"}'
+# → returns workflowId
+conductor workflow get-execution {workflowId} -c
+```
+
+Expected status: `COMPLETED`. Output: `${fetch_weather.output.response.body}` and `${send_notification.output.response.statusCode}`.
+
+## Patterns demonstrated
+
+- HTTP task for external APIs.
+- Workflow input parameterization via `${workflow.input.x}`.
+- Task-to-task data passing via `${taskRef.output.x}`.
+- `outputParameters` for aggregating results.

package/skills/conductor/examples/do-while-loop.md

@@ -0,0 +1,72 @@
+# Example: DO_WHILE Loop with Iteration Counter
+
+Loop a body of tasks until a JavaScript condition returns false. The body sees an auto-managed `iteration` counter on the loop task's output.
+
+## The self-reference pattern
+
+The `loopCondition` is JavaScript. Variables in the script are read from the task's `inputParameters` via `$.varName`. To read the iteration counter, you must wire the loop task's *own output* back into its inputs:
+
+```json
+"inputParameters": {
+  "value": "${workflow.input.count}",
+  "loop_ref": "${loop_ref.output}"
+}
+```
+
+This looks like a typo — referencing the task before it has output — but it's the canonical pattern. Conductor resolves `${loop_ref.output}` lazily at each iteration, exposing the running counter as `$.loop_ref['iteration']` inside the script.
+
+## Workflow
+
+See [workflows/do-while-loop.json](workflows/do-while-loop.json):
+
+```json
+{
+  "name": "loop",
+  "taskReferenceName": "loop_ref",
+  "type": "DO_WHILE",
+  "loopCondition": "if ($.loop_ref['iteration'] < $.value) { true; } else { false; }",
+  "loopOver": [
+    {
+      "name": "do_work",
+      "taskReferenceName": "do_work",
+      "type": "HTTP",
+      "inputParameters": {
+        "http_request": {
+          "uri": "${workflow.input.endpoint}?page=${loop_ref.output.iteration}",
+          "method": "GET"
+        }
+      }
+    }
+  ],
+  "inputParameters": {
+    "value": "${workflow.input.count}",
+    "loop_ref": "${loop_ref.output}"
+  }
+}
+```
+
+## Run
+
+```bash
+conductor workflow create examples/workflows/do-while-loop.json
+conductor workflow start -w paginated_fetch -i '{"endpoint": "https://api.example.com/items", "count": 5}'
+```
+
+## Reading per-iteration output
+
+Each iteration's task output is keyed by iteration number under the loop task:
+
+```
+${loop_ref.output.1.do_work.response.body}
+${loop_ref.output.2.do_work.response.body}
+...
+```
+
+The total iteration count is at `${loop_ref.output.iteration}`.
+
+## Notes
+
+- `iteration` is 1-indexed.
+- The condition uses semicolon-terminated JS — Conductor's evaluator is strict.
+- Every variable referenced as `$.x` in the condition must appear as a key in `inputParameters`. Forgetting this gives a confusing "undefined" failure at runtime.
+- For unbounded loops, guard with both an iteration cap and a result-driven condition (e.g. `iteration < 100 && !$.loop_ref[iteration].do_work.output.done`).

package/skills/conductor/examples/fork-join.md

@@ -0,0 +1,52 @@
+# Example: Parallel Branches with FORK_JOIN
+
+Run independent tasks in parallel, then converge before continuing. Always pair `FORK_JOIN` with a `JOIN` that lists every parallel branch's terminal `taskReferenceName`.
+
+## Pattern
+
+```
+       ┌─→ branch_a_task ─┐
+fork ──┤                  ├─→ join ─→ next
+       └─→ branch_b_task ─┘
+```
+
+## Workflow
+
+See [workflows/fork-join.json](workflows/fork-join.json). Key tasks:
+
+```json
+{
+  "name": "fork", "taskReferenceName": "fork", "type": "FORK_JOIN",
+  "forkTasks": [
+    [{"name": "fetch_inventory", "taskReferenceName": "inventory", "type": "HTTP", "inputParameters": {"http_request": {"uri": "${workflow.input.inventoryUrl}", "method": "GET"}}}],
+    [{"name": "fetch_pricing",   "taskReferenceName": "pricing",   "type": "HTTP", "inputParameters": {"http_request": {"uri": "${workflow.input.pricingUrl}",   "method": "GET"}}}]
+  ]
+},
+{
+  "name": "join", "taskReferenceName": "join", "type": "JOIN",
+  "joinOn": ["inventory", "pricing"]
+}
+```
+
+## Run
+
+```bash
+conductor workflow create examples/workflows/fork-join.json
+conductor workflow start -w parallel_fetch -i '{"inventoryUrl": "https://...", "pricingUrl": "https://..."}'
+```
+
+## Reading the output
+
+Each branch's output is available as `${branchRef.output...}` in tasks after the JOIN. The JOIN task's own output aggregates branch outputs by reference name:
+
+```
+${join.output.inventory.response.body}
+${join.output.pricing.response.body}
+```
+
+## Notes
+
+- Branches in `forkTasks` are arrays of arrays — one inner array per parallel branch. Each inner array can itself be a sequence of tasks.
+- `joinOn` must list the **last** task's `taskReferenceName` from each branch.
+- Failure in any branch fails the JOIN unless every task in that branch is `optional: true`.
+- For dynamic branch counts, use `FORK_JOIN_DYNAMIC` (see workflow-definition.md).