conductor-board 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mettafive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# conductor-board
+
+The CLI and live local Kanban board for [Agent Conductor](../README.md). It
+watches `.conductor/status.json` and renders your conductor workflow in real time
+as the agent executes it — and scaffolds and validates conductors.
+
+```bash
+npx conductor-board
+```
+
+```
+🎼 conductor-board
+Board live at http://localhost:3042 — watching .conductor/status.json
+```
+
+## Commands
+
+```bash
+npx conductor-board                         # serve the live board (default)
+npx conductor-board init                    # scaffold .conductor/conductor.yaml
+npx conductor-board init --name w --steps 4 # non-interactive scaffold
+npx conductor-board validate [path]         # check a conductor against the spec
+npx conductor-board --help                  # all commands + options
+```
+
+## What it does
+
+- **Watches** `.conductor/status.json` via `fs.watch` and streams changes to the
+  browser over **Server-Sent Events** — no polling, no WebSocket.
+- **Merges** the live status with the conductor definition (auto-discovered next
+  to the status file) so cards show the full picture: instruction, gate criteria,
+  soft/hard split, `requires`, conditions, outputs.
+- **Renders** a board with columns **Pending → Running → Gate Check → Done** and a
+  **Failed** side column. Cards animate between columns as status changes.
+- **Archives** every completed/failed run to `.conductor/history/` and shows a
+  **history sidebar** — click any past run to view its frozen final state.
+
+## Options
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--path`, `-p` | `.conductor/status.json` | Path to the status file |
+| `--conductor`, `-c` | auto-discovered | Path to the conductor `.yaml` |
+| `--port` | `3042` | Port to serve on (walks forward if taken) |
+| `--no-open` | — | Don't open the browser |
+| `--help`, `-h` | — | Show help |
+
+```bash
+npx conductor-board --path ./run/status.json --port 3001
+npx conductor-board --conductor ./workflows/review.yaml
+```
+
+The board reads `status.json` for live **state** and the conductor file for step
+**structure**. If no conductor file is found, cards degrade gracefully to
+status-only.
+
+## History
+
+When a run reaches `done` or `failed`, the server archives a **self-contained**
+record (the final status plus the conductor that produced it) to
+`.conductor/history/<run_id>_<workflow>.json`. The board's history sidebar lists past runs
+grouped by workflow; selecting one shows its frozen final state. Deep-link a run
+with `?run=<run_id>`.
+
+Give each run a distinct `run_id` (a timestamp works well) in `status.json` so
+runs archive cleanly instead of overwriting each other.
+
+| Endpoint | Returns |
+| --- | --- |
+| `GET /api/state` | current `{ status, conductorYaml }` snapshot |
+| `GET /history` | summaries of archived runs, newest first |
+| `GET /history/:filename` | one full archived run (also resolves by `run_id`) |
+| `GET /events` | SSE stream of `update` and `history` events |
+
+## Card anatomy
+
+- Step ID, first line of the instruction, and soft/hard gate badges
+- Attempt counter (`×2`) when a step has been retried
+- Condition steps show a fork icon and the branch taken
+- Loop steps (`type: loop`) show an `n/total` iterations bar; expand to see each
+  iteration's sub-step statuses and per-iteration retries
+- `requires` dependencies render as a chip on the card
+- Click a card to expand its gate criteria with per-criterion pass/fail
+
+## Architecture
+
+```
+.conductor/status.json ──fs.watch──┐
+.conductor/conductor.yaml ─────────┤
+                                   ▼
+                       server (zero-dep node:http)
+                          ├── serves dist/ (React app)
+                          └── /events  (Server-Sent Events)
+                                   ▼
+                       browser: parse + merge + render
+```
+
+The **board server has zero runtime dependencies** — plain `node:http`, `fs`, and
+`fs.watch`. YAML is parsed in the browser, so the server never needs a parser. The
+package's only dependency is `js-yaml`, used by the `validate` command (it has no
+dependencies of its own, so `npx` stays instant).
+
+## Develop
+
+```bash
+npm install
+npm run build              # build the React app into dist/
+npm start                  # serve the board (node bin/cli.js)
+
+# drive a demo workflow through the board to see the animations + history:
+npm run simulate -- --fail security-audit                 # one run, with a retry
+npm run simulate -- --fatal coverage-check                # a run that ends failed
+npm run simulate -- --loop                                # keep archiving runs
+npm run simulate -- ../examples/batch-review.yaml --fail critique   # a loop run
+```
+
+`scripts/simulate.js` is a dev-only tool that walks a conductor and writes
+`status.json` over time (it is not part of the published package).

package/bin/cli.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { startServer } from "../server/server.js";
+
+const argv = process.argv.slice(2);
+const command = argv[0] && !argv[0].startsWith("-") ? argv[0] : null;
+const rest = argv.slice(1);
+
+function flag(names, fallback) {
+  for (const name of names) {
+    const i = argv.indexOf(name);
+    if (i !== -1) {
+      const next = argv[i + 1];
+      return next && !next.startsWith("-") ? next : true;
+    }
+  }
+  return fallback;
+}
+
+const HELP = `
+  conductor-board — gated workflows for AI agents, with a live Kanban board
+
+  Usage
+    $ npx conductor-board [command] [options]
+
+  Commands
+    (default)                Serve the live board (watches .conductor/)
+    init                     Scaffold a new .conductor/conductor.yaml
+    validate [path]          Check a conductor against the spec
+    setup                    Write setup.conductor.yaml (the bootstrap conductor)
+
+  Board options
+    --path, -p <file>        Path to status.json   (default: .conductor/status.json)
+    --conductor, -c <file>   Path to the conductor  (default: auto-discovered)
+    --port <n>               Port to serve on        (default: 3042)
+    --no-open                Don't open the browser
+
+  init options
+    --name, -n <name>        Workflow name (skips the prompts)
+    --description, -d <text> One-line description
+    --steps, -s <n>          Number of placeholder steps
+    --force, -f              Overwrite an existing conductor.yaml
+
+  --help, -h                 Show this help
+
+  Examples
+    $ npx conductor-board
+    $ npx conductor-board init --name clinic-update --steps 4
+    $ npx conductor-board validate .conductor/conductor.yaml
+`;
+
+// ---- subcommands ----
+if (command === "help" || (!command && flag(["--help", "-h"], false))) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+if (command === "init") {
+  const { runInit } = await import("../cli/init.js");
+  process.exit((await runInit(rest)) ? 0 : 1);
+}
+
+if (command === "validate") {
+  const { runValidate } = await import("../cli/validate.js");
+  process.exit((await runValidate(rest)) ? 0 : 1);
+}
+
+if (command === "setup") {
+  const { runSetup } = await import("../cli/setup.js");
+  process.exit((await runSetup(rest)) ? 0 : 1);
+}
+
+if (command && command !== "board") {
+  console.error(`Unknown command "${command}". Run with --help to see usage.`);
+  process.exit(1);
+}
+
+// ---- default: serve the board ----
+const statusPath = String(flag(["--path", "-p"], ".conductor/status.json"));
+const conductorArg = flag(["--conductor", "-c"], null);
+const conductorPath = conductorArg ? path.resolve(process.cwd(), String(conductorArg)) : null;
+const wantedPort = Number(flag(["--port"], 3042)) || 3042;
+const noOpen = flag(["--no-open"], false) === true;
+
+function openBrowser(url) {
+  const cmd =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "cmd"
+        : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+  } catch {
+    /* opening the browser is best-effort */
+  }
+}
+
+// Try the requested port, walk forward a few if it's taken.
+async function listenWithFallback(port, attempts = 10) {
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await startServer({ statusPath, conductorPath, port: port + i });
+    } catch (e) {
+      if (e && e.code === "EADDRINUSE") continue;
+      throw e;
+    }
+  }
+  throw new Error(`No free port in range ${port}-${port + attempts - 1}`);
+}
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const iris = (s) => `\x1b[38;5;141m${s}\x1b[0m`;
+const mint = (s) => `\x1b[38;5;78m${s}\x1b[0m`;
+
+const { conductorPath: resolvedConductor, absStatus, server, serverJsonPath } =
+  await listenWithFallback(wantedPort);
+const port = server.address().port;
+const url = `http://localhost:${port}`;
+const rel = (p) => (p ? path.relative(process.cwd(), p) || p : null);
+
+console.log("");
+console.log(`  ${iris("🎼 conductor-board")}`);
+console.log(`  ${bold("Board live at")} ${mint(url)} ${dim("— watching " + rel(absStatus))}`);
+if (resolvedConductor) {
+  console.log(`  ${dim("conductor:  " + rel(resolvedConductor))}`);
+} else {
+  console.log(`  ${dim("conductor:  not found — cards show status only")}`);
+}
+console.log(`  ${dim("press ctrl+c to stop")}`);
+console.log("");
+
+if (!noOpen) openBrowser(url);
+
+function shutdown() {
+  try {
+    if (serverJsonPath) fs.unlinkSync(serverJsonPath);
+  } catch {
+    /* already gone */
+  }
+  console.log(dim("\n  board stopped\n"));
+  process.exit(0);
+}
+
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/cli/init.js

@@ -0,0 +1,87 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+
+function flag(args, names) {
+  for (const name of names) {
+    const i = args.indexOf(name);
+    if (i !== -1) {
+      const next = args[i + 1];
+      return next && !next.startsWith("-") ? next : true;
+    }
+  }
+  return undefined;
+}
+
+function buildYaml({ name, description, steps }) {
+  const lines = [
+    "conductor: 1.0.0",
+    `name: ${name}`,
+    `description: ${description}`,
+    "",
+    "steps:",
+  ];
+  for (let i = 1; i <= steps; i++) {
+    lines.push(`  - id: step-${i}`);
+    lines.push("    instruction: |");
+    lines.push("      TODO: Describe what to do in this step.");
+    if (i > 1) lines.push(`    requires: [step-${i - 1}]`);
+    lines.push("    gate:");
+    lines.push('      - "TODO: Add validation criteria"');
+    lines.push("");
+  }
+  return lines.join("\n").replace(/\n+$/, "\n");
+}
+
+export async function runInit(args) {
+  const force = flag(args, ["--force", "-f"]) === true;
+  const dir = path.resolve(process.cwd(), String(flag(args, ["--dir"]) ?? ".conductor"));
+  const target = path.join(dir, "conductor.yaml");
+
+  let name = flag(args, ["--name", "-n"]);
+  let description = flag(args, ["--description", "-d"]);
+  let stepsRaw = flag(args, ["--steps", "-s"]);
+
+  // interactive unless a name was passed
+  const interactive = name === undefined;
+  if (interactive) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      console.log("");
+      name = (await rl.question("? Workflow name: ")).trim() || "my-workflow";
+      description = (await rl.question("? Description: ")).trim() || "A gated agent workflow.";
+      stepsRaw = (await rl.question("? How many steps? ")).trim() || "3";
+    } finally {
+      rl.close();
+    }
+  }
+
+  name = String(name || "my-workflow").trim();
+  description = String(description ?? "A gated agent workflow.").trim();
+  let steps = parseInt(String(stepsRaw ?? "3"), 10);
+  if (!Number.isFinite(steps) || steps < 1) steps = 3;
+  steps = Math.min(steps, 50);
+
+  if (fs.existsSync(target) && !force) {
+    console.error("");
+    console.error(red(`✗ ${path.relative(process.cwd(), target)} already exists.`));
+    console.error(dim("  Use --force to overwrite it."));
+    console.error("");
+    return false;
+  }
+
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(target, buildYaml({ name, description, steps }));
+
+  const rel = path.relative(process.cwd(), target) || target;
+  console.log("");
+  console.log(`${green("✓")} Created ${bold(rel)} with ${steps} step${steps === 1 ? "" : "s"}.`);
+  console.log(dim("  Edit the steps, then run: ") + "conductor-board");
+  console.log("");
+  return true;
+}

package/cli/setup.js

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+
+// The self-bootstrapping conductor. Every gate is a HARD gate — in the
+// bootstrap, either it works or it doesn't, no soft judgment.
+export const SETUP_YAML = `conductor: 1.0.0
+name: conductor-board-bootstrap
+description: Set up the board, convert a skill into a gated workflow, and execute it.
+
+inputs:
+  - skill_content
+
+steps:
+  - id: preflight
+    instruction: |
+      Verify the environment can run conductor-board.
+      Check that Node.js 18+ and npx are available.
+    gate:
+      - name: "Node.js installed"
+        check: "node --version"
+      - name: "npx available"
+        check: "npx --version"
+
+  - id: start-board
+    instruction: |
+      Start the board server in the background:
+        npx conductor-board &
+      Wait ~3 seconds for it to initialize. It auto-detects a free port if 3042
+      is taken and records the chosen port in .conductor/server.json.
+    requires: [preflight]
+    gate:
+      - name: "Server config file exists"
+        check: "test -f .conductor/server.json"
+      - name: "Server responds to health check"
+        check: "curl -sf http://localhost:$(node -p \\"require('./.conductor/server.json').port\\")/health -o /dev/null"
+
+  - id: read-skill
+    instruction: |
+      Read and analyze the user's skill content:
+
+      {skill_content}
+
+      Break it down into: the discrete sequential steps; decision points where
+      the flow could branch; repeated operations that need loops; and which
+      checks are verifiable by a shell command vs which need judgment.
+      Save your analysis to .conductor/skill-analysis.md.
+    requires: [start-board]
+    gate:
+      - name: "Analysis saved"
+        check: "test -f .conductor/skill-analysis.md"
+
+  - id: convert-to-conductor
+    instruction: |
+      Convert the analysis into a conductor YAML. Follow the format in
+      spec/conductor-spec.md and the examples/ directory. Rules:
+      - every step gets at least one gate criterion
+      - hard gates (check:) for anything verifiable by command; soft gates for judgment
+      - conditions (type: condition) where the flow branches
+      - loops (type: loop) where steps repeat over a list
+      - chain data between steps with output: and requires:
+      Save the conductor to .conductor/conductor.yaml.
+    requires: [read-skill]
+    gate:
+      - name: "Conductor file created"
+        check: "test -f .conductor/conductor.yaml"
+      - name: "Conductor passes validation"
+        check: "npx conductor-board validate .conductor/conductor.yaml"
+
+  - id: execute-workflow
+    instruction: |
+      Execute the generated conductor workflow.
+      Create .conductor/status.json with all steps pending and a timestamp run_id.
+      Walk each step in order, updating status.json after every step and gate
+      change. Retry on gate failure — never skip. Set the top-level status to
+      "done" when the last step completes.
+    requires: [convert-to-conductor]
+    gate:
+      - name: "Status file exists"
+        check: "test -f .conductor/status.json"
+      - name: "Workflow completed successfully"
+        check: "node -p \\"JSON.parse(require('fs').readFileSync('.conductor/status.json','utf8')).status\\" | grep done"
+`;
+
+export async function runSetup(args) {
+  const force = args.includes("--force") || args.includes("-f");
+  const target = path.resolve(process.cwd(), "setup.conductor.yaml");
+
+  if (fs.existsSync(target) && !force) {
+    console.log("");
+    console.log(dim(`  setup.conductor.yaml already exists (use --force to replace).`));
+    console.log("");
+    return true;
+  }
+
+  fs.writeFileSync(target, SETUP_YAML);
+  console.log("");
+  console.log(`${green("✓")} Wrote ${bold("setup.conductor.yaml")}`);
+  console.log(dim("  Point your agent at it: \"Read setup.conductor.yaml and execute it.\""));
+  console.log("");
+  return true;
+}

package/cli/validate.js

@@ -0,0 +1,201 @@
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+
+const SEMVER = /^\d+\.\d+\.\d+$/;
+
+function gateOk(g) {
+  if (typeof g === "string") return true;
+  return g && typeof g === "object" && typeof g.check === "string";
+}
+
+function countGates(steps, acc) {
+  for (const s of steps) {
+    for (const g of s.gate ?? []) {
+      if (typeof g === "string") acc.soft++;
+      else if (g && typeof g === "object" && typeof g.check === "string") acc.hard++;
+    }
+    if (s.type === "loop" && Array.isArray(s.steps)) countGates(s.steps, acc);
+  }
+}
+
+/** Validate sub-steps of a loop; pushes errors with a prefix. */
+function validateSubSteps(loop, errors) {
+  const seen = new Set();
+  for (const sub of loop.steps ?? []) {
+    if (!sub || !sub.id) {
+      errors.push(`Loop "${loop.id}" has a sub-step with no id`);
+      continue;
+    }
+    if (seen.has(sub.id)) errors.push(`Loop "${loop.id}" has duplicate sub-step id "${sub.id}"`);
+    seen.add(sub.id);
+    if (!sub.instruction) errors.push(`Loop sub-step "${sub.id}" has no instruction`);
+    for (const g of sub.gate ?? []) {
+      if (!gateOk(g)) errors.push(`Loop sub-step "${sub.id}" has a malformed gate criterion`);
+    }
+  }
+}
+
+/** Reachability from the first step, following flow (not requires). */
+function findOrphans(steps, ids) {
+  if (steps.length === 0) return [];
+  const indexById = new Map(steps.map((s, i) => [s.id, i]));
+  const successors = (s, i) => {
+    if (s.type === "condition") return [s.if_true, s.if_false].filter(Boolean);
+    if (s.then) return [s.then];
+    const next = steps[i + 1];
+    return next ? [next.id] : [];
+  };
+  const reachable = new Set();
+  const queue = [steps[0].id];
+  while (queue.length) {
+    const id = queue.shift();
+    if (reachable.has(id) || !ids.has(id)) continue;
+    reachable.add(id);
+    const i = indexById.get(id);
+    for (const n of successors(steps[i], i)) if (!reachable.has(n)) queue.push(n);
+  }
+  return steps.map((s) => s.id).filter((id) => !reachable.has(id));
+}
+
+/** Detect a cycle in the `requires` dependency graph. */
+function hasRequiresCycle(steps, ids) {
+  const deps = new Map(steps.map((s) => [s.id, (s.requires ?? []).filter((d) => ids.has(d))]));
+  const state = new Map(); // white/gray/black
+  const dfs = (id) => {
+    state.set(id, "gray");
+    for (const d of deps.get(id) ?? []) {
+      const st = state.get(d);
+      if (st === "gray") return true;
+      if (st !== "black" && dfs(d)) return true;
+    }
+    state.set(id, "black");
+    return false;
+  };
+  for (const s of steps) if (state.get(s.id) !== "black" && dfs(s.id)) return true;
+  return false;
+}
+
+export function validateConductor(doc) {
+  const errors = [];
+  if (!doc || typeof doc !== "object") return ["File is empty or not a YAML mapping"];
+
+  for (const key of ["conductor", "name", "description", "steps"]) {
+    if (doc[key] === undefined) errors.push(`Missing required top-level key "${key}"`);
+  }
+  if (doc.conductor !== undefined && !SEMVER.test(String(doc.conductor))) {
+    errors.push(`"conductor" must be a semver version (e.g. 1.1.0), got "${doc.conductor}"`);
+  }
+
+  const steps = Array.isArray(doc.steps) ? doc.steps : [];
+  if (doc.steps !== undefined && !Array.isArray(doc.steps)) errors.push(`"steps" must be a list`);
+
+  const ids = new Set();
+  for (const s of steps) {
+    if (!s || typeof s !== "object" || !s.id) {
+      errors.push("A step is missing its id");
+      continue;
+    }
+    if (ids.has(s.id)) errors.push(`Duplicate step id "${s.id}"`);
+    ids.add(s.id);
+  }
+
+  for (const s of steps) {
+    if (!s || !s.id) continue;
+    const isCond = s.type === "condition";
+    const isLoop = s.type === "loop";
+
+    if (!isLoop && !s.instruction) errors.push(`Step "${s.id}" has no instruction`);
+
+    for (const g of s.gate ?? []) {
+      if (!gateOk(g)) errors.push(`Step "${s.id}" has a malformed gate criterion`);
+    }
+
+    if (isCond) {
+      if (!s.if_true) errors.push(`Step "${s.id}" is a condition but missing if_true`);
+      if (!s.if_false) errors.push(`Step "${s.id}" is a condition but missing if_false`);
+    }
+
+    if (isLoop) {
+      if (!s.over) errors.push(`Loop "${s.id}" is missing "over"`);
+      if (!s.as) errors.push(`Loop "${s.id}" is missing "as"`);
+      if (!Array.isArray(s.steps) || s.steps.length === 0)
+        errors.push(`Loop "${s.id}" has no sub-steps`);
+      else validateSubSteps(s, errors);
+    }
+
+    for (const [field, val] of [
+      ["if_true", s.if_true],
+      ["if_false", s.if_false],
+      ["then", s.then],
+    ]) {
+      if (val && !ids.has(val)) {
+        errors.push(`Step "${s.id}" references unknown step "${val}" in ${field}`);
+      }
+    }
+    for (const dep of s.requires ?? []) {
+      if (!ids.has(dep)) errors.push(`Step "${s.id}" references unknown step "${dep}" in requires`);
+    }
+  }
+
+  if (steps.length && hasRequiresCycle(steps, ids)) {
+    errors.push("Circular dependency detected in requires");
+  }
+
+  for (const orphan of findOrphans(steps, ids)) {
+    errors.push(`Step "${orphan}" is unreachable`);
+  }
+
+  return errors;
+}
+
+export async function runValidate(args) {
+  const fileArg = args.find((a) => !a.startsWith("-"));
+  const file = path.resolve(process.cwd(), fileArg || ".conductor/conductor.yaml");
+
+  if (!fs.existsSync(file)) {
+    console.error(red(`✗ No conductor file at ${path.relative(process.cwd(), file)}`));
+    return false;
+  }
+
+  let doc;
+  try {
+    doc = yaml.load(fs.readFileSync(file, "utf8"));
+  } catch (e) {
+    console.error(red(`✗ Could not parse YAML: ${e.message}`));
+    return false;
+  }
+
+  const errors = validateConductor(doc);
+  console.log("");
+  if (errors.length === 0) {
+    const steps = Array.isArray(doc.steps) ? doc.steps : [];
+    const acc = { soft: 0, hard: 0 };
+    countGates(steps, acc);
+    const conditions = steps.filter((s) => s.type === "condition").length;
+    const loops = steps.filter((s) => s.type === "loop").length;
+    const part = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+    console.log(green(`✓ ${path.basename(file)} is valid`));
+    console.log(
+      dim(
+        `  ${part(steps.length, "step", "steps")}, ` +
+          `${part(acc.soft, "soft gate", "soft gates")}, ` +
+          `${part(acc.hard, "hard gate", "hard gates")}, ` +
+          `${part(conditions, "condition", "conditions")}, ` +
+          `${part(loops, "loop", "loops")}`,
+      ),
+    );
+    console.log("");
+    return true;
+  }
+
+  for (const e of errors) console.error(red(`✗ ${e}`));
+  console.error("");
+  console.error(`${errors.length} error${errors.length === 1 ? "" : "s"} found`);
+  console.error("");
+  return false;
+}