@conductor-oss/conductor-skills 1.4.2

package/skills/conductor/examples/workflows/llm-chat.json

@@ -0,0 +1,28 @@
+{
+  "name": "summarize_text",
+  "description": "Summarize input text using an LLM",
+  "version": 1,
+  "schemaVersion": 2,
+  "inputParameters": ["text"],
+  "tasks": [
+    {
+      "name": "summarize",
+      "taskReferenceName": "summarize",
+      "type": "LLM_CHAT_COMPLETE",
+      "inputParameters": {
+        "llmProvider": "openai",
+        "model": "gpt-4o-mini",
+        "messages": [
+          {"role": "system", "message": "You summarize text in one sentence."},
+          {"role": "user", "message": "${workflow.input.text}"}
+        ],
+        "temperature": 0.3,
+        "maxTokens": 200
+      }
+    }
+  ],
+  "outputParameters": {
+    "summary": "${summarize.output.result}",
+    "tokensUsed": "${summarize.output.tokenUsed}"
+  }
+}

package/skills/conductor/examples/workflows/llm-rag.json

@@ -0,0 +1,49 @@
+{
+  "name": "rag_qa",
+  "description": "Retrieval-augmented Q&A: vector search then LLM answer with context",
+  "version": 1,
+  "schemaVersion": 2,
+  "inputParameters": ["question"],
+  "tasks": [
+    {
+      "name": "search_knowledge_base",
+      "taskReferenceName": "search",
+      "type": "LLM_SEARCH_INDEX",
+      "inputParameters": {
+        "vectorDB": "postgres-prod",
+        "namespace": "kb",
+        "index": "articles",
+        "embeddingModelProvider": "openai",
+        "embeddingModel": "text-embedding-3-small",
+        "query": "${workflow.input.question}",
+        "llmMaxResults": 3
+      }
+    },
+    {
+      "name": "generate_answer",
+      "taskReferenceName": "answer",
+      "type": "LLM_CHAT_COMPLETE",
+      "inputParameters": {
+        "llmProvider": "anthropic",
+        "model": "claude-sonnet-4-6",
+        "messages": [
+          {
+            "role": "system",
+            "message": "Answer using only the context below. If the answer isn't in the context, say \"I don't know.\"\n\nContext:\n${search.output.result}"
+          },
+          {
+            "role": "user",
+            "message": "${workflow.input.question}"
+          }
+        ],
+        "temperature": 0.2,
+        "maxTokens": 500
+      }
+    }
+  ],
+  "outputParameters": {
+    "answer": "${answer.output.result}",
+    "sources": "${search.output.result}",
+    "tokensUsed": "${answer.output.tokenUsed}"
+  }
+}

package/skills/conductor/examples/workflows/parent-pipeline.json

@@ -0,0 +1,35 @@
+{
+  "name": "parent_pipeline",
+  "description": "Composes child_normalize then forwards the result",
+  "version": 1,
+  "schemaVersion": 2,
+  "inputParameters": ["raw"],
+  "tasks": [
+    {
+      "name": "normalize",
+      "taskReferenceName": "normalize",
+      "type": "SUB_WORKFLOW",
+      "subWorkflowParam": {
+        "name": "child_normalize",
+        "version": 1
+      },
+      "inputParameters": {
+        "payload": "${workflow.input.raw}"
+      }
+    },
+    {
+      "name": "log_result",
+      "taskReferenceName": "log_result",
+      "type": "INLINE",
+      "inputParameters": {
+        "evaluatorType": "graaljs",
+        "expression": "function e() { return { message: 'Normalized: ' + JSON.stringify($.normalized) }; } e();",
+        "normalized": "${normalize.output.normalized}"
+      }
+    }
+  ],
+  "outputParameters": {
+    "normalized": "${normalize.output.normalized}",
+    "log": "${log_result.output.result.message}"
+  }
+}

package/skills/conductor/examples/workflows/weather-notification.json

