@bastani/atomic 0.8.1 → 0.8.2

package/dist/builtin/workflows/skills/workflow/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: workflow
-description: Create, run, inspect, and improve pi/atomic workflows. Use whenever the user wants a reusable multi-stage automation, DAG or staged agent pipeline, workflow definition, defineWorkflow file, ctx.task/ctx.parallel/ctx.chain/ctx.stage orchestration, /workflow run/status/resume help, custom workflow discovery, or context-engineered multi-session process.
+description: Create, run, inspect, and improve pi/atomic workflows. Use whenever the user wants reusable multi-stage automation, a DAG or staged agent pipeline, workflow definitions with defineWorkflow, ctx.task/ctx.parallel/ctx.chain/ctx.stage/ctx.ui orchestration, workflow tool calls, /workflow list/inputs/connect/attach/pause/resume/status help, custom workflow discovery, model fallback chains, or context-engineered multi-session processes.
 ---
 
 # Workflow Skill
 
-You help users create and operate pi/atomic workflows. A workflow is a reusable TypeScript definition that orchestrates named stages, parallel branches, handoffs, artifacts, user-input prompts, status UI, and resumable runs through pi's workflow extension.
+You help users create and operate pi/atomic workflows. A workflow is a reusable TypeScript definition that orchestrates named stages, parallel branches, handoffs, artifacts, human-in-the-loop prompts, live graph/status UI, attachable stage chats, model fallback chains, and resumable background runs through pi's workflow extension.
 
 This skill is for people using workflows. Default to helping users author workflow definitions and run them through pi. Only discuss package implementation details if the user explicitly asks to modify the `@bastani/workflows` package itself.
 
 Use this skill for two user journeys:
 
-1. **Run or inspect an existing workflow** — use the workflow tool or `/workflow` surface. Load `references/running-workflows.md`.
+1. **Run, inspect, attach to, pause, or resume an existing workflow** — use the workflow tool or `/workflow` surface. Load `references/running-workflows.md`.
 2. **Create or edit a workflow definition** — design the information flow, then author a `defineWorkflow(...).run(...).compile()` TypeScript file. Load `references/sdk-authoring.md` and `references/design-checklist.md`.
 
 ## Reference Files
@@ -20,8 +20,8 @@ Load references on demand. Keep this file lean; put details in references.
 
 | File | Load when |
 | --- | --- |
-| `references/sdk-authoring.md` | Creating/editing workflow definition files, inputs, `ctx.task`, `ctx.parallel`, `ctx.chain`, `ctx.stage`, or programmatic runner usage. |
-| `references/running-workflows.md` | Running, monitoring, interrupting, resuming, or inspecting workflows. |
+| `references/sdk-authoring.md` | Creating/editing workflow definition files, inputs, `ctx.task`, `ctx.parallel`, `ctx.chain`, `ctx.stage`, `ctx.ui`, model fallbacks, registries, or programmatic runner usage. |
+| `references/running-workflows.md` | Running, monitoring, connecting/attaching, pausing, interrupting, resuming, or inspecting workflows. |
 | `references/design-checklist.md` | Before implementing or shipping any non-trivial workflow. |
 | `references/context-engineering.md` | Any multi-stage or multi-agent workflow; routes to copied context-engineering references. |
 | `references/context-engineering/context-fundamentals.md` | Prompt/context basics, token budgeting, prompt placement, progressive disclosure. |
@@ -42,9 +42,9 @@ Load references on demand. Keep this file lean; put details in references.
 
 Classify the user's ask before acting:
 
