chore: update skill reference docs for new CLI flags and checkpoint support

.claude/skills/conductor/SKILL.md

@@ -10,16 +10,20 @@ CLI tool for defining and running multi-agent workflows with the GitHub Copilot
 ## Quick Reference
 
 ```bash
-conductor run workflow.yaml --input question="Hello"     # Execute (progress shown by default)
-conductor run workflow.yaml -V --input question="Hello"  # Full verbose (untruncated prompts, tool args)
+conductor run workflow.yaml --input question="Hello"     # Execute (full output by default)
+conductor run workflow.yaml -q --input question="Hello"  # Quiet: lifecycle + routing only
+conductor run workflow.yaml -s --input question="Hello"  # Silent: JSON result only
+conductor run workflow.yaml --log-file auto               # Log full debug output to file
 conductor validate workflow.yaml                         # Validate only
 conductor init my-workflow --template simple              # Create from template
 conductor templates                                      # List templates
 conductor stop                                           # Stop background workflow
 conductor update                                         # Check for and install latest version
+conductor resume workflow.yaml                           # Resume from last checkpoint
+conductor checkpoints                                    # List available checkpoints
 ```
 
-Progress output is shown by default. Use `-V` (verbose) for full prompts and detailed tool call info.
+Full output is shown by default. Use `-q` (quiet) for minimal output or `-s` (silent) for JSON-only.
 
 ## When to Use Each Guide
 
@@ -32,9 +36,10 @@ Progress output is shown by default. Use `-V` (verbose) for full prompts and det
 - Cost tracking configuration
 
 **Running or debugging workflows?** → See [references/execution.md](references/execution.md)
-- CLI options and flags
+- CLI options and flags (run, resume, checkpoints, stop, update)
 - Debugging techniques
 - Error troubleshooting
+- Checkpoint/resume after failures
 - Environment setup and providers
 
 **Need complete YAML schema?** → See [references/yaml-schema.md](references/yaml-schema.md)
@@ -82,13 +87,16 @@ output:
 |---------|-------------|
 | `entry_point` | First agent/group to execute |
 | `routes` | Where agent goes next (`$end` to finish, `self` to loop) |
+| `type: script` | Shell command step (captures stdout, stderr, exit_code) |
 | `parallel` | Static parallel groups (fixed agent list) |
 | `for_each` | Dynamic parallel groups (runtime-determined array) |
 | `human_gate` | Pauses for user decision with options |
+| `!file` tag | Include external file content in YAML (`prompt: !file prompt.md`) |
 | `context.mode` | How agents share data (accumulate, last_only, explicit) |
 | `limits` | Safety bounds (max_iterations up to 500, timeout_seconds) |
 | `cost` | Token usage and cost tracking configuration |
 | `runtime` | Provider, model, temperature, max_tokens, MCP servers |
+| checkpoint | Auto-saved on failure; resume with `conductor resume` |
 
 ## Common Patterns
 
@@ -125,7 +133,7 @@ parallel:
 for_each:
   - name: processors
     type: for_each
-    source: finder.output.items
+    source: finder.output.topics
     as: item
     max_concurrent: 5
     agent:
@@ -136,6 +144,27 @@ for_each:
       - 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

.claude/skills/conductor/references/authoring.md

@@ -46,7 +46,7 @@ workflow:
 ```yaml
 agents:
   - name: my_agent               # Required: unique identifier
-    type: agent                  # agent (default) or human_gate
+    type: agent                  # agent (default), human_gate, or script
     description: What it does
     model: gpt-5.2               # Override workflow default
     provider: claude             # Optional: per-agent provider override
@@ -119,6 +119,70 @@ routes:
   - to: item_processors         # Route to a for-each group
 ```
 
+## Script Steps
+
+Script steps run shell commands and capture stdout, stderr, and exit_code:
+
+```yaml
+agents:
+  - name: check_python
+    type: script
+    description: Check the installed Python version
+    command: python3
+    args: ["--version"]
+    timeout: 30                  # Per-script timeout in seconds (optional)
+    working_dir: /tmp            # Working directory (optional, Jinja2 templated)
+    env:                         # Extra environment variables (optional)
+      MY_VAR: "value"
+    routes:
+      - to: analyzer
+        when: "exit_code == 0"
+      - to: error_handler
+```
+
+### Script Output
+
+Script steps always produce three fields (no custom `output` schema):
+
+```jinja2
+{{ script_name.output.stdout }}     # Captured standard output
+{{ script_name.output.stderr }}     # Captured standard error
+{{ script_name.output.exit_code }}  # Process exit code (0 = success)
+```
+
+### Script Routing
+
+Route conditions use `exit_code` directly (simpleeval syntax):
+
+```yaml
+routes:
+  - to: next_step
+    when: "exit_code == 0"
+  - to: error_handler            # Fallback for non-zero exit
+```
+
+### Script Restrictions
+
+Script agents **cannot** have: `prompt`, `provider`, `model`, `tools`, `output`, `system_prompt`, `options`.
+Command and args support Jinja2 templating for dynamic values.
+
+## File Includes (`!file` Tag)
+
+Include external file content in YAML using the `!file` tag:
+
+```yaml
+agents:
+  - name: analyzer
+    system_prompt: !file prompts/system.md
+    prompt: !file prompts/analyze.md
+```
+
+- Paths are **relative to the YAML file's directory**
+- If the included file is valid YAML, it's parsed as a data structure
+- If it's plain text (e.g., Markdown), it's included as a string
+- Supports **recursive includes** — included YAML files can use `!file` too
+- Circular references are detected and raise an error
+
 ## Parallel Groups
 
 Static parallel groups run a fixed set of agents concurrently:

