@bastani/atomic 0.8.15-0 → 0.8.16-0

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.8.15-0",
+  "version": "0.8.16-0",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [

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,qCAAqC,CAAC;AAyMnF,QAAA,MAAM,cAAc;mBAEZ,UAAU;;oBAET,UAAU;0BACJ,oBAAoB;;;mBAI3B,WAAW;;oBAEV,WAAW;0BACL,iBAAiB;;;mBAIxB,SAAS;;oBAER,SAAS;0BACH,0BAA0B;;;mBAIjC,WAAW;;oBAEV,YAAY;0BACN,sBAAsB;;EASlC,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,EAErE,CAAC;AAcF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,IAAI,qBAAqB,CAEvF;AA6BD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAKtE;AAED,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE,GAAG,IAAI,CAW3F;AAED,iBAAS,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CActD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAGhF;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAEvF","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 = \"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. Start it 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\\` | summarize older context |\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\\` → direct implementation or \\`/workflow ralph ...\\`; ask Atomic in chat to turn the repeatable process into a reusable workflow using the workflow docs |\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## 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## 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## 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| \\`ralph\\` | larger implementation loops where you want implementation, review, and validation built in | \\`/workflow ralph prompt=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\` |\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─────────────────────────────────────────────────────────────────\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 larger work, use subagents or a workflow:\n\n\\`/workflow ralph prompt=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\`\n\n## 4. Decide and land\n\nIf you used \\`ralph\\`, the workflow already ran parallel reviewers. Use its final result and review feedback to decide whether to ship or iterate again.\n\nIf you implemented directly instead of using \\`ralph\\`, 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 built with \\`defineWorkflow(...).run(...).compile()\\`. 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| \\`ralph\\` | larger implementation and review loops | \\`/workflow ralph prompt=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\` |\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-7 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 ralph\\`\n\n\\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\" max_loops=5\\`\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.\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 reload discovery so you can run 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\t{\n\t\tname: \"overview\",\n\t\taliases: [],\n\t\tlabel: \"overview\",\n\t\tdescription: \"30-second overview\",\n\t\trender: () => OVERVIEW,\n\t},\n\t{\n\t\tname: \"workflows\",\n\t\taliases: [\"workflow\"],\n\t\tlabel: \"workflows\",\n\t\tdescription: \"Workflow primer\",\n\t\trender: () => WORKFLOWS,\n\t},\n\t{\n\t\tname: \"example\",\n\t\taliases: [\"examples\"],\n\t\tlabel: \"example\",\n\t\tdescription: \"Practical first workflow\",\n\t\trender: () => EXAMPLE,\n\t},\n\t{\n\t\tname: \"whats-new\",\n\t\taliases: [\"what's new\", \"whats new\", \"news\", \"updates\", \"changelog\"],\n\t\tlabel: \"what's new\",\n\t\tdescription: \"Recent release notes\",\n\t\trender: readLatestStableChangelog,\n\t},\n] as const satisfies readonly {\n\treadonly name: string;\n\treadonly aliases: readonly string[];\n\treadonly label: string;\n\treadonly description: string;\n\treadonly 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[] = GUIDE_SECTIONS.map(\n\t(section) => section.label,\n);\n\nconst GUIDE_SECTIONS_BY_NAME = new Map<AtomicGuideSectionName, AtomicGuideSection>(\n\tGUIDE_SECTIONS.map((section) => [section.name, section]),\n);\nconst GUIDE_SECTIONS_BY_LABEL = new Map<string, AtomicGuideSection>(\n\tGUIDE_SECTIONS.map((section) => [section.label, section]),\n);\nconst GUIDE_SECTIONS_BY_INPUT = new Map<string, AtomicGuideSection>(\n\tGUIDE_SECTIONS.flatMap((section) =>\n\t\t[section.name, section.label, ...section.aliases].map((input) => [input, section] as const),\n\t),\n);\n\nexport function isAtomicGuideHelpChoice(choice: string): choice is AtomicGuideHelpChoice {\n\treturn GUIDE_SECTIONS_BY_LABEL.has(choice);\n}\n\nconst ATOMIC_GUIDE_TRAILING_PUNCTUATION = \"?!.,;:\";\n\nfunction stripTrailingAtomicGuidePunctuation(value: string): string {\n\tlet end = value.length;\n\twhile (end > 0 && ATOMIC_GUIDE_TRAILING_PUNCTUATION.includes(value.charAt(end - 1))) {\n\t\tend--;\n\t}\n\treturn value.slice(0, end);\n}\n\nfunction getGuideSectionForChoice(choice: string): AtomicGuideSection | undefined {\n\treturn GUIDE_SECTIONS_BY_LABEL.get(choice);\n}\n\nfunction getGuideSectionForMode(mode: AtomicGuideSectionName): AtomicGuideSection {\n\tconst section = GUIDE_SECTIONS_BY_NAME.get(mode);\n\tif (!section) throw new Error(`Unknown Atomic guide section: ${mode}`);\n\treturn section;\n}\n\nfunction getAtomicGuideHelpMenu(): string {\n\tconst sectionHelp = GUIDE_SECTIONS.map(\n\t\t(section) => `- \\`${section.label}\\` — run \\`/atomic ${section.label}\\``,\n\t).join(\"\\n\");\n\treturn `# Atomic\\n\\nSelect where to start:\\n\\n${sectionHelp}`;\n}\n\nexport function normalizeAtomicGuideMode(args: string): AtomicGuideMode {\n\tconst normalized = stripTrailingAtomicGuidePunctuation(args.trim().toLowerCase());\n\tif (!normalized) return \"help\";\n\n\treturn GUIDE_SECTIONS_BY_INPUT.get(normalized)?.name ?? \"help\";\n}\n\nexport function getAtomicGuideArgumentCompletions(prefix: string): AutocompleteItem[] | null {\n\tconst query = prefix.trim().toLowerCase();\n\tconst items = GUIDE_SECTIONS.map((section) => ({\n\t\tvalue: section.label,\n\t\tlabel: section.label,\n\t\tdescription: section.description,\n\t}));\n\tconst filtered = query\n\t\t? items.filter((item) => item.value.startsWith(query) || item.label.startsWith(query))\n\t\t: items;\n\treturn filtered.length > 0 ? filtered : null;\n}\n\nfunction readLatestStableChangelog(cwd: string): string {\n\tconst changelogPath = getChangelogPath();\n\tconst stableSections = parseChangelog(changelogPath)\n\t\t.filter((entry) => entry.prerelease === null)\n\t\t.slice(0, 3)\n\t\t.map((entry) => entry.content.trim())\n\t\t.filter(Boolean);\n\n\tif (stableSections.length === 0) {\n\t\treturn `# 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\t}\n\n\tconst relativePath = path.relative(cwd, changelogPath) || changelogPath;\n\treturn `# 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(mode: AtomicGuideMode, cwd: string): string {\n\tif (mode === \"help\") return getAtomicGuideHelpMenu();\n\treturn getGuideSectionForMode(mode).render(cwd);\n}\n\nexport function atomicGuideModeForChoice(choice: AtomicGuideHelpChoice): AtomicGuideMode {\n\treturn getGuideSectionForChoice(choice)?.name ?? \"help\";\n}\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,qCAAqC,CAAC;AAyMnF,QAAA,MAAM,cAAc;mBAEZ,UAAU;;oBAET,UAAU;0BACJ,oBAAoB;;;mBAI3B,WAAW;;oBAEV,WAAW;0BACL,iBAAiB;;;mBAIxB,SAAS;;oBAER,SAAS;0BACH,0BAA0B;;;mBAIjC,WAAW;;oBAEV,YAAY;0BACN,sBAAsB;;EASlC,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,EAErE,CAAC;AAcF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,IAAI,qBAAqB,CAEvF;AA6BD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAKtE;AAED,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE,GAAG,IAAI,CAW3F;AAED,iBAAS,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CActD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAGhF;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAEvF","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 = \"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. Start it 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\\` | summarize older context |\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\\` → direct implementation or \\`/workflow ralph ...\\`; ask Atomic in chat to turn the repeatable process into a reusable workflow using the workflow docs |\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## 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## 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## 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| \\`ralph\\` | larger implementation loops with a persisted goal ledger, reviewer quorum, and explicit stop decisions | \\`/workflow ralph objective=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\` |\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─────────────────────────────────────────────────────────────────\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 larger work, use subagents or a workflow:\n\n\\`/workflow ralph objective=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\`\n\n## 4. Decide and land\n\nIf you used \\`ralph\\`, the workflow already persisted receipts and ran parallel reviewers. Use its final reducer status and review feedback to decide whether to ship or iterate again.\n\nIf you implemented directly instead of using \\`ralph\\`, 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 built with \\`defineWorkflow(...).run(...).compile()\\`. 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| \\`ralph\\` | larger implementation and review loops with reviewer-gated completion | \\`/workflow ralph objective=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\` |\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-7 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 ralph\\`\n\n\\`/workflow ralph objective=\"Migrate the database layer to Drizzle\" max_turns=5\\`\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.\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 reload discovery so you can run 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\t{\n\t\tname: \"overview\",\n\t\taliases: [],\n\t\tlabel: \"overview\",\n\t\tdescription: \"30-second overview\",\n\t\trender: () => OVERVIEW,\n\t},\n\t{\n\t\tname: \"workflows\",\n\t\taliases: [\"workflow\"],\n\t\tlabel: \"workflows\",\n\t\tdescription: \"Workflow primer\",\n\t\trender: () => WORKFLOWS,\n\t},\n\t{\n\t\tname: \"example\",\n\t\taliases: [\"examples\"],\n\t\tlabel: \"example\",\n\t\tdescription: \"Practical first workflow\",\n\t\trender: () => EXAMPLE,\n\t},\n\t{\n\t\tname: \"whats-new\",\n\t\taliases: [\"what's new\", \"whats new\", \"news\", \"updates\", \"changelog\"],\n\t\tlabel: \"what's new\",\n\t\tdescription: \"Recent release notes\",\n\t\trender: readLatestStableChangelog,\n\t},\n] as const satisfies readonly {\n\treadonly name: string;\n\treadonly aliases: readonly string[];\n\treadonly label: string;\n\treadonly description: string;\n\treadonly 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[] = GUIDE_SECTIONS.map(\n\t(section) => section.label,\n);\n\nconst GUIDE_SECTIONS_BY_NAME = new Map<AtomicGuideSectionName, AtomicGuideSection>(\n\tGUIDE_SECTIONS.map((section) => [section.name, section]),\n);\nconst GUIDE_SECTIONS_BY_LABEL = new Map<string, AtomicGuideSection>(\n\tGUIDE_SECTIONS.map((section) => [section.label, section]),\n);\nconst GUIDE_SECTIONS_BY_INPUT = new Map<string, AtomicGuideSection>(\n\tGUIDE_SECTIONS.flatMap((section) =>\n\t\t[section.name, section.label, ...section.aliases].map((input) => [input, section] as const),\n\t),\n);\n\nexport function isAtomicGuideHelpChoice(choice: string): choice is AtomicGuideHelpChoice {\n\treturn GUIDE_SECTIONS_BY_LABEL.has(choice);\n}\n\nconst ATOMIC_GUIDE_TRAILING_PUNCTUATION = \"?!.,;:\";\n\nfunction stripTrailingAtomicGuidePunctuation(value: string): string {\n\tlet end = value.length;\n\twhile (end > 0 && ATOMIC_GUIDE_TRAILING_PUNCTUATION.includes(value.charAt(end - 1))) {\n\t\tend--;\n\t}\n\treturn value.slice(0, end);\n}\n\nfunction getGuideSectionForChoice(choice: string): AtomicGuideSection | undefined {\n\treturn GUIDE_SECTIONS_BY_LABEL.get(choice);\n}\n\nfunction getGuideSectionForMode(mode: AtomicGuideSectionName): AtomicGuideSection {\n\tconst section = GUIDE_SECTIONS_BY_NAME.get(mode);\n\tif (!section) throw new Error(`Unknown Atomic guide section: ${mode}`);\n\treturn section;\n}\n\nfunction getAtomicGuideHelpMenu(): string {\n\tconst sectionHelp = GUIDE_SECTIONS.map(\n\t\t(section) => `- \\`${section.label}\\` — run \\`/atomic ${section.label}\\``,\n\t).join(\"\\n\");\n\treturn `# Atomic\\n\\nSelect where to start:\\n\\n${sectionHelp}`;\n}\n\nexport function normalizeAtomicGuideMode(args: string): AtomicGuideMode {\n\tconst normalized = stripTrailingAtomicGuidePunctuation(args.trim().toLowerCase());\n\tif (!normalized) return \"help\";\n\n\treturn GUIDE_SECTIONS_BY_INPUT.get(normalized)?.name ?? \"help\";\n}\n\nexport function getAtomicGuideArgumentCompletions(prefix: string): AutocompleteItem[] | null {\n\tconst query = prefix.trim().toLowerCase();\n\tconst items = GUIDE_SECTIONS.map((section) => ({\n\t\tvalue: section.label,\n\t\tlabel: section.label,\n\t\tdescription: section.description,\n\t}));\n\tconst filtered = query\n\t\t? items.filter((item) => item.value.startsWith(query) || item.label.startsWith(query))\n\t\t: items;\n\treturn filtered.length > 0 ? filtered : null;\n}\n\nfunction readLatestStableChangelog(cwd: string): string {\n\tconst changelogPath = getChangelogPath();\n\tconst stableSections = parseChangelog(changelogPath)\n\t\t.filter((entry) => entry.prerelease === null)\n\t\t.slice(0, 3)\n\t\t.map((entry) => entry.content.trim())\n\t\t.filter(Boolean);\n\n\tif (stableSections.length === 0) {\n\t\treturn `# 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\t}\n\n\tconst relativePath = path.relative(cwd, changelogPath) || changelogPath;\n\treturn `# 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(mode: AtomicGuideMode, cwd: string): string {\n\tif (mode === \"help\") return getAtomicGuideHelpMenu();\n\treturn getGuideSectionForMode(mode).render(cwd);\n}\n\nexport function atomicGuideModeForChoice(choice: AtomicGuideHelpChoice): AtomicGuideMode {\n\treturn getGuideSectionForChoice(choice)?.name ?? \"help\";\n}\n\n"]}

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