@@ -0,0 +1,42 @@
+{
+  "name": "weather_notification",
+  "description": "Fetch weather and send a notification",
+  "version": 1,
+  "schemaVersion": 2,
+  "inputParameters": ["city", "notifyEmail"],
+  "tasks": [
+    {
+      "name": "fetch_weather",
+      "taskReferenceName": "fetch_weather",
+      "type": "HTTP",
+      "inputParameters": {
+        "http_request": {
+          "uri": "https://api.weather.example.com/current?city=${workflow.input.city}",
+          "method": "GET",
+          "headers": { "Accept": "application/json" }
+        }
+      }
+    },
+    {
+      "name": "send_notification",
+      "taskReferenceName": "send_notification",
+      "type": "HTTP",
+      "inputParameters": {
+        "http_request": {
+          "uri": "https://api.notify.example.com/send",
+          "method": "POST",
+          "headers": { "Content-Type": "application/json" },
+          "body": {
+            "to": "${workflow.input.notifyEmail}",
+            "subject": "Weather Update",
+            "message": "Current weather in ${workflow.input.city}: ${fetch_weather.output.response.body.temperature}°F, ${fetch_weather.output.response.body.condition}"
+          }
+        }
+      }
+    }
+  ],
+  "outputParameters": {
+    "weather": "${fetch_weather.output.response.body}",
+    "notificationStatus": "${send_notification.output.response.statusCode}"
+  }
+}

package/skills/conductor/references/api-reference.md

@@ -0,0 +1,111 @@
+# Conductor REST API Reference
+
+## Authentication
+
+Include one of these headers with every request:
+
+```
+X-Authorization: {token}
+Content-Type: application/json
+```
+
+## Base URL
+
+All paths below are relative to the server base URL (e.g. `http://localhost:8080/api`).
+
+## Workflow metadata endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/metadata/workflow` | List all workflow definitions |
+| GET | `/metadata/workflow/{name}?version={v}` | Get workflow definition |
+| GET | `/metadata/workflow/names-and-versions` | List names and versions only |
+| GET | `/metadata/workflow/latest-versions` | Get latest version of all workflows |
+| POST | `/metadata/workflow` | Create a workflow definition |
+| POST | `/metadata/workflow/validate` | Validate a workflow definition |
+| PUT | `/metadata/workflow` | Update workflow definitions (array) |
+| DELETE | `/metadata/workflow/{name}/{version}` | Delete a workflow definition |
+
+## Workflow execution endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/workflow` | Start workflow (body: StartWorkflowRequest) |
+| POST | `/workflow/{name}` | Start workflow by name (body: input map) |
+| POST | `/workflow/execute/{name}/{version}` | Execute synchronously |
+| GET | `/workflow/{workflowId}?includeTasks=true` | Get execution status |
+| GET | `/workflow/{workflowId}/tasks` | Get execution tasks (paginated) |
+| GET | `/workflow/running/{name}?version={v}` | List running workflow IDs |
+| GET | `/workflow/search?query={q}&start={s}&size={n}` | Search executions |
+| GET | `/workflow/{name}/correlated/{correlationId}` | Get by correlation ID |
+| PUT | `/workflow/{workflowId}/pause` | Pause workflow |
+| PUT | `/workflow/{workflowId}/resume` | Resume workflow |
+| DELETE | `/workflow/{workflowId}?reason={r}` | Terminate workflow |
+| POST | `/workflow/{workflowId}/restart` | Restart completed workflow |
+| POST | `/workflow/{workflowId}/retry` | Retry last failed task |
+| POST | `/workflow/{workflowId}/rerun` | Rerun from specific task |
+| PUT | `/workflow/{workflowId}/skiptask/{taskRef}` | Skip a task |
+| PUT | `/workflow/decide/{workflowId}` | Trigger decide |
+| DELETE | `/workflow/{workflowId}/remove` | Remove from system |
+| POST | `/workflow/test` | Test with mock data |
+
+## Task endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/tasks/poll/{tasktype}` | Poll for a single task |
+| GET | `/tasks/poll/batch/{tasktype}?count={n}` | Batch poll for tasks |
+| POST | `/tasks` | Update a task (body: TaskResult) |
+| POST | `/tasks/{workflowId}/{taskRefName}/{status}` | Update task by ref (async) |
+| POST | `/tasks/{workflowId}/{taskRefName}/{status}/sync` | Update task by ref (returns workflow) |
+| GET | `/tasks/{taskId}` | Get task by ID |
+| POST | `/tasks/{taskId}/log` | Log task execution details |
+| GET | `/tasks/{taskId}/log` | Get task execution logs |
+| GET | `/tasks/queue/size?taskType={t}` | Get queue size |
+| GET | `/tasks/queue/all` | Get all queue details |
+| GET | `/tasks/search?query={q}` | Search tasks |
+
+## Task definition endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/metadata/taskdefs` | List all task definitions |
+| GET | `/metadata/taskdefs/{tasktype}` | Get task definition |
+| POST | `/metadata/taskdefs` | Create task definitions (array) |
+| PUT | `/metadata/taskdefs` | Update a task definition |
+| DELETE | `/metadata/taskdefs/{tasktype}` | Delete task definition |
+
+## Event endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/event` | List all event handlers |
+| GET | `/event/{event}?activeOnly=true` | Get handlers for event |
+| POST | `/event` | Create event handler |
+| PUT | `/event` | Update event handler |
+| DELETE | `/event/{name}` | Delete event handler |
+
+## Search query syntax
+
+The `query` parameter supports field-based filtering:
+
+- `status=RUNNING`
+- `workflowType=my_workflow`
+- `startTime>[epoch_ms]`
+- `startTime<[epoch_ms]`
+
+Combine with AND: `status=RUNNING AND workflowType=my_workflow`
+
+The `sort` parameter: `sort=startTime:DESC`
+
+## Response codes
+
+| Code | Meaning |
+|------|---------|
+| 200 | Success |
+| 204 | Success, no content |
+| 400 | Bad request (invalid input) |
+| 401 | Unauthorized (missing/invalid token) |
+| 404 | Resource not found |
+| 409 | Conflict (already exists) |
+| 500 | Server error |

package/skills/conductor/references/cli-index.md

@@ -0,0 +1,92 @@
+# CLI Command Index
+
+Flat verb-to-CLI lookup. For fallback equivalents see [fallback-cli.md](fallback-cli.md).
+
+## Definitions
+
+| Verb | CLI |
+|------|-----|
+| List | `conductor workflow list` |
+| Get | `conductor workflow get {name}` |
+| Create | `conductor workflow create file.json` |
+| Update | `conductor workflow update file.json` |
+| Delete | `conductor workflow delete {name} {version}` |
+| List task defs | `conductor taskDef list` |
+| Create task def | `conductor taskDef create file.json` |
+
+## Execution
+
+| Verb | CLI |
+|------|-----|
+| Start (async) | `conductor workflow start -w {name} -i '{...}'` |
+| Start (sync, wait for completion) | `conductor workflow start -w {name} -i '{...}' --sync` |
+| Start (sync, wait until task) | `conductor workflow start -w {name} -i '{...}' --sync -u {taskRef}` |
+| Start with file input | `conductor workflow start -w {name} -f input.json` |
+| Start with version + correlation | `conductor workflow start -w {name} --version {v} --correlation {id} -i '{...}'` |
+| Get execution | `conductor workflow get-execution {id} -c` |
+| Quick status | `conductor workflow status {id}` |
+| Search by status | `conductor workflow search -s RUNNING -c 20` |
+| Search by name + status | `conductor workflow search -w {name} -s FAILED -c 10` |
+| Search by time | `conductor workflow search -s COMPLETED --start-time-after "2024-01-01" --start-time-before "2024-01-31"` |
+
+Statuses: `RUNNING`, `COMPLETED`, `FAILED`, `TIMED_OUT`, `TERMINATED`, `PAUSED`.
+
+## Lifecycle
+
+| Verb | CLI |
+|------|-----|
+| Pause | `conductor workflow pause {id}` |
+| Resume | `conductor workflow resume {id}` |
+| Terminate | `conductor workflow terminate {id}` |
+| Restart | `conductor workflow restart {id}` |
+| Restart on latest | `conductor workflow restart {id} --use-latest` |
+
+## Intervention
+
+| Verb | CLI |
+|------|-----|
+| Retry last failed task | `conductor workflow retry {id}` |
+| Rerun from task | `conductor workflow rerun {id} --task-id {taskId}` |
+| Skip a task | `conductor workflow skip-task {id} {taskRef}` |
+| Jump to task | `conductor workflow jump {id} {taskRef}` |
+| Signal task (async) | `conductor task signal --workflow-id {id} --task-ref {ref} --status COMPLETED --output '{...}'` |
+| Signal task (sync, returns workflow) | `conductor task signal-sync --workflow-id {id} --task-ref {ref} --status COMPLETED --output '{...}'` |
+
+Use **signal-sync** when you need the updated workflow back in one round-trip; **signal** is fire-and-forget.
+
+Task statuses for signaling: `COMPLETED`, `FAILED`, `FAILED_WITH_TERMINAL_ERROR`.
+
+## Tasks & queues
+
+| Verb | CLI |
+|------|-----|
+| Poll | `conductor task poll {taskType} --count 5` |
+| Update execution | `conductor task update-execution --workflow-id {id} --task-ref-name {ref} --status COMPLETED --output '{...}'` |
+| Queue size | `conductor task queue-size --task-type {type}` |
+
+## Schedules
+
+| Verb | CLI |
+|------|-----|
+| List | `conductor schedule list` |
+| Get | `conductor schedule get {name}` |
+| Create | `conductor schedule create file.json` |
+| Update | `conductor schedule update file.json` |
+| Delete | `conductor schedule delete {name}` |
+| Pause | `conductor schedule pause {name}` |
+| Resume | `conductor schedule resume {name}` |
+
+Schedules are part of OSS. See [schedules.md](schedules.md) for the JSON schema, cron format, and patterns.
+
+## Server (local)
+
+| Verb | CLI |
+|------|-----|
+| Start | `conductor server start` (or `--port 3000`) |
+| Status | `conductor server status` |
+| Logs | `conductor server logs -f` |
+| Stop | `conductor server stop` |
+
+## Enterprise (Orkes only)
+
+See [orkes.md](orkes.md) for `secret` and `webhook` commands.

