@bastani/atomic 0.5.0-3 → 0.5.0-5

package/.atomic/workflows/ralph/opencode/index.ts

@@ -1,26 +1,17 @@
 /**
  * Ralph workflow for OpenCode — plan → orchestrate → review → debug loop.
  *
- * One OpenCode client backs every iteration; each loop step creates a fresh
- * sub-session bound to the appropriate sub-agent (planner, orchestrator,
- * reviewer, debugger). The loop terminates when:
+ * Each sub-agent invocation spawns its own visible session in the graph,
+ * so users can see each iteration's progress in real time. The loop
+ * terminates when:
  *   - {@link MAX_LOOPS} iterations have completed, OR
  *   - Two consecutive reviewer passes return zero findings.
  *
- * A loop is one cycle of plan → orchestrate → review. When a review returns
- * zero findings on the FIRST pass we re-run only the reviewer (still inside
- * the same loop iteration) to confirm; if that confirmation pass is also
- * clean we stop. The debugger only runs when findings remain, and its
- * markdown report is fed back into the next iteration's planner.
- *
  * Run: atomic workflow -n ralph -a opencode "<your spec>"
  */
 
 import { defineWorkflow } from "@bastani/atomic/workflows";
-import {
-  createOpencodeClient,
-  type SessionPromptResponse,
-} from "@opencode-ai/sdk/v2";
+import { createOpencodeClient } from "@opencode-ai/sdk/v2";
 
 import {
   buildPlannerPrompt,
@@ -51,114 +42,186 @@ export default defineWorkflow({
   description:
     "Plan → orchestrate → review → debug loop with bounded iteration",
 })
-  .session({
-    name: "ralph-loop",
-    description:
-      "Drive plan/orchestrate/review/debug iterations until clean or capped",
-    run: async (ctx) => {
-      const client = createOpencodeClient({ baseUrl: ctx.serverUrl });
-
-      let lastResultData: SessionPromptResponse | null = null;
-
-      /** Run a sub-agent in a fresh session and return its concatenated text. */
-      async function runAgent(
-        title: string,
-        agent: string,
-        text: string,
-      ): Promise<string> {
-        const session = await client.session.create({ title });
-        await client.tui.selectSession({ sessionID: session.data!.id });
-        const result = await client.session.prompt({
-          sessionID: session.data!.id,
-          parts: [{ type: "text", text }],
-          agent,
-        });
-        lastResultData = result.data ?? null;
-        return extractResponseText(result.data!.parts);
-      }
-
-      let consecutiveClean = 0;
-      let debuggerReport = "";
-
-      for (let iteration = 1; iteration <= MAX_LOOPS; iteration++) {
-        // ── Plan ────────────────────────────────────────────────────────────
-        await runAgent(
-          `planner-${iteration}`,
-          "planner",
-          buildPlannerPrompt(ctx.userPrompt, {
-            iteration,
-            debuggerReport: debuggerReport || undefined,
-          }),
+  .run(async (ctx) => {
+    let consecutiveClean = 0;
+    let debuggerReport = "";
+    // Track the most recent session so the next stage can declare it as a
+    // dependency — this chains planner → orchestrator → reviewer → [confirm]
+    // → [debugger] → next planner in the graph instead of showing every
+    // stage as an independent sibling under the root.
+    let prevStage: string | undefined;
+    const depsOn = (): string[] | undefined =>
+      prevStage ? [prevStage] : undefined;
+
+    for (let iteration = 1; iteration <= MAX_LOOPS; iteration++) {
+      // ── Plan ────────────────────────────────────────────────────────────
+      const plannerName = `planner-${iteration}`;
+      const planner = await ctx.session(
+        { name: plannerName, dependsOn: depsOn() },
+        async (s) => {
+          const client = createOpencodeClient({ baseUrl: s.serverUrl });
+          const session = await client.session.create({
+            title: `planner-${iteration}`,
+          });
+          await client.tui.selectSession({ sessionID: session.data!.id });
+          const result = await client.session.prompt({
+            sessionID: session.data!.id,
+            parts: [
+              {
+                type: "text",
+                text: buildPlannerPrompt(s.userPrompt, {
+                  iteration,
+                  debuggerReport: debuggerReport || undefined,
+                }),
+              },
+            ],
+            agent: "planner",
+          });
+          s.save(result.data!);
+          return extractResponseText(result.data!.parts);
+        },
+      );
+      prevStage = plannerName;
+
+      // ── Orchestrate ─────────────────────────────────────────────────────
+      const orchName = `orchestrator-${iteration}`;
+      await ctx.session(
+        { name: orchName, dependsOn: depsOn() },
+        async (s) => {
+          const client = createOpencodeClient({ baseUrl: s.serverUrl });
+          const session = await client.session.create({
+            title: `orchestrator-${iteration}`,
+          });
+          await client.tui.selectSession({ sessionID: session.data!.id });
+          const result = await client.session.prompt({
+            sessionID: session.data!.id,
+            parts: [
+              {
+                type: "text",
+                text: buildOrchestratorPrompt(s.userPrompt, {
+                  plannerNotes: planner.result,
+                }),
+              },
+            ],
+            agent: "orchestrator",
+          });
+          s.save(result.data!);
+        },
+      );
+      prevStage = orchName;
+
+      // ── Review (first pass) ─────────────────────────────────────────────
+      let gitStatus = await safeGitStatusS();
+      const reviewerName = `reviewer-${iteration}`;
+      const review = await ctx.session(
+        { name: reviewerName, dependsOn: depsOn() },
+        async (s) => {
+          const client = createOpencodeClient({ baseUrl: s.serverUrl });
+          const session = await client.session.create({
+            title: `reviewer-${iteration}`,
+          });
+          await client.tui.selectSession({ sessionID: session.data!.id });
+          const result = await client.session.prompt({
+            sessionID: session.data!.id,
+            parts: [
+              {
+                type: "text",
+                text: buildReviewPrompt(s.userPrompt, {
+                  gitStatus,
+                  iteration,
+                }),
+              },
+            ],
+            agent: "reviewer",
+          });
+          s.save(result.data!);
+          return extractResponseText(result.data!.parts);
+        },
+      );
+      prevStage = reviewerName;
+
+      let reviewRaw = review.result;
+      let parsed = parseReviewResult(reviewRaw);
+
+      if (!hasActionableFindings(parsed, reviewRaw)) {
+        consecutiveClean += 1;
+        if (consecutiveClean >= CONSECUTIVE_CLEAN_THRESHOLD) break;
+
+        // Confirmation pass — re-run reviewer only
+        gitStatus = await safeGitStatusS();
+        const confirmName = `reviewer-${iteration}-confirm`;
+        const confirm = await ctx.session(
+          { name: confirmName, dependsOn: depsOn() },
+          async (s) => {
+            const client = createOpencodeClient({ baseUrl: s.serverUrl });
+            const session = await client.session.create({
+              title: `reviewer-${iteration}-confirm`,
+            });
+            await client.tui.selectSession({ sessionID: session.data!.id });
+            const result = await client.session.prompt({
+              sessionID: session.data!.id,
+              parts: [
+                {
+                  type: "text",
+                  text: buildReviewPrompt(s.userPrompt, {
+                    gitStatus,
+                    iteration,
+                    isConfirmationPass: true,
+                  }),
+                },
+              ],
+              agent: "reviewer",
+            });
+            s.save(result.data!);
+            return extractResponseText(result.data!.parts);
+          },
         );
+        prevStage = confirmName;
 
-        // ── Orchestrate ─────────────────────────────────────────────────────
-        await runAgent(
-          `orchestrator-${iteration}`,
-          "orchestrator",
-          buildOrchestratorPrompt(),
-        );
-
-        // ── Review (first pass) ─────────────────────────────────────────────
-        let gitStatus = await safeGitStatusS();
-        let reviewRaw = await runAgent(
-          `reviewer-${iteration}-1`,
-          "reviewer",
-          buildReviewPrompt(ctx.userPrompt, { gitStatus, iteration }),
-        );
-        let parsed = parseReviewResult(reviewRaw);
+        reviewRaw = confirm.result;
+        parsed = parseReviewResult(reviewRaw);
 
         if (!hasActionableFindings(parsed, reviewRaw)) {
           consecutiveClean += 1;
-          if (consecutiveClean >= CONSECUTIVE_CLEAN_THRESHOLD) {
-            break;
-          }
-
-          // Confirmation pass — re-run reviewer only, NOT plan/orchestrate.
-          gitStatus = await safeGitStatusS();
-          reviewRaw = await runAgent(
-            `reviewer-${iteration}-2`,
-            "reviewer",
-            buildReviewPrompt(ctx.userPrompt, {
-              gitStatus,
-              iteration,
-              isConfirmationPass: true,
-            }),
-          );
-          parsed = parseReviewResult(reviewRaw);
-
-          if (!hasActionableFindings(parsed, reviewRaw)) {
-            consecutiveClean += 1;
-            if (consecutiveClean >= CONSECUTIVE_CLEAN_THRESHOLD) {
-              break;
-            }
-          } else {
-            consecutiveClean = 0;
-            // fall through to debugger
-          }
+          if (consecutiveClean >= CONSECUTIVE_CLEAN_THRESHOLD) break;
         } else {
           consecutiveClean = 0;
         }
-
-        // ── Debug (only if findings remain AND another iteration is allowed) ─
-        if (
-          hasActionableFindings(parsed, reviewRaw) &&
-          iteration < MAX_LOOPS
-        ) {
-          const debuggerRaw = await runAgent(
-            `debugger-${iteration}`,
-            "debugger",
-            buildDebuggerReportPrompt(parsed, reviewRaw, {
-              iteration,
-              gitStatus,
-            }),
-          );
-          debuggerReport = extractMarkdownBlock(debuggerRaw);
-        }
+      } else {
+        consecutiveClean = 0;
       }
 
-      if (lastResultData !== null) {
-        ctx.save(lastResultData);
+      // ── Debug (only if findings remain AND another iteration is allowed) ─
+      if (hasActionableFindings(parsed, reviewRaw) && iteration < MAX_LOOPS) {
+        const debuggerName = `debugger-${iteration}`;
+        const debugger_ = await ctx.session(
+          { name: debuggerName, dependsOn: depsOn() },
+          async (s) => {
+            const client = createOpencodeClient({ baseUrl: s.serverUrl });
+            const session = await client.session.create({
+              title: `debugger-${iteration}`,
+            });
+            await client.tui.selectSession({ sessionID: session.data!.id });
+            const result = await client.session.prompt({
+              sessionID: session.data!.id,
+              parts: [
+                {
+                  type: "text",
+                  text: buildDebuggerReportPrompt(parsed, reviewRaw, {
+                    iteration,
+                    gitStatus,
+                  }),
+                },
+              ],
+              agent: "debugger",
+            });
+            s.save(result.data!);
+            return extractResponseText(result.data!.parts);
+          },
+        );
+        prevStage = debuggerName;
+        debuggerReport = extractMarkdownBlock(debugger_.result);
       }
-    },
+    }
   })
   .compile();

package/README.md

@@ -31,6 +31,7 @@ Atomic is an open-source **multi-agent harness** that orchestrates **Claude Code
     - [Workflow SDK — Build Your Own Harness](#workflow-sdk--build-your-own-harness)
       - [Builder API](#builder-api)
       - [Session Context (`ctx`)](#session-context-ctx)
+      - [Session Options (`SessionRunOptions`)](#session-options-sessionrunoptions)
       - [Saving Transcripts](#saving-transcripts)
       - [Provider Helpers](#provider-helpers)
       - [Key Rules](#key-rules)
@@ -44,6 +45,8 @@ Atomic is an open-source **multi-agent harness** that orchestrates **Claude Code
     - [Why Research → Plan → Implement → Verify Works](#why-research--plan--implement--verify-works)
   - [Commands Reference](#commands-reference)
     - [CLI Commands](#cli-commands)
+      - [Global Flags](#global-flags)
+      - [`atomic init` Flags](#atomic-init-flags)
       - [`atomic chat` Flags](#atomic-chat-flags)
       - [`atomic workflow` Flags](#atomic-workflow-flags)
     - [Atomic-Provided Skills (invokable from any agent chat)](#atomic-provided-skills-invokable-from-any-agent-chat)
@@ -220,7 +223,7 @@ Each agent gets its own configuration directory (`.claude/`, `.opencode/`, `.git
 
 ### Workflow SDK — Build Your Own Harness
 
-Every team has a process — triage bugs this way, ship features that way, review PRs with these checks. Most of it lives in a wiki nobody reads or in one senior engineer's head. The **Workflow SDK** (`@bastani/atomic/workflows`) lets you encode that process as a chain of named sessions with raw provider SDK code — then run it from the CLI.
+Every team has a process — triage bugs this way, ship features that way, review PRs with these checks. Most of it lives in a wiki nobody reads or in one senior engineer's head. The **Workflow SDK** (`@bastani/atomic/workflows`) lets you encode that process as TypeScript — spawn agent sessions dynamically with native control flow (`for`, `if`, `Promise.all()`), and watch them appear in a live graph as they execute.
 
 Drop a `.ts` file in `.atomic/workflows/<name>/<agent>/index.ts` and run it:
 
@@ -239,31 +242,28 @@ export default defineWorkflow({
   name: "hello",
   description: "Two-session Claude demo: describe → summarize",
 })
-  .session({
-    name: "describe",
-    description: "Ask Claude to describe the project",
-    run: async (ctx) => {
-      await createClaudeSession({ paneId: ctx.paneId });
-      await claudeQuery({
-        paneId: ctx.paneId,
-        prompt: ctx.userPrompt,
-      });
-      ctx.save(ctx.sessionId);
-    },
-  })
-  .session({
-    name: "summarize",
-    description: "Summarize the previous session's output",
-    run: async (ctx) => {
-      await createClaudeSession({ paneId: ctx.paneId });
-      const research = await ctx.transcript("describe");
-
-      await claudeQuery({
-        paneId: ctx.paneId,
-        prompt: `Read ${research.path} and summarize it in 2-3 bullet points.`,
-      });
-      ctx.save(ctx.sessionId);
-    },
+  .run(async (ctx) => {
+    const describe = await ctx.session(
+      { name: "describe", description: "Ask Claude to describe the project" },
+      async (s) => {
+        await createClaudeSession({ paneId: s.paneId });
+        await claudeQuery({ paneId: s.paneId, prompt: s.userPrompt });
+        s.save(s.sessionId);
+      },
+    );
+
+    await ctx.session(
+      { name: "summarize", description: "Summarize the previous session's output" },
+      async (s) => {
+        const research = await s.transcript(describe);
+        await createClaudeSession({ paneId: s.paneId });
+        await claudeQuery({
+          paneId: s.paneId,
+          prompt: `Read ${research.path} and summarize it in 2-3 bullet points.`,
+        });
+        s.save(s.sessionId);
+      },
+    );
   })
   .compile();
 ```
@@ -272,13 +272,16 @@ export default defineWorkflow({
 
 **Key capabilities:**
 
-| Capability               | Description                                                                          |
-| ------------------------ | ------------------------------------------------------------------------------------ |
-| **Sequential sessions**  | Chain `.session()` calls that execute in order, each in its own tmux pane            |
-| **Transcript passing**   | Access previous session output via `ctx.transcript(name)` or `ctx.getMessages(name)` |
-| **Provider-agnostic**    | Write raw SDK code for Claude, Copilot, or OpenCode inside each session's `run()`    |
-| **tmux-based execution** | Each session runs in its own tmux pane for isolation and observability               |
-| **Native SDK access**    | Use `createClaudeSession`, `claudeQuery`, Copilot SDK, or OpenCode SDK directly      |
+| Capability                   | Description                                                                          |
+| ---------------------------- | ------------------------------------------------------------------------------------ |
+| **Dynamic session spawning** | Call `ctx.session()` to spawn sessions at runtime — each gets its own tmux window and graph node |
+| **Native TypeScript control flow** | Use `for`, `if/else`, `Promise.all()`, `try/catch` — no framework DSL needed |
+| **Session return values**    | Session callbacks can return data: `const h = await ctx.session(...); h.result`      |
+| **Transcript passing**       | Access prior session output via handle (`s.transcript(handle)`) or name (`s.transcript("name")`) |
+| **Nested sub-sessions**      | Call `s.session()` inside a session callback to spawn child sessions — visible as nested nodes in the graph |
+| **Dependency tracking**      | Use `dependsOn: ["name"]` to declare session ordering — the runtime waits and the graph shows the edges |
+| **Provider-agnostic**        | Write raw SDK code for Claude, Copilot, or OpenCode inside each session callback     |
+| **Live graph visualization** | Sessions appear in the TUI graph as they're spawned — loops and conditionals are visible in real time |
 
 Drop a `.ts` file in `.atomic/workflows/<name>/<agent>/` (project-local) or `~/.atomic/workflows/` (global). You can also ask Atomic to create workflows for you:
 
@@ -294,22 +297,51 @@ Use your workflow-creator skill to create a workflow that plans, implements, and
 | Method                                  | Purpose                                                           |
 | --------------------------------------- | ----------------------------------------------------------------- |
 | `defineWorkflow({ name, description })` | Entry point — returns a `WorkflowBuilder`                         |
-| `.session({ name, description?, run })` | Add a named session (or pass an array for parallel execution)     |
+| `.run(async (ctx) => { ... })`          | Set the workflow's entry point — `ctx` is a `WorkflowContext`     |
 | `.compile()`                            | **Required** — terminal method that seals the workflow definition |
 
-#### Session Context (`ctx`)
+#### WorkflowContext (`ctx`) — top-level orchestrator
 
 | Property                | Type                      | Description                                                    |
 | ----------------------- | ------------------------- | -------------------------------------------------------------- |
 | `ctx.userPrompt`        | `string`                  | Original user prompt from the CLI invocation                   |
 | `ctx.agent`             | `AgentType`               | Which agent is running (`"claude"`, `"copilot"`, `"opencode"`) |
-| `ctx.serverUrl`         | `string`                  | The agent's server URL                                         |
-| `ctx.paneId`            | `string`                  | tmux pane ID for this session                                  |
-| `ctx.sessionId`         | `string`                  | Session UUID                                                   |
-| `ctx.sessionDir`        | `string`                  | Path to this session's storage directory on disk               |
-| `ctx.transcript(name)`  | `Promise<Transcript>`     | Get a previous session's transcript (`{ path, content }`)      |
-| `ctx.getMessages(name)` | `Promise<SavedMessage[]>` | Get a previous session's raw native messages                   |
-| `ctx.save(messages)`    | `SaveTranscript`          | Save this session's output for subsequent sessions             |
+| `ctx.session(opts, fn)` | `Promise<SessionHandle<T>>` | Spawn a session — returns handle with `name`, `id`, `result` |
+| `ctx.transcript(ref)`   | `Promise<Transcript>`     | Get a completed session's transcript (`{ path, content }`)     |
+| `ctx.getMessages(ref)`  | `Promise<SavedMessage[]>` | Get a completed session's raw native messages                  |
+
+#### SessionContext (`s`) — inside each session callback
+
+| Property                | Type                      | Description                                                    |
+| ----------------------- | ------------------------- | -------------------------------------------------------------- |
+| `s.serverUrl`           | `string`                  | The agent's server URL                                         |
+| `s.userPrompt`          | `string`                  | Original user prompt from the CLI invocation                   |
+| `s.agent`               | `AgentType`               | Which agent is running                                         |
+| `s.paneId`              | `string`                  | tmux pane ID for this session                                  |
+| `s.sessionId`           | `string`                  | Session UUID                                                   |
+| `s.sessionDir`          | `string`                  | Path to this session's storage directory on disk               |
+| `s.save(messages)`      | `SaveTranscript`          | Save this session's output for subsequent sessions             |
+| `s.transcript(ref)`     | `Promise<Transcript>`     | Get a completed session's transcript                           |
+| `s.getMessages(ref)`    | `Promise<SavedMessage[]>` | Get a completed session's raw native messages                  |
+| `s.session(opts, fn)`   | `Promise<SessionHandle<T>>` | Spawn a nested sub-session (child in the graph)              |
+
+#### Session Options (`SessionRunOptions`)
+
+| Property      | Type       | Description                                                                   |
+| ------------- | ---------- | ----------------------------------------------------------------------------- |
+| `name`        | `string`   | Unique session name within the workflow run                                   |
+| `description` | `string?`  | Human-readable description shown in the graph                                 |
+| `dependsOn`   | `string[]?`| Names of sessions that must complete before this one starts (creates graph edges) |
+
+`dependsOn` is useful when spawning sessions with `Promise.all()` — it lets the runtime enforce ordering while still allowing parallel spawning of independent sessions:
+
+```ts
+await Promise.all([
+  ctx.session({ name: "migrate-db" }, async (s) => { /* ... */ }),
+  ctx.session({ name: "seed-data", dependsOn: ["migrate-db"] }, async (s) => { /* ... */ }),
+  ctx.session({ name: "gen-types", dependsOn: ["migrate-db"] }, async (s) => { /* ... */ }),
+]);
+```
 
 #### Saving Transcripts
 
@@ -317,27 +349,49 @@ Each provider saves transcripts differently:
 
 | Provider     | How to Save                                                        |
 | ------------ | ------------------------------------------------------------------ |
-| **Claude**   | `ctx.save(ctx.sessionId)` — auto-reads via `getSessionMessages()`  |
-| **Copilot**  | `ctx.save(await session.getMessages())` — pass `SessionEvent[]`    |
-| **OpenCode** | `ctx.save(result.data)` — pass the full `{ info, parts }` response |
+| **Claude**   | `s.save(s.sessionId)` — auto-reads via `getSessionMessages()`     |
+| **Copilot**  | `s.save(await session.getMessages())` — pass `SessionEvent[]`     |
+| **OpenCode** | `s.save(result.data!)` — pass the full `{ info, parts }` response |
 
 #### Provider Helpers
 
 | Export                            | Purpose                                             |
 | --------------------------------- | --------------------------------------------------- |
-| `createClaudeSession({ paneId })` | Start a Claude TUI in a tmux pane                   |
-| `claudeQuery({ paneId, prompt })` | Send a prompt to Claude and wait for the response   |
-| `clearClaudeSession({ paneId })`  | Clear the current Claude session                    |
-| `validateClaudeWorkflow()`        | Validate a Claude workflow definition before run    |
-| `validateCopilotWorkflow()`       | Validate a Copilot workflow definition before run   |
-| `validateOpenCodeWorkflow()`      | Validate an OpenCode workflow definition before run |
+| `createClaudeSession(options)`    | Start a Claude TUI in a tmux pane                   |
+| `claudeQuery(options)`            | Send a prompt to Claude and wait for the response   |
+| `clearClaudeSession(paneId)`      | Free memory for a killed/finished Claude session    |
+| `validateClaudeWorkflow()`        | Validate a Claude workflow source before run        |
+| `validateCopilotWorkflow()`       | Validate a Copilot workflow source before run       |
+| `validateOpenCodeWorkflow()`      | Validate an OpenCode workflow source before run     |
+
+`createClaudeSession` accepts:
+
+| Option            | Type       | Default                                               | Description                        |
+| ----------------- | ---------- | ----------------------------------------------------- | ---------------------------------- |
+| `paneId`          | `string`   | —                                                     | tmux pane ID (required)            |
+| `chatFlags`       | `string[]` | `["--dangerously-skip-permissions"]` | CLI flags passed to `claude`       |
+| `readyTimeoutMs`  | `number`   | `30000`                                               | Timeout waiting for TUI readiness  |
+
+`claudeQuery` accepts:
+
+| Option            | Type     | Default  | Description                                      |
+| ----------------- | -------- | -------- | ------------------------------------------------ |
+| `paneId`          | `string` | —        | tmux pane ID (required)                           |
+| `prompt`          | `string` | —        | The prompt to send (required)                     |
+| `timeoutMs`       | `number` | `300000` | Response timeout (5 min)                          |
+| `pollIntervalMs`  | `number` | `2000`   | Polling interval for output stabilization         |
+| `submitPresses`   | `number` | `1`      | C-m presses per submit round                      |
+| `maxSubmitRounds` | `number` | `6`      | Max retry rounds for delivery confirmation        |
+| `readyTimeoutMs`  | `number` | `30000`  | Pane readiness timeout before sending             |
+
+Returns `{ output: string; delivered: boolean }` — `delivered` confirms the prompt was accepted by the agent.
 
 #### Key Rules
 
-1. Every workflow file must use `export default` with `.compile()` at the end
-2. Session names must be unique within a workflow
-3. Sessions execute sequentially in the order they are defined
-4. Each session runs in its own tmux pane with the chosen agent
+1. Every workflow file must use `export default` with `.run()` and `.compile()`
+2. Session names must be unique within a workflow run
+3. `transcript()` / `getMessages()` only access completed sessions (callback returned + saves flushed)
+4. Each session runs in its own tmux window with the chosen agent
 5. Workflows are organized per-workflow: `.atomic/workflows/<name>/<agent>/index.ts`
 
 Workflow files need no `package.json` or `node_modules` of their own — the Atomic loader rewrites `@bastani/atomic/*` and atomic's transitive deps (`@github/copilot-sdk`, `@opencode-ai/sdk`, `@anthropic-ai/claude-agent-sdk`, `zod`, etc.) to absolute paths inside the installed atomic package at load time. Drop a `.ts` file and it runs.
@@ -410,8 +464,10 @@ The [Ralph Wiggum Method](https://ghuntley.com/ralph/) enables **multi-hour auto
 **How Ralph works:**
 
 1. **Task Decomposition** — A `planner` sub-agent breaks your spec into a structured task list with dependency tracking, stored in a SQLite database with WAL mode for parallel access
-2. **Worker Loop** — Dispatches `worker` sub-agents for ready tasks, executing up to 100 iterations with concurrent execution of independent tasks
-3. **Review & Debug** — A `reviewer` sub-agent audits the implementation; if issues are found, a `debugger` sub-agent generates a report that feeds back to the planner on the next iteration
+2. **Orchestration** — An `orchestrator` sub-agent retrieves the task list, validates the dependency graph, and dispatches `worker` sub-agents for ready tasks with concurrent execution of independent tasks
+3. **Review & Debug** — A `reviewer` sub-agent audits the implementation with structured JSON output; if actionable findings exist (P0–P2 severity), a `debugger` sub-agent investigates root causes and produces a markdown report that feeds back to the planner on the next iteration
+
+**Loop configuration:** Ralph runs up to **10 iterations** and exits early after **2 consecutive clean reviews** (zero actionable findings). P3 (minor) findings are filtered as non-actionable.
 
 ```bash
 # From a prompt
@@ -601,7 +657,7 @@ During `atomic workflow` execution, Atomic renders a live orchestrator panel bui
 - **Session graph** — Nodes for each `.session()` call with status (pending, running, completed, failed) and edges for sequential / parallel dependencies
 - **Task list tracking** — Ralph's decomposed task list with dependency arrows, updated in real time as workers complete tasks
 - **Pane previews** — Thumbnail of each tmux pane so you can see what every agent is doing without switching contexts
-- **Transcript passing visibility** — Highlights `ctx.save()` / `ctx.transcript()` handoffs as they happen between sessions
+- **Transcript passing visibility** — Highlights `s.save()` / `s.transcript()` handoffs as they happen between sessions
 
 During `atomic chat`, there is no Atomic-owned TUI — `atomic chat -a <agent>` spawns the native agent CLI inside a tmux/psmux session, so all chat features (streaming, `@` mentions, `/slash-commands`, model selection, theme switching, keyboard shortcuts) come from the agent CLI itself. Atomic's role in chat mode is to handle config sync, tmux session management, and argument passthrough.
 
@@ -659,6 +715,29 @@ This is also why the cycle is iterative. Research and specs become persistent co
 | `atomic workflow`           | Run a multi-session agent workflow with the Atomic orchestrator panel |
 | `atomic config set <k> <v>` | Set configuration values (currently supports `telemetry`)             |
 
+#### Global Flags
+
+These flags are available on all commands:
+
+| Flag            | Description                                  |
+| --------------- | -------------------------------------------- |
+| `-y, --yes`     | Auto-confirm all prompts (non-interactive)   |
+| `--no-banner`   | Skip ASCII banner display                    |
+| `-v, --version` | Show version number                          |
+
+#### `atomic init` Flags
+
+| Flag                 | Description                                    |
+| -------------------- | ---------------------------------------------- |
+| `-a, --agent <name>` | Pre-select agent: `claude`, `opencode`, `copilot` |
+| `-s, --scm <name>`   | Pre-select SCM: `github`, `sapling`            |
+
+```bash
+atomic init                              # Interactive setup
+atomic init -a claude -s github          # Pre-select agent and SCM
+atomic init --yes                        # Auto-confirm all prompts
+```
+
 #### `atomic chat` Flags
 
 | Flag                 | Description                            |
@@ -751,7 +830,7 @@ Created automatically during `atomic init`. Resolution order:
 <summary>Install a specific version</summary>
 
 ```bash
-bun install -g @bastani/atomic@0.5.0-1   # replace with desired version
+bun install -g @bastani/atomic@0.5.0-4   # replace with desired version
 ```
 
 List all published versions with `npm view @bastani/atomic versions`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.5.0-3",
+  "version": "0.5.0-5",
   "description": "Configuration management CLI and SDK for coding agents",
   "type": "module",
   "license": "MIT",

package/src/cli.ts

@@ -30,7 +30,6 @@ export function createProgram() {
         .version(VERSION, "-v, --version", "Show version number")
 
         // Global options available to all commands
-        .option("-f, --force", "Overwrite all config files")
         .option("-y, --yes", "Auto-confirm all prompts (non-interactive mode)")
         .option("--no-banner", "Skip ASCII banner display")
 
@@ -68,7 +67,6 @@ export function createProgram() {
                 showBanner: globalOpts.banner !== false,
                 preSelectedAgent: localOpts.agent as AgentKey | undefined,
                 preSelectedScm: localOpts.scm as SourceControlType | undefined,
-                force: globalOpts.force,
                 yes: globalOpts.yes,
             });
         });