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

package/dist/builtin/workflows/src/extension/workflow-prompts.ts

@@ -8,7 +8,10 @@ export const WORKFLOW_TOOL_DESCRIPTION =
   "then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview.";
 
 export const DEFAULT_PROMPT_GUIDANCE: string[] = [
-  `**Workflows**: Use the \`workflow\` tool for existing named workflows and for repeatable, inspectable, resumable, or multi-stage processes; use direct \`task\`, \`tasks\`, or \`chain\` workflow calls for one-off tracked work when that is useful.
+  `**Workflows**: Treat workflows as the default execution path for any non-trivial task and for any request that has inherent structure plus an objective you can make verifiable. Use the \`workflow\` tool for existing named workflows and for repeatable, inspectable, resumable, multi-stage, or reviewer-gated processes; use direct \`task\`, \`tasks\`, or \`chain\` workflow calls for one-off tracked work when no named workflow fits.
+  - Workflow fit check: before implementing directly, ask whether the task is an implementation, build, debug/diagnosis, bug-fix, migration, new-feature, scoped multi-file edit, or docs/code change with validation; or whether it has multiple steps, dependencies, handoffs, uncertainty, validation/review needs, a long-running surface, or measurable done criteria. If yes, launch or design a workflow instead of doing parallel implementation yourself.
+  - Treat loop/structural wording as a strong workflow signal, especially requests like "do X until Y", "repeat until", "iterate until", "review/fix until passing", "run checks and fix until green", "keep going until done", or any prompt that names a stop condition, approval gate, or evidence requirement.
+  - Only skip workflows for tiny, deterministic, low-risk answers or direct edits that are faster and safer to complete inline without stage tracking, typically a clearly single-file/no-test/no-review change.
   - For unfamiliar named workflows, discover with \`action: "list"\`, inspect with \`action: "get"\` or \`action: "inputs"\`, and run with \`action: "run"\`, \`workflow\`, and validated \`inputs\`; do not invent workflow names or input keys.
   - When designing or editing workflows, read docs/workflows.md and reference its Workflow Starter Patterns: Classify-and-act, Fan-out-and-synthesize, Adversarial verification, Generate-and-filter, Tournament, and Loop until done. Choose or combine these patterns before inventing a custom stage graph, and reflect the selected pattern in the spec and Mermaid diagram when using the create-spec skill.
   - Once you run a workflow with the workflow tool, end your current turn and wait for the next user input or lifecycle notice.
@@ -19,7 +22,7 @@ export const DEFAULT_PROMPT_GUIDANCE: string[] = [
   - For transcripts, avoid reading whole session transcripts at once. Use \`stages\` or \`stage\` to get \`sessionFile\`/\`transcriptPath\`, quote the exact path without rewriting separators (preserve Windows backslashes), search it with \`rg\`/\`grep\`, and read small relevant ranges; use \`transcript\` with explicit \`tail\` or \`limit\` only for quick recent-context checks.
   - If a user asks to create or edit a workflow, use the create-spec skill when available and ask detailed clarifying questions until you understand its purpose, inputs, stages, handoffs, validation, success criteria, and selected starter pattern. Then read the workflow docs/examples and implement the workflow from the created spec directly as a TypeScript definition. After you implement the workflow, reload it to access it and run it with test inputs to validate it works as intended before presenting it to the user.
     - Tip: when designing workflows, implement it in a way that you pass information from stage to stage by writing it to a file or artifact (either deterministic or model-driven), pass the path with \`reads\`, and explicitly prompt the downstream agent with wording like \`Read the file at <path>...\`; do not inject large \`previous\` payloads or session history into the next prompt unless explicitly requested to.
-  - Prefer using the \`goal\` workflow for small fixes/quick fixes and the \`ralph\` workflow for tasks that are non-trivial (over 2K LoC estimated diff).
-    - Adjust the \`max_loops\` based on task complexity (estimated LoC and number of unique files that are touched).
+  - Prefer the \`goal\` workflow for small-to-medium non-trivial one-off fixes, debugging, docs/code changes, scoped multi-file edits, or test/fix loops when you can name the work surface, outcome, and validation; prefer the \`ralph\` workflow for larger/riskier work, migrations, new features, broad refactors, multi-package changes, or tasks estimated over ~2K LoC.
+    - Adjust \`goal.max_turns\` for Goal runs and \`ralph.max_loops\` for Ralph runs based on task complexity (estimated LoC, risk, validation effort, and number of unique files/areas touched).
     - Define an objective that includes tight scope, concrete and verifiable done criteria, and validation steps; then monitor progress as above instead of doing parallel implementation yourself.`,
 ];

package/dist/core/atomic-guide-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-guide-command.d.ts","sourceRoot":"","sources":["../../src/core/atomic-guide-command.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D,eAAO,MAAM,yBAAyB,WAAW,CAAC;AAClD,eAAO,MAAM,gCAAgC,qCACT,CAAC;AAuNrC,QAAA,MAAM,cAAc;mBAEV,UAAU;;oBAET,UAAU;0BACJ,oBAAoB;;;mBAI3B,WAAW;;oBAEV,WAAW;0BACL,iBAAiB;;;mBAIxB,SAAS;;oBAER,SAAS;0BACH,0BAA0B;;;mBAIjC,WAAW;;oBAEV,YAAY;0BACN,sBAAsB;;EASpC,CAAC;AAEJ,KAAK,kBAAkB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1D,KAAK,sBAAsB,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAEzD,MAAM,MAAM,qBAAqB,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAEhE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,sBAAsB,CAAC;AAE9D,eAAO,MAAM,yBAAyB,EAAE,SAAS,qBAAqB,EACtB,CAAC;AAiBjD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,GACb,MAAM,IAAI,qBAAqB,CAEjC;AAoCD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAOtE;AAED,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,MAAM,GACb,gBAAgB,EAAE,GAAG,IAAI,CAa3B;AAED,iBAAS,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CActD;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,eAAe,EACrB,GAAG,EAAE,MAAM,GACV,MAAM,CAGR;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,qBAAqB,GAC5B,eAAe,CAEjB","sourcesContent":["import * as path from \"node:path\";\nimport type { AutocompleteItem } from \"@earendil-works/pi-tui\";\nimport { getChangelogPath, parseChangelog } from \"../utils/changelog.ts\";\n\nexport const ATOMIC_GUIDE_COMMAND_NAME = \"atomic\";\nexport const ATOMIC_GUIDE_COMMAND_DESCRIPTION =\n  \"Atomic onboarding and help guide\";\n\nconst OVERVIEW = `# Atomic overview\n\nAtomic turns one-off prompts into developer workflows: on-call debugging, repo research that turns into implementation, testing and review loops, and larger multi-stage automation. Use \\`/workflow goal\\` for small-to-medium changes with a clear work surface, exact outcome, and named validation; keep \\`/workflow ralph\\` for larger migrations, broad refactors, and multi-package research-first implementation work. Start Atomic in a project with \\`atomic\\`, then talk to it normally. Use \\`@file\\` to attach files, \\`!command\\` to run shell output through the model, and \\`!!command\\` to run shell output without adding it to context.\n\n## Core session commands\n\n| Command | Use |\n|---|---|\n| \\`/login\\` | configure auth |\n| \\`/model\\` | switch model |\n| \\`/settings\\` | thinking level, theme, message delivery, transport |\n| \\`/new\\`, \\`/resume\\` | start or resume sessions |\n| \\`/tree\\`, \\`/fork\\`, \\`/clone\\` | branch or navigate session history |\n| \\`/compact\\` | delete safe older context verbatim |\n| \\`/hotkeys\\`, \\`/changelog\\` | local help and release notes |\n\n## Examples of using Atomic\n\n| Goal | How to use |\n|---|---|\n| On-call / broken behavior | Run \\`/run debugger \"Reproduce the failure, patch the root cause, and validate it\"\\` for a focused fix loop, or ask Atomic in chat to build a reusable workflow that does the same |\n| Research → spec → implementation | Chain \\`/skill:research-codebase\\` → \\`/skill:create-spec\\` → \\`/workflow goal objective=\"...\"\\` for bounded scoped work with explicit validation; add \\`create_pr=true\\` for Goal's final PR handoff after approval, or use \\`/workflow ralph ...\\` when the work needs research-first broad refactoring |\n| Testing / regression hardening | Run \\`/skill:tdd\\` for test-first work, then \\`/parallel-review current diff\\`, then land the change |\n| Large repo discovery | Run \\`/parallel codebase-locator \"map the area\" -> codebase-analyzer \"trace the current flow\" -> codebase-pattern-finder \"find patterns\" --bg\\`, or \\`/workflow deep-research-codebase\\` for whole-repo synthesis |\n| UI / product polish | Run \\`/skill:impeccable\\` for interface critique and refinement, or \\`/workflow open-claude-design\\` for generation + refinement loops |\n\n## Built-in workflows\n\n| Workflow | When to use | How to run |\n|---|---|---|\n| \\`deep-research-codebase\\` | broad repo or cross-cutting research before you decide what to change (for one area, use \\`/skill:research-codebase\\`; this indexes the whole repo) | \\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\` |\n| \\`goal\\` | small-to-medium scoped changes when you can name the work surface, outcome, and validation; keeps receipts in a ledger, stops as \\`complete\\`, \\`blocked\\`, or \\`needs_human\\`, and can run a final PR handoff with \\`create_pr=true\\` after approval | \\`/workflow goal objective=\"Implement specs/<date>-<topic>.md, run focused tests, and validate the changed behavior\"\\` |\n| \\`ralph\\` | larger migrations, broad refactors, and multi-package changes where you want Atomic to research first, delegate, review, and iterate; add \\`create_pr=true\\` only when you want the final pull-request stage and report | \\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\" create_pr=true\\` |\n| \\`open-claude-design\\` | UI and design-system work that benefits from generation and refinement loops | \\`/workflow open-claude-design prompt=\"Refresh the settings page hierarchy\"\\` |\n\nUse \\`/workflow list\\` to see what is available and \\`/workflow inputs <name>\\` to inspect inputs in your environment.\n\n## Top skills\n\n| Skill | When to use | How to run |\n|---|---|---|\n| \\`research-codebase\\` | write a grounded research artifact for one subsystem or question | \\`/skill:research-codebase how the rate limiter works in src/middleware/\\` |\n| \\`create-spec\\` | turn research into an implementation-ready plan | \\`/skill:create-spec from research/docs/<date>-<topic>.md\\` |\n| \\`tdd\\` | do test-first feature or bug work | \\`/skill:tdd\\` |\n| \\`prompt-engineer\\` | tighten a vague prompt before a long run | \\`/skill:prompt-engineer Draft a sharper implementation prompt for ...\\` |\n| \\`subagent\\` | learn delegation patterns and exact \\`/run\\`, \\`/parallel\\`, and \\`/chain\\` usage | \\`/skill:subagent\\` |\n| \\`impeccable\\` | critique or refine frontend and product UI | \\`/skill:impeccable\\` |\n\n## Subagents\n\nSubagents are focused child Atomic sessions you can point at one job inside the repo.\n\n| Built-in subagent | Use |\n|---|---|\n| \\`codebase-locator\\` | find relevant files, tests, entrypoints, and configs |\n| \\`codebase-analyzer\\` | explain current behavior with file:line refs |\n| \\`codebase-pattern-finder\\` | find existing code to model after |\n| \\`debugger\\` | reproduce, diagnose, and fix broken behavior |\n\nHow the direct commands map to repo work:\n- \\`/run\\` = one specialist on one job, for example \\`/run codebase-locator \"Map the webhook retry flow\"\\`\n- \\`/parallel\\` = several independent specialists at once, for example \\`/parallel codebase-locator \"map retry files\" -> codebase-pattern-finder \"find existing retry/backoff patterns\" -> codebase-online-researcher \"research current retry guidance\" --bg\\`\n- \\`/chain\\` = ordered handoffs, for example \\`/chain codebase-locator \"find the auth files\" -> codebase-analyzer \"trace the auth flow\" -> debugger \"patch the failing auth edge case\"\\`\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic example\\` — see the pieces used on a code task\n\\`/atomic workflows\\` — learn when to use workflows`;\n\nconst EXAMPLE = `# Practical example\n\nThis is an example of a spec-driven development process using Atomic workflows. Use it when you are new to a repo or the task has non-trivial scope. Type the examples below into the Atomic TUI chat after starting \\`atomic\\` in your project.\n\n## 1. Research what exists\n\nUse \\`/skill:research-codebase\\` for a scoped area, subsystem, or directory:\n\n\\`/skill:research-codebase how the rate limiter works in src/middleware/\\`\n\nUse \\`deep-research-codebase\\` when the answer spans the whole repo or a cross-cutting implementation path:\n\n\\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\`\n\nIf the research prompt is vague, tighten it first with \\`/skill:prompt-engineer\\`:\n\n\\`/skill:prompt-engineer Draft a sharper repo-research prompt for understanding payment retries end to end, including retries, queues, and failure handling.\\`\n\n## 2. Create a spec when requirements are fuzzy\n\nSkip this if the implementation request is already precise.\n\n\\`/skill:create-spec from research/docs/<date>-<topic>.md\\`\n\n## 3. Implement with review built in\n\nFor ordinary work, ask Atomic directly and require validation:\n\n\\`Implement the approved spec in specs/<date>-<topic>.md. Run focused tests and summarize validation.\\`\n\nFor small-to-medium scoped changes where you can identify the work surface, exact outcome, and validation, use \\`goal\\`:\n\n\\`/workflow goal objective=\"Implement specs/<date>-<topic>.md, run focused tests, and finish when the documented behavior is validated\"\\`\n\nFor larger migrations, broad refactors, or multi-package changes that need research-first implementation, use \\`ralph\\`:\n\n\\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\"\\`\n\nAdd \\`create_pr=true\\` only when you want the final pull-request stage and report after the review gate approves.\n\n## 4. Decide and land\n\nIf you used \\`goal\\`, the workflow already persisted receipts in a goal ledger and reviewer-gated completion. Use its final status — \\`complete\\`, \\`blocked\\`, or \\`needs_human\\` — plus the remaining-work report to decide whether to ship, unblock, or clarify. If you enabled \\`create_pr=true\\`, use its final pull-request report to decide whether to ship or iterate again.\n\nIf you used \\`ralph\\`, the workflow transformed the prompt into a research question, researched the codebase, delegated implementation through sub-agents, reviewed, and iterated. If you enabled \\`create_pr=true\\`, use its final pull-request report to decide whether to ship or iterate again.\n\nIf you implemented directly instead of using a workflow, you can still run:\n\n\\`/parallel-review current diff\\`\n\nAtomic will synthesize reviewer feedback and ask before applying fixes.\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic workflows\\` — learn when to use workflows\n\\`/atomic overview\\` — quick refresh`;\n\nconst WORKFLOWS = `# Workflows primer\n\nA workflow is a TypeScript-defined pipeline exported from \\`workflow({...})\\`. It can run tasks, chains, parallel fan-out, human-in-the-loop prompts, background status, and model fallback chains.\n\nYou do not have to write TypeScript to add one. Describe the workflow you want in plain chat — goal, inputs, stages, which steps are parallel or sequential, handoff/output shape, and any model or thinking-level preferences — and Atomic will use the workflow docs to scaffold a reusable definition under \\`.atomic/workflows/\\` and reload it for you. Hand-edit the TypeScript afterward when you want precise control.\n\n## Built-in workflows\n\n| Workflow | When to use | How to run |\n|---|---|---|\n| \\`deep-research-codebase\\` | broad repo or cross-cutting research before you decide what to change (for one area, use \\`/skill:research-codebase\\`; this indexes the whole repo) | \\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\` |\n| \\`goal\\` | small-to-medium scoped changes with a clear outcome and named validation; add \\`create_pr=true\\` only for final PR handoff after approval | \\`/workflow goal objective=\"Update the CLI docs, include one usage example, and verify the docs build passes\"\\` |\n| \\`ralph\\` | larger migrations, broad refactors, and multi-package research-first implementation work | \\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\" create_pr=true\\` |\n| \\`open-claude-design\\` | frontend and product design work | \\`/workflow open-claude-design prompt=\"Refresh the settings page hierarchy\"\\` |\n\nUse \\`/workflow inputs <name>\\` to inspect the exact inputs in your environment.\n\nUse \\`/skill:research-codebase ...\\` when you want research on one subsystem, directory, or focused question. Use \\`/workflow deep-research-codebase ...\\` when the answer needs end-to-end tracing across many parts of the repo.\n\nIf you are drafting research, reviewer, or synthesis prompts for a workflow, use \\`/skill:prompt-engineer\\` first. It is a good fit when a stage prompt feels vague, overloaded, or underspecified.\n\n## What good workflow authoring looks like\n\nA good workflow request is explicit about stage purpose, model choice, handoff, and the decision each step must return.\n\nExample: ask Atomic in chat with something like this:\n\n~~~text\nCreate a reusable workflow called review-changes.\n\nIt should accept one required text input called target for a diff, PR summary, or review target.\n\nRun two independent review stages in parallel with fresh context:\n- one reviewer focused on correctness, regressions, and missing tests using openai-codex/gpt-5.5 at xhigh thinking\n- one reviewer focused on edge cases, maintainability, and hidden risks using anthropic/claude-opus-4-8 at xhigh thinking\n\nThen add an aggregate stage that consolidates both reviews, deduplicates overlap, keeps only evidence-backed issues, and separates blockers from optional suggestions using openai/gpt-5.5 at high thinking.\n\nFinally add an adjudicate stage using anthropic/claude-sonnet-4 at high thinking that decides what to fix now, what to defer, and what to reject. Return a short action list with rationale.\n\nThe workflow should return structured output with consolidated_review and decision fields.\n~~~\n\nWhy this is good:\n- it names the workflow and required input\n- it specifies which stages are parallel vs sequential\n- each stage has one job\n- it defines the handoff and final outputs\n- it calls out model choice and thinking level where that matters\n\n## Run and inspect\n\n\\`/workflow list\\`\n\n\\`/workflow inputs goal\\`\n\n\\`/workflow goal objective=\"Fix the settings form validation bug, add the focused test, and finish when invalid emails show the inline error without submitting\"\\`\n\n\\`/workflow inputs ralph\\`\n\n\\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\" create_pr=true\\`\n\n\\`/workflow status\\`\n\n\\`/workflow connect <run-id>\\`\n\n\\`/workflow interrupt <run-id>\\`\n\n\\`/workflow resume <run-id>\\`\n\nWorkflows run as background tasks. Use F2 or \\`/workflow connect <run-id>\\` for the graph viewer. Human-in-the-loop prompts appear there, not as chat modals, and awaiting-input states do not wake the main chat agent. Completion and failure notices are steered back into the main chat; answers submitted in the workflow UI interrupt stale main-chat questions so the model does not ask again.\n\n## Author your own\n\nDescribe your workflow in plain chat — say what you want the workflow to accomplish, what inputs it should accept, what stages should run, and what final output or decision it should return. Atomic will use the workflow docs to scaffold a reusable definition under \\`.atomic/workflows/\\`, ask clarifying questions when stage purpose, models, or handoffs are ambiguous, and run \\`/workflow reload\\` so you can launch it immediately.\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic example\\` — see workflows in a normal task flow\n\\`/atomic overview\\` — quick refresh`;\n\nconst GUIDE_SECTIONS = [\n  {\n    name: \"overview\",\n    aliases: [],\n    label: \"overview\",\n    description: \"30-second overview\",\n    render: () => OVERVIEW,\n  },\n  {\n    name: \"workflows\",\n    aliases: [\"workflow\"],\n    label: \"workflows\",\n    description: \"Workflow primer\",\n    render: () => WORKFLOWS,\n  },\n  {\n    name: \"example\",\n    aliases: [\"examples\"],\n    label: \"example\",\n    description: \"Practical first workflow\",\n    render: () => EXAMPLE,\n  },\n  {\n    name: \"whats-new\",\n    aliases: [\"what's new\", \"whats new\", \"news\", \"updates\", \"changelog\"],\n    label: \"what's new\",\n    description: \"Recent release notes\",\n    render: readLatestStableChangelog,\n  },\n] as const satisfies readonly {\n  readonly name: string;\n  readonly aliases: readonly string[];\n  readonly label: string;\n  readonly description: string;\n  readonly render: (cwd: string) => string;\n}[];\n\ntype AtomicGuideSection = (typeof GUIDE_SECTIONS)[number];\ntype AtomicGuideSectionName = AtomicGuideSection[\"name\"];\n\nexport type AtomicGuideHelpChoice = AtomicGuideSection[\"label\"];\n\nexport type AtomicGuideMode = \"help\" | AtomicGuideSectionName;\n\nexport const ATOMIC_GUIDE_HELP_CHOICES: readonly AtomicGuideHelpChoice[] =\n  GUIDE_SECTIONS.map((section) => section.label);\n\nconst GUIDE_SECTIONS_BY_NAME = new Map<\n  AtomicGuideSectionName,\n  AtomicGuideSection\n>(GUIDE_SECTIONS.map((section) => [section.name, section]));\nconst GUIDE_SECTIONS_BY_LABEL = new Map<string, AtomicGuideSection>(\n  GUIDE_SECTIONS.map((section) => [section.label, section]),\n);\nconst GUIDE_SECTIONS_BY_INPUT = new Map<string, AtomicGuideSection>(\n  GUIDE_SECTIONS.flatMap((section) =>\n    [section.name, section.label, ...section.aliases].map(\n      (input) => [input, section] as const,\n    ),\n  ),\n);\n\nexport function isAtomicGuideHelpChoice(\n  choice: string,\n): choice is AtomicGuideHelpChoice {\n  return GUIDE_SECTIONS_BY_LABEL.has(choice);\n}\n\nconst ATOMIC_GUIDE_TRAILING_PUNCTUATION = \"?!.,;:\";\n\nfunction stripTrailingAtomicGuidePunctuation(value: string): string {\n  let end = value.length;\n  while (\n    end > 0 &&\n    ATOMIC_GUIDE_TRAILING_PUNCTUATION.includes(value.charAt(end - 1))\n  ) {\n    end--;\n  }\n  return value.slice(0, end);\n}\n\nfunction getGuideSectionForChoice(\n  choice: string,\n): AtomicGuideSection | undefined {\n  return GUIDE_SECTIONS_BY_LABEL.get(choice);\n}\n\nfunction getGuideSectionForMode(\n  mode: AtomicGuideSectionName,\n): AtomicGuideSection {\n  const section = GUIDE_SECTIONS_BY_NAME.get(mode);\n  if (!section) throw new Error(`Unknown Atomic guide section: ${mode}`);\n  return section;\n}\n\nfunction getAtomicGuideHelpMenu(): string {\n  const sectionHelp = GUIDE_SECTIONS.map(\n    (section) => `- \\`${section.label}\\` — run \\`/atomic ${section.label}\\``,\n  ).join(\"\\n\");\n  return `# Atomic\\n\\nSelect where to start:\\n\\n${sectionHelp}`;\n}\n\nexport function normalizeAtomicGuideMode(args: string): AtomicGuideMode {\n  const normalized = stripTrailingAtomicGuidePunctuation(\n    args.trim().toLowerCase(),\n  );\n  if (!normalized) return \"help\";\n\n  return GUIDE_SECTIONS_BY_INPUT.get(normalized)?.name ?? \"help\";\n}\n\nexport function getAtomicGuideArgumentCompletions(\n  prefix: string,\n): AutocompleteItem[] | null {\n  const query = prefix.trim().toLowerCase();\n  const items = GUIDE_SECTIONS.map((section) => ({\n    value: section.label,\n    label: section.label,\n    description: section.description,\n  }));\n  const filtered = query\n    ? items.filter(\n        (item) => item.value.startsWith(query) || item.label.startsWith(query),\n      )\n    : items;\n  return filtered.length > 0 ? filtered : null;\n}\n\nfunction readLatestStableChangelog(cwd: string): string {\n  const changelogPath = getChangelogPath();\n  const stableSections = parseChangelog(changelogPath)\n    .filter((entry) => entry.prerelease === null)\n    .slice(0, 3)\n    .map((entry) => entry.content.trim())\n    .filter(Boolean);\n\n  if (stableSections.length === 0) {\n    return `# What's new\\n\\nNo stable release sections were found. Try \\`/changelog\\` for the interactive changelog viewer.\\n\\n─────────────────────────────────────────────────────────────────\\n\\nWhere to next:\\n\\n\\`/atomic example\\` — see a practical first workflow\\n\\`/atomic overview\\` — quick refresh`;\n  }\n\n  const relativePath = path.relative(cwd, changelogPath) || changelogPath;\n  return `# What's new\\n\\n${stableSections.join(\"\\n\\n\")}\\n\\nSource: \\`${relativePath}\\`\\n\\n─────────────────────────────────────────────────────────────────\\n\\nWhere to next:\\n\\n\\`/atomic example\\` — see a practical first workflow\\n\\`/atomic overview\\` — quick refresh`;\n}\n\nexport function getAtomicGuideMessage(\n  mode: AtomicGuideMode,\n  cwd: string,\n): string {\n  if (mode === \"help\") return getAtomicGuideHelpMenu();\n  return getGuideSectionForMode(mode).render(cwd);\n}\n\nexport function atomicGuideModeForChoice(\n  choice: AtomicGuideHelpChoice,\n): AtomicGuideMode {\n  return getGuideSectionForChoice(choice)?.name ?? \"help\";\n}\n"]}
+{"version":3,"file":"atomic-guide-command.d.ts","sourceRoot":"","sources":["../../src/core/atomic-guide-command.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D,eAAO,MAAM,yBAAyB,WAAW,CAAC;AAClD,eAAO,MAAM,gCAAgC,qCACT,CAAC;AA2NrC,QAAA,MAAM,cAAc;mBAEV,UAAU;;oBAET,UAAU;0BACJ,oBAAoB;;;mBAI3B,WAAW;;oBAEV,WAAW;0BACL,iBAAiB;;;mBAIxB,SAAS;;oBAER,SAAS;0BACH,0BAA0B;;;mBAIjC,WAAW;;oBAEV,YAAY;0BACN,sBAAsB;;EASpC,CAAC;AAEJ,KAAK,kBAAkB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1D,KAAK,sBAAsB,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAEzD,MAAM,MAAM,qBAAqB,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAEhE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,sBAAsB,CAAC;AAE9D,eAAO,MAAM,yBAAyB,EAAE,SAAS,qBAAqB,EACtB,CAAC;AAiBjD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,GACb,MAAM,IAAI,qBAAqB,CAEjC;AAoCD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAOtE;AAED,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,MAAM,GACb,gBAAgB,EAAE,GAAG,IAAI,CAa3B;AAED,iBAAS,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CActD;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,eAAe,EACrB,GAAG,EAAE,MAAM,GACV,MAAM,CAGR;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,qBAAqB,GAC5B,eAAe,CAEjB","sourcesContent":["import * as path from \"node:path\";\nimport type { AutocompleteItem } from \"@earendil-works/pi-tui\";\nimport { getChangelogPath, parseChangelog } from \"../utils/changelog.ts\";\n\nexport const ATOMIC_GUIDE_COMMAND_NAME = \"atomic\";\nexport const ATOMIC_GUIDE_COMMAND_DESCRIPTION =\n  \"Atomic onboarding and help guide\";\n\nconst OVERVIEW = `# Atomic overview\n\nAtomic turns one-off prompts into developer workflows: on-call debugging, repo research that turns into implementation, testing and review loops, and larger multi-stage automation. Workflows are the default for non-trivial work and requests with inherent structure plus a verifiable objective, including implementation, build, debugging, bug-fix, migration, new-feature, scoped multi-file, or validation-heavy docs/code work. Loop-shaped prompts like \\`do X until Y\\`, \\`repeat until\\`, \\`iterate until\\`, \\`review/fix until passing\\`, or \\`run checks and fix until green\\` should map to a workflow unless the task is a tiny deterministic direct edit or simple answer. Use \\`/workflow goal\\` for small-to-medium changes with a clear work surface, exact outcome, and named validation; keep \\`/workflow ralph\\` for larger migrations, broad refactors, and multi-package research-first implementation work. Start Atomic in a project with \\`atomic\\`, then talk to it normally. Use \\`@file\\` to attach files, \\`!command\\` to run shell output through the model, and \\`!!command\\` to run shell output without adding it to context.\n\n## Core session commands\n\n| Command | Use |\n|---|---|\n| \\`/login\\` | configure auth |\n| \\`/model\\` | switch model |\n| \\`/settings\\` | thinking level, theme, message delivery, transport |\n| \\`/new\\`, \\`/resume\\` | start or resume sessions |\n| \\`/tree\\`, \\`/fork\\`, \\`/clone\\` | branch or navigate session history |\n| \\`/compact\\` | delete safe older context verbatim |\n| \\`/hotkeys\\`, \\`/changelog\\` | local help and release notes |\n\n## Examples of using Atomic\n\n| Goal | How to use |\n|---|---|\n| On-call / broken behavior | Use \\`/workflow goal objective=\"Reproduce the failure, patch the root cause, and validate it\"\\` for a focused fix loop; reserve direct debugger/subagent calls for narrow diagnosis or truly tiny deterministic fixes |\n| Research → spec → implementation | Chain \\`/skill:research-codebase\\` → \\`/skill:create-spec\\` → \\`/workflow goal objective=\"...\"\\` for bounded scoped work with explicit validation; add \\`create_pr=true\\` for Goal's final PR handoff after approval, or use \\`/workflow ralph ...\\` when the work needs research-first broad refactoring |\n| Testing / regression hardening | Use \\`/workflow goal objective=\"Add the regression coverage, fix failures, and finish when focused tests pass\"\\`; loop wording like review/fix/test until passing is workflow-shaped |\n| Large repo discovery | Run \\`/parallel codebase-locator \"map the area\" -> codebase-analyzer \"trace the current flow\" -> codebase-pattern-finder \"find patterns\" --bg\\`, or \\`/workflow deep-research-codebase\\` for whole-repo synthesis |\n| UI / product polish | Run \\`/skill:impeccable\\` for interface critique and refinement, or \\`/workflow open-claude-design\\` for generation + refinement loops |\n\n## Built-in workflows\n\n| Workflow | When to use | How to run |\n|---|---|---|\n| \\`deep-research-codebase\\` | broad repo or cross-cutting research before you decide what to change (for one area, use \\`/skill:research-codebase\\`; this indexes the whole repo) | \\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\` |\n| \\`goal\\` | small-to-medium scoped changes when you can name the work surface, outcome, and validation, including bug fixes, debugging, scoped multi-file edits, and test/fix loops; keeps receipts in a ledger, stops as \\`complete\\`, \\`blocked\\`, or \\`needs_human\\`, and can run a final PR handoff with \\`create_pr=true\\` after approval | \\`/workflow goal objective=\"Implement specs/<date>-<topic>.md, run focused tests, and validate the changed behavior\"\\` |\n| \\`ralph\\` | larger migrations, new features, broad refactors, and multi-package changes where you want Atomic to research first, delegate, review, and iterate; add \\`create_pr=true\\` only when you want the final pull-request stage and report | \\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\" create_pr=true\\` |\n| \\`open-claude-design\\` | UI and design-system work that benefits from generation and refinement loops | \\`/workflow open-claude-design prompt=\"Refresh the settings page hierarchy\"\\` |\n\nUse \\`/workflow list\\` to see what is available and \\`/workflow inputs <name>\\` to inspect inputs in your environment.\n\n## Top skills\n\n| Skill | When to use | How to run |\n|---|---|---|\n| \\`research-codebase\\` | write a grounded research artifact for one subsystem or question | \\`/skill:research-codebase how the rate limiter works in src/middleware/\\` |\n| \\`create-spec\\` | turn research into an implementation-ready plan | \\`/skill:create-spec from research/docs/<date>-<topic>.md\\` |\n| \\`tdd\\` | do test-first feature or bug work | \\`/skill:tdd\\` |\n| \\`prompt-engineer\\` | tighten a vague prompt before a long run | \\`/skill:prompt-engineer Draft a sharper implementation prompt for ...\\` |\n| \\`subagent\\` | learn delegation patterns and exact \\`/run\\`, \\`/parallel\\`, and \\`/chain\\` usage | \\`/skill:subagent\\` |\n| \\`impeccable\\` | critique or refine frontend and product UI | \\`/skill:impeccable\\` |\n\n## Subagents\n\nSubagents are focused child Atomic sessions you can point at one job inside the repo.\n\n| Built-in subagent | Use |\n|---|---|\n| \\`codebase-locator\\` | find relevant files, tests, entrypoints, and configs |\n| \\`codebase-analyzer\\` | explain current behavior with file:line refs |\n| \\`codebase-pattern-finder\\` | find existing code to model after |\n| \\`debugger\\` | reproduce, diagnose, and fix broken behavior |\n\nHow the direct commands map to repo work:\n- \\`/run\\` = one specialist on one job, for example \\`/run codebase-locator \"Map the webhook retry flow\"\\`\n- \\`/parallel\\` = several independent specialists at once, for example \\`/parallel codebase-locator \"map retry files\" -> codebase-pattern-finder \"find existing retry/backoff patterns\" -> codebase-online-researcher \"research current retry guidance\" --bg\\`\n- \\`/chain\\` = ordered handoffs, for example \\`/chain codebase-locator \"find the auth files\" -> codebase-analyzer \"trace the auth flow\" -> debugger \"patch the failing auth edge case\"\\`\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic example\\` — see the pieces used on a code task\n\\`/atomic workflows\\` — learn when to use workflows`;\n\nconst EXAMPLE = `# Practical example\n\nThis is an example of a spec-driven development process using Atomic workflows. Use it when you are new to a repo or the task has non-trivial scope. Type the examples below into the Atomic TUI chat after starting \\`atomic\\` in your project.\n\n## 1. Research what exists\n\nUse \\`/skill:research-codebase\\` for a scoped area, subsystem, or directory:\n\n\\`/skill:research-codebase how the rate limiter works in src/middleware/\\`\n\nUse \\`deep-research-codebase\\` when the answer spans the whole repo or a cross-cutting implementation path:\n\n\\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\`\n\nIf the research prompt is vague, tighten it first with \\`/skill:prompt-engineer\\`:\n\n\\`/skill:prompt-engineer Draft a sharper repo-research prompt for understanding payment retries end to end, including retries, queues, and failure handling.\\`\n\n## 2. Create a spec when requirements are fuzzy\n\nSkip this if the implementation request is already precise.\n\n\\`/skill:create-spec from research/docs/<date>-<topic>.md\\`\n\n## 3. Implement with review built in\n\nDefault to a workflow for non-trivial implementation, build, debugging, bug-fix, migration, new-feature, scoped multi-file, or docs/code-change work when validation matters. Direct chat is best reserved for tiny deterministic single-file/no-test/no-review edits or simple answers.\n\nFor small-to-medium scoped changes where you can identify the work surface, exact outcome, and validation, use \\`goal\\`:\n\n\\`/workflow goal objective=\"Implement specs/<date>-<topic>.md, run focused tests, and finish when the documented behavior is validated\"\\`\n\nIf the request is loop-shaped — for example \\`do X until Y\\`, \\`repeat until\\`, \\`iterate until\\`, \\`review/fix until passing\\`, or \\`run checks and fix until green\\` — make the stop condition explicit in the Goal objective:\n\n\\`/workflow goal objective=\"Fix the flaky checkout test, adjust the smallest necessary code, and finish when the focused test passes three times\"\\`\n\nFor larger migrations, broad refactors, new features, or multi-package changes that need research-first implementation, use \\`ralph\\`:\n\n\\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\"\\`\n\nAdd \\`create_pr=true\\` only when you want the final pull-request stage and report after the review gate approves.\n\n## 4. Decide and land\n\nIf you used \\`goal\\`, the workflow already persisted receipts in a goal ledger and reviewer-gated completion. Use its final status — \\`complete\\`, \\`blocked\\`, or \\`needs_human\\` — plus the remaining-work report to decide whether to ship, unblock, or clarify. If you enabled \\`create_pr=true\\`, use its final pull-request report to decide whether to ship or iterate again.\n\nIf you used \\`ralph\\`, the workflow transformed the prompt into a research question, researched the codebase, delegated implementation through sub-agents, reviewed, and iterated. If you enabled \\`create_pr=true\\`, use its final pull-request report to decide whether to ship or iterate again.\n\nIf you implemented directly instead of using a workflow, you can still run:\n\n\\`/parallel-review current diff\\`\n\nAtomic will synthesize reviewer feedback and ask before applying fixes.\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic workflows\\` — learn when to use workflows\n\\`/atomic overview\\` — quick refresh`;\n\nconst WORKFLOWS = `# Workflows primer\n\nA workflow is a TypeScript-defined pipeline exported from \\`workflow({...})\\`. It can run tasks, chains, parallel fan-out, human-in-the-loop prompts, background status, and model fallback chains.\n\nUse workflows by default for non-trivial work with a verifiable objective: implementation, build, debugging, bug-fix, migration, new-feature, scoped multi-file, validation-heavy docs/code changes, or any prompt with a stop condition such as \\`do X until Y\\`, \\`repeat until\\`, \\`iterate until\\`, or \\`review/fix until passing\\`. Skip workflows only for tiny deterministic direct edits or simple answers where tracking would add more overhead than value.\n\nYou do not have to write TypeScript to add one. Describe the workflow you want in plain chat — goal, inputs, stages, which steps are parallel or sequential, handoff/output shape, and any model or thinking-level preferences — and Atomic will use the workflow docs to scaffold a reusable definition under \\`.atomic/workflows/\\` and reload it for you. Hand-edit the TypeScript afterward when you want precise control.\n\n## Built-in workflows\n\n| Workflow | When to use | How to run |\n|---|---|---|\n| \\`deep-research-codebase\\` | broad repo or cross-cutting research before you decide what to change (for one area, use \\`/skill:research-codebase\\`; this indexes the whole repo) | \\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\` |\n| \\`goal\\` | small-to-medium scoped changes with a clear outcome and named validation, including bug fixes, debugging, scoped multi-file edits, and test/fix loops; add \\`create_pr=true\\` only for final PR handoff after approval | \\`/workflow goal objective=\"Update the CLI docs, include one usage example, and verify the docs build passes\"\\` |\n| \\`ralph\\` | larger migrations, new features, broad refactors, and multi-package research-first implementation work | \\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\" create_pr=true\\` |\n| \\`open-claude-design\\` | frontend and product design work | \\`/workflow open-claude-design prompt=\"Refresh the settings page hierarchy\"\\` |\n\nUse \\`/workflow inputs <name>\\` to inspect the exact inputs in your environment.\n\nUse \\`/skill:research-codebase ...\\` when you want research on one subsystem, directory, or focused question. Use \\`/workflow deep-research-codebase ...\\` when the answer needs end-to-end tracing across many parts of the repo.\n\nIf you are drafting research, reviewer, or synthesis prompts for a workflow, use \\`/skill:prompt-engineer\\` first. It is a good fit when a stage prompt feels vague, overloaded, or underspecified.\n\n## What good workflow authoring looks like\n\nA good workflow request is explicit about stage purpose, model choice, handoff, and the decision each step must return.\n\nExample: ask Atomic in chat with something like this:\n\n~~~text\nCreate a reusable workflow called review-changes.\n\nIt should accept one required text input called target for a diff, PR summary, or review target.\n\nRun two independent review stages in parallel with fresh context:\n- one reviewer focused on correctness, regressions, and missing tests using openai-codex/gpt-5.5 at xhigh thinking\n- one reviewer focused on edge cases, maintainability, and hidden risks using anthropic/claude-opus-4-8 at xhigh thinking\n\nThen add an aggregate stage that consolidates both reviews, deduplicates overlap, keeps only evidence-backed issues, and separates blockers from optional suggestions using openai/gpt-5.5 at high thinking.\n\nFinally add an adjudicate stage using anthropic/claude-sonnet-4 at high thinking that decides what to fix now, what to defer, and what to reject. Return a short action list with rationale.\n\nThe workflow should return structured output with consolidated_review and decision fields.\n~~~\n\nWhy this is good:\n- it names the workflow and required input\n- it specifies which stages are parallel vs sequential\n- each stage has one job\n- it defines the handoff and final outputs\n- it calls out model choice and thinking level where that matters\n\n## Run and inspect\n\n\\`/workflow list\\`\n\n\\`/workflow inputs goal\\`\n\n\\`/workflow goal objective=\"Fix the settings form validation bug, add the focused test, and finish when invalid emails show the inline error without submitting\"\\`\n\n\\`/workflow inputs ralph\\`\n\n\\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\" create_pr=true\\`\n\n\\`/workflow status\\`\n\n\\`/workflow connect <run-id>\\`\n\n\\`/workflow interrupt <run-id>\\`\n\n\\`/workflow resume <run-id>\\`\n\nWorkflows run as background tasks. Use F2 or \\`/workflow connect <run-id>\\` for the graph viewer. Human-in-the-loop prompts appear there, not as chat modals, and awaiting-input states do not wake the main chat agent. Completion and failure notices are steered back into the main chat; answers submitted in the workflow UI interrupt stale main-chat questions so the model does not ask again.\n\n## Author your own\n\nDescribe your workflow in plain chat — say what you want the workflow to accomplish, what inputs it should accept, what stages should run, and what final output or decision it should return. Atomic will use the workflow docs to scaffold a reusable definition under \\`.atomic/workflows/\\`, ask clarifying questions when stage purpose, models, or handoffs are ambiguous, and run \\`/workflow reload\\` so you can launch it immediately.\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic example\\` — see workflows in a normal task flow\n\\`/atomic overview\\` — quick refresh`;\n\nconst GUIDE_SECTIONS = [\n  {\n    name: \"overview\",\n    aliases: [],\n    label: \"overview\",\n    description: \"30-second overview\",\n    render: () => OVERVIEW,\n  },\n  {\n    name: \"workflows\",\n    aliases: [\"workflow\"],\n    label: \"workflows\",\n    description: \"Workflow primer\",\n    render: () => WORKFLOWS,\n  },\n  {\n    name: \"example\",\n    aliases: [\"examples\"],\n    label: \"example\",\n    description: \"Practical first workflow\",\n    render: () => EXAMPLE,\n  },\n  {\n    name: \"whats-new\",\n    aliases: [\"what's new\", \"whats new\", \"news\", \"updates\", \"changelog\"],\n    label: \"what's new\",\n    description: \"Recent release notes\",\n    render: readLatestStableChangelog,\n  },\n] as const satisfies readonly {\n  readonly name: string;\n  readonly aliases: readonly string[];\n  readonly label: string;\n  readonly description: string;\n  readonly render: (cwd: string) => string;\n}[];\n\ntype AtomicGuideSection = (typeof GUIDE_SECTIONS)[number];\ntype AtomicGuideSectionName = AtomicGuideSection[\"name\"];\n\nexport type AtomicGuideHelpChoice = AtomicGuideSection[\"label\"];\n\nexport type AtomicGuideMode = \"help\" | AtomicGuideSectionName;\n\nexport const ATOMIC_GUIDE_HELP_CHOICES: readonly AtomicGuideHelpChoice[] =\n  GUIDE_SECTIONS.map((section) => section.label);\n\nconst GUIDE_SECTIONS_BY_NAME = new Map<\n  AtomicGuideSectionName,\n  AtomicGuideSection\n>(GUIDE_SECTIONS.map((section) => [section.name, section]));\nconst GUIDE_SECTIONS_BY_LABEL = new Map<string, AtomicGuideSection>(\n  GUIDE_SECTIONS.map((section) => [section.label, section]),\n);\nconst GUIDE_SECTIONS_BY_INPUT = new Map<string, AtomicGuideSection>(\n  GUIDE_SECTIONS.flatMap((section) =>\n    [section.name, section.label, ...section.aliases].map(\n      (input) => [input, section] as const,\n    ),\n  ),\n);\n\nexport function isAtomicGuideHelpChoice(\n  choice: string,\n): choice is AtomicGuideHelpChoice {\n  return GUIDE_SECTIONS_BY_LABEL.has(choice);\n}\n\nconst ATOMIC_GUIDE_TRAILING_PUNCTUATION = \"?!.,;:\";\n\nfunction stripTrailingAtomicGuidePunctuation(value: string): string {\n  let end = value.length;\n  while (\n    end > 0 &&\n    ATOMIC_GUIDE_TRAILING_PUNCTUATION.includes(value.charAt(end - 1))\n  ) {\n    end--;\n  }\n  return value.slice(0, end);\n}\n\nfunction getGuideSectionForChoice(\n  choice: string,\n): AtomicGuideSection | undefined {\n  return GUIDE_SECTIONS_BY_LABEL.get(choice);\n}\n\nfunction getGuideSectionForMode(\n  mode: AtomicGuideSectionName,\n): AtomicGuideSection {\n  const section = GUIDE_SECTIONS_BY_NAME.get(mode);\n  if (!section) throw new Error(`Unknown Atomic guide section: ${mode}`);\n  return section;\n}\n\nfunction getAtomicGuideHelpMenu(): string {\n  const sectionHelp = GUIDE_SECTIONS.map(\n    (section) => `- \\`${section.label}\\` — run \\`/atomic ${section.label}\\``,\n  ).join(\"\\n\");\n  return `# Atomic\\n\\nSelect where to start:\\n\\n${sectionHelp}`;\n}\n\nexport function normalizeAtomicGuideMode(args: string): AtomicGuideMode {\n  const normalized = stripTrailingAtomicGuidePunctuation(\n    args.trim().toLowerCase(),\n  );\n  if (!normalized) return \"help\";\n\n  return GUIDE_SECTIONS_BY_INPUT.get(normalized)?.name ?? \"help\";\n}\n\nexport function getAtomicGuideArgumentCompletions(\n  prefix: string,\n): AutocompleteItem[] | null {\n  const query = prefix.trim().toLowerCase();\n  const items = GUIDE_SECTIONS.map((section) => ({\n    value: section.label,\n    label: section.label,\n    description: section.description,\n  }));\n  const filtered = query\n    ? items.filter(\n        (item) => item.value.startsWith(query) || item.label.startsWith(query),\n      )\n    : items;\n  return filtered.length > 0 ? filtered : null;\n}\n\nfunction readLatestStableChangelog(cwd: string): string {\n  const changelogPath = getChangelogPath();\n  const stableSections = parseChangelog(changelogPath)\n    .filter((entry) => entry.prerelease === null)\n    .slice(0, 3)\n    .map((entry) => entry.content.trim())\n    .filter(Boolean);\n\n  if (stableSections.length === 0) {\n    return `# What's new\\n\\nNo stable release sections were found. Try \\`/changelog\\` for the interactive changelog viewer.\\n\\n─────────────────────────────────────────────────────────────────\\n\\nWhere to next:\\n\\n\\`/atomic example\\` — see a practical first workflow\\n\\`/atomic overview\\` — quick refresh`;\n  }\n\n  const relativePath = path.relative(cwd, changelogPath) || changelogPath;\n  return `# What's new\\n\\n${stableSections.join(\"\\n\\n\")}\\n\\nSource: \\`${relativePath}\\`\\n\\n─────────────────────────────────────────────────────────────────\\n\\nWhere to next:\\n\\n\\`/atomic example\\` — see a practical first workflow\\n\\`/atomic overview\\` — quick refresh`;\n}\n\nexport function getAtomicGuideMessage(\n  mode: AtomicGuideMode,\n  cwd: string,\n): string {\n  if (mode === \"help\") return getAtomicGuideHelpMenu();\n  return getGuideSectionForMode(mode).render(cwd);\n}\n\nexport function atomicGuideModeForChoice(\n  choice: AtomicGuideHelpChoice,\n): AtomicGuideMode {\n  return getGuideSectionForChoice(choice)?.name ?? \"help\";\n}\n"]}

package/dist/core/atomic-guide-command.js

@@ -4,7 +4,7 @@ export const ATOMIC_GUIDE_COMMAND_NAME = "atomic";
 export const ATOMIC_GUIDE_COMMAND_DESCRIPTION = "Atomic onboarding and help guide";
 const OVERVIEW = `# Atomic overview
 
-Atomic turns one-off prompts into developer workflows: on-call debugging, repo research that turns into implementation, testing and review loops, and larger multi-stage automation. Use \`/workflow goal\` for small-to-medium changes with a clear work surface, exact outcome, and named validation; keep \`/workflow ralph\` for larger migrations, broad refactors, and multi-package research-first implementation work. Start Atomic in a project with \`atomic\`, then talk to it normally. Use \`@file\` to attach files, \`!command\` to run shell output through the model, and \`!!command\` to run shell output without adding it to context.
+Atomic turns one-off prompts into developer workflows: on-call debugging, repo research that turns into implementation, testing and review loops, and larger multi-stage automation. Workflows are the default for non-trivial work and requests with inherent structure plus a verifiable objective, including implementation, build, debugging, bug-fix, migration, new-feature, scoped multi-file, or validation-heavy docs/code work. Loop-shaped prompts like \`do X until Y\`, \`repeat until\`, \`iterate until\`, \`review/fix until passing\`, or \`run checks and fix until green\` should map to a workflow unless the task is a tiny deterministic direct edit or simple answer. Use \`/workflow goal\` for small-to-medium changes with a clear work surface, exact outcome, and named validation; keep \`/workflow ralph\` for larger migrations, broad refactors, and multi-package research-first implementation work. Start Atomic in a project with \`atomic\`, then talk to it normally. Use \`@file\` to attach files, \`!command\` to run shell output through the model, and \`!!command\` to run shell output without adding it to context.
 
 ## Core session commands
 
@@ -22,9 +22,9 @@ Atomic turns one-off prompts into developer workflows: on-call debugging, repo r
 
 | Goal | How to use |
 |---|---|
-| On-call / broken behavior | Run \`/run debugger "Reproduce the failure, patch the root cause, and validate it"\` for a focused fix loop, or ask Atomic in chat to build a reusable workflow that does the same |
+| On-call / broken behavior | Use \`/workflow goal objective="Reproduce the failure, patch the root cause, and validate it"\` for a focused fix loop; reserve direct debugger/subagent calls for narrow diagnosis or truly tiny deterministic fixes |
 | Research → spec → implementation | Chain \`/skill:research-codebase\` → \`/skill:create-spec\` → \`/workflow goal objective="..."\` for bounded scoped work with explicit validation; add \`create_pr=true\` for Goal's final PR handoff after approval, or use \`/workflow ralph ...\` when the work needs research-first broad refactoring |
-| Testing / regression hardening | Run \`/skill:tdd\` for test-first work, then \`/parallel-review current diff\`, then land the change |
+| Testing / regression hardening | Use \`/workflow goal objective="Add the regression coverage, fix failures, and finish when focused tests pass"\`; loop wording like review/fix/test until passing is workflow-shaped |
 | Large repo discovery | Run \`/parallel codebase-locator "map the area" -> codebase-analyzer "trace the current flow" -> codebase-pattern-finder "find patterns" --bg\`, or \`/workflow deep-research-codebase\` for whole-repo synthesis |
 | UI / product polish | Run \`/skill:impeccable\` for interface critique and refinement, or \`/workflow open-claude-design\` for generation + refinement loops |
 
@@ -33,8 +33,8 @@ Atomic turns one-off prompts into developer workflows: on-call debugging, repo r
 | Workflow | When to use | How to run |
 |---|---|---|
 | \`deep-research-codebase\` | broad repo or cross-cutting research before you decide what to change (for one area, use \`/skill:research-codebase\`; this indexes the whole repo) | \`/workflow deep-research-codebase prompt="How do payment retries work end to end?"\` |
-| \`goal\` | small-to-medium scoped changes when you can name the work surface, outcome, and validation; keeps receipts in a ledger, stops as \`complete\`, \`blocked\`, or \`needs_human\`, and can run a final PR handoff with \`create_pr=true\` after approval | \`/workflow goal objective="Implement specs/<date>-<topic>.md, run focused tests, and validate the changed behavior"\` |
-| \`ralph\` | larger migrations, broad refactors, and multi-package changes where you want Atomic to research first, delegate, review, and iterate; add \`create_pr=true\` only when you want the final pull-request stage and report | \`/workflow ralph prompt="Migrate the database layer to Drizzle" create_pr=true\` |
+| \`goal\` | small-to-medium scoped changes when you can name the work surface, outcome, and validation, including bug fixes, debugging, scoped multi-file edits, and test/fix loops; keeps receipts in a ledger, stops as \`complete\`, \`blocked\`, or \`needs_human\`, and can run a final PR handoff with \`create_pr=true\` after approval | \`/workflow goal objective="Implement specs/<date>-<topic>.md, run focused tests, and validate the changed behavior"\` |
+| \`ralph\` | larger migrations, new features, broad refactors, and multi-package changes where you want Atomic to research first, delegate, review, and iterate; add \`create_pr=true\` only when you want the final pull-request stage and report | \`/workflow ralph prompt="Migrate the database layer to Drizzle" create_pr=true\` |
 | \`open-claude-design\` | UI and design-system work that benefits from generation and refinement loops | \`/workflow open-claude-design prompt="Refresh the settings page hierarchy"\` |
 
 Use \`/workflow list\` to see what is available and \`/workflow inputs <name>\` to inspect inputs in your environment.
@@ -98,15 +98,17 @@ Skip this if the implementation request is already precise.
 
 ## 3. Implement with review built in
 
-For ordinary work, ask Atomic directly and require validation:
-
-\`Implement the approved spec in specs/<date>-<topic>.md. Run focused tests and summarize validation.\`
+Default to a workflow for non-trivial implementation, build, debugging, bug-fix, migration, new-feature, scoped multi-file, or docs/code-change work when validation matters. Direct chat is best reserved for tiny deterministic single-file/no-test/no-review edits or simple answers.
 
 For small-to-medium scoped changes where you can identify the work surface, exact outcome, and validation, use \`goal\`:
 
 \`/workflow goal objective="Implement specs/<date>-<topic>.md, run focused tests, and finish when the documented behavior is validated"\`
 
-For larger migrations, broad refactors, or multi-package changes that need research-first implementation, use \`ralph\`:
+If the request is loop-shaped — for example \`do X until Y\`, \`repeat until\`, \`iterate until\`, \`review/fix until passing\`, or \`run checks and fix until green\` — make the stop condition explicit in the Goal objective:
+
+\`/workflow goal objective="Fix the flaky checkout test, adjust the smallest necessary code, and finish when the focused test passes three times"\`
+
+For larger migrations, broad refactors, new features, or multi-package changes that need research-first implementation, use \`ralph\`:
 
 \`/workflow ralph prompt="Migrate the database layer to Drizzle"\`
 
@@ -134,6 +136,8 @@ const WORKFLOWS = `# Workflows primer
 
 A workflow is a TypeScript-defined pipeline exported from \`workflow({...})\`. It can run tasks, chains, parallel fan-out, human-in-the-loop prompts, background status, and model fallback chains.
 
+Use workflows by default for non-trivial work with a verifiable objective: implementation, build, debugging, bug-fix, migration, new-feature, scoped multi-file, validation-heavy docs/code changes, or any prompt with a stop condition such as \`do X until Y\`, \`repeat until\`, \`iterate until\`, or \`review/fix until passing\`. Skip workflows only for tiny deterministic direct edits or simple answers where tracking would add more overhead than value.
+
 You do not have to write TypeScript to add one. Describe the workflow you want in plain chat — goal, inputs, stages, which steps are parallel or sequential, handoff/output shape, and any model or thinking-level preferences — and Atomic will use the workflow docs to scaffold a reusable definition under \`.atomic/workflows/\` and reload it for you. Hand-edit the TypeScript afterward when you want precise control.
 
 ## Built-in workflows
@@ -141,8 +145,8 @@ You do not have to write TypeScript to add one. Describe the workflow you want i
 | Workflow | When to use | How to run |
 |---|---|---|
 | \`deep-research-codebase\` | broad repo or cross-cutting research before you decide what to change (for one area, use \`/skill:research-codebase\`; this indexes the whole repo) | \`/workflow deep-research-codebase prompt="How do payment retries work end to end?"\` |
-| \`goal\` | small-to-medium scoped changes with a clear outcome and named validation; add \`create_pr=true\` only for final PR handoff after approval | \`/workflow goal objective="Update the CLI docs, include one usage example, and verify the docs build passes"\` |
-| \`ralph\` | larger migrations, broad refactors, and multi-package research-first implementation work | \`/workflow ralph prompt="Migrate the database layer to Drizzle" create_pr=true\` |
+| \`goal\` | small-to-medium scoped changes with a clear outcome and named validation, including bug fixes, debugging, scoped multi-file edits, and test/fix loops; add \`create_pr=true\` only for final PR handoff after approval | \`/workflow goal objective="Update the CLI docs, include one usage example, and verify the docs build passes"\` |
+| \`ralph\` | larger migrations, new features, broad refactors, and multi-package research-first implementation work | \`/workflow ralph prompt="Migrate the database layer to Drizzle" create_pr=true\` |
 | \`open-claude-design\` | frontend and product design work | \`/workflow open-claude-design prompt="Refresh the settings page hierarchy"\` |
 
 Use \`/workflow inputs <name>\` to inspect the exact inputs in your environment.

package/dist/core/atomic-guide-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-guide-command.js","sourceRoot":"","sources":["../../src/core/atomic-guide-command.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from \"node:path\";\nimport type { AutocompleteItem } from \"@earendil-works/pi-tui\";\nimport { getChangelogPath, parseChangelog } from \"../utils/changelog.ts\";\n\nexport const ATOMIC_GUIDE_COMMAND_NAME = \"atomic\";\nexport const ATOMIC_GUIDE_COMMAND_DESCRIPTION =\n  \"Atomic onboarding and help guide\";\n\nconst OVERVIEW = `# Atomic overview\n\nAtomic turns one-off prompts into developer workflows: on-call debugging, repo research that turns into implementation, testing and review loops, and larger multi-stage automation. Use \\`/workflow goal\\` for small-to-medium changes with a clear work surface, exact outcome, and named validation; keep \\`/workflow ralph\\` for larger migrations, broad refactors, and multi-package research-first implementation work. Start Atomic in a project with \\`atomic\\`, then talk to it normally. Use \\`@file\\` to attach files, \\`!command\\` to run shell output through the model, and \\`!!command\\` to run shell output without adding it to context.\n\n## Core session commands\n\n| Command | Use |\n|---|---|\n| \\`/login\\` | configure auth |\n| \\`/model\\` | switch model |\n| \\`/settings\\` | thinking level, theme, message delivery, transport |\n| \\`/new\\`, \\`/resume\\` | start or resume sessions |\n| \\`/tree\\`, \\`/fork\\`, \\`/clone\\` | branch or navigate session history |\n| \\`/compact\\` | delete safe older context verbatim |\n| \\`/hotkeys\\`, \\`/changelog\\` | local help and release notes |\n\n## Examples of using Atomic\n\n| Goal | How to use |\n|---|---|\n| On-call / broken behavior | Run \\`/run debugger \"Reproduce the failure, patch the root cause, and validate it\"\\` for a focused fix loop, or ask Atomic in chat to build a reusable workflow that does the same |\n| Research → spec → implementation | Chain \\`/skill:research-codebase\\` → \\`/skill:create-spec\\` → \\`/workflow goal objective=\"...\"\\` for bounded scoped work with explicit validation; add \\`create_pr=true\\` for Goal's final PR handoff after approval, or use \\`/workflow ralph ...\\` when the work needs research-first broad refactoring |\n| Testing / regression hardening | Run \\`/skill:tdd\\` for test-first work, then \\`/parallel-review current diff\\`, then land the change |\n| Large repo discovery | Run \\`/parallel codebase-locator \"map the area\" -> codebase-analyzer \"trace the current flow\" -> codebase-pattern-finder \"find patterns\" --bg\\`, or \\`/workflow deep-research-codebase\\` for whole-repo synthesis |\n| UI / product polish | Run \\`/skill:impeccable\\` for interface critique and refinement, or \\`/workflow open-claude-design\\` for generation + refinement loops |\n\n## Built-in workflows\n\n| Workflow | When to use | How to run |\n|---|---|---|\n| \\`deep-research-codebase\\` | broad repo or cross-cutting research before you decide what to change (for one area, use \\`/skill:research-codebase\\`; this indexes the whole repo) | \\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\` |\n| \\`goal\\` | small-to-medium scoped changes when you can name the work surface, outcome, and validation; keeps receipts in a ledger, stops as \\`complete\\`, \\`blocked\\`, or \\`needs_human\\`, and can run a final PR handoff with \\`create_pr=true\\` after approval | \\`/workflow goal objective=\"Implement specs/<date>-<topic>.md, run focused tests, and validate the changed behavior\"\\` |\n| \\`ralph\\` | larger migrations, broad refactors, and multi-package changes where you want Atomic to research first, delegate, review, and iterate; add \\`create_pr=true\\` only when you want the final pull-request stage and report | \\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\" create_pr=true\\` |\n| \\`open-claude-design\\` | UI and design-system work that benefits from generation and refinement loops | \\`/workflow open-claude-design prompt=\"Refresh the settings page hierarchy\"\\` |\n\nUse \\`/workflow list\\` to see what is available and \\`/workflow inputs <name>\\` to inspect inputs in your environment.\n\n## Top skills\n\n| Skill | When to use | How to run |\n|---|---|---|\n| \\`research-codebase\\` | write a grounded research artifact for one subsystem or question | \\`/skill:research-codebase how the rate limiter works in src/middleware/\\` |\n| \\`create-spec\\` | turn research into an implementation-ready plan | \\`/skill:create-spec from research/docs/<date>-<topic>.md\\` |\n| \\`tdd\\` | do test-first feature or bug work | \\`/skill:tdd\\` |\n| \\`prompt-engineer\\` | tighten a vague prompt before a long run | \\`/skill:prompt-engineer Draft a sharper implementation prompt for ...\\` |\n| \\`subagent\\` | learn delegation patterns and exact \\`/run\\`, \\`/parallel\\`, and \\`/chain\\` usage | \\`/skill:subagent\\` |\n| \\`impeccable\\` | critique or refine frontend and product UI | \\`/skill:impeccable\\` |\n\n## Subagents\n\nSubagents are focused child Atomic sessions you can point at one job inside the repo.\n\n| Built-in subagent | Use |\n|---|---|\n| \\`codebase-locator\\` | find relevant files, tests, entrypoints, and configs |\n| \\`codebase-analyzer\\` | explain current behavior with file:line refs |\n| \\`codebase-pattern-finder\\` | find existing code to model after |\n| \\`debugger\\` | reproduce, diagnose, and fix broken behavior |\n\nHow the direct commands map to repo work:\n- \\`/run\\` = one specialist on one job, for example \\`/run codebase-locator \"Map the webhook retry flow\"\\`\n- \\`/parallel\\` = several independent specialists at once, for example \\`/parallel codebase-locator \"map retry files\" -> codebase-pattern-finder \"find existing retry/backoff patterns\" -> codebase-online-researcher \"research current retry guidance\" --bg\\`\n- \\`/chain\\` = ordered handoffs, for example \\`/chain codebase-locator \"find the auth files\" -> codebase-analyzer \"trace the auth flow\" -> debugger \"patch the failing auth edge case\"\\`\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic example\\` — see the pieces used on a code task\n\\`/atomic workflows\\` — learn when to use workflows`;\n\nconst EXAMPLE = `# Practical example\n\nThis is an example of a spec-driven development process using Atomic workflows. Use it when you are new to a repo or the task has non-trivial scope. Type the examples below into the Atomic TUI chat after starting \\`atomic\\` in your project.\n\n## 1. Research what exists\n\nUse \\`/skill:research-codebase\\` for a scoped area, subsystem, or directory:\n\n\\`/skill:research-codebase how the rate limiter works in src/middleware/\\`\n\nUse \\`deep-research-codebase\\` when the answer spans the whole repo or a cross-cutting implementation path:\n\n\\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\`\n\nIf the research prompt is vague, tighten it first with \\`/skill:prompt-engineer\\`:\n\n\\`/skill:prompt-engineer Draft a sharper repo-research prompt for understanding payment retries end to end, including retries, queues, and failure handling.\\`\n\n## 2. Create a spec when requirements are fuzzy\n\nSkip this if the implementation request is already precise.\n\n\\`/skill:create-spec from research/docs/<date>-<topic>.md\\`\n\n## 3. Implement with review built in\n\nFor ordinary work, ask Atomic directly and require validation:\n\n\\`Implement the approved spec in specs/<date>-<topic>.md. Run focused tests and summarize validation.\\`\n\nFor small-to-medium scoped changes where you can identify the work surface, exact outcome, and validation, use \\`goal\\`:\n\n\\`/workflow goal objective=\"Implement specs/<date>-<topic>.md, run focused tests, and finish when the documented behavior is validated\"\\`\n\nFor larger migrations, broad refactors, or multi-package changes that need research-first implementation, use \\`ralph\\`:\n\n\\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\"\\`\n\nAdd \\`create_pr=true\\` only when you want the final pull-request stage and report after the review gate approves.\n\n## 4. Decide and land\n\nIf you used \\`goal\\`, the workflow already persisted receipts in a goal ledger and reviewer-gated completion. Use its final status — \\`complete\\`, \\`blocked\\`, or \\`needs_human\\` — plus the remaining-work report to decide whether to ship, unblock, or clarify. If you enabled \\`create_pr=true\\`, use its final pull-request report to decide whether to ship or iterate again.\n\nIf you used \\`ralph\\`, the workflow transformed the prompt into a research question, researched the codebase, delegated implementation through sub-agents, reviewed, and iterated. If you enabled \\`create_pr=true\\`, use its final pull-request report to decide whether to ship or iterate again.\n\nIf you implemented directly instead of using a workflow, you can still run:\n\n\\`/parallel-review current diff\\`\n\nAtomic will synthesize reviewer feedback and ask before applying fixes.\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic workflows\\` — learn when to use workflows\n\\`/atomic overview\\` — quick refresh`;\n\nconst WORKFLOWS = `# Workflows primer\n\nA workflow is a TypeScript-defined pipeline exported from \\`workflow({...})\\`. It can run tasks, chains, parallel fan-out, human-in-the-loop prompts, background status, and model fallback chains.\n\nYou do not have to write TypeScript to add one. Describe the workflow you want in plain chat — goal, inputs, stages, which steps are parallel or sequential, handoff/output shape, and any model or thinking-level preferences — and Atomic will use the workflow docs to scaffold a reusable definition under \\`.atomic/workflows/\\` and reload it for you. Hand-edit the TypeScript afterward when you want precise control.\n\n## Built-in workflows\n\n| Workflow | When to use | How to run |\n|---|---|---|\n| \\`deep-research-codebase\\` | broad repo or cross-cutting research before you decide what to change (for one area, use \\`/skill:research-codebase\\`; this indexes the whole repo) | \\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\` |\n| \\`goal\\` | small-to-medium scoped changes with a clear outcome and named validation; add \\`create_pr=true\\` only for final PR handoff after approval | \\`/workflow goal objective=\"Update the CLI docs, include one usage example, and verify the docs build passes\"\\` |\n| \\`ralph\\` | larger migrations, broad refactors, and multi-package research-first implementation work | \\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\" create_pr=true\\` |\n| \\`open-claude-design\\` | frontend and product design work | \\`/workflow open-claude-design prompt=\"Refresh the settings page hierarchy\"\\` |\n\nUse \\`/workflow inputs <name>\\` to inspect the exact inputs in your environment.\n\nUse \\`/skill:research-codebase ...\\` when you want research on one subsystem, directory, or focused question. Use \\`/workflow deep-research-codebase ...\\` when the answer needs end-to-end tracing across many parts of the repo.\n\nIf you are drafting research, reviewer, or synthesis prompts for a workflow, use \\`/skill:prompt-engineer\\` first. It is a good fit when a stage prompt feels vague, overloaded, or underspecified.\n\n## What good workflow authoring looks like\n\nA good workflow request is explicit about stage purpose, model choice, handoff, and the decision each step must return.\n\nExample: ask Atomic in chat with something like this:\n\n~~~text\nCreate a reusable workflow called review-changes.\n\nIt should accept one required text input called target for a diff, PR summary, or review target.\n\nRun two independent review stages in parallel with fresh context:\n- one reviewer focused on correctness, regressions, and missing tests using openai-codex/gpt-5.5 at xhigh thinking\n- one reviewer focused on edge cases, maintainability, and hidden risks using anthropic/claude-opus-4-8 at xhigh thinking\n\nThen add an aggregate stage that consolidates both reviews, deduplicates overlap, keeps only evidence-backed issues, and separates blockers from optional suggestions using openai/gpt-5.5 at high thinking.\n\nFinally add an adjudicate stage using anthropic/claude-sonnet-4 at high thinking that decides what to fix now, what to defer, and what to reject. Return a short action list with rationale.\n\nThe workflow should return structured output with consolidated_review and decision fields.\n~~~\n\nWhy this is good:\n- it names the workflow and required input\n- it specifies which stages are parallel vs sequential\n- each stage has one job\n- it defines the handoff and final outputs\n- it calls out model choice and thinking level where that matters\n\n## Run and inspect\n\n\\`/workflow list\\`\n\n\\`/workflow inputs goal\\`\n\n\\`/workflow goal objective=\"Fix the settings form validation bug, add the focused test, and finish when invalid emails show the inline error without submitting\"\\`\n\n\\`/workflow inputs ralph\\`\n\n\\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\" create_pr=true\\`\n\n\\`/workflow status\\`\n\n\\`/workflow connect <run-id>\\`\n\n\\`/workflow interrupt <run-id>\\`\n\n\\`/workflow resume <run-id>\\`\n\nWorkflows run as background tasks. Use F2 or \\`/workflow connect <run-id>\\` for the graph viewer. Human-in-the-loop prompts appear there, not as chat modals, and awaiting-input states do not wake the main chat agent. Completion and failure notices are steered back into the main chat; answers submitted in the workflow UI interrupt stale main-chat questions so the model does not ask again.\n\n## Author your own\n\nDescribe your workflow in plain chat — say what you want the workflow to accomplish, what inputs it should accept, what stages should run, and what final output or decision it should return. Atomic will use the workflow docs to scaffold a reusable definition under \\`.atomic/workflows/\\`, ask clarifying questions when stage purpose, models, or handoffs are ambiguous, and run \\`/workflow reload\\` so you can launch it immediately.\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic example\\` — see workflows in a normal task flow\n\\`/atomic overview\\` — quick refresh`;\n\nconst GUIDE_SECTIONS = [\n  {\n    name: \"overview\",\n    aliases: [],\n    label: \"overview\",\n    description: \"30-second overview\",\n    render: () => OVERVIEW,\n  },\n  {\n    name: \"workflows\",\n    aliases: [\"workflow\"],\n    label: \"workflows\",\n    description: \"Workflow primer\",\n    render: () => WORKFLOWS,\n  },\n  {\n    name: \"example\",\n    aliases: [\"examples\"],\n    label: \"example\",\n    description: \"Practical first workflow\",\n    render: () => EXAMPLE,\n  },\n  {\n    name: \"whats-new\",\n    aliases: [\"what's new\", \"whats new\", \"news\", \"updates\", \"changelog\"],\n    label: \"what's new\",\n    description: \"Recent release notes\",\n    render: readLatestStableChangelog,\n  },\n] as const satisfies readonly {\n  readonly name: string;\n  readonly aliases: readonly string[];\n  readonly label: string;\n  readonly description: string;\n  readonly render: (cwd: string) => string;\n}[];\n\ntype AtomicGuideSection = (typeof GUIDE_SECTIONS)[number];\ntype AtomicGuideSectionName = AtomicGuideSection[\"name\"];\n\nexport type AtomicGuideHelpChoice = AtomicGuideSection[\"label\"];\n\nexport type AtomicGuideMode = \"help\" | AtomicGuideSectionName;\n\nexport const ATOMIC_GUIDE_HELP_CHOICES: readonly AtomicGuideHelpChoice[] =\n  GUIDE_SECTIONS.map((section) => section.label);\n\nconst GUIDE_SECTIONS_BY_NAME = new Map<\n  AtomicGuideSectionName,\n  AtomicGuideSection\n>(GUIDE_SECTIONS.map((section) => [section.name, section]));\nconst GUIDE_SECTIONS_BY_LABEL = new Map<string, AtomicGuideSection>(\n  GUIDE_SECTIONS.map((section) => [section.label, section]),\n);\nconst GUIDE_SECTIONS_BY_INPUT = new Map<string, AtomicGuideSection>(\n  GUIDE_SECTIONS.flatMap((section) =>\n    [section.name, section.label, ...section.aliases].map(\n      (input) => [input, section] as const,\n    ),\n  ),\n);\n\nexport function isAtomicGuideHelpChoice(\n  choice: string,\n): choice is AtomicGuideHelpChoice {\n  return GUIDE_SECTIONS_BY_LABEL.has(choice);\n}\n\nconst ATOMIC_GUIDE_TRAILING_PUNCTUATION = \"?!.,;:\";\n\nfunction stripTrailingAtomicGuidePunctuation(value: string): string {\n  let end = value.length;\n  while (\n    end > 0 &&\n    ATOMIC_GUIDE_TRAILING_PUNCTUATION.includes(value.charAt(end - 1))\n  ) {\n    end--;\n  }\n  return value.slice(0, end);\n}\n\nfunction getGuideSectionForChoice(\n  choice: string,\n): AtomicGuideSection | undefined {\n  return GUIDE_SECTIONS_BY_LABEL.get(choice);\n}\n\nfunction getGuideSectionForMode(\n  mode: AtomicGuideSectionName,\n): AtomicGuideSection {\n  const section = GUIDE_SECTIONS_BY_NAME.get(mode);\n  if (!section) throw new Error(`Unknown Atomic guide section: ${mode}`);\n  return section;\n}\n\nfunction getAtomicGuideHelpMenu(): string {\n  const sectionHelp = GUIDE_SECTIONS.map(\n    (section) => `- \\`${section.label}\\` — run \\`/atomic ${section.label}\\``,\n  ).join(\"\\n\");\n  return `# Atomic\\n\\nSelect where to start:\\n\\n${sectionHelp}`;\n}\n\nexport function normalizeAtomicGuideMode(args: string): AtomicGuideMode {\n  const normalized = stripTrailingAtomicGuidePunctuation(\n    args.trim().toLowerCase(),\n  );\n  if (!normalized) return \"help\";\n\n  return GUIDE_SECTIONS_BY_INPUT.get(normalized)?.name ?? \"help\";\n}\n\nexport function getAtomicGuideArgumentCompletions(\n  prefix: string,\n): AutocompleteItem[] | null {\n  const query = prefix.trim().toLowerCase();\n  const items = GUIDE_SECTIONS.map((section) => ({\n    value: section.label,\n    label: section.label,\n    description: section.description,\n  }));\n  const filtered = query\n    ? items.filter(\n        (item) => item.value.startsWith(query) || item.label.startsWith(query),\n      )\n    : items;\n  return filtered.length > 0 ? filtered : null;\n}\n\nfunction readLatestStableChangelog(cwd: string): string {\n  const changelogPath = getChangelogPath();\n  const stableSections = parseChangelog(changelogPath)\n    .filter((entry) => entry.prerelease === null)\n    .slice(0, 3)\n    .map((entry) => entry.content.trim())\n    .filter(Boolean);\n\n  if (stableSections.length === 0) {\n    return `# What's new\\n\\nNo stable release sections were found. Try \\`/changelog\\` for the interactive changelog viewer.\\n\\n─────────────────────────────────────────────────────────────────\\n\\nWhere to next:\\n\\n\\`/atomic example\\` — see a practical first workflow\\n\\`/atomic overview\\` — quick refresh`;\n  }\n\n  const relativePath = path.relative(cwd, changelogPath) || changelogPath;\n  return `# What's new\\n\\n${stableSections.join(\"\\n\\n\")}\\n\\nSource: \\`${relativePath}\\`\\n\\n─────────────────────────────────────────────────────────────────\\n\\nWhere to next:\\n\\n\\`/atomic example\\` — see a practical first workflow\\n\\`/atomic overview\\` — quick refresh`;\n}\n\nexport function getAtomicGuideMessage(\n  mode: AtomicGuideMode,\n  cwd: string,\n): string {\n  if (mode === \"help\") return getAtomicGuideHelpMenu();\n  return getGuideSectionForMode(mode).render(cwd);\n}\n\nexport function atomicGuideModeForChoice(\n  choice: AtomicGuideHelpChoice,\n): AtomicGuideMode {\n  return getGuideSectionForChoice(choice)?.name ?? \"help\";\n}\n"]}
+{"version":3,"file":"atomic-guide-command.js","sourceRoot":"","sources":["../../src/core/atomic-guide-command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEzE,MAAM,CAAC,MAAM,yBAAyB,GAAG,QAAQ,CAAC;AAClD,MAAM,CAAC,MAAM,gCAAgC,GAC3C,kCAAkC,CAAC;AAErC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oDAqEmC,CAAC;AAErD,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qCA2DqB,CAAC;AAEtC,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qCAmFmB,CAAC;AAEtC,MAAM,cAAc,GAAG;IACrB;QACE,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,EAAE;QACX,KAAK,EAAE,UAAU;QACjB,WAAW,EAAE,oBAAoB;QACjC,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ;KACvB;IACD;QACE,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,CAAC,UAAU,CAAC;QACrB,KAAK,EAAE,WAAW;QAClB,WAAW,EAAE,iBAAiB;QAC9B,MAAM,EAAE,GAAG,EAAE,CAAC,SAAS;KACxB;IACD;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,CAAC,UAAU,CAAC;QACrB,KAAK,EAAE,SAAS;QAChB,WAAW,EAAE,0BAA0B;QACvC,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO;KACtB;IACD;QACE,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,CAAC,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC;QACpE,KAAK,EAAE,YAAY;QACnB,WAAW,EAAE,sBAAsB;QACnC,MAAM,EAAE,yBAAyB;KAClC;CAOA,CAAC;AASJ,MAAM,CAAC,MAAM,yBAAyB,GACpC,cAAc,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAEjD,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAGpC,cAAc,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;AAC5D,MAAM,uBAAuB,GAAG,IAAI,GAAG,CACrC,cAAc,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAC1D,CAAC;AACF,MAAM,uBAAuB,GAAG,IAAI,GAAG,CACrC,cAAc,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CACjC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,CACnD,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,CAAU,CACrC,CACF,CACF,CAAC;AAEF,MAAM,UAAU,uBAAuB,CACrC,MAAc;IAEd,OAAO,uBAAuB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,iCAAiC,GAAG,QAAQ,CAAC;AAEnD,SAAS,mCAAmC,CAAC,KAAa;IACxD,IAAI,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC;IACvB,OACE,GAAG,GAAG,CAAC;QACP,iCAAiC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,EACjE,CAAC;QACD,GAAG,EAAE,CAAC;IACR,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,wBAAwB,CAC/B,MAAc;IAEd,OAAO,uBAAuB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,sBAAsB,CAC7B,IAA4B;IAE5B,MAAM,OAAO,GAAG,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,IAAI,EAAE,CAAC,CAAC;IACvE,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,sBAAsB;IAC7B,MAAM,WAAW,GAAG,cAAc,CAAC,GAAG,CACpC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,OAAO,CAAC,KAAK,sBAAsB,OAAO,CAAC,KAAK,IAAI,CACzE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,OAAO,yCAAyC,WAAW,EAAE,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,IAAY;IACnD,MAAM,UAAU,GAAG,mCAAmC,CACpD,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAC1B,CAAC;IACF,IAAI,CAAC,UAAU;QAAE,OAAO,MAAM,CAAC;IAE/B,OAAO,uBAAuB,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,IAAI,IAAI,MAAM,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,iCAAiC,CAC/C,MAAc;IAEd,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC1C,MAAM,KAAK,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC7C,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAC,CAAC,CAAC;IACJ,MAAM,QAAQ,GAAG,KAAK;QACpB,CAAC,CAAC,KAAK,CAAC,MAAM,CACV,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CACvE;QACH,CAAC,CAAC,KAAK,CAAC;IACV,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/C,CAAC;AAED,SAAS,yBAAyB,CAAC,GAAW;IAC5C,MAAM,aAAa,GAAG,gBAAgB,EAAE,CAAC;IACzC,MAAM,cAAc,GAAG,cAAc,CAAC,aAAa,CAAC;SACjD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;SAC5C,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;SACX,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;SACpC,MAAM,CAAC,OAAO,CAAC,CAAC;IAEnB,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO,sSAAsS,CAAC;IAChT,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC,IAAI,aAAa,CAAC;IACxE,OAAO,mBAAmB,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,iBAAiB,YAAY,yLAAyL,CAAC;AAC9Q,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,IAAqB,EACrB,GAAW;IAEX,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,sBAAsB,EAAE,CAAC;IACrD,OAAO,sBAAsB,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,MAA6B;IAE7B,OAAO,wBAAwB,CAAC,MAAM,CAAC,EAAE,IAAI,IAAI,MAAM,CAAC;AAC1D,CAAC","sourcesContent":["import * as path from \"node:path\";\nimport type { AutocompleteItem } from \"@earendil-works/pi-tui\";\nimport { getChangelogPath, parseChangelog } from \"../utils/changelog.ts\";\n\nexport const ATOMIC_GUIDE_COMMAND_NAME = \"atomic\";\nexport const ATOMIC_GUIDE_COMMAND_DESCRIPTION =\n  \"Atomic onboarding and help guide\";\n\nconst OVERVIEW = `# Atomic overview\n\nAtomic turns one-off prompts into developer workflows: on-call debugging, repo research that turns into implementation, testing and review loops, and larger multi-stage automation. Workflows are the default for non-trivial work and requests with inherent structure plus a verifiable objective, including implementation, build, debugging, bug-fix, migration, new-feature, scoped multi-file, or validation-heavy docs/code work. Loop-shaped prompts like \\`do X until Y\\`, \\`repeat until\\`, \\`iterate until\\`, \\`review/fix until passing\\`, or \\`run checks and fix until green\\` should map to a workflow unless the task is a tiny deterministic direct edit or simple answer. Use \\`/workflow goal\\` for small-to-medium changes with a clear work surface, exact outcome, and named validation; keep \\`/workflow ralph\\` for larger migrations, broad refactors, and multi-package research-first implementation work. Start Atomic in a project with \\`atomic\\`, then talk to it normally. Use \\`@file\\` to attach files, \\`!command\\` to run shell output through the model, and \\`!!command\\` to run shell output without adding it to context.\n\n## Core session commands\n\n| Command | Use |\n|---|---|\n| \\`/login\\` | configure auth |\n| \\`/model\\` | switch model |\n| \\`/settings\\` | thinking level, theme, message delivery, transport |\n| \\`/new\\`, \\`/resume\\` | start or resume sessions |\n| \\`/tree\\`, \\`/fork\\`, \\`/clone\\` | branch or navigate session history |\n| \\`/compact\\` | delete safe older context verbatim |\n| \\`/hotkeys\\`, \\`/changelog\\` | local help and release notes |\n\n## Examples of using Atomic\n\n| Goal | How to use |\n|---|---|\n| On-call / broken behavior | Use \\`/workflow goal objective=\"Reproduce the failure, patch the root cause, and validate it\"\\` for a focused fix loop; reserve direct debugger/subagent calls for narrow diagnosis or truly tiny deterministic fixes |\n| Research → spec → implementation | Chain \\`/skill:research-codebase\\` → \\`/skill:create-spec\\` → \\`/workflow goal objective=\"...\"\\` for bounded scoped work with explicit validation; add \\`create_pr=true\\` for Goal's final PR handoff after approval, or use \\`/workflow ralph ...\\` when the work needs research-first broad refactoring |\n| Testing / regression hardening | Use \\`/workflow goal objective=\"Add the regression coverage, fix failures, and finish when focused tests pass\"\\`; loop wording like review/fix/test until passing is workflow-shaped |\n| Large repo discovery | Run \\`/parallel codebase-locator \"map the area\" -> codebase-analyzer \"trace the current flow\" -> codebase-pattern-finder \"find patterns\" --bg\\`, or \\`/workflow deep-research-codebase\\` for whole-repo synthesis |\n| UI / product polish | Run \\`/skill:impeccable\\` for interface critique and refinement, or \\`/workflow open-claude-design\\` for generation + refinement loops |\n\n## Built-in workflows\n\n| Workflow | When to use | How to run |\n|---|---|---|\n| \\`deep-research-codebase\\` | broad repo or cross-cutting research before you decide what to change (for one area, use \\`/skill:research-codebase\\`; this indexes the whole repo) | \\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\` |\n| \\`goal\\` | small-to-medium scoped changes when you can name the work surface, outcome, and validation, including bug fixes, debugging, scoped multi-file edits, and test/fix loops; keeps receipts in a ledger, stops as \\`complete\\`, \\`blocked\\`, or \\`needs_human\\`, and can run a final PR handoff with \\`create_pr=true\\` after approval | \\`/workflow goal objective=\"Implement specs/<date>-<topic>.md, run focused tests, and validate the changed behavior\"\\` |\n| \\`ralph\\` | larger migrations, new features, broad refactors, and multi-package changes where you want Atomic to research first, delegate, review, and iterate; add \\`create_pr=true\\` only when you want the final pull-request stage and report | \\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\" create_pr=true\\` |\n| \\`open-claude-design\\` | UI and design-system work that benefits from generation and refinement loops | \\`/workflow open-claude-design prompt=\"Refresh the settings page hierarchy\"\\` |\n\nUse \\`/workflow list\\` to see what is available and \\`/workflow inputs <name>\\` to inspect inputs in your environment.\n\n## Top skills\n\n| Skill | When to use | How to run |\n|---|---|---|\n| \\`research-codebase\\` | write a grounded research artifact for one subsystem or question | \\`/skill:research-codebase how the rate limiter works in src/middleware/\\` |\n| \\`create-spec\\` | turn research into an implementation-ready plan | \\`/skill:create-spec from research/docs/<date>-<topic>.md\\` |\n| \\`tdd\\` | do test-first feature or bug work | \\`/skill:tdd\\` |\n| \\`prompt-engineer\\` | tighten a vague prompt before a long run | \\`/skill:prompt-engineer Draft a sharper implementation prompt for ...\\` |\n| \\`subagent\\` | learn delegation patterns and exact \\`/run\\`, \\`/parallel\\`, and \\`/chain\\` usage | \\`/skill:subagent\\` |\n| \\`impeccable\\` | critique or refine frontend and product UI | \\`/skill:impeccable\\` |\n\n## Subagents\n\nSubagents are focused child Atomic sessions you can point at one job inside the repo.\n\n| Built-in subagent | Use |\n|---|---|\n| \\`codebase-locator\\` | find relevant files, tests, entrypoints, and configs |\n| \\`codebase-analyzer\\` | explain current behavior with file:line refs |\n| \\`codebase-pattern-finder\\` | find existing code to model after |\n| \\`debugger\\` | reproduce, diagnose, and fix broken behavior |\n\nHow the direct commands map to repo work:\n- \\`/run\\` = one specialist on one job, for example \\`/run codebase-locator \"Map the webhook retry flow\"\\`\n- \\`/parallel\\` = several independent specialists at once, for example \\`/parallel codebase-locator \"map retry files\" -> codebase-pattern-finder \"find existing retry/backoff patterns\" -> codebase-online-researcher \"research current retry guidance\" --bg\\`\n- \\`/chain\\` = ordered handoffs, for example \\`/chain codebase-locator \"find the auth files\" -> codebase-analyzer \"trace the auth flow\" -> debugger \"patch the failing auth edge case\"\\`\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic example\\` — see the pieces used on a code task\n\\`/atomic workflows\\` — learn when to use workflows`;\n\nconst EXAMPLE = `# Practical example\n\nThis is an example of a spec-driven development process using Atomic workflows. Use it when you are new to a repo or the task has non-trivial scope. Type the examples below into the Atomic TUI chat after starting \\`atomic\\` in your project.\n\n## 1. Research what exists\n\nUse \\`/skill:research-codebase\\` for a scoped area, subsystem, or directory:\n\n\\`/skill:research-codebase how the rate limiter works in src/middleware/\\`\n\nUse \\`deep-research-codebase\\` when the answer spans the whole repo or a cross-cutting implementation path:\n\n\\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\`\n\nIf the research prompt is vague, tighten it first with \\`/skill:prompt-engineer\\`:\n\n\\`/skill:prompt-engineer Draft a sharper repo-research prompt for understanding payment retries end to end, including retries, queues, and failure handling.\\`\n\n## 2. Create a spec when requirements are fuzzy\n\nSkip this if the implementation request is already precise.\n\n\\`/skill:create-spec from research/docs/<date>-<topic>.md\\`\n\n## 3. Implement with review built in\n\nDefault to a workflow for non-trivial implementation, build, debugging, bug-fix, migration, new-feature, scoped multi-file, or docs/code-change work when validation matters. Direct chat is best reserved for tiny deterministic single-file/no-test/no-review edits or simple answers.\n\nFor small-to-medium scoped changes where you can identify the work surface, exact outcome, and validation, use \\`goal\\`:\n\n\\`/workflow goal objective=\"Implement specs/<date>-<topic>.md, run focused tests, and finish when the documented behavior is validated\"\\`\n\nIf the request is loop-shaped — for example \\`do X until Y\\`, \\`repeat until\\`, \\`iterate until\\`, \\`review/fix until passing\\`, or \\`run checks and fix until green\\` — make the stop condition explicit in the Goal objective:\n\n\\`/workflow goal objective=\"Fix the flaky checkout test, adjust the smallest necessary code, and finish when the focused test passes three times\"\\`\n\nFor larger migrations, broad refactors, new features, or multi-package changes that need research-first implementation, use \\`ralph\\`:\n\n\\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\"\\`\n\nAdd \\`create_pr=true\\` only when you want the final pull-request stage and report after the review gate approves.\n\n## 4. Decide and land\n\nIf you used \\`goal\\`, the workflow already persisted receipts in a goal ledger and reviewer-gated completion. Use its final status — \\`complete\\`, \\`blocked\\`, or \\`needs_human\\` — plus the remaining-work report to decide whether to ship, unblock, or clarify. If you enabled \\`create_pr=true\\`, use its final pull-request report to decide whether to ship or iterate again.\n\nIf you used \\`ralph\\`, the workflow transformed the prompt into a research question, researched the codebase, delegated implementation through sub-agents, reviewed, and iterated. If you enabled \\`create_pr=true\\`, use its final pull-request report to decide whether to ship or iterate again.\n\nIf you implemented directly instead of using a workflow, you can still run:\n\n\\`/parallel-review current diff\\`\n\nAtomic will synthesize reviewer feedback and ask before applying fixes.\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic workflows\\` — learn when to use workflows\n\\`/atomic overview\\` — quick refresh`;\n\nconst WORKFLOWS = `# Workflows primer\n\nA workflow is a TypeScript-defined pipeline exported from \\`workflow({...})\\`. It can run tasks, chains, parallel fan-out, human-in-the-loop prompts, background status, and model fallback chains.\n\nUse workflows by default for non-trivial work with a verifiable objective: implementation, build, debugging, bug-fix, migration, new-feature, scoped multi-file, validation-heavy docs/code changes, or any prompt with a stop condition such as \\`do X until Y\\`, \\`repeat until\\`, \\`iterate until\\`, or \\`review/fix until passing\\`. Skip workflows only for tiny deterministic direct edits or simple answers where tracking would add more overhead than value.\n\nYou do not have to write TypeScript to add one. Describe the workflow you want in plain chat — goal, inputs, stages, which steps are parallel or sequential, handoff/output shape, and any model or thinking-level preferences — and Atomic will use the workflow docs to scaffold a reusable definition under \\`.atomic/workflows/\\` and reload it for you. Hand-edit the TypeScript afterward when you want precise control.\n\n## Built-in workflows\n\n| Workflow | When to use | How to run |\n|---|---|---|\n| \\`deep-research-codebase\\` | broad repo or cross-cutting research before you decide what to change (for one area, use \\`/skill:research-codebase\\`; this indexes the whole repo) | \\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\` |\n| \\`goal\\` | small-to-medium scoped changes with a clear outcome and named validation, including bug fixes, debugging, scoped multi-file edits, and test/fix loops; add \\`create_pr=true\\` only for final PR handoff after approval | \\`/workflow goal objective=\"Update the CLI docs, include one usage example, and verify the docs build passes\"\\` |\n| \\`ralph\\` | larger migrations, new features, broad refactors, and multi-package research-first implementation work | \\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\" create_pr=true\\` |\n| \\`open-claude-design\\` | frontend and product design work | \\`/workflow open-claude-design prompt=\"Refresh the settings page hierarchy\"\\` |\n\nUse \\`/workflow inputs <name>\\` to inspect the exact inputs in your environment.\n\nUse \\`/skill:research-codebase ...\\` when you want research on one subsystem, directory, or focused question. Use \\`/workflow deep-research-codebase ...\\` when the answer needs end-to-end tracing across many parts of the repo.\n\nIf you are drafting research, reviewer, or synthesis prompts for a workflow, use \\`/skill:prompt-engineer\\` first. It is a good fit when a stage prompt feels vague, overloaded, or underspecified.\n\n## What good workflow authoring looks like\n\nA good workflow request is explicit about stage purpose, model choice, handoff, and the decision each step must return.\n\nExample: ask Atomic in chat with something like this:\n\n~~~text\nCreate a reusable workflow called review-changes.\n\nIt should accept one required text input called target for a diff, PR summary, or review target.\n\nRun two independent review stages in parallel with fresh context:\n- one reviewer focused on correctness, regressions, and missing tests using openai-codex/gpt-5.5 at xhigh thinking\n- one reviewer focused on edge cases, maintainability, and hidden risks using anthropic/claude-opus-4-8 at xhigh thinking\n\nThen add an aggregate stage that consolidates both reviews, deduplicates overlap, keeps only evidence-backed issues, and separates blockers from optional suggestions using openai/gpt-5.5 at high thinking.\n\nFinally add an adjudicate stage using anthropic/claude-sonnet-4 at high thinking that decides what to fix now, what to defer, and what to reject. Return a short action list with rationale.\n\nThe workflow should return structured output with consolidated_review and decision fields.\n~~~\n\nWhy this is good:\n- it names the workflow and required input\n- it specifies which stages are parallel vs sequential\n- each stage has one job\n- it defines the handoff and final outputs\n- it calls out model choice and thinking level where that matters\n\n## Run and inspect\n\n\\`/workflow list\\`\n\n\\`/workflow inputs goal\\`\n\n\\`/workflow goal objective=\"Fix the settings form validation bug, add the focused test, and finish when invalid emails show the inline error without submitting\"\\`\n\n\\`/workflow inputs ralph\\`\n\n\\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\" create_pr=true\\`\n\n\\`/workflow status\\`\n\n\\`/workflow connect <run-id>\\`\n\n\\`/workflow interrupt <run-id>\\`\n\n\\`/workflow resume <run-id>\\`\n\nWorkflows run as background tasks. Use F2 or \\`/workflow connect <run-id>\\` for the graph viewer. Human-in-the-loop prompts appear there, not as chat modals, and awaiting-input states do not wake the main chat agent. Completion and failure notices are steered back into the main chat; answers submitted in the workflow UI interrupt stale main-chat questions so the model does not ask again.\n\n## Author your own\n\nDescribe your workflow in plain chat — say what you want the workflow to accomplish, what inputs it should accept, what stages should run, and what final output or decision it should return. Atomic will use the workflow docs to scaffold a reusable definition under \\`.atomic/workflows/\\`, ask clarifying questions when stage purpose, models, or handoffs are ambiguous, and run \\`/workflow reload\\` so you can launch it immediately.\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic example\\` — see workflows in a normal task flow\n\\`/atomic overview\\` — quick refresh`;\n\nconst GUIDE_SECTIONS = [\n  {\n    name: \"overview\",\n    aliases: [],\n    label: \"overview\",\n    description: \"30-second overview\",\n    render: () => OVERVIEW,\n  },\n  {\n    name: \"workflows\",\n    aliases: [\"workflow\"],\n    label: \"workflows\",\n    description: \"Workflow primer\",\n    render: () => WORKFLOWS,\n  },\n  {\n    name: \"example\",\n    aliases: [\"examples\"],\n    label: \"example\",\n    description: \"Practical first workflow\",\n    render: () => EXAMPLE,\n  },\n  {\n    name: \"whats-new\",\n    aliases: [\"what's new\", \"whats new\", \"news\", \"updates\", \"changelog\"],\n    label: \"what's new\",\n    description: \"Recent release notes\",\n    render: readLatestStableChangelog,\n  },\n] as const satisfies readonly {\n  readonly name: string;\n  readonly aliases: readonly string[];\n  readonly label: string;\n  readonly description: string;\n  readonly render: (cwd: string) => string;\n}[];\n\ntype AtomicGuideSection = (typeof GUIDE_SECTIONS)[number];\ntype AtomicGuideSectionName = AtomicGuideSection[\"name\"];\n\nexport type AtomicGuideHelpChoice = AtomicGuideSection[\"label\"];\n\nexport type AtomicGuideMode = \"help\" | AtomicGuideSectionName;\n\nexport const ATOMIC_GUIDE_HELP_CHOICES: readonly AtomicGuideHelpChoice[] =\n  GUIDE_SECTIONS.map((section) => section.label);\n\nconst GUIDE_SECTIONS_BY_NAME = new Map<\n  AtomicGuideSectionName,\n  AtomicGuideSection\n>(GUIDE_SECTIONS.map((section) => [section.name, section]));\nconst GUIDE_SECTIONS_BY_LABEL = new Map<string, AtomicGuideSection>(\n  GUIDE_SECTIONS.map((section) => [section.label, section]),\n);\nconst GUIDE_SECTIONS_BY_INPUT = new Map<string, AtomicGuideSection>(\n  GUIDE_SECTIONS.flatMap((section) =>\n    [section.name, section.label, ...section.aliases].map(\n      (input) => [input, section] as const,\n    ),\n  ),\n);\n\nexport function isAtomicGuideHelpChoice(\n  choice: string,\n): choice is AtomicGuideHelpChoice {\n  return GUIDE_SECTIONS_BY_LABEL.has(choice);\n}\n\nconst ATOMIC_GUIDE_TRAILING_PUNCTUATION = \"?!.,;:\";\n\nfunction stripTrailingAtomicGuidePunctuation(value: string): string {\n  let end = value.length;\n  while (\n    end > 0 &&\n    ATOMIC_GUIDE_TRAILING_PUNCTUATION.includes(value.charAt(end - 1))\n  ) {\n    end--;\n  }\n  return value.slice(0, end);\n}\n\nfunction getGuideSectionForChoice(\n  choice: string,\n): AtomicGuideSection | undefined {\n  return GUIDE_SECTIONS_BY_LABEL.get(choice);\n}\n\nfunction getGuideSectionForMode(\n  mode: AtomicGuideSectionName,\n): AtomicGuideSection {\n  const section = GUIDE_SECTIONS_BY_NAME.get(mode);\n  if (!section) throw new Error(`Unknown Atomic guide section: ${mode}`);\n  return section;\n}\n\nfunction getAtomicGuideHelpMenu(): string {\n  const sectionHelp = GUIDE_SECTIONS.map(\n    (section) => `- \\`${section.label}\\` — run \\`/atomic ${section.label}\\``,\n  ).join(\"\\n\");\n  return `# Atomic\\n\\nSelect where to start:\\n\\n${sectionHelp}`;\n}\n\nexport function normalizeAtomicGuideMode(args: string): AtomicGuideMode {\n  const normalized = stripTrailingAtomicGuidePunctuation(\n    args.trim().toLowerCase(),\n  );\n  if (!normalized) return \"help\";\n\n  return GUIDE_SECTIONS_BY_INPUT.get(normalized)?.name ?? \"help\";\n}\n\nexport function getAtomicGuideArgumentCompletions(\n  prefix: string,\n): AutocompleteItem[] | null {\n  const query = prefix.trim().toLowerCase();\n  const items = GUIDE_SECTIONS.map((section) => ({\n    value: section.label,\n    label: section.label,\n    description: section.description,\n  }));\n  const filtered = query\n    ? items.filter(\n        (item) => item.value.startsWith(query) || item.label.startsWith(query),\n      )\n    : items;\n  return filtered.length > 0 ? filtered : null;\n}\n\nfunction readLatestStableChangelog(cwd: string): string {\n  const changelogPath = getChangelogPath();\n  const stableSections = parseChangelog(changelogPath)\n    .filter((entry) => entry.prerelease === null)\n    .slice(0, 3)\n    .map((entry) => entry.content.trim())\n    .filter(Boolean);\n\n  if (stableSections.length === 0) {\n    return `# What's new\\n\\nNo stable release sections were found. Try \\`/changelog\\` for the interactive changelog viewer.\\n\\n─────────────────────────────────────────────────────────────────\\n\\nWhere to next:\\n\\n\\`/atomic example\\` — see a practical first workflow\\n\\`/atomic overview\\` — quick refresh`;\n  }\n\n  const relativePath = path.relative(cwd, changelogPath) || changelogPath;\n  return `# What's new\\n\\n${stableSections.join(\"\\n\\n\")}\\n\\nSource: \\`${relativePath}\\`\\n\\n─────────────────────────────────────────────────────────────────\\n\\nWhere to next:\\n\\n\\`/atomic example\\` — see a practical first workflow\\n\\`/atomic overview\\` — quick refresh`;\n}\n\nexport function getAtomicGuideMessage(\n  mode: AtomicGuideMode,\n  cwd: string,\n): string {\n  if (mode === \"help\") return getAtomicGuideHelpMenu();\n  return getGuideSectionForMode(mode).render(cwd);\n}\n\nexport function atomicGuideModeForChoice(\n  choice: AtomicGuideHelpChoice,\n): AtomicGuideMode {\n  return getGuideSectionForChoice(choice)?.name ?? \"help\";\n}\n"]}

package/docs/models.md

@@ -4,6 +4,8 @@ Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.atomi
 
 Built-in subscription providers such as Cursor (experimental) are selected with the same `provider/model` syntax, for example `cursor/composer-2`. Cursor image input is scoped to known multimodal Cursor Claude, Composer, Gemini, GPT, and Kimi model families (`claude-`, `composer-`, `gemini-`, `gpt-`, `kimi-`), plus `grok-4.3`; text-only Cursor models still reject images. Cursor image payloads must be non-empty standard base64, with MIME-style line wrapping whitespace accepted and stripped before serialization. Live private-API model metadata may fall back to estimated labels. Because Cursor support targets undocumented private endpoints with Cursor CLI-compatible headers, maintainers and users should explicitly accept the risk that it may conflict with Cursor's terms, break without notice, or affect the Cursor account used to authenticate.
 
+When Cursor omits token limits, Atomic derives them from its bundled `@earendil-works/pi-ai` model catalog and treats explicit `1M` Cursor labels as a 1,000,000-token context floor; unmatched Cursor-only models keep conservative estimates instead of disappearing from `/model`.
+
 ## Table of Contents
 
 - [Minimal Example](#minimal-example)

package/docs/providers.md

@@ -46,7 +46,7 @@ Anthropic subscription auth is active for Claude Pro/Max accounts. Third-party h
 
 ### Cursor (experimental)
 
-Cursor support is bundled as the first-party `@bastani/cursor` extension and appears in `/login` as **Cursor (experimental)**. It uses Cursor's browser PKCE flow and stores OAuth credentials in `~/.atomic/agent/auth.json`; do not paste Cursor tokens into environment variables, command-line arguments, or custom proxies. Atomic identifies as a Cursor CLI-compatible client against private endpoints; maintainers and users should explicitly accept that this may conflict with Cursor's terms of service, stop working without notice, or affect the Cursor account used to authenticate.
+Cursor support is bundled as the first-party `@bastani/cursor` extension and appears in `/login` as **Cursor (Experimental)**. It uses Cursor's browser PKCE flow and stores OAuth credentials in `~/.atomic/agent/auth.json`; do not paste Cursor tokens into environment variables, command-line arguments, or custom proxies. Atomic identifies as a Cursor CLI-compatible client against private endpoints; maintainers and users should explicitly accept that this may conflict with Cursor's terms of service, stop working without notice, or affect the Cursor account used to authenticate.
 
 Current limitations:
 
@@ -54,6 +54,8 @@ Current limitations:
 - Image input is supported only for known multimodal Cursor Claude, Composer, Gemini, GPT, and Kimi model families (IDs beginning `claude-`, `composer-`, `gemini-`, `gpt-`, or `kimi-`), plus `grok-4.3`. Text-only Cursor models still reject images with a clear error.
 - For image-capable Cursor models, Atomic serializes user images and mixed text/image MCP tool results into Cursor's private request format. Image payloads must be non-empty standard base64; MIME-style line wrapping whitespace is accepted and stripped before serialization.
 - Model metadata is cached token-free in `~/.atomic/agent/cursor-model-catalog.json` and can be used at startup before fresh credentials are available. Estimated labels are used only when no valid cache exists and allowed live `GetUsableModels` discovery failures occur; refresh-time discovery is best-effort so rotated credentials are still persisted.
+- Cursor's private model discovery does not return token-limit metadata. Atomic preserves any positive limits Cursor does send, then resolves a model's context window and max output tokens from its bundled `@earendil-works/pi-ai` model catalog by matching the Cursor model ID's family/version. Explicit `1M` Cursor ids or labels on any fast/thinking sibling for the same family are treated as a 1,000,000-token context floor even when the closest reference match advertises a smaller base window. Cursor-only models with no pi-ai match (for example `composer-*` and `default`/Auto) keep a conservative 200k context / 64k output estimate. This only sets limits; it never changes which Cursor models are listed.
+- Cursor thinking levels are derived from the discovered Cursor variants for each model group. Atomic only exposes `xhigh` when Cursor advertises a true `xhigh` or `max` variant for that group; if an older saved `xhigh` selection is restored for a model that currently only has lower-effort variants, the request falls back to the nearest concrete Cursor variant instead of sending an invalid id.
 - The implementation avoids a localhost proxy and keeps credentials OAuth-only. Cursor's HTTP/2 transport uses the bundled `@bastani/atomic-natives` Rust/N-API client, so it does not require Node.js on `PATH`. The native client currently opens request-scoped HTTP/2 sessions; pooling may be added in a future release.
 - Cursor request encoding intentionally omits a `previousWorkspaceUris` current-directory entry by default so local absolute working-directory paths are not sent as workspace context. HTTP/2 Connect request/framing code is isolated, buffered across arbitrary chunks, tested with injected fakes, and uses a minimal production protobuf codec with field-order-independent exec ids, protobuf `Value` plus raw UTF-8/JSON tool arguments, historical tool-result correlation, checkpoint token-details parsing, paused-stream abort/idle cleanup, catalog-aware fast/thinking model grouping, and credential/PKCE-redacted protocol errors.
 

package/docs/quickstart.md

@@ -82,7 +82,9 @@ See [Providers](/providers) for all supported providers, environment variables,
 
 On a fresh install with no prior Atomic startup state, Atomic starts with a first-run workflow prompt. Returning users with prior startup state are marked onboarded automatically and continue directly into the normal chat UI; stored credentials by themselves do not skip onboarding. Paste a ticket description, GitHub issue, path to a spec, or task prompt and Atomic hands it to the normal coding-agent session. The handoff raises the selected model to high reasoning when supported and first asks the parent agent to estimate scope from the seed text alone: tickets, issues, and especially specs often list enough work items, files, tests, docs, migrations, or acceptance criteria to classify likely size without immediately inspecting the repo. That text-only pass is treated as a routing confidence signal, not final planning. If the task is clearly tiny/small and high-confidence, the parent can route directly; if the seed references context that must be read or the scope is medium, large, unclear, or risky, it inspects only the necessary issue/spec/path/repo area and can use targeted read-only subagents such as `codebase-locator`, `codebase-analyzer`, and `codebase-pattern-finder` at their normal defaults. It then chooses `goal` for focused work or `ralph` for broader/riskier work, starts the selected workflow, and continues normally. If you paste the task before logging in or selecting a usable model, Atomic keeps only an in-memory copy, asks you to run `/login`, and resumes with the latest saved task after login or `/model` selection makes the session ready; `/new` starts a fresh unresolved onboarding session and drops that saved in-memory task. If you want normal chat instead, type `/chat` or `/chat <message>`; other slash commands such as `/login`, `/model`, and `/atomic` still work and do not dismiss onboarding.
 
-Once Atomic starts, the fastest way to get value is to kick off a built-in workflow or invoke a skill. Atomic turns repeatable engineering loops into executable stages with inspectable evidence instead of relying on a markdown checklist the model may or may not follow.
+Once Atomic starts, the fastest way to get value is to kick off a built-in workflow or invoke a skill. Workflows are the default path for non-trivial tasks and for requests with inherent structure plus a verifiable objective, including implementation, build, debugging, bug-fix, migration, new-feature, scoped multi-file, or docs/code-change work where validation matters. If a prompt says `do X until Y`, `repeat until`, `iterate until`, `review/fix until passing`, or `run checks and fix until green`, it already describes a workflow-shaped loop with a stop condition.
+
+Atomic turns repeatable engineering loops into executable stages with inspectable evidence instead of relying on a markdown checklist the model may or may not follow.
 
 For an interactive tour any time, run `/atomic` inside the TUI; `/atomic overview`, `/atomic workflows`, and `/atomic example` walk through the same flow in more depth.
 
@@ -93,8 +95,8 @@ Atomic ships with four workflows you can run immediately. Use `/workflow list` t
 | Workflow | When to use | Example |
 |---|---|---|
 | `deep-research-codebase` | Broad, cross-cutting research before you decide what to change. Scout → research-history → parallel specialist waves → aggregator. | `/workflow deep-research-codebase prompt="How do payment retries work end to end?"` |
-| `goal` | Bounded one-off changes when you already know the work surface, exact outcome, and validation — for example tests, lint/typecheck, docs builds, or observable behavior. Keeps the run focused with a goal ledger, reviewer gates, final status `complete`, `blocked`, or `needs_human`, and optional final-stage PR creation with `create_pr=true` after approval. | `/workflow goal objective="Update the CLI docs for --json, include one example, run the docs build, and finish when the build passes"` |
-| `ralph` | Planned or broad implementation work from a spec file, GitHub issue, or crisp ticket description. Ralph researches as needed, delegates implementation through sub-agents, reviews, records a QA proof video for UI/full-stack changes when practical, iterates, and optionally lets only the final stage attempt PR creation with `create_pr=true`. | `/workflow ralph prompt="Implement specs/2026-03-rate-limit.md and validate burst traffic returns 429"` |
+| `goal` | Bounded one-off changes when you already know the work surface, exact outcome, and validation — for example bug fixes, debugging, tests, lint/typecheck, docs builds, observable behavior, scoped multi-file edits, or a review/fix/test loop that should continue until passing. Keeps the run focused with a goal ledger, reviewer gates, final status `complete`, `blocked`, or `needs_human`, and optional final-stage PR creation with `create_pr=true` after approval. | `/workflow goal objective="Update the CLI docs for --json, include one example, run the docs build, and finish when the build passes"` |
+| `ralph` | Planned or broad implementation work from a spec file, GitHub issue, or crisp ticket description, including migrations and new features. Ralph researches as needed, delegates implementation through sub-agents, reviews, records a QA proof video for UI/full-stack changes when practical, iterates until approval or the loop limit, and optionally lets only the final stage attempt PR creation with `create_pr=true`. | `/workflow ralph prompt="Implement specs/2026-03-rate-limit.md and validate burst traffic returns 429"` |
 | `open-claude-design` | UI and design-system work with separate forked generate and feedback chains; renders a live `preview.html` you can iterate against. | `/workflow open-claude-design prompt="Refresh the settings page hierarchy as a page"` |
 
 <p align="center"><img src="images/workflow-list.png" alt="Workflow List" width="600" /></p>
@@ -115,7 +117,7 @@ Atomic picks the workflow, fills in inputs from the request, and confirms before
 
 For planned work, make `ralph` the default implementation loop after research or spec creation. Give it a spec file, GitHub issue, or crisp ticket description; it refines the prompt, researches as needed, delegates implementation, reviews, records a QA proof video for UI/full-stack changes when practical, and iterates. Add `create_pr=true` only when you want the final PR handoff after the review gate approves.
 
-For smaller one-off tasks, use `goal` with a concrete task description that names the work surface, desired outcome, and validation. It 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 only the final PR handoff with `create_pr=true` after approval.
+For smaller one-off tasks, use `goal` with a concrete task description that names the work surface, desired outcome, and validation. It is the default for small-to-medium non-trivial changes with verifiable done criteria, especially bug fixes, debugging, scoped multi-file edits, and prompts that say to review/fix, test/fix, or iterate until passing. It 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 only the final PR handoff with `create_pr=true` after approval.
 
 ### Monitor and steer a run
 

package/docs/workflows.md

@@ -4,7 +4,9 @@
 
 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. 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.
+Default to a workflow for any non-trivial task, and for any task with inherent structure plus an objective you can make verifiable. Inherent structure includes implementation, build, debugging, bug-fix, migration, new-feature, scoped multi-file, or docs/code-change work where validation matters, plus multiple subtasks, dependencies, handoffs, review/validation gates, uncertainty, or an outcome that needs evidence. Loop-shaped requests are especially strong workflow signals: phrases such as `do X until Y`, `repeat until`, `iterate until`, `review/fix until passing`, `run checks and fix until green`, or `keep going until done` already describe a control loop plus a stop condition. 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.
+
+Use direct chat only for tiny, deterministic, low-risk work where workflow tracking would add more overhead than value, usually a clearly single-file/no-test/no-review edit or a simple answer.
 
 **Key capabilities:**
 - **Tracked stages** - Name each step and inspect it in workflow status and graph views
@@ -18,6 +20,7 @@ Use a workflow when a task should be repeatable, inspectable, resumable, or spli
 - **Package distribution** - Ship workflows through Atomic packages, settings, or conventional directories
 
 **Example use cases:**
+- Any non-trivial task with a clear objective and verifiable done criteria
 - Small, outcome-driven code or docs changes with explicit done criteria
 - Codebase research with parallel local and external research stages
 - Review/fix loops with independent reviewers and a synthesis stage
@@ -399,17 +402,19 @@ Prompt answers are replayable only while the source run remains in the live in-m
 
 ## When to Use Workflows
 
-Workflows are a good fit when you need:
+Workflows are the default path when a request is non-trivial, has inherent structure, and has an objective you can verify. Choose a workflow before direct chat when the prompt includes any of these signals:
 
-- named stages that appear in status and graph views
-- sequential or parallel work with explicit handoffs
+- implementation, build, debugging/diagnosis, bug-fix, migration, new-feature, scoped multi-file, or docs/code-change work where validation matters
+- multiple subtasks, dependencies, or handoffs
+- sequential or parallel work with explicit context handoffs
+- review, validation, QA, approval, or human-input gates
 - long-running or resumable background execution
-- human approval or missing information during a run
 - saved artifacts for later inspection
 - model fallback chains for important stages
 - reusable automation that can be launched again with different inputs
+- loop or stop-condition phrasing such as `do X until Y`, `repeat until`, `iterate until`, `review/fix until passing`, `run checks and fix until green`, or `keep going until done`
 
-If the task is only deterministic TypeScript with no LLM/session stage, use a script, custom tool, or extension command instead.
+Use direct chat instead only for tiny, deterministic, low-risk edits or answers where stage tracking would add more overhead than value, usually a clearly single-file/no-test/no-review edit. If the task is only deterministic TypeScript with no LLM/session stage, use a script, custom tool, or extension command instead.
 
 | User goal | Use |
 |-----------|-----|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.9.3-alpha.2",
+  "version": "0.9.3-alpha.4",
   "description": "Atomic coding agent CLI with read, bash, edit, write tools and session management",
   "type": "module",
   "atomicConfig": {
@@ -68,7 +68,7 @@
     "prepublishOnly": "bun run clean && bun run build"
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.9.3-alpha.2",
+    "@bastani/atomic-natives": "0.9.3-alpha.4",
     "@bufbuild/protobuf": "^2.0.0",
     "@earendil-works/pi-agent-core": "^0.79.10",
     "@earendil-works/pi-ai": "^0.79.10",