@bastani/atomic 0.7.17-1 → 0.8.0-0

package/dist/builtin/web-access/youtube-extract.ts

@@ -0,0 +1,311 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME } from "@bastani/atomic";
+import { activityMonitor } from "./activity.js";
+import { isGeminiWebAvailable, queryWithCookies } from "./gemini-web.js";
+import { isGeminiApiAvailable, queryGeminiApiWithVideo } from "./gemini-api.js";
+import { searchWithPerplexity } from "./perplexity.js";
+import { extractHeadingTitle, type ExtractedContent, type FrameResult, type VideoFrame } from "./extract.js";
+import { formatSeconds, readExecError, isTimeoutError, trimErrorText, mapFfmpegError } from "./utils.js";
+
+const CONFIG_PATH = join(homedir(), CONFIG_DIR_NAME, "web-search.json");
+
+const YOUTUBE_PROMPT = `Extract the complete content of this YouTube video. Include:
+1. Video title, channel name, and duration
+2. A brief summary (2-3 sentences)
+3. Full transcript with timestamps
+4. Descriptions of any code, terminal commands, diagrams, slides, or UI shown on screen
+
+Format as markdown.`;
+
+const YOUTUBE_REGEX =
+	/(?:(?:www\.|m\.)?youtube\.com\/(?:watch\?.*v=|shorts\/|live\/|embed\/|v\/)|youtu\.be\/)([a-zA-Z0-9_-]{11})/;
+
+function shouldRethrow(err: unknown): boolean {
+	const message = err instanceof Error ? err.message : String(err);
+	return message.startsWith("Failed to parse ");
+}
+
+interface YouTubeConfig {
+	enabled: boolean;
+	preferredModel: string;
+}
+
+function normalizePreferredModel(value: unknown, fallback: string): string {
+	if (typeof value !== "string") return fallback;
+	const normalized = value.trim();
+	return normalized.length > 0 ? normalized : fallback;
+}
+
+function normalizeEnabled(value: unknown, fallback: boolean): boolean {
+	return typeof value === "boolean" ? value : fallback;
+}
+
+const defaults: YouTubeConfig = { enabled: true, preferredModel: "gemini-3-flash-preview" };
+let cachedConfig: YouTubeConfig | null = null;
+
+function loadYouTubeConfig(): YouTubeConfig {
+	if (cachedConfig) return cachedConfig;
+	if (!existsSync(CONFIG_PATH)) {
+		cachedConfig = { ...defaults };
+		return cachedConfig;
+	}
+
+	const rawText = readFileSync(CONFIG_PATH, "utf-8");
+	let raw: { youtube?: { enabled?: boolean; preferredModel?: string } };
+	try {
+		raw = JSON.parse(rawText) as { youtube?: { enabled?: boolean; preferredModel?: string } };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to parse ${CONFIG_PATH}: ${message}`);
+	}
+
+	const yt = raw.youtube ?? {};
+	cachedConfig = {
+		enabled: normalizeEnabled(yt.enabled, defaults.enabled),
+		preferredModel: normalizePreferredModel(yt.preferredModel, defaults.preferredModel),
+	};
+	return cachedConfig;
+}
+
+export function isYouTubeURL(url: string): { isYouTube: boolean; videoId: string | null } {
+	try {
+		const parsed = new URL(url);
+		if (parsed.pathname === "/playlist") {
+			return { isYouTube: false, videoId: null };
+		}
+	} catch {
+	}
+
+	const match = url.match(YOUTUBE_REGEX);
+	if (!match) return { isYouTube: false, videoId: null };
+	return { isYouTube: true, videoId: match[1] };
+}
+
+export function isYouTubeEnabled(): boolean {
+	return loadYouTubeConfig().enabled;
+}
+
+export async function extractYouTube(
+	url: string,
+	signal?: AbortSignal,
+	prompt?: string,
+	model?: string,
+): Promise<ExtractedContent | null> {
+	const config = loadYouTubeConfig();
+	const { videoId } = isYouTubeURL(url);
+	const canonicalUrl = videoId
+		? `https://www.youtube.com/watch?v=${videoId}`
+		: url;
+	const effectivePrompt = prompt ?? YOUTUBE_PROMPT;
+	const effectiveModel = model ?? config.preferredModel;
+
+	const activityId = activityMonitor.logStart({ type: "fetch", url: `youtube.com/${videoId ?? "video"}` });
+
+	const result = await tryGeminiWeb(canonicalUrl, effectivePrompt, effectiveModel, signal)
+		?? await tryGeminiApi(canonicalUrl, effectivePrompt, effectiveModel, signal)
+		?? await tryPerplexity(url, effectivePrompt, signal);
+
+	if (result) {
+		result.url = url;
+		if (videoId) {
+			const thumb = await fetchYouTubeThumbnail(videoId);
+			if (thumb) result.thumbnail = thumb;
+		}
+		activityMonitor.logComplete(activityId, 200);
+		return result;
+	}
+
+	if (signal?.aborted) {
+		activityMonitor.logComplete(activityId, 0);
+		return null;
+	}
+
+	activityMonitor.logError(activityId, "all extraction paths failed");
+	return null;
+}
+
+type StreamInfo = { streamUrl: string; duration: number | null };
+type StreamResult = StreamInfo | { error: string };
+
+function mapYtDlpError(err: unknown): string {
+	const { code, stderr, message } = readExecError(err);
+	if (code === "ENOENT") return "yt-dlp is not installed. Install with: brew install yt-dlp";
+	if (isTimeoutError(err)) return "yt-dlp timed out fetching video info";
+	const lower = stderr.toLowerCase();
+	if (lower.includes("private")) return "Video is private or unavailable";
+	if (lower.includes("sign in")) return "Video is age-restricted and requires authentication";
+	if (lower.includes("not available")) return "Video is unavailable in your region or has been removed";
+	if (lower.includes("live")) return "Cannot extract frames from a live stream";
+	const snippet = trimErrorText(stderr || message);
+	return snippet ? `yt-dlp failed: ${snippet}` : "yt-dlp failed";
+}
+
+export async function getYouTubeStreamInfo(videoId: string): Promise<StreamResult> {
+	try {
+		const output = execFileSync("yt-dlp", [
+			"--print", "duration",
+			"-g", `https://www.youtube.com/watch?v=${videoId}`,
+		], { timeout: 15000, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+		const lines = output.split(/\r?\n/);
+		const rawDuration = lines[0]?.trim();
+		const streamUrl = lines[1]?.trim();
+		if (!streamUrl) return { error: "yt-dlp failed: missing stream URL" };
+		const parsedDuration = rawDuration && rawDuration !== "NA" ? Number.parseFloat(rawDuration) : NaN;
+		const duration = Number.isFinite(parsedDuration) ? parsedDuration : null;
+		return { streamUrl, duration };
+	} catch (err) {
+		return { error: mapYtDlpError(err) };
+	}
+}
+
+async function extractFrameFromStream(streamUrl: string, seconds: number): Promise<FrameResult> {
+	try {
+		const buffer = execFileSync("ffmpeg", [
+			"-ss", String(seconds), "-i", streamUrl,
+			"-frames:v", "1", "-f", "image2pipe", "-vcodec", "mjpeg", "pipe:1",
+		], { maxBuffer: 5 * 1024 * 1024, timeout: 30000, stdio: ["pipe", "pipe", "pipe"] });
+		if (buffer.length === 0) return { error: "ffmpeg failed: empty output" };
+		return { data: buffer.toString("base64"), mimeType: "image/jpeg" };
+	} catch (err) {
+		return { error: mapFfmpegError(err) };
+	}
+}
+
+export async function extractYouTubeFrame(
+	videoId: string,
+	seconds: number,
+	streamInfo?: StreamInfo,
+): Promise<FrameResult> {
+	const info = streamInfo ?? await getYouTubeStreamInfo(videoId);
+	if ("error" in info) return info;
+	return extractFrameFromStream(info.streamUrl, seconds);
+}
+
+export async function extractYouTubeFrames(
+	videoId: string,
+	timestamps: number[],
+	streamInfo?: StreamInfo,
+): Promise<{ frames: VideoFrame[]; duration: number | null; error: string | null }> {
+	const info = streamInfo ?? await getYouTubeStreamInfo(videoId);
+	if ("error" in info) return { frames: [], duration: null, error: info.error };
+	const results = await Promise.all(timestamps.map(async (t) => {
+		const frame = await extractFrameFromStream(info.streamUrl, t);
+		if ("error" in frame) return { error: frame.error };
+		return { ...frame, timestamp: formatSeconds(t) };
+	}));
+	const frames = results.filter((f): f is VideoFrame => "data" in f);
+	const errorResult = results.find((f): f is { error: string } => "error" in f);
+	return { frames, duration: info.duration, error: frames.length === 0 && errorResult ? errorResult.error : null };
+}
+
+export async function fetchYouTubeThumbnail(videoId: string): Promise<{ data: string; mimeType: string } | null> {
+	try {
+		const res = await fetch(`https://img.youtube.com/vi/${videoId}/hqdefault.jpg`, {
+			signal: AbortSignal.timeout(5000),
+		});
+		if (!res.ok) return null;
+		const buffer = Buffer.from(await res.arrayBuffer());
+		if (buffer.length === 0) return null;
+		return { data: buffer.toString("base64"), mimeType: "image/jpeg" };
+	} catch {
+		return null;
+	}
+}
+
+async function tryGeminiWeb(
+	url: string,
+	prompt: string,
+	model: string,
+	signal?: AbortSignal,
+): Promise<ExtractedContent | null> {
+	try {
+		const cookies = await isGeminiWebAvailable();
+		if (!cookies) return null;
+
+		if (signal?.aborted) return null;
+
+		const text = await queryWithCookies(prompt, cookies, {
+			youtubeUrl: url,
+			model,
+			signal,
+			timeoutMs: 120000,
+		});
+
+		return {
+			url,
+			title: extractHeadingTitle(text) ?? "YouTube Video",
+			content: text,
+			error: null,
+		};
+	} catch (err) {
+		if (shouldRethrow(err)) throw err;
+		return null;
+	}
+}
+
+async function tryGeminiApi(
+	url: string,
+	prompt: string,
+	model: string,
+	signal?: AbortSignal,
+): Promise<ExtractedContent | null> {
+	try {
+		if (!isGeminiApiAvailable()) return null;
+
+		if (signal?.aborted) return null;
+
+		const text = await queryGeminiApiWithVideo(prompt, url, {
+			model,
+			signal,
+			timeoutMs: 120000,
+		});
+
+		return {
+			url,
+			title: extractHeadingTitle(text) ?? "YouTube Video",
+			content: text,
+			error: null,
+		};
+	} catch (err) {
+		if (shouldRethrow(err)) throw err;
+		return null;
+	}
+}
+
+async function tryPerplexity(
+	url: string,
+	prompt: string,
+	signal?: AbortSignal,
+): Promise<ExtractedContent | null> {
+	try {
+		if (signal?.aborted) return null;
+
+		const perplexityQuery = prompt === YOUTUBE_PROMPT
+			? `Summarize this YouTube video in detail: ${url}`
+			: `${prompt} YouTube video: ${url}`;
+
+		const { answer } = await searchWithPerplexity(
+			perplexityQuery,
+			{ signal },
+		);
+
+		if (!answer) return null;
+
+		const content =
+			`# Video Summary (via Perplexity)\n\n${answer}\n\n` +
+			`*Full video understanding requires Gemini access. Set GEMINI_API_KEY or sign into Google in Chrome.*`;
+
+		return {
+			url,
+			title: "Video Summary (via Perplexity)",
+			content,
+			error: null,
+		};
+	} catch (err) {
+		if (shouldRethrow(err)) throw err;
+		return null;
+	}
+}

package/dist/builtin/workflows/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] — 2026-05-15
+
+### Added
+
+- Initial release of `@bastani/workflows`, a raw TypeScript pi package for multi-stage workflow authoring and execution.
+- pi extension entry point at `src/extension/index.ts` registered through the package `pi` manifest.
+- Public authoring API with `defineWorkflow`, `createRegistry`, workflow identity helpers, and programmatic workflow runners.
+- `workflow` LLM tool and `/workflow` slash command surface for listing, inspecting, running, interrupting, and resuming workflows.
+- Background workflow execution with persisted run/stage state, status rendering, cancellation, pause/resume support, and HIL prompt routing.
+- TUI surfaces for live workflow progress, graph overlays, run details, stage chat, input collection, and status widgets.
+- Workflow discovery from bundled workflows, project-local `.atomic/workflows/`, user-global `~/.atomic/agent/workflows/`, and configured workflow directories.
+- Built-in workflows: `deep-research-codebase`, `open-claude-design`, and `ralph`.
+- Optional runtime integrations with companion pi packages including `pi-subagents`, `pi-mcp-adapter`, `pi-intercom`, and `pi-web-access`.
+- Bundled skills, agents, themes, examples, and documentation for authoring and operating workflows.

package/dist/builtin/workflows/README.md

@@ -0,0 +1,323 @@
+<h1 align="center">Atomic Workflows</h1>
+
+<p align="center">
+  <b>Turn coding agents into reliable engineering workflows.</b><br>
+  An open-source pi extension: install it, author workflows in TypeScript, run them from chat.
+</p>
+
+<p align="center">
+  <a href="#authoring-api">Authoring API</a>
+  &nbsp;·&nbsp;
+  <a href="#surfaces">Surfaces</a>
+  &nbsp;·&nbsp;
+  <a href="#builtin-workflows">Builtins</a>
+  &nbsp;·&nbsp;
+</p>
+
+
+### Custom workflow directories
+
+Adding workflow files under `.atomic/workflows/` (project scope) or `~/.atomic/agent/workflows/` (user scope) makes them discoverable automatically. To register additional discovery paths, add a workflow extension config file at `.atomic/extensions/workflow/config.json` for a project or `~/.atomic/agent/extensions/workflow/config.json` for your user account:
+
+```json
+{
+  "workflows": {
+    "team": { "path": "/shared/team/workflows" }
+  }
+}
+```
+
+---
+
+## Authoring API
+
+### Example 1 — Single task
+
+```typescript
+import { defineWorkflow } from "@bastani/workflows";
+
+export default defineWorkflow("summarize-pr")
+  .description("Summarize a pull request in one task.")
+  .input("pr_url", {
+    type: "text",
+    required: true,
+    description: "URL of the pull request to summarize.",
+  })
+  .run(async (ctx) => {
+    const summary = await ctx.task("summarize", {
+      prompt: `Summarize the pull request at ${String(ctx.inputs.pr_url)} clearly and concisely.`,
+    });
+    return { summary: summary.text };
+  })
+  .compile();
+```
+
+### Example 2 — Parallel fan-out with `ctx.parallel`
+
+Use `ctx.parallel` for independent specialist work. The aggregator receives the specialist outputs through typed task results instead of manual stage/session plumbing.
+
+```typescript
+import { defineWorkflow } from "@bastani/workflows";
+
+export default defineWorkflow("parallel-research")
+  .description("Scout → three parallel specialists → aggregator.")
+  .input("topic", { type: "text", required: true, description: "Research topic." })
+  .run(async (ctx) => {
+    const { topic } = ctx.inputs as { topic: string };
+
+    const reports = await ctx.parallel([
+      { name: "auth-specialist", task: `Research authentication patterns for: ${topic}` },
+      { name: "db-specialist", task: `Research database layer for: ${topic}` },
+      { name: "api-specialist", task: `Research API surface for: ${topic}` },
+    ]);
+
+    const summary = await ctx.task("aggregator", {
+      prompt: "Synthesize these specialist reports:\n\n{previous}",
+      previous: reports,
+    });
+    return { summary: summary.text };
+  })
+  .compile();
+```
+
+### Example 3 — Human-in-the-loop (HIL)
+
+```typescript
+import { defineWorkflow } from "@bastani/workflows";
+
+export default defineWorkflow("review-and-merge")
+  .description("Plan a change, ask for human approval, then execute.")
+  .input("task", { type: "text", required: true, description: "What to implement." })
+  .run(async (ctx) => {
+    const plan = await ctx.task("planner", {
+      prompt: `Create a concise implementation plan for: ${String(ctx.inputs.task)}`,
+    });
+
+    const approved = await ctx.ui.confirm(`Proceed with this plan?\n\n${plan.text}`);
+    if (!approved) return { status: "cancelled" };
+
+    const result = await ctx.task("implementer", {
+      prompt: "Execute this plan exactly:\n\n{previous}",
+      previous: plan,
+    });
+    return { result: result.text };
+  })
+  .compile();
+```
+
+### Model fallbacks
+
+Stages and high-level task helpers can retry transient provider/model failures with an ordered `fallbackModels` list. The primary `model` is tried first, then each fallback, and finally the current pi-selected model when available. Fallbacks are only used for retryable model/provider failures such as rate limits, quota/auth/provider outages, unavailable models, network timeouts, and 5xx errors — ordinary tool, shell, validation, cancellation, and workflow-code failures are not retried.
+
+```typescript
+import { defineWorkflow } from "@bastani/workflows";
+
+export default defineWorkflow("fallback-review")
+  .description("Review with a model fallback chain.")
+  .input("topic", { type: "text", required: true })
+  .run(async (ctx) => {
+    const review = await ctx.task("reviewer", {
+      prompt: `Review this topic: ${String(ctx.inputs.topic)}`,
+      model: "anthropic/claude-sonnet-4",
+      fallbackModels: ["openai/gpt-5-mini", "github-copilot/gpt-5-mini"],
+    });
+
+    return {
+      review: review.text,
+      model: review.model,
+      attemptedModels: review.attemptedModels,
+      modelAttempts: review.modelAttempts,
+    };
+  })
+  .compile();
+```
+
+Direct helpers and workflow tool direct modes can set task-local fallbacks or a top-level default:
+
+```typescript
+await runParallel([
+  { name: "runtime-review", task: "Review runtime changes", model: "anthropic/claude-sonnet-4" },
+  { name: "quality-review", task: "Review quality risks", fallbackModels: ["openai/gpt-5-mini"] },
+], {
+  fallbackModels: ["github-copilot/gpt-5-mini"],
+});
+```
+
+When pi exposes its model registry, workflow runs validate user-specified `model` / `fallbackModels` before starting model-backed work and report all unavailable or ambiguous IDs together. Bare model IDs are accepted only when they resolve uniquely or match the current provider; otherwise use `provider/model`. Fallback attempts may send the same prompt/context to a different provider, so choose fallbacks that fit your cost, privacy, and data-handling requirements.
+
+### `createRegistry` — grouping workflows
+
+```typescript
+import { createRegistry, defineWorkflow } from "@bastani/workflows";
+
+const alpha = defineWorkflow("alpha").run(async () => {}).compile();
+const beta  = defineWorkflow("beta").run(async () => {}).compile();
+const gamma = defineWorkflow("gamma").run(async () => {}).compile();
+
+const registry = createRegistry()
+  .register(alpha)
+  .register(beta)
+  .merge(createRegistry().register(gamma));
+
+registry.names();      // ["alpha", "beta", "gamma"]
+registry.all();        // compiled workflow definitions
+registry.get("alpha"); // compiled workflow definition | undefined
+```
+
+### Input types
+
+| Type      | Description        | Extra options                              |
+| --------- | ------------------ | ------------------------------------------ |
+| `text`    | Free-form string   | `default`, `required`                      |
+| `string`  | Alias for `text`   | `default`, `required`                      |
+| `number`  | Numeric value      | `default`, `required`                      |
+| `boolean` | True/false toggle  | `default`, `required`                      |
+| `select`  | Enumerated choices | `choices: string[]`, `default`, `required` |
+
+---
+
+## Surfaces
+
+### Slash commands
+
+| Command                               | Description                                              |
+| ------------------------------------- | -------------------------------------------------------- |
+| `/workflow <name> [key=value ...]`    | Start a named workflow, passing optional input overrides |
+| `/workflow <name> --help`             | Print the workflow's input schema                        |
+| `/workflow list`                      | List all registered workflows with descriptions          |
+| `/workflow status [run-id]`           | Show active runs or details for one run                  |
+| `/workflow connect [run-id]`          | Attach to a workflow run overlay                         |
+| `/workflow attach [run-id] [stage]`   | Open the attach/chat pane for a run or stage             |
+| `/workflow pause [run-id] [stage]`    | Pause a live run or stage                                |
+| `/workflow interrupt [run-id\|--all]` | Stop the active run, a named run, or all active runs     |
+| `/workflow resume <run-id>`           | Resume paused work or re-open a run snapshot             |
+| `/workflow inputs <name>`             | Print the input schema for a workflow                    |
+
+Input overrides are bare `key=value` tokens (no leading `--`). Values are JSON-parsed when possible, so numbers, booleans, and quoted strings work as expected (e.g. `count=3`, `flag=true`, `prompt="multi word value"`). A whole-object override can be passed as a single JSON token (e.g. `{"prompt":"...","count":3}`).
+
+Workflows always run as **background tasks** — the chat editor stays free while a run executes. Press **F2** (or `/workflow connect <run-id>`) to attach to the live graph viewer; HIL prompts (`ctx.ui.input/confirm/select/editor`) surface there, never as modal dialogs over the chat.
+
+### `workflow` tool (LLM-callable)
+
+```json
+{
+  "name": "workflow",
+  "description": "Run a defined multi-stage workflow by name.",
+  "parameters": {
+    "workflow": "string (optional) — workflow ID or normalized name",
+    "inputs": "object (optional) — key/value map of workflow inputs",
+    "action": "'run' | 'list' | 'get' | 'inputs' | 'status' | 'interrupt' | 'resume'",
+    "task/tasks/chain": "optional direct workflow-native orchestration modes"
+  }
+}
+```
+
+- **`renderCall`** — renders a compact workflow call summary in the chat scroll.
+- **`renderResult`** — renders the result or dispatch banner; live progress continues through the widget and graph viewer. Named workflow runs are background-oriented.
+
+### F2 keyboard shortcut
+
+Press **F2** while a workflow is running to open the DAG overlay for the active run.
+
+### Execution model
+
+`@bastani/workflows` follows pi's package/extension model: pi loads `src/extension/index.ts` from the package `pi.extensions` manifest, then the extension registers the `workflow` tool, `/workflow` slash command, renderers, widget, and lifecycle hooks in-process.
+
+For interactive use, run workflows through `/workflow <name> [key=value ...]` or let the LLM call the `workflow` tool. For library or scripted use, call the explicit programmatic runner:
+
+```ts
+import { runWorkflow, type WorkflowOptions } from "@bastani/workflows";
+
+const definition = {
+  mode: "workflow",
+  workflow: "deep-research-codebase",
+  inputs: {
+    prompt: "Investigate the auth module",
+    max_partitions: 6,
+  },
+} as const;
+
+const options: WorkflowOptions = {};
+
+await runWorkflow(definition, options);
+```
+
+To inspect a workflow's input schema inside pi, use `/workflow inputs <name>` or `/workflow <name> --help`.
+
+---
+
+## Builtin workflows
+
+### `deep-research-codebase`
+
+Scout + research-history chain → two parallel specialist waves → aggregator. Ideal for deep investigation of a codebase topic across locator, pattern, analyzer, and ecosystem angles.
+
+```text
+/workflow deep-research-codebase prompt="How does session persistence work?"
+```
+
+| Input            | Type     | Required | Default | Description                                       |
+| ---------------- | -------- | -------- | ------- | ------------------------------------------------- |
+| `prompt`         | `text`   | ✓        | —       | Research question or topic to investigate.        |
+| `max_partitions` | `number` | —        | `100`   | Maximum number of codebase partitions to explore. |
+
+### `ralph`
+
+Plan → orchestrate → simplify → infrastructure discovery → parallel review loop. Named after the [Ralph Wiggum Method](https://ghuntley.com/ralph/).
+
+```text
+/workflow ralph prompt="Migrate the database layer to Drizzle ORM"
+```
+
+| Input       | Type     | Required | Default | Description                                |
+| ----------- | -------- | -------- | ------- | ------------------------------------------ |
+| `prompt`    | `text`   | ✓        | —       | High-level task or goal to accomplish.     |
+| `max_loops` | `number` | —        | `10`    | Maximum plan → orchestrate → review loops. |
+
+### `open-claude-design`
+
+Design-system onboarding → reference import → generation → refinement → export/handoff pipeline.
+
+```text
+/workflow open-claude-design prompt="Design a kanban board" output_type=prototype
+```
+
+| Input             | Type     | Required | Default     | Description                                                          |
+| ----------------- | -------- | -------- | ----------- | -------------------------------------------------------------------- |
+| `prompt`          | `text`   | ✓        | —           | Design brief or description.                                         |
+| `reference`       | `text`   | —        | —           | Optional URL, path, screenshot, or design doc.                       |
+| `output_type`     | `select` | —        | `prototype` | `prototype`, `wireframe`, `page`, `component`, `theme`, or `tokens`. |
+| `design_system`   | `text`   | —        | —           | Existing design-system reference / Design.md path.                   |
+| `max_refinements` | `number` | —        | `3`         | Maximum critique/apply refinement iterations.                        |
+
+---
+
+## Custom workflow discovery
+
+`@bastani/workflows` automatically discovers workflow files from three locations:
+
+| Location                          | Scope      | Example path                               |
+| --------------------------------- | ---------- | ------------------------------------------ |
+| `.atomic/workflows/*.ts`          | Project    | `.atomic/workflows/my-workflow.ts`         |
+| `~/.atomic/agent/workflows/*.ts`  | User       | `~/.atomic/agent/workflows/my-workflow.ts` |
+| `workflows.<name>.path` in config | Configured | see config example below                   |
+
+Config-based discovery (`~/.atomic/agent/extensions/workflow/config.json` or `.atomic/extensions/workflow/config.json`):
+
+```json
+{
+  "workflows": {
+    "my-team-workflows": { "path": "/shared/team/workflows" }
+  }
+}
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+**Development:** see [DEV_SETUP.md](../../DEV_SETUP.md) for setup, testing, layout, and the local-extension dev loop.