feat: usability features — script steps, file tags, workflow resume, interrupts, and web dashboard

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

@@ -19,6 +19,10 @@ conductor run <workflow.yaml> [OPTIONS]
 | `--provider`, `-p PROVIDER` | Override provider (copilot, claude) |
 | `--dry-run` | Show execution plan only |
 | `--skip-gates` | Auto-select first option at human gates |
+| `--web` | Start real-time web dashboard |
+| `--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 |
 
 **Global options** (before the subcommand):
 
@@ -49,8 +53,16 @@ conductor run workflow.yaml --dry-run
 
 # Override provider
 conductor run workflow.yaml -p claude
+
+# Start real-time web dashboard
+conductor run workflow.yaml --web --input question="Hello"
+
+# Background mode: prints URL and exits immediately
+conductor run workflow.yaml --web-bg --input question="Hello"
 ```
 
+The `--web` flag opens a browser dashboard with a DAG visualization showing live agent status, streaming reasoning/tool calls, and an agent detail panel. The `--web-bg` flag forks a background process and exits immediately. `--web` and `--web-bg` are mutually exclusive.
+
 ### conductor validate
 
 Validate without executing:
@@ -163,6 +175,14 @@ conductor run workflow.yaml --dry-run
 
 Preview execution plan without running agents. Shows the workflow graph, agent order, and configuration.
 
