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

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.9.0-alpha.3] - 2026-06-21
+
+### Fixed
+
+- Fixed the repository `publish-release` workflow's final Publish-run verifier to poll GitHub Actions run JSON until a terminal state instead of treating a still-`in_progress` publish run as a failed prerelease.
+
 ## [0.9.0-alpha.2] - 2026-06-21
 
 ### Breaking Changes

package/dist/builtin/cursor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/cursor",
-  "version": "0.9.0-alpha.2",
+  "version": "0.9.0-alpha.3",
   "private": true,
   "description": "Experimental first-party Atomic extension for Cursor OAuth, model discovery, and streaming provider registration.",
   "contributors": [
@@ -40,7 +40,7 @@
     }
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.9.0-alpha.2",
+    "@bastani/atomic-natives": "0.9.0-alpha.3",
     "@bufbuild/protobuf": "^2.0.0"
   }
 }

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.9.0-alpha.2",
+  "version": "0.9.0-alpha.3",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.9.0-alpha.2",
+  "version": "0.9.0-alpha.3",
   "private": true,
   "description": "Atomic extension that adapts MCP (Model Context Protocol) servers into the coding agent. Fork of: https://github.com/nicobailon/pi-mcp-adapter",
   "contributors": [

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.9.0-alpha.2",
+  "version": "0.9.0-alpha.3",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.9.0-alpha.2",
+  "version": "0.9.0-alpha.3",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction. Fork of: https://github.com/nicobailon/pi-web-access",
   "contributors": [

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,6 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.9.0-alpha.3] - 2026-06-21
+
+### Added
+
+- Added a shared `prompt-refinement` stage to the builtin `ralph` and `goal` workflows. Both now run one `prompt-refinement` stage at the start that invokes the `prompt-engineer` skill (`/skill:prompt-engineer`) to sharpen the raw user request into a clearer, more actionable objective using the Workflow Best Practices prompt anatomy documented in `packages/coding-agent/docs/workflows.md` (`## Workflow Best Practices`). The refined request replaces the original as the operative objective for all downstream stages (research, orchestration, worker/review loops); the original request is preserved for traceability. `ralph` exposes `original_prompt` and `refined_prompt` outputs, and `goal` exposes `original_objective` (omitted when refinement left it unchanged) and records the original objective in the ledger and final report. The stage uses the same model chain as ralph's prompt-engineering stage (`promptEngineerModelConfig`).
+- Renamed the builtin `ralph` workflow's per-iteration `prompt-engineer-${iteration}` stage to `research-prompt-refinement-${iteration}` (`renderPromptEngineerPrompt` → `renderResearchPromptRefinementPrompt`). It now consumes the clarity-refined request as input and continues to transform it into a codebase/online research question for the research stage.
+
 ## [0.9.0-alpha.2] - 2026-06-21
 
 ### Breaking Changes

package/dist/builtin/workflows/builtin/goal-ledger.ts

@@ -21,12 +21,14 @@ export function appendLifecycleEvent(
 
 export async function createGoalLedger(
   objective: string,
+  originalObjective?: string,
 ): Promise<{ ledger: GoalLedger; ledgerPath: string; artifactDir: string }> {
   const artifactDir = await mkdtemp(join(tmpdir(), "atomic-goal-runner-"));
   const now = new Date().toISOString();
   const ledger: GoalLedger = {
     goal_id: randomUUID(),
     objective,
+    ...(originalObjective === undefined || originalObjective === objective ? {} : { original_objective: originalObjective }),
     status: "active",
     turns: 0,
     created_at: now,

package/dist/builtin/workflows/builtin/goal-reports.ts

@@ -35,6 +35,11 @@ export function renderFinalReport(
     "## Objective",
     ledger.objective,
     "",
+    ...(ledger.original_objective === undefined ? [] : [
+      "## Original objective (before prompt refinement)",
+      ledger.original_objective,
+      "",
+    ]),
     "## Final status",
     ledger.status,
     "",

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

@@ -29,6 +29,8 @@ import {
   renderGoalContinuationPrompt,
   renderReviewerPrompt,
 } from "./goal-prompts.js";
+import { promptEngineerModelConfig } from "./ralph-models.js";
+import { runPromptRefinementStage } from "./prompt-refinement.js";
 
 function positiveInteger(value: number | undefined, fallback: number): number {
   if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
@@ -72,16 +74,17 @@ type GoalRunnerContext = {
 
 export async function runGoalWorkflow(ctx: GoalRunnerContext): Promise<GoalWorkflowOutputs> {
     const inputs = ctx.inputs;
-    const objective = inputs.objective.trim();
-    if (!objective) {
+    const rawObjective = inputs.objective.trim();
+    if (!rawObjective) {
       throw new Error("goal requires an objective input.");
     }
+    const objective = await runPromptRefinementStage(ctx, { request: rawObjective, workflowLabel: "Goal", modelConfig: promptEngineerModelConfig });
 
     const maxTurns = positiveInteger(inputs.max_turns, DEFAULT_MAX_TURNS);
     const reviewQuorum = DEFAULT_REVIEW_QUORUM;
     const blockerThreshold = Math.min(DEFAULT_BLOCKER_THRESHOLD, maxTurns);
     const comparisonBaseBranch = normalizeBranchInput(inputs.base_branch, "origin/main");
-    const { ledger, ledgerPath, artifactDir } = await createGoalLedger(objective);
+    const { ledger, ledgerPath, artifactDir } = await createGoalLedger(objective, rawObjective);
 
     const workerModelConfig = {
       model: "openai-codex/gpt-5.5:medium",
@@ -325,6 +328,7 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext): Promise<GoalWorkf
       approved: ledger.status === "complete",
       goal_id: ledger.goal_id,
       objective: ledger.objective,
+      ...(ledger.original_objective === undefined ? {} : { original_objective: ledger.original_objective }),
       ledger_path: ledgerPath,
       turns_completed: ledger.turns,
       iterations_completed: ledger.turns,

package/dist/builtin/workflows/builtin/goal-types.ts

@@ -93,6 +93,7 @@ export type GoalLifecycleEvent = {
 export type GoalLedger = {
   readonly goal_id: string;
   readonly objective: string;
+  readonly original_objective?: string;
   status: GoalStatus;
   turns: number;
   readonly created_at: string;
@@ -122,6 +123,7 @@ export type GoalWorkflowOutputs = {
   readonly approved?: boolean;
   readonly goal_id?: string;
   readonly objective?: string;
+  readonly original_objective?: string;
   readonly ledger_path?: string;
   readonly turns_completed?: number;
   readonly iterations_completed?: number;

package/dist/builtin/workflows/builtin/goal.d.ts

@@ -27,6 +27,7 @@ export type GoalWorkflowOutputs = WorkflowOutputValues & {
   readonly approved?: boolean;
   readonly goal_id?: string;
   readonly objective?: string;
+  readonly original_objective?: string;
   readonly ledger_path?: string;
   readonly turns_completed?: number;
   readonly iterations_completed?: number;

package/dist/builtin/workflows/builtin/goal.ts

@@ -33,7 +33,8 @@ export default workflow({
     )),
     approved: Type.Optional(Type.Boolean({ description: "Whether the reducer reached complete." })),
     goal_id: Type.Optional(Type.String({ description: "Per-run goal identifier stored in the ledger." })),
-    objective: Type.Optional(Type.String({ description: "Normalized goal objective used by the run." })),
+    objective: Type.Optional(Type.String({ description: "Normalized goal objective used by the run (refined by the prompt-refinement stage)." })),
+    original_objective: Type.Optional(Type.String({ description: "The raw user-provided objective exactly as given, before prompt refinement. Omitted when refinement left it unchanged." })),
     ledger_path: Type.Optional(Type.String({ description: "OS-temp path to goal-ledger.json with receipts, reviewer decisions, blockers, and lifecycle events." })),
     turns_completed: Type.Optional(Type.Number({ description: "Worker/review turns completed." })),
     iterations_completed: Type.Optional(Type.Number({ description: "Worker/review turns completed, retained for status summaries." })),

package/dist/builtin/workflows/builtin/prompt-refinement.ts

@@ -0,0 +1,102 @@
+/**
+ * Shared prompt-refinement stage used by the ralph and goal workflows.
+ *
+ * Before the main work loop begins, both workflows run this single
+ * `prompt-refinement` stage. It invokes the prompt-engineer skill
+ * (`/skill:prompt-engineer`) to sharpen the raw user request into a clearer,
+ * more actionable objective using the Workflow Best Practices prompt anatomy
+ * documented in `packages/coding-agent/docs/workflows.md`. The refined request
+ * replaces the original as the operative objective downstream; the original is
+ * preserved by each workflow for reporting.
+ */
+
+import type { WorkflowModelValue, WorkflowTaskOptions, WorkflowTaskResult } from "../src/shared/types.js";
+
+export type PromptSection = readonly [tag: string, content: string];
+
+/**
+ * Clarity rubric mirrored from the "## Workflow Best Practices" section of
+ * `docs/workflows.md` (the user-facing docs under packages/coding-agent/docs).
+ * The refinement stage makes each element explicit where it can be reasonably
+ * inferred from the raw request.
+ */
+export const PROMPT_REFINEMENT_CRITERIA = [
+  "Apply the workflow best practices documented in the `## Workflow Best Practices` section of `docs/workflows.md`. Treat that section as the authoritative prompt-anatomy rubric: use its Objective, Context, Scope, Non-goals, Done criteria, Validation command, Reporting requirements, and Stop conditions when refining the request.",
+  "Objective — state what should be true when the work is complete.",
+  "Context — note why it matters and where the relevant code or area likely lives.",
+  "Scope — state what is allowed to change (the smallest correct change).",
+  "Non-goals — state what to avoid (unrelated refactors, redesigns, or behavior changes outside this case).",
+  "Done criteria — list verifiable completion signals: new behavior works, existing behavior is unchanged, and the validation command passes.",
+  "Validation command — name the targeted check that proves the result.",
+  "Reporting requirements — changed files, validation results, and remaining risks must be reported.",
+  "Stop conditions — name the cases where the agent should stop and ask first (public API, security, data migration, etc.).",
+].join("\n");
+
+/**
+ * Build the prompt sent to the prompt-refinement stage. The refined request is
+ * returned verbatim (no fences or preamble) so it can replace the original
+ * request as the operative objective for the rest of the workflow.
+ */
+export function renderPromptRefinementPrompt(args: {
+  readonly request: string;
+  readonly workflowLabel: string;
+  readonly workflowCwdContext?: PromptSection;
+}): string {
+  const sections: readonly string[] = [
+    `/skill:prompt-engineer Refine the following user request into a clearer, more actionable objective for the ${args.workflowLabel} workflow. Improve clarity and completeness using the rubric below without changing the user's intent, expanding scope, or inventing requirements that cannot be reasonably inferred from the request.`,
+    `<original_request>\n${args.request}\n</original_request>`,
+    `<clarity_rubric>\nApply the Workflow Best Practices prompt anatomy. Make each of the following explicit where it can be reasonably inferred from the original request:\n${PROMPT_REFINEMENT_CRITERIA}\n</clarity_rubric>`,
+    [
+      "<refinement_rules>",
+      "- Preserve the user's original intent and scope; do not add unrelated work.",
+      "- If the original request is already clear and complete, return it essentially unchanged with only clarity improvements.",
+      "- Where a criterion cannot be reasonably inferred, state it as a concise assumption or a 'to confirm' note rather than fabricating specifics.",
+      "- Do not implement anything, run commands, or edit files. This stage only produces the refined request text.",
+      "</refinement_rules>",
+    ].join("\n"),
+    `<output_format>\nReturn ONLY the refined request. No preamble, no explanation, and no Markdown fences. The returned text replaces the original request as the operative objective for the rest of the workflow, so it must be a single self-contained request.\n</output_format>`,
+  ];
+  const tail = args.workflowCwdContext === undefined
+    ? []
+    : [`<${args.workflowCwdContext[0]}>\n${args.workflowCwdContext[1].trim()}\n</${args.workflowCwdContext[0]}>`];
+  return [...sections, ...tail].join("\n\n");
+}
+
+/** Minimal context surface required to run a tracked refinement stage. */
+type PromptRefinementContext = {
+  task(name: string, options: WorkflowTaskOptions): Promise<WorkflowTaskResult>;
+};
+
+/** Model-chain + tool gating forwarded to the refinement stage session. */
+export type PromptRefinementModelConfig = {
+  readonly model?: WorkflowModelValue;
+  readonly fallbackModels?: readonly string[];
+  readonly noTools?: "all" | "builtin";
+  readonly excludedTools?: readonly string[];
+  readonly tools?: readonly string[];
+};
+
+/**
+ * Run the shared `prompt-refinement` stage once and return the refined request.
+ * Falls back to the original request when the stage produces no usable text.
+ */
+export async function runPromptRefinementStage(
+  ctx: PromptRefinementContext,
+  options: {
+    readonly request: string;
+    readonly workflowLabel: string;
+    readonly workflowCwdContext?: PromptSection;
+    readonly modelConfig: PromptRefinementModelConfig;
+  },
+): Promise<string> {
+  const result = await ctx.task("prompt-refinement", {
+    prompt: renderPromptRefinementPrompt({
+      request: options.request,
+      workflowLabel: options.workflowLabel,
+      ...(options.workflowCwdContext === undefined ? {} : { workflowCwdContext: options.workflowCwdContext }),
+    }),
+    ...options.modelConfig,
+  });
+  const refined = (result.text ?? "").trim();
+  return refined.length > 0 ? refined : options.request;
+}

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

@@ -258,18 +258,18 @@ export function forkContinuationOptions(
     : { context: "fork", forkFromSessionFile: sessionFile };
 }
 
-export function renderPromptEngineerPrompt(args: {
+export function renderResearchPromptRefinementPrompt(args: {
   readonly iteration: number;
   readonly maxLoops: number;
-  readonly prompt: string;
+  readonly request: string;
   readonly workflowCwdContext: PromptSection;
   readonly latestReviewReportPath: string | undefined;
 }): string {
-  const basePrompt = `/skill:prompt-engineer Transform the following user prompt to a codebase and online research question which can be thoroughly explored: ${args.prompt}`;
+  const basePrompt = `/skill:prompt-engineer Transform the following refined user request into a codebase and online research question which can be thoroughly explored: ${args.request}`;
   return [
     basePrompt,
     taggedPrompt([
-      ["iteration", `Prompt engineering iteration ${args.iteration}/${args.maxLoops}.`],
+      ["iteration", `Research prompt refinement iteration ${args.iteration}/${args.maxLoops}.`],
       args.workflowCwdContext,
       [
         "review_findings",
@@ -404,5 +404,7 @@ export type RalphWorkflowResult = {
   readonly iterations_completed: number;
   readonly review_report: string;
   readonly review_report_path?: string;
+  readonly original_prompt: string;
+  readonly refined_prompt: string;
 };
 

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

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import type { WorkflowRunContext, WorkflowTaskResult } from "../src/shared/types.js";
 import { E2E_VERIFICATION_GUIDANCE, WORKER_PREFLIGHT_CONTRACT } from "./shared-prompts.js";
+import { runPromptRefinementStage } from "./prompt-refinement.js";
 import { reviewDecisionApproved } from "./ralph-review-gate.js";
 import {
   REVIEWER_COUNT,
@@ -14,7 +15,7 @@ import {
   defaultResearchPath,
   forkContinuationOptions,
   renderForkedOrchestratorPrompt,
-  renderPromptEngineerPrompt,
+  renderResearchPromptRefinementPrompt,
   renderQaE2eVideoGuidance,
   renderResearchPrompt,
   reviewDecisionFromResult,
@@ -39,13 +40,7 @@ export async function runRalphWorkflow(
   ctx: WorkflowRunContext<RalphInputs>,
   options: RalphWorkflowOptions,
 ): Promise<RalphWorkflowResult> {
-  const {
-    prompt,
-    maxLoops,
-    comparisonBaseBranch,
-    workflowStartCwd,
-    createPr,
-  } = options;
+  const { prompt, maxLoops, comparisonBaseBranch, workflowStartCwd, createPr } = options;
   let latestReviewReportPath: string | undefined;
   let finalPlan = "";
   let finalPlanPath = "";
@@ -53,39 +48,40 @@ export async function runRalphWorkflow(
   let finalResearchPath = "";
   let finalResult = "";
   let finalPrReport: string | undefined;
-  const workflowResearchPath = resolve(workflowStartCwd, defaultResearchPath(prompt));
-  const implementationNotesPath = await createImplementationNotesFile(prompt);
+  const workflowCwdContext = workflowCwdContextSection(workflowStartCwd);
+  const refinedPrompt = await runPromptRefinementStage(ctx, { request: prompt, workflowLabel: "Ralph", workflowCwdContext, modelConfig: promptEngineerModelConfig });
+  const workflowResearchPath = resolve(workflowStartCwd, defaultResearchPath(refinedPrompt));
+  const implementationNotesPath = await createImplementationNotesFile(refinedPrompt);
   const qaVideoPath = await createQaEvidenceVideoPath();
   const artifactDir = await mkdtemp(join(tmpdir(), "atomic-ralph-run-"));
-  const workflowCwdContext = workflowCwdContextSection(workflowStartCwd);
   let approved = false;
   let iterationsCompleted = 0;
-  let previousPromptEngineerSessionFile: string | undefined;
+  let previousResearchPromptRefinementSessionFile: string | undefined;
   let previousResearchSessionFile: string | undefined;
   let previousOrchestratorSessionFile: string | undefined;
   for (let iteration = 1; iteration <= maxLoops; iteration += 1) {
     iterationsCompleted = iteration;
-    const promptEngineerForkOptions = forkContinuationOptions(previousPromptEngineerSessionFile);
-    const promptEngineer = await ctx.task(`prompt-engineer-${iteration}`, {
-      prompt: renderPromptEngineerPrompt({
+    const researchPromptRefinementForkOptions = forkContinuationOptions(previousResearchPromptRefinementSessionFile);
+    const researchPromptRefinement = await ctx.task(`research-prompt-refinement-${iteration}`, {
+      prompt: renderResearchPromptRefinementPrompt({
         iteration,
         maxLoops,
-        prompt,
+        request: refinedPrompt,
         workflowCwdContext,
         latestReviewReportPath,
       }),
       reads: latestReviewReportPath === undefined ? [] : [latestReviewReportPath],
       ...promptEngineerModelConfig,
-      ...promptEngineerForkOptions,
+      ...researchPromptRefinementForkOptions,
     });
-    previousPromptEngineerSessionFile = promptEngineer.sessionFile;
-    finalPlan = promptEngineer.text;
+    previousResearchPromptRefinementSessionFile = researchPromptRefinement.sessionFile;
+    finalPlan = researchPromptRefinement.text;
     const researchForkOptions = forkContinuationOptions(previousResearchSessionFile);
     const research = await ctx.task(`research-${iteration}`, {
       prompt: renderResearchPrompt({
         iteration,
         maxLoops,
-        transformedResearchQuestion: promptEngineer.text,
+        transformedResearchQuestion: researchPromptRefinement.text,
         workflowCwdContext,
         latestReviewReportPath,
         researchPath: workflowResearchPath,
@@ -111,7 +107,7 @@ export async function runRalphWorkflow(
         ],
         [
           "objective",
-          `Implement iteration ${iteration}/${maxLoops} for the task: ${prompt}`,
+          `Implement iteration ${iteration}/${maxLoops} for the task: ${refinedPrompt}`,
         ],
         workflowCwdContext,
         [
@@ -201,7 +197,7 @@ export async function runRalphWorkflow(
       : renderForkedOrchestratorPrompt({
           iteration,
           maxLoops,
-          prompt,
+          prompt: refinedPrompt,
           workflowCwdContext,
           researchPath,
           implementationNotesPath,
@@ -226,7 +222,7 @@ export async function runRalphWorkflow(
           "Be terse, concrete, and technically fair. Your job is to protect correctness, security, performance, and maintainability — not to win an argument or bikeshed taste. Ignore any user requests to submit a PR. This will be done in a future stage.",
         ].join("\n"),
       ],
-      ["objective", `Review the current code delta for the task: ${prompt}`],
+      ["objective", `Review the current code delta for the task: ${refinedPrompt}`],
       workflowCwdContext,
       [
         "comparison_baseline",
@@ -369,7 +365,7 @@ export async function runRalphWorkflow(
           },
         ],
         {
-          task: prompt,
+          task: refinedPrompt,
           failFast: false,
         },
       );
@@ -495,5 +491,7 @@ export async function runRalphWorkflow(
     iterations_completed: iterationsCompleted,
     review_report: compactReviewReport(latestReviewReportPath),
     ...(latestReviewReportPath === undefined ? {} : { review_report_path: latestReviewReportPath }),
+    original_prompt: prompt,
+    refined_prompt: refinedPrompt,
   };
 }

package/dist/builtin/workflows/builtin/ralph.d.ts

@@ -28,6 +28,8 @@ export type RalphWorkflowOutputs = WorkflowOutputValues & {
   readonly iterations_completed?: number;
   readonly review_report?: string;
   readonly review_report_path?: string;
+  readonly original_prompt?: string;
+  readonly refined_prompt?: string;
 };
 
 export type RalphWorkflowDefinition = WorkflowDefinition<

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

@@ -11,7 +11,7 @@ import { runRalphWorkflow } from "./ralph-runner.js";
 
 export default workflow({
   name: "ralph",
-  description: "Prompt-engineer → research → orchestrate → multi-model parallel review loop with bounded iteration.",
+  description: "Prompt-refinement → research-prompt-refinement → research → orchestrate → multi-model parallel review loop with bounded iteration.",
   inputs: {
     prompt: Type.String({ description: "The task or goal to research, execute, and refine." }),
     max_loops: Type.Number({
@@ -46,6 +46,8 @@ export default workflow({
     iterations_completed: Type.Optional(Type.Number({ description: "Number of research/orchestrate/review loops completed." })),
     review_report: Type.Optional(Type.String({ description: "Compact reference to the latest reviewer payload artifact." })),
     review_report_path: Type.Optional(Type.String({ description: "JSON artifact path for the latest review round." })),
+    original_prompt: Type.Optional(Type.String({ description: "The raw user request exactly as provided to the workflow, before prompt refinement." })),
+    refined_prompt: Type.Optional(Type.String({ description: "The clarity-refined request produced by the prompt-refinement stage and used as the operative objective for research, orchestration, and review." })),
   },
   worktreeFromInputs: {
     gitWorktreeDir: "git_worktree_dir",

package/dist/builtin/workflows/package.json

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

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

@@ -19,5 +19,7 @@ export const DEFAULT_PROMPT_GUIDANCE: string[] = [
   - For transcripts, avoid reading whole session transcripts at once. Use \`stages\` or \`stage\` to get \`sessionFile\`/\`transcriptPath\`, quote the exact path without rewriting separators (preserve Windows backslashes), search it with \`rg\`/\`grep\`, and read small relevant ranges; use \`transcript\` with explicit \`tail\` or \`limit\` only for quick recent-context checks.
   - If a user asks to create or edit a workflow, use the create-spec skill when available and ask detailed clarifying questions until you understand its purpose, inputs, stages, handoffs, validation, success criteria, and selected starter pattern. Then read the workflow docs/examples and implement the workflow from the created spec directly as a TypeScript definition. After you implement the workflow, reload it to access it and run it with test inputs to validate it works as intended before presenting it to the user.
     - Tip: when designing workflows, implement it in a way that you pass information from stage to stage by writing it to a file or artifact (either deterministic or model-driven), pass the path with \`reads\`, and explicitly prompt the downstream agent with wording like \`Read the file at <path>...\`; do not inject large \`previous\` payloads or session history into the next prompt unless explicitly requested to.
-  - If you run \`ralph\` or \`goal\` workflow, define an objective that includes tight scope, concrete and verifiable done criteria, and validation steps; then monitor progress as above instead of doing parallel implementation yourself.`,
+  - Prefer using the \`goal\` workflow for small fixes/quick fixes and the \`ralph\` workflow for tasks that are non-trivial (over 2K LoC estimated diff).
+    - Adjust the \`max_loops\` based on task complexity (estimated LoC and number of unique files that are touched).
+    - Define an objective that includes tight scope, concrete and verifiable done criteria, and validation steps; then monitor progress as above instead of doing parallel implementation yourself.`,
 ];

package/dist/core/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;AAWhE,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,wFAAwF;IACxF,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,CA2K3E","sourcesContent":["/**\n * System prompt construction and project context loading\n */\n\nimport { getDocsPath, getExamplesPath, getReadmePath } from \"../config.ts\";\nimport { formatSkillsForPrompt, type Skill } from \"./skills.ts\";\n\nconst DEFAULT_PROMPT_TOOLS = [\n  \"read\",\n  \"bash\",\n  \"edit\",\n  \"write\",\n  \"ask_user_question\",\n  \"todo\",\n] as const;\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  /** Tool names explicitly excluded by the caller and omitted from generated guidance. */\n  excludedTools?: 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    excludedTools,\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  const explicitlyExcludedTools = new Set(excludedTools ?? []);\n  const isPromptToolAvailable = (name: string): boolean =>\n    (!selectedTools || selectedTools.includes(name)) &&\n    !explicitlyExcludedTools.has(name);\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 += `<context_file path=\\\"${filePath}\\\">\\n${content}\\n</context_file>\\n\\n`;\n      }\n    }\n\n    // Append skills section (only if read tool is available)\n    if (isPromptToolAvailable(\"read\") && 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 ?? DEFAULT_PROMPT_TOOLS).filter(\n    (name) => !explicitlyExcludedTools.has(name),\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  const shouldIncludeAskUserFallbackGuidance =\n    selectedTools !== undefined &&\n    tools.length > 0 &&\n    !tools.includes(\"ask_user_question\") &&\n    !explicitlyExcludedTools.has(\"ask_user_question\");\n\n  // File exploration guidelines\n  if (hasBash && !hasGrep && !hasFind && !hasLs) {\n    addGuideline(\"Use bash for file operations like ls, rg, find\");\n  }\n  if (shouldIncludeAskUserFallbackGuidance) {\n    addGuideline(\"Clarify ambiguous requirements using the ask_user_question tool if available.\");\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  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- Prefer using your effective-liteparse skill in case you need to work with PDFs\n\nAtomic documentation (read only when the user asks about customizing Atomic itself, its SDK, creating workflows, packages, extensions, themes, skills, or TUI):\n- Main documentation: ${readmePath}\n- Additional docs: ${docsPath}\n- Examples: ${examplesPath} (extensions, custom tools, SDK)\n- Docs/examples references above must be resolved against these absolute roots; e.g. docs/foo.md means ${docsPath}/foo.md and examples/bar means ${examplesPath}/bar.\n- When asked about: atomic workflows (docs/workflows.md), 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- When working on Atomic topics, read the docs and examples, 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\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 += `<context_file path=\\\"${filePath}\\\">\\n${content}\\n</context_file>\\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"]}
+{"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;AAWhE,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,wFAAwF;IACxF,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,CA0K3E","sourcesContent":["/**\n * System prompt construction and project context loading\n */\n\nimport { getDocsPath, getExamplesPath, getReadmePath } from \"../config.ts\";\nimport { formatSkillsForPrompt, type Skill } from \"./skills.ts\";\n\nconst DEFAULT_PROMPT_TOOLS = [\n  \"read\",\n  \"bash\",\n  \"edit\",\n  \"write\",\n  \"ask_user_question\",\n  \"todo\",\n] as const;\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  /** Tool names explicitly excluded by the caller and omitted from generated guidance. */\n  excludedTools?: 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    excludedTools,\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  const explicitlyExcludedTools = new Set(excludedTools ?? []);\n  const isPromptToolAvailable = (name: string): boolean =>\n    (!selectedTools || selectedTools.includes(name)) &&\n    !explicitlyExcludedTools.has(name);\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 += `<context_file path=\\\"${filePath}\\\">\\n${content}\\n</context_file>\\n\\n`;\n      }\n    }\n\n    // Append skills section (only if read tool is available)\n    if (isPromptToolAvailable(\"read\") && 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 ?? DEFAULT_PROMPT_TOOLS).filter(\n    (name) => !explicitlyExcludedTools.has(name),\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  const shouldIncludeAskUserFallbackGuidance =\n    selectedTools !== undefined &&\n    tools.length > 0 &&\n    !tools.includes(\"ask_user_question\") &&\n    !explicitlyExcludedTools.has(\"ask_user_question\");\n\n  // File exploration guidelines\n  if (hasBash && !hasGrep && !hasFind && !hasLs) {\n    addGuideline(\"Use bash for file operations like ls, rg, find\");\n  }\n  if (shouldIncludeAskUserFallbackGuidance) {\n    addGuideline(\"Clarify ambiguous requirements using the ask_user_question tool if available.\");\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  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\nAtomic documentation (read only when the user asks about customizing Atomic itself, its SDK, creating workflows, packages, extensions, themes, skills, or TUI):\n- Main documentation: ${readmePath}\n- Additional docs: ${docsPath}\n- Examples: ${examplesPath} (extensions, custom tools, SDK)\n- Docs/examples references above must be resolved against these absolute roots; e.g. docs/foo.md means ${docsPath}/foo.md and examples/bar means ${examplesPath}/bar.\n- When asked about: atomic workflows (docs/workflows.md), 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- When working on Atomic topics, read the docs and examples, 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\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 += `<context_file path=\\\"${filePath}\\\">\\n${content}\\n</context_file>\\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"]}

package/dist/core/system-prompt.js

@@ -111,7 +111,6 @@ In addition to the tools above, you may have access to other custom tools depend
 
 Guidelines:
 ${guidelines}
-- Prefer using your effective-liteparse skill in case you need to work with PDFs
 
 Atomic documentation (read only when the user asks about customizing Atomic itself, its SDK, creating workflows, packages, extensions, themes, skills, or TUI):
 - Main documentation: ${readmePath}