diff --git a/.claude/skills/conductor/SKILL.md b/.claude/skills/conductor/SKILL.md index f53762d..fb71f5b 100644 --- a/.claude/skills/conductor/SKILL.md +++ b/.claude/skills/conductor/SKILL.md @@ -1,12 +1,25 @@ --- name: conductor -description: Create, validate, and run workflows. Use when orchestrating AI agents via YAML workflow files, creating new workflows, debugging execution, configuring routing between agents, setting up human-in-the-loop gates, or understanding workflow YAML schema. +description: Validate, run, and execute workflows; creating new workflows when explicitly asked. Use when orchestrating AI agents via YAML workflow files, executing an existing workflow, debugging execution, configuring routing between agents, setting up human-in-the-loop gates, or understanding workflow YAML schema. Only create new workflows when explicitly asked. --- # Conductor CLI tool for defining and running multi-agent workflows with the GitHub Copilot SDK or Anthropic Claude. +> **DO NOT create new workflow files unless the user explicitly asks you to create one.** Default to running, validating, or debugging existing workflows. If the user's request is ambiguous, assume they want to run or modify an existing workflow rather than create a new one. + +## Error Handling + +> **CRITICAL — do NOT improvise workarounds.** If `conductor` fails for any reason (installation failure, provider error, missing dependency, platform bug), you MUST: +> +> 1. **Report the exact error** to the user — include the full error message. +> 2. **Stop and wait for user direction.** Do NOT attempt to simulate, replicate, or approximate the multi-agent workflow yourself. The value of this skill is the structured multi-agent orchestration — a single-agent attempt is not an equivalent substitute. + +## Setup + +Conductor is installed automatically when needed. If a `conductor` command fails with "command not found", install it. For installation instructions, see [references/setup.md](references/setup.md). + ## Quick Reference ```bash @@ -49,40 +62,29 @@ Full output is shown by default. Use `-q` (quiet) for minimal output or `-s` (si - Validation rules - Type definitions -## Workflow Structure Overview +## Minimal Workflow Example ```yaml workflow: name: my-workflow - entry_point: first_agent - runtime: - provider: copilot # or claude - default_model: gpt-5.2 - temperature: 0.7 + entry_point: answerer input: - question: - type: string - context: - mode: accumulate # accumulate, last_only, explicit - limits: - max_iterations: 10 - cost: - show_summary: true + question: { type: string } agents: - - name: first_agent - prompt: | - Answer: {{ workflow.input.question }} + - name: answerer + prompt: "Answer: {{ workflow.input.question }}" output: - answer: - type: string + answer: { type: string } routes: - to: $end output: - answer: "{{ first_agent.output.answer }}" + answer: "{{ answerer.output.answer }}" ``` +For runtime config, context modes, limits, and cost tracking, see [references/authoring.md](references/authoring.md). + ## Key Concepts | Concept | Description | @@ -101,108 +103,4 @@ output: | `--web` | Real-time web dashboard with DAG graph, live streaming, in-browser human gates | | `checkpoint` | Auto-saved on failure; resume with `conductor resume` | -## Common Patterns - -**Linear pipeline**: `agent1 → agent2 → agent3 → $end` - -**Loop until quality**: -```yaml -routes: - - to: $end - when: "{{ output.score >= 90 }}" - - to: self -``` - -**Conditional branching**: -```yaml -routes: - - to: success_path - when: "{{ output.approved }}" - - to: failure_path -``` - -**Parallel execution**: -```yaml -parallel: - - name: researchers - agents: [web_researcher, academic_researcher] - failure_mode: continue_on_error - routes: - - to: synthesizer -``` - -**For-each (dynamic parallel)**: -```yaml -for_each: - - name: processors - type: for_each - source: finder.output.topics - as: item - max_concurrent: 5 - agent: - prompt: "Process {{ item }} (index: {{ _index }})" - output: - result: { type: string } - routes: - - to: aggregator -``` - -**Script step** (shell command): -```yaml -agents: - - name: check_version - type: script - command: python3 - args: ["--version"] - routes: - - to: analyzer - when: "exit_code == 0" - - to: error_handler -``` - -**File include** (`!file` tag): -```yaml -agents: - - name: analyzer - system_prompt: !file prompts/system.md - prompt: !file prompts/analyze.md -``` - -**Human gate**: -```yaml -- name: review - type: human_gate - prompt: "Review: {{ designer.output.summary }}" - options: - - label: Approve - value: approved - route: $end - - label: Revise - value: changes - route: designer - prompt_for: feedback -``` - -## Template Variables (Jinja2) - -```jinja2 -{{ workflow.input.param }} # Input parameter -{{ workflow.name }} # Workflow name -{{ agent_name.output.field }} # Agent output -{{ output.field }} # Current output (in routes) -{{ group.outputs.agent.field }} # Parallel group outputs -{{ group.outputs[0].field }} # For-each outputs (index) -{{ group.outputs["key"].field }} # For-each outputs (key_by) -{% if agent is defined %}...{% endif %} # Conditional -{% for item in list %}...{% endfor %} # Loop -{{ value | default("fallback") }} # Filter -``` - -## Providers - -| Provider | Auth | MCP Support | -|----------|------|-------------| -| `copilot` | `GITHUB_TOKEN` | ✅ Full | -| `claude` | `ANTHROPIC_API_KEY` | ✅ Full | - -Per-agent provider override: `provider: claude` on any agent definition for multi-provider workflows. +For pattern examples (linear, loop, conditional, parallel, for-each, human gate) and template syntax, see [references/authoring.md](references/authoring.md). diff --git a/.claude/skills/conductor/references/execution.md b/.claude/skills/conductor/references/execution.md index d148d60..88e78e9 100644 --- a/.claude/skills/conductor/references/execution.md +++ b/.claude/skills/conductor/references/execution.md @@ -120,12 +120,7 @@ The command: If already up to date, prints a confirmation message and exits. -**Examples:** - -```bash -# Check for updates and install if available -conductor update -``` +**Passive update hints:** On every CLI invocation, Conductor checks for updates (cached 24 hours, 2-second timeout) and prints a one-line hint if a newer version is available. Hints only appear when stderr is a TTY and `--silent` is not set. ### conductor resume @@ -337,7 +332,7 @@ conductor stop conductor validate workflow.yaml ``` -Catch configuration errors before execution. Reports agent count, parallel groups, for-each groups, human gates, and more. +Catch configuration errors before execution of new workflows. Reports agent count, parallel groups, for-each groups, human gates, and more. ### Check Exit Codes @@ -444,6 +439,44 @@ conductor run workflow.yaml --skip-gates Auto-selects the first option at each gate. +## Interactive Interrupt + +During execution, press **Esc** or **Ctrl+G** to pause the workflow. An interactive menu appears with these actions: + +| Action | Description | +|--------|-------------| +| **Continue with guidance** | Provide text guidance that is appended to subsequent agent prompts | +| **Skip to agent** | Jump to a specific agent in the workflow | +| **Stop** | Stop the workflow entirely | +| **Cancel** | Resume execution as-is | + +Guidance text accumulates across multiple interrupts and is injected into agent context. + +Disable with `--no-interactive`. In `--skip-gates` mode, interrupts auto-cancel. + +## Checkpoint & Resume + +When a workflow fails, Conductor automatically saves a checkpoint containing: +- All completed agent outputs +- Current workflow state and iteration count +- Workflow file hash (to detect changes) +- Failure details (agent, error type, message) + +Checkpoints are stored in `$TMPDIR/conductor/checkpoints/`. + +```bash +# List available checkpoints +conductor checkpoints + +# Resume from latest checkpoint for a workflow +conductor resume workflow.yaml + +# Resume from a specific checkpoint file +conductor resume --from /tmp/conductor/checkpoints/my-workflow-20260303-153000.json +``` + +If the workflow file has changed since the checkpoint was saved, a warning is displayed but resumption proceeds. + ## Provider Configuration ### Override Provider @@ -515,46 +548,7 @@ Environment variables in YAML configs support `${VAR}` and `${VAR:-default}` int 3. [ ] Verify entry_point exists as an agent, parallel group, or for-each group 4. [ ] Ensure all paths lead to `$end` 5. [ ] Test with `--dry-run` first -6. [ ] Use `-V` to trace execution with full details -7. [ ] Check template variables are defined before use -8. [ ] Verify for-each `source` resolves to an array -9. [ ] Check parallel groups have 2+ agents -10. [ ] Review cost output for unexpected token usage - -## Interactive Interrupt - -During execution, press **Esc** or **Ctrl+G** to pause the workflow. An interactive menu appears with these actions: - -| Action | Description | -|--------|-------------| -| **Continue with guidance** | Provide text guidance that is appended to subsequent agent prompts | -| **Skip to agent** | Jump to a specific agent in the workflow | -| **Stop** | Stop the workflow entirely | -| **Cancel** | Resume execution as-is | - -Guidance text accumulates across multiple interrupts and is injected into agent context. - -Disable with `--no-interactive`. In `--skip-gates` mode, interrupts auto-cancel. - -## Checkpoint & Resume - -When a workflow fails, Conductor automatically saves a checkpoint containing: -- All completed agent outputs -- Current workflow state and iteration count -- Workflow file hash (to detect changes) -- Failure details (agent, error type, message) - -Checkpoints are stored in `$TMPDIR/conductor/checkpoints/`. - -```bash -# List available checkpoints -conductor checkpoints - -# Resume from latest checkpoint for a workflow -conductor resume workflow.yaml - -# Resume from a specific checkpoint file -conductor resume --from /tmp/conductor/checkpoints/my-workflow-20260303-153000.json -``` - -If the workflow file has changed since the checkpoint was saved, a warning is displayed but resumption proceeds. +6. [ ] Check template variables are defined before use +7. [ ] Verify for-each `source` resolves to an array +8. [ ] Check parallel groups have 2+ agents +9. [ ] Review cost output for unexpected token usage diff --git a/.claude/skills/conductor/references/setup.md b/.claude/skills/conductor/references/setup.md new file mode 100644 index 0000000..6286010 --- /dev/null +++ b/.claude/skills/conductor/references/setup.md @@ -0,0 +1,18 @@ +# Conductor Setup + +## Installation + +Conductor does not need to be checked before every use. Simply run `conductor` commands directly. If the command fails with "command not found", install it: + +```bash +uv tool install --locked git+https://github.com/microsoft/conductor.git +``` + +If `uv` is also not available, install it first: + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +After installation, retry the original `conductor` command. + diff --git a/src/conductor/cli/app.py b/src/conductor/cli/app.py index e9db085..4fb0582 100644 --- a/src/conductor/cli/app.py +++ b/src/conductor/cli/app.py @@ -839,7 +839,7 @@ def update() -> None: """Check for and install the latest version of Conductor. Fetches the latest release from GitHub and upgrades using - ``uv tool install --force``. + ``uv tool install --locked --force git+https://github.com/microsoft/conductor.git@v{version}``. \b Examples: