workplane 0.2.0 → 0.3.1

package/README.md

@@ -1,15 +1,15 @@
 # workplane
 
-[![website](https://img.shields.io/badge/website-mindstaq.github.io%2Fworkplane-3dd6c6)](https://mindstaq.github.io/workplane/)
+[![website](https://img.shields.io/badge/website-workplane.dev-3dd6c6)](https://mindstaq.github.io/workplane/)
 [![npm version](https://img.shields.io/npm/v/workplane)](https://www.npmjs.com/package/workplane)
-[![status](https://img.shields.io/badge/status-beta-orange)](https://github.com/MindStaq/workplane)
+[![status](https://img.shields.io/badge/status-alpha-orange)](https://github.com/MindStaq/workplane)
 [![license](https://img.shields.io/npm/l/workplane)](https://github.com/MindStaq/workplane/blob/main/packages/workplane/LICENSE)
 
-> **Beta** — Workplane v0.1.x is under active development. APIs, CLI commands, and deployment expectations may change. Not recommended for production workloads yet.
+> **Alpha software.** APIs and data models are unstable and will change between releases. Not recommended for production use.
 
-Route durable work—shell commands, local inference (Ollama), and batch agent harness jobs (Aider, Codex, Claude Code)—to capable machines on your private network.
+Route durable work to capable nodes on your private network. Compose multi-step AI workplans that mix local Ollama with frontier APIs. Supports shell commands, local inference, and AI coding agents (Codex, Claude Code, Aider) — both **batch** (one-shot) and **interactive** (multi-turn PTY/stdin sessions mediated through the control plane with no direct client-to-node connection).
 
-Workplane is a control plane + polling node runtime backed by Postgres and [DBOS](https://www.dbos.dev/). You submit tasks from a CLI; nodes pull work, run it in isolated workspaces, and report logs and artifacts.
+Workplane is a control plane + polling node runtime backed by Postgres. You submit tasks from a CLI; nodes pull work, run it in isolated workspaces, and stream logs and artifacts back.
 
 **Requires Node.js 20+** and **Postgres**.
 
@@ -54,7 +54,7 @@ workplane-node
 **4. Submit a task** (fourth terminal):
 
 ```bash
-export WORKPLANE_OPERATOR_TOKEN=your-operator-secret   # if auth enabled on server
+export WORKPLANE_OPERATOR_TOKEN=your-operator-secret
 
 workplane task submit shell --command "echo hello"
 workplane tasks
@@ -64,18 +64,18 @@ workplane logs <runId>
 
 ## Authentication
 
-When `WORKPLANE_NODE_TOKEN` is set on the **server**, every node must use the same value. When `WORKPLANE_OPERATOR_TOKEN` is set, the CLI must send it for `task submit`, `retry`, and `cancel`.
-
 | Variable | Used by |
 |----------|---------|
-| `WORKPLANE_NODE_TOKEN` | `workplane-node` |
-| `WORKPLANE_OPERATOR_TOKEN` | `workplane` CLI (mutating commands) |
+| `WORKPLANE_NODE_TOKEN` | `workplane-node` (register, poll, report) |
+| `WORKPLANE_OPERATOR_TOKEN` | `workplane` CLI (task submit / retry / cancel / send input) |
 
-Read-only CLI commands (`tasks`, `logs`, `runs`, …) work without the operator token unless you add stricter rules in your deployment.
+Read-only CLI commands (`tasks`, `logs`, `runs`, …) work without the operator token.
 
 ## CLI examples
 
 ```bash
+export WORKPLANE_OPERATOR_TOKEN=...
+
 # Shell
 workplane task submit shell --command "npm test" \
   --repo https://github.com/you/your-repo.git
@@ -83,19 +83,33 @@ workplane task submit shell --command "npm test" \
 # Local inference (node must advertise ollama capability)
 workplane task submit inference --model llama3.2 --prompt "Say hello"
 
-# Agent harness (node must have codex or claude-code installed)
-workplane task submit harness --harness codex \
-  --repo git@github.com:you/app.git \
-  --prompt "Fix failing tests"
-
-workplane task submit aider \
-  --repo git@github.com:you/app.git \
-  --prompt "Fix the bug" \
-  --test-command "npm test"
-
-workplane task retry <taskId>
-workplane task cancel <taskId>
+# Batch harness (one-shot)
+workplane task submit harness --harness claude-code \
+  --repo git@github.com:you/app.git --prompt "Refactor auth middleware" \
+  --requires claude-code,git
+
+# Interactive harness (multi-turn PTY/stdin session)
+workplane task submit harness --harness claude-code \
+  --repo git@github.com:you/app.git --prompt "Start exploring the codebase" \
+  --interactive --requires claude-code,git
+
+# Send input to a running interactive session
+workplane run input <runId> --stdin "Focus on the auth module"
+workplane run input <runId> --signal SIGINT
+workplane run input <runId> --resize 220x50
+
+# Skills (v0.3.0)
+workplane skill list
+workplane skill run code-review --repo . --model claude-haiku-4-5-20251001
+
+# Inspect
+workplane tasks [--status running]
+workplane runs --task-id <taskId>
+workplane run show <runId>
+workplane logs <runId>
 workplane artifacts <runId>
+workplane task cancel <taskId>
+workplane task retry <taskId>
 ```
 
 ## Node capabilities
@@ -109,27 +123,106 @@ workplane-node
 
 Tasks declare `requires`; the control plane assigns work to a node whose capabilities are a superset.
 
-| Adapter | Typical capabilities |
-|---------|----------------------|
-| Shell | `shell` |
-| Ollama | `ollama` |
-| Aider | `git`, `aider` |
-| Codex | `git`, `codex` |
-| Claude Code | `git`, `claude-code` |
+| Adapter | Capability tags | Modes |
+|---------|----------------|-------|
+| Shell | `shell` | batch |
+| Ollama | `ollama` | batch |
+| Aider | `aider`, `git` | batch |
+| Codex | `codex`, `git` | batch, interactive (stdio) |
+| Claude Code | `claude-code`, `git` | batch, interactive (PTY) |
 
 Override harness binaries: `WORKPLANE_CODEX_BIN`, `WORKPLANE_CLAUDE_CODE_BIN`.
 
+## Workplans (v0.3.0)
+
+Compose multi-step AI pipelines with the `@workplane/workplans` DSL:
+
+```ts
+import { SequentialWorkplanRunner, LocalWorkplanContext } from "@workplane/workplans";
+
+const plan = {
+  id: "review", name: "Code Review",
+  steps: [
+    {
+      id: "diff", adapter: "shell", provider: "shell",
+      payload: { command: "git diff HEAD~1", cwd: "./my-repo" },
+      output: { dest: "next" },
+    },
+    {
+      id: "summarize", adapter: "ollama", provider: "ollama", model: "llama3",
+      payload: { prompt: "Summarize these changes:\n{{prevOutput}}" },
+      output: { dest: "next" },
+    },
+    {
+      id: "critique", adapter: "anthropic", provider: "anthropic",
+      model: "claude-haiku-4-5-20251001",
+      payload: { prompt: "Review for correctness and security:\n{{prevOutput}}" },
+    },
+  ],
+};
+
+await new SequentialWorkplanRunner().run(plan, new LocalWorkplanContext());
+```
+
+Inline providers (`anthropic`, `openai`, `ollama`, `shell`, `file`) run without dispatching to a fleet node.
+
+## Agent skills (v0.3.0)
+
+Pre-built workplans via `@workplane/agent-skills`:
+
+```ts
+import { createDefaultRegistry } from "@workplane/agent-skills";
+import { SequentialWorkplanRunner, LocalWorkplanContext } from "@workplane/workplans";
+
+const skill = createDefaultRegistry().get("code-review");
+const plan = skill.buildPlan({ repo: ".", model: "claude-haiku-4-5-20251001" });
+await new SequentialWorkplanRunner().run(plan, new LocalWorkplanContext());
+```
+
+Or via CLI: `workplane skill run code-review --repo . --model claude-haiku-4-5-20251001`
+
+## Library packages
+
+All packages are published under `@workplane/` and can be imported independently:
+
+| Package | Purpose |
+|---------|---------|
+| `@workplane/workplans` | Workplan DSL, sequential runner, inline providers |
+| `@workplane/agent-skills` | Pre-built skills, SkillRegistry, CanonicalSkillWorkflow |
+| `@workplane/adapter-sdk` | Build custom adapters — WorkAdapter, WorkContext, cancellable exec |
+| `@workplane/types` | Shared TypeScript types |
+| `@workplane/core` | Config, HTTP client, auth, git utilities |
+| `@workplane/adapter-shell` | Shell command adapter |
+| `@workplane/adapter-ollama` | Ollama inference adapter |
+| `@workplane/adapter-aider` | Aider coding agent adapter |
+| `@workplane/adapter-harness` | Base harness adapter (extended by codex/claude-code) |
+| `@workplane/adapter-claude-code` | Claude Code adapter (PTY interactive) |
+| `@workplane/adapter-codex` | Codex adapter (stdio interactive) |
+| `@workplane/dbos` | Optional DBOS durability layer (step checkpointing + replay) |
+
+## DBOS (optional)
+
+DBOS durability is opt-in. The server boots without it by default:
+
+```bash
+# Default — no DBOS
+workplane-server
+
+# With DBOS durability
+WORKPLANE_USE_DBOS=true workplane-server
+```
+
 ## Personal fleet (home + office)
 
-Run the control plane on an always-on host (VPS, NAS, or home server). Run nodes on each machine where tools or GPUs live. Connect machines with Tailscale, WireGuard, or a trusted LAN.
+Run the control plane on an always-on host (VPS, NAS, or home server). Run nodes on each machine where tools or GPUs live. Nodes poll outbound — no inbound ports required. Use Tailscale, WireGuard, or a trusted LAN.
 
-Set `WORKPLANE_SERVER_URL` to the control plane’s reachable URL on every node and CLI client.
+Set `WORKPLANE_SERVER_URL` to the control plane's reachable address on every node and CLI client.
 
-Full deployment guide: [github.com/MindStaq/workplane/blob/main/docs/deployment/FLEET.md](https://github.com/MindStaq/workplane/blob/main/docs/deployment/FLEET.md)
+Full deployment guide: [docs/deployment/FLEET.md](https://github.com/MindStaq/workplane/blob/main/docs/deployment/FLEET.md)
 
 ## Documentation
 
-- [v0.1.0 specification](https://github.com/MindStaq/workplane/blob/main/docs/specs/v0.1.0/WORKPLANE_SPEC.md)
+- [v0.3.0 specification](https://github.com/MindStaq/workplane/blob/main/docs/specs/v0.3.0/WORKPLANE_SPEC.md)
 - [Source repository](https://github.com/MindStaq/workplane)
 - [Issues](https://github.com/MindStaq/workplane/issues)
 

package/dist/cli.js

@@ -1,4 +1,110 @@
 #!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// ../workplans/src/providers/anthropic.ts
+var anthropic_exports = {};
+__export(anthropic_exports, {
+  runAnthropicStep: () => runAnthropicStep
+});
+import Anthropic from "@anthropic-ai/sdk";
+async function runAnthropicStep(opts) {
+  const client = new Anthropic({ apiKey: opts.apiKey ?? process.env.ANTHROPIC_API_KEY });
+  const message = await client.messages.create({
+    model: opts.model,
+    max_tokens: 4096,
+    messages: [{ role: "user", content: opts.prompt }]
+  });
+  const block = message.content[0];
+  return block.type === "text" ? block.text : "";
+}
+var init_anthropic = __esm({
+  "../workplans/src/providers/anthropic.ts"() {
+    "use strict";
+  }
+});
+
+// ../workplans/src/providers/openai.ts
+var openai_exports = {};
+__export(openai_exports, {
+  runOpenAIStep: () => runOpenAIStep
+});
+import OpenAI from "openai";
+async function runOpenAIStep(opts) {
+  const client = new OpenAI({ apiKey: opts.apiKey ?? process.env.OPENAI_API_KEY });
+  const completion = await client.chat.completions.create({
+    model: opts.model,
+    messages: [{ role: "user", content: opts.prompt }]
+  });
+  return completion.choices[0]?.message.content ?? "";
+}
+var init_openai = __esm({
+  "../workplans/src/providers/openai.ts"() {
+    "use strict";
+  }
+});
+
+// ../workplans/src/providers/ollama.ts
+var ollama_exports = {};
+__export(ollama_exports, {
+  runOllamaStep: () => runOllamaStep
+});
+import { Ollama } from "ollama";
+async function runOllamaStep(opts) {
+  const host = opts.host ?? process.env.OLLAMA_HOST ?? "http://localhost:11434";
+  const client = new Ollama({ host });
+  const response = await client.generate({ model: opts.model, prompt: opts.prompt });
+  return response.response;
+}
+var init_ollama = __esm({
+  "../workplans/src/providers/ollama.ts"() {
+    "use strict";
+  }
+});
+
+// ../workplans/src/providers/shell.ts
+var shell_exports = {};
+__export(shell_exports, {
+  runShellStep: () => runShellStep
+});
+import { exec } from "child_process";
+import { promisify } from "util";
+async function runShellStep(opts) {
+  const { stdout } = await execAsync(opts.command, {
+    cwd: opts.cwd,
+    maxBuffer: 10 * 1024 * 1024
+  });
+  return stdout;
+}
+var execAsync;
+var init_shell = __esm({
+  "../workplans/src/providers/shell.ts"() {
+    "use strict";
+    execAsync = promisify(exec);
+  }
+});
+
+// ../workplans/src/providers/file.ts
+var file_exports = {};
+__export(file_exports, {
+  runFileStep: () => runFileStep
+});
+import { readFile } from "fs/promises";
+async function runFileStep(opts) {
+  return readFile(opts.path, opts.encoding ?? "utf8");
+}
+var init_file = __esm({
+  "../workplans/src/providers/file.ts"() {
+    "use strict";
+  }
+});
 
 // ../core/src/env.ts
 import { config as dotenvConfig } from "dotenv";
@@ -64,6 +170,292 @@ async function workplaneFetch(serverUrl2, path, options = {}) {
   return await response.json();
 }
 
+// ../agent-skills/src/skills/code-review.ts
+function codeReviewPlan(opts = {}) {
+  const { repoPath = ".", model = "claude-haiku-4-5-20251001", branch } = opts;
+  const diffCmd = branch ? `git diff ${branch}..HEAD` : "git diff HEAD~1";
+  return {
+    id: "code-review",
+    name: "Code Review",
+    steps: [
+      {
+        id: "diff",
+        name: "Git Diff",
+        adapter: "shell",
+        provider: "shell",
+        payload: { command: diffCmd, cwd: repoPath },
+        output: { dest: "next" }
+      },
+      {
+        id: "summarize",
+        name: "Summarize",
+        adapter: "ollama",
+        provider: "ollama",
+        model: "llama3",
+        payload: { prompt: "Summarize these code changes concisely:\n{{prevOutput}}" },
+        output: { dest: "next" }
+      },
+      {
+        id: "critique",
+        name: "Critique",
+        adapter: "anthropic",
+        provider: "anthropic",
+        model,
+        payload: { prompt: "Review this summary for correctness, security issues, and code quality:\n{{prevOutput}}" }
+      }
+    ]
+  };
+}
+
+// ../agent-skills/src/skills/summarize-file.ts
+function summarizeFilePlan(opts) {
+  const { filePath, provider = "ollama", model = "llama3" } = opts;
+  return {
+    id: "summarize-file",
+    name: "Summarize File",
+    steps: [
+      {
+        id: "read",
+        name: "Read File",
+        adapter: "file",
+        provider: "file",
+        payload: { path: filePath },
+        output: { dest: "next" }
+      },
+      {
+        id: "summarize",
+        name: "Summarize",
+        adapter: provider,
+        provider,
+        model,
+        payload: { prompt: "Summarize the following file content concisely:\n{{prevOutput}}" }
+      }
+    ]
+  };
+}
+
+// ../agent-skills/src/skills/index.ts
+var SkillRegistry = class {
+  skills = /* @__PURE__ */ new Map();
+  register(entry) {
+    this.skills.set(entry.name, entry);
+  }
+  get(name) {
+    return this.skills.get(name);
+  }
+  list() {
+    return Array.from(this.skills.values());
+  }
+};
+function createDefaultRegistry() {
+  const registry = new SkillRegistry();
+  registry.register({
+    name: "code-review",
+    description: "Git diff \u2192 local summarize (ollama) \u2192 frontier critique (anthropic)",
+    buildPlan: (opts) => codeReviewPlan({
+      repoPath: typeof opts.repo === "string" ? opts.repo : void 0,
+      model: typeof opts.model === "string" ? opts.model : void 0,
+      branch: typeof opts.branch === "string" ? opts.branch : void 0
+    })
+  });
+  registry.register({
+    name: "summarize-file",
+    description: "Read file \u2192 summarize with configurable provider (default: ollama)",
+    buildPlan: (opts) => {
+      const filePath = typeof opts.file === "string" ? opts.file : "";
+      if (!filePath) throw new Error("--file is required for summarize-file");
+      return summarizeFilePlan({
+        filePath,
+        provider: typeof opts.provider === "string" ? opts.provider : void 0,
+        model: typeof opts.model === "string" ? opts.model : void 0
+      });
+    }
+  });
+  return registry;
+}
+function listSkills(registry) {
+  for (const skill of registry.list()) {
+    process.stdout.write(`  ${skill.name.padEnd(20)} ${skill.description}
+`);
+  }
+}
+
+// ../workplans/src/template.ts
+function applyTemplate(payload, prevOutput) {
+  return Object.fromEntries(
+    Object.entries(payload).map(([k, v]) => [
+      k,
+      typeof v === "string" ? v.replaceAll("{{prevOutput}}", prevOutput) : v
+    ])
+  );
+}
+
+// ../workplans/src/runner.ts
+var INLINE_PROVIDERS = /* @__PURE__ */ new Set(["anthropic", "openai", "ollama", "shell", "file"]);
+async function runInlineStep(step, prompt) {
+  const provider = step.provider;
+  if (provider === "anthropic") {
+    const { runAnthropicStep: runAnthropicStep2 } = await Promise.resolve().then(() => (init_anthropic(), anthropic_exports));
+    return runAnthropicStep2({ model: step.model ?? "claude-haiku-4-5-20251001", prompt });
+  }
+  if (provider === "openai") {
+    const { runOpenAIStep: runOpenAIStep2 } = await Promise.resolve().then(() => (init_openai(), openai_exports));
+    return runOpenAIStep2({ model: step.model ?? "gpt-4o-mini", prompt });
+  }
+  if (provider === "ollama") {
+    const { runOllamaStep: runOllamaStep2 } = await Promise.resolve().then(() => (init_ollama(), ollama_exports));
+    return runOllamaStep2({ model: step.model ?? "llama3", prompt });
+  }
+  if (provider === "shell") {
+    const { runShellStep: runShellStep2 } = await Promise.resolve().then(() => (init_shell(), shell_exports));
+    return runShellStep2({
+      command: String(step.payload.command ?? ""),
+      cwd: typeof step.payload.cwd === "string" ? step.payload.cwd : void 0
+    });
+  }
+  if (provider === "file") {
+    const { runFileStep: runFileStep2 } = await Promise.resolve().then(() => (init_file(), file_exports));
+    return runFileStep2({ path: String(step.payload.path ?? "") });
+  }
+  throw new Error(`unknown inline provider: ${provider}`);
+}
+var SequentialWorkplanRunner = class {
+  async run(plan, ctx) {
+    const results = [];
+    let prevOutput = "";
+    let planSucceeded = true;
+    for (const step of plan.steps) {
+      const payload = prevOutput ? applyTemplate(step.payload, prevOutput) : step.payload;
+      const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
+      const start = Date.now();
+      let output = "";
+      let exitCode = 0;
+      try {
+        if (step.provider && INLINE_PROVIDERS.has(step.provider)) {
+          output = await runInlineStep({ ...step, payload }, prompt);
+        } else {
+          const node = await ctx.resolveNode(step.requires ?? [], step.provider);
+          const result = await node.execute({ ...step, payload });
+          output = result.output;
+          exitCode = result.exitCode;
+        }
+      } catch (err) {
+        exitCode = 1;
+        output = err instanceof Error ? err.message : String(err);
+        planSucceeded = false;
+        const stepResult2 = {
+          stepId: step.id,
+          output,
+          exitCode,
+          durationMs: Date.now() - start
+        };
+        results.push(stepResult2);
+        ctx.emitResult(step.id, step.name, output);
+        if (!step.continueOnError) {
+          return {
+            planId: plan.id,
+            status: "step_failed",
+            steps: results,
+            succeeded: false
+          };
+        }
+        prevOutput = "";
+        continue;
+      }
+      const dest = step.output?.dest ?? "stdout";
+      const stepResult = {
+        stepId: step.id,
+        output,
+        exitCode,
+        durationMs: Date.now() - start
+      };
+      results.push(stepResult);
+      if (dest === "stdout" || dest === "artifact") {
+        ctx.emitResult(step.id, step.name, output);
+        prevOutput = "";
+      } else if (dest === "next") {
+        prevOutput = output;
+      }
+    }
+    return {
+      planId: plan.id,
+      status: planSucceeded ? "completed" : "failed",
+      steps: results,
+      succeeded: planSucceeded
+    };
+  }
+};
+
+// ../workplans/src/sinks/stdout.ts
+function printStepResult(stepName, output) {
+  process.stdout.write(`=== step: ${stepName} ===
+${output}
+
+`);
+}
+
+// ../workplans/src/context.ts
+var WorkplaneNodeHandle = class {
+  constructor(serverUrl2, nodeToken) {
+    this.serverUrl = serverUrl2;
+    this.nodeToken = nodeToken;
+  }
+  serverUrl;
+  nodeToken;
+  async execute(step) {
+    const start = Date.now();
+    const taskRes = await fetch(`${this.serverUrl}/tasks`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${this.nodeToken}`
+      },
+      body: JSON.stringify({
+        kind: "workplan.step",
+        adapter: step.adapter,
+        payload: step.payload,
+        requires: step.requires ?? []
+      })
+    });
+    if (!taskRes.ok) {
+      throw new Error(`failed to submit step ${step.id}: ${taskRes.status}`);
+    }
+    const task = await taskRes.json();
+    const output = await this.pollUntilDone(task.id);
+    return { stepId: step.id, output, exitCode: 0, durationMs: Date.now() - start };
+  }
+  async pollUntilDone(taskId) {
+    const terminalStatuses = /* @__PURE__ */ new Set(["succeeded", "failed", "cancelled"]);
+    for (; ; ) {
+      await new Promise((r) => setTimeout(r, 1e3));
+      const res = await fetch(`${this.serverUrl}/tasks/${taskId}`, {
+        headers: { authorization: `Bearer ${this.nodeToken}` }
+      });
+      const task = await res.json();
+      if (terminalStatuses.has(task.status)) {
+        if (task.status !== "succeeded") {
+          throw new Error(`step task ${taskId} ended with status: ${task.status}`);
+        }
+        return typeof task.payload?.output === "string" ? task.payload.output : "";
+      }
+    }
+  }
+};
+var LocalWorkplanContext = class {
+  serverUrl;
+  nodeToken;
+  constructor(opts = {}) {
+    this.serverUrl = opts.serverUrl ?? process.env.WORKPLANE_SERVER_URL ?? "http://localhost:8787";
+    this.nodeToken = opts.nodeToken ?? process.env.WORKPLANE_NODE_TOKEN ?? "";
+  }
+  async resolveNode(_requires, _provider) {
+    return new WorkplaneNodeHandle(this.serverUrl, this.nodeToken);
+  }
+  emitResult(_stepId, stepName, output) {
+    printStepResult(stepName, output);
+  }
+};
+
 // ../cli/src/index.ts
 loadLocalEnv();
 var serverUrl = process.env.WORKPLANE_SERVER_URL ?? "http://localhost:8787";
@@ -120,7 +512,9 @@ function usage() {
       "  run input <runId> --signal <SIGTERM|SIGKILL|SIGINT>",
       "  run input <runId> --resize <COLSxROWS>",
       "  logs <runId|taskId>",
-      "  artifacts <runId>"
+      "  artifacts <runId>",
+      "  skill list",
+      "  skill run <name> [--key value ...]"
     ].join("\n")
   );
 }
@@ -364,6 +758,41 @@ async function main() {
     printJson(artifacts);
     return;
   }
+  if (command === "skill" && subcommand === "list") {
+    const registry = createDefaultRegistry();
+    process.stdout.write("Available skills:\n");
+    listSkills(registry);
+    return;
+  }
+  if (command === "skill" && subcommand === "run") {
+    const skillName = rest[0];
+    if (!skillName) {
+      throw new Error("skill name is required");
+    }
+    const registry = createDefaultRegistry();
+    const skill = registry.get(skillName);
+    if (!skill) {
+      throw new Error(`unknown skill: ${skillName}. Run 'workplane skill list' to see available skills.`);
+    }
+    const optArgs = rest.slice(1);
+    const options = {};
+    for (let i = 0; i < optArgs.length - 1; i++) {
+      if (optArgs[i].startsWith("--")) {
+        options[optArgs[i].slice(2)] = optArgs[i + 1];
+        i++;
+      }
+    }
+    const plan = skill.buildPlan(options);
+    const runner = new SequentialWorkplanRunner();
+    const ctx = new LocalWorkplanContext();
+    const result = await runner.run(plan, ctx);
+    if (!result.succeeded) {
+      process.stderr.write(`skill '${skillName}' failed at step '${result.steps.at(-1)?.stepId ?? "unknown"}'
+`);
+      process.exit(1);
+    }
+    return;
+  }
   usage();
 }
 main().catch((error) => {