package/skills/conductor/references/fallback-cli.md

@@ -0,0 +1,36 @@
+# Fallback CLI Mapping
+
+When the `conductor` CLI cannot be installed, use the bundled `scripts/conductor_api.py` (stdlib-only Python). Set `CONDUCTOR_API` to its path, e.g. `export CONDUCTOR_API="<skill-path>/scripts/conductor_api.py"`.
+
+The fallback covers core CRUD and execution — not all CLI features. Limitations:
+
+- **Auth:** `CONDUCTOR_AUTH_TOKEN` only. Key/secret exchange is **not** supported. Users on Orkes who need key/secret auth must obtain a token externally.
+- **No profile support** — set `CONDUCTOR_SERVER_URL` directly.
+- **No server auto-detection** — `CONDUCTOR_SERVER_URL` is required.
+- **No `taskDef` CRUD** — cannot list/create/update/delete task definitions.
+- **No time-range search** — `search-workflows` accepts `--query` and `--status` only.
+- **No** `update-execution`, `restart --use-latest`, `rerun`, `skip-task`, `jump`, schedules, secrets, webhooks, server lifecycle.
+
+## Verb → command mapping
+
+| Verb | CLI | Fallback |
+|------|-----|----------|
+| List workflow definitions | `conductor workflow list` | `python3 "$CONDUCTOR_API" list-workflows` |
+| Get workflow definition | `conductor workflow get {name}` | `python3 "$CONDUCTOR_API" get-workflow --name {name} --version {v}` |
+| Create workflow | `conductor workflow create file.json` | `python3 "$CONDUCTOR_API" create-workflow --file file.json` |
+| Update workflow | `conductor workflow update file.json` | `python3 "$CONDUCTOR_API" update-workflow --file file.json` |
+| Delete workflow | `conductor workflow delete {name} {v}` | `python3 "$CONDUCTOR_API" delete-workflow --name {name} --version {v}` |
+| Start workflow | `conductor workflow start -w {name} -i '{...}'` | `python3 "$CONDUCTOR_API" start-workflow --name {name} --input '{...}'` |
+| Get execution | `conductor workflow get-execution {id} -c` | `python3 "$CONDUCTOR_API" get-execution --id {id} --include-tasks` |
+| Search executions | `conductor workflow search -s RUNNING` | `python3 "$CONDUCTOR_API" search-workflows --status RUNNING --size 20` |
+| Pause | `conductor workflow pause {id}` | `python3 "$CONDUCTOR_API" pause-workflow --id {id}` |
+| Resume | `conductor workflow resume {id}` | `python3 "$CONDUCTOR_API" resume-workflow --id {id}` |
+| Terminate | `conductor workflow terminate {id}` | `python3 "$CONDUCTOR_API" terminate-workflow --id {id} --reason "..."` |
+| Restart | `conductor workflow restart {id}` | `python3 "$CONDUCTOR_API" restart-workflow --id {id}` |
+| Retry | `conductor workflow retry {id}` | `python3 "$CONDUCTOR_API" retry-workflow --id {id}` |
+| Signal task (async) | `conductor task signal --workflow-id {id} --task-ref {ref} --status COMPLETED --output '{...}'` | `python3 "$CONDUCTOR_API" signal-task --workflow-id {id} --task-ref {ref} --status COMPLETED --output '{...}'` |
+| Signal task (sync) | `conductor task signal-sync ...` | `python3 "$CONDUCTOR_API" signal-task-sync --workflow-id {id} --task-ref {ref} --status COMPLETED --output '{...}'` |
+| Poll task | `conductor task poll {type} --count 5` | `python3 "$CONDUCTOR_API" poll-task --task-type {type} --count 5` |
+| Queue size | `conductor task queue-size --task-type {type}` | `python3 "$CONDUCTOR_API" queue-size --task-type {type}` |
+
+For anything not in the table (taskDef CRUD, schedules, secrets, etc.), the user must install the CLI.