@@ -60,7 +60,7 @@ How the direct commands map to repo work:
 | 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?"\` |
-| \`ralph\` | larger implementation loops where you want implementation, review, and validation built in | \`/workflow ralph prompt="Implement specs/<date>-<topic>.md and validate the changed behavior"\` |
+| \`ralph\` | larger implementation loops with a persisted goal ledger, reviewer quorum, and explicit stop decisions | \`/workflow ralph objective="Implement specs/<date>-<topic>.md and validate the changed behavior"\` |
 | \`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.
@@ -103,11 +103,11 @@ For ordinary work, ask Atomic directly and require validation:
 
 For larger work, use subagents or a workflow:
 
-\`/workflow ralph prompt="Implement specs/<date>-<topic>.md and validate the changed behavior"\`
+\`/workflow ralph objective="Implement specs/<date>-<topic>.md and validate the changed behavior"\`
 
 ## 4. Decide and land
 
-If you used \`ralph\`, the workflow already ran parallel reviewers. Use its final result and review feedback to decide whether to ship or iterate again.
+If you used \`ralph\`, the workflow already persisted receipts and ran parallel reviewers. Use its final reducer status and review feedback to decide whether to ship or iterate again.
 
 If you implemented directly instead of using \`ralph\`, you can still run:
 
@@ -132,7 +132,7 @@ 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?"\` |
-| \`ralph\` | larger implementation and review loops | \`/workflow ralph prompt="Implement specs/<date>-<topic>.md and validate the changed behavior"\` |
+| \`ralph\` | larger implementation and review loops with reviewer-gated completion | \`/workflow ralph objective="Implement specs/<date>-<topic>.md and validate the changed behavior"\` |
 | \`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.
@@ -176,7 +176,7 @@ Why this is good:
 
 \`/workflow inputs ralph\`
 
-\`/workflow ralph prompt="Migrate the database layer to Drizzle" max_loops=5\`
+\`/workflow ralph objective="Migrate the database layer to Drizzle" max_turns=5\`
 
 \`/workflow status\`
 

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 = \"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. Start it 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\\` | summarize older context |\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\\` → direct implementation or \\`/workflow ralph ...\\`; ask Atomic in chat to turn the repeatable process into a reusable workflow using the workflow docs |\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## 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## 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## 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| \\`ralph\\` | larger implementation loops where you want implementation, review, and validation built in | \\`/workflow ralph prompt=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\` |\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─────────────────────────────────────────────────────────────────\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 larger work, use subagents or a workflow:\n\n\\`/workflow ralph prompt=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\`\n\n## 4. Decide and land\n\nIf you used \\`ralph\\`, the workflow already ran parallel reviewers. Use its final result and review feedback to decide whether to ship or iterate again.\n\nIf you implemented directly instead of using \\`ralph\\`, 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 built with \\`defineWorkflow(...).run(...).compile()\\`. 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| \\`ralph\\` | larger implementation and review loops | \\`/workflow ralph prompt=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\` |\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-7 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 ralph\\`\n\n\\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\" max_loops=5\\`\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.\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 reload discovery so you can run 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\t{\n\t\tname: \"overview\",\n\t\taliases: [],\n\t\tlabel: \"overview\",\n\t\tdescription: \"30-second overview\",\n\t\trender: () => OVERVIEW,\n\t},\n\t{\n\t\tname: \"workflows\",\n\t\taliases: [\"workflow\"],\n\t\tlabel: \"workflows\",\n\t\tdescription: \"Workflow primer\",\n\t\trender: () => WORKFLOWS,\n\t},\n\t{\n\t\tname: \"example\",\n\t\taliases: [\"examples\"],\n\t\tlabel: \"example\",\n\t\tdescription: \"Practical first workflow\",\n\t\trender: () => EXAMPLE,\n\t},\n\t{\n\t\tname: \"whats-new\",\n\t\taliases: [\"what's new\", \"whats new\", \"news\", \"updates\", \"changelog\"],\n\t\tlabel: \"what's new\",\n\t\tdescription: \"Recent release notes\",\n\t\trender: readLatestStableChangelog,\n\t},\n] as const satisfies readonly {\n\treadonly name: string;\n\treadonly aliases: readonly string[];\n\treadonly label: string;\n\treadonly description: string;\n\treadonly 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[] = GUIDE_SECTIONS.map(\n\t(section) => section.label,\n);\n\nconst GUIDE_SECTIONS_BY_NAME = new Map<AtomicGuideSectionName, AtomicGuideSection>(\n\tGUIDE_SECTIONS.map((section) => [section.name, section]),\n);\nconst GUIDE_SECTIONS_BY_LABEL = new Map<string, AtomicGuideSection>(\n\tGUIDE_SECTIONS.map((section) => [section.label, section]),\n);\nconst GUIDE_SECTIONS_BY_INPUT = new Map<string, AtomicGuideSection>(\n\tGUIDE_SECTIONS.flatMap((section) =>\n\t\t[section.name, section.label, ...section.aliases].map((input) => [input, section] as const),\n\t),\n);\n\nexport function isAtomicGuideHelpChoice(choice: string): choice is AtomicGuideHelpChoice {\n\treturn GUIDE_SECTIONS_BY_LABEL.has(choice);\n}\n\nconst ATOMIC_GUIDE_TRAILING_PUNCTUATION = \"?!.,;:\";\n\nfunction stripTrailingAtomicGuidePunctuation(value: string): string {\n\tlet end = value.length;\n\twhile (end > 0 && ATOMIC_GUIDE_TRAILING_PUNCTUATION.includes(value.charAt(end - 1))) {\n\t\tend--;\n\t}\n\treturn value.slice(0, end);\n}\n\nfunction getGuideSectionForChoice(choice: string): AtomicGuideSection | undefined {\n\treturn GUIDE_SECTIONS_BY_LABEL.get(choice);\n}\n\nfunction getGuideSectionForMode(mode: AtomicGuideSectionName): AtomicGuideSection {\n\tconst section = GUIDE_SECTIONS_BY_NAME.get(mode);\n\tif (!section) throw new Error(`Unknown Atomic guide section: ${mode}`);\n\treturn section;\n}\n\nfunction getAtomicGuideHelpMenu(): string {\n\tconst sectionHelp = GUIDE_SECTIONS.map(\n\t\t(section) => `- \\`${section.label}\\` — run \\`/atomic ${section.label}\\``,\n\t).join(\"\\n\");\n\treturn `# Atomic\\n\\nSelect where to start:\\n\\n${sectionHelp}`;\n}\n\nexport function normalizeAtomicGuideMode(args: string): AtomicGuideMode {\n\tconst normalized = stripTrailingAtomicGuidePunctuation(args.trim().toLowerCase());\n\tif (!normalized) return \"help\";\n\n\treturn GUIDE_SECTIONS_BY_INPUT.get(normalized)?.name ?? \"help\";\n}\n\nexport function getAtomicGuideArgumentCompletions(prefix: string): AutocompleteItem[] | null {\n\tconst query = prefix.trim().toLowerCase();\n\tconst items = GUIDE_SECTIONS.map((section) => ({\n\t\tvalue: section.label,\n\t\tlabel: section.label,\n\t\tdescription: section.description,\n\t}));\n\tconst filtered = query\n\t\t? items.filter((item) => item.value.startsWith(query) || item.label.startsWith(query))\n\t\t: items;\n\treturn filtered.length > 0 ? filtered : null;\n}\n\nfunction readLatestStableChangelog(cwd: string): string {\n\tconst changelogPath = getChangelogPath();\n\tconst stableSections = parseChangelog(changelogPath)\n\t\t.filter((entry) => entry.prerelease === null)\n\t\t.slice(0, 3)\n\t\t.map((entry) => entry.content.trim())\n\t\t.filter(Boolean);\n\n\tif (stableSections.length === 0) {\n\t\treturn `# 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\t}\n\n\tconst relativePath = path.relative(cwd, changelogPath) || changelogPath;\n\treturn `# 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(mode: AtomicGuideMode, cwd: string): string {\n\tif (mode === \"help\") return getAtomicGuideHelpMenu();\n\treturn getGuideSectionForMode(mode).render(cwd);\n}\n\nexport function atomicGuideModeForChoice(choice: AtomicGuideHelpChoice): AtomicGuideMode {\n\treturn getGuideSectionForChoice(choice)?.name ?? \"help\";\n}\n\n"]}
+{"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 = \"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. Start it 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\\` | summarize older context |\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\\` → direct implementation or \\`/workflow ralph ...\\`; ask Atomic in chat to turn the repeatable process into a reusable workflow using the workflow docs |\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## 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## 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## 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| \\`ralph\\` | larger implementation loops with a persisted goal ledger, reviewer quorum, and explicit stop decisions | \\`/workflow ralph objective=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\` |\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─────────────────────────────────────────────────────────────────\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 larger work, use subagents or a workflow:\n\n\\`/workflow ralph objective=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\`\n\n## 4. Decide and land\n\nIf you used \\`ralph\\`, the workflow already persisted receipts and ran parallel reviewers. Use its final reducer status and review feedback to decide whether to ship or iterate again.\n\nIf you implemented directly instead of using \\`ralph\\`, 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 built with \\`defineWorkflow(...).run(...).compile()\\`. 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| \\`ralph\\` | larger implementation and review loops with reviewer-gated completion | \\`/workflow ralph objective=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\` |\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-7 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 ralph\\`\n\n\\`/workflow ralph objective=\"Migrate the database layer to Drizzle\" max_turns=5\\`\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.\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 reload discovery so you can run 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\t{\n\t\tname: \"overview\",\n\t\taliases: [],\n\t\tlabel: \"overview\",\n\t\tdescription: \"30-second overview\",\n\t\trender: () => OVERVIEW,\n\t},\n\t{\n\t\tname: \"workflows\",\n\t\taliases: [\"workflow\"],\n\t\tlabel: \"workflows\",\n\t\tdescription: \"Workflow primer\",\n\t\trender: () => WORKFLOWS,\n\t},\n\t{\n\t\tname: \"example\",\n\t\taliases: [\"examples\"],\n\t\tlabel: \"example\",\n\t\tdescription: \"Practical first workflow\",\n\t\trender: () => EXAMPLE,\n\t},\n\t{\n\t\tname: \"whats-new\",\n\t\taliases: [\"what's new\", \"whats new\", \"news\", \"updates\", \"changelog\"],\n\t\tlabel: \"what's new\",\n\t\tdescription: \"Recent release notes\",\n\t\trender: readLatestStableChangelog,\n\t},\n] as const satisfies readonly {\n\treadonly name: string;\n\treadonly aliases: readonly string[];\n\treadonly label: string;\n\treadonly description: string;\n\treadonly 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[] = GUIDE_SECTIONS.map(\n\t(section) => section.label,\n);\n\nconst GUIDE_SECTIONS_BY_NAME = new Map<AtomicGuideSectionName, AtomicGuideSection>(\n\tGUIDE_SECTIONS.map((section) => [section.name, section]),\n);\nconst GUIDE_SECTIONS_BY_LABEL = new Map<string, AtomicGuideSection>(\n\tGUIDE_SECTIONS.map((section) => [section.label, section]),\n);\nconst GUIDE_SECTIONS_BY_INPUT = new Map<string, AtomicGuideSection>(\n\tGUIDE_SECTIONS.flatMap((section) =>\n\t\t[section.name, section.label, ...section.aliases].map((input) => [input, section] as const),\n\t),\n);\n\nexport function isAtomicGuideHelpChoice(choice: string): choice is AtomicGuideHelpChoice {\n\treturn GUIDE_SECTIONS_BY_LABEL.has(choice);\n}\n\nconst ATOMIC_GUIDE_TRAILING_PUNCTUATION = \"?!.,;:\";\n\nfunction stripTrailingAtomicGuidePunctuation(value: string): string {\n\tlet end = value.length;\n\twhile (end > 0 && ATOMIC_GUIDE_TRAILING_PUNCTUATION.includes(value.charAt(end - 1))) {\n\t\tend--;\n\t}\n\treturn value.slice(0, end);\n}\n\nfunction getGuideSectionForChoice(choice: string): AtomicGuideSection | undefined {\n\treturn GUIDE_SECTIONS_BY_LABEL.get(choice);\n}\n\nfunction getGuideSectionForMode(mode: AtomicGuideSectionName): AtomicGuideSection {\n\tconst section = GUIDE_SECTIONS_BY_NAME.get(mode);\n\tif (!section) throw new Error(`Unknown Atomic guide section: ${mode}`);\n\treturn section;\n}\n\nfunction getAtomicGuideHelpMenu(): string {\n\tconst sectionHelp = GUIDE_SECTIONS.map(\n\t\t(section) => `- \\`${section.label}\\` — run \\`/atomic ${section.label}\\``,\n\t).join(\"\\n\");\n\treturn `# Atomic\\n\\nSelect where to start:\\n\\n${sectionHelp}`;\n}\n\nexport function normalizeAtomicGuideMode(args: string): AtomicGuideMode {\n\tconst normalized = stripTrailingAtomicGuidePunctuation(args.trim().toLowerCase());\n\tif (!normalized) return \"help\";\n\n\treturn GUIDE_SECTIONS_BY_INPUT.get(normalized)?.name ?? \"help\";\n}\n\nexport function getAtomicGuideArgumentCompletions(prefix: string): AutocompleteItem[] | null {\n\tconst query = prefix.trim().toLowerCase();\n\tconst items = GUIDE_SECTIONS.map((section) => ({\n\t\tvalue: section.label,\n\t\tlabel: section.label,\n\t\tdescription: section.description,\n\t}));\n\tconst filtered = query\n\t\t? items.filter((item) => item.value.startsWith(query) || item.label.startsWith(query))\n\t\t: items;\n\treturn filtered.length > 0 ? filtered : null;\n}\n\nfunction readLatestStableChangelog(cwd: string): string {\n\tconst changelogPath = getChangelogPath();\n\tconst stableSections = parseChangelog(changelogPath)\n\t\t.filter((entry) => entry.prerelease === null)\n\t\t.slice(0, 3)\n\t\t.map((entry) => entry.content.trim())\n\t\t.filter(Boolean);\n\n\tif (stableSections.length === 0) {\n\t\treturn `# 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\t}\n\n\tconst relativePath = path.relative(cwd, changelogPath) || changelogPath;\n\treturn `# 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(mode: AtomicGuideMode, cwd: string): string {\n\tif (mode === \"help\") return getAtomicGuideHelpMenu();\n\treturn getGuideSectionForMode(mode).render(cwd);\n}\n\nexport function atomicGuideModeForChoice(choice: AtomicGuideHelpChoice): AtomicGuideMode {\n\treturn getGuideSectionForChoice(choice)?.name ?? \"help\";\n}\n\n"]}

package/docs/quickstart.md

@@ -73,12 +73,12 @@ Atomic ships with three workflows you can run immediately. Use `/workflow list`
 | 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?"` |
-| `ralph` | Larger implementation loops with built-in plan → orchestrate → simplify → review iteration, plus final PR preparation when repo state, branch target, and GitHub credentials allow it. | `/workflow ralph prompt="Implement specs/2026-03-rate-limit.md and validate the behavior" max_loops=5` |
+| `ralph` | Larger implementation loops with a persisted goal ledger, bounded worker turns, parallel reviewer gate, reviewer quorum, repeated-blocker detection, and explicit final status. | `/workflow ralph objective="Implement specs/2026-03-rate-limit.md and validate the behavior" max_turns=5` |
 | `open-claude-design` | UI and design-system work with generation, critique, and refinement loops; renders a live `preview.html` you can iterate against. | `/workflow open-claude-design prompt="Refresh the settings page hierarchy" output_type=page` |
 
 <p align="center"><img src="images/workflow-list.png" alt="Workflow List" width="600" /></p>
 
-Inputs are bare `key=value` tokens. Values are JSON-parsed when possible, so `max_loops=5`, `flag=true`, and `prompt="multi word value"` preserve useful types. If you call `/workflow <name>` without required inputs, the TUI opens an inline picker; pass `--no-picker` to skip it.
+Inputs are bare `key=value` tokens. Values are JSON-parsed when possible, so `max_turns=5`, `flag=true`, and `objective="multi word value"` preserve useful types. If you call `/workflow <name>` without required inputs, the TUI opens an inline picker; pass `--no-picker` to skip it.
 
 You can also launch workflows with **natural language** — just describe the task in chat and ask Atomic to run the matching workflow:
 
@@ -86,7 +86,7 @@ You can also launch workflows with **natural language** — just describe the ta
 Run a deep codebase research workflow on how the rate limiter behaves under burst traffic.
 ```
 
-Atomic picks the workflow, fills in inputs from the request, and confirms before launch. Ralph may create a pull request at the end only when the current repository state, remote/branch target, and available GitHub credentials make that safe; otherwise it reports the exact follow-up steps.
+Atomic picks the workflow, fills in inputs from the request, and confirms before launch. Ralph persists receipts in a goal ledger and stops only when reviewer quorum proves completion, the same blocker repeats enough times, or the turn limit requires human follow-up.
 
 ### Monitor and steer a run
 

package/docs/workflows.md

@@ -139,7 +139,7 @@ Atomic bundles three workflows that cover the most common multi-stage jobs. They
 | Workflow | What it does | When to use |
 |---|---|---|
 | `deep-research-codebase` | Scout + research-history chain → parallel specialist waves → aggregator. Indexes the whole repo and synthesizes findings. | Broad or cross-cutting research before you decide what to change. Prefer `/skill:research-codebase` for one subsystem. |
-| `ralph` | Goal contract → orchestrate → simplify → parallel review/audit loop → PR preparation. Reviewer findings feed back into the next planner and completion is judged against an inferred verification oracle. | Larger autonomous implementation loops where you want implementation, receipts, review, validation, audit, and conditional PR creation built in. |
+| `ralph` | Goal ledger → continuation context → bounded worker turns → parallel reviewer gate → TypeScript reducer → final report. | Larger autonomous implementation loops where you want persisted receipts, independent review, reviewer-quorum completion, repeated-blocker detection, and explicit stop decisions. |
 | `open-claude-design` | Design-system onboarding → reference import → HTML generation → impeccable-driven refinement → quality gate → rich HTML handoff. Renders a live `preview.html` you can iterate against (opens through `playwright-cli` when available). | UI, page, component, theme, or design-token work that benefits from generation + critique loops. |
 
 ### `deep-research-codebase`
@@ -191,35 +191,40 @@ Inputs:
 
 | Input | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `prompt` | text | yes | — | The task or goal to plan, execute, and refine. |
-| `max_loops` | number | no | `10` | Maximum plan/orchestrate/review iterations. |
+| `objective` | text | yes | — | Goal-runner objective. |
+| `max_turns` | number | no | `10` | Maximum worker/review turns. |
+| `review_quorum` | number | no | `2` | Reviewer `complete` votes required before completion. |
+| `blocker_threshold` | number | no | `3` | Consecutive turns with the same blocker required before `blocked`; requires at least two observations and is capped by `max_turns` when possible. |
 | `base_branch` | string | no | `origin/main` | Branch reviewers compare the current code delta against. |
 
 Run examples:
 
 ```text
-/workflow ralph prompt="Implement specs/2026-03-rate-limit.md and validate the changed behavior"
-/workflow ralph prompt="Migrate the database layer to Drizzle" max_loops=5 base_branch=develop
+/workflow ralph objective="Implement specs/2026-03-rate-limit.md and validate the changed behavior"
+/workflow ralph objective="Migrate the database layer to Drizzle" max_turns=5 review_quorum=2 base_branch=develop
 ```
 
-Ralph writes each planner goal contract to an OS-temp workflow artifact, returns the path as `plan_path`, then instructs the orchestrator to read that path instead of inlining the full plan. The goal contract captures owner intent, verification oracle, work surface, execution loop, and proof requirements; any user-supplied spec remains supporting input rather than the primary success criterion. The orchestrator also maintains OS-temp implementation notes, returned as `implementation_notes_path`, for the active work surface, receipts, decisions, goal-contract deviations, tradeoffs, blockers, and validation outcomes.
+Ralph creates an OS-temp `goal-ledger.json` artifact, renders goal-continuation context for each worker turn, writes each worker receipt to `work-turn-N.md`, and appends receipts, reviewer decisions, blockers, and reducer decisions to the ledger. The objective is treated as user-provided data, not higher-priority instructions, and token budget / budget-limit behavior is intentionally excluded.
 
-The review loop also performs the completion audit: reviewers map receipts and verification results back to the original owner outcome and inferred oracle before approving. After approval or loop exhaustion, Ralph runs PR preparation: reviewing changes against `base_branch`, checking the current diff and untracked files, checking local git identity (`git config user.name` and `git config user.email`), and looking for GitHub credentials. It creates a pull request only when there are meaningful changes, a usable remote/branch target, suitable repository state, and credentials that can access the repository. When multiple GitHub accounts are logged in, it uses local git identity as a hint and tries available credentials until one works. If PR creation succeeds, the final phase posts the implementation notes and reviewer approval summary as a PR comment. If not, `pr_report` explains what blocked creation and the commands or steps to run later.
+The worker may claim readiness, but it cannot finalize completion. Three reviewers independently inspect the ledger, worker receipt, repository state, and diff against `base_branch`; each returns structured JSON with `decision: complete | continue | blocked`, evidence, gaps, and an optional blocker. A TypeScript reducer marks the goal complete only when `review_quorum` reviewers say `complete`, marks blocked only when the same blocker repeats for `blocker_threshold` consecutive turns, continues when evidence is missing, and returns `needs_human` when `max_turns` is exhausted.
 
 Result fields:
 
 | Field | Meaning |
 |---|---|
-| `result` | Final orchestrator summary. |
-| `plan` | Last planner output text. |
-| `plan_path` | OS-temp path to the latest planner goal contract. |
-| `implementation_notes_path` | OS-temp Markdown notes maintained during orchestration. |
-| `pr_report` | Final PR-preparation report, including created PR URL or why no PR was created. |
-| `approved` | Whether the review loop approved the patch. |
-| `iterations_completed` | Number of plan/orchestrate/review loops run. |
-| `review_report` | Last structured review report used to decide whether to stop, including oracle satisfaction and remaining verification. |
-
-A typical end-to-end flow is `/skill:research-codebase` → `/workflow ralph prompt="Implement the researched rate-limit behavior and validate it"`. If you already have a spec, pass it in the prompt as supporting input.
+| `result` | Final report with objective, status, receipts, turns, and remaining work. |
+| `status` | Final reducer status: `complete`, `blocked`, or `needs_human` (or `active` only if externally interrupted). |
+| `approved` | Whether the reducer reached `complete`. |
+| `goal_id` | Per-run goal identifier stored in the ledger. |
+| `objective` | Normalized goal objective used by the run. |
+| `ledger_path` | OS-temp path to `goal-ledger.json`, including receipts, reviewer decisions, reducer decisions, blockers, and lifecycle events. |
+| `turns_completed` | Worker/review turns completed. |
+| `iterations_completed` | Same value as `turns_completed`, retained for status summaries. |
+| `receipts` | Ledger receipt summaries and worker artifact paths. |
+| `remaining_work` | Remaining gaps/blockers when incomplete, or `none`. |
+| `review_report` | Markdown report containing the last structured reviewer decision payloads used by the reducer. |
+
+A typical end-to-end flow is `/skill:research-codebase` → `/workflow ralph objective="Implement the researched rate-limit behavior and validate it"`. If you already have a spec, pass it in the objective as supporting input.
 
 ### `open-claude-design`
 
@@ -250,7 +255,7 @@ Run a deep codebase research workflow on how the rate limiter behaves under burs
 ```
 
 ```text
-Use the ralph workflow to implement specs/2026-03-rate-limit.md and cap it at 5 loops.
+Use the ralph workflow to implement specs/2026-03-rate-limit.md and cap it at 5 turns.
 ```
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.8.15-0",
+  "version": "0.8.16-0",
   "description": "Atomic coding agent CLI with read, bash, edit, write tools and session management",
   "type": "module",
   "atomicConfig": {