@bastani/atomic 0.8.24-alpha.1 → 0.8.24-alpha.3

package/docs/packages.md

@@ -166,7 +166,7 @@ If no app manifest (`atomic`, or legacy `pi`) is present, Atomic auto-discovers
 - `skills/` recursively finds `SKILL.md` folders and loads top-level `.md` files as skills
 - `prompts/` loads `.md` files
 - `themes/` loads `.json` files
-- `workflows/` loads workflow SDK files (`.ts`, `.js`, `.mjs`, `.cjs`); `workflow/` is also accepted as a singular alias. Workflow files should `import { defineWorkflow, Type } from "@bastani/workflows"` and export `defineWorkflow(...).compile()` output. TypeScript package authors do not need a local `.d.ts` or `declare module` shim for the SDK import.
+- `workflows/` loads workflow SDK files (`.ts`, `.js`, `.mjs`, `.cjs`); `workflow/` is also accepted as a singular alias. Workflow files should `import { defineWorkflow, Type } from "@bastani/workflows"` and export `defineWorkflow(...).compile()` output. TypeScript package authors do not need a hand-authored `.d.ts`, a `declare module` shim, or a `tsconfig` `paths` alias for the SDK import — the SDK types ship with `@bastani/atomic`. A package that also imports `@bastani/atomic` picks them up automatically; a pure workflow-only package adds one opt-in line (`compilerOptions.types: ["@bastani/atomic/workflows/ambient"]` or a `/// <reference types="@bastani/atomic/workflows/ambient" />` directive). See the workflow SDK typing guidance under Programmatic Usage in the workflows guide.
 
 When a package manifest exists, declared resource arrays normally define what loads. Workflows are the exception: if `atomic.workflows` / legacy `pi.workflows` is omitted, Atomic still checks conventional `workflows/` and `workflow/` directories.
 
@@ -176,7 +176,7 @@ Third-party runtime dependencies belong in `dependencies` in `package.json`. Dep
 
 Atomic bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, `@bastani/atomic`, `@earendil-works/pi-tui`, `typebox`.
 