.claude/skills/conductor/references/execution.md

@@ -23,24 +23,35 @@ conductor run <workflow.yaml> [OPTIONS]
 | `--web-bg` | Run in background, print dashboard URL, exit |
 | `--web-port PORT` | Port for web dashboard (0 = auto) |
 | `--no-interactive` | Disable Esc-to-interrupt capability |
+| `--log-file`, `-l PATH` | Write full debug output to file (`auto` for auto-generated) |
 
 **Global options** (before the subcommand):
 
 | Option | Description |
 |--------|-------------|
-| `--verbose`, `-V` | Show full prompts and detailed tool call information |
+| `--quiet`, `-q` | Minimal output: agent lifecycle and routing only |
+| `--silent`, `-s` | No progress output. Only JSON result on stdout |
 | `--version`, `-v` | Show version and exit |
 
-> **Note:** Progress output is shown by default. Use `-V` for full untruncated prompts, tool arguments, and reasoning details.
+> **Note:** Full output is shown by default (prompts, tool calls, reasoning). Use `-q` for minimal output or `-s` for JSON-only. `--quiet` and `--silent` are mutually exclusive.
 
 **Examples:**
 
 ```bash
-# Standard run (progress shown by default)
+# Standard run (full output by default)
 conductor run workflow.yaml --input question="Hello"
 
-# Full verbose mode (untruncated prompts, tool args, reasoning)
-conductor -V run workflow.yaml --input question="Hello"
+# Quiet mode (lifecycle + routing only)
+conductor -q run workflow.yaml --input question="Hello"
+
+# Silent mode (JSON result only, no progress)
+conductor -s run workflow.yaml --input question="Hello"
+
+# Log full debug output to auto-generated file
+conductor run workflow.yaml --log-file auto
+
+# Silent terminal + full file logging
+conductor -s run workflow.yaml --log-file auto
 
 # Multiple inputs
 conductor run workflow.yaml -i topic="AI" -i depth="detailed"
@@ -116,6 +127,62 @@ If already up to date, prints a confirmation message and exits.
 conductor update
 ```
 
+### conductor resume
+
+Resume a workflow from a checkpoint after failure:
+
+```bash
+conductor resume <workflow.yaml> [OPTIONS]
+conductor resume --from <checkpoint.json> [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--from PATH` | Resume from a specific checkpoint file |
+| `--skip-gates` | Auto-select first option at human gates |
+| `--log-file`, `-l PATH` | Write debug output to file |
+| `--no-interactive` | Disable Esc-to-interrupt |
+
+When a workflow fails, Conductor automatically saves a checkpoint to `$TMPDIR/conductor/checkpoints/`. The checkpoint contains all prior agent outputs and workflow state, enabling seamless resumption from the failed agent.
+
+**Examples:**
+
+```bash
+# Resume the 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
+
+# Resume with log file
+conductor resume workflow.yaml --log-file auto
+```
+
+**Behavior:**
+- If the workflow file has changed since the checkpoint was saved, a warning is displayed
+- Execution resumes from the exact agent that failed
+- All prior agent outputs are restored from the checkpoint
+
+### conductor checkpoints
+
+List available workflow checkpoints:
+
+```bash
+conductor checkpoints [workflow.yaml]
+```
+
+Shows all checkpoint files with metadata: workflow name, timestamp, failed agent, and error type. Optionally filter by workflow file.
+
+**Examples:**
+
+```bash
+# List all checkpoints
+conductor checkpoints
+
+# List checkpoints for a specific workflow
+conductor checkpoints workflow.yaml
+```
+
 ### conductor validate
 
 Validate without executing:
@@ -188,7 +255,7 @@ conductor templates
 
 ## Cost Tracking
 
-Conductor tracks token usage and costs automatically when using verbose output:
+Conductor tracks token usage and costs automatically:
 
 ```yaml
 cost:
@@ -206,10 +273,12 @@ Output includes input/output token counts and estimated costs per agent and in t
 
 ## Debugging
 
-### Use Full Verbose Mode
+### Default Output
+
+Full output is shown by default:
 
 ```bash
-conductor -V run workflow.yaml --input question="test"
+conductor run workflow.yaml --input question="test"
 ```
 
 Shows:
@@ -220,6 +289,17 @@ Shows:
 - Tool call arguments and reasoning
 - Token usage and costs per agent
 
+Use `--quiet` for minimal output (lifecycle + routing only) or `--silent` for JSON-only.
+
+### Log File
+
+```bash
+conductor run workflow.yaml --log-file auto
+conductor -s run workflow.yaml --log-file debug.log
+```
+
+Capture full debug output to a file. Combine with `--silent` for quiet terminal with full logging. Auto mode generates files in `$TMPDIR/conductor/`.
+
 ### Dry Run
 
 ```bash
@@ -425,3 +505,41 @@ Environment variables in YAML configs support `${VAR}` and `${VAR:-default}` int
 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.