-- **Run**: "run workflow X", "kick off ralph", "is it done?", "resume", "interrupt", "status", "what inputs does it need?" → load `references/running-workflows.md`; list/inspect first if needed; execute rather than merely printing commands when tools allow.
-- **Author**: "create a workflow", "turn this process into a workflow", "add a stage", "make a reusable workflow", "defineWorkflow", "ctx.parallel", "workflow schema" → load `references/sdk-authoring.md`; design before coding.
-- **Design/architecture**: "make this workflow robust", "multi-agent pipeline", "context handoff", "review/fix loop" → load `references/design-checklist.md` and `references/context-engineering.md` before writing code.
+- **Run**: "run workflow X", "kick off ralph", "is it done?", "resume", "interrupt", "pause", "attach", "status", "what inputs does it need?" → load `references/running-workflows.md`; list/inspect first if needed; execute rather than merely printing commands when tools allow.
+- **Author**: "create a workflow", "turn this process into a workflow", "add a stage", "make a reusable workflow", "defineWorkflow", "ctx.parallel", "ctx.ui", "workflow schema" → load `references/sdk-authoring.md`; design before coding.
+- **Design/architecture**: "make this workflow robust", "multi-agent pipeline", "context handoff", "review/fix loop", "fallback models", "human approval gate" → load `references/design-checklist.md` and `references/context-engineering.md` before writing code.
 
 ## Running Existing Workflows
 
@@ -52,8 +52,9 @@ Inspect before running unfamiliar named workflows:
 
 ```ts
 workflow({ action: "list" })
+workflow({ action: "get", workflow: "deep-research-codebase" })
 workflow({ action: "inputs", workflow: "deep-research-codebase" })
-workflow({ workflow: "deep-research-codebase", inputs: { prompt: "map workflow runtime" } })
+workflow({ action: "run", workflow: "deep-research-codebase", inputs: { prompt: "map workflow runtime" } })
 ```
 
 Slash equivalents:
@@ -61,13 +62,18 @@ Slash equivalents:
 ```text
 /workflow list
 /workflow inputs deep-research-codebase
+/workflow deep-research-codebase --help
 /workflow deep-research-codebase prompt="map src" max_partitions=2
+/workflow connect <run-id>
+/workflow attach <run-id> <stage-id-or-name>
+/workflow pause <run-id> [stage-id-or-name]
 /workflow status --all
 /workflow status <run-id>
-/workflow resume <run-id>
+/workflow interrupt <run-id|--all>
+/workflow resume <run-id> [stage-id-or-name] [message]
 ```
 
-Named workflow dispatch is background-oriented: expect a run id and then monitor status/attention states.
+Named workflow dispatch is always background-oriented: expect a run id, then monitor status/attention states. Press F2 or run `/workflow connect <run-id>` to open the live graph viewer. HIL prompts from `ctx.ui.input/confirm/select/editor` appear in that workflow UI, not as modal chat dialogs.
 
 ## Direct Workflow-Native Orchestration
 
