@bastani/atomic 0.5.0-1 → 0.5.0-2

package/.atomic/workflows/hello/claude/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Hello workflow for Claude Code — two-session example.
+ *
+ * Claude runs as a full interactive TUI in a tmux pane.
+ * We automate it via tmux send-keys using the claudeQuery() helper.
+ * Transcript is extracted via the Claude Agent SDK's getSessionMessages().
+ *
+ * Run: atomic workflow -n hello -a claude "describe this project"
+ */
+
+import { defineWorkflow, createClaudeSession, claudeQuery } from "@bastani/atomic/workflows";
+
+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,
+      });
+      // Save transcript via Claude Agent SDK (reads from ~/.claude session files)
+      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);
+    },
+  })
+  .compile();

package/.atomic/workflows/hello/copilot/index.ts

@@ -0,0 +1,58 @@
+/**
+ * Hello workflow for Copilot — two-session example.
+ *
+ * Session 1: Ask the agent to describe the project.
+ * Session 2: Read session 1's transcript and summarize it.
+ *
+ * Run: atomic workflow -n hello -a copilot "describe this project"
+ */
+
+import { defineWorkflow } from "@bastani/atomic/workflows";
+import { CopilotClient, approveAll } from "@github/copilot-sdk";
+
+export default defineWorkflow({
+  name: "hello",
+  description: "Two-session Copilot demo: describe → summarize",
+})
+  .session({
+    name: "describe",
+    description: "Ask the agent to describe the project",
+    run: async (ctx) => {
+      const client = new CopilotClient({ cliUrl: ctx.serverUrl });
+      await client.start();
+
+      const session = await client.createSession({ onPermissionRequest: approveAll });
+      await client.setForegroundSessionId(session.sessionId);
+
+      await session.sendAndWait({ prompt: ctx.userPrompt });
+
+      // Save Copilot messages for the next session
+      ctx.save(await session.getMessages() );
+
+      await session.disconnect();
+      await client.stop();
+    },
+  })
+  .session({
+    name: "summarize",
+    description: "Summarize the previous session's output",
+    run: async (ctx) => {
+      const research = await ctx.transcript("describe");
+
+      const client = new CopilotClient({ cliUrl: ctx.serverUrl });
+      await client.start();
+
+      const session = await client.createSession({ onPermissionRequest: approveAll });
+      await client.setForegroundSessionId(session.sessionId);
+
+      await session.sendAndWait({
+        prompt: `Summarize the following in 2-3 bullet points:\n\n${research.content}`,
+      });
+
+      ctx.save(await session.getMessages());
+
+      await session.disconnect();
+      await client.stop();
+    },
+  })
+  .compile();

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

@@ -0,0 +1,58 @@
+/**
+ * Hello workflow for OpenCode — two-session example.
+ *
+ * Session 1: Ask the agent to describe the project.
+ * Session 2: Read session 1's transcript and summarize it.
+ *
+ * Run: atomic workflow -n hello -a opencode "describe this project"
+ */
+
+import { defineWorkflow } from "@bastani/atomic/workflows";
+import { createOpencodeClient } from "@opencode-ai/sdk/v2";
+
+export default defineWorkflow({
+  name: "hello",
+  description: "Two-session OpenCode demo: describe → summarize",
+})
+  .session({
+    name: "describe",
+    description: "Ask the agent to describe the project",
+    run: async (ctx) => {
+      const client = createOpencodeClient({ baseUrl: ctx.serverUrl });
+
+      const session = await client.session.create({ title: "describe" });
+      await client.tui.selectSession({ sessionID: session.data!.id });
+
+      const result = await client.session.prompt({
+        sessionID: session.data!.id,
+        parts: [{ type: "text", text: ctx.userPrompt }],
+      });
+
+      // Save OpenCode response parts for the next session
+      ctx.save(result.data!);
+    },
+  })
+  .session({
+    name: "summarize",
+    description: "Summarize the previous session's output",
+    run: async (ctx) => {
+      const research = await ctx.transcript("describe");
+      const client = createOpencodeClient({ baseUrl: ctx.serverUrl });
+
+      const session = await client.session.create({ title: "summarize" });
+      await client.tui.selectSession({ sessionID: session.data!.id });
+
+      const result = await client.session.prompt({
+        sessionID: session.data!.id,
+        parts: [
+          {
+            type: "text",
+            text: `Summarize the following in 2-3 bullet points:\n\n${research.content}`,
+          },
+        ],
+      });
+
+      ctx.save(result.data!);
+    },
+  })
+  .compile();

package/.atomic/workflows/hello-parallel/claude/index.ts