+### Web Dashboard
+
+```bash
+conductor run workflow.yaml --web --input question="test"
+```
+
+Visualize execution in real-time with a browser dashboard. Shows agent prompts, reasoning, tool calls, and outputs as they stream in.
+
 ### Validate First
 
 ```bash

.gitignore

@@ -77,3 +77,6 @@ dmypy.json
 # OS
 .DS_Store
 Thumbs.db
+
+# Frontend
+src/conductor/web/frontend/node_modules/

AGENTS.md

@@ -32,6 +32,12 @@ make check
 # Run a workflow
 uv run conductor run workflow.yaml --input question="What is Python?"
 
+# Run with web dashboard
+uv run conductor run workflow.yaml --web --input question="What is Python?"
+
+# Run in background (prints dashboard URL and exits)
+uv run conductor run workflow.yaml --web-bg --input question="What is Python?"
+
 # Validate a workflow
 uv run conductor validate examples/simple-qa.yaml
 make validate-examples    # validate all examples
@@ -44,6 +50,7 @@ make validate-examples    # validate all examples
 - **cli/**: Typer-based CLI with commands `run`, `validate`, `init`, `templates`
   - `app.py` - Main entry point, defines the Typer application
   - `run.py` - Workflow execution command with verbose logging helpers
+  - `bg_runner.py` - Background process forking for `--web-bg` mode
 
 - **config/**: YAML loading and Pydantic schema validation
   - `schema.py` - Pydantic models for all workflow YAML structures (WorkflowConfig, AgentDef, ParallelGroup, ForEachDef, etc.)
@@ -58,6 +65,7 @@ make validate-examples    # validate all examples
 
 - **executor/**: Agent execution
   - `agent.py` - `AgentExecutor` handles prompt rendering, tool resolution, and output validation for single agents
+  - `script.py` - `ScriptExecutor` runs shell commands as workflow steps, capturing stdout/stderr/exit_code
   - `template.py` - Jinja2 template rendering
   - `output.py` - JSON output parsing and schema validation
 
@@ -69,17 +77,24 @@ make validate-examples    # validate all examples
 - **gates/**: Human-in-the-loop support
   - `human.py` - Rich terminal UI for human gate interactions
 
+- **web/**: Real-time web dashboard for workflow visualization
+  - `server.py` - FastAPI + uvicorn server with WebSocket broadcasting and late-joiner state replay
+  - `static/index.html` - Single-file Cytoscape.js frontend with DAG graph, agent detail panel, and streaming activity
+
+- **events.py**: Pub/sub event system decoupling workflow execution from rendering (console, web dashboard)
+
 - **exceptions.py**: Custom exception hierarchy (ConductorError, ValidationError, ExecutionError, etc.)
 
 ### Workflow Execution Flow
 
 1. CLI parses YAML via `config/loader.py` → `WorkflowConfig`
 2. `WorkflowEngine` initializes with config and provider
-3. Engine loops: find agent/parallel/for-each → execute → evaluate routes → next
+3. Engine loops: find agent/parallel/for-each/script → execute → evaluate routes → next
 4. Parallel groups execute agents concurrently with context isolation (deep copy snapshot)
 5. For-each groups resolve source arrays at runtime, inject loop variables (`{{ item }}`, `{{ _index }}`, `{{ _key }}`)
-6. Routes evaluated via `Router` using Jinja2 or simpleeval expressions
-7. Final output built from templates in `output:` section
+6. Script steps run shell commands via asyncio subprocess, expose stdout/stderr/exit_code to context
+7. Routes evaluated via `Router` using Jinja2 or simpleeval expressions
+8. Final output built from templates in `output:` section
 
 ### Key Patterns
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: install install-cli dev test test-cov lint format typecheck check clean build all
+.PHONY: install install-cli dev test test-cov lint format typecheck check clean build all build-frontend dev-frontend
 
 # Default target
 all: check test
@@ -61,3 +61,11 @@ validate-examples:
 		echo "Validating $$file..."; \
 		uv run conductor validate "$$file" || exit 1; \
 	done
+
+# Build frontend dashboard (output to src/conductor/web/static/)
+build-frontend:
+	cd src/conductor/web/frontend && npm install && npm run build
+
+# Run frontend dev server (with proxy to FastAPI backend)
+dev-frontend:
+	cd src/conductor/web/frontend && npm run dev

README.md

@@ -16,9 +16,11 @@ Conductor provides the patterns that work: evaluator-optimizer loops for iterati
 - **YAML-based workflows** - Define multi-agent workflows in readable YAML
 - **Multiple providers** - GitHub Copilot or Anthropic Claude with seamless switching
 - **Parallel execution** - Run agents concurrently (static groups or dynamic for-each)
+- **Script steps** - Run shell commands and route on exit code without an AI agent
 - **Conditional routing** - Route between agents based on output conditions
 - **Human-in-the-loop** - Pause for human decisions with Rich terminal UI
 - **Safety limits** - Max iterations and timeout enforcement
+- **Web dashboard** - Real-time DAG visualization with agent detail streaming
 - **Validation** - Validate workflows before execution
 
 ## Installation
@@ -143,6 +145,9 @@ conductor run <workflow.yaml> [OPTIONS]
 | `-p, --provider PROVIDER` | Override provider |
 | `--dry-run` | Preview execution plan |
 | `--skip-gates` | Auto-select at human gates |
+| `--web` | Start real-time web dashboard |
+| `--web-bg` | Run in background, print dashboard URL, exit |
+| `--web-port PORT` | Port for web dashboard (0 = auto) |
 | `-q, --quiet` | Suppress progress output |
 | `-s, --silent` | Suppress all output except errors |
 | `-l, --log-file PATH` | Write logs to file |
@@ -183,6 +188,7 @@ See the [`examples/`](./examples/) directory for complete workflows:
 | [for-each-simple.yaml](./examples/for-each-simple.yaml) | Dynamic parallel processing |
 | [parallel-research.yaml](./examples/parallel-research.yaml) | Static parallel execution |
 | [design-review.yaml](./examples/design-review.yaml) | Human gate with loop pattern |
+| [script-step.yaml](./examples/script-step.yaml) | Script step with exit_code routing |
 
 **More examples and running instructions:** [examples/README.md](./examples/README.md)
 

docs/cli-reference.md

@@ -29,6 +29,10 @@ conductor run <workflow.yaml> [OPTIONS]
 | `--quiet` | `-q` | Minimal output (agent lifecycle and routing only) |
 | `--silent` | `-s` | No progress output (JSON result only) |
 | `--log-file <auto\|PATH>` | `-l` | Write full debug output to a file |
+| `--web` | | Start a real-time web dashboard |
+| `--web-bg` | | Run in background, print dashboard URL, exit |
+| `--web-port PORT` | | Port for web dashboard (0 = auto-select) |
+| `--no-interactive` | | Disable Esc-to-interrupt capability |
 
 ### Examples
 
@@ -68,6 +72,29 @@ conductor run workflow.yaml --quiet --input question="Test"
 conductor run workflow.yaml --log-file debug.log
 ```
 
+#### Web Dashboard
+
+```bash
+# Start dashboard in foreground (keeps running after workflow completes)
+conductor run workflow.yaml --web --input question="Test"
+
+# Start dashboard on a specific port
+conductor run workflow.yaml --web --web-port 8080 --input question="Test"
+
+# Background mode: prints URL and exits immediately
+conductor run workflow.yaml --web-bg --input question="Test"
+# Dashboard auto-shuts down after workflow completes and clients disconnect
+```
+
+The `--web` flag starts a real-time browser dashboard showing:
+- DAG visualization of the workflow graph with live node state updates
+- Agent detail panel with rendered prompt, reasoning, tool calls, and output
+- Streaming activity as agents execute (reasoning chunks, tool invocations)
+
+The `--web-bg` flag is a convenience shortcut: it forks a background process running the workflow with the dashboard, prints the URL, and exits the CLI immediately. The background process shuts down automatically after the workflow completes and all browser clients disconnect.
+
+`--web` and `--web-bg` are mutually exclusive.
+
 #### Automation Mode
 
 ```bash