@bastani/atomic 0.9.0-alpha.2 → 0.9.0-alpha.4

package/docs/workflows.md

@@ -2,9 +2,9 @@
 
 # Workflows
 
-Workflows let Atomic run reusable multi-stage automation with tracked stages, parallel branches, artifacts, human input, live status, and resumable background execution.
+Workflows are how Atomic runs executable engineering loops: reusable multi-stage automation with tracked stages, parallel branches, artifacts, human input, live status, checkpoints, and resumable background execution.
 
-Use a workflow when a task should be repeatable, inspectable, resumable, or split across multiple model sessions. For one-off work, the `workflow` tool can also run a tracked single task, parallel fan-out, or chain without creating a saved workflow file.
+Use a workflow when a task should be repeatable, inspectable, resumable, or split across multiple model sessions. Markdown prompts can describe a loop; Atomic workflows run the loop with scoped context, tools, artifacts, verification, subagents, review gates, and human approvals. For one-off work, the `workflow` tool can also run a tracked single task, parallel fan-out, or chain without creating a saved workflow file.
 
 **Key capabilities:**
 - **Tracked stages** - Name each step and inspect it in workflow status and graph views
@@ -13,6 +13,7 @@ Use a workflow when a task should be repeatable, inspectable, resumable, or spli
 - **Human input** - Pause for `ctx.ui.input`, `confirm`, `select`, `editor`, or custom TUI widget decisions during a run
 - **Resumable control** - Interrupt, pause, resume, attach to, or kill workflow runs
 - **Artifacts** - Save large outputs to files instead of pushing everything through model context
+- **Verification and gates** - Preserve evidence, run checks, and stop for human approval where reliability matters
 - **Model fallback chains** - Retry important stages on fallback models when providers fail
 - **Package distribution** - Ship workflows through Atomic packages, settings, or conventional directories
 
@@ -43,12 +44,14 @@ Use a workflow when a task should be repeatable, inspectable, resumable, or spli
 - [Direct One-Off Runs](#direct-one-off-runs)
 - [Fast Inference for Workflow Stages](#fast-inference-for-workflow-stages)
 - [Writing a Workflow](#writing-a-workflow)
+- [Migrating from the `defineWorkflow()` Builder API](#migrating-from-the-defineworkflow-builder-api)
 - [Workflow Primitives](#workflow-primitives)
 - [Task and Stage Options](#task-and-stage-options)
 - [Programmatic Usage](#programmatic-usage)
 - [Context Engineering](#context-engineering)
 - [Design Checklist](#design-checklist)
 - [Common Mistakes](#common-mistakes)
+- [Workflow Best Practices](#workflow-best-practices)
 
 ## Quick Start
 
@@ -155,9 +158,9 @@ For the builtin result tables below, `deep-research-codebase`, `goal`, and `ralp
 | Workflow | What it does | When to use |
 |---|---|---|
 | `deep-research-codebase` | Scout + research-history chain → parallel specialist waves → aggregator. Indexes the whole repo and synthesizes findings. | Broad or cross-cutting research before you decide what to change. Prefer `/skill:research-codebase` for one subsystem. |
-| `goal` | Persisted goal ledger → bounded worker turns → receipts → three-reviewer gate → deterministic reducer → final report. | Small-to-medium scope changes when you can identify the work surface, state the exact outcome, and name the validation that proves it is done — for example tests, lint/typecheck, docs builds, or observable behavior. |
-| `ralph` | Prompt-engineering → codebase/online research → sub-agent orchestration → multi-model parallel review → optional final-stage PR handoff. | Larger migrations, broad refactors, and multi-package changes where you want Atomic to transform the prompt into a research question, research the codebase before implementing, delegate through sub-agents, review, iterate, and optionally allow only the final `pull-request` stage to attempt PR creation with `create_pr=true`. |
-| `open-claude-design` | Design-system onboarding → reference import → HTML generation → impeccable-driven refinement → quality gate → rich HTML handoff. Renders a live `preview.html` you can iterate against (opens through `browser` when available). | UI, page, component, theme, or design-token work that benefits from generation + critique loops. |
+| `goal` | Persisted goal ledger → bounded worker turns → receipts → three-reviewer gate → deterministic reducer → final report → optional final-stage PR handoff after approval. | Small-to-medium scope changes when you can identify the work surface, state the exact outcome, name the validation that proves it is done, and optionally allow only the final `pull-request` stage to attempt PR creation with `create_pr=true` after Goal reaches `complete`. |
+| `ralph` | Prompt-refinement → research-prompt-refinement → codebase/online research → sub-agent orchestration → multi-model parallel review → optional final-stage PR handoff. | Larger migrations, broad refactors, and multi-package changes where you want Atomic to refine the prompt for clarity, transform it into a research question, research the codebase before implementing, delegate through sub-agents, review, iterate, and optionally allow only the final `pull-request` stage to attempt PR creation with `create_pr=true`. |
+| `open-claude-design` | Combined discovery/init (`/skill:impeccable shape` + `/skill:impeccable init` in one `discovery` stage) → design-system/reference research (`ds-*`) → curated gallery reference-discovery using that context → a forked `generate-*` / `user-feedback-*` loop → rich HTML handoff (`exporter` → `final-display`). The discovery stage asks what to build, the output type, and which references to emulate, then lets impeccable init detect/create/reconcile `PRODUCT.md` and `DESIGN.md` (references take precedence over project context). Renders a live `preview.html` you can iterate against in the browser (opens through impeccable `live` / the `playwright-cli` skill when available). | UI, page, component, theme, or design-token work that benefits from a guided brief, beautiful references, and generation + user feedback loops. |
 
 ### `deep-research-codebase`
 
@@ -211,7 +214,8 @@ Inputs:
 |---|---|---|---|---|
 | `objective` | text | yes | — | Goal-runner objective. Include the desired end state, expected outcome, testing/validation instructions, and any explicit done criteria. |
 | `max_turns` | number | no | `10` | Maximum worker/review turns before human follow-up is needed. |
-| `base_branch` | string | no | `origin/main` | Branch reviewers compare the current code delta against. |
+| `base_branch` | string | no | `origin/main` | Branch reviewers and the optional final stage compare the current code delta against. |
+| `create_pr` | boolean | no | `false` | Safe-by-default PR creation flag. Omitted or `false` skips the final `pull-request` stage and omits `pr_report`; prompt text alone does not opt in, and only strict `true` authorizes the final `pull-request` stage to attempt provider-appropriate PR/MR/review creation after Goal reaches `complete`. |
 
 `goal` defaults to 10 worker/review turns. Reviewer quorum is fixed internally at 2 reviewer `complete` votes. The repeated-blocker threshold defaults to 3 consecutive same-blocker turns and is clamped to `max_turns` when you run fewer than 3 turns.
 
@@ -221,9 +225,10 @@ Run examples:
 /workflow goal objective="Implement specs/2026-03-rate-limit.md, add the requested regression tests, run bun test packages/api/rate-limit.test.ts, and finish only when burst traffic returns 429 with Retry-After"
 /workflow goal objective="Update the CLI docs to describe the new --json flag, include one usage example, and verify the docs build still passes" max_turns=3
 /workflow goal objective="Fix the settings form validation bug; add/adjust the focused test and consider it done when invalid emails show the inline error without submitting"
+/workflow goal objective="Implement the focused docs fix, run the docs validation command, and open a PR when complete" create_pr=true
 ```
 
-`goal` creates an OS-temp `goal-ledger.json` artifact, renders goal-continuation context for each worker turn, writes each worker receipt to `work-turn-N.md`, and appends receipts, reviewer decisions, blockers, reducer decisions, and lifecycle events to the ledger. The objective is treated as user-provided data, not higher-priority instructions.
+`goal` starts with a single `prompt-refinement` stage that invokes the `prompt-engineer` skill (`/skill:prompt-engineer`) to sharpen the raw objective into a clearer, more actionable form using the Workflow Best Practices prompt anatomy documented later in this guide; the refined objective becomes the operative one recorded in the ledger (the original is preserved as `original_objective` and shown in the final report when it differs). `goal` then creates an OS-temp `goal-ledger.json` artifact, renders goal-continuation context for each worker turn, writes each worker receipt to `work-turn-N.md`, and appends receipts, reviewer decisions, blockers, reducer decisions, and lifecycle events to the ledger. The objective is treated as user-provided data, not higher-priority instructions. By default `goal` does not start the final `pull-request` stage, and `pr_report` is omitted. Prompt text alone does not opt in. Pass `create_pr=true` only when you explicitly want the final stage to inspect provider credentials and attempt provider-appropriate PR/MR/review creation, such as GitHub `gh`, Azure Repos `az repos pr create`, or Sapling/Phabricator tooling, after Goal reaches `complete` within `max_turns`. Goal worker and reviewer prompts explicitly tell intermediate stages to ignore PR-creation requests; only the final `pull-request` stage may attempt that handoff.
 
 Write the `objective` like a compact acceptance spec. Say what should exist when the run is done, how you want testing handled, which command(s) or manual checks matter, and what outcome proves completion. The workflow is intentionally lean: it does not first generate an RFC or migration plan, so the developer-supplied objective is where scope, validation, and completion criteria belong.
 
@@ -237,13 +242,16 @@ Result fields:
 | `status` | Final reducer status: `complete`, `blocked`, or `needs_human` (or `active` only if externally interrupted). |
 | `approved` | Whether the reducer reached `complete`. |
 | `goal_id` | Per-run goal identifier stored in the ledger. |
-| `objective` | Normalized goal objective used by the run. |
+| `objective` | Normalized goal objective used by the run (after the `prompt-refinement` stage refines the raw objective). |
+| `original_objective` | The raw user-provided objective exactly as given, before `prompt-refinement`. Omitted when refinement left it unchanged. |
 | `ledger_path` | OS-temp path to `goal-ledger.json`, including receipts, reviewer decisions, reducer decisions, blockers, and lifecycle events. |
 | `turns_completed` | Worker/review turns completed. |
 | `iterations_completed` | Same value as `turns_completed`, retained for status summaries. |
 | `receipts` | Ledger receipt summaries and worker artifact paths. |
 | `remaining_work` | Remaining gaps/blockers when incomplete, or `none`. |
 | `review_report` | Markdown report containing the last structured reviewer decision payloads used by the reducer. |
+| `review_report_path` | JSON artifact path for the latest Goal review round. |
+| `pr_report` | Pull-request report emitted only when `create_pr=true`, Goal reaches `complete`, and the final `pull-request` stage runs. |
 
 ### `ralph`
 
@@ -265,7 +273,7 @@ Run examples:
 /workflow ralph prompt="Safely implement the API refactor" git_worktree_dir=../atomic-ralph-api-wt base_branch=main
 ```
 
-Each `ralph` iteration starts by prompt-engineering the user prompt with `/skill:prompt-engineer Transform the following user prompt to a codebase and online research question which can be thoroughly explored: ...`, then researches that transformed question with `/skill:research-codebase ...` and writes the findings under `research/`. The orchestrator treats that research artifact as its primary implementation context, initializes/updates an OS-temp implementation notes file while generating verifiable evidence for any claims it records in the notes and reviewer artifacts, delegates implementation through sub-agents, and asks three independent reviewers to inspect the patch directly against `base_branch`. The reviewer fan-out runs each reviewer on a different primary model family (with shared fallbacks) so the adversarial review gets cross-model coverage instead of three passes from one model. Ralph's orchestrator and reviewers are prompted to verify user-visible behavior end-to-end when practical, using `playwright-cli`-skilled subagents for web/frontend flows that may depend on backend/API behavior and tmux-skilled subagents for TUI or terminal-app scenarios. For UI-applicable or full-stack changes, the orchestrator runs a `playwright-cli` end-to-end QA pass and records a reviewable proof video (referenced in the implementation notes and surfaced as `qa_video_path`); when `create_pr=true`, the final `pull-request` stage attaches or links that video to the created PR/MR/review. If reviewers find issues, the next prompt-engineering and research stages receive the review artifact path so follow-up research can address unresolved findings, and research stages fork from prior research session data when available. The loop stops only when all three reviewers independently approve (each finds no issues) or `max_loops` is reached, so a P0–P3 finding from any single reviewer keeps Ralph iterating instead of being out-voted by a majority quorum. By default Ralph does not start the final `pull-request` stage, and `pr_report` is omitted. Prompt text alone does not opt in. Pass `create_pr=true` only when you explicitly want the final `pull-request` stage to inspect provider credentials and attempt provider-appropriate PR/MR/review creation, such as GitHub `gh`, Azure Repos `az repos pr create`, or Sapling/Phabricator tooling; Ralph's own PR-creation instructions live in that final stage.
+Each `ralph` run starts with a single `prompt-refinement` stage that invokes the `prompt-engineer` skill (`/skill:prompt-engineer`) to sharpen the raw user prompt into a clearer, more actionable objective using the Workflow Best Practices prompt anatomy documented later in this guide; that refined prompt becomes the operative objective for research, orchestration, and review, while the original is surfaced as `original_prompt`. Each iteration then transforms the refined prompt with `/skill:prompt-engineer Transform the following refined user request into a codebase and online research question which can be thoroughly explored: ...` (`research-prompt-refinement`), researches that transformed question with `/skill:research-codebase ...`, and writes the findings under `research/`. The orchestrator treats that research artifact as its primary implementation context, initializes/updates an OS-temp implementation notes file while generating verifiable evidence for any claims it records in the notes and reviewer artifacts, delegates implementation through sub-agents, and asks three independent reviewers to inspect the patch directly against `base_branch`. The reviewer fan-out runs each reviewer on a different primary model family (with shared fallbacks) so the adversarial review gets cross-model coverage instead of three passes from one model. Ralph's orchestrator and reviewers are prompted to verify user-visible behavior end-to-end when practical, using `playwright-cli`-skilled subagents for web/frontend flows that may depend on backend/API behavior and tmux-skilled subagents for TUI or terminal-app scenarios. For UI-applicable or full-stack changes, the orchestrator runs a `playwright-cli` end-to-end QA pass and records a reviewable proof video (referenced in the implementation notes and surfaced as `qa_video_path`); when `create_pr=true`, the final `pull-request` stage attaches or links that video to the created PR/MR/review. If reviewers find issues, the next `research-prompt-refinement` and research stages receive the review artifact path so follow-up research can address unresolved findings, and research stages fork from prior research session data when available. The loop stops only when all three reviewers independently approve (each finds no issues) or `max_loops` is reached, so a P0–P3 finding from any single reviewer keeps Ralph iterating instead of being out-voted by a majority quorum. By default Ralph does not start the final `pull-request` stage, and `pr_report` is omitted. Prompt text alone does not opt in. Pass `create_pr=true` only when you explicitly want the final `pull-request` stage to inspect provider credentials and attempt provider-appropriate PR/MR/review creation, such as GitHub `gh`, Azure Repos `az repos pr create`, or Sapling/Phabricator tooling; Ralph's own PR-creation instructions live in that final stage.
 
 Set `git_worktree_dir` when you want Ralph's worker stages isolated in a reusable Git worktree. Relative paths resolve from the invoking repository root, existing same-repository worktree roots are reused, and missing paths are created from `base_branch`. Ralph preserves the invoking repo-relative cwd inside the worktree, so launching from `repo/packages/api` with `git_worktree_dir=../repo-wt` runs stages from `../repo-wt/packages/api`.
 
@@ -285,8 +293,10 @@ Result fields:
 | `iterations_completed` | Number of research/orchestrate/review loops completed. |
 | `review_report` | Compact reference to the latest reviewer payload artifact. |
 | `review_report_path` | JSON artifact path for the latest Ralph review round. |
+| `original_prompt` | The raw user prompt exactly as provided, before the `prompt-refinement` stage. |
+| `refined_prompt` | The clarity-refined prompt produced by the `prompt-refinement` stage and used as the operative objective for research, orchestration, and review. |
 
-A typical end-to-end flow is `/skill:research-codebase` → `/skill:create-spec` → `/workflow goal objective="Implement the researched rate-limit behavior, run the focused tests, and finish when the documented burst behavior is validated"` when you can identify the work surface, state the exact outcome, and name the validation that proves it is done. Keep using `/workflow ralph` for larger migrations, broad refactors, and multi-package changes where you want Atomic to research first, delegate through sub-agents, review, iterate, and optionally allow only the final `pull-request` stage to attempt PR creation with `create_pr=true`.
+A typical planned flow is `/skill:research-codebase` → `/skill:create-spec` → `/workflow ralph prompt="Implement specs/2026-03-rate-limit.md and validate the documented burst behavior"`. Ralph can start from a spec path, GitHub issue, or crisp ticket description, then refines the prompt, researches as needed, delegates through sub-agents, reviews, records a QA proof video for UI/full-stack changes when practical, and iterates. For smaller one-off tasks, use `/workflow goal` with a concrete objective that identifies the work surface, states the exact outcome, and names the validation that proves it is done; add `create_pr=true` only when you want Goal's final `pull-request` stage after approval.
 
 ### `open-claude-design`
 
@@ -294,21 +304,21 @@ Inputs:
 
 | Input | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `prompt` | text | yes | — | What to design (dashboard, page, component, prototype, …). |
-| `reference` | text | no | — | URL, file path, screenshot path, or design doc to import as a reference. |
-| `output_type` | select | no | `prototype` | One of `prototype`, `wireframe`, `page`, `component`, `theme`, `tokens`. |
-| `design_system` | text | no | — | Path(s) or description of an existing design system (e.g. `DESIGN.md`, `PRODUCT.md`). Skips onboarding when provided. |
-| `max_refinements` | number | no | `3` | Maximum critique/apply refinement iterations. |
+| `prompt` | text | yes | — | What to design (dashboard, page, component, prototype, …). The discovery stage refines this into a confirmed brief and asks for the output type and references. |
+| `discover_references` | boolean | no | `true` | Discover beautiful, current reference designs (Awwwards, recent.design, Dribbble, Monet, Motionsites) and feed them to generation. Set `false` to skip the network/browser reference pass. |
+| `max_refinements` | number | no | `3` | Maximum generate/user-feedback loop iterations. |
+
+The output type (`prototype`, `wireframe`, `page`, `component`, `theme`, `tokens`) and any reference designs are **not** inputs — the discovery stage asks for them. There is no `design_system` input; the project's `DESIGN.md`/`PRODUCT.md` are established/loaded automatically.
 
 Result fields:
 
 | Field | Meaning |
 |---|---|
-| `output_type` | Kind of design artifact produced. |
-| `design_system` | Design system source used for generation: supplied input or project-derived design system. |
+| `output_type` | Kind of design artifact produced (chosen during the discovery interview). |
+| `design_system` | Design system source used for generation: the project-derived design system. |
 | `artifact` | Latest final design summary from the approved preview artifact. |
 | `handoff` | Final rich HTML spec and implementation handoff summary. |
-| `approved_for_export` | Whether refinement completed before the final export gate. |
+| `approved_for_export` | Whether the latest user-feedback stage reported no further changes before export. |
 | `refinements_completed` | Number of refinement iterations completed. |
 | `import_context` | Reference-import context used during generation. |
 | `run_id` | Per-run design workflow artifact identifier. |
@@ -321,14 +331,28 @@ Result fields:
 
 `open-claude-design` has no `result` output; it exposes only the declared fields listed above. Use the declared `artifact` and `handoff` fields for generated content.
 
+**Combined discovery/init.** The workflow's first and only front-door stage runs `/skill:impeccable shape` and `/skill:impeccable init` together. It interviews you (via the structured question tool) about what you want to build, the **output type** (`prototype`, `wireframe`, `page`, `component`, `theme`, or `tokens`), and which **references** to emulate (URLs, local file paths, screenshots, or design docs). Then, in the same `discovery` stage, impeccable init performs its own `PRODUCT.md`/`DESIGN.md` detection and creates or reconciles those files as needed. The references you name take **precedence over `DESIGN.md`/`PRODUCT.md`** during generation (the design system fills gaps the references don't cover, and `PRODUCT.md` still governs strategic register/voice). Headless runs infer a defensible brief, output type, references, and project-context assumptions rather than blocking.
+
+**Context and reference phase.** Design-system/reference research runs first, then gallery reference discovery uses those findings before the generator consumes the combined context:
+
+- *Design-system/reference research* — three parallel passes (`ds-locator` / `ds-analyzer` / `ds-patterns`) extract the project's design-system evidence and also handle user-provided references. URL references are captured with browser/screenshot tooling where available; local files, screenshots, and design docs are parsed by the applicable `ds-*` pass. Their extracted requirements feed the generator and **take precedence over `DESIGN.md`/`PRODUCT.md`**. There are no separate `web-capture-*`, `file-parser-*`, or `design-system-builder` stages.
+- *Reference discovery* (gated by `discover_references=true`, the default) — after the `ds-*` passes complete, the `reference-discovery` stage receives their evidence plus the `PRODUCT.md`/`DESIGN.md` init summary. It uses the `playwright-cli` skill to browse five curated galleries — [Awwwards](https://www.awwwards.com/websites/), [recent.design](https://recent.design/), [Dribbble recents](https://dribbble.com/shots/recent), [Monet](https://www.monet.design/c), and [Motionsites](https://motionsites.ai/) — then **clicks into the standout work** and, ideally, **records a scroll-through video of each real design page so its animations are captured** (with a full-page screenshot as a supplement/fallback) plus the real destination URL (it does not just screenshot the gallery thumbnails; web-search fallback when the browser is unavailable). It then asks which curated reference direction you prefer; if none align, it asks you to provide a reference image, screenshot, URL, or local path for best results. The curated **references brief** is persisted to `<artifact_dir>/references.md` and threaded into the generator (`reference_inspiration`) and refinement. Set `discover_references=false` to skip it.
+
+**Generate/user-feedback loop.** Refinement is intentionally simple and mirrors Ralph's implement/reviewer rhythm: `generate-1` writes the first `preview.html`, `user-feedback-1` opens that preview with `/skill:impeccable live`, and any captured `live_changes`, `user_notes`, or `annotated_snapshot` feed the next forked `generate-*` stage. Each later `generate-*` forks from the previous generate session, and each later `user-feedback-*` forks from the previous feedback session, preserving focused continuity without adding extra critique/screenshot/apply stages. When a `user-feedback-*` stage captures no meaningful feedback, the loop exports immediately. Export is deliberately just `exporter` followed by `final-display`; there is no pre-export scan, forced-fix stage, or export gate. Captured feedback is persisted as durable artifacts under `<artifact_dir>/feedback/iteration-<n>.md` / `.json` (plus a best-effort copy of the annotated snapshot, constrained to files within the project/artifact dir). If captured notes fail to thread into the next generate prompt, the run fails loudly rather than silently generating without user feedback.
+
+**Browser requirement.** open-claude-design is browser-centric (the discovery/preview review and the `live` QA loop need the `playwright-cli` skill's browser). If the browser cannot be made available, the workflow exits cleanly up front — surfacing the would-be artifact paths and install instructions — rather than generating a design you could not review interactively. (This early exit is skipped under the test harness so headless test runs still complete.)
+
 Run examples:
 
 ```text
 /workflow open-claude-design prompt="Refresh the settings page hierarchy"
-/workflow open-claude-design prompt="Design a billing page" reference=https://stripe.com/billing output_type=page
-/workflow open-claude-design prompt="Generate spacing and color tokens" output_type=tokens design_system=./DESIGN.md
+/workflow open-claude-design prompt="Design a billing page like Stripe's"
+/workflow open-claude-design prompt="Generate spacing and color tokens"
+/workflow open-claude-design prompt="Design a marketing landing page" discover_references=false
 ```
 
+The discovery interview asks for the output type and any reference URLs/files, so you no longer pass `output_type`, `reference`, or `design_system` on the command line.
+
 ### Launching with natural language
 
 You can also kick off a built-in workflow by describing the task in chat. Atomic picks the matching workflow and fills in inputs from your request:
@@ -389,7 +413,7 @@ If the task is only deterministic TypeScript with no LLM/session stage, use a sc
 | User goal | Use |
 |-----------|-----|
 | Run, inspect, attach to, pause, interrupt, resume, or check status for an existing workflow | `/workflow ...` or `workflow({ action: ... })` |
-| Implement a small-to-medium scope change with an identifiable work surface, exact outcome, and named validation | `/workflow goal objective="..."` so Atomic keeps the run bounded, captures receipts in a goal ledger, gates completion through reviewers, and stops as `complete`, `blocked`, or `needs_human` |
+| Implement a small-to-medium scope change with an identifiable work surface, exact outcome, and named validation | `/workflow goal objective="..."` so Atomic keeps the run bounded, captures receipts in a goal ledger, gates completion through reviewers, stops as `complete`, `blocked`, or `needs_human`, and can optionally run a final PR handoff with `create_pr=true` after approval |
 | Research and execute a larger migration, broad refactor, or multi-package change | `/workflow ralph prompt="..."` so Atomic can transform the prompt into a research question, research the codebase first, delegate implementation through sub-agents, review, and iterate; prompt text alone does not opt in to PR creation, so add `create_pr=true` only when you want the final `pull-request` stage and `pr_report` |
 | Create or edit reusable automation | a TypeScript workflow definition exported from `workflow({...})` |
 | Track one-off work without saving a workflow file | direct `workflow({ task })`, `workflow({ tasks })`, or `workflow({ chain })` calls |
@@ -570,13 +594,13 @@ Record the selected pattern in your spec or workflow README, then adapt the diag
 
 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.
 
-The difference is where control lives.
+Atomic's category is broader and more explicit: it is the loop engine for engineering work. The difference is where control lives and how much of the loop you can inspect, version, extend, and connect to your stack.
 
 | Dimension | Atomic | Claude Code Dynamic Workflows |
 | --- | --- | --- |
-| Core idea | Open-source, repo-native workflow automation for coding agents. You can run built-ins, tell the coding agent to use a workflow for a task, describe new workflows in natural language for Atomic to scaffold dynamically, or version them as explicit TypeScript files. | Claude dynamically creates orchestration scripts for a task and fans work out to many parallel Claude subagents. |
-| Best fit | Teams that want repeatable software engineering workflows they can inspect, version, extend, and run across providers. | Claude Code users who want Claude to decide when a task needs a larger dynamic workflow and orchestrate it automatically. |
-| Workflow control | The process is explicit: stages, inputs, handoffs, retries, artifacts, model choices, and human gates are part of the workflow definition. | The process is generated dynamically by Claude for the current task, with confirmation before the first workflow run. |
+| Core idea | Open-source, repo-native loop engine for coding agents. You can run built-ins, tell the coding agent to use a workflow for a task, describe new loops in natural language for Atomic to scaffold dynamically, or version them as explicit TypeScript files. | Claude dynamically creates orchestration scripts for a task and fans work out to many parallel Claude subagents. |
+| Best fit | Teams that want repeatable software engineering loops they can inspect, version, extend, connect to tools, and run across providers. | Claude Code users who want Claude to decide when a task needs a larger dynamic workflow and orchestrate it automatically. |
+| Workflow control | The process is explicit: stages, inputs, handoffs, retries, artifacts, model choices, checkpoints, and human gates are part of the workflow definition. | The process is generated dynamically by Claude for the current task, with confirmation before the first workflow run. |
 | Models | Model-agnostic. Atomic connects directly to supported API-key and subscription providers, and workflows can use model fallback chains. | Claude-first. Availability is tied to Claude Code, Claude plans, and Anthropic-supported API/cloud channels. |
 | Extensibility | Built on Pi extensions: add tools, TUI, MCP, web access, intercom, skills, prompt templates, themes, custom providers, and packaged workflows. | Optimized for Claude Code's built-in dynamic orchestration experience rather than an open extension SDK you own in-repo. |
 | Artifacts and auditability | Research docs, specs, logs, transcripts, reviewer notes, check output, and final summaries can live in the repo or workflow run directory. | Progress is saved and resumable, but the orchestration is primarily a Claude Code runtime behavior. |
@@ -1071,27 +1095,7 @@ Authoring basics:
 - `outputs` declares typed outputs that parent workflows receive from `ctx.workflow(childWorkflow, ...)`.
 - `run: async (ctx) => { ... }` defines the workflow body.
 
-Codemod-style migration from the removed builder API:
-
-```diff
--import { defineWorkflow, Type } from "@bastani/workflows";
-+import { workflow } from "@bastani/workflows";
-+import { Type } from "typebox";
-
--export default defineWorkflow("review-changes")
--  .description("Run two reviewers and synthesize findings.")
--  .input("target", Type.String())
--  .output("decision", Type.String())
--  .run(async (ctx) => ({ decision: await review(ctx) }))
--  .compile();
-+export default workflow({
-+  name: "review-changes",
-+  description: "Run two reviewers and synthesize findings.",
-+  inputs: { target: Type.String() },
-+  outputs: { decision: Type.String() },
-+  run: async (ctx) => ({ decision: await review(ctx) }),
-+});
-```
+Migrating an existing file from the removed `defineWorkflow(...).compile()` builder? See [Migrating from the `defineWorkflow()` Builder API](#migrating-from-the-defineworkflow-builder-api) for the full method-to-key mapping, a before/after walkthrough, and a conversion checklist.
 
 `prompt` and `task` are aliases for task text. Prefer `prompt` inside authored workflow files because it mirrors lower-level `stage.prompt(...)`; `task` remains useful in direct tool calls and chain examples.
 
@@ -1383,7 +1387,7 @@ Common builtin import targets:
 | Workflow name | TypeScript export | Individual module path | Typical use inside another workflow |
 |---|---|---|---|
 | `deep-research-codebase` | `deepResearchCodebase` | `@bastani/workflows/builtin/deep-research-codebase` | Gather broad repo research before planning, synthesis, or implementation. |
-| `goal` | `goal` | `@bastani/workflows/builtin/goal` | Run a bounded implementation/check loop with receipts and reviewer-gated completion. |
+| `goal` | `goal` | `@bastani/workflows/builtin/goal` | Run a bounded implementation/check loop with receipts and reviewer-gated completion; pass `create_pr=true` to authorize only the final PR-creation stage after approval. |
 | `ralph` | `ralph` | `@bastani/workflows/builtin/ralph` | Delegate a larger migration/refactor effort to Ralph's research/orchestrate/review loop; pass `create_pr=true` to authorize only the final PR-creation stage. |
 | `open-claude-design` | `openClaudeDesign` | `@bastani/workflows/builtin/open-claude-design` | Generate and refine a UI/design artifact and handoff spec. |
 
@@ -1503,6 +1507,121 @@ If a parent workflow exits through `ctx.exit(...)` while a child workflow is in
 
 Continuation replay treats the parent child-workflow boundary as the durable checkpoint: a previously completed child boundary replays with the original exposed outputs and without re-running the child, while a child that failed or was interrupted before completion starts again from the beginning on continuation. If `ctx.exit(...)` wins while a completed boundary is being replayed but before replay finalization, the boundary is finalized as skipped and its preloaded child metadata is omitted from store, persistence, restore, and expanded graph views.
 
+## Migrating from the `defineWorkflow()` Builder API
+
+The chained builder API — `defineWorkflow(name).description(...).input(...).output(...).worktreeFromInputs(...).run(...).compile()` — was removed in [#1457](https://github.com/bastani-inc/atomic/pull/1457). The single `workflow({ name?, description, inputs, outputs, run })` object form is now the only authoring door. There is no shim and no deprecation period: workflow files that still call `defineWorkflow(...).compile()` fail discovery with a module-load error until they are migrated.
+
+This section is for workflow files written against the previous API. If you are authoring a new workflow, skip it and start from [Writing a Workflow](#writing-a-workflow).
+
+### What changed
+
+- `import { defineWorkflow, Type } from "@bastani/workflows"` → `workflow` now comes from `@bastani/workflows`, and `Type` comes from the `typebox` package directly. `@bastani/workflows` no longer re-exports `Type`. The `Static` and `TSchema` *type* exports are still re-exported from `@bastani/workflows`, so `import type { Static } from "@bastani/workflows"` keeps working — only the runtime `Type` builder moved.
+- The fluent builder chain became one object literal passed to `workflow({ ... })`.
+- `name` moved from the `defineWorkflow(name)` argument into the object. It is now **optional** — omit it and discovery derives the name from the filename (the recommended style used by the builtins and most examples), or keep it when you want the name to differ from the file's basename.
+- `outputs` is now **required**. Workflows that declared no outputs before must now pass `outputs: {}`.
+- `.compile()` is gone. `workflow({ ... })` returns the frozen, branded definition directly; `export default` it.
+- The imperative object-form `runWorkflow(...)` runner is also removed (it is a `never` placeholder that throws on access). Programmatic execution uses the exported `run(def, inputs)` helper or a registry — see [Programmatic Usage](#programmatic-usage).
+
+### Builder method → object key
+
+| Removed builder API | New `workflow({ ... })` key |
+| --- | --- |
+| `defineWorkflow("name")` argument | `name: "name"` (optional; derived from the filename when omitted) |
+| `.description(text)` | `description: text` |
+| `.input(key, schema)` (repeatable) | `inputs: { key: schema, ... }` |
+| `.output(key, schema)` (repeatable) | `outputs: { key: schema, ... }` (required, even if `{}`) |
+| `.worktreeFromInputs(binding)` | `worktreeFromInputs: binding` (binding shape unchanged) |
+| `.run(fn)` callback | `run: fn` |
+| `.compile()` terminal | delete — `workflow({ ... })` returns the definition |
+
+`ctx` and every primitive (`ctx.task`, `ctx.chain`, `ctx.parallel`, `ctx.stage`, `ctx.workflow`, `ctx.exit`, `ctx.ui`) are unchanged, so workflow **bodies do not need rewriting** — only the authoring wrapper changes.
+
+### Full before / after
+
+Before (removed API):
+
+```ts
+import { defineWorkflow, Type } from "@bastani/workflows";
+
+export default defineWorkflow("review-changes")
+  .description("Run two reviewers in parallel and synthesize a decision.")
+  .input("target", Type.String({ description: "Path or change target to review." }))
+  .input("base_branch", Type.String({ default: "origin/main" }))
+  .output("decision", Type.String())
+  .output("concerns", Type.Optional(Type.Array(Type.String())))
+  .worktreeFromInputs({ baseBranch: "base_branch" })
+  .run(async (ctx) => {
+    const target = String(ctx.inputs.target);
+    const [quality, runtime] = await ctx.parallel(
+      [
+        { name: "quality", prompt: `Review quality of ${target}` },
+        { name: "runtime", prompt: `Review runtime behavior of ${target}` },
+      ],
+      { concurrency: 2 },
+    );
+    return { decision: `${quality.text}\n${runtime.text}`, concerns: [] };
+  })
+  .compile();
+```
+
+After (current API):
+
+```ts
+import { workflow } from "@bastani/workflows";
+import { Type } from "typebox";
+
+export default workflow({
+  name: "review-changes", // optional — omit to derive from filename
+  description: "Run two reviewers in parallel and synthesize a decision.",
+  inputs: {
+    target: Type.String({ description: "Path or change target to review." }),
+    base_branch: Type.String({ default: "origin/main" }),
+  },
+  outputs: {
+    decision: Type.String(),
+    concerns: Type.Optional(Type.Array(Type.String())),
+  },
+  worktreeFromInputs: { baseBranch: "base_branch" },
+  run: async (ctx) => {
+    const target = String(ctx.inputs.target);
+    const [quality, runtime] = await ctx.parallel(
+      [
+        { name: "quality", prompt: `Review quality of ${target}` },
+        { name: "runtime", prompt: `Review runtime behavior of ${target}` },
+      ],
+      { concurrency: 2 },
+    );
+    return { decision: `${quality.text}\n${runtime.text}`, concerns: [] };
+  },
+});
+```
+
+### Conversion checklist
+
+For each `.atomic/workflows/*.ts` (or workflow-package) file:
+
+1. Swap the import to `import { workflow } from "@bastani/workflows"` and add `import { Type } from "typebox"`. Drop `defineWorkflow` from the `@bastani/workflows` import. `import type { Static, TSchema }` can stay on the `@bastani/workflows` import if you use those types.
+2. Replace `defineWorkflow("<name>")` with `workflow({`. You may keep `name: "<name>"` or drop the key entirely to derive the name from the filename.
+3. Move `.description("<text>")` to a `description: "<text>",` property.
+4. Collect every `.input(key, schema)` into one `inputs: { key: schema, ... },` map.
+5. Collect every `.output(key, schema)` into one `outputs: { key: schema, ... },` map. If there were no `.output(...)` calls, add `outputs: {},` — it is now required.
+6. Move `.worktreeFromInputs(binding)` to a `worktreeFromInputs: binding,` property (same binding shape, unchanged).
+7. Move the `.run(fn)` callback to a `run: fn,` property; the body stays byte-for-byte the same.
+8. Delete the trailing `.compile()`, close the object with `})`, and keep `export default`.
+9. Run `/workflow reload` (or restart Atomic) and `/workflow list` to confirm the file loads. Because `ctx` and its primitives are unchanged, stage behavior, graph layout, resume/kill, and human-input prompts are unaffected.
+
+### Gotchas
+
+- **`outputs` is required.** The old `.output(...)` calls were optional, and a workflow with none compiled fine. The new object form throws `workflow: outputs must be a schema map` when `outputs` is missing, so declare `outputs: {}` for outputless workflows.
+- **`Type` is no longer re-exported.** `import { Type } from "@bastani/workflows"` fails type-checking; import it from `typebox` instead. (`Static` and `TSchema` *types* are still re-exported from `@bastani/workflows`, so those imports do not need to change.)
+- **`.compile()` does not exist.** Leaving it produces a runtime `TypeError`; `workflow({ ... })` already returns the frozen, branded definition.
+- **`name` is derived from the filename when omitted.** `review-changes.ts` becomes the `review-changes` workflow, so an explicit `name` is only needed when it should differ from the basename.
+- **No hand-rolled definitions.** Objects carrying `__piWorkflow: true` that you construct by hand are rejected by discovery and by `ctx.workflow(...)`. Only definitions minted by `workflow({ ... })` are accepted.
+- **The imperative `runWorkflow` runner is gone.** It is now a `never` placeholder that throws on access; use the exported `run(def, inputs)` helper or a registry for programmatic execution.
+- **Keep `outputs` inline for the strictest type checking.** The old builder enforced no-extra-output keys through a `NoExtraOutputs` generic on `.run(fn)`; the object form re-creates that check for inline `outputs` maps, but cannot recover output keys when a schema map is widened or built up before being passed to `workflow({ ... })`. Keep the `outputs` literal inline so the declared-key check stays exact.
+
+Everything else — stage primitives, `ctx.inputs` typing, runtime validation, DAG inference, MCP scoping, resume/kill, worktree binding, model fallback, and the `/workflow` tool contract — is unchanged.
+
 ## Workflow Primitives
 
 Prefer high-level primitives because they create tracked graph nodes, provide consistent handoff semantics, and keep workflow definitions easier to read.
@@ -1904,3 +2023,653 @@ Good workflows are information-flow systems, not just prompt sequences. Keep sta
 - Do not write stage prompts that depend on hidden workflow-wide awareness; make each model stage locally scoped and self-described.
 - Do not parse model gate decisions from ad-hoc prose with regular expressions; configure `schema` on a focused workflow item and consume `result.structured`.
 - Return compact structured decisions and save large artifacts to files; artifact handoffs should still use files when the next stage does not need the whole payload in context.
+
+## Workflow Best Practices
+
+This is the playbook I use to get consistently better results from coding agents and workflow systems.
+
+The core idea is simple: do not treat an agent like a magic box. Treat it like a capable engineering partner that needs a clear objective, tight scope, explicit validation, and occasional steering.
+
+Most weak agent runs fail for predictable reasons: the goal is vague, the scope is too broad, validation is missing, or the agent keeps following the wrong signal. This playbook is about avoiding those failure modes.
+
+The examples below are synthetic and intentionally generic. Replace placeholders like `[component]`, `[test command]`, and `[workflow]` with your own project details.
+
+---
+
+### The core loop
+
+The workflow pattern I rely on most often is:
+
+```text
+Objective -> Scope -> Done criteria -> Run -> Inspect -> Steer -> Validate -> Summarize
+```
+
+In practice, that means:
+
+1. Define the end state.
+2. Constrain the blast radius.
+3. State what counts as done.
+4. Let the agent or workflow work.
+5. Inspect status before reading details.
+6. Steer only when the run is off track, blocked, or missing criteria.
+7. Require evidence before accepting the result.
+8. Ask for a summary, handoff, or next-step plan.
+
+A good workflow prompt does not just say what to try. It says what success looks like.
+
+---
+
+### Prompt anatomy
+
+A strong workflow prompt usually has these parts:
+
+#### Objective
+
+What should be true when the work is complete?
+
+```text
+Implement `[specific behavior]` in `[component]`.
+```
+
+#### Context
+
+What does the agent need to know before acting?
+
+```text
+This is needed because `[reason]`. The relevant code likely lives near `[area]`.
+```
+
+#### Scope
+
+What is the agent allowed to change?
+
+```text
+Only touch files directly required for `[behavior]`.
+```
+
+#### Non-goals
+
+What should the agent avoid?
+
+```text
+Do not redesign `[subsystem]`, refactor unrelated code, or change public behavior outside `[case]`.
+```
+
+#### Done criteria
+
+How will we know the work is complete?
+
+```text
+Done means:
+- `[new behavior]` works.
+- `[existing behavior]` is unchanged.
+- `[test command]` passes.
+- The final response includes changed files, validation results, and remaining risks.
+```
+
+#### Stop conditions
+
+When should the agent stop and ask instead of guessing?
+
+```text
+If this requires changing `[public API/security behavior/data migration]`, stop and ask first.
+```
+
+---
+
+### Core principles
+
+#### 1. Start with the end state
+
+I try to describe what should be true at the end, not just what the agent should investigate.
+
+Bad:
+
+```text
+Look into the login issue.
+```
+
+Better:
+
+```text
+Fix the login redirect regression. Done means users who sign in from `[page]` return to `[expected destination]`, and `[test command]` passes.
+```
+
+#### 2. Keep scope tight
+
+Agents are often tempted to clean up nearby code. Sometimes that is useful, but most workflow runs should be bounded.
+
+Use phrases like:
+
+- `Only touch files required for this behavior.`
+- `Do not refactor unrelated code.`
+- `Preserve existing behavior for [case].`
+- `Make the smallest correct change.`
+
+#### 3. Separate implementation from validation
+
+A change is not done because the agent says it is done. It is done when the relevant evidence supports it.
+
+That evidence can be:
+
+- a targeted test,
+- a broader regression test,
+- a smoke command,
+- a typecheck or lint command,
+- a structured output contract check,
+- or a clear manual verification step.
+
+#### 4. Prefer evidence over speculation
+
+When something fails, I steer the agent back to the observable signal: the error, failing test, log line, user behavior, or broken contract.
+
+```text
+Treat the failing assertion as the source of truth. Do not guess from nearby code alone.
+```
+
+#### 5. Use staged thinking
+
+For ambiguous work, I usually separate the flow into stages:
+
+```text
+Investigate -> identify root cause -> propose fix -> implement -> validate -> summarize
+```
+
+If the cause is not clear, I do not want the agent making broad changes just to see what happens.
+
+#### 6. Steer, do not micromanage
+
+The best steering messages are short and corrective. They add constraints, redirect attention, or provide a decision.
+
+You usually do not need to rewrite the whole prompt. You need to say what changed.
+
+#### 7. Treat failed validation as the next task
+
+A failed test is not a footnote. It becomes the next objective.
+
+```text
+Validation failed on `[command]`. Treat that as the source of truth. Fix the root cause only, rerun the failing check, then report the result.
+```
+
+#### 8. Interrupt stale or wrong work
+
+If a run is solving the wrong problem, based on outdated assumptions, or duplicating another run, stop it. Letting it continue usually creates more cleanup later.
+
+#### 9. Inspect at the right level
+
+For long-running workflows, I do not start by reading every log. I check:
+
+1. overall status,
+2. current stage,
+3. blocker or failure reason,
+4. relevant stage details only if needed.
+
+#### 10. Ask for synthesis before handoff
+
+Before switching from investigation to implementation, or from implementation to review, I often ask for a concise synthesis:
+
+```text
+Summarize root cause, proposed fix, files involved, validation plan, and remaining risks.
+```
+
+---
+
+### Common workflow patterns
+
+#### Scoped implementation sprint
+
+**Use when:** You have a clear feature, bug fix, or issue to delegate.
+
+**Prompt shape:**
+
+```text
+Implement `[feature]` in `[component]`. Only touch files directly needed for this behavior. Done means the new behavior works, existing behavior is unchanged, and `[test command]` passes.
+```
+
+**Why it works:** The agent gets autonomy, but the objective and blast radius are bounded.
+
+**Validation:** Run the most relevant targeted check first, then a broader nearby check if the change is risky.
+
+---
+
+#### Regression repair loop
+
+**Use when:** CI, tests, typecheck, lint, or smoke validation fails.
+
+**Prompt shape:**
+
+```text
+Fix the failing `[test suite]` regression. Treat the failure output as the source of truth. Do not refactor unrelated code. Done means the failing test passes and no nearby tests regress.
+```
+
+**Why it works:** It anchors the run to observable evidence instead of speculation.
+
+**Validation:** Reproduce the failure, fix the root cause, rerun the failing check, then run a nearby or broader check.
+
+---
+
+#### Workflow or tooling smoke test
+
+**Use when:** You changed a workflow definition, prompt contract, structured output, CLI behavior, or developer tool.
+
+**Prompt shape:**
+
+```text
+Validate `[workflow/tool]` after the change. Run a minimal smoke case, confirm required outputs are present, and report whether it can be invoked with expected inputs.
+```
+
+**Why it works:** Workflow and tooling changes often fail at integration boundaries. A small smoke case catches those failures early.
+
+**Validation:** Reload or rerun the tool, check the output shape, and report contract mismatches.
+
+---
+
+#### Human-in-the-loop checkpoint
+
+**Use when:** The workflow might need a product decision, API decision, migration choice, or risky approval.
+
+**Prompt shape:**
+
+```text
+If blocked, ask before changing public API behavior. Otherwise proceed with the smallest compatible fix.
+```
+
+**Why it works:** The agent keeps moving where it can, but does not guess on high-impact decisions.
+
+**Validation:** Confirm the decision is reflected in the final behavior and summary.
+
+---
+
+#### Release gate
+
+**Use when:** Preparing a release, version bump, changelog, publish step, migration, or deployment-adjacent task.
+
+**Prompt shape:**
+
+```text
+Prepare a `[release kind]` release for `[version]`. Do not publish unless validation passes. Report the exact checks performed and any unresolved blockers.
+```
+
+**Why it works:** Release work needs explicit gates and stop conditions.
+
+**Validation:** Require changelog review, tests, build/package checks, and a clear publish/no-publish decision.
+
+---
+
+#### Monitor-and-steer long run
+
+**Use when:** A workflow runs asynchronously, has multiple stages, or may need supervision.
+
+**Prompt shape:**
+
+```text
+Show the current stage and blocker. If implementation is complete, summarize validation status and remaining risks.
+```
+
+**Why it works:** It avoids both blind trust and excessive log-reading.
+
+**Validation:** Inspect status first, then stages, then only the relevant details.
+
+---
+
+#### Investigate before implementing
+
+**Use when:** A bug or request is ambiguous.
+
+**Prompt shape:**
+
+```text
+Investigate `[bug]`, identify root cause, and propose the smallest fix. Do not implement until the cause is clear.
+```
+
+**Why it works:** It prevents the agent from making changes before it understands the failure mode.
+
+**Validation:** Ask for a reproduction, root-cause explanation, proposed fix, and test plan before implementation.
+
+---
+
+### Steering patterns
+
+#### Tighten scope
+
+**Signal:** The agent starts expanding into adjacent cleanup, unrelated files, or broad refactors.
+
+**Steer:**
+
+```text
+Narrow this to `[specific behavior]` in `[component]`. Do not refactor unrelated code or change `[adjacent area]`. Done means `[specific acceptance criteria]`.
+```
+
+**Why:** Prevents risky changes and keeps the run reviewable.
+
+---
+
+#### Add missing done criteria
+
+**Signal:** The agent has a plan, but no clear finish line.
+
+**Steer:**
+
+```text
+Use these done criteria:
+1. `[behavior]` works.
+2. `[regression]` remains unchanged.
+3. `[test command]` passes.
+4. Report files changed and validation results.
+```
+
+**Why:** Makes completion verifiable.
+
+---
+
+#### Redirect an off-track stage
+
+**Signal:** The workflow is investigating the wrong area or solving the wrong problem.
+
+**Steer:**
+
+```text
+Stop pursuing `[wrong direction]`. The relevant signal is `[error/test/user behavior]`. Re-focus on `[target area]` and continue from there.
+```
+
+**Why:** Saves time and prevents wrong assumptions from compounding.
+
+---
+
+#### Respond to a blocked prompt
+
+**Signal:** The workflow asks for approval, a choice, or clarification.
+
+**Steer:**
+
+```text
+Choose `[option]`. Continue only if `[condition]`; otherwise stop and report the blocker.
+```
+
+**Why:** Keeps the workflow unblocked without adding ambiguity.
+
+---
+
+#### Turn failed validation into the next task
+
+**Signal:** Tests, typecheck, lint, build, or smoke checks fail.
+
+**Steer:**
+
+```text
+Validation failed on `[command]`. Treat that as the source of truth. Fix the root cause only, rerun the failing check, then report the result.
+```
+
+**Why:** Prevents accepting partially working output.
+
+---
+
+#### Ask for synthesis
+
+**Signal:** The workflow has gathered information, but the next action is unclear.
+
+**Steer:**
+
+```text
+Synthesize the current findings into: root cause, proposed fix, files likely involved, validation plan, and remaining risks.
+```
+
+**Why:** Converts exploration into a usable plan.
+
+---
+
+#### Pause, kill, or rerun
+
+**Signal:** A run is stale, duplicated, superseded, or based on outdated assumptions.
+
+**Steer:**
+
+```text
+Pause this run; it has been superseded by `[new context]`. Resume only with `[updated objective]`, or stop and summarize current state.
+```
+
+**Why:** Avoids conflicting changes and wasted work.
+
+---
+
+### Copy-paste templates
+
+#### Start a workflow
+
+```text
+Objective:
+Implement/fix `[specific behavior]` in `[component]`.
+
+Context:
+`[short context about why this matters or where to look]`
+
+Scope:
+- Only touch files required for `[behavior]`.
+- Do not refactor unrelated code.
+- Preserve existing behavior for `[existing case]`.
+
+Done criteria:
+- `[new behavior]` works.
+- `[regression case]` still works.
+- `[test command]` passes.
+- Report changed files, validation results, and any risks.
+
+Stop conditions:
+- If this requires `[risky decision]`, stop and ask first.
+```
+
+#### Tighten scope
+
+```text
+Tighten scope to `[specific target]`.
+
+Do not work on:
+- `[excluded area 1]`
+- `[excluded area 2]`
+- broad cleanup or unrelated refactors
+
+Continue only on the path needed to satisfy:
+`[acceptance criterion]`.
+```
+
+#### Add acceptance criteria
+
+```text
+Add these acceptance criteria before continuing:
+
+1. User can `[action]`.
+2. System handles `[edge case]`.
+3. Existing behavior `[existing behavior]` is unchanged.
+4. `[test command]` passes.
+5. Final response includes validation evidence.
+```
+
+#### Redirect a stage
+
+```text
+This stage is off track.
+
+Stop investigating `[wrong area]`.
+The relevant signal is `[error/output/requirement]`.
+Refocus on `[correct area]`.
+
+Next:
+1. Reproduce or inspect `[signal]`.
+2. Identify root cause.
+3. Make the smallest fix.
+4. Run `[validation command]`.
+```
+
+#### Handle failed validation
+
+```text
+Validation failed:
+
+Command:
+`[command]`
+
+Failure:
+`[short sanitized failure summary]`
+
+Treat this as the source of truth.
+Fix only the root cause.
+Rerun the failing command.
+If it still fails, summarize the blocker and stop.
+```
+
+#### Ask for synthesis
+
+```text
+Synthesize current progress into:
+
+- What was attempted
+- What changed
+- What evidence supports the result
+- What remains uncertain
+- Recommended next steps
+- Exact validation commands run
+```
+
+#### Turn findings into implementation steps
+
+```text
+Convert the findings into an implementation plan:
+
+1. Files/components to change
+2. Order of changes
+3. Tests to add or update
+4. Validation commands
+5. Risks or edge cases
+6. Stop conditions
+```
+
+#### Prepare a release gate
+
+```text
+Prepare `[version]` as a `[release kind]` release.
+
+Requirements:
+- Verify changelog entries are complete.
+- Run `[test command]`.
+- Run `[build/package command]`.
+- Do not publish unless all validation passes.
+- If any gate fails, stop and report blockers.
+
+Final response should include:
+- Version
+- Checks run
+- Results
+- Files changed
+- Publish readiness
+```
+
+---
+
+### Concrete examples
+
+#### Example 1: Fixing a failing test
+
+**Scenario:** A package has one failing unit test after a recent change.
+
+**Initial objective:**
+
+```text
+Fix the failing `[unit test]`. Do not rewrite the module. Done means the test passes and nearby tests still pass.
+```
+
+**Steering message:**
+
+```text
+Stop exploring unrelated failures. Focus only on the assertion mismatch in `[test file]`.
+```
+
+**Validation:** Run `[targeted test command]`, then `[nearby test command]`.
+
+**Outcome:** Small fix applied, regression test passes, and the workflow reports exact commands and results.
+
+---
+
+#### Example 2: Repairing a workflow definition
+
+**Scenario:** A custom workflow no longer returns the expected structured output.
+
+**Initial objective:**
+
+```text
+Validate `[workflow]` and fix its output contract. Done means the smoke run returns `[required fields]`.
+```
+
+**Steering message:**
+
+```text
+Treat the missing output field as the root issue. Do not change unrelated stage prompts.
+```
+
+**Validation:** Reload workflow, run minimal smoke input, inspect structured result.
+
+**Outcome:** Contract fixed, smoke test passes, and the workflow can be reused safely.
+
+---
+
+#### Example 3: Investigating before implementing
+
+**Scenario:** A user-reported bug is ambiguous.
+
+**Initial objective:**
+
+```text
+Investigate `[bug]`, identify root cause, and propose the smallest fix. Do not implement until the cause is clear.
+```
+
+**Steering message:**
+
+```text
+Synthesize findings first: root cause, affected path, proposed fix, and validation plan.
+```
+
+**Validation:** Add or run a reproduction test before changing code.
+
+**Outcome:** Clear implementation plan produced, then delegated as a scoped fix.
+
+---
+
+### Anti-patterns
+
+| Anti-pattern | Better approach |
+| --- | --- |
+| `Fix this.` | `Fix [specific failure]; done means [test command] passes.` |
+| No validation step | Require tests, smoke checks, typecheck, or explicit manual verification. |
+| Broad refactors | Constrain the run to the files needed for the objective. |
+| Letting a wrong stage continue | Redirect or interrupt as soon as the agent follows the wrong signal. |
+| Accepting unverified summaries | Ask for changed files, commands run, results, and remaining risks. |
+| Mixing investigation and implementation too early | Ask for root cause and proposed fix before code changes. |
+| Ignoring blocked stages | Answer directly with one decision and any constraints. |
+| Continuing stale runs | Pause, kill, or rerun with updated context. |
+| Reading every log | Inspect status, then stages, then only relevant details. |
+| Publishing without gates | Require release validation and explicit stop conditions. |
+
+---
+
+### Quick reference
+
+Before starting a workflow, include:
+
+- [ ] Objective
+- [ ] Context
+- [ ] Scope
+- [ ] Non-goals
+- [ ] Done criteria
+- [ ] Validation command
+- [ ] Reporting requirements
+- [ ] Stop conditions
+
+Before accepting a workflow result, ask:
+
+- [ ] What changed?
+- [ ] Why was this the right fix?
+- [ ] What evidence supports it?
+- [ ] Which commands were run?
+- [ ] What still might be risky?
+- [ ] Is anything blocked or unresolved?
+
+The better the prompt defines the game, the better the agent can play it.