@@ -0,0 +1,76 @@
+/**
+ * Hello-parallel workflow for Claude Code — parallel session example.
+ *
+ * Session 1 (sequential): Ask Claude to describe the project.
+ * Sessions 2+3 (parallel): Two agents summarize session 1 concurrently.
+ * Session 4 (sequential): Merge both summaries into a final output.
+ *
+ * Run: atomic workflow -n hello-parallel -a claude "describe this project"
+ */
+
+import { defineWorkflow, createClaudeSession, claudeQuery } from "@bastani/atomic/workflows";
+
+export default defineWorkflow({
+  name: "hello-parallel",
+  description: "Parallel Claude demo: describe → [summarize-a, summarize-b] → merge",
+})
+  .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-a",
+      description: "Summarize the description as bullet points",
+      run: async (ctx) => {
+        const research = await ctx.transcript("describe");
+        await createClaudeSession({ paneId: ctx.paneId });
+        await claudeQuery({
+          paneId: ctx.paneId,
+          prompt: `Read ${research.path} and summarize it in 2-3 bullet points.`,
+        });
+        ctx.save(ctx.sessionId);
+      },
+    },
+    {
+      name: "summarize-b",
+      description: "Summarize the description as a one-liner",
+      run: async (ctx) => {
+        const research = await ctx.transcript("describe");
+        await createClaudeSession({ paneId: ctx.paneId });
+        await claudeQuery({
+          paneId: ctx.paneId,
+          prompt: `Read ${research.path} and summarize it in a single sentence.`,
+        });
+        ctx.save(ctx.sessionId);
+      },
+    },
+  ])
+  .session({
+    name: "merge",
+    description: "Merge both summaries into a final output",
+    run: async (ctx) => {
+      const bullets = await ctx.transcript("summarize-a");
+      const oneliner = await ctx.transcript("summarize-b");
+      await createClaudeSession({ paneId: ctx.paneId });
+      await claudeQuery({
+        paneId: ctx.paneId,
+        prompt: [
+          "Combine the following two summaries into one concise paragraph:",
+          "",
+          "## Bullet points",
+          bullets.content,
+          "",
+          "## One-liner",
+          oneliner.content,
+        ].join("\n"),
+      });
+      ctx.save(ctx.sessionId);
+    },
+  })
+  .compile();

package/.atomic/workflows/hello-parallel/copilot/index.ts

@@ -0,0 +1,105 @@
+/**
+ * Hello-parallel workflow for Copilot — parallel session example.
+ *
+ * Session 1 (sequential): Ask the agent to describe the project.
+ * Sessions 2+3 (parallel): Two agents summarize session 1 concurrently.
+ * Session 4 (sequential): Merge both summaries into a final output.
+ *
+ * Run: atomic workflow -n hello-parallel -a copilot "describe this project"
+ */
+
+import { defineWorkflow } from "@bastani/atomic/workflows";
+import { CopilotClient, approveAll } from "@github/copilot-sdk";
+
+export default defineWorkflow({
+  name: "hello-parallel",
+  description: "Parallel Copilot demo: describe → [summarize-a, summarize-b] → merge",
+})
+  .session({
+    name: "describe",
+    description: "Ask the agent to describe the project",
+    run: async (ctx) => {
+      const client = new CopilotClient({ cliUrl: ctx.serverUrl });
+      await client.start();
+
+      const session = await client.createSession({ onPermissionRequest: approveAll });
+      await client.setForegroundSessionId(session.sessionId);
+      await session.sendAndWait({ prompt: ctx.userPrompt });
+
+      ctx.save(await session.getMessages());
+      await session.disconnect();
+      await client.stop();
+    },
+  })
+  .session([
+    {
+      name: "summarize-a",
+      description: "Summarize the description as bullet points",
+      run: async (ctx) => {
+        const research = await ctx.transcript("describe");
+
+        const client = new CopilotClient({ cliUrl: ctx.serverUrl });
+        await client.start();
+
+        const session = await client.createSession({ onPermissionRequest: approveAll });
+        await client.setForegroundSessionId(session.sessionId);
+        await session.sendAndWait({
+          prompt: `Summarize the following in 2-3 bullet points:\n\n${research.content}`,
+        });
+
+        ctx.save(await session.getMessages());
+        await session.disconnect();
+        await client.stop();
+      },
+    },
+    {
+      name: "summarize-b",
+      description: "Summarize the description as a one-liner",
+      run: async (ctx) => {
+        const research = await ctx.transcript("describe");
+
+        const client = new CopilotClient({ cliUrl: ctx.serverUrl });
+        await client.start();
+
+        const session = await client.createSession({ onPermissionRequest: approveAll });
+        await client.setForegroundSessionId(session.sessionId);
+        await session.sendAndWait({
+          prompt: `Summarize the following in a single sentence:\n\n${research.content}`,
+        });
+
+        ctx.save(await session.getMessages());
+        await session.disconnect();
+        await client.stop();
+      },
+    },
+  ])
+  .session({
+    name: "merge",
+    description: "Merge both summaries into a final output",
+    run: async (ctx) => {
+      const bullets = await ctx.transcript("summarize-a");
+      const oneliner = await ctx.transcript("summarize-b");
+
+      const client = new CopilotClient({ cliUrl: ctx.serverUrl });
+      await client.start();
+
+      const session = await client.createSession({ onPermissionRequest: approveAll });
+      await client.setForegroundSessionId(session.sessionId);
+      await session.sendAndWait({
+        prompt: [
+          "Combine the following two summaries into one concise paragraph:",
+          "",
+          "## Bullet points",
+          bullets.content,
+          "",
+          "## One-liner",
+          oneliner.content,
+        ].join("\n"),
+      });
+
+      ctx.save(await session.getMessages());
+      await session.disconnect();
+      await client.stop();
+    },
+  })
+  .compile();