package/skills/conductor/references/optimization.md

@@ -0,0 +1,148 @@
+# Reviewing & Optimizing Workflows
+
+When the user asks to **review**, **optimize**, **simplify**, or **audit** a workflow, walk this checklist and produce a structured report. Findings are graded:
+
+- **CRITICAL** — likely production incident waiting to happen. Recommend before next deploy.
+- **WARN** — smell or maintenance burden. Recommend, but not blocking.
+- **INFO** — observation; no fix required.
+
+Treat the checklist as guidance — not every item applies to every workflow. A 3-task batch job doesn't need a `failureWorkflow`. Use judgment.
+
+## Review flow
+
+1. Load the workflow definition. Either:
+   - User supplied a JSON file → read it.
+   - User named a registered workflow → `conductor workflow get {name} --version {v}` (omit `--version` for the latest).
+2. For each `SIMPLE` task, load its task definition: `conductor taskDef get {name}`. Timeout/retry config lives there, not on the workflow task.
+3. (Optional, if the user asks about runtime behavior) Look at recent executions: `conductor workflow search -w {name} -s FAILED -c 20` and inspect a few with `get-execution`.
+4. Walk the checklist below, recording findings.
+5. Report grouped by severity. Offer to apply each fix. Don't apply silently.
+
+## Checklist
+
+### A. Structure & maintainability
+
+- **A1. Description present.** `description` should explain what the workflow does and why. Empty descriptions force readers to reverse-engineer intent.
+  - Severity: WARN if missing.
+- **A2. ownerEmail set.** Routes alerts and identifies the on-call.
+  - Severity: WARN if missing.
+- **A3. schemaVersion: 2.** Older schemas use legacy semantics. New workflows should always be 2.
+  - Severity: WARN if missing or 1.
+- **A4. Task count.** Soft limit ~100 tasks per workflow definition. Beyond that, readability and observability degrade — extract logical chunks into `SUB_WORKFLOW`s, just like refactoring oversized functions.
+  - Severity: WARN if `len(tasks) > 100`.
+- **A5. Descriptive `taskReferenceName`.** Each ref name is unique workflow-wide and shows up in the UI/logs. Prefer `validate_order` over `task1`.
+  - Severity: INFO/WARN.
+- **A6. Understand the three timeouts.** Reference (no severity — purely educational). Each task definition has three timeout knobs and they catch different failure modes:
+  - `pollTimeoutSeconds` — task sits in the queue this long without a worker picking it up → abandoned. Catches "no worker is polling for this type."
+  - `responseTimeoutSeconds` — once a worker checks out the task, how long without a heartbeat before redelivery. Catches "worker crashed mid-execution."
+  - `timeoutSeconds` — total wall clock from pickup to terminal status. Catches "worker is alive but the task takes too long."
+
+  The severity ladder for missing/zero timeouts is **B1** below.
+- **A7. Workflow versioning hygiene.** Don't in-place update workflows that have running production executions — bump `version`, deploy callers pointing at the new version, deprecate the old when no executions remain. In-place updates can affect running executions in ways that vary by task type (especially around input expressions). New versions are free; the registry holds many.
+  - Severity: WARN if a workflow with executions in the last 30 days has been edited in place.
+
+### B. Reliability
+
+- **B1. Task timeouts on every SIMPLE task.** Each task definition needs `responseTimeoutSeconds`, `pollTimeoutSeconds`, and `timeoutSeconds`. See A6 for what each catches. Single severity ladder:
+  - **CRITICAL** if any of the three is `0` or unset on a task def for a SIMPLE task in production use.
+  - **WARN** if all three are set but one or more are clearly too low (e.g. `responseTimeoutSeconds: 1`).
+  - **INFO** if all three are set with reasonable values.
+- **B2. Workflow-level timeout.** `timeoutSeconds` + `timeoutPolicy` (`TIME_OUT_WF` or `ALERT_ONLY`). Without one, a stuck workflow can run forever.
+  - Severity: WARN by default; only INFO if the workflow legitimately has no upper bound (long-lived state machines, event-driven loops). Confirm with the user.
+- **B3. Retry policy on SIMPLE tasks.** `retryCount`, `retryLogic` (`FIXED` or `EXPONENTIAL_BACKOFF`), `retryDelaySeconds`. Transient errors are common — `retryCount: 0` exposes every blip.
+  - Severity: WARN if `retryCount == 0` and the task isn't intrinsically non-retryable.
+- **B4. `failureWorkflow` for cleanup/alerting.** Runs when the parent fails. Common pattern: send an alert, mark the entity failed in your DB, release reserved resources. Often missing.
+  - Severity: WARN if absent on workflows that mutate external state.
+- **B5. DO_WHILE iteration cap.** The `loopCondition` should always include a max-iteration guard (`$.loop_ref['iteration'] < N`) in addition to any result-driven exit. Without it, an unexpected output spins forever.
+  - Severity: CRITICAL if unbounded.
+- **B6. `optional: true` on non-critical branches.** A best-effort notification, audit log, or analytics push shouldn't fail the workflow. Mark them optional.
+  - Severity: INFO — flag candidates, don't dictate.
+- **B7. Rate limits and concurrent-exec limits on task defs.** Two related throttling levers, often both missing:
+  - `rateLimitPerFrequency` + `rateLimitFrequencyInSeconds` — token-bucket rate limit. Use for tasks calling external APIs with quotas (Stripe, Slack, third-party LLMs). Without this, a spike in workflow starts blows your quota.
+  - `concurrentExecLimit` — caps simultaneous executions of this task across all workflows. Use for resource-bound tasks: heavy DB writes, GPU-bound model calls, memory-hungry transforms.
+  - Severity: WARN on tasks calling external rate-limited APIs without `rateLimitPerFrequency`. WARN on resource-bound tasks without `concurrentExecLimit`.
+
+### C. Performance & complexity
+
+- **C1. INLINE/graaljs scope.** JavaScript inline is for trivial validation, format conversion, simple computation. Anything with business logic — multi-step transforms, external dependencies, side effects — belongs in a worker.
+  - Heuristic: INLINE script over ~15 lines, or one that's hard to follow at a glance, is a smell.
+  - Severity: WARN.
+- **C2. Prefer `JSON_JQ_TRANSFORM` for data shaping.** JQ is purpose-built and faster than INLINE for filter/map/aggregate. INLINE makes sense for control flow or arithmetic; JQ for shape transforms.
+  - Severity: INFO.
+- **C3. Bounded fan-out.** Static `FORK_JOIN` with > ~20 branches is a smell — switch to `FORK_JOIN_DYNAMIC`. Dynamic fork with thousands of branches needs batching (chunk inputs, run sub-workflows of size ~50).
+  - Severity: WARN at high static counts; CRITICAL at unbounded dynamic counts without batching.
+- **C4. `asyncComplete: true` for long-running operations.** Worker initiates external work, returns immediately, then signals completion later. Avoids holding worker threads for hours.
+  - Severity: INFO.
+- **C5. SUB_WORKFLOW for reuse, not organization.** Each sub-workflow has its own execution context, separate UI view, and orchestration overhead. Worth it when:
+  - the same logic is reused across multiple parents, OR
+  - the chunk is independently scheduled or testable.
+
+  Don't extract a sub-workflow just to "organize" a long workflow into chapters — that's what naming and the description field are for. The cost is real: debugging a single failure now spans two execution views.
+  - Severity: WARN if a SUB_WORKFLOW is used by exactly one parent and isn't independently scheduled.
+
+### D. Security & inputs
+
+- **D1. No secrets in workflow input.** Tokens, API keys, signing secrets must come from the secrets system (`${workflow.secrets.X}` on Orkes) or worker environment variables — never `${workflow.input.token}`. Workflow inputs are visible in the execution view.
+  - Severity: CRITICAL if a real secret is being passed via input.
+- **D2. No hardcoded URLs / config in task definitions.** Parameterize via `${workflow.input.x}` or `${workflow.variables.x}` — environment-specific URLs hardcoded into a definition mean a separate definition per environment.
+  - Severity: WARN.
+- **D3. `outputParameters` is a public API.** Other workflows, services, and dashboards depend on the workflow's output shape. Treat changes the way you'd treat function-signature changes: additions are usually safe, removals and renames are breaking. Bump `version` on breaking output changes; never reshape outputs in place.
+  - Severity: WARN if a workflow with active consumers had outputs renamed or removed in place.
+
+### E. Wrong tool
+
+Sometimes the right answer is *not a workflow*. Smell tests:
+
+- **E1. Sub-100ms latency-critical paths.** Workflow start has measurable overhead (queue write, definition load, dispatch). If a user is waiting synchronously, prefer a direct call.
+- **E2. Single-task "workflows."** A workflow with one HTTP task is a queue with extra steps. Use a queue, scheduled worker, or just a function call.
+- **E3. Large payloads in inputs/outputs.** Conductor has practical limits — typically a few MB before perf degrades and the UI struggles. Push blobs (uploaded files, large model outputs, dataset rows) to object storage and let the workflow carry only references (`{ "bucket": "...", "key": "..." }`).
+  - Severity: WARN/CRITICAL depending on actual payload size and frequency.
+
+## Report template
+
+Render findings like this:
+
+```
+Workflow: order_processing v3 (47 tasks)
+
+CRITICAL (3)
+  ✗ B1  SIMPLE task `charge_card`: responseTimeoutSeconds=0
+        → Set responseTimeoutSeconds >= 30, pollTimeoutSeconds >= 60, timeoutSeconds = 300
+  ✗ B5  DO_WHILE `retry_loop`: condition has no iteration cap
+        → Add `$.retry_loop['iteration'] < 10 &&` to loopCondition
+  ✗ D1  Workflow input `stripeKey` looks like a secret
+        → Move to ${workflow.secrets.STRIPE_KEY} or worker env
+
+WARN (4)
+  ⚠ A1  Description is empty
+  ⚠ B2  No workflow timeout. Add timeoutSeconds + timeoutPolicy.
+  ⚠ B3  SIMPLE task `send_email` has retryCount=0 (transient SMTP errors will fail the workflow)
+  ⚠ C1  INLINE task `compute_pricing` has 60 lines of JS — extract to a worker
+
+INFO (2)
+  • A4  47 tasks — well within the 100-task soft limit
+  • A5  Task names are descriptive
+
+Recommended Changes (priority order)
+  [ ] task_def_charge_card.json  set responseTimeoutSeconds=30, pollTimeoutSeconds=60, timeoutSeconds=300
+  [ ] order_processing.json:7    add `$.retry_loop['iteration'] < 10` clause to loopCondition
+  [ ] order_processing.json:2    move stripeKey to ${workflow.secrets.STRIPE_KEY}
+  [ ] order_processing.json:1    add description, timeoutSeconds, timeoutPolicy
+  [ ] task_def_send_email.json   set retryCount=3, retryLogic=EXPONENTIAL_BACKOFF
+  [ ] compute_pricing INLINE     extract to a Python worker
+```
+
+Then offer: *"Want me to apply any of these? I can update the task definitions and re-register the workflow."*
+
+**Always end with a `Recommended Changes` checklist** even if the findings are split by severity above. The checklist is the actionable artifact the user takes away — one bullet per fix, file/path pointer first, then the change to make. Skip findings that are INFO-only.
+
+## When the user just says "make it simpler"
+
+A simpler workflow is one a new engineer can read in five minutes. The biggest levers:
+
+1. **Extract sub-workflows.** Group related tasks (validate-and-prep, fulfill, notify) into separate registered workflows.
+2. **Replace INLINE business logic with workers.** A worker has a name, version, tests, and a stack trace; INLINE has none of those.
+3. **Flatten nested SWITCHes.** Two-level decision trees are usually a sign that one level should be a sub-workflow.
+4. **Name things.** Every task ref name and variable should read as English.
+
+Don't over-refactor. If the workflow is already small and readable, "simpler" might be a no-op — say so.

package/skills/conductor/references/orkes.md

@@ -0,0 +1,57 @@
+# Orkes Enterprise Features
+
+Secrets and webhooks require Orkes Conductor (orkes.io). They are unavailable on plain OSS Conductor and on the Python fallback script.
+
+> Schedules used to live here — they're now part of OSS. See [schedules.md](schedules.md).
+
+Auth is the same as the rest of the CLI — see [setup.md](setup.md) (key/secret recommended).
+
+## Secrets
+
+Securely store values referenced from workflows (e.g. API keys). Reference in tasks via `${workflow.secrets.MY_KEY}`.
+
+```bash
+conductor secret list
+conductor secret get {key}
+conductor secret put {key} {value}
+conductor secret delete {key}
+```
+
+**Important: secret values are resolved server-side at task execution time**, not by the agent, the CLI, or the workflow definition. The reference `${workflow.secrets.MY_KEY}` lives in the workflow JSON; the actual value is substituted by the Conductor server when the task runs. This means:
+
+- The plaintext secret never appears in the workflow definition, the execution view, or any agent transcript.
+- Rotating a secret on the server affects every running and future workflow without redeploying any definition.
+- Workers and HTTP tasks receive the substituted value at runtime via task inputs.
+
+Never echo secret values in agent output. After `put`, confirm with name only (e.g. via `conductor secret list`).
+
+## Webhooks
+
+Trigger workflows from external HTTP callbacks (Stripe, GitHub, custom services).
+
+```bash
+conductor webhook list
+conductor webhook get {name}
+conductor webhook create webhook.json
+conductor webhook update webhook.json
+conductor webhook delete {name}
+```
+
+Example `webhook.json`:
+
+```json
+{
+  "name": "github-pr-events",
+  "verifier": "HEADER_BASED",
+  "headers": { "X-Hub-Signature-256": "${secrets.GITHUB_WEBHOOK_SIG}" },
+  "receiverWorkflowNamesToVersions": { "github_pr_handler": 1 },
+  "sourcePlatform": "Custom"
+}
+```
+
+After creation the CLI returns a webhook URL — give that to the user (don't fabricate one).
+
+## Notes
+
+- Enterprise commands fail on OSS Conductor with a `404` or `Not Found`. If the user hits this, confirm they're pointed at an Orkes server.
+- For dev against Orkes, [developer.orkescloud.com](https://developer.orkescloud.com) is the public developer sandbox.