@bastani/atomic 0.8.9 → 0.8.10-0

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

@@ -0,0 +1,41 @@
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+export declare const ATOMIC_GUIDE_COMMAND_NAME = "atomic";
+export declare const ATOMIC_GUIDE_COMMAND_DESCRIPTION = "Atomic onboarding and help guide";
+declare const GUIDE_SECTIONS: readonly [{
+    readonly name: "overview";
+    readonly aliases: readonly [];
+    readonly label: "overview";
+    readonly description: "30-second overview";
+    readonly render: () => string;
+}, {
+    readonly name: "workflows";
+    readonly aliases: readonly ["workflow"];
+    readonly label: "workflows";
+    readonly description: "Workflow primer";
+    readonly render: () => string;
+}, {
+    readonly name: "example";
+    readonly aliases: readonly ["examples"];
+    readonly label: "example";
+    readonly description: "Practical first workflow";
+    readonly render: () => string;
+}, {
+    readonly name: "whats-new";
+    readonly aliases: readonly ["what's new", "whats new", "news", "updates", "changelog"];
+    readonly label: "what's new";
+    readonly description: "Recent release notes";
+    readonly render: typeof readLatestStableChangelog;
+}];
+type AtomicGuideSection = (typeof GUIDE_SECTIONS)[number];
+type AtomicGuideSectionName = AtomicGuideSection["name"];
+export type AtomicGuideHelpChoice = AtomicGuideSection["label"];
+export type AtomicGuideMode = "help" | AtomicGuideSectionName;
+export declare const ATOMIC_GUIDE_HELP_CHOICES: readonly AtomicGuideHelpChoice[];
+export declare function isAtomicGuideHelpChoice(choice: string): choice is AtomicGuideHelpChoice;
+export declare function normalizeAtomicGuideMode(args: string): AtomicGuideMode;
+export declare function getAtomicGuideArgumentCompletions(prefix: string): AutocompleteItem[] | null;
+declare function readLatestStableChangelog(cwd: string): string;
+export declare function getAtomicGuideMessage(mode: AtomicGuideMode, cwd: string): string;
+export declare function atomicGuideModeForChoice(choice: AtomicGuideHelpChoice): AtomicGuideMode;
+export {};
+//# sourceMappingURL=atomic-guide-command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-guide-command.d.ts","sourceRoot":"","sources":["../../src/core/atomic-guide-command.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D,eAAO,MAAM,yBAAyB,WAAW,CAAC;AAClD,eAAO,MAAM,gCAAgC,qCAAqC,CAAC;AA0MnF,QAAA,MAAM,cAAc;mBAEZ,UAAU;;oBAET,UAAU;0BACJ,oBAAoB;;;mBAI3B,WAAW;;oBAEV,WAAW;0BACL,iBAAiB;;;mBAIxB,SAAS;;oBAER,SAAS;0BACH,0BAA0B;;;mBAIjC,WAAW;;oBAEV,YAAY;0BACN,sBAAsB;;EASlC,CAAC;AAEJ,KAAK,kBAAkB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1D,KAAK,sBAAsB,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAEzD,MAAM,MAAM,qBAAqB,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAEhE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,sBAAsB,CAAC;AAE9D,eAAO,MAAM,yBAAyB,EAAE,SAAS,qBAAqB,EAErE,CAAC;AAcF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,IAAI,qBAAqB,CAEvF;AA6BD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAKtE;AAED,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE,GAAG,IAAI,CAW3F;AAED,iBAAS,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CActD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAGhF;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAEvF","sourcesContent":["import * as path from \"node:path\";\nimport type { AutocompleteItem } from \"@earendil-works/pi-tui\";\nimport { getChangelogPath, parseChangelog } from \"../utils/changelog.js\";\n\nexport const ATOMIC_GUIDE_COMMAND_NAME = \"atomic\";\nexport const ATOMIC_GUIDE_COMMAND_DESCRIPTION = \"Atomic onboarding and help guide\";\n\nconst OVERVIEW = `# Atomic overview\n\nAtomic turns one-off prompts into developer workflows: on-call debugging, repo research that turns into implementation, testing and review loops, and larger multi-stage automation. Start it in a project with \\`atomic\\`, then talk to it normally. Use \\`@file\\` to attach files, \\`!command\\` to run shell output through the model, and \\`!!command\\` to run shell output without adding it to context.\n\n## Core session commands\n\n| Command | Use |\n|---|---|\n| \\`/login\\` | configure auth |\n| \\`/model\\` | switch model |\n| \\`/settings\\` | thinking level, theme, message delivery, transport |\n| \\`/new\\`, \\`/resume\\` | start or resume sessions |\n| \\`/tree\\`, \\`/fork\\`, \\`/clone\\` | branch or navigate session history |\n| \\`/compact\\` | summarize older context |\n| \\`/hotkeys\\`, \\`/changelog\\` | local help and release notes |\n\n## Examples of using Atomic\n\n| Goal | How to use |\n|---|---|\n| On-call / broken behavior | Use \\`/skill:workflow\\` to create a workflow that runs \\`/run debugger \"Reproduce the failure, patch the root cause, and validate it\"\\` for a focused fix loop |\n| Research → spec → implementation | Use \\`/skill:workflow\\` to create a workflow that runs \\`/skill:research-codebase\\`, then \\`/skill:create-spec\\`, then direct implementation or \\`/workflow ralph ...\\` |\n| Testing / regression hardening | Use \\`/skill:workflow\\` to create a workflow that runs \\`/skill:tdd\\` for test-first work, then \\`/parallel-review current diff\\`, then land the change |\n| Large repo discovery | Use \\`/skill:workflow\\` to create a workflow that runs \\`/parallel codebase-locator \"map the area\" -> codebase-analyzer \"trace the current flow\" -> codebase-pattern-finder \"find patterns\" --bg\\` |\n| UI / product polish | Use \\`/skill:workflow\\` to create a workflow that runs \\`/skill:impeccable\\` for interface critique, refinement, and clearer UX decisions |\n\n## Subagents\n\nSubagents are focused child Atomic sessions you can point at one job inside the repo.\n\n| Built-in subagent | Use |\n|---|---|\n| \\`codebase-locator\\` | find relevant files, tests, entrypoints, and configs |\n| \\`codebase-analyzer\\` | explain current behavior with file:line refs |\n| \\`codebase-pattern-finder\\` | find existing code to model after |\n| \\`debugger\\` | reproduce, diagnose, and fix broken behavior |\n\nHow the direct commands map to repo work:\n- \\`/run\\` = one specialist on one job, for example \\`/run codebase-locator \"Map the webhook retry flow\"\\`\n- \\`/parallel\\` = several independent specialists at once, for example \\`/parallel codebase-locator \"map retry files\" -> codebase-pattern-finder \"find existing retry/backoff patterns\" -> codebase-online-researcher \"research current retry guidance\" --bg\\`\n- \\`/chain\\` = ordered handoffs, for example \\`/chain codebase-locator \"find the auth files\" -> codebase-analyzer \"trace the auth flow\" -> debugger \"patch the failing auth edge case\"\\`\n\n## Top skills\n\n| Skill | When to use | How to run |\n|---|---|---|\n| \\`research-codebase\\` | write a grounded research artifact for one subsystem or question | \\`/skill:research-codebase how the rate limiter works in src/middleware/\\` |\n| \\`create-spec\\` | turn research into an implementation-ready plan | \\`/skill:create-spec from research/docs/<date>-<topic>.md\\` |\n| \\`tdd\\` | do test-first feature or bug work | \\`/skill:tdd\\` |\n| \\`prompt-engineer\\` | tighten a vague prompt before a long run | \\`/skill:prompt-engineer Draft a sharper implementation prompt for ...\\` |\n| \\`workflow\\` | author, inspect, or improve workflows; start by describing the desired workflow in natural language | \\`/skill:workflow\\` |\n| \\`subagent\\` | learn delegation patterns and exact \\`/run\\`, \\`/parallel\\`, and \\`/chain\\` usage | \\`/skill:subagent\\` |\n| \\`impeccable\\` | critique or refine frontend and product UI | \\`/skill:impeccable\\` |\n\n## Built-in workflows\n\n| Workflow | When to use | How to run |\n|---|---|---|\n| \\`deep-research-codebase\\` | broad repo or cross-cutting research before you decide what to change (for one area, use \\`/skill:research-codebase\\`; this indexes the whole repo) | \\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\` |\n| \\`ralph\\` | larger implementation loops where you want implementation, review, and validation built in | \\`/workflow ralph prompt=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\` |\n| \\`open-claude-design\\` | UI and design-system work that benefits from generation and refinement loops | \\`/workflow open-claude-design prompt=\"Refresh the settings page hierarchy\"\\` |\n\nUse \\`/workflow list\\` to see what is available and \\`/workflow inputs <name>\\` to inspect inputs in your environment.\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic example\\` — see the pieces used on a code task\n\\`/atomic workflows\\` — learn when to use workflows`;\n\nconst EXAMPLE = `# Practical example\n\nThis is an example of a spec-driven development process using Atomic workflows. Use it when you are new to a repo or the task has non-trivial scope. Type the examples below into the Atomic TUI chat after starting \\`atomic\\` in your project.\n\n## 1. Research what exists\n\nUse \\`/skill:research-codebase\\` for a scoped area, subsystem, or directory:\n\n\\`/skill:research-codebase how the rate limiter works in src/middleware/\\`\n\nUse \\`deep-research-codebase\\` when the answer spans the whole repo or a cross-cutting implementation path:\n\n\\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\`\n\nIf the research prompt is vague, tighten it first with \\`/skill:prompt-engineer\\`:\n\n\\`/skill:prompt-engineer Draft a sharper repo-research prompt for understanding payment retries end to end, including retries, queues, and failure handling.\\`\n\n## 2. Create a spec when requirements are fuzzy\n\nSkip this if the implementation request is already precise.\n\n\\`/skill:create-spec from research/docs/<date>-<topic>.md\\`\n\n## 3. Implement with review built in\n\nFor ordinary work, ask Atomic directly and require validation:\n\n\\`Implement the approved spec in specs/<date>-<topic>.md. Run focused tests and summarize validation.\\`\n\nFor larger work, use subagents or a workflow:\n\n\\`/workflow ralph prompt=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\`\n\n## 4. Decide and land\n\nIf you used \\`ralph\\`, the workflow already ran parallel reviewers. Use its final result and review feedback to decide whether to ship or iterate again.\n\nIf you implemented directly instead of using \\`ralph\\`, you can still run:\n\n\\`/parallel-review current diff\\`\n\nAtomic will synthesize reviewer feedback and ask before applying fixes.\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic workflows\\` — learn when to use workflows\n\\`/atomic overview\\` — quick refresh`;\n\nconst WORKFLOWS = `# Workflows primer\n\nA workflow is a TypeScript-defined pipeline built with \\`defineWorkflow(...).run(...).compile()\\`. It can run tasks, chains, parallel fan-out, human-in-the-loop prompts, background status, and model fallback chains.\n\nStart by defining the workflow in natural language with \\`/skill:workflow\\`, the workflow creator skill. Describe the goal, inputs, stages, which steps are parallel or sequential, handoff/output shape, and any model or thinking-level preferences; let the skill help turn that into a reusable workflow before you hand-edit TypeScript.\n\n## Built-in workflows\n\n| Workflow | When to use | How to run |\n|---|---|---|\n| \\`deep-research-codebase\\` | broad repo or cross-cutting research before you decide what to change (for one area, use \\`/skill:research-codebase\\`; this indexes the whole repo) | \\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\` |\n| \\`ralph\\` | larger implementation and review loops | \\`/workflow ralph prompt=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\` |\n| \\`open-claude-design\\` | frontend and product design work | \\`/workflow open-claude-design prompt=\"Refresh the settings page hierarchy\"\\` |\n\nUse \\`/workflow inputs <name>\\` to inspect the exact inputs in your environment.\n\nUse \\`/skill:research-codebase ...\\` when you want research on one subsystem, directory, or focused question. Use \\`/workflow deep-research-codebase ...\\` when the answer needs end-to-end tracing across many parts of the repo.\n\nIf you are drafting research, reviewer, or synthesis prompts for a workflow, use \\`/skill:prompt-engineer\\` first. It is a good fit when a stage prompt feels vague, overloaded, or underspecified.\n\n## What good workflow authoring looks like\n\nA good workflow request is explicit about stage purpose, model choice, handoff, and the decision each step must return.\n\nExample: prompt \\`/skill:workflow\\` with something like this:\n\n~~~text\nCreate a reusable workflow called review-changes.\n\nIt should accept one required text input called target for a diff, PR summary, or review target.\n\nRun two independent review stages in parallel with fresh context:\n- one reviewer focused on correctness, regressions, and missing tests using openai-codex/gpt-5.5 at xhigh thinking\n- one reviewer focused on edge cases, maintainability, and hidden risks using anthropic/claude-opus-4-7 at xhigh thinking\n\nThen add an aggregate stage that consolidates both reviews, deduplicates overlap, keeps only evidence-backed issues, and separates blockers from optional suggestions using openai/gpt-5.5 at high thinking.\n\nFinally add an adjudicate stage using anthropic/claude-sonnet-4 at high thinking that decides what to fix now, what to defer, and what to reject. Return a short action list with rationale.\n\nThe workflow should return structured output with consolidated_review and decision fields.\n~~~\n\nWhy this is good:\n- it names the workflow and required input\n- it specifies which stages are parallel vs sequential\n- each stage has one job\n- it defines the handoff and final outputs\n- it calls out model choice and thinking level where that matters\n\n## Run and inspect\n\n\\`/workflow list\\`\n\n\\`/workflow inputs ralph\\`\n\n\\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\" max_loops=5\\`\n\n\\`/workflow status\\`\n\n\\`/workflow connect <run-id>\\`\n\n\\`/workflow interrupt <run-id>\\`\n\n\\`/workflow resume <run-id>\\`\n\nWorkflows run as background tasks. Use F2 or \\`/workflow connect <run-id>\\` for the graph viewer. Human-in-the-loop prompts appear there, not as chat modals.\n\n## Author your own\n\nUse \\`/skill:workflow\\` to describe your workflow in natural language and build your first workflow. This is the recommended starting point for creation and design questions: 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. Ask Atomic in chat when you want help refining or implementing one.\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic example\\` — see workflows in a normal task flow\n\\`/atomic overview\\` — quick refresh`;\n\nconst GUIDE_SECTIONS = [\n\t{\n\t\tname: \"overview\",\n\t\taliases: [],\n\t\tlabel: \"overview\",\n\t\tdescription: \"30-second overview\",\n\t\trender: () => OVERVIEW,\n\t},\n\t{\n\t\tname: \"workflows\",\n\t\taliases: [\"workflow\"],\n\t\tlabel: \"workflows\",\n\t\tdescription: \"Workflow primer\",\n\t\trender: () => WORKFLOWS,\n\t},\n\t{\n\t\tname: \"example\",\n\t\taliases: [\"examples\"],\n\t\tlabel: \"example\",\n\t\tdescription: \"Practical first workflow\",\n\t\trender: () => EXAMPLE,\n\t},\n\t{\n\t\tname: \"whats-new\",\n\t\taliases: [\"what's new\", \"whats new\", \"news\", \"updates\", \"changelog\"],\n\t\tlabel: \"what's new\",\n\t\tdescription: \"Recent release notes\",\n\t\trender: readLatestStableChangelog,\n\t},\n] as const satisfies readonly {\n\treadonly name: string;\n\treadonly aliases: readonly string[];\n\treadonly label: string;\n\treadonly description: string;\n\treadonly render: (cwd: string) => string;\n}[];\n\ntype AtomicGuideSection = (typeof GUIDE_SECTIONS)[number];\ntype AtomicGuideSectionName = AtomicGuideSection[\"name\"];\n\nexport type AtomicGuideHelpChoice = AtomicGuideSection[\"label\"];\n\nexport type AtomicGuideMode = \"help\" | AtomicGuideSectionName;\n\nexport const ATOMIC_GUIDE_HELP_CHOICES: readonly AtomicGuideHelpChoice[] = GUIDE_SECTIONS.map(\n\t(section) => section.label,\n);\n\nconst GUIDE_SECTIONS_BY_NAME = new Map<AtomicGuideSectionName, AtomicGuideSection>(\n\tGUIDE_SECTIONS.map((section) => [section.name, section]),\n);\nconst GUIDE_SECTIONS_BY_LABEL = new Map<string, AtomicGuideSection>(\n\tGUIDE_SECTIONS.map((section) => [section.label, section]),\n);\nconst GUIDE_SECTIONS_BY_INPUT = new Map<string, AtomicGuideSection>(\n\tGUIDE_SECTIONS.flatMap((section) =>\n\t\t[section.name, section.label, ...section.aliases].map((input) => [input, section] as const),\n\t),\n);\n\nexport function isAtomicGuideHelpChoice(choice: string): choice is AtomicGuideHelpChoice {\n\treturn GUIDE_SECTIONS_BY_LABEL.has(choice);\n}\n\nconst ATOMIC_GUIDE_TRAILING_PUNCTUATION = \"?!.,;:\";\n\nfunction stripTrailingAtomicGuidePunctuation(value: string): string {\n\tlet end = value.length;\n\twhile (end > 0 && ATOMIC_GUIDE_TRAILING_PUNCTUATION.includes(value.charAt(end - 1))) {\n\t\tend--;\n\t}\n\treturn value.slice(0, end);\n}\n\nfunction getGuideSectionForChoice(choice: string): AtomicGuideSection | undefined {\n\treturn GUIDE_SECTIONS_BY_LABEL.get(choice);\n}\n\nfunction getGuideSectionForMode(mode: AtomicGuideSectionName): AtomicGuideSection {\n\tconst section = GUIDE_SECTIONS_BY_NAME.get(mode);\n\tif (!section) throw new Error(`Unknown Atomic guide section: ${mode}`);\n\treturn section;\n}\n\nfunction getAtomicGuideHelpMenu(): string {\n\tconst sectionHelp = GUIDE_SECTIONS.map(\n\t\t(section) => `- \\`${section.label}\\` — run \\`/atomic ${section.label}\\``,\n\t).join(\"\\n\");\n\treturn `# Atomic\\n\\nSelect where to start:\\n\\n${sectionHelp}`;\n}\n\nexport function normalizeAtomicGuideMode(args: string): AtomicGuideMode {\n\tconst normalized = stripTrailingAtomicGuidePunctuation(args.trim().toLowerCase());\n\tif (!normalized) return \"help\";\n\n\treturn GUIDE_SECTIONS_BY_INPUT.get(normalized)?.name ?? \"help\";\n}\n\nexport function getAtomicGuideArgumentCompletions(prefix: string): AutocompleteItem[] | null {\n\tconst query = prefix.trim().toLowerCase();\n\tconst items = GUIDE_SECTIONS.map((section) => ({\n\t\tvalue: section.label,\n\t\tlabel: section.label,\n\t\tdescription: section.description,\n\t}));\n\tconst filtered = query\n\t\t? items.filter((item) => item.value.startsWith(query) || item.label.startsWith(query))\n\t\t: items;\n\treturn filtered.length > 0 ? filtered : null;\n}\n\nfunction readLatestStableChangelog(cwd: string): string {\n\tconst changelogPath = getChangelogPath();\n\tconst stableSections = parseChangelog(changelogPath)\n\t\t.filter((entry) => entry.prerelease === null)\n\t\t.slice(0, 3)\n\t\t.map((entry) => entry.content.trim())\n\t\t.filter(Boolean);\n\n\tif (stableSections.length === 0) {\n\t\treturn `# What's new\\n\\nNo stable release sections were found. Try \\`/changelog\\` for the interactive changelog viewer.\\n\\n─────────────────────────────────────────────────────────────────\\n\\nWhere to next:\\n\\n\\`/atomic example\\` — see a practical first workflow\\n\\`/atomic overview\\` — quick refresh`;\n\t}\n\n\tconst relativePath = path.relative(cwd, changelogPath) || changelogPath;\n\treturn `# What's new\\n\\n${stableSections.join(\"\\n\\n\")}\\n\\nSource: \\`${relativePath}\\`\\n\\n─────────────────────────────────────────────────────────────────\\n\\nWhere to next:\\n\\n\\`/atomic example\\` — see a practical first workflow\\n\\`/atomic overview\\` — quick refresh`;\n}\n\nexport function getAtomicGuideMessage(mode: AtomicGuideMode, cwd: string): string {\n\tif (mode === \"help\") return getAtomicGuideHelpMenu();\n\treturn getGuideSectionForMode(mode).render(cwd);\n}\n\nexport function atomicGuideModeForChoice(choice: AtomicGuideHelpChoice): AtomicGuideMode {\n\treturn getGuideSectionForChoice(choice)?.name ?? \"help\";\n}\n\n"]}

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

@@ -0,0 +1,299 @@
+import * as path from "node:path";
+import { getChangelogPath, parseChangelog } from "../utils/changelog.js";
+export const ATOMIC_GUIDE_COMMAND_NAME = "atomic";
+export const ATOMIC_GUIDE_COMMAND_DESCRIPTION = "Atomic onboarding and help guide";
+const OVERVIEW = `# Atomic overview
+
+Atomic turns one-off prompts into developer workflows: on-call debugging, repo research that turns into implementation, testing and review loops, and larger multi-stage automation. Start it in a project with \`atomic\`, then talk to it normally. Use \`@file\` to attach files, \`!command\` to run shell output through the model, and \`!!command\` to run shell output without adding it to context.
+
+## Core session commands
+
+| Command | Use |
+|---|---|
+| \`/login\` | configure auth |
+| \`/model\` | switch model |
+| \`/settings\` | thinking level, theme, message delivery, transport |
+| \`/new\`, \`/resume\` | start or resume sessions |
+| \`/tree\`, \`/fork\`, \`/clone\` | branch or navigate session history |
+| \`/compact\` | summarize older context |
+| \`/hotkeys\`, \`/changelog\` | local help and release notes |
+
+## Examples of using Atomic
+
+| Goal | How to use |
+|---|---|
+| On-call / broken behavior | Use \`/skill:workflow\` to create a workflow that runs \`/run debugger "Reproduce the failure, patch the root cause, and validate it"\` for a focused fix loop |
+| Research → spec → implementation | Use \`/skill:workflow\` to create a workflow that runs \`/skill:research-codebase\`, then \`/skill:create-spec\`, then direct implementation or \`/workflow ralph ...\` |
+| Testing / regression hardening | Use \`/skill:workflow\` to create a workflow that runs \`/skill:tdd\` for test-first work, then \`/parallel-review current diff\`, then land the change |
+| Large repo discovery | Use \`/skill:workflow\` to create a workflow that runs \`/parallel codebase-locator "map the area" -> codebase-analyzer "trace the current flow" -> codebase-pattern-finder "find patterns" --bg\` |
+| UI / product polish | Use \`/skill:workflow\` to create a workflow that runs \`/skill:impeccable\` for interface critique, refinement, and clearer UX decisions |
+
+## Subagents
+
+Subagents are focused child Atomic sessions you can point at one job inside the repo.
+
+| Built-in subagent | Use |
+|---|---|
+| \`codebase-locator\` | find relevant files, tests, entrypoints, and configs |
+| \`codebase-analyzer\` | explain current behavior with file:line refs |
+| \`codebase-pattern-finder\` | find existing code to model after |
+| \`debugger\` | reproduce, diagnose, and fix broken behavior |
+
+How the direct commands map to repo work:
+- \`/run\` = one specialist on one job, for example \`/run codebase-locator "Map the webhook retry flow"\`
+- \`/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\`
+- \`/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"\`
+
+## Top skills
+
+| Skill | When to use | How to run |
+|---|---|---|
+| \`research-codebase\` | write a grounded research artifact for one subsystem or question | \`/skill:research-codebase how the rate limiter works in src/middleware/\` |
+| \`create-spec\` | turn research into an implementation-ready plan | \`/skill:create-spec from research/docs/<date>-<topic>.md\` |
+| \`tdd\` | do test-first feature or bug work | \`/skill:tdd\` |
+| \`prompt-engineer\` | tighten a vague prompt before a long run | \`/skill:prompt-engineer Draft a sharper implementation prompt for ...\` |
+| \`workflow\` | author, inspect, or improve workflows; start by describing the desired workflow in natural language | \`/skill:workflow\` |
+| \`subagent\` | learn delegation patterns and exact \`/run\`, \`/parallel\`, and \`/chain\` usage | \`/skill:subagent\` |
+| \`impeccable\` | critique or refine frontend and product UI | \`/skill:impeccable\` |
+
+## Built-in workflows
+
+| Workflow | When to use | How to run |
+|---|---|---|
+| \`deep-research-codebase\` | broad repo or cross-cutting research before you decide what to change (for one area, use \`/skill:research-codebase\`; this indexes the whole repo) | \`/workflow deep-research-codebase prompt="How do payment retries work end to end?"\` |
+| \`ralph\` | larger implementation loops where you want implementation, review, and validation built in | \`/workflow ralph prompt="Implement specs/<date>-<topic>.md and validate the changed behavior"\` |
+| \`open-claude-design\` | UI and design-system work that benefits from generation and refinement loops | \`/workflow open-claude-design prompt="Refresh the settings page hierarchy"\` |
+
+Use \`/workflow list\` to see what is available and \`/workflow inputs <name>\` to inspect inputs in your environment.
+
+─────────────────────────────────────────────────────────────────
+
+Where to next:
+
+\`/atomic example\` — see the pieces used on a code task
+\`/atomic workflows\` — learn when to use workflows`;
+const EXAMPLE = `# Practical example
+
+This is an example of a spec-driven development process using Atomic workflows. Use it when you are new to a repo or the task has non-trivial scope. Type the examples below into the Atomic TUI chat after starting \`atomic\` in your project.
+
+## 1. Research what exists
+
+Use \`/skill:research-codebase\` for a scoped area, subsystem, or directory:
+
+\`/skill:research-codebase how the rate limiter works in src/middleware/\`
+
+Use \`deep-research-codebase\` when the answer spans the whole repo or a cross-cutting implementation path:
+
+\`/workflow deep-research-codebase prompt="How do payment retries work end to end?"\`
+
+If the research prompt is vague, tighten it first with \`/skill:prompt-engineer\`:
+
+\`/skill:prompt-engineer Draft a sharper repo-research prompt for understanding payment retries end to end, including retries, queues, and failure handling.\`
+
+## 2. Create a spec when requirements are fuzzy
+
+Skip this if the implementation request is already precise.
+
+\`/skill:create-spec from research/docs/<date>-<topic>.md\`
+
+## 3. Implement with review built in
+
+For ordinary work, ask Atomic directly and require validation:
+
+\`Implement the approved spec in specs/<date>-<topic>.md. Run focused tests and summarize validation.\`
+
+For larger work, use subagents or a workflow:
+
+\`/workflow ralph prompt="Implement specs/<date>-<topic>.md and validate the changed behavior"\`
+
+## 4. Decide and land
+
+If you used \`ralph\`, the workflow already ran parallel reviewers. Use its final result and review feedback to decide whether to ship or iterate again.
+
+If you implemented directly instead of using \`ralph\`, you can still run:
+
+\`/parallel-review current diff\`
+
+Atomic will synthesize reviewer feedback and ask before applying fixes.
+
+─────────────────────────────────────────────────────────────────
+
+Where to next:
+
+\`/atomic workflows\` — learn when to use workflows
+\`/atomic overview\` — quick refresh`;
+const WORKFLOWS = `# Workflows primer
+
+A workflow is a TypeScript-defined pipeline built with \`defineWorkflow(...).run(...).compile()\`. It can run tasks, chains, parallel fan-out, human-in-the-loop prompts, background status, and model fallback chains.
+
+Start by defining the workflow in natural language with \`/skill:workflow\`, the workflow creator skill. Describe the goal, inputs, stages, which steps are parallel or sequential, handoff/output shape, and any model or thinking-level preferences; let the skill help turn that into a reusable workflow before you hand-edit TypeScript.
+
+## Built-in workflows
+
+| Workflow | When to use | How to run |
+|---|---|---|
+| \`deep-research-codebase\` | broad repo or cross-cutting research before you decide what to change (for one area, use \`/skill:research-codebase\`; this indexes the whole repo) | \`/workflow deep-research-codebase prompt="How do payment retries work end to end?"\` |
+| \`ralph\` | larger implementation and review loops | \`/workflow ralph prompt="Implement specs/<date>-<topic>.md and validate the changed behavior"\` |
+| \`open-claude-design\` | frontend and product design work | \`/workflow open-claude-design prompt="Refresh the settings page hierarchy"\` |
+
+Use \`/workflow inputs <name>\` to inspect the exact inputs in your environment.
+
+Use \`/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.
+
+If 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.
+
+## What good workflow authoring looks like
+
+A good workflow request is explicit about stage purpose, model choice, handoff, and the decision each step must return.
+
+Example: prompt \`/skill:workflow\` with something like this:
+
+~~~text
+Create a reusable workflow called review-changes.
+
+It should accept one required text input called target for a diff, PR summary, or review target.
+
+Run two independent review stages in parallel with fresh context:
+- one reviewer focused on correctness, regressions, and missing tests using openai-codex/gpt-5.5 at xhigh thinking
+- one reviewer focused on edge cases, maintainability, and hidden risks using anthropic/claude-opus-4-7 at xhigh thinking
+
+Then 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.
+
+Finally 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.
+
+The workflow should return structured output with consolidated_review and decision fields.
+~~~
+
+Why this is good:
+- it names the workflow and required input
+- it specifies which stages are parallel vs sequential
+- each stage has one job
+- it defines the handoff and final outputs
+- it calls out model choice and thinking level where that matters
+
+## Run and inspect
+
+\`/workflow list\`
+
+\`/workflow inputs ralph\`
+
+\`/workflow ralph prompt="Migrate the database layer to Drizzle" max_loops=5\`
+
+\`/workflow status\`
+
+\`/workflow connect <run-id>\`
+
+\`/workflow interrupt <run-id>\`
+
+\`/workflow resume <run-id>\`
+
+Workflows 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.
+
+## Author your own
+
+Use \`/skill:workflow\` to describe your workflow in natural language and build your first workflow. This is the recommended starting point for creation and design questions: 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. Ask Atomic in chat when you want help refining or implementing one.
+
+─────────────────────────────────────────────────────────────────
+
+Where to next:
+
+\`/atomic example\` — see workflows in a normal task flow
+\`/atomic overview\` — quick refresh`;
+const GUIDE_SECTIONS = [
+    {
+        name: "overview",
+        aliases: [],
+        label: "overview",
+        description: "30-second overview",
+        render: () => OVERVIEW,
+    },
+    {
+        name: "workflows",
+        aliases: ["workflow"],
+        label: "workflows",
+        description: "Workflow primer",
+        render: () => WORKFLOWS,
+    },
+    {
+        name: "example",
+        aliases: ["examples"],
+        label: "example",
+        description: "Practical first workflow",
+        render: () => EXAMPLE,
+    },
+    {
+        name: "whats-new",
+        aliases: ["what's new", "whats new", "news", "updates", "changelog"],
+        label: "what's new",
+        description: "Recent release notes",
+        render: readLatestStableChangelog,
+    },
+];
+export const ATOMIC_GUIDE_HELP_CHOICES = GUIDE_SECTIONS.map((section) => section.label);
+const GUIDE_SECTIONS_BY_NAME = new Map(GUIDE_SECTIONS.map((section) => [section.name, section]));
+const GUIDE_SECTIONS_BY_LABEL = new Map(GUIDE_SECTIONS.map((section) => [section.label, section]));
+const GUIDE_SECTIONS_BY_INPUT = new Map(GUIDE_SECTIONS.flatMap((section) => [section.name, section.label, ...section.aliases].map((input) => [input, section])));
+export function isAtomicGuideHelpChoice(choice) {
+    return GUIDE_SECTIONS_BY_LABEL.has(choice);
+}
+const ATOMIC_GUIDE_TRAILING_PUNCTUATION = "?!.,;:";
+function stripTrailingAtomicGuidePunctuation(value) {
+    let end = value.length;
+    while (end > 0 && ATOMIC_GUIDE_TRAILING_PUNCTUATION.includes(value.charAt(end - 1))) {
+        end--;
+    }
+    return value.slice(0, end);
+}
+function getGuideSectionForChoice(choice) {
+    return GUIDE_SECTIONS_BY_LABEL.get(choice);
+}
+function getGuideSectionForMode(mode) {
+    const section = GUIDE_SECTIONS_BY_NAME.get(mode);
+    if (!section)
+        throw new Error(`Unknown Atomic guide section: ${mode}`);
+    return section;
+}
+function getAtomicGuideHelpMenu() {
+    const sectionHelp = GUIDE_SECTIONS.map((section) => `- \`${section.label}\` — run \`/atomic ${section.label}\``).join("\n");
+    return `# Atomic\n\nSelect where to start:\n\n${sectionHelp}`;
+}
+export function normalizeAtomicGuideMode(args) {
+    const normalized = stripTrailingAtomicGuidePunctuation(args.trim().toLowerCase());
+    if (!normalized)
+        return "help";
+    return GUIDE_SECTIONS_BY_INPUT.get(normalized)?.name ?? "help";
+}
+export function getAtomicGuideArgumentCompletions(prefix) {
+    const query = prefix.trim().toLowerCase();
+    const items = GUIDE_SECTIONS.map((section) => ({
+        value: section.label,
+        label: section.label,
+        description: section.description,
+    }));
+    const filtered = query
+        ? items.filter((item) => item.value.startsWith(query) || item.label.startsWith(query))
+        : items;
+    return filtered.length > 0 ? filtered : null;
+}
+function readLatestStableChangelog(cwd) {
+    const changelogPath = getChangelogPath();
+    const stableSections = parseChangelog(changelogPath)
+        .filter((entry) => entry.prerelease === null)
+        .slice(0, 3)
+        .map((entry) => entry.content.trim())
+        .filter(Boolean);
+    if (stableSections.length === 0) {
+        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`;
+    }
+    const relativePath = path.relative(cwd, changelogPath) || changelogPath;
+    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`;
+}
+export function getAtomicGuideMessage(mode, cwd) {
+    if (mode === "help")
+        return getAtomicGuideHelpMenu();
+    return getGuideSectionForMode(mode).render(cwd);
+}
+export function atomicGuideModeForChoice(choice) {
+    return getGuideSectionForChoice(choice)?.name ?? "help";
+}
+//# sourceMappingURL=atomic-guide-command.js.map

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

@@ -0,0 +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.js\";\n\nexport const ATOMIC_GUIDE_COMMAND_NAME = \"atomic\";\nexport const ATOMIC_GUIDE_COMMAND_DESCRIPTION = \"Atomic onboarding and help guide\";\n\nconst OVERVIEW = `# Atomic overview\n\nAtomic turns one-off prompts into developer workflows: on-call debugging, repo research that turns into implementation, testing and review loops, and larger multi-stage automation. Start it in a project with \\`atomic\\`, then talk to it normally. Use \\`@file\\` to attach files, \\`!command\\` to run shell output through the model, and \\`!!command\\` to run shell output without adding it to context.\n\n## Core session commands\n\n| Command | Use |\n|---|---|\n| \\`/login\\` | configure auth |\n| \\`/model\\` | switch model |\n| \\`/settings\\` | thinking level, theme, message delivery, transport |\n| \\`/new\\`, \\`/resume\\` | start or resume sessions |\n| \\`/tree\\`, \\`/fork\\`, \\`/clone\\` | branch or navigate session history |\n| \\`/compact\\` | summarize older context |\n| \\`/hotkeys\\`, \\`/changelog\\` | local help and release notes |\n\n## Examples of using Atomic\n\n| Goal | How to use |\n|---|---|\n| On-call / broken behavior | Use \\`/skill:workflow\\` to create a workflow that runs \\`/run debugger \"Reproduce the failure, patch the root cause, and validate it\"\\` for a focused fix loop |\n| Research → spec → implementation | Use \\`/skill:workflow\\` to create a workflow that runs \\`/skill:research-codebase\\`, then \\`/skill:create-spec\\`, then direct implementation or \\`/workflow ralph ...\\` |\n| Testing / regression hardening | Use \\`/skill:workflow\\` to create a workflow that runs \\`/skill:tdd\\` for test-first work, then \\`/parallel-review current diff\\`, then land the change |\n| Large repo discovery | Use \\`/skill:workflow\\` to create a workflow that runs \\`/parallel codebase-locator \"map the area\" -> codebase-analyzer \"trace the current flow\" -> codebase-pattern-finder \"find patterns\" --bg\\` |\n| UI / product polish | Use \\`/skill:workflow\\` to create a workflow that runs \\`/skill:impeccable\\` for interface critique, refinement, and clearer UX decisions |\n\n## Subagents\n\nSubagents are focused child Atomic sessions you can point at one job inside the repo.\n\n| Built-in subagent | Use |\n|---|---|\n| \\`codebase-locator\\` | find relevant files, tests, entrypoints, and configs |\n| \\`codebase-analyzer\\` | explain current behavior with file:line refs |\n| \\`codebase-pattern-finder\\` | find existing code to model after |\n| \\`debugger\\` | reproduce, diagnose, and fix broken behavior |\n\nHow the direct commands map to repo work:\n- \\`/run\\` = one specialist on one job, for example \\`/run codebase-locator \"Map the webhook retry flow\"\\`\n- \\`/parallel\\` = several independent specialists at once, for example \\`/parallel codebase-locator \"map retry files\" -> codebase-pattern-finder \"find existing retry/backoff patterns\" -> codebase-online-researcher \"research current retry guidance\" --bg\\`\n- \\`/chain\\` = ordered handoffs, for example \\`/chain codebase-locator \"find the auth files\" -> codebase-analyzer \"trace the auth flow\" -> debugger \"patch the failing auth edge case\"\\`\n\n## Top skills\n\n| Skill | When to use | How to run |\n|---|---|---|\n| \\`research-codebase\\` | write a grounded research artifact for one subsystem or question | \\`/skill:research-codebase how the rate limiter works in src/middleware/\\` |\n| \\`create-spec\\` | turn research into an implementation-ready plan | \\`/skill:create-spec from research/docs/<date>-<topic>.md\\` |\n| \\`tdd\\` | do test-first feature or bug work | \\`/skill:tdd\\` |\n| \\`prompt-engineer\\` | tighten a vague prompt before a long run | \\`/skill:prompt-engineer Draft a sharper implementation prompt for ...\\` |\n| \\`workflow\\` | author, inspect, or improve workflows; start by describing the desired workflow in natural language | \\`/skill:workflow\\` |\n| \\`subagent\\` | learn delegation patterns and exact \\`/run\\`, \\`/parallel\\`, and \\`/chain\\` usage | \\`/skill:subagent\\` |\n| \\`impeccable\\` | critique or refine frontend and product UI | \\`/skill:impeccable\\` |\n\n## Built-in workflows\n\n| Workflow | When to use | How to run |\n|---|---|---|\n| \\`deep-research-codebase\\` | broad repo or cross-cutting research before you decide what to change (for one area, use \\`/skill:research-codebase\\`; this indexes the whole repo) | \\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\` |\n| \\`ralph\\` | larger implementation loops where you want implementation, review, and validation built in | \\`/workflow ralph prompt=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\` |\n| \\`open-claude-design\\` | UI and design-system work that benefits from generation and refinement loops | \\`/workflow open-claude-design prompt=\"Refresh the settings page hierarchy\"\\` |\n\nUse \\`/workflow list\\` to see what is available and \\`/workflow inputs <name>\\` to inspect inputs in your environment.\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic example\\` — see the pieces used on a code task\n\\`/atomic workflows\\` — learn when to use workflows`;\n\nconst EXAMPLE = `# Practical example\n\nThis is an example of a spec-driven development process using Atomic workflows. Use it when you are new to a repo or the task has non-trivial scope. Type the examples below into the Atomic TUI chat after starting \\`atomic\\` in your project.\n\n## 1. Research what exists\n\nUse \\`/skill:research-codebase\\` for a scoped area, subsystem, or directory:\n\n\\`/skill:research-codebase how the rate limiter works in src/middleware/\\`\n\nUse \\`deep-research-codebase\\` when the answer spans the whole repo or a cross-cutting implementation path:\n\n\\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\`\n\nIf the research prompt is vague, tighten it first with \\`/skill:prompt-engineer\\`:\n\n\\`/skill:prompt-engineer Draft a sharper repo-research prompt for understanding payment retries end to end, including retries, queues, and failure handling.\\`\n\n## 2. Create a spec when requirements are fuzzy\n\nSkip this if the implementation request is already precise.\n\n\\`/skill:create-spec from research/docs/<date>-<topic>.md\\`\n\n## 3. Implement with review built in\n\nFor ordinary work, ask Atomic directly and require validation:\n\n\\`Implement the approved spec in specs/<date>-<topic>.md. Run focused tests and summarize validation.\\`\n\nFor larger work, use subagents or a workflow:\n\n\\`/workflow ralph prompt=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\`\n\n## 4. Decide and land\n\nIf you used \\`ralph\\`, the workflow already ran parallel reviewers. Use its final result and review feedback to decide whether to ship or iterate again.\n\nIf you implemented directly instead of using \\`ralph\\`, you can still run:\n\n\\`/parallel-review current diff\\`\n\nAtomic will synthesize reviewer feedback and ask before applying fixes.\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic workflows\\` — learn when to use workflows\n\\`/atomic overview\\` — quick refresh`;\n\nconst WORKFLOWS = `# Workflows primer\n\nA workflow is a TypeScript-defined pipeline built with \\`defineWorkflow(...).run(...).compile()\\`. It can run tasks, chains, parallel fan-out, human-in-the-loop prompts, background status, and model fallback chains.\n\nStart by defining the workflow in natural language with \\`/skill:workflow\\`, the workflow creator skill. Describe the goal, inputs, stages, which steps are parallel or sequential, handoff/output shape, and any model or thinking-level preferences; let the skill help turn that into a reusable workflow before you hand-edit TypeScript.\n\n## Built-in workflows\n\n| Workflow | When to use | How to run |\n|---|---|---|\n| \\`deep-research-codebase\\` | broad repo or cross-cutting research before you decide what to change (for one area, use \\`/skill:research-codebase\\`; this indexes the whole repo) | \\`/workflow deep-research-codebase prompt=\"How do payment retries work end to end?\"\\` |\n| \\`ralph\\` | larger implementation and review loops | \\`/workflow ralph prompt=\"Implement specs/<date>-<topic>.md and validate the changed behavior\"\\` |\n| \\`open-claude-design\\` | frontend and product design work | \\`/workflow open-claude-design prompt=\"Refresh the settings page hierarchy\"\\` |\n\nUse \\`/workflow inputs <name>\\` to inspect the exact inputs in your environment.\n\nUse \\`/skill:research-codebase ...\\` when you want research on one subsystem, directory, or focused question. Use \\`/workflow deep-research-codebase ...\\` when the answer needs end-to-end tracing across many parts of the repo.\n\nIf you are drafting research, reviewer, or synthesis prompts for a workflow, use \\`/skill:prompt-engineer\\` first. It is a good fit when a stage prompt feels vague, overloaded, or underspecified.\n\n## What good workflow authoring looks like\n\nA good workflow request is explicit about stage purpose, model choice, handoff, and the decision each step must return.\n\nExample: prompt \\`/skill:workflow\\` with something like this:\n\n~~~text\nCreate a reusable workflow called review-changes.\n\nIt should accept one required text input called target for a diff, PR summary, or review target.\n\nRun two independent review stages in parallel with fresh context:\n- one reviewer focused on correctness, regressions, and missing tests using openai-codex/gpt-5.5 at xhigh thinking\n- one reviewer focused on edge cases, maintainability, and hidden risks using anthropic/claude-opus-4-7 at xhigh thinking\n\nThen add an aggregate stage that consolidates both reviews, deduplicates overlap, keeps only evidence-backed issues, and separates blockers from optional suggestions using openai/gpt-5.5 at high thinking.\n\nFinally add an adjudicate stage using anthropic/claude-sonnet-4 at high thinking that decides what to fix now, what to defer, and what to reject. Return a short action list with rationale.\n\nThe workflow should return structured output with consolidated_review and decision fields.\n~~~\n\nWhy this is good:\n- it names the workflow and required input\n- it specifies which stages are parallel vs sequential\n- each stage has one job\n- it defines the handoff and final outputs\n- it calls out model choice and thinking level where that matters\n\n## Run and inspect\n\n\\`/workflow list\\`\n\n\\`/workflow inputs ralph\\`\n\n\\`/workflow ralph prompt=\"Migrate the database layer to Drizzle\" max_loops=5\\`\n\n\\`/workflow status\\`\n\n\\`/workflow connect <run-id>\\`\n\n\\`/workflow interrupt <run-id>\\`\n\n\\`/workflow resume <run-id>\\`\n\nWorkflows run as background tasks. Use F2 or \\`/workflow connect <run-id>\\` for the graph viewer. Human-in-the-loop prompts appear there, not as chat modals.\n\n## Author your own\n\nUse \\`/skill:workflow\\` to describe your workflow in natural language and build your first workflow. This is the recommended starting point for creation and design questions: 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. Ask Atomic in chat when you want help refining or implementing one.\n\n─────────────────────────────────────────────────────────────────\n\nWhere to next:\n\n\\`/atomic example\\` — see workflows in a normal task flow\n\\`/atomic overview\\` — quick refresh`;\n\nconst GUIDE_SECTIONS = [\n\t{\n\t\tname: \"overview\",\n\t\taliases: [],\n\t\tlabel: \"overview\",\n\t\tdescription: \"30-second overview\",\n\t\trender: () => OVERVIEW,\n\t},\n\t{\n\t\tname: \"workflows\",\n\t\taliases: [\"workflow\"],\n\t\tlabel: \"workflows\",\n\t\tdescription: \"Workflow primer\",\n\t\trender: () => WORKFLOWS,\n\t},\n\t{\n\t\tname: \"example\",\n\t\taliases: [\"examples\"],\n\t\tlabel: \"example\",\n\t\tdescription: \"Practical first workflow\",\n\t\trender: () => EXAMPLE,\n\t},\n\t{\n\t\tname: \"whats-new\",\n\t\taliases: [\"what's new\", \"whats new\", \"news\", \"updates\", \"changelog\"],\n\t\tlabel: \"what's new\",\n\t\tdescription: \"Recent release notes\",\n\t\trender: readLatestStableChangelog,\n\t},\n] as const satisfies readonly {\n\treadonly name: string;\n\treadonly aliases: readonly string[];\n\treadonly label: string;\n\treadonly description: string;\n\treadonly render: (cwd: string) => string;\n}[];\n\ntype AtomicGuideSection = (typeof GUIDE_SECTIONS)[number];\ntype AtomicGuideSectionName = AtomicGuideSection[\"name\"];\n\nexport type AtomicGuideHelpChoice = AtomicGuideSection[\"label\"];\n\nexport type AtomicGuideMode = \"help\" | AtomicGuideSectionName;\n\nexport const ATOMIC_GUIDE_HELP_CHOICES: readonly AtomicGuideHelpChoice[] = GUIDE_SECTIONS.map(\n\t(section) => section.label,\n);\n\nconst GUIDE_SECTIONS_BY_NAME = new Map<AtomicGuideSectionName, AtomicGuideSection>(\n\tGUIDE_SECTIONS.map((section) => [section.name, section]),\n);\nconst GUIDE_SECTIONS_BY_LABEL = new Map<string, AtomicGuideSection>(\n\tGUIDE_SECTIONS.map((section) => [section.label, section]),\n);\nconst GUIDE_SECTIONS_BY_INPUT = new Map<string, AtomicGuideSection>(\n\tGUIDE_SECTIONS.flatMap((section) =>\n\t\t[section.name, section.label, ...section.aliases].map((input) => [input, section] as const),\n\t),\n);\n\nexport function isAtomicGuideHelpChoice(choice: string): choice is AtomicGuideHelpChoice {\n\treturn GUIDE_SECTIONS_BY_LABEL.has(choice);\n}\n\nconst ATOMIC_GUIDE_TRAILING_PUNCTUATION = \"?!.,;:\";\n\nfunction stripTrailingAtomicGuidePunctuation(value: string): string {\n\tlet end = value.length;\n\twhile (end > 0 && ATOMIC_GUIDE_TRAILING_PUNCTUATION.includes(value.charAt(end - 1))) {\n\t\tend--;\n\t}\n\treturn value.slice(0, end);\n}\n\nfunction getGuideSectionForChoice(choice: string): AtomicGuideSection | undefined {\n\treturn GUIDE_SECTIONS_BY_LABEL.get(choice);\n}\n\nfunction getGuideSectionForMode(mode: AtomicGuideSectionName): AtomicGuideSection {\n\tconst section = GUIDE_SECTIONS_BY_NAME.get(mode);\n\tif (!section) throw new Error(`Unknown Atomic guide section: ${mode}`);\n\treturn section;\n}\n\nfunction getAtomicGuideHelpMenu(): string {\n\tconst sectionHelp = GUIDE_SECTIONS.map(\n\t\t(section) => `- \\`${section.label}\\` — run \\`/atomic ${section.label}\\``,\n\t).join(\"\\n\");\n\treturn `# Atomic\\n\\nSelect where to start:\\n\\n${sectionHelp}`;\n}\n\nexport function normalizeAtomicGuideMode(args: string): AtomicGuideMode {\n\tconst normalized = stripTrailingAtomicGuidePunctuation(args.trim().toLowerCase());\n\tif (!normalized) return \"help\";\n\n\treturn GUIDE_SECTIONS_BY_INPUT.get(normalized)?.name ?? \"help\";\n}\n\nexport function getAtomicGuideArgumentCompletions(prefix: string): AutocompleteItem[] | null {\n\tconst query = prefix.trim().toLowerCase();\n\tconst items = GUIDE_SECTIONS.map((section) => ({\n\t\tvalue: section.label,\n\t\tlabel: section.label,\n\t\tdescription: section.description,\n\t}));\n\tconst filtered = query\n\t\t? items.filter((item) => item.value.startsWith(query) || item.label.startsWith(query))\n\t\t: items;\n\treturn filtered.length > 0 ? filtered : null;\n}\n\nfunction readLatestStableChangelog(cwd: string): string {\n\tconst changelogPath = getChangelogPath();\n\tconst stableSections = parseChangelog(changelogPath)\n\t\t.filter((entry) => entry.prerelease === null)\n\t\t.slice(0, 3)\n\t\t.map((entry) => entry.content.trim())\n\t\t.filter(Boolean);\n\n\tif (stableSections.length === 0) {\n\t\treturn `# What's new\\n\\nNo stable release sections were found. Try \\`/changelog\\` for the interactive changelog viewer.\\n\\n─────────────────────────────────────────────────────────────────\\n\\nWhere to next:\\n\\n\\`/atomic example\\` — see a practical first workflow\\n\\`/atomic overview\\` — quick refresh`;\n\t}\n\n\tconst relativePath = path.relative(cwd, changelogPath) || changelogPath;\n\treturn `# What's new\\n\\n${stableSections.join(\"\\n\\n\")}\\n\\nSource: \\`${relativePath}\\`\\n\\n─────────────────────────────────────────────────────────────────\\n\\nWhere to next:\\n\\n\\`/atomic example\\` — see a practical first workflow\\n\\`/atomic overview\\` — quick refresh`;\n}\n\nexport function getAtomicGuideMessage(mode: AtomicGuideMode, cwd: string): string {\n\tif (mode === \"help\") return getAtomicGuideHelpMenu();\n\treturn getGuideSectionForMode(mode).render(cwd);\n}\n\nexport function atomicGuideModeForChoice(choice: AtomicGuideHelpChoice): AtomicGuideMode {\n\treturn getGuideSectionForChoice(choice)?.name ?? \"help\";\n}\n\n"]}

package/dist/core/slash-commands.d.ts

@@ -1,3 +1,4 @@
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
 import type { SourceInfo } from "./source-info.js";
 export type SlashCommandSource = "extension" | "prompt" | "skill";
 export interface SlashCommandInfo {
@@ -9,6 +10,7 @@ export interface SlashCommandInfo {
 export interface BuiltinSlashCommand {
     name: string;
     description: string;
+    getArgumentCompletions?: (argumentPrefix: string) => AutocompleteItem[] | null | Promise<AutocompleteItem[] | null>;
 }
 export declare const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand>;
 //# sourceMappingURL=slash-commands.d.ts.map

package/dist/core/slash-commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slash-commands.d.ts","sourceRoot":"","sources":["../../src/core/slash-commands.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAElE,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,UAAU,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,sBAAsB,EAAE,aAAa,CAAC,mBAAmB,CAsBrE,CAAC","sourcesContent":["import { APP_NAME } from \"../config.js\";\nimport type { SourceInfo } from \"./source-info.js\";\n\nexport type SlashCommandSource = \"extension\" | \"prompt\" | \"skill\";\n\nexport interface SlashCommandInfo {\n\tname: string;\n\tdescription?: string;\n\tsource: SlashCommandSource;\n\tsourceInfo: SourceInfo;\n}\n\nexport interface BuiltinSlashCommand {\n\tname: string;\n\tdescription: string;\n}\n\nexport const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [\n\t{ name: \"settings\", description: \"Open settings menu\" },\n\t{ name: \"model\", description: \"Select model (opens selector UI)\" },\n\t{ name: \"scoped-models\", description: \"Enable/disable models for ctrl+p cycling\" },\n\t{ name: \"export\", description: \"Export session (HTML default, or specify path: .html/.jsonl)\" },\n\t{ name: \"import\", description: \"Import and resume a session from a JSONL file\" },\n\t{ name: \"share\", description: \"Share session as a secret GitHub gist\" },\n\t{ name: \"copy\", description: \"Copy last agent message to clipboard\" },\n\t{ name: \"name\", description: \"Set session display name\" },\n\t{ name: \"session\", description: \"Show session info and stats\" },\n\t{ name: \"changelog\", description: \"Show changelog entries\" },\n\t{ name: \"hotkeys\", description: \"Show all keyboard shortcuts\" },\n\t{ name: \"fork\", description: \"Create a new fork from a previous user message\" },\n\t{ name: \"clone\", description: \"Duplicate the current session at the current position\" },\n\t{ name: \"tree\", description: \"Navigate session tree (switch branches)\" },\n\t{ name: \"login\", description: \"Configure provider authentication\" },\n\t{ name: \"logout\", description: \"Remove provider authentication\" },\n\t{ name: \"new\", description: \"Start a new session\" },\n\t{ name: \"compact\", description: \"Manually compact the session context\" },\n\t{ name: \"resume\", description: \"Resume a different session\" },\n\t{ name: \"reload\", description: \"Reload keybindings, extensions, skills, prompts, and themes\" },\n\t{ name: \"quit\", description: `Quit ${APP_NAME}` },\n];\n"]}
+{"version":3,"file":"slash-commands.d.ts","sourceRoot":"","sources":["../../src/core/slash-commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAO/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAElE,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,UAAU,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB,CAAC,EAAE,CACxB,cAAc,EAAE,MAAM,KAClB,gBAAgB,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,gBAAgB,EAAE,GAAG,IAAI,CAAC,CAAC;CACpE;AAED,eAAO,MAAM,sBAAsB,EAAE,aAAa,CAAC,mBAAmB,CA2BrE,CAAC","sourcesContent":["import type { AutocompleteItem } from \"@earendil-works/pi-tui\";\nimport { APP_NAME } from \"../config.js\";\nimport {\n\tATOMIC_GUIDE_COMMAND_DESCRIPTION,\n\tATOMIC_GUIDE_COMMAND_NAME,\n\tgetAtomicGuideArgumentCompletions,\n} from \"./atomic-guide-command.js\";\nimport type { SourceInfo } from \"./source-info.js\";\n\nexport type SlashCommandSource = \"extension\" | \"prompt\" | \"skill\";\n\nexport interface SlashCommandInfo {\n\tname: string;\n\tdescription?: string;\n\tsource: SlashCommandSource;\n\tsourceInfo: SourceInfo;\n}\n\nexport interface BuiltinSlashCommand {\n\tname: string;\n\tdescription: string;\n\tgetArgumentCompletions?: (\n\t\targumentPrefix: string,\n\t) => AutocompleteItem[] | null | Promise<AutocompleteItem[] | null>;\n}\n\nexport const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [\n\t{ name: \"settings\", description: \"Open settings menu\" },\n\t{ name: \"model\", description: \"Select model (opens selector UI)\" },\n\t{ name: \"scoped-models\", description: \"Enable/disable models for ctrl+p cycling\" },\n\t{ name: \"export\", description: \"Export session (HTML default, or specify path: .html/.jsonl)\" },\n\t{ name: \"import\", description: \"Import and resume a session from a JSONL file\" },\n\t{ name: \"share\", description: \"Share session as a secret GitHub gist\" },\n\t{ name: \"copy\", description: \"Copy last agent message to clipboard\" },\n\t{ name: \"name\", description: \"Set session display name\" },\n\t{ name: \"session\", description: \"Show session info and stats\" },\n\t{ name: \"changelog\", description: \"Show changelog entries\" },\n\t{\n\t\tname: ATOMIC_GUIDE_COMMAND_NAME,\n\t\tdescription: ATOMIC_GUIDE_COMMAND_DESCRIPTION,\n\t\tgetArgumentCompletions: getAtomicGuideArgumentCompletions,\n\t},\n\t{ name: \"hotkeys\", description: \"Show all keyboard shortcuts\" },\n\t{ name: \"fork\", description: \"Create a new fork from a previous user message\" },\n\t{ name: \"clone\", description: \"Duplicate the current session at the current position\" },\n\t{ name: \"tree\", description: \"Navigate session tree (switch branches)\" },\n\t{ name: \"login\", description: \"Configure provider authentication\" },\n\t{ name: \"logout\", description: \"Remove provider authentication\" },\n\t{ name: \"new\", description: \"Start a new session\" },\n\t{ name: \"compact\", description: \"Manually compact the session context\" },\n\t{ name: \"resume\", description: \"Resume a different session\" },\n\t{ name: \"reload\", description: \"Reload keybindings, extensions, skills, prompts, and themes\" },\n\t{ name: \"quit\", description: `Quit ${APP_NAME}` },\n];\n"]}

package/dist/core/slash-commands.js

@@ -1,4 +1,5 @@
 import { APP_NAME } from "../config.js";
+import { ATOMIC_GUIDE_COMMAND_DESCRIPTION, ATOMIC_GUIDE_COMMAND_NAME, getAtomicGuideArgumentCompletions, } from "./atomic-guide-command.js";
 export const BUILTIN_SLASH_COMMANDS = [
     { name: "settings", description: "Open settings menu" },
     { name: "model", description: "Select model (opens selector UI)" },
@@ -10,6 +11,11 @@ export const BUILTIN_SLASH_COMMANDS = [
     { name: "name", description: "Set session display name" },
     { name: "session", description: "Show session info and stats" },
     { name: "changelog", description: "Show changelog entries" },
+    {
+        name: ATOMIC_GUIDE_COMMAND_NAME,
+        description: ATOMIC_GUIDE_COMMAND_DESCRIPTION,
+        getArgumentCompletions: getAtomicGuideArgumentCompletions,
+    },
     { name: "hotkeys", description: "Show all keyboard shortcuts" },
     { name: "fork", description: "Create a new fork from a previous user message" },
     { name: "clone", description: "Duplicate the current session at the current position" },

package/dist/core/slash-commands.js.map

@@ -1 +1 @@
-{"version":3,"file":"slash-commands.js","sourceRoot":"","sources":["../../src/core/slash-commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAiBxC,MAAM,CAAC,MAAM,sBAAsB,GAAuC;IACzE,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,oBAAoB,EAAE;IACvD,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,kCAAkC,EAAE;IAClE,EAAE,IAAI,EAAE,eAAe,EAAE,WAAW,EAAE,0CAA0C,EAAE;IAClF,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,8DAA8D,EAAE;IAC/F,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,+CAA+C,EAAE;IAChF,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,uCAAuC,EAAE;IACvE,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,sCAAsC,EAAE;IACrE,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,0BAA0B,EAAE;IACzD,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,6BAA6B,EAAE;IAC/D,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,wBAAwB,EAAE;IAC5D,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,6BAA6B,EAAE;IAC/D,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,gDAAgD,EAAE;IAC/E,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,uDAAuD,EAAE;IACvF,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,yCAAyC,EAAE;IACxE,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,mCAAmC,EAAE;IACnE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gCAAgC,EAAE;IACjE,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE;IACnD,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,sCAAsC,EAAE;IACxE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,4BAA4B,EAAE;IAC7D,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,6DAA6D,EAAE;IAC9F,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,QAAQ,EAAE,EAAE;CACjD,CAAC","sourcesContent":["import { APP_NAME } from \"../config.js\";\nimport type { SourceInfo } from \"./source-info.js\";\n\nexport type SlashCommandSource = \"extension\" | \"prompt\" | \"skill\";\n\nexport interface SlashCommandInfo {\n\tname: string;\n\tdescription?: string;\n\tsource: SlashCommandSource;\n\tsourceInfo: SourceInfo;\n}\n\nexport interface BuiltinSlashCommand {\n\tname: string;\n\tdescription: string;\n}\n\nexport const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [\n\t{ name: \"settings\", description: \"Open settings menu\" },\n\t{ name: \"model\", description: \"Select model (opens selector UI)\" },\n\t{ name: \"scoped-models\", description: \"Enable/disable models for ctrl+p cycling\" },\n\t{ name: \"export\", description: \"Export session (HTML default, or specify path: .html/.jsonl)\" },\n\t{ name: \"import\", description: \"Import and resume a session from a JSONL file\" },\n\t{ name: \"share\", description: \"Share session as a secret GitHub gist\" },\n\t{ name: \"copy\", description: \"Copy last agent message to clipboard\" },\n\t{ name: \"name\", description: \"Set session display name\" },\n\t{ name: \"session\", description: \"Show session info and stats\" },\n\t{ name: \"changelog\", description: \"Show changelog entries\" },\n\t{ name: \"hotkeys\", description: \"Show all keyboard shortcuts\" },\n\t{ name: \"fork\", description: \"Create a new fork from a previous user message\" },\n\t{ name: \"clone\", description: \"Duplicate the current session at the current position\" },\n\t{ name: \"tree\", description: \"Navigate session tree (switch branches)\" },\n\t{ name: \"login\", description: \"Configure provider authentication\" },\n\t{ name: \"logout\", description: \"Remove provider authentication\" },\n\t{ name: \"new\", description: \"Start a new session\" },\n\t{ name: \"compact\", description: \"Manually compact the session context\" },\n\t{ name: \"resume\", description: \"Resume a different session\" },\n\t{ name: \"reload\", description: \"Reload keybindings, extensions, skills, prompts, and themes\" },\n\t{ name: \"quit\", description: `Quit ${APP_NAME}` },\n];\n"]}
+{"version":3,"file":"slash-commands.js","sourceRoot":"","sources":["../../src/core/slash-commands.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EACN,gCAAgC,EAChC,yBAAyB,EACzB,iCAAiC,GACjC,MAAM,2BAA2B,CAAC;AAoBnC,MAAM,CAAC,MAAM,sBAAsB,GAAuC;IACzE,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,oBAAoB,EAAE;IACvD,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,kCAAkC,EAAE;IAClE,EAAE,IAAI,EAAE,eAAe,EAAE,WAAW,EAAE,0CAA0C,EAAE;IAClF,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,8DAA8D,EAAE;IAC/F,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,+CAA+C,EAAE;IAChF,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,uCAAuC,EAAE;IACvE,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,sCAAsC,EAAE;IACrE,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,0BAA0B,EAAE;IACzD,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,6BAA6B,EAAE;IAC/D,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,wBAAwB,EAAE;IAC5D;QACC,IAAI,EAAE,yBAAyB;QAC/B,WAAW,EAAE,gCAAgC;QAC7C,sBAAsB,EAAE,iCAAiC;KACzD;IACD,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,6BAA6B,EAAE;IAC/D,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,gDAAgD,EAAE;IAC/E,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,uDAAuD,EAAE;IACvF,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,yCAAyC,EAAE;IACxE,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,mCAAmC,EAAE;IACnE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gCAAgC,EAAE;IACjE,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE;IACnD,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,sCAAsC,EAAE;IACxE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,4BAA4B,EAAE;IAC7D,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,6DAA6D,EAAE;IAC9F,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,QAAQ,EAAE,EAAE;CACjD,CAAC","sourcesContent":["import type { AutocompleteItem } from \"@earendil-works/pi-tui\";\nimport { APP_NAME } from \"../config.js\";\nimport {\n\tATOMIC_GUIDE_COMMAND_DESCRIPTION,\n\tATOMIC_GUIDE_COMMAND_NAME,\n\tgetAtomicGuideArgumentCompletions,\n} from \"./atomic-guide-command.js\";\nimport type { SourceInfo } from \"./source-info.js\";\n\nexport type SlashCommandSource = \"extension\" | \"prompt\" | \"skill\";\n\nexport interface SlashCommandInfo {\n\tname: string;\n\tdescription?: string;\n\tsource: SlashCommandSource;\n\tsourceInfo: SourceInfo;\n}\n\nexport interface BuiltinSlashCommand {\n\tname: string;\n\tdescription: string;\n\tgetArgumentCompletions?: (\n\t\targumentPrefix: string,\n\t) => AutocompleteItem[] | null | Promise<AutocompleteItem[] | null>;\n}\n\nexport const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [\n\t{ name: \"settings\", description: \"Open settings menu\" },\n\t{ name: \"model\", description: \"Select model (opens selector UI)\" },\n\t{ name: \"scoped-models\", description: \"Enable/disable models for ctrl+p cycling\" },\n\t{ name: \"export\", description: \"Export session (HTML default, or specify path: .html/.jsonl)\" },\n\t{ name: \"import\", description: \"Import and resume a session from a JSONL file\" },\n\t{ name: \"share\", description: \"Share session as a secret GitHub gist\" },\n\t{ name: \"copy\", description: \"Copy last agent message to clipboard\" },\n\t{ name: \"name\", description: \"Set session display name\" },\n\t{ name: \"session\", description: \"Show session info and stats\" },\n\t{ name: \"changelog\", description: \"Show changelog entries\" },\n\t{\n\t\tname: ATOMIC_GUIDE_COMMAND_NAME,\n\t\tdescription: ATOMIC_GUIDE_COMMAND_DESCRIPTION,\n\t\tgetArgumentCompletions: getAtomicGuideArgumentCompletions,\n\t},\n\t{ name: \"hotkeys\", description: \"Show all keyboard shortcuts\" },\n\t{ name: \"fork\", description: \"Create a new fork from a previous user message\" },\n\t{ name: \"clone\", description: \"Duplicate the current session at the current position\" },\n\t{ name: \"tree\", description: \"Navigate session tree (switch branches)\" },\n\t{ name: \"login\", description: \"Configure provider authentication\" },\n\t{ name: \"logout\", description: \"Remove provider authentication\" },\n\t{ name: \"new\", description: \"Start a new session\" },\n\t{ name: \"compact\", description: \"Manually compact the session context\" },\n\t{ name: \"resume\", description: \"Resume a different session\" },\n\t{ name: \"reload\", description: \"Reload keybindings, extensions, skills, prompts, and themes\" },\n\t{ name: \"quit\", description: `Quit ${APP_NAME}` },\n];\n"]}

package/dist/core/system-prompt.d.ts

@@ -25,6 +25,8 @@ export interface BuildSystemPromptOptions {
     cwd: string;
     /** Currently selected model, used for model-aware prompt metadata. */
     selectedModel?: SystemPromptModel;
+    /** Current reasoning/thinking level for the selected model. */
+    selectedThinkingLevel?: string;
     /** Pre-loaded context files. */
     contextFiles?: Array<{
         path: string;

package/dist/core/system-prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/core/system-prompt.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAyB,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAEhE,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8FAA8F;IAC9F,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,uCAAuC;IACvC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,gCAAgC;IAChC,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,yBAAyB;IACzB,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;CAClB;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CAgO3E","sourcesContent":["/**\n * System prompt construction and project context loading\n */\n\nimport { getDocsPath, getExamplesPath, getReadmePath } from \"../config.js\";\nimport { formatSkillsForPrompt, type Skill } from \"./skills.js\";\n\nexport interface SystemPromptModel {\n  /** Provider identifier for the selected model. */\n  provider: string;\n  /** Stable provider-specific model identifier. */\n  id: string;\n  /** Human-readable model name, when available. */\n  name?: string;\n}\n\nexport interface BuildSystemPromptOptions {\n  /** Custom system prompt (replaces default). */\n  customPrompt?: string;\n  /** Tools to include in prompt. Default: [read, bash, edit, write, ask_user_question, todo] */\n  selectedTools?: string[];\n  /** Optional one-line tool snippets keyed by tool name. */\n  toolSnippets?: Record<string, string>;\n  /** Additional guideline bullets appended to the default system prompt guidelines. */\n  promptGuidelines?: string[];\n  /** Text to append to system prompt. */\n  appendSystemPrompt?: string;\n  /** Working directory. */\n  cwd: string;\n  /** Currently selected model, used for model-aware prompt metadata. */\n  selectedModel?: SystemPromptModel;\n  /** Pre-loaded context files. */\n  contextFiles?: Array<{ path: string; content: string }>;\n  /** Pre-loaded skills. */\n  skills?: Skill[];\n}\n\n/** Build the system prompt with tools, guidelines, and context */\nexport function buildSystemPrompt(options: BuildSystemPromptOptions): string {\n  const {\n    customPrompt,\n    selectedTools,\n    toolSnippets,\n    promptGuidelines,\n    appendSystemPrompt,\n    cwd,\n    selectedModel,\n    contextFiles: providedContextFiles,\n    skills: providedSkills,\n  } = options;\n  const resolvedCwd = cwd;\n  const promptCwd = resolvedCwd.replace(/\\\\/g, \"/\");\n\n  const now = new Date();\n  const year = now.getFullYear();\n  const month = String(now.getMonth() + 1).padStart(2, \"0\");\n  const day = String(now.getDate()).padStart(2, \"0\");\n  const date = `${year}-${month}-${day}`;\n\n  const appendSection = appendSystemPrompt ? `\\n\\n${appendSystemPrompt}` : \"\";\n  const modelName =\n    selectedModel?.name?.trim() || selectedModel?.id || \"unknown\";\n\n  const contextFiles = providedContextFiles ?? [];\n  const skills = providedSkills ?? [];\n\n  if (customPrompt) {\n    let prompt = customPrompt;\n\n    if (appendSection) {\n      prompt += appendSection;\n    }\n\n    // Append project context files\n    if (contextFiles.length > 0) {\n      prompt += \"\\n\\n# Project Context\\n\\n\";\n      prompt += \"Project-specific instructions and guidelines:\\n\\n\";\n      for (const { path: filePath, content } of contextFiles) {\n        prompt += `## ${filePath}\\n\\n${content}\\n\\n`;\n      }\n    }\n\n    // Append skills section (only if read tool is available)\n    const customPromptHasRead =\n      !selectedTools || selectedTools.includes(\"read\");\n    if (customPromptHasRead && skills.length > 0) {\n      prompt += formatSkillsForPrompt(skills);\n    }\n\n    // Add model name, date, and working directory last\n    prompt += `\\nModel name (used for commit attribution): ${modelName}`;\n    prompt += `\\nCurrent date: ${date}`;\n    prompt += `\\nCurrent working directory: ${promptCwd}`;\n\n    return prompt;\n  }\n\n  // Get absolute paths to documentation and examples\n  const readmePath = getReadmePath();\n  const docsPath = getDocsPath();\n  const examplesPath = getExamplesPath();\n\n  // Build tools list based on selected tools.\n  // A tool appears in Available tools only when the caller provides a one-line snippet.\n  const tools = selectedTools || [\n    \"read\",\n    \"bash\",\n    \"edit\",\n    \"write\",\n    \"ask_user_question\",\n    \"todo\",\n  ];\n  const visibleTools = tools.filter((name) => !!toolSnippets?.[name]);\n  const toolsList =\n    visibleTools.length > 0\n      ? visibleTools\n          .map((name) => `- ${name}: ${toolSnippets![name]}`)\n          .join(\"\\n\")\n      : \"(none)\";\n\n  // Build guidelines based on which tools are actually available\n  const guidelinesList: string[] = [];\n  const guidelinesSet = new Set<string>();\n  const addGuideline = (guideline: string): void => {\n    if (guidelinesSet.has(guideline)) {\n      return;\n    }\n    guidelinesSet.add(guideline);\n    guidelinesList.push(guideline);\n  };\n\n  const hasBash = tools.includes(\"bash\");\n  const hasGrep = tools.includes(\"grep\");\n  const hasFind = tools.includes(\"find\");\n  const hasLs = tools.includes(\"ls\");\n  const hasRead = tools.includes(\"read\");\n\n  // File exploration guidelines\n  if (hasBash && !hasGrep && !hasFind && !hasLs) {\n    addGuideline(\"Use bash for file operations like ls, rg, find\");\n  } else if (hasBash && (hasGrep || hasFind || hasLs)) {\n    addGuideline(\n      \"Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)\",\n    );\n  }\n\n  for (const guideline of promptGuidelines ?? []) {\n    const normalized = guideline.trim();\n    if (normalized.length > 0) {\n      addGuideline(normalized);\n    }\n  }\n\n  // Always include these\n  addGuideline(\"Be concise in your responses\");\n  addGuideline(\"Show file paths clearly when working with files\");\n\n  const guidelines = guidelinesList.map((g) => `- ${g}`).join(\"\\n\");\n\n  const engineering_guidelines = `<user_experience>\n- Always ask clarifying questions (using the ask_user_question tool if available) if the user's request is ambiguous or lacks necessary details. NEVER make assumptions about what the user wants.\n- If you find yourself circling in thought and asking what the user \"really\" wants, stop and ask the user for clarification. It's better to clarify intent rather than to guess.\n</user_experience>\n\n<tool_policies>\nFollow these tool selection and usage rules in order of priority:\n\n1. **To-do management**: If the user has a complex task that can be broken down into actionable steps, ALWAYS use the \\`todo\\` tool to create a task list before proceeding. This ensures clarity and alignment with the user's goals and that you have a way to track your work and ensure you are meeting the user's expectations.\n\n2. **Browser search and automation**:\n\nUse web search tools, playwright-cli (refer to playwright-cli skill) for ALL browser automation tasks, including web research, form filling, and UI interaction:\n   - ALWAYS load the playwright-cli skill before usage.\n   - ALWAYS ASSUME playwright-cli is installed. If the \\`playwright-cli\\` command fails, fall back to \\`npx playwright-cli\\`.\n\n3. **Testing**: ALWAYS invoke your tdd skill BEFORE creating or modifying any tests.\n\n4. **Sub-agent Orchestration**: To avoid draining your context window, prefer to use subagents for complex tasks all non-trivial operations should be delegated to subagents.\n\nYou should delegate running bash commands (particularly ones that are likely to produce lots of output) such as investigating with the \\`aws\\` CLI, using the \\`gh\\` CLI, digging through logs to \\`bash\\` subagents.\n\nYou should use separate subagents for separate tasks, and you may launch them in parallel, but do not delegate multiple tasks that are likely to have significant overlap to separate subagents.\n\nIMPORTANT: if the user has already given you a task, you should proceed with that task using this approach.\nIMPORTANT: sometimes subagents will take a long time. DO NOT attempt to do the job yourself while waiting for the subagent to respond. Instead, use the time to plan out your next steps, or ask the user follow-up questions to clarify the task requirements.\n\nIf you have not already been explicitly given a task, you should ask the user what task they would like for you to work on--do not assume or begin working on a ticket automatically without a clear problem statement and verifiable acceptance criteria from the user.\n\n5. **Debugging**: When a user asks about debugging, spawn a debugger subagent first.\n   - Do not attempt to debug or analyze code yourself without first consulting the debugger subagent.\n   - Explain the debugger's insights to the user clearly and concisely.\n   - Once the user confirms, implement the necessary code changes based on those insights.\n   - If the user has follow-up questions, spawn additional debugger and research subagents as needed.\n</tool_policies>\n\n<engineering_principles>\nSoftware engineering is fundamentally about **managing complexity** to prevent technical debt. When implementing features, prioritize maintainability and testability over cleverness.\n\n**Core Principles:**\n- **Single Responsibility (SRP):** Every class and module must have exactly one reason to change. If a unit does more than one job, split it.\n- **Dependency Inversion (DIP):** Depend on abstractions (interfaces), never on concrete implementations. Inject dependencies; do not instantiate them internally.\n- **KISS:** Keep solutions as simple as possible. Reject unnecessary abstraction layers.\n- **YAGNI:** Do not build generic frameworks or add configurability for hypothetical future requirements. Solve the problem at hand.\n\n**Design Patterns** — Use Gang of Four patterns as a shared vocabulary for recurring problems:\n- **Creational:** Use _Factory_ or _Builder_ to abstract complex object creation and isolate construction logic.\n- **Structural:** Use _Adapter_ or _Facade_ to decouple core logic from external APIs or legacy code.\n- **Behavioral:** Use _Strategy_ to make algorithms interchangeable. Use _Observer_ for event-driven communication between decoupled components.\n\n**Architectural Hygiene:**\n- **Separation of Concerns:** Isolate business logic (Domain) from infrastructure (Database, UI, networking). Never let infrastructure details leak into domain code.\n- **Anti-Pattern Detection:** Watch for **God Objects** (classes with too many responsibilities) and **Spaghetti Code** (tightly coupled, hard-to-follow control flow). Refactor them using polymorphism and clear interfaces.\n\nCreate **seams** in your software using interfaces and abstractions. This ensures code remains flexible, testable, and capable of evolving independently.\n</engineering_principles>`;\n\n  let prompt = `You are an expert coding assistant operating named Atomic (users may also refer to you as Pi), a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.\n\nAvailable tools:\n${toolsList}\n\nIn addition to the tools above, you may have access to other custom tools depending on the project.\n\nGuidelines:\n${guidelines}\n\nEngineering guidelines:\n${engineering_guidelines}\n\nAtomic (users may also call you Pi) documentation (read only when the user asks about atomic/pi itself, its SDK, extensions, themes, skills, or TUI):\n- Main documentation: ${readmePath}\n- Additional docs: ${docsPath}\n- Examples: ${examplesPath} (extensions, custom tools, SDK)\n- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)\n- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing\n- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)\n- Prefer to use .atomic over .pi (backwards compatible) for creations, the two are fully compatible`;\n\n  if (appendSection) {\n    prompt += appendSection;\n  }\n\n  // Append project context files\n  if (contextFiles.length > 0) {\n    prompt += \"\\n\\n# Project Context\\n\\n\";\n    prompt += \"Project-specific instructions and guidelines:\\n\\n\";\n    for (const { path: filePath, content } of contextFiles) {\n      prompt += `## ${filePath}\\n\\n${content}\\n\\n`;\n    }\n  }\n\n  // Append skills section (only if read tool is available)\n  if (hasRead && skills.length > 0) {\n    prompt += formatSkillsForPrompt(skills);\n  }\n\n  // Add model name, date, and working directory last\n  prompt += `\\nModel name (used for commit attribution): ${modelName}`;\n  prompt += `\\nCurrent date: ${date}`;\n  prompt += `\\nCurrent working directory: ${promptCwd}`;\n\n  return prompt;\n}\n"]}
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/core/system-prompt.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAyB,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAEhE,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8FAA8F;IAC9F,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,uCAAuC;IACvC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,+DAA+D;IAC/D,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,gCAAgC;IAChC,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,yBAAyB;IACzB,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;CAClB;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CAqO3E","sourcesContent":["/**\n * System prompt construction and project context loading\n */\n\nimport { getDocsPath, getExamplesPath, getReadmePath } from \"../config.js\";\nimport { formatSkillsForPrompt, type Skill } from \"./skills.js\";\n\nexport interface SystemPromptModel {\n  /** Provider identifier for the selected model. */\n  provider: string;\n  /** Stable provider-specific model identifier. */\n  id: string;\n  /** Human-readable model name, when available. */\n  name?: string;\n}\n\nexport interface BuildSystemPromptOptions {\n  /** Custom system prompt (replaces default). */\n  customPrompt?: string;\n  /** Tools to include in prompt. Default: [read, bash, edit, write, ask_user_question, todo] */\n  selectedTools?: string[];\n  /** Optional one-line tool snippets keyed by tool name. */\n  toolSnippets?: Record<string, string>;\n  /** Additional guideline bullets appended to the default system prompt guidelines. */\n  promptGuidelines?: string[];\n  /** Text to append to system prompt. */\n  appendSystemPrompt?: string;\n  /** Working directory. */\n  cwd: string;\n  /** Currently selected model, used for model-aware prompt metadata. */\n  selectedModel?: SystemPromptModel;\n  /** Current reasoning/thinking level for the selected model. */\n  selectedThinkingLevel?: string;\n  /** Pre-loaded context files. */\n  contextFiles?: Array<{ path: string; content: string }>;\n  /** Pre-loaded skills. */\n  skills?: Skill[];\n}\n\n/** Build the system prompt with tools, guidelines, and context */\nexport function buildSystemPrompt(options: BuildSystemPromptOptions): string {\n  const {\n    customPrompt,\n    selectedTools,\n    toolSnippets,\n    promptGuidelines,\n    appendSystemPrompt,\n    cwd,\n    selectedModel,\n    selectedThinkingLevel,\n    contextFiles: providedContextFiles,\n    skills: providedSkills,\n  } = options;\n  const resolvedCwd = cwd;\n  const promptCwd = resolvedCwd.replace(/\\\\/g, \"/\");\n\n  const now = new Date();\n  const year = now.getFullYear();\n  const month = String(now.getMonth() + 1).padStart(2, \"0\");\n  const day = String(now.getDate()).padStart(2, \"0\");\n  const date = `${year}-${month}-${day}`;\n\n  const appendSection = appendSystemPrompt ? `\\n\\n${appendSystemPrompt}` : \"\";\n  const modelName =\n    selectedModel?.name?.trim() || selectedModel?.id || \"unknown\";\n  const modelReasoningLevel = selectedThinkingLevel?.trim() || \"off\";\n\n  const contextFiles = providedContextFiles ?? [];\n  const skills = providedSkills ?? [];\n\n  if (customPrompt) {\n    let prompt = customPrompt;\n\n    if (appendSection) {\n      prompt += appendSection;\n    }\n\n    // Append project context files\n    if (contextFiles.length > 0) {\n      prompt += \"\\n\\n# Project Context\\n\\n\";\n      prompt += \"Project-specific instructions and guidelines:\\n\\n\";\n      for (const { path: filePath, content } of contextFiles) {\n        prompt += `## ${filePath}\\n\\n${content}\\n\\n`;\n      }\n    }\n\n    // Append skills section (only if read tool is available)\n    const customPromptHasRead =\n      !selectedTools || selectedTools.includes(\"read\");\n    if (customPromptHasRead && skills.length > 0) {\n      prompt += formatSkillsForPrompt(skills);\n    }\n\n    // Add model metadata, date, and working directory last\n    prompt += `\\nModel name (used for commit attribution): ${modelName}`;\n    prompt += `\\nModel reasoning level: ${modelReasoningLevel}`;\n    prompt += `\\nCurrent date: ${date}`;\n    prompt += `\\nCurrent working directory: ${promptCwd}`;\n\n    return prompt;\n  }\n\n  // Get absolute paths to documentation and examples\n  const readmePath = getReadmePath();\n  const docsPath = getDocsPath();\n  const examplesPath = getExamplesPath();\n\n  // Build tools list based on selected tools.\n  // A tool appears in Available tools only when the caller provides a one-line snippet.\n  const tools = selectedTools || [\n    \"read\",\n    \"bash\",\n    \"edit\",\n    \"write\",\n    \"ask_user_question\",\n    \"todo\",\n  ];\n  const visibleTools = tools.filter((name) => !!toolSnippets?.[name]);\n  const toolsList =\n    visibleTools.length > 0\n      ? visibleTools\n          .map((name) => `- ${name}: ${toolSnippets![name]}`)\n          .join(\"\\n\")\n      : \"(none)\";\n\n  // Build guidelines based on which tools are actually available\n  const guidelinesList: string[] = [];\n  const guidelinesSet = new Set<string>();\n  const addGuideline = (guideline: string): void => {\n    if (guidelinesSet.has(guideline)) {\n      return;\n    }\n    guidelinesSet.add(guideline);\n    guidelinesList.push(guideline);\n  };\n\n  const hasBash = tools.includes(\"bash\");\n  const hasGrep = tools.includes(\"grep\");\n  const hasFind = tools.includes(\"find\");\n  const hasLs = tools.includes(\"ls\");\n  const hasRead = tools.includes(\"read\");\n\n  // File exploration guidelines\n  if (hasBash && !hasGrep && !hasFind && !hasLs) {\n    addGuideline(\"Use bash for file operations like ls, rg, find\");\n  } else if (hasBash && (hasGrep || hasFind || hasLs)) {\n    addGuideline(\n      \"Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)\",\n    );\n  }\n\n  for (const guideline of promptGuidelines ?? []) {\n    const normalized = guideline.trim();\n    if (normalized.length > 0) {\n      addGuideline(normalized);\n    }\n  }\n\n  // Always include these\n  addGuideline(\"Be concise in your responses\");\n  addGuideline(\"Show file paths clearly when working with files\");\n\n  const guidelines = guidelinesList.map((g) => `- ${g}`).join(\"\\n\");\n\n  const engineering_guidelines = `<user_experience>\n- Always ask clarifying questions (using the ask_user_question tool if available) if the user's request is ambiguous or lacks necessary details. NEVER make assumptions about what the user wants.\n- If you find yourself circling in thought and asking what the user \"really\" wants, stop and ask the user for clarification. It's better to clarify intent rather than to guess.\n</user_experience>\n\n<tool_policies>\nFollow these tool selection and usage rules in order of priority:\n\n1. **To-do management**: If the user has a complex task that can be broken down into actionable steps, ALWAYS use the \\`todo\\` tool to create a task list before proceeding. This ensures clarity and alignment with the user's goals and that you have a way to track your work and ensure you are meeting the user's expectations.\n\n2. **Browser search and automation**:\n\nUse web search tools, playwright-cli (refer to playwright-cli skill) for ALL browser automation tasks, including web research, form filling, and UI interaction:\n   - ALWAYS load the playwright-cli skill before usage.\n   - ALWAYS ASSUME playwright-cli is installed. If the \\`playwright-cli\\` command fails, fall back to \\`npx playwright-cli\\`.\n\n3. **Testing**: ALWAYS invoke your tdd skill BEFORE creating or modifying any tests.\n\n4. **Sub-agent Orchestration**: To avoid draining your context window, prefer to use subagents for complex tasks all non-trivial operations should be delegated to subagents.\n\nYou should delegate running bash commands (particularly ones that are likely to produce lots of output) such as investigating with the \\`aws\\` CLI, using the \\`gh\\` CLI, digging through logs to \\`bash\\` subagents.\n\nYou should use separate subagents for separate tasks, and you may launch them in parallel, but do not delegate multiple tasks that are likely to have significant overlap to separate subagents.\n\nIMPORTANT: if the user has already given you a task, you should proceed with that task using this approach.\nIMPORTANT: sometimes subagents will take a long time. DO NOT attempt to do the job yourself while waiting for the subagent to respond. Instead, use the time to plan out your next steps, or ask the user follow-up questions to clarify the task requirements.\n\nIf you have not already been explicitly given a task, you should ask the user what task they would like for you to work on--do not assume or begin working on a ticket automatically without a clear problem statement and verifiable acceptance criteria from the user.\n\n5. **Debugging**: When a user asks about debugging, spawn a debugger subagent first.\n   - Do not attempt to debug or analyze code yourself without first consulting the debugger subagent.\n   - Explain the debugger's insights to the user clearly and concisely.\n   - Once the user confirms, implement the necessary code changes based on those insights.\n   - If the user has follow-up questions, spawn additional debugger and research subagents as needed.\n</tool_policies>\n\n<engineering_principles>\nSoftware engineering is fundamentally about **managing complexity** to prevent technical debt. When implementing features, prioritize maintainability and testability over cleverness.\n\n**Core Principles:**\n- **Single Responsibility (SRP):** Every class and module must have exactly one reason to change. If a unit does more than one job, split it.\n- **Dependency Inversion (DIP):** Depend on abstractions (interfaces), never on concrete implementations. Inject dependencies; do not instantiate them internally.\n- **KISS:** Keep solutions as simple as possible. Reject unnecessary abstraction layers.\n- **YAGNI:** Do not build generic frameworks or add configurability for hypothetical future requirements. Solve the problem at hand.\n\n**Design Patterns** — Use Gang of Four patterns as a shared vocabulary for recurring problems:\n- **Creational:** Use _Factory_ or _Builder_ to abstract complex object creation and isolate construction logic.\n- **Structural:** Use _Adapter_ or _Facade_ to decouple core logic from external APIs or legacy code.\n- **Behavioral:** Use _Strategy_ to make algorithms interchangeable. Use _Observer_ for event-driven communication between decoupled components.\n\n**Architectural Hygiene:**\n- **Separation of Concerns:** Isolate business logic (Domain) from infrastructure (Database, UI, networking). Never let infrastructure details leak into domain code.\n- **Anti-Pattern Detection:** Watch for **God Objects** (classes with too many responsibilities) and **Spaghetti Code** (tightly coupled, hard-to-follow control flow). Refactor them using polymorphism and clear interfaces.\n\nCreate **seams** in your software using interfaces and abstractions. This ensures code remains flexible, testable, and capable of evolving independently.\n</engineering_principles>`;\n\n  let prompt = `You are an expert coding assistant operating named Atomic, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.\n\nAvailable tools:\n${toolsList}\n\nIn addition to the tools above, you may have access to other custom tools depending on the project.\n\nGuidelines:\n${guidelines}\n\nEngineering guidelines:\n${engineering_guidelines}\n\nAtomic documentation (read only when the user asks about customizing Atomic itself, its SDK, creating extensions, themes, skills, or TUI):\n- Main documentation: ${readmePath}\n- Additional docs: ${docsPath}\n- Examples: ${examplesPath} (extensions, custom tools, SDK)\n- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), atomic packages (docs/packages.md)\n- Note that your docs mention using \"pi\" commands, but you should prefer \"atomic\" commands for everything (just substitute \"atomic\" for \"pi\" when running any command, e.g., \\`atomic <command>\\` over \\`pi <command>\\`) since Pi is an older fork of Atomic with a limited set of features (e.g. Pi doesn't support workflows). Although some API/SDK methods may use \"pi.*\" in their names, which you should use as-is since that is Atomic library code.\n- When working on Atomic topics, read the docs and examples (when searching be aware that these might have the legacy name \"Pi\" in them), and follow .md cross-references before implementing\n- Always read Atomic .md files completely and follow links to related docs (e.g., tui.md for TUI API details)\n- Prefer to use .atomic over .pi (backwards compatible) for creations, the docs may mention .pi but you should use .atomic for everything since .pi is legacy and may not support all features.`;\n\n  if (appendSection) {\n    prompt += appendSection;\n  }\n\n  // Append project context files\n  if (contextFiles.length > 0) {\n    prompt += \"\\n\\n# Project Context\\n\\n\";\n    prompt += \"Project-specific instructions and guidelines:\\n\\n\";\n    for (const { path: filePath, content } of contextFiles) {\n      prompt += `## ${filePath}\\n\\n${content}\\n\\n`;\n    }\n  }\n\n  // Append skills section (only if read tool is available)\n  if (hasRead && skills.length > 0) {\n    prompt += formatSkillsForPrompt(skills);\n  }\n\n  // Add model metadata, date, and working directory last\n  prompt += `\\nModel name (used for commit attribution): ${modelName}`;\n  prompt += `\\nModel reasoning level: ${modelReasoningLevel}`;\n  prompt += `\\nCurrent date: ${date}`;\n  prompt += `\\nCurrent working directory: ${promptCwd}`;\n\n  return prompt;\n}\n"]}