@@ -129,8 +135,9 @@ Task options mirror pi session options plus workflow-owned fields such as `outpu
 
 For user-authored workflows, place definitions where pi discovers them:
 
-- Project-local: `.atomic/workflows/*.ts` inside the current project.
-- User-global: `~/.atomic/agent/workflows/*.ts` for workflows available across projects.
+- Project-local: `.atomic/workflows/*.{ts,js,mjs,cjs}` inside the current project. Legacy `.pi/workflows/` is also checked for compatibility.
+- User-global: `~/.atomic/agent/workflows/*.{ts,js,mjs,cjs}` for workflows available across projects. Legacy `~/.pi/agent/workflows/` is also checked.
+- Configured directories: `.atomic/extensions/workflow/config.json` or `~/.atomic/agent/extensions/workflow/config.json` may add named `workflows.<name>.path` entries; legacy `.pi/...` config paths are also considered.
 - Package workflows: a pi package can expose bundled workflow directories through `package.json` under `pi.builtin`.
 
 If an existing project has workflow examples, inspect those first for import style and naming conventions. In a normal consumer project, import from the package:
@@ -169,7 +176,7 @@ export default defineWorkflow("explain-file")
   .input("path", { type: "text", required: true, description: "File path to explain." })
   .run(async (ctx) => {
     const explanation = await ctx.task("explain", {
-      task: `Read ${ctx.inputs.path} and explain purpose, risks, and key symbols.`,
+      prompt: `Read ${String(ctx.inputs.path)} and explain purpose, risks, and key symbols.`,
       context: "fresh",
     });
 
@@ -186,7 +193,7 @@ Builder rules:
 - `.run(async (ctx) => ({ ... }))` defines the workflow body.
 - `.compile()` returns the workflow definition for discovery.
 
-Input types: `text`, `string`, `number`, `boolean`, `select`. All support `description` and `required`; defaults are type-specific; `select` requires `choices`.
+Input types: `text`, `string`, `number`, `boolean`, `select`. All support `description` and `required`; defaults are type-specific; `select` requires `choices`. Runtime validation rejects unknown keys, missing required values, type mismatches, and select values outside `choices`.
 
 ### 4. Pick the right primitive
 
@@ -196,7 +203,7 @@ Input types: `text`, `string`, `number`, `boolean`, `select`. All support `descr
 | Independent branches | `ctx.parallel(steps, { task? })` |
 | Dependent stages | `ctx.chain(steps, { task? })` |
 | Low-level session controls | `ctx.stage(name, options)` then `stage.prompt/complete` |
-| User interaction during run | `ctx.ui` primitives |
+| User interaction during run | `ctx.ui.input/confirm/select/editor` |
 | Pure computation / file I/O / parsing | Plain TypeScript in `.run()` or helpers |
 
 Use `previous` plus `{previous}` for context handoff. If no placeholder is present, the runtime appends context. Chain defaults: first missing task uses `{task}`, later missing tasks use `{previous}`, and missing tasks inside chain-parallel groups use `{previous}`.
@@ -220,8 +227,9 @@ Prefer concise structured returns and durable artifacts over dumping full transc
 
 Use these supported workflow surfaces:
 
-- `/workflow <name> key=value ...` for interactive pi use.
-- The `workflow` tool for LLM-initiated orchestration.
+- `/workflow <name> key=value ...` for interactive pi use; omit required args to open the input picker when the TUI is available.
+- `/workflow connect|attach|pause|interrupt|resume|status|inputs` for live control and inspection.
+- The `workflow` tool for LLM-initiated orchestration and direct one-off task/parallel/chain runs.
 - `runWorkflow(definition)` for explicit library/script usage.
 
 Programmatic runner example:
@@ -245,10 +253,10 @@ await runWorkflow(definition, options);
 
 ## Safety and Compatibility Rules
 
-- Do not fabricate workflow names or inputs; list/inspect first.
+- Do not fabricate workflow names or inputs; list/inspect first with `list`, `get`, or `inputs`.
 - Do not use legacy workflow tool fields such as `agent`, `stage`, or run-control `name`.
 - Do not expect workflow-tool `create`, `update`, or `delete`; reusable definitions are code-authored.
-- Use `/workflow` slash commands for named runs, inspection, status, and diagnostics.
+- Use `/workflow` slash commands for named runs, input picker/help, graph attach, pause/resume, status, and diagnostics.
 - Prefer `ctx.task`, `ctx.parallel`, and `ctx.chain`; drop to `ctx.stage` only for lower-level controls.
 - Keep stage names user-readable because they appear in workflow status/UI.
 - Put deterministic code outside standalone stages.

package/dist/builtin/workflows/skills/workflow/references/design-checklist.md

@@ -13,7 +13,8 @@ Use this before implementing or shipping a non-trivial workflow.
 
 - Declare every user-provided value as an input.
 - Pick the narrowest schema type: `text`, `string`, `number`, `boolean`, or `select`.
-- Add useful descriptions; set defaults only when safe.
+- Add useful descriptions because `/workflow inputs`, `--help`, and the input picker show them.
+- Set defaults only when safe; remember runtime validation rejects unknown keys, missing required values, wrong types, and invalid `select` choices.
 - Validate risky input combinations before starting expensive stages.
 
 ## 3. Stage decomposition
@@ -26,7 +27,7 @@ For each planned stage, write:
 - input context required
 - output artifact/result shape
 - model/thinking/tool/MCP needs
-- failure mode and retry/fallback behavior
+- failure mode and retry/fallback behavior, including whether `fallbackModels` is appropriate
 
 Avoid stages that only do filesystem, parsing, git, or formatting work.
 
@@ -58,7 +59,8 @@ Load `context-engineering.md` and relevant detailed references. At minimum consi
 
 - Use `ctx.chain` for dependent steps.
 - Use `ctx.parallel` for independent branches.
-- Use `concurrency` limits for large fan-outs.
+- Use `ctx.ui.input/confirm/select/editor` for real human decisions or missing information during a run.
+- Use direct-mode `concurrency` limits when available; for authored `ctx.parallel(...)`, keep fan-outs intentionally bounded because the high-level primitive currently runs its steps together.
 - Use `failFast` deliberately where available.
 - Use loops only with clear bounds and termination criteria.
 - Use `fallbackModels` for critical expensive stages when model availability is uncertain.
@@ -68,7 +70,8 @@ Load `context-engineering.md` and relevant detailed references. At minimum consi
 - Name stages so they make sense in workflow UI/status.
 - Return a compact structured output at the end.
 - Save important artifacts with stable paths.
-- Surface HIL/attention states promptly.
+- Surface HIL/attention states promptly and tell users to open F2 or `/workflow connect <run-id>` when input is needed.
+- Make attachable stage names clear enough for `/workflow attach <run-id> <stage>`.
 - Include enough progress and output for resumed/inspected runs.
 
 ## 8. Final sanity pass
@@ -77,3 +80,4 @@ Load `context-engineering.md` and relevant detailed references. At minimum consi
 - Confirm every required input is declared and described.
 - Confirm every stage name is user-readable in `/workflow status` and the graph UI.
 - Confirm the workflow uses a supported surface: `/workflow`, the `workflow` tool, or explicit `runWorkflow(...)` objects.
+- Confirm any required live controls are represented accurately: `connect`/`attach`/`pause` are slash/TUI controls; tool controls cover status/interrupt/resume.

package/dist/builtin/workflows/skills/workflow/references/running-workflows.md

@@ -1,22 +1,27 @@
 # Running and Inspecting Pi Workflows
 
-Use this when the user asks to run, start, kick off, monitor, interrupt, resume, attach to, or inspect a workflow.
+Use this when the user asks to run, start, kick off, monitor, connect to, attach to, pause, interrupt, resume, or inspect a workflow.
 
 ## Discover first
 
-For named workflows, do not guess the schema:
+For named workflows, do not guess names or schemas:
 
 ```ts
 workflow({ action: "list" })
+workflow({ action: "get", workflow: "<name>" })
 workflow({ action: "inputs", workflow: "<name>" })
 ```
 
 If required inputs are missing and cannot be inferred, ask the user with `ask_user_question` or a concise free-form question.
 
-## Run
+## Run named workflows
 
 ```ts
-workflow({ workflow: "deep-research-codebase", inputs: { prompt: "map workflow dispatch" } })
+workflow({
+  action: "run",
+  workflow: "deep-research-codebase",
+  inputs: { prompt: "map workflow dispatch" },
+})
 ```
 
 Slash equivalent:
@@ -25,62 +30,84 @@ Slash equivalent:
 /workflow deep-research-codebase prompt="map workflow dispatch"
 ```
 
-Named workflow dispatch is background-oriented: expect a run id and then monitor status.
+Input overrides are bare `key=value` tokens. Values are JSON-parsed when possible, so `count=3`, `flag=true`, and `prompt="multi word value"` preserve useful types. A whole input object can also be passed as one JSON token.
+
+Named workflow dispatch is always background-oriented: expect a run id and then monitor status. Press F2 or use `/workflow connect <run-id>` to attach to the graph viewer. If the TUI is available and required inputs are missing, `/workflow <name>` opens an input picker unless the user passes `--no-picker`.
+
+## Slash command surface
+
+```text
+/workflow list
+/workflow inputs <name>
+/workflow <name> --help
+/workflow <name> [key=value ...]
+/workflow connect [run-id]
+/workflow attach [run-id] [stage-id-or-name]
+/workflow pause [run-id] [stage-id-or-name]
+/workflow status [run-id]
+/workflow status --all
+/workflow interrupt <run-id|--all>
+/workflow resume <run-id> [stage-id-or-name] [message]
+```
+
+Use `connect` for the orchestrator graph. Use `attach` when the user wants to open a chat pane for a specific stage. Use `pause`/`resume` for live paused work; `resume` on a non-paused run reopens the saved snapshot/overlay.
+
+Human-in-the-loop prompts from `ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, and `ctx.ui.editor` surface in the workflow UI/graph viewer, not as ordinary chat modals.
 
 ## Direct runs
 
-Use direct workflow-native orchestration for one-off tracked work:
+Use direct workflow-native orchestration for one-off tracked work that does not need a reusable workflow file.
+
+Single tracked task:
 
 ```ts
 workflow({
   task: { name: "review", task: "Review this patch for API risks." },
   async: true,
-  intercom: { delivery: "result" }
+  intercom: { delivery: "result" },
 })
 ```
 
-Parallel:
+Parallel fan-out:
 
 ```ts
 workflow({
   tasks: [
     { name: "docs", task: "Review documentation gaps" },
-    { name: "risks", task: "Review operational risks" }
+    { name: "risks", task: "Review operational risks" },
   ],
   concurrency: 2,
-  outputMode: "file-only"
+  outputMode: "file-only",
+  async: true,
 })
 ```
 
-Chain:
+Dependent chain:
 
 ```ts
 workflow({
   task: "Design the workflow SDK migration",
   chain: [
     { name: "research", task: "Research {task}" },
-    { name: "plan", task: "Plan from {previous}" }
-  ]
+    { name: "plan", task: "Plan from {previous}" },
+  ],
+  async: true,
 })
 ```
 
-## Monitor/control
+Direct mode supports top-level/default options and per-task options such as `context`, `model`, `fallbackModels`, `thinkingLevel`, `mcp`, `output`, `reads`, `progress`, `worktree`, `maxOutput`, `artifacts`, `sessionDir`, and `cwd`. For large fan-outs, prefer `outputMode: "file-only"`.
+
+## Monitor/control with the workflow tool
 
 ```ts
 workflow({ action: "status" })
 workflow({ action: "status", runId: "<id>" })
 workflow({ action: "interrupt", runId: "<id>" })
+workflow({ action: "interrupt", runId: "--all" })
 workflow({ action: "resume", runId: "<id>" })
 ```
 
-Slash equivalents:
-
-```text
-/workflow status --all
-/workflow status <id>
-/workflow interrupt <id>
-/workflow resume <id>
-```
+The LLM-callable tool exposes status/interrupt/resume controls. Use slash commands for graph connect, stage attach, and pause because those are interactive TUI surfaces.
 
 When a run needs user input or attention, surface that to the user instead of polling silently.
 
@@ -92,7 +119,7 @@ For async direct runs, request result delivery when available:
 workflow({
   tasks: [{ name: "reviewer", task: "Review the patch" }],
   async: true,
-  intercom: { delivery: "result" }
+  intercom: { delivery: "result" },
 })
 ```
 
@@ -101,7 +128,9 @@ Treat intercom payloads as user-visible workflow output.
 ## Common mistakes
 
 - Do not fabricate workflow names; list first.
+- Do not guess input keys; inspect with `inputs` or `get` first.
 - Do not call `create`, `update`, or `delete` on the workflow tool; definitions are code-authored.
 - Do not use legacy tool fields like `agent`, `stage`, or run-control `name`.
+- Do not expect named workflow runs to block the chat turn; they are background tasks.
 - Prefer `outputMode: "file-only"` for large fan-outs.
 - Use status/resume controls for run lifecycle; inspect workflow output and artifacts for behavior.

package/dist/builtin/workflows/skills/workflow/references/sdk-authoring.md

@@ -4,10 +4,11 @@ Use this when creating or editing user-facing workflow definition files for `@ba
 
 ## Where workflow files live
 
-Pi discovers workflows from these user-facing locations:
+Pi/Atomic discovers workflows from these user-facing locations:
 
-- Project-local: `.atomic/workflows/*.ts` inside a project.
-- User-global: `~/.atomic/agent/workflows/*.ts` for workflows shared across projects.
+- Project-local: `.atomic/workflows/*.{ts,js,mjs,cjs}` inside a project. Legacy `.pi/workflows/` is also checked for compatibility.
+- User-global: `~/.atomic/agent/workflows/*.{ts,js,mjs,cjs}` for workflows shared across projects. Legacy `~/.pi/agent/workflows/` is also checked.
+- Configured directories: `.atomic/extensions/workflow/config.json` or `~/.atomic/agent/extensions/workflow/config.json` can add `workflows.<name>.path` entries; legacy `.pi/...` config paths are also considered.
 - Package-provided: a pi package can expose bundled workflow directories through `package.json` under `pi.builtin`.
 
 In a normal consumer project, import from the package:
@@ -31,18 +32,20 @@ export default defineWorkflow("my-workflow")
     description: "Task or question for the workflow.",
   })
   .run(async (ctx) => {
+    const prompt = String(ctx.inputs.prompt);
+
     const scout = await ctx.task("scout", {
-      task: `Map the relevant context for: ${ctx.inputs.prompt}`,
+      prompt: `Map the relevant context for: ${prompt}`,
       context: "fresh",
     });
 
     const reviews = await ctx.parallel([
-      { name: "quality", task: "Inspect quality risks using this context: {previous}", previous: scout },
-      { name: "runtime", task: "Inspect runtime concerns using this context: {previous}", previous: scout },
+      { name: "quality", prompt: "Inspect quality risks using this context: {previous}", previous: scout },
+      { name: "runtime", prompt: "Inspect runtime concerns using this context: {previous}", previous: scout },
     ]);
 
     const final = await ctx.task("synthesis", {
-      task: "Synthesize findings and recommend next steps.",
+      prompt: "Synthesize findings and recommend next steps.",
       previous: reviews,
     });
 
@@ -51,6 +54,8 @@ export default defineWorkflow("my-workflow")
   .compile();
 ```
 
+`prompt` and `task` are aliases for task text. Prefer `prompt` inside authored workflow files because it mirrors the lower-level `stage.prompt(...)`; `task` remains useful in direct tool calls and chain examples.
+
 ## Builder facts
 
 - `defineWorkflow(name)` requires a non-empty string name.
@@ -69,7 +74,7 @@ Supported input schema types are:
 - `boolean`: optional `default: boolean`
 - `select`: required `choices: string[]`, optional `default: string`
 
-All schemas support `description` and `required`. Prefer explicit descriptions because `/workflow inputs <name>` and the input picker show them to the user.
+All schemas support `description` and `required`. Prefer explicit descriptions because `/workflow inputs <name>`, `/workflow <name> --help`, and the input picker show them to the user. Runtime validation rejects unknown keys, missing required values, type mismatches, and select values outside `choices`; it does not coerce strings like `"3"` to numbers.
 
 ## Run context
 
@@ -78,9 +83,9 @@ All schemas support `description` and `required`. Prefer explicit descriptions b
 Prefer high-level primitives:
 
 - `ctx.task(name, options)` — one tracked stage + prompt, returns `WorkflowTaskResult`.
-- `ctx.parallel(steps, options?)` — run independent task steps concurrently.
+- `ctx.parallel(steps, options?)` — run independent task steps together; keep authored fan-outs intentionally bounded.
 - `ctx.chain(steps, options?)` — run dependent task steps sequentially.
-- `ctx.ui` — user interaction primitives when a run needs human input.
+- `ctx.ui` — human-in-the-loop primitives when a run needs user input.
 
 Use `ctx.stage(name, options?)` only when you need lower-level session control. `StageContext` supports:
 
@@ -91,6 +96,17 @@ Use `ctx.stage(name, options?)` only when you need lower-level session control.
 - state access: `agent`, `model`, `thinkingLevel`, `messages`, `isStreaming`
 - tree navigation, compaction, and abort
 
+## Human-in-the-loop UI
+
+`ctx.ui` supports:
+
+- `input(prompt): Promise<string>`
+- `confirm(message): Promise<boolean>`
+- `select(message, options): Promise<T>`
+- `editor(initial?): Promise<string>`
+
+These suspend the workflow until the user responds. In interactive pi/Atomic, prompts appear in the workflow graph/input UI opened by F2 or `/workflow connect <run-id>`, not as modal chat dialogs. Always make the surrounding stage/output clear enough that the user knows what decision they are making.
+
 ## Task/session options
 
 Common task/stage options include:
@@ -102,6 +118,8 @@ Common task/stage options include:
 - `output`, `outputMode`, `reads`, `progress`, `worktree`, `maxOutput`, `artifacts`, `sessionDir`, `cwd`
 - `mcp: { allow?: string[], deny?: string[] }`
 
+`fallbackModels` retries transient provider/model failures with the primary `model` first, then each fallback, then the current pi-selected model when available. It is for rate limits, quota/auth/provider outages, unavailable models, network timeouts, and 5xx errors — not workflow-code errors, tool failures, validation failures, or cancellations. Use provider-qualified IDs when bare IDs would be ambiguous.
+
 Chain defaults:
 
 - first missing task uses `{task}` from chain options/root direct task
@@ -112,12 +130,23 @@ Chain defaults:
 
 A stage should correspond to an LLM/session interaction. Put pure deterministic work directly in `.run()` or helper functions, not in a standalone stage. Examples: parsing, filesystem writes, JSON validation, git queries, and formatting. Pair deterministic parsing/validation with a nearby LLM call when it is part of that stage's output handling.
 
-## Execution model
+## Registries and programmatic execution
+
+Use `createRegistry()` when code needs to group definitions explicitly:
+
+```ts
+import { createRegistry, defineWorkflow } from "@bastani/workflows";
+
+const alpha = defineWorkflow("alpha").run(async () => ({})).compile();
+const registry = createRegistry().register(alpha);
+registry.names();
+registry.get("alpha");
+```
 
 `@bastani/workflows` is a pi package/extension. Pi loads the extension from the package manifest; the extension registers the `workflow` tool, `/workflow` command, renderers, widgets, and lifecycle hooks. Use these user-facing surfaces:
 
 - `/workflow <name> key=value ...` inside pi.
-- The `workflow` tool for LLM-driven orchestration.
+- The `workflow` tool for LLM-driven orchestration and direct one-off runs.
 - `runWorkflow(definition)` for explicit library/script usage.
 
 Programmatic runner example:

package/dist/builtin/workflows/src/extension/config-loader.ts

@@ -18,7 +18,7 @@
 
 import { join, isAbsolute } from "node:path";
 import { homedir } from "node:os";
-import { CONFIG_DIR_NAME } from "@bastani/atomic";
+import { CONFIG_DIR_NAME, CONFIG_DIR_NAMES, getProjectConfigPaths } from "@bastani/atomic";
 
 // ---------------------------------------------------------------------------
 // Public types
@@ -439,37 +439,36 @@ export async function loadWorkflowConfig(
 
   const diagnostics: ConfigDiagnostic[] = [];
 
-  // Global config path
-  const globalPath = join(home, CONFIG_DIR_NAME, "agent", "extensions", "workflow", "config.json");
+  // Global config paths (primary Atomic first, then legacy pi)
+  const globalCandidates = CONFIG_DIR_NAMES.map((name) => join(home, name, "agent", "extensions", "workflow", "config.json"));
 
-  // Project-local config
-  const projectCandidates: string[] = [
-    join(projectRoot, CONFIG_DIR_NAME, "extensions", "workflow", "config.json"),
-  ];
+  // Project-local config paths (primary Atomic first, then legacy pi)
+  const projectCandidates: string[] = getProjectConfigPaths(projectRoot, "extensions", "workflow", "config.json");
 
-  // Load global config
+  // Load global config (primary overrides legacy)
   let globalConfig: WorkflowExtensionConfig | null = null;
-  {
+  for (let i = globalCandidates.length - 1; i >= 0; i--) {
+    const globalPath = globalCandidates[i]!;
     const outcome = await loadConfigFile(globalPath);
     if (outcome.kind === "error") {
       diagnostics.push(outcome.diagnostic);
     } else if (outcome.kind === "ok") {
-      globalConfig = outcome.parsed;
+      globalConfig = globalConfig ? mergeConfigs(globalConfig, outcome.parsed) : outcome.parsed;
     }
     // "missing" → silently skip
   }
 
-  // Load first existing project-local config
+  // Load project-local configs (primary overrides legacy)
   let projectConfig: WorkflowExtensionConfig | null = null;
-  for (const candidatePath of projectCandidates) {
+  for (let i = projectCandidates.length - 1; i >= 0; i--) {
+    const candidatePath = projectCandidates[i]!;
     const outcome = await loadConfigFile(candidatePath);
     if (outcome.kind === "missing") continue;
     if (outcome.kind === "error") {
       diagnostics.push(outcome.diagnostic);
     } else {
-      projectConfig = outcome.parsed;
+      projectConfig = projectConfig ? mergeConfigs(projectConfig, outcome.parsed) : outcome.parsed;
     }
-    break; // Only first existing candidate
   }
 
   // Merge: start from global, apply project override

package/dist/builtin/workflows/src/extension/discovery.ts

@@ -21,7 +21,7 @@
 
 import { readdir, stat } from "node:fs/promises";
 import { join, resolve, extname, isAbsolute } from "node:path";
-import { CONFIG_DIR_NAME } from "@bastani/atomic";
+import { CONFIG_DIR_NAMES, getProjectConfigPaths } from "@bastani/atomic";
 import type { WorkflowDefinition } from "../shared/types.js";
 import { createRegistry } from "../workflows/registry.js";
 import type { WorkflowRegistry } from "../workflows/registry.js";
@@ -408,8 +408,7 @@ export async function discoverWorkflows(
   }
 
   // 2. project-local
-  {
-    const dir = join(cwd, CONFIG_DIR_NAME, "workflows");
+  for (const dir of getProjectConfigPaths(cwd, "workflows").reverse()) {
     const candidates = await loadFromDir(dir, "project-local", diagnostics);
     registry = applyBatch(candidates, registry, sources, diagnostics);
   }
@@ -424,9 +423,8 @@ export async function discoverWorkflows(
     }
   }
 
-  // 4. user-global — canonical Atomic path: ~/.atomic/agent/workflows/
-  {
-    const dir = join(homeDir, CONFIG_DIR_NAME, "agent", "workflows");
+  // 4. user-global — canonical Atomic path plus legacy pi path
+  for (const dir of CONFIG_DIR_NAMES.map((name) => join(homeDir, name, "agent", "workflows")).reverse()) {
     const candidates = await loadFromDir(dir, "user-global", diagnostics);
     registry = applyBatch(candidates, registry, sources, diagnostics);
   }