-Workflow packages should author workflow files with `import { defineWorkflow, Type } from "@bastani/workflows"` and export definitions produced by `defineWorkflow(...).compile()`. Do not use the removed `runWorkflow` object-form API, and do not hand-roll objects with `__piWorkflow: true`; discovery accepts only compiled definitions.
+Workflow packages should author workflow files with `import { defineWorkflow, Type } from "@bastani/workflows"` and export definitions produced by `defineWorkflow(...).compile()`. Do not use the removed `runWorkflow` object-form API, and do not hand-roll objects with `__piWorkflow: true`; discovery accepts only compiled definitions. `@bastani/workflows` is not a separate npm package: its types resolve through `@bastani/atomic`, so list `@bastani/atomic` and `typebox` in `peerDependencies` (the workflow SDK's emitted types reference `typebox`). A pure workflow-only package also adds the one-line ambient opt-in noted above; a package that imports `@bastani/atomic` elsewhere picks the types up automatically.
 
 Other Atomic packages must be bundled in your tarball. Add them to `dependencies` and `bundledDependencies`, then reference their resources through `node_modules/` paths. Atomic loads packages with separate module roots, so separate installs do not collide or share modules.
 

package/docs/usage.md

@@ -55,6 +55,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/reload` | Reload keybindings, extensions, skills, prompts, and context files |
 | `/hotkeys` | Show all keyboard shortcuts |
 | `/changelog` | Display version history |
+| `/exit` | Exit Atomic |
 | `/quit` | Quit Atomic |
 
 ## Message Queue

package/docs/workflows.md

@@ -30,6 +30,7 @@ Use a workflow when a task should be repeatable, inspectable, resumable, or spli
 - [Quick Start](#quick-start)
 - [Built-in Workflows](#built-in-workflows)
 - [When to Use Workflows](#when-to-use-workflows)
+- [Workflow Starter Patterns](#workflow-starter-patterns)
 - [Atomic vs Claude Code Dynamic Workflows](#atomic-vs-claude-code-dynamic-workflows)
 - [Workflow Locations](#workflow-locations)
 - [Workflow Configuration](#workflow-configuration)
@@ -382,6 +383,177 @@ If the task is only deterministic TypeScript with no LLM/session stage, use a sc
 | Track one-off work without saving a workflow file | direct `workflow({ task })`, `workflow({ tasks })`, or `workflow({ chain })` calls |
 | Make a workflow robust | design the stage graph, context handoffs, artifacts, validation gates, model fallbacks, and human approval points before coding |
 
+## Workflow Starter Patterns
+
+When a workflow is larger than a single tracked task, start by choosing a small control-flow pattern before writing prompts. Naming the pattern keeps the stage graph understandable, makes validation gates explicit, and helps reviewers see why work is split across model sessions.
+
+These patterns are composable. For example, a migration workflow might use **fan-out-and-synthesize** to fix many call sites, then **adversarial verification** to review each patch, and finally **loop until done** while tests still fail.
+
+| Pattern | Use it when | Atomic shape |
+|---|---|---|
+| **Classify-and-act** | Inputs arrive in different categories and each category needs a different path, model, tool set, or output format. | `ctx.task("classify")` → deterministic branch → category-specific `ctx.task`, `ctx.chain`, `ctx.parallel`, or child `ctx.workflow(...)`. |
+| **Fan-out-and-synthesize** | The task can be split into many independent slices that benefit from clean context windows. | `ctx.parallel([...])` with separate artifacts → synthesis barrier that reads the artifacts and merges the answer. |
+| **Adversarial verification** | Outputs need independent checking against a rubric, security rule, factual source, or acceptance contract. | Worker stage(s) → fresh-context verifier stage(s) → reducer that accepts, rejects, or asks for repair. |
+| **Generate-and-filter** | You need many candidate ideas, plans, names, fixes, or hypotheses before selecting the best few. | Generator fan-out → dedupe/filter stage → optional verifier/judge → final shortlist. |
+| **Tournament** | The whole task is subjective or approach-sensitive, and comparative judgment is more reliable than absolute scoring. | Several agents attempt the same task → pairwise judges compare results → bracket reducer returns winners. |
+| **Loop until done** | The amount of work is unknown up front, such as finding all failures, mining repeated issues, or iterating until checks pass. | Bounded loop with an explicit stop condition, progress ledger, per-iteration artifacts, and a max-iteration escape hatch. |
+
+### Pattern diagrams
+
+#### 1. Classify-and-act
+
+```text
+┌─ 1  Classify-and-act ────────────────────────────────────┐
+│                                                          │
+│                             ┌───────┐                    │
+│                         ╭──▸│agent A│                    │
+│                         │   └───────┘                    │
+│  ┌────┐  ┌──────────┐   │   ┌───────┐                    │
+│  │task│─▸│classifier│───┼──▸│agent B│ ◂ chosen           │
+│  └────┘  └──────────┘   │   └───────┘                    │
+│                         │   ┌───────┐                    │
+│                         ╰──▸│agent C│                    │
+│                             └───────┘                    │
+│                                                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+Best practices:
+- Make the classifier return a structured category and confidence, not free-form prose.
+- Keep each action branch isolated with the minimum tools and context it needs.
+- Add a fallback or human-input branch for low-confidence classifications.
+
+#### 2. Fan-out-and-synthesize
+
+```text
+┌─ 2  Fan-out-and-synthesize ──────────────────────────────┐
+│                                                          │
+│            ┌───────┐                                     │
+│          ╭▸│agent 1│──╮                                  │
+│          │ └───────┘  │                                  │
+│          │ ┌───────┐  │                                  │
+│          ├▸│agent 2│──┤                                  │
+│  ┌────┐  │ └───────┘  │ ┌───────┐  ┌──────────┐          │
+│  │task│──┤ ┌───────┐  ├▸│barrier│─▸│synthesize│          │
+│  └────┘  ├▸│agent 3│──┤ └───────┘  └──────────┘          │
+│          │ └───────┘  │                                  │
+│          │ ┌───────┐  │                                  │
+│          ╰▸│agent 4│──╯                                  │
+│            └───────┘                                     │
+│                                                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+Best practices:
+- Partition by files, sources, claims, candidates, or work items that can be evaluated independently.
+- Save each branch to a separate artifact and pass paths with `reads` instead of inlining all branch output.
+- Treat synthesis as a barrier: it waits for every branch, deduplicates, resolves conflicts, and cites evidence.
+
+#### 3. Adversarial verification
+
+```text
+┌─ 3  Adversarial verification ────────────────────────────┐
+│                                                          │
+│                                                          │
+│                                 ┌──────────┐             │
+│               ├────────────────▸│verifier A│             │
+│               │                 └──────────┘             │
+│  ┌──────┐     │                 ┌──────────┐             │
+│  │worker│◂────┼────────────────▸│verifier B│             │
+│  └──────┘     │                 └──────────┘             │
+│               │                 ┌──────────┐             │
+│               ├────────────────▸│verifier C│             │
+│                                 └──────────┘             │
+│                                                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+Best practices:
+- Give verifiers fresh context and a concrete rubric with pass/fail evidence requirements.
+- Separate production from judgment to reduce self-preferential bias.
+- Ask verifiers to find blockers, not to rewrite the candidate unless repair is explicitly their role.
+
+#### 4. Generate-and-filter
+
+```text
+┌─ 4  Generate-and-filter ─────────────────────────────────┐
+│                                                          │
+│                                                          │
+│  ┌─────┐   ┌────┐                      ┌────┐            │
+│  │gen A│──▸│idea│───╮              ╭──▸│best│            │
+│  └─────┘   └────┘   │              │   └────┘            │
+│  ┌─────┐   ┌────┐   │  ┌──────┐    │   ┌────┐            │
+│  │gen B│──▸│idea│───┼─▸│filter│────┼──▸│best│            │
+│  └─────┘   └────┘   │  └──────┘    │   └────┘            │
+│  ┌─────┐   ┌────┐   │              │   ┌╌╌╌╌╌╌╌╌╌┐       │
+│  │gen C│──▸│idea│───╯              ╰──▸╎discarded╎       │
+│  └─────┘   └────┘                      └╌╌╌╌╌╌╌╌╌┘       │
+│                                                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+Best practices:
+- Generate more candidates than you need, then filter hard by an explicit rubric.
+- Dedupe before judging so near-identical candidates do not dominate the shortlist.
+- Use this for exploration, naming, design options, hypotheses, and lightweight eval ideas.
+
+#### 5. Tournament
+
+```text
+┌─ 5  Tournament ──────────────────────────────────────────┐
+│                                                          │
+│  ┌─────────┐                                             │
+│  │attempt A│──╮  ┌───────┐                               │
+│  └─────────┘  ├─▸│judge 1│───╮                           │
+│  ┌─────────┐  │  └───────┘   │                           │
+│  │attempt B│──╯              │   ┌─────┐  ┌──────┐       │
+│  └─────────┘                 ├──▸│final│─▸│winner│       │
+│  ┌─────────┐                 │   └─────┘  └──────┘       │
+│  │attempt C│──╮  ┌───────┐   │                           │
+│  └─────────┘  ├─▸│judge 2│───╯                           │
+│  ┌─────────┐  │  └───────┘                               │
+│  │attempt D│──╯                                          │
+│  └─────────┘                                             │
+│                                                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+Best practices:
+- Use pairwise comparison when absolute scores are noisy or subjective.
+- Randomize or balance presentation order where possible to reduce order bias.
+- Keep the judge rubric short and require rationale tied to observable criteria.
+
+#### 6. Loop until done
+
+```text
+┌─ 6  Loop until done ─────────────────────────────────────┐
+│                                                          │
+│      yes, spawn another                                  │
+│     ╭────────────────╮                                   │
+│     ▾                │                                   │
+│  ┌─────┐      ┌─────────────┐  no   ┌────┐               │
+│  │agent│─────▸│new findings?│──────▸│done│               │
+│  └─────┘      └─────────────┘       └────┘               │
+│                                                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+Best practices:
+- Define both success and escape conditions before the loop starts.
+- Keep a durable ledger of attempted work, findings, failures, and validation evidence.
+- Bound loops by iterations, budget, or convergence criteria so they fail inspectably instead of drifting.
+
+### Choosing a starter pattern
+
+- Pick **classify-and-act** when routing correctness matters more than breadth.
+- Pick **fan-out-and-synthesize** when the work divides cleanly into independent slices.
+- Pick **adversarial verification** when the main risk is a plausible but wrong answer.
+- Pick **generate-and-filter** when the output quality depends on exploring a large option space.
+- Pick **tournament** when multiple whole-solution strategies should compete under one rubric.
+- Pick **loop until done** when the workflow should continue until evidence says it is finished, not until a preselected number of stages completes.
+
+Record the selected pattern in your spec or workflow README, then adapt the diagram to the actual stage graph. If the final design does not resemble any starter pattern, explain why in the workflow's design notes.
+
 ## Atomic vs Claude Code Dynamic Workflows
 
 Claude Code Dynamic Workflows and Atomic are trying to solve a similar class of problem: important software engineering work is too large for one agent pass, so the system should split the job into stages, run agents in parallel, verify the result, and keep enough state to finish long-running work.
@@ -845,7 +1017,7 @@ Author workflows to create at least one tracked stage by calling `ctx.task()`, `
 
 ### Inputs
 
-Inputs are declared with TypeBox `Type.*` schemas passed to `.input(key, schema)`. `Type` is re-exported from `@bastani/workflows` (along with the `Static` and `TSchema` type helpers), so you can author and type schemas without adding a separate `typebox` dependency. Common input schemas map to picker kinds and accepted runtime values:
+Inputs are declared with TypeBox `Type.*` schemas passed to `.input(key, schema)`. `Type` is re-exported from `@bastani/workflows` (along with the `Static` and `TSchema` type helpers), so you do not import from `typebox` directly in workflow files. Workflow packages still declare `typebox` as a peer dependency so the SDK's shipped types resolve under `tsc` — see [Programmatic Usage](#programmatic-usage). Common input schemas map to picker kinds and accepted runtime values:
 
 | TypeBox schema | Picker kind | Accepted runtime value |
 |---|---|---|
@@ -1241,7 +1413,7 @@ This applies everywhere a stage accepts a model: direct `ctx.task`/`ctx.chain`/`
 - the `workflow` tool for agent-initiated orchestration and direct one-off runs
 Workflow definition files must export definitions produced by `defineWorkflow(...).compile()`. The former imperative object-form runner is not part of the public SDK, and authored workflow files cannot import `runWorkflow` from `@bastani/workflows`.
 
-Standalone TypeScript workflow packages can import the typed SDK directly, with no hand-authored `.d.ts` or `declare module` shim:
+Standalone TypeScript workflow packages type-check the SDK import with no hand-authored `.d.ts`, no `declare module` shim, and no `tsconfig` `paths` alias. The SDK types ship with `@bastani/atomic`, so a workflow package depends only on `@bastani/atomic` (plus a `typebox` peer):
 
 ```ts
 import { defineWorkflow, Type } from "@bastani/workflows";
@@ -1255,6 +1427,29 @@ export default defineWorkflow("map-workflow-sdk")
   .compile();
 ```
 
+How those types resolve depends on what else the package imports:
+
+- A package that imports `@bastani/atomic` anywhere (for example, an extension shipped in the same package) picks the workflow SDK types up automatically. `@bastani/atomic`'s root declarations reference the ambient bridge, so no extra configuration is needed.
+- A pure workflow-only package — one that imports nothing but `@bastani/workflows` — adds a single opt-in so TypeScript loads the ambient bridge. Set it once for the project in `tsconfig.json`:
+
+  ```jsonc
+  {
+    "compilerOptions": {
+      "module": "NodeNext",
+      "moduleResolution": "NodeNext",
+      "types": ["@bastani/atomic/workflows/ambient"]
+    }
+  }
+  ```
+
+  or add a single reference directive at the top of one workflow file:
+
+  ```ts
+  /// <reference types="@bastani/atomic/workflows/ambient" />
+  ```
+
+Either form makes `import { defineWorkflow, Type } from "@bastani/workflows"` and the `@bastani/workflows/builtin/*` composition imports resolve under `tsc` (`moduleResolution: NodeNext`) with no hand-authored `.d.ts`, no `declare module` shim, and no `paths` alias. `@bastani/workflows` is not a separate npm package — its types ship with `@bastani/atomic` — so list both `@bastani/atomic` and `typebox` (the SDK's emitted types reference TypeBox) in `peerDependencies`. Runtime discovery and loading via `atomic.workflows` are unchanged: Atomic's loader still supplies the SDK when workflow files execute.
+
 The `workflow` tool still supports direct one-off `task`, `tasks`, and `chain` modes. Direct chains support `chainName` for status/artifact grouping and `chainDir` as a shared directory for relative reads, outputs, and worktree diffs.
 
 Use `createRegistry()` when code needs to group definitions explicitly:
@@ -1415,6 +1610,7 @@ Before implementing or shipping a non-trivial workflow, answer these questions:
 
 - **Purpose and fit:** What concrete outcome should the workflow produce? Is the task naturally multi-stage, parallel, resumable, or reusable? What is out of scope?
 - **Inputs:** Which values should be declared as inputs? What is the narrowest schema type? Which defaults are safe?
+- **Starter pattern:** Which [workflow starter pattern](#workflow-starter-patterns) best matches the task, and where does the actual design intentionally diverge?
 - **Stage decomposition:** For each stage, what question does it answer, what context does it need, what output should it return, and what model/tool/MCP requirements does it have?
 - **Information flow:** For every edge between stages, is `previous` enough, or should the handoff use structured returns, files, `reads`, `output`, or `outputMode`?
 - **Output contract:** Which outputs should be declared with `.output(...)`, which stage/task/child results should `.run()` return for those keys, and what runtime type must each value have? If another workflow may call this workflow as a child, which non-default outputs should the parent rely on?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.8.24-alpha.1",
+  "version": "0.8.24-alpha.3",
   "description": "Atomic coding agent CLI with read, bash, edit, write tools and session management",
   "type": "module",
   "atomicConfig": {
@@ -26,6 +26,24 @@
     "./hooks": {
       "types": "./dist/core/hooks/index.d.ts",
       "import": "./dist/core/hooks/index.js"
+    },
+    "./workflows": {
+      "types": "./dist/builtin/workflows/src/authoring.d.ts",
+      "import": "./dist/builtin/workflows/src/index.ts",
+      "default": "./dist/builtin/workflows/src/index.ts"
+    },
+    "./workflows/ambient": {
+      "types": "./dist/builtin/workflows/ambient.d.ts"
+    },
+    "./workflows/builtin": {
+      "types": "./dist/builtin/workflows/builtin/index.d.ts",
+      "import": "./dist/builtin/workflows/builtin/index.ts",
+      "default": "./dist/builtin/workflows/builtin/index.ts"
+    },
+    "./workflows/builtin/*": {
+      "types": "./dist/builtin/workflows/builtin/*.d.ts",
+      "import": "./dist/builtin/workflows/builtin/*.ts",
+      "default": "./dist/builtin/workflows/builtin/*.ts"
     }
   },
   "files": [
@@ -44,6 +62,7 @@
     "copy-builtin-packages": "bun run scripts/copy-builtin-packages.ts",
     "copy-builtin-workflows": "bun run copy-builtin-packages",
     "docs:check": "bun run scripts/validate-docs-links.ts",
+    "verify:workflow-types": "bun run scripts/verify-workflow-sdk-types.ts",
     "test": "vitest --run",
     "prepublishOnly": "bun run clean && bun run build"
   },