package/.atomic/workflows/hello-parallel/opencode/index.ts

@@ -0,0 +1,115 @@
+/**
+ * Hello-parallel workflow for OpenCode — parallel session example.
+ *
+ * Session 1 (sequential): Ask the agent to describe the project.
+ * Sessions 2+3 (parallel): Two agents summarize session 1 concurrently.
+ * Session 4 (sequential): Merge both summaries into a final output.
+ *
+ * Run: atomic workflow -n hello-parallel -a opencode "describe this project"
+ */
+
+import { defineWorkflow } from "@bastani/atomic/workflows";
+import { createOpencodeClient } from "@opencode-ai/sdk/v2";
+
+export default defineWorkflow({
+  name: "hello-parallel",
+  description: "Parallel OpenCode demo: describe → [summarize-a, summarize-b] → merge",
+})
+  .session({
+    name: "describe",
+    description: "Ask the agent to describe the project",
+    run: async (ctx) => {
+      const client = createOpencodeClient({ baseUrl: ctx.serverUrl });
+
+      const session = await client.session.create({ title: "describe" });
+      await client.tui.selectSession({ sessionID: session.data!.id });
+
+      const result = await client.session.prompt({
+        sessionID: session.data!.id,
+        parts: [{ type: "text", text: ctx.userPrompt }],
+      });
+
+      ctx.save(result.data!);
+    },
+  })
+  .session([
+    {
+      name: "summarize-a",
+      description: "Summarize the description as bullet points",
+      run: async (ctx) => {
+        const research = await ctx.transcript("describe");
+        const client = createOpencodeClient({ baseUrl: ctx.serverUrl });
+
+        const session = await client.session.create({ title: "summarize-a" });
+        await client.tui.selectSession({ sessionID: session.data!.id });
+
+        const result = await client.session.prompt({
+          sessionID: session.data!.id,
+          parts: [
+            {
+              type: "text",
+              text: `Summarize the following in 2-3 bullet points:\n\n${research.content}`,
+            },
+          ],
+        });
+
+        ctx.save(result.data!);
+      },
+    },
+    {
+      name: "summarize-b",
+      description: "Summarize the description as a one-liner",
+      run: async (ctx) => {
+        const research = await ctx.transcript("describe");
+        const client = createOpencodeClient({ baseUrl: ctx.serverUrl });
+
+        const session = await client.session.create({ title: "summarize-b" });
+        await client.tui.selectSession({ sessionID: session.data!.id });
+
+        const result = await client.session.prompt({
+          sessionID: session.data!.id,
+          parts: [
+            {
+              type: "text",
+              text: `Summarize the following in a single sentence:\n\n${research.content}`,
+            },
+          ],
+        });
+
+        ctx.save(result.data!);
+      },
+    },
+  ])
+  .session({
+    name: "merge",
+    description: "Merge both summaries into a final output",
+    run: async (ctx) => {
+      const bullets = await ctx.transcript("summarize-a");
+      const oneliner = await ctx.transcript("summarize-b");
+      const client = createOpencodeClient({ baseUrl: ctx.serverUrl });
+
+      const session = await client.session.create({ title: "merge" });
+      await client.tui.selectSession({ sessionID: session.data!.id });
+
+      const result = await client.session.prompt({
+        sessionID: session.data!.id,
+        parts: [
+          {
+            type: "text",
+            text: [
+              "Combine the following two summaries into one concise paragraph:",
+              "",
+              "## Bullet points",
+              bullets.content,
+              "",
+              "## One-liner",
+              oneliner.content,
+            ].join("\n"),
+          },
+        ],
+      });
+
+      ctx.save(result.data!);
+    },
+  })
+  .compile();

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

