@conductor-oss/conductor-skills 1.4.2

package/skills/conductor/references/schedules.md

@@ -0,0 +1,81 @@
+# Schedules
+
+Run a workflow on a cron schedule. Schedules are part of OSS Conductor.
+
+## CLI
+
+```bash
+conductor schedule list
+conductor schedule get {name}
+conductor schedule create schedule.json
+conductor schedule update schedule.json
+conductor schedule delete {name}
+conductor schedule pause {name}
+conductor schedule resume {name}
+```
+
+The Python fallback script does **not** include schedule commands — the CLI is required.
+
+## Schedule definition
+
+Write the schedule to a JSON file, then `conductor schedule create file.json`.
+
+```json
+{
+  "name": "nightly-cleanup",
+  "cronExpression": "0 0 2 * * ?",
+  "startWorkflowRequest": {
+    "name": "cleanup_workflow",
+    "version": 1,
+    "input": { "olderThanDays": 30 },
+    "correlationId": "scheduled-${date}"
+  },
+  "scheduleStartTime": 0,
+  "scheduleEndTime": 0,
+  "paused": false
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | yes | Unique schedule name |
+| `cronExpression` | string | yes | Quartz cron (6 or 7 fields, see below) |
+| `startWorkflowRequest` | object | yes | The workflow to start each tick |
+| `scheduleStartTime` | long | no | Epoch ms; `0` = no start bound |
+| `scheduleEndTime` | long | no | Epoch ms; `0` = no end bound |
+| `paused` | boolean | no | If true, schedule exists but does not fire |
+| `description` | string | no | Human description |
+
+`startWorkflowRequest` mirrors `POST /workflow`: `name`, `version`, `input`, `correlationId`, `taskToDomain`.
+
+## Cron expression format
+
+Quartz cron — 6 fields (no year) or 7 fields (with year):
+
+```
+seconds  minutes  hours  day-of-month  month  day-of-week  [year]
+```
+
+| Pattern | Meaning |
+|---------|---------|
+| `0 0 * * * ?` | Every hour, on the hour |
+| `0 0 2 * * ?` | Every day at 02:00 |
+| `0 30 9 ? * MON-FRI` | Weekdays at 09:30 |
+| `0 0 0 1 * ?` | First of every month, midnight |
+| `0 */15 * * * ?` | Every 15 minutes |
+
+Either day-of-month or day-of-week must be `?` (Quartz quirk — they can't both be specified). Cron is evaluated in the server's timezone unless you configure otherwise.
+
+## Patterns
+
+**Idempotency.** Use a derived `correlationId` (e.g. `nightly-cleanup-${date}`) so a schedule that double-fires won't create duplicate work — your workflow can detect the existing run and short-circuit.
+
+**Pausing without deleting.** Set `paused: true` and update — preserves history vs delete.
+
+**Ad-hoc backfill.** To run the scheduled workflow immediately for a missed window, just `conductor workflow start -w {name} -i '{...}'` — the schedule is just a trigger, not the workflow.
+
+**Monitoring.** Schedules don't have their own execution history. Search executions by `correlationId` prefix to find scheduled runs:
+
+```bash
+conductor workflow search -q "correlationId:scheduled-*" -c 50
+```

package/skills/conductor/references/setup.md

@@ -0,0 +1,126 @@
+# Server Setup
+
+Connect the agent to a Conductor server. Run through this once per environment.
+
+## Server resolution order
+
+`--profile` > `CONDUCTOR_SERVER_URL` > CLI auto-detection of a local server started via `conductor server start`.
+
+Most commands need no flags — the CLI finds the server automatically. Only append `--profile {env}` when the user mentions a named environment (dev, qa, prod, staging, uat). If unsure which profile exists, read `~/.conductor-cli/config.yaml` and ask the user to confirm. Only create named profiles when the user explicitly wants to switch between multiple environments.
+
+The Python fallback script (`scripts/conductor_api.py`) does **not** auto-detect — it requires `CONDUCTOR_SERVER_URL` to be set explicitly.
+
+## Step 1 — Install the CLI
+
+Check whether `conductor` is already installed:
+
+```bash
+conductor --version
+```
+
+If not installed, check for npm/Node.js:
+
+```bash
+npm --version
+```
+
+If npm is also missing, install Node.js first:
+
+```bash
+# macOS
+brew install node
+# Linux (Debian/Ubuntu)
+curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs
+```
+
+For installing the CLI itself, two options:
+
+- **Recommended (no global install):** invoke as `npx @conductor-oss/conductor-cli ...` for one-off use. No system modification.
+- **Global install (ask the user first):** `npm install -g @conductor-oss/conductor-cli`. Modifies the global npm prefix — confirm before running. Once approved, verify with `conductor --version`.
+
+**Fallback** — only after the CLI is genuinely unavailable (`conductor --version` fails) **and** Node/npm cannot be installed (restricted environment, no package manager), fall back to the bundled REST API script:
+
+```bash
+export CONDUCTOR_API="<path-to-this-skill>/scripts/conductor_api.py"
+```
+
+The fallback supports a subset of CLI commands — see [fallback-cli.md](fallback-cli.md). It does not support key/secret auth (token only), profiles, server auto-detection, taskDef CRUD, or time-range search.
+
+## Step 2 — Choose a server
+
+Ask the user:
+
+- **Option A** — Start a local server (good for development/testing).
+- **Option B** — Connect to an existing remote server.
+
+Don't assume — present both.
+
+**Option A — local server:**
+
+```bash
+conductor server start
+# custom port:
+conductor server start --port 3000
+# verify:
+conductor server status
+```
+
+**Option B — existing server:**
+
+```bash
+export CONDUCTOR_SERVER_URL="http://your-server:8080/api"
+```
+
+## Step 3 — Test connectivity and handle auth
+
+```bash
+conductor workflow list
+```
+
+If this succeeds, the server has no auth — go to Step 4.
+
+If you get **401 or 403**, the server requires authentication. Only then ask the user for credentials. Set them via env vars (never echo the values):
+
+```bash
+# Key + Secret (recommended for Orkes / Enterprise)
+export CONDUCTOR_AUTH_KEY="<ask user>"
+export CONDUCTOR_AUTH_SECRET="<ask user>"
+
+# Or a pre-existing token
+export CONDUCTOR_AUTH_TOKEN="<ask user>"
+```
+
+Re-test: `conductor workflow list`
+
+> **Auth header:** the REST API expects `X-Authorization: <token>`. The CLI handles this automatically. If using the Python fallback, only `CONDUCTOR_AUTH_TOKEN` is supported — key/secret exchange is not implemented.
+
+## Step 4 — Verify
+
+```bash
+conductor workflow list
+```
+
+Report the result to the user. Setup complete.
+
+## Optional — named profiles
+
+For switching between multiple servers (dev / staging / prod):
+
+```bash
+conductor config save --server https://dev.example.com/api  --auth-key KEY --auth-secret SECRET --profile dev
+conductor config save --server https://prod.example.com/api --auth-key KEY --auth-secret SECRET --profile prod
+```
+
+Then append `--profile {env}` on any command. Profiles live in `~/.conductor-cli/config.yaml`.
+
+## Updating this skill
+
+If the user asks to upgrade or you suspect this skill is outdated:
+
+```bash
+# macOS / Linux
+curl -sSL https://conductor-oss.github.io/conductor-skills/install.sh | bash -s -- --all --upgrade
+
+# Windows
+irm https://conductor-oss.github.io/conductor-skills/install.ps1 -OutFile install.ps1; .\install.ps1 -All -Upgrade
+```

package/skills/conductor/references/troubleshooting.md

@@ -0,0 +1,35 @@
+# Troubleshooting & Output
+
+## Output formatting
+
+- Present workflow data as structured summaries: `workflowId`, `status`, `startTime`, `endTime`, failed-task details.
+- For searches, render a table with `workflowId`, `name`, `status`, `startTime`.
+- On failures, include the failed task name, error message, and retry count.
+- Never echo auth tokens, keys, or secrets in output or logs.
+
+## Common errors
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| `conductor: command not found` | CLI not installed | Run `npx @conductor-oss/conductor-cli ...`, or ask the user before global install (see [setup.md](setup.md)). If npm itself is missing, fall back to `scripts/conductor_api.py`. |
+| `Connection refused` / `URLError` | Server not running, or wrong URL | Verify `CONDUCTOR_SERVER_URL`. For local servers run `conductor server status`. |
+| `401 Unauthorized` | Missing or invalid auth | Check `CONDUCTOR_AUTH_TOKEN` (or `CONDUCTOR_AUTH_KEY` + `_SECRET` with the CLI). Re-run `conductor workflow list` to confirm. |
+| `403 Forbidden` | Token valid but lacks permissions | Confirm with the user that the credentials have access to the target workflow/namespace. |
+| `404 Not Found` | Wrong workflow name, version, or execution ID | Run `conductor workflow list` or `conductor workflow search` to find the correct identifier. |
+| Workflow stuck on a SIMPLE task | No worker polling for that task type | Run `conductor task queue-size --task-type {name}` — if size > 0 and growing, no worker is consuming. Scaffold a worker (see [workers.md](workers.md)). |
+| `409 Conflict` on workflow create | Definition with that name+version already exists | Bump version, or use update instead of create. |
+| 5xx errors | Server-side issue | The fallback script auto-retries 3× with backoff. CLI may need a manual retry. Surface server error to the user. |
+
+## Diagnosis flow for failed workflows
+
+1. `conductor workflow get-execution {id} -c` — full task list with statuses.
+2. Identify the failed task (`status: FAILED` or `TIMED_OUT`) and its `reasonForIncompletion`.
+3. Decide:
+   - `TIMED_OUT` with retries remaining → `conductor workflow retry {id}`.
+   - `FAILED_WITH_TERMINAL_ERROR` → not retryable; fix root cause first.
+   - Persistent timeouts → recommend raising `responseTimeoutSeconds` on the task definition.
+
+## Docs
+
+- General Conductor docs: https://orkes.io/content/
+- REST endpoints: see [api-reference.md](api-reference.md)

package/skills/conductor/references/visualization.md

@@ -0,0 +1,49 @@
+# Workflow Visualization
+
+Generate a Mermaid flowchart when the user asks to visualize a workflow, or after creating one. Renders in any Markdown viewer (GitHub, VS Code, etc.).
+
+Always pair the diagram with a **1–2 sentence text summary of the flow** ("Fetches data, then either notifies on success or terminates on failure"). The summary helps users skim and is the accessibility fallback for screen readers and any environment that doesn't render Mermaid.
+
+## Diagram rules
+
+- Use `flowchart TD` for sequential workflows, `flowchart LR` for wide parallel flows.
+- Only use `-->` arrows and `-->|label|` for labeled edges.
+- Do **not** use `title`, `style`, or `classDef`.
+- In **edge label text** (between `|...|`), avoid `{}[]()` — they break Mermaid parsing. Node shapes (`[]`, `()`, `{}`) are fine; just keep the text inside short.
+- Keep node labels short: task type + reference name, e.g. `fetch_data[HTTP: fetch_data]`.
+
+## Mapping Conductor constructs
+
+| Construct | Mermaid pattern |
+|-----------|-----------------|
+| Sequential tasks | `task1 --> task2 --> task3` |
+| SWITCH (decision) | `sw{Switch: ref}` with `-->|case: value|` edges per case + `-->|default|` |
+| FORK_JOIN (parallel) | `fork[Fork] --> branch_a & branch_b` then both `--> join[Join]` |
+| DO_WHILE (loop) | `loop[DO_WHILE: ref] --> body --> loop` with `body -->|done| next` |
+| SUB_WORKFLOW | `sub([Sub: workflow_name])` rounded node |
+| WAIT / HUMAN | `wait[/WAIT: ref/]` parallelogram (signals external input) |
+
+## Example
+
+````markdown
+```mermaid
+flowchart TD
+  start([Start]) --> fetch[HTTP: fetch_data]
+  fetch --> check{Switch: check_status}
+  check -->|case: ok| transform[INLINE: transform]
+  check -->|default| fail[TERMINATE: fail]
+  transform --> approve[/WAIT: approval/]
+  approve --> notify[HTTP: send_notification]
+  notify --> done([End])
+```
+````
+
+## Conductor UI link
+
+If a Conductor server is reachable, also offer a link to the visual editor:
+
+```
+{BASE_URL}/workflowDef/{workflowName}
+```
+
+Where `BASE_URL` is `CONDUCTOR_SERVER_URL` with the trailing `/api` stripped. Example: `http://localhost:8080/api` → `http://localhost:8080/workflowDef/order-processing`. Always resolve the actual URL — never output `{SERVER_UI_URL}` literally.

