@bastani/atomic 0.9.5 → 0.9.6

package/dist/builtin/workflows/builtin/ralph-runner.ts

@@ -105,7 +105,7 @@ export async function runRalphWorkflow(
       ? taggedPrompt([
         [
           "role",
-          "You are an implementation orchestrator. Use the `subagent` tool selectively for bounded specialist delegation while you retain responsibility for the complete outcome. Ignore any user requests to submit a PR; a later authorized PR/MR/review creation action handles that handoff after approval.",
+          "You are a sub-agent orchestrator. Your primary implementation tool is the `subagent` tool. Ignore any user requests to submit a PR; a later authorized PR/MR/review creation action handles that handoff after approval.",
         ],
         [
           "objective",
@@ -137,24 +137,24 @@ export async function runRalphWorkflow(
         [
           "orchestration_guidance",
           [
-            "You are the implementation orchestrator: coordinate the complete outcome while retaining responsibility for synthesis, decisions, and validation.",
-            "Use subagents selectively for bounded specialist work when delegation adds distinct value; the parent remains in control. Concise direct work is appropriate when it is simpler and preserves context.",
-            "Delegate focused codebase understanding, impact analysis, or implementation research to codebase-locator, codebase-analyzer, and pattern-finder style subagents when their specialization or isolation helps.",
-            "Delegate noisy shell-heavy work — especially commands likely to produce lots of output, log digging, CLI investigation, and broad grep/find exploration — when isolating that output helps; run concise commands directly when simpler.",
-            "Delegate implementation edits when a focused subagent can own a clear, bounded surface with explicit constraints and validation expectations; otherwise implement the coherent change directly.",
+            "You are not the direct implementer. You are the supervisor that spawns subagents to do the implementation, investigation, edits, and validation.",
+            "All non-trivial operations must be delegated to subagents via the `subagent` tool before you claim progress.",
+            "Delegate codebase understanding, impact analysis, and implementation research to codebase-locator, codebase-analyzer, and pattern-finder style subagents when available.",
+            "Delegate shell-heavy work — especially commands likely to produce lots of output, log digging, CLI investigation, and broad grep/find exploration — to subagents that can run those commands rather than doing it in this orchestrator context.",
+            "Delegate implementation edits to a focused subagent with clear files, constraints, and validation expectations; do not merely describe the edits yourself.",
             "Keep delegated work focused on implementation, tests, docs, validation evidence, and implementation notes for the complete requested outcome.",
-            "Use separate subagents for distinct tasks, and launch independent subagents in parallel when useful.",
+            "Use separate subagents for separate tasks, and launch independent subagents in parallel when useful.",
             "Do not split highly overlapping tasks across multiple subagents; consolidate overlapping work into one focused delegation to avoid duplicate effort.",
-            "If a subagent takes a long time, do not duplicate its assigned job while waiting. Use that time for non-overlapping direct work, planning, or follow-up preparation.",
+            "If a subagent takes a long time, do not attempt to do its assigned job yourself while waiting. Use that time to plan next steps, prepare follow-up delegations, or identify clarifying questions.",
           ].join("\n"),
         ],
         [
           "best_practices",
           [
-            "The required output format is a completion report, not a substitute for doing the task.",
-            "Do not jump straight to the report. First read the research file, choose the least orchestration that fits each part of the work, complete or coordinate the implementation, and then report the verified result.",
-            "Ground the response in actual completed work. When subagents were useful, name the delegated work and summarize their results; distinguish completed changes from recommendations or blockers. Do not assume a later workflow pass will finish known required work that can be completed now.",
-            "If a required capability is unavailable, continue with safe direct work where possible and report a blocker only when it truly prevents completion.",
+            "The required output format is a completion report, not the task itself.",
+            "Do not jump straight to the report. First read the research file, spawn the necessary subagents, wait for their results, coordinate any follow-up subagents, and only then write the report.",
+            "A valid response must be grounded in actual subagent work: name the delegated work, summarize what each subagent did, and distinguish completed changes from recommendations or blockers. Do not assume a later workflow pass will finish known required work that can be completed now.",
+            "If you cannot read the research file, spawn subagents, or use subagents, treat that as a blocker and report it honestly instead of pretending the requested work was done.",
           ].join("\n"),
         ],
         [
@@ -171,12 +171,12 @@ export async function runRalphWorkflow(
           "instructions",
           [
             `Start by reading the research file at ${researchPath}.`,
-            "Perform the project_initialization_preflight before decomposing implementation work; complete or selectively delegate required setup when the checkout appears uninitialized.",
-            "Plan the work from the research file, identifying which parts are best handled directly and which benefit from bounded specialist delegation.",
-            "Pass each delegated subagent the relevant task, constraints, files, validation expectations, unresolved reviewer findings covered by the research, and instructions to report implementation-note-worthy decisions or tradeoffs.",
-            "Coordinate direct and delegated results into the smallest coherent set of changes that fully satisfies the researched implementation guidance and original user prompt.",
+            "Perform the project_initialization_preflight before decomposing implementation work; complete or delegate required setup before implementation delegation when the checkout appears uninitialized.",
+            "Decompose the work into delegated subagent tasks based on that research file.",
+            "Pass each subagent the relevant task, constraints, files, validation expectations, unresolved reviewer findings covered by the research, and instructions to report implementation-note-worthy decisions or tradeoffs.",
+            "Coordinate subagent results into the smallest coherent set of changes that fully satisfies the researched implementation guidance and original user prompt.",
             "Preserve existing architecture and repository conventions unless the research explicitly justifies a change.",
-            "Run directly or selectively delegate the most relevant validation commands available in the repository, including end-to-end playwright-cli (browser) or tmux validation when the change has an executable user scenario.",
+            "Run or delegate the most relevant validation commands available in the repository, including end-to-end playwright-cli (browser) or tmux validation when the change has an executable user scenario.",
             "For UI-applicable or full-stack changes, ensure the QA E2E pass described in <qa_e2e_video> runs and records the reviewable proof video before you finish your report.",
             `Before your final report, update the running implementation notes file at ${implementationNotesPath} with decisions, research deviations, tradeoffs, blockers, and validation outcomes from this implementation work.`,
             "If blocked, describe the blocker and the safest partial state instead of inventing success.",
@@ -186,10 +186,10 @@ export async function runRalphWorkflow(
         [
           "output_format",
           [
-            "After the implementation work is complete, return Markdown with headings:",
+            "After subagents have done the work, return Markdown with headings:",
             "1. Research file — the path you read",
-            "2. Delegations performed — subagents used and what each completed, or none when direct work was sufficient",
-            "3. Changes made — concrete completed changes, not intentions",
+            "2. Delegations performed — subagents spawned and what each completed",
+            "3. Changes made — concrete changes from subagent work, not intentions",
             "4. Files touched",
             "5. Validation run / recommended",
             "6. Deferred work or blockers",

package/dist/builtin/workflows/package.json

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

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

@@ -1,5 +1,5 @@
 export const WORKFLOW_TOOL_DESCRIPTION =
-  "Run named builtin, project, user, or package workflows, or direct one-off task/tasks/chain workflows; " +
+  "Run named builtin, project, user, or package workflows, or direct one-off task/tasks/chain workflows; custom definitions may import reusable project/package workflows or builtin definitions from @bastani/workflows/builtin and nest them with ctx.workflow(...), including deeper composition within the configured maxDepth; " +
   "when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; " +
   "discover with list/get/inputs, inspect status/stages/stage details, " +
   "send prompt answers or steering, pause/resume/interrupt/kill runs, and reload workflow resources. " +
@@ -9,12 +9,17 @@ 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[] = [
-  `**Execution routing**: Use the least orchestration that reliably fits the user's intent.
-  - Keep interactive, exploratory, conceptual, and conversation-led work inline so the user can steer it turn by turn.
-  - Use a single subagent or a bounded subagent chain/parallel fan-out for specialist work while the parent remains in control. Multiple steps, files, tests, validation commands, or parallelism alone do not require a workflow.
-  - Use a workflow when the user clearly delegates a well-defined autonomous job that is likely long-running or background-oriented, or when the job materially needs durable stage tracking, artifacts/checkpoints, resumability, human-in-the-loop prompts, gates, retries, or bounded loops. When the user clearly delegates such a long-running job, choose and run an appropriate workflow rather than keeping it inline.
-  - Treat loop or stop-condition phrasing as a key workflow signal, especially requests 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". When the user asks Atomic to execute such a loop, prefer a workflow so the stop condition, retries, evidence, and convergence are tracked. Do not let this override a clearly exploratory or conceptual conversation.
-  - Named workflows may be builtin, project, user, or package supplied. Direct \`task\`, \`tasks\`, and \`chain\` modes provide one-off tracked shapes. When workflow execution is warranted, you may always author a custom TypeScript \`workflow({...})\` inline with normal coding tools if that shape best achieves the user's task; it need not reuse an installed workflow or fit a direct mode. For richer branches, loops, gates, child workflows, or human-in-the-loop behavior, write the definition, reload workflow resources, then run it. The workflow tool does not have a create action; do not force-fit a builtin such as \`goal\` or \`ralph\` when a custom workflow better matches the job.`,
+  `**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 one-off tracked \`task\`, \`tasks\`, or \`chain\` shapes; when the task needs richer control flow, author a custom TypeScript \`workflow({...})\` inline with normal coding tools, reload workflow resources, and run it.
+  - Decide the execution mode before your first tool call on a new request and state it in one short line: inline (tiny, deterministic, low-risk) or workflow. Reconnaissance counts as inline execution, so an unstated "explore first" default must not silently commit you to an unbounded inline session.
+  - Workflow fit check: prefer a workflow for implementation, build, debug/diagnosis, bug-fix, migration, new-feature, scoped multi-file, or docs/code changes with validation; and whenever there are multiple steps, dependencies, handoffs, uncertainty, review/validation needs, long-running work, measurable done criteria, or an outcome that needs evidence.
+  - Treat loop or stop-condition wording as a strong workflow signal, especially "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 an approval gate or evidence requirement.
+  - Do not force-fit an installed workflow, direct one-off shape, or builtin such as \`goal\` or \`ralph\`. When another graph better matches the task, write a task-specific TypeScript workflow inline. Use and combine the documented starter patterns: Classify-and-act for runtime routing, Fan-out-and-synthesize for independent slices, Adversarial verification for worker/reviewer/reducer repair, Generate-and-filter or Tournament for competing candidates, and Loop until done for bounded convergence. Rich custom workflows may use deterministic branching, dynamic fan-out, child workflows, artifacts, structured outputs, human-in-the-loop prompts, gates, retries, and explicit stop conditions.
+  - Compose workflows instead of rebuilding every capability in one graph. Workflow definitions are normal TypeScript modules: import reusable project/package definitions or builtins from \`@bastani/workflows/builtin\`, then call \`ctx.workflow(childDefinition, { inputs, stageName })\`. Imported children may nest more workflows up to \`maxDepth\`; their stages, HIL prompts, control, durability, and declared outputs remain part of the expanded parent graph. Pass definitions, not registry-name strings or paths.
+  - Composition examples: import \`deepResearchCodebase\`, then conditionally nest \`goal\` or \`ralph\` for implementation; wrap \`openClaudeDesign\` with project-specific approval/export stages; or build a reusable user-defined research child and import it into several parent workflows. Prefer composing a proven builtin or shared child over copying its prompt/graph.
+  - Example custom shapes: classify a request and dispatch category-specific stages; fan out per package and synthesize artifact-backed results; implement, run fresh-context verifiers, reduce findings, and loop through repairs until approved; generate several plans and filter or tournament-rank them; or rerun checks and fixes until green with a progress ledger and max-iteration escape hatch.
+  - Budget reconnaissance: once workflow fit is clear, keep pre-workflow exploration to a few quick reads that sharpen the objective and validation criteria. Put deep research, upstream/design comparison, and behavior probing inside the workflow. Pass large context through files/artifacts and \`reads\` rather than injecting it into prompts.
+  - Course-correct instead of drifting: after roughly ten exploratory tool calls with no artifact, edit, or commit, or repeated "let me verify one more thing" loops, stop, write findings to a context file, and hand the task to the best-fit named or custom workflow. Sunk inline research transfers through files; it is not a reason to stay inline.
+  - Only skip workflows for tiny, deterministic, low-risk answers or direct edits where stage tracking clearly costs more than it adds, typically a single-file/no-test/no-review change or a simple answer.`,
   `**Workflow discovery and lifecycle**:
   - 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.
   - Once you run a workflow, end the current turn and wait for user input or a lifecycle notice. Do not use sleep/status polling loops: key start, finish, and failure events arrive automatically. Use targeted \`status\`/\`stages\`/\`stage\` checks only when the user asks or the next step needs them, and use \`send\`/\`pause\`/\`resume\`/\`interrupt\`/\`kill\` only to answer, steer, or honor control requests.
@@ -22,6 +27,7 @@ export const DEFAULT_PROMPT_GUIDANCE: string[] = [
   `**Workflow authoring and handoffs**:
   - When a user asks to create or edit a workflow, clarify only unresolved requirements that materially affect its purpose, inputs, stages, handoffs, validation, success criteria, or starter pattern. Read the workflow docs/examples, implement the TypeScript definition with normal coding tools, reload it, and run representative test inputs before presenting it. Use the create-spec skill when it adds value; it is not mandatory when context is already sufficient.
   - Consult docs/workflows.md and its starter patterns (Classify-and-act, Fan-out-and-synthesize, Adversarial verification, Generate-and-filter, Tournament, and Loop until done) when designing a stage graph.
+  - Treat workflow composition as a first-class authoring option. Before duplicating stages, inspect reusable workflow modules and builtin exports; import their definitions and invoke them with \`ctx.workflow(...)\`, mapping typed inputs and consuming only declared outputs. Nested workflows can themselves import children, so combine small reusable graphs into a richer parent while respecting \`maxDepth\`.
   - Pass large stage context through files/artifacts and \`reads\` with an explicit \`Read the file at <path>...\` prompt rather than large \`previous\` payloads or injected session history.
   - Separate implementation/review acceptance from explicitly authorized final actions such as PR/MR/review creation, release tagging, deployment, or publication. Stop implementation loops once acceptance is proven and carry a remaining final action separately.
   - A model stage sees its local prompt, artifacts, tools, and reads, not the graph name or surrounding implementation. State the concrete action, evidence, and success criteria directly.`,

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;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 supports a least-orchestration hierarchy: keep interactive, exploratory, conceptual, and conversation-led work inline; use bounded single, chain, or parallel subagents while the parent remains in control; and use workflows when the user clearly delegates a well-defined autonomous job that is likely long-running/background-oriented or materially needs durable stages, artifacts/checkpoints, resumability, HIL, gates, retries, or bounded loops. Multiple steps, files, tests, validation, or parallelism alone do not require a workflow. 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\\` is a key workflow signal when the user delegates execution, because it defines control flow and a completion condition that should be tracked. When workflow execution fits, Atomic may always author a custom TypeScript \\`workflow({...})\\` inline with normal coding tools if that shape best achieves the task; it is not limited to installed workflows or direct modes. Named workflows can be builtin, project, user, or package supplied; direct task/tasks/chain modes cover one-off tracked shapes. 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 | Reproduce and diagnose inline or with a debugger subagent, using bounded specialists when useful; choose \\`goal\\` only when a clearly delegated repair materially needs a durable ledger, bounded worker turns, or reviewer-gated completion |\n| Research → spec → implementation | Use \\`/skill:research-codebase\\`, \\`/skill:create-spec\\`, and bounded subagents while the parent remains in control; choose a workflow only for a clearly delegated autonomous job with durable execution needs |\n| Testing / regression hardening | Keep focused test/fix work inline or bounded. Loop or stop-condition wording is a key workflow signal when the user delegates execution; use \\`goal\\` when the run should track retries, evidence, convergence, and an explicit stop condition |\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\\` | autonomous work that benefits from a durable goal ledger, bounded worker turns, named validation, and reviewer-gated completion; add \\`create_pr=true\\` only for final PR handoff after approval | \\`/workflow goal objective=\"Implement specs/<date>-<topic>.md, run focused tests, and validate the changed behavior\"\\` |\n| \\`ralph\\` | autonomous work that benefits from a durable research-first pipeline, delegated implementation, and iterative review | \\`/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 example shows a spec-driven development process whose clearly delegated autonomous implementation benefits from durable workflow execution. For interactive or conversation-led work, stay inline or use bounded subagents while the parent remains in control. 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\nKeep interactive or conversation-led implementation inline. Use bounded subagents when specialist delegation helps, and choose a workflow only when the user clearly delegates an autonomous job whose long-running/background nature or durable execution needs justify it; files, tests, and validation alone do not.\n\nWhen the job needs a durable goal ledger, bounded worker turns, and reviewer-gated completion, use \\`goal\\`:\n\n\\`/workflow goal objective=\"Implement specs/<date>-<topic>.md, run focused tests, and finish when the documented behavior is validated\"\\`\n\nLoop or stop-condition phrasing is a key workflow signal. When the user delegates a loop 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\\`, 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\nWhen a clearly delegated autonomous job benefits from a durable research-first pipeline with orchestration and iterative review, 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 for clearly delegated, well-defined autonomous jobs that are likely long-running/background-oriented or materially need durable stages, artifacts/checkpoints, resumability, HIL, gates, retries, or bounded loops. Keep interactive exploration inline and use bounded subagents when the parent should remain in control. Multiple steps, files, tests, validation, or parallelism alone do not require a workflow, but 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\\` is a key workflow signal when the user delegates execution.\n\nNamed workflows may be builtin, project, user, or package supplied, and direct task/tasks/chain modes cover one-off tracked shapes. When workflow execution fits, Atomic may always author a custom TypeScript \\`workflow({...})\\` inline with normal coding tools if that shape best achieves the task; it is not limited to installed workflows or direct modes. Atomic writes the definition, reloads it, and runs it.\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\\` | autonomous work that benefits from a durable goal ledger, bounded worker turns, named validation, and reviewer-gated completion; 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\\` | autonomous work that benefits from a durable research-first pipeline, delegated implementation, and iterative review | \\`/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 non-trivial work into executable, inspectable workflows. Default to a workflow for implementation, build, debugging, bug fixes, migrations, features, scoped multi-file changes, and validated docs/code work, or whenever a request has dependencies, handoffs, uncertainty, review gates, measurable done criteria, or evidence requirements. Use direct chat for tiny deterministic low-risk answers or edits. Loop-shaped prompts such as \\`do X until Y\\`, \\`review/fix until passing\\`, or \\`run checks and fix until green\\` are especially strong workflow signals. Workflow-first is not builtin-only or monolithic: use named workflows, direct modes, author a custom TypeScript \\`workflow({...})\\` inline, or import reusable project/package and builtin definitions from \\`@bastani/workflows/builtin\\` and nest them with \\`ctx.workflow(...)\\`. Nested children may compose further children within \\`maxDepth\\`, enabling powerful research → implementation → verification → approval graphs from reusable parts. 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 a focused workflow to reproduce, diagnose, repair, and validate; direct debugger/subagent calls remain useful as stages or for tiny deterministic diagnosis |\n| Research → spec → implementation | Chain \\`/skill:research-codebase\\` → \\`/skill:create-spec\\` → a named or custom implementation workflow with explicit validation and review |\n| Testing / regression hardening | Use a workflow for test/fix loops so retries, evidence, and the passing stop condition are tracked |\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\\` | autonomous work that benefits from a durable goal ledger, bounded worker turns, named validation, and reviewer-gated completion; add \\`create_pr=true\\` only for final PR handoff after approval | \\`/workflow goal objective=\"Implement specs/<date>-<topic>.md, run focused tests, and validate the changed behavior\"\\` |\n| \\`ralph\\` | autonomous work that benefits from a durable research-first pipeline, delegated implementation, and iterative review | \\`/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 example shows a spec-driven development process whose clearly delegated autonomous implementation benefits from durable workflow execution. For interactive or conversation-led work, stay inline or use bounded subagents while the parent remains in control. 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 and review. Use direct chat only for tiny deterministic low-risk edits; use focused subagents inside workflow stages or for bounded specialist passes. Choose an installed workflow when it fits, or author a custom TypeScript workflow inline from the starter patterns when the task needs a richer graph.\n\nFor work that fits a durable goal ledger, bounded worker turns, and reviewer-gated completion, use \\`goal\\`:\n\n\\`/workflow goal objective=\"Implement specs/<date>-<topic>.md, run focused tests, and finish when the documented behavior is validated\"\\`\n\nLoop or stop-condition phrasing is a key workflow signal. When the user delegates a loop 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\\`, 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\nWhen a clearly delegated autonomous job benefits from a durable research-first pipeline with orchestration and iterative review, 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\nDefault to workflows for non-trivial work and requests with inherent structure plus a verifiable objective. Implementation, debugging, migrations, multi-file changes, validation, review, evidence requirements, and explicit stop conditions are workflow-shaped; use direct chat only for tiny deterministic low-risk answers or edits.\n\nWorkflow-first is not builtin-only or monolithic. Atomic can author custom TypeScript \\`workflow({...})\\` definitions inline, and workflows can import reusable project/package definitions or builtins from \\`@bastani/workflows/builtin\\`, then nest them with \\`ctx.workflow(...)\\`. Imported children can nest further children within \\`maxDepth\\`, so compose proven research, implementation, design, verification, and approval workflows instead of copying their stages. Use the documented starter patterns for classify-and-act routing, dynamic fan-out and synthesis, adversarial verification, candidate selection, and bounded convergence. Atomic writes the parent definition, reloads it, and runs the composed graph.\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\\` | autonomous work that benefits from a durable goal ledger, bounded worker turns, named validation, and reviewer-gated completion; 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\\` | autonomous work that benefits from a durable research-first pipeline, delegated implementation, and iterative review | \\`/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 supports a least-orchestration hierarchy: keep interactive, exploratory, conceptual, and conversation-led work inline; use bounded single, chain, or parallel subagents while the parent remains in control; and use workflows when the user clearly delegates a well-defined autonomous job that is likely long-running/background-oriented or materially needs durable stages, artifacts/checkpoints, resumability, HIL, gates, retries, or bounded loops. Multiple steps, files, tests, validation, or parallelism alone do not require a workflow. 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\` is a key workflow signal when the user delegates execution, because it defines control flow and a completion condition that should be tracked. When workflow execution fits, Atomic may always author a custom TypeScript \`workflow({...})\` inline with normal coding tools if that shape best achieves the task; it is not limited to installed workflows or direct modes. Named workflows can be builtin, project, user, or package supplied; direct task/tasks/chain modes cover one-off tracked shapes. 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 non-trivial work into executable, inspectable workflows. Default to a workflow for implementation, build, debugging, bug fixes, migrations, features, scoped multi-file changes, and validated docs/code work, or whenever a request has dependencies, handoffs, uncertainty, review gates, measurable done criteria, or evidence requirements. Use direct chat for tiny deterministic low-risk answers or edits. Loop-shaped prompts such as \`do X until Y\`, \`review/fix until passing\`, or \`run checks and fix until green\` are especially strong workflow signals. Workflow-first is not builtin-only or monolithic: use named workflows, direct modes, author a custom TypeScript \`workflow({...})\` inline, or import reusable project/package and builtin definitions from \`@bastani/workflows/builtin\` and nest them with \`ctx.workflow(...)\`. Nested children may compose further children within \`maxDepth\`, enabling powerful research → implementation → verification → approval graphs from reusable parts. 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 supports a least-orchestration hierarchy: keep interactive, exploratory,
 
 | Goal | How to use |
 |---|---|
-| On-call / broken behavior | Reproduce and diagnose inline or with a debugger subagent, using bounded specialists when useful; choose \`goal\` only when a clearly delegated repair materially needs a durable ledger, bounded worker turns, or reviewer-gated completion |
-| Research → spec → implementation | Use \`/skill:research-codebase\`, \`/skill:create-spec\`, and bounded subagents while the parent remains in control; choose a workflow only for a clearly delegated autonomous job with durable execution needs |
-| Testing / regression hardening | Keep focused test/fix work inline or bounded. Loop or stop-condition wording is a key workflow signal when the user delegates execution; use \`goal\` when the run should track retries, evidence, convergence, and an explicit stop condition |
+| On-call / broken behavior | Use a focused workflow to reproduce, diagnose, repair, and validate; direct debugger/subagent calls remain useful as stages or for tiny deterministic diagnosis |
+| Research → spec → implementation | Chain \`/skill:research-codebase\` → \`/skill:create-spec\` → a named or custom implementation workflow with explicit validation and review |
+| Testing / regression hardening | Use a workflow for test/fix loops so retries, evidence, and the passing stop condition are tracked |
 | 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 |
 
@@ -98,9 +98,9 @@ Skip this if the implementation request is already precise.
 
 ## 3. Implement with review built in
 
-Keep interactive or conversation-led implementation inline. Use bounded subagents when specialist delegation helps, and choose a workflow only when the user clearly delegates an autonomous job whose long-running/background nature or durable execution needs justify it; files, tests, and validation alone do not.
+Default to a workflow for non-trivial implementation and review. Use direct chat only for tiny deterministic low-risk edits; use focused subagents inside workflow stages or for bounded specialist passes. Choose an installed workflow when it fits, or author a custom TypeScript workflow inline from the starter patterns when the task needs a richer graph.
 
-When the job needs a durable goal ledger, bounded worker turns, and reviewer-gated completion, use \`goal\`:
+For work that fits a durable goal ledger, bounded worker turns, and reviewer-gated completion, use \`goal\`:
 
 \`/workflow goal objective="Implement specs/<date>-<topic>.md, run focused tests, and finish when the documented behavior is validated"\`
 
@@ -136,9 +136,9 @@ 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 for clearly delegated, well-defined autonomous jobs that are likely long-running/background-oriented or materially need durable stages, artifacts/checkpoints, resumability, HIL, gates, retries, or bounded loops. Keep interactive exploration inline and use bounded subagents when the parent should remain in control. Multiple steps, files, tests, validation, or parallelism alone do not require a workflow, but 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\` is a key workflow signal when the user delegates execution.
+Default to workflows for non-trivial work and requests with inherent structure plus a verifiable objective. Implementation, debugging, migrations, multi-file changes, validation, review, evidence requirements, and explicit stop conditions are workflow-shaped; use direct chat only for tiny deterministic low-risk answers or edits.
 
-Named workflows may be builtin, project, user, or package supplied, and direct task/tasks/chain modes cover one-off tracked shapes. When workflow execution fits, Atomic may always author a custom TypeScript \`workflow({...})\` inline with normal coding tools if that shape best achieves the task; it is not limited to installed workflows or direct modes. Atomic writes the definition, reloads it, and runs it.
+Workflow-first is not builtin-only or monolithic. Atomic can author custom TypeScript \`workflow({...})\` definitions inline, and workflows can import reusable project/package definitions or builtins from \`@bastani/workflows/builtin\`, then nest them with \`ctx.workflow(...)\`. Imported children can nest further children within \`maxDepth\`, so compose proven research, implementation, design, verification, and approval workflows instead of copying their stages. Use the documented starter patterns for classify-and-act routing, dynamic fan-out and synthesis, adversarial verification, candidate selection, and bounded convergence. Atomic writes the parent definition, reloads it, and runs the composed graph.
 
 ## Built-in workflows
 

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 supports a least-orchestration hierarchy: keep interactive, exploratory, conceptual, and conversation-led work inline; use bounded single, chain, or parallel subagents while the parent remains in control; and use workflows when the user clearly delegates a well-defined autonomous job that is likely long-running/background-oriented or materially needs durable stages, artifacts/checkpoints, resumability, HIL, gates, retries, or bounded loops. Multiple steps, files, tests, validation, or parallelism alone do not require a workflow. 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\\` is a key workflow signal when the user delegates execution, because it defines control flow and a completion condition that should be tracked. When workflow execution fits, Atomic may always author a custom TypeScript \\`workflow({...})\\` inline with normal coding tools if that shape best achieves the task; it is not limited to installed workflows or direct modes. Named workflows can be builtin, project, user, or package supplied; direct task/tasks/chain modes cover one-off tracked shapes. 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 | Reproduce and diagnose inline or with a debugger subagent, using bounded specialists when useful; choose \\`goal\\` only when a clearly delegated repair materially needs a durable ledger, bounded worker turns, or reviewer-gated completion |\n| Research → spec → implementation | Use \\`/skill:research-codebase\\`, \\`/skill:create-spec\\`, and bounded subagents while the parent remains in control; choose a workflow only for a clearly delegated autonomous job with durable execution needs |\n| Testing / regression hardening | Keep focused test/fix work inline or bounded. Loop or stop-condition wording is a key workflow signal when the user delegates execution; use \\`goal\\` when the run should track retries, evidence, convergence, and an explicit stop condition |\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\\` | autonomous work that benefits from a durable goal ledger, bounded worker turns, named validation, and reviewer-gated completion; add \\`create_pr=true\\` only for final PR handoff after approval | \\`/workflow goal objective=\"Implement specs/<date>-<topic>.md, run focused tests, and validate the changed behavior\"\\` |\n| \\`ralph\\` | autonomous work that benefits from a durable research-first pipeline, delegated implementation, and iterative review | \\`/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 example shows a spec-driven development process whose clearly delegated autonomous implementation benefits from durable workflow execution. For interactive or conversation-led work, stay inline or use bounded subagents while the parent remains in control. 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\nKeep interactive or conversation-led implementation inline. Use bounded subagents when specialist delegation helps, and choose a workflow only when the user clearly delegates an autonomous job whose long-running/background nature or durable execution needs justify it; files, tests, and validation alone do not.\n\nWhen the job needs a durable goal ledger, bounded worker turns, and reviewer-gated completion, use \\`goal\\`:\n\n\\`/workflow goal objective=\"Implement specs/<date>-<topic>.md, run focused tests, and finish when the documented behavior is validated\"\\`\n\nLoop or stop-condition phrasing is a key workflow signal. When the user delegates a loop 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\\`, 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\nWhen a clearly delegated autonomous job benefits from a durable research-first pipeline with orchestration and iterative review, 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 for clearly delegated, well-defined autonomous jobs that are likely long-running/background-oriented or materially need durable stages, artifacts/checkpoints, resumability, HIL, gates, retries, or bounded loops. Keep interactive exploration inline and use bounded subagents when the parent should remain in control. Multiple steps, files, tests, validation, or parallelism alone do not require a workflow, but 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\\` is a key workflow signal when the user delegates execution.\n\nNamed workflows may be builtin, project, user, or package supplied, and direct task/tasks/chain modes cover one-off tracked shapes. When workflow execution fits, Atomic may always author a custom TypeScript \\`workflow({...})\\` inline with normal coding tools if that shape best achieves the task; it is not limited to installed workflows or direct modes. Atomic writes the definition, reloads it, and runs it.\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\\` | autonomous work that benefits from a durable goal ledger, bounded worker turns, named validation, and reviewer-gated completion; 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\\` | autonomous work that benefits from a durable research-first pipeline, delegated implementation, and iterative review | \\`/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":"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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 non-trivial work into executable, inspectable workflows. Default to a workflow for implementation, build, debugging, bug fixes, migrations, features, scoped multi-file changes, and validated docs/code work, or whenever a request has dependencies, handoffs, uncertainty, review gates, measurable done criteria, or evidence requirements. Use direct chat for tiny deterministic low-risk answers or edits. Loop-shaped prompts such as \\`do X until Y\\`, \\`review/fix until passing\\`, or \\`run checks and fix until green\\` are especially strong workflow signals. Workflow-first is not builtin-only or monolithic: use named workflows, direct modes, author a custom TypeScript \\`workflow({...})\\` inline, or import reusable project/package and builtin definitions from \\`@bastani/workflows/builtin\\` and nest them with \\`ctx.workflow(...)\\`. Nested children may compose further children within \\`maxDepth\\`, enabling powerful research → implementation → verification → approval graphs from reusable parts. 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 a focused workflow to reproduce, diagnose, repair, and validate; direct debugger/subagent calls remain useful as stages or for tiny deterministic diagnosis |\n| Research → spec → implementation | Chain \\`/skill:research-codebase\\` → \\`/skill:create-spec\\` → a named or custom implementation workflow with explicit validation and review |\n| Testing / regression hardening | Use a workflow for test/fix loops so retries, evidence, and the passing stop condition are tracked |\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\\` | autonomous work that benefits from a durable goal ledger, bounded worker turns, named validation, and reviewer-gated completion; add \\`create_pr=true\\` only for final PR handoff after approval | \\`/workflow goal objective=\"Implement specs/<date>-<topic>.md, run focused tests, and validate the changed behavior\"\\` |\n| \\`ralph\\` | autonomous work that benefits from a durable research-first pipeline, delegated implementation, and iterative review | \\`/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 example shows a spec-driven development process whose clearly delegated autonomous implementation benefits from durable workflow execution. For interactive or conversation-led work, stay inline or use bounded subagents while the parent remains in control. 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 and review. Use direct chat only for tiny deterministic low-risk edits; use focused subagents inside workflow stages or for bounded specialist passes. Choose an installed workflow when it fits, or author a custom TypeScript workflow inline from the starter patterns when the task needs a richer graph.\n\nFor work that fits a durable goal ledger, bounded worker turns, and reviewer-gated completion, use \\`goal\\`:\n\n\\`/workflow goal objective=\"Implement specs/<date>-<topic>.md, run focused tests, and finish when the documented behavior is validated\"\\`\n\nLoop or stop-condition phrasing is a key workflow signal. When the user delegates a loop 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\\`, 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\nWhen a clearly delegated autonomous job benefits from a durable research-first pipeline with orchestration and iterative review, 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\nDefault to workflows for non-trivial work and requests with inherent structure plus a verifiable objective. Implementation, debugging, migrations, multi-file changes, validation, review, evidence requirements, and explicit stop conditions are workflow-shaped; use direct chat only for tiny deterministic low-risk answers or edits.\n\nWorkflow-first is not builtin-only or monolithic. Atomic can author custom TypeScript \\`workflow({...})\\` definitions inline, and workflows can import reusable project/package definitions or builtins from \\`@bastani/workflows/builtin\\`, then nest them with \\`ctx.workflow(...)\\`. Imported children can nest further children within \\`maxDepth\\`, so compose proven research, implementation, design, verification, and approval workflows instead of copying their stages. Use the documented starter patterns for classify-and-act routing, dynamic fan-out and synthesis, adversarial verification, candidate selection, and bounded convergence. Atomic writes the parent definition, reloads it, and runs the composed graph.\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\\` | autonomous work that benefits from a durable goal ledger, bounded worker turns, named validation, and reviewer-gated completion; 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\\` | autonomous work that benefits from a durable research-first pipeline, delegated implementation, and iterative review | \\`/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/quickstart.md

@@ -82,11 +82,9 @@ See [Providers](/providers) for all supported providers, environment variables,
 
 On a fresh install with no prior Atomic startup state, Atomic shows a one-time first-run explanation after any What's New notes and directly above the input box describing Atomic as a verifiable coding agent runtime for building and running agent workflows you can feel confident in. 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 the first-run explanation. The composer is the normal Atomic input from the start: type a message, run `/login` first if no provider is connected, open `/atomic`, or launch a workflow command without a special onboarding transition.
 
-Once Atomic starts, use the least orchestration that fits your intent. Keep interactive or exploratory work in chat; use single, chain, or parallel subagents for bounded specialist delegation; and use workflows for clearly delegated, well-defined autonomous jobs that are likely long-running/background-oriented or materially need durable stages, artifacts/checkpoints, resumability, HIL, gates, retries, or bounded loops. Multiple steps, files, tests, validation, or parallelism alone do not require a workflow.
+Once Atomic starts, default to a workflow for non-trivial work and for requests with inherent structure plus a verifiable objective. Implementation, build, debugging, bug fixes, migrations, features, scoped multi-file edits, validation/review work, and loop-shaped requests are workflow candidates; reserve direct chat for tiny deterministic low-risk answers or edits where tracking clearly adds more overhead than value.
 
-Loop or stop-condition phrasing is a key workflow signal. Requests 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` should generally use a workflow when the user is delegating execution, so the stop condition, retries, evidence, and convergence are tracked.
-
-When workflow execution fits, Atomic may always author a custom TypeScript `workflow({...})` inline with normal coding tools if that shape best achieves the task; it is not limited to installed workflows or direct modes.
+Workflow-first is not builtin-only or monolithic. Atomic can discover named builtin, project, user, and package workflows; run direct `task`, `tasks`, and `chain` shapes; author a rich custom TypeScript `workflow({...})` inline; and compositionally import reusable workflow definitions—including builtins from `@bastani/workflows/builtin`—into parent workflows with `ctx.workflow(...)`. Nested children can nest again within `maxDepth`, so custom graphs can combine proven research, implementation, design, verification, and approval workflows instead of copying them. They can also classify and branch, dynamically fan out and synthesize artifacts, run adversarial repair cycles, tournament-rank candidates, and loop until checks pass with explicit bounds.
 
 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.
 

package/docs/subagents.md

@@ -41,7 +41,7 @@ When a foreground child sends `intercom.ask`, `intercom.send`, or `contact_super
 
 Only the matching foreground child releases the parent `subagent` tool. It stays alive under the normal watchdog, cancellation, drain, and stdio cleanup lifecycle; its eventual completion replaces the detached placeholder. Fire-and-forget `intercom.send` and `progress_update` also release foreground supervision promptly, but do not create a reply waiter.
 
-Interactive parent sessions lazily register with Intercom when needed; a foreground launch awaits the parent's broker/inbound-handler readiness before the child process can coordinate. Bridged foreground and background children register before agent work begins. Disabled, unavailable, noninteractive, unused-parent, and management-only `list`/`get`/`create`/`update`/`delete`/`status`/`interrupt`/`doctor` paths do not force heavy runtime loading or broker startup. `resume` remains launch-capable and retains the readiness gate. Optional Intercom import, broker, or connection failures are diagnosed without aborting launch, and later calls can retry. Cancellation or session replacement invalidates the handshake generation, so stale acknowledgements cannot surface or detach a child.
+Intercom connection remains tool-driven. Foreground and background launches do not import the heavy Intercom runtime or connect either the parent or bridged child automatically. If live child-to-parent coordination is needed, the parent model should invoke `intercom({ action: "status" })` before launch; the child then connects on its first `contact_supervisor` or `intercom` call. Cancellation or session replacement still invalidates the handshake generation, so stale acknowledgements cannot surface or detach a child.
 
 Atomic's implementation adapts the prompt foreground release and later-result recovery contracts proven in `nicobailon/pi-subagents` commits `1b55c8c`, `589e51e`, `68fb528`, and `9dfe3df`; it retains Atomic's broker and raw-TypeScript architecture rather than copying upstream's filesystem transport.