@@ -0,0 +1,149 @@
+/**
+ * Ralph workflow for Claude Code — plan → orchestrate → review → debug loop.
+ *
+ * One Claude TUI runs in a tmux pane for the duration of the workflow. Each
+ * loop iteration invokes sub-agents via @-mention syntax (planner,
+ * orchestrator, reviewer, and — when findings remain — debugger). 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 after the
+ * reviewer pass(es), and its markdown report is fed back to the planner on
+ * the next iteration.
+ *
+ * Run: atomic workflow -n ralph -a claude "<your spec>"
+ */
+
+import {
+  defineWorkflow,
+  createClaudeSession,
+  claudeQuery,
+} from "@bastani/atomic/workflows";
+
+import {
+  buildPlannerPrompt,
+  buildOrchestratorPrompt,
+  buildReviewPrompt,
+  buildDebuggerReportPrompt,
+  parseReviewResult,
+  extractMarkdownBlock,
+} from "../helpers/prompts.ts";
+import { hasActionableFindings } from "../helpers/review.ts";
+import { safeGitStatusS } from "../helpers/git.ts";
+
+const MAX_LOOPS = 10;
+const CONSECUTIVE_CLEAN_THRESHOLD = 2;
+
+/** Wrap a prompt with a Claude Code @-mention so the named sub-agent runs it. */
+function asAgentCall(agentName: string, prompt: string): string {
+  return `@"${agentName} (agent)" ${prompt}`;
+}
+
+export default defineWorkflow({
+  name: "ralph",
+  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) => {
+      await createClaudeSession({ paneId: ctx.paneId });
+
+      let consecutiveClean = 0;
+      let debuggerReport = "";
+
+      for (let iteration = 1; iteration <= MAX_LOOPS; iteration++) {
+        // ── Plan ────────────────────────────────────────────────────────────
+        await claudeQuery({
+          paneId: ctx.paneId,
+          prompt: asAgentCall(
+            "planner",
+            buildPlannerPrompt(ctx.userPrompt, {
+              iteration,
+              debuggerReport: debuggerReport || undefined,
+            }),
+          ),
+        });
+
+        // ── Orchestrate ─────────────────────────────────────────────────────
+        await claudeQuery({
+          paneId: ctx.paneId,
+          prompt: asAgentCall("orchestrator", buildOrchestratorPrompt()),
+        });
+
+        // ── Review (first pass) ─────────────────────────────────────────────
+        let gitStatus = await safeGitStatusS();
+        let reviewQuery = await claudeQuery({
+          paneId: ctx.paneId,
+          prompt: asAgentCall(
+            "reviewer",
+            buildReviewPrompt(ctx.userPrompt, { gitStatus, iteration }),
+          ),
+        });
+        let reviewRaw = reviewQuery.output;
+        let 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();
+          reviewQuery = await claudeQuery({
+            paneId: ctx.paneId,
+            prompt: asAgentCall(
+              "reviewer",
+              buildReviewPrompt(ctx.userPrompt, {
+                gitStatus,
+                iteration,
+                isConfirmationPass: true,
+              }),
+            ),
+          });
+          reviewRaw = reviewQuery.output;
+          parsed = parseReviewResult(reviewRaw);
+
+          if (!hasActionableFindings(parsed, reviewRaw)) {
+            consecutiveClean += 1;
+            if (consecutiveClean >= CONSECUTIVE_CLEAN_THRESHOLD) {
+              break;
+            }
+          } else {
+            consecutiveClean = 0;
+            // fall through to debugger
+          }
+        } else {
+          consecutiveClean = 0;
+        }
+
+        // ── Debug (only if findings remain AND another iteration is allowed) ─
+        if (
+          hasActionableFindings(parsed, reviewRaw) &&
+          iteration < MAX_LOOPS
+        ) {
+          const debuggerQuery = await claudeQuery({
+            paneId: ctx.paneId,
+            prompt: asAgentCall(
+              "debugger",
+              buildDebuggerReportPrompt(parsed, reviewRaw, {
+                iteration,
+                gitStatus,
+              }),
+            ),
+          });
+          debuggerReport = extractMarkdownBlock(debuggerQuery.output);
+        }
+      }
+
+      ctx.save(ctx.sessionId);
+    },
+  })
+  .compile();