package/skills/conductor/references/workers.md

@@ -0,0 +1,227 @@
+# Writing Conductor Workers
+
+Workers execute SIMPLE tasks in a workflow. They poll the Conductor server for tasks, execute business logic, and report results back. Workers are stateless and idempotent.
+
+## How workers work
+
+1. Workflow reaches a SIMPLE task
+2. Task is placed in a queue
+3. Worker polls the queue, picks up the task
+4. Worker executes logic using task's `inputData`
+5. Worker returns result (COMPLETED or FAILED) with `outputData`
+6. Workflow continues to the next task
+
+## SDKs
+
+| Language | Package | Install |
+|----------|---------|---------|
+| Python | `conductor-python` | `pip install conductor-python` |
+| JavaScript/TypeScript | `@io-orkes/conductor-javascript` | `npm install @io-orkes/conductor-javascript` |
+| Java | `org.conductoross:conductor-client` | Maven/Gradle (see below) |
+| Go | `github.com/conductor-sdk/conductor-go` | `go get github.com/conductor-sdk/conductor-go` |
+| C# | [conductor-oss/csharp-sdk](https://github.com/conductor-oss/csharp-sdk) | NuGet |
+| Ruby | [conductor-oss/ruby-sdk](https://github.com/conductor-oss/ruby-sdk) | Gem |
+| Rust | [conductor-oss/rust-sdk](https://github.com/conductor-oss/rust-sdk) | Cargo |
+
+All SDKs connect via the same env vars: `CONDUCTOR_SERVER_URL`, `CONDUCTOR_AUTH_KEY`, `CONDUCTOR_AUTH_SECRET`.
+
+---
+
+## Python
+
+```bash
+pip install conductor-python
+```
+
+### Define a worker
+
+```python
+from conductor.client.worker.worker_task import worker_task
+
+@worker_task(task_definition_name='process_order')
+def process_order(order_id: str, amount: float) -> dict:
+    # Your business logic here
+    return {'status': 'processed', 'order_id': order_id, 'total': amount * 1.1}
+```
+
+Function parameters are automatically mapped from the task's `inputParameters`. The return value becomes the task's `outputData`.
+
+### Start workers
+
+```python
+from conductor.client.automator.task_handler import TaskHandler
+from conductor.client.configuration.configuration import Configuration
+
+config = Configuration()  # reads CONDUCTOR_SERVER_URL, CONDUCTOR_AUTH_KEY, CONDUCTOR_AUTH_SECRET
+with TaskHandler(configuration=config, scan_for_annotated_workers=True) as handler:
+    handler.start_processes()
+    # Workers poll until stopped
+```
+
+---
+
+## JavaScript / TypeScript
+
+```bash
+npm install @io-orkes/conductor-javascript
+```
+
+### Define and run a worker
+
+```typescript
+import {
+  orkesConductorClient,
+  TaskManager,
+} from "@io-orkes/conductor-javascript";
+
+const client = await orkesConductorClient({
+  serverUrl: "http://localhost:8080/api",
+});
+
+const taskManager = new TaskManager(client, [
+  {
+    taskType: "process_order",
+    execute: async ({ inputData }) => {
+      return {
+        status: "COMPLETED",
+        outputData: {
+          status: "processed",
+          order_id: inputData.order_id,
+        },
+      };
+    },
+  },
+]);
+
+taskManager.startPolling();
+```
+
+---
+
+## Java
+
+**Gradle:**
+```gradle
+implementation 'org.conductoross:conductor-client:5.0.0'
+```
+
+**Maven:**
+```xml
+<dependency>
+    <groupId>org.conductoross</groupId>
+    <artifactId>conductor-client</artifactId>
+    <version>5.0.0</version>
+</dependency>
+```
+
+### Option A: Implement Worker interface
+
+```java
+public class ProcessOrderWorker implements Worker {
+    @Override
+    public String getTaskDefName() {
+        return "process_order";
+    }
+
+    @Override
+    public TaskResult execute(Task task) {
+        String orderId = (String) task.getInputData().get("order_id");
+        TaskResult result = new TaskResult(task);
+        result.setStatus(TaskResult.Status.COMPLETED);
+        result.addOutputData("status", "processed");
+        result.addOutputData("order_id", orderId);
+        return result;
+    }
+}
+```
+
+### Option B: @WorkerTask annotation
+
+```java
+public class Workers {
+    @WorkerTask("process_order")
+    public Map<String, Object> processOrder(@InputParam("order_id") String orderId) {
+        return Map.of("status", "processed", "order_id", orderId);
+    }
+}
+```
+
+### Start workers
+
+```java
+ConductorClient client = ConductorClient.builder()
+    .basePath("http://localhost:8080/api")
+    .build();
+
+TaskClient taskClient = new TaskClient(client);
+new TaskRunnerConfigurer.Builder(taskClient, List.of(new ProcessOrderWorker()))
+    .withThreadCount(10)
+    .build()
+    .init();
+```
+
+---
+
+## Go
+
+```bash
+go get github.com/conductor-sdk/conductor-go
+```
+
+### Define and run a worker
+
+```go
+package main
+
+import (
+    "fmt"
+    "time"
+    "github.com/conductor-sdk/conductor-go/sdk/client"
+    "github.com/conductor-sdk/conductor-go/sdk/model"
+    "github.com/conductor-sdk/conductor-go/sdk/worker"
+)
+
+func ProcessOrder(task *model.Task) (interface{}, error) {
+    orderId := fmt.Sprintf("%v", task.InputData["order_id"])
+    return map[string]interface{}{
+        "status":   "processed",
+        "order_id": orderId,
+    }, nil
+}
+
+func main() {
+    apiClient := client.NewAPIClientFromEnv()
+    taskRunner := worker.NewTaskRunnerWithApiClient(apiClient)
+    taskRunner.StartWorker("process_order", ProcessOrder, 1, time.Millisecond*100)
+    // Blocks and polls until stopped
+    select {}
+}
+```
+
+---
+
+## Linking workers to workflows
+
+In your workflow definition, use `"type": "SIMPLE"` and set `"name"` to the task type your worker polls for:
+
+```json
+{
+  "name": "process_order",
+  "taskReferenceName": "process_order_ref",
+  "type": "SIMPLE",
+  "inputParameters": {
+    "order_id": "${workflow.input.order_id}",
+    "amount": "${workflow.input.amount}"
+  }
+}
+```
+
+The worker registered for task type `process_order` will automatically pick up this task when the workflow reaches it.
+
+## Best practices
+
+- **Idempotent**: Workers may receive the same task on retry. Design for safe re-execution.
+- **Timeouts**: Set `responseTimeoutSeconds` on task definitions so stuck tasks get rescheduled.
+- **Error handling**: Return `FAILED` status with a `reasonForIncompletion` message for graceful failures. Return `FAILED_WITH_TERMINAL_ERROR` to fail the task without retrying.
+- **Scaling**: Run multiple worker instances for throughput. Each polls independently.
+- **Domain isolation**: Use task domains to route tasks to specific worker groups (e.g. region-specific workers).