ralphflow 0.1.0

package/dist/ralphflow.js

@@ -0,0 +1,575 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { Command as Command4 } from "commander";
+import chalk7 from "chalk";
+
+// src/cli/init.ts
+import { Command } from "commander";
+import chalk2 from "chalk";
+
+// src/core/init.ts
+import { existsSync as existsSync2, readdirSync } from "fs";
+import { join as join2 } from "path";
+import { createInterface } from "readline";
+import chalk from "chalk";
+
+// src/core/template.ts
+import { readFileSync, mkdirSync, cpSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+function resolveTemplatePath(templateName) {
+  const candidates = [
+    join(__dirname, "..", "templates", templateName),
+    // dev: src/core/ -> src/templates/
+    join(__dirname, "..", "src", "templates", templateName)
+    // bundled: dist/ -> src/templates/
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error(
+    `Template "${templateName}" not found. Searched:
+${candidates.join("\n")}`
+  );
+}
+function copyTemplate(templateName, targetDir) {
+  const templatePath = resolveTemplatePath(templateName);
+  const loopsDir = join(templatePath, "loops");
+  if (!existsSync(loopsDir)) {
+    throw new Error(`Template "${templateName}" has no loops/ directory`);
+  }
+  mkdirSync(targetDir, { recursive: true });
+  cpSync(loopsDir, targetDir, { recursive: true });
+  const yamlSrc = join(templatePath, "ralphflow.yaml");
+  if (existsSync(yamlSrc)) {
+    const yamlDest = join(targetDir, "ralphflow.yaml");
+    cpSync(yamlSrc, yamlDest);
+  }
+}
+
+// src/core/init.ts
+function ask(rl, question) {
+  return new Promise((resolve) => {
+    rl.question(chalk.cyan("? ") + question + " ", (answer) => {
+      resolve(answer.trim());
+    });
+  });
+}
+var TEMPLATES = ["code-implementation", "research"];
+async function initProject(cwd, options = {}) {
+  const ralphFlowDir = join2(cwd, ".ralph-flow");
+  const claudeMdPath = join2(cwd, "CLAUDE.md");
+  if (!existsSync2(claudeMdPath)) {
+    console.log();
+    console.log(chalk.yellow("  No CLAUDE.md found."));
+    console.log(chalk.dim('  Create one with: claude "Initialize CLAUDE.md for this project"'));
+    console.log(chalk.dim("  Or create it manually with your project description, stack, and commands."));
+    console.log();
+    return;
+  }
+  if (existsSync2(ralphFlowDir)) {
+    const existing = listFlows(ralphFlowDir);
+    if (existing.length > 0 && !options.template) {
+      console.log();
+      console.log(chalk.bold("  Existing flows:"));
+      for (const flow of existing) {
+        console.log(chalk.dim(`    - ${flow}`));
+      }
+      console.log();
+      console.log(chalk.dim("  To add another: npx ralphflow init --template code-implementation --name my-feature"));
+      console.log(chalk.dim("  To check status: npx ralphflow status"));
+      console.log();
+      return;
+    }
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  console.log();
+  let template = options.template;
+  if (!template) {
+    console.log(chalk.dim(`  Templates: ${TEMPLATES.join(", ")}`));
+    template = await ask(rl, "Which template?") || "code-implementation";
+  }
+  if (!TEMPLATES.includes(template)) {
+    console.log(chalk.red(`  Unknown template "${template}". Available: ${TEMPLATES.join(", ")}`));
+    rl.close();
+    return;
+  }
+  let flowName = options.name;
+  if (!flowName) {
+    flowName = await ask(rl, "Flow name? (Enter for default)") || template;
+  }
+  rl.close();
+  console.log();
+  const flowDir = join2(ralphFlowDir, flowName);
+  if (existsSync2(flowDir)) {
+    console.log(chalk.yellow(`  Flow "${flowName}" already exists at .ralph-flow/${flowName}/`));
+    return;
+  }
+  copyTemplate(template, flowDir);
+  console.log(chalk.green(`  Created .ralph-flow/${flowName}/`) + " (loops, trackers, prompts)");
+  console.log();
+  console.log(chalk.dim(`  Next: npx ralphflow run story --flow ${flowName}`));
+  console.log();
+}
+function listFlows(ralphFlowDir) {
+  try {
+    return readdirSync(ralphFlowDir, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith(".")).map((d) => d.name);
+  } catch {
+    return [];
+  }
+}
+
+// src/cli/init.ts
+var initCommand = new Command("init").description("Initialize a new RalphFlow flow").option("-t, --template <name>", "Template to use (code-implementation, research)").option("-n, --name <name>", "Custom name for the flow").action(async (opts) => {
+  try {
+    await initProject(process.cwd(), { template: opts.template, name: opts.name });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(chalk2.red(`
+  ${msg}
+`));
+    process.exit(1);
+  }
+});
+
+// src/cli/run.ts
+import { Command as Command2 } from "commander";
+import chalk4 from "chalk";
+
+// src/core/runner.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { join as join4 } from "path";
+import chalk3 from "chalk";
+
+// src/core/config.ts
+import { readFileSync as readFileSync2, existsSync as existsSync3, readdirSync as readdirSync2 } from "fs";
+import { join as join3 } from "path";
+import { parse as parseYaml } from "yaml";
+var LOOP_ALIASES = {
+  story: "story-loop",
+  stories: "story-loop",
+  tasks: "tasks-loop",
+  task: "tasks-loop",
+  delivery: "delivery-loop",
+  deliver: "delivery-loop"
+};
+function listFlows2(cwd) {
+  const baseDir = join3(cwd, ".ralph-flow");
+  if (!existsSync3(baseDir)) return [];
+  return readdirSync2(baseDir, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith(".")).filter((d) => existsSync3(join3(baseDir, d.name, "ralphflow.yaml"))).map((d) => d.name);
+}
+function resolveFlowDir(cwd, flowName) {
+  const baseDir = join3(cwd, ".ralph-flow");
+  if (!existsSync3(baseDir)) {
+    throw new Error("No .ralph-flow/ found. Run `npx ralphflow init` first.");
+  }
+  const flows = listFlows2(cwd);
+  if (flows.length === 0) {
+    throw new Error("No flows found in .ralph-flow/. Run `npx ralphflow init` first.");
+  }
+  if (flowName) {
+    if (!flows.includes(flowName)) {
+      throw new Error(`Flow "${flowName}" not found. Available: ${flows.join(", ")}`);
+    }
+    return join3(baseDir, flowName);
+  }
+  if (flows.length === 1) {
+    return join3(baseDir, flows[0]);
+  }
+  throw new Error(
+    `Multiple flows found: ${flows.join(", ")}. Use --flow <name> to specify which one.`
+  );
+}
+function loadConfig(flowDir) {
+  const configPath = join3(flowDir, "ralphflow.yaml");
+  if (!existsSync3(configPath)) {
+    throw new Error(`No ralphflow.yaml found in ${flowDir}`);
+  }
+  const raw = readFileSync2(configPath, "utf-8");
+  const config = parseYaml(raw);
+  if (!config.name) {
+    throw new Error('ralphflow.yaml: missing required field "name"');
+  }
+  if (!config.loops || Object.keys(config.loops).length === 0) {
+    throw new Error('ralphflow.yaml: missing required field "loops"');
+  }
+  if (!config.dir) {
+    config.dir = ".ralph-flow";
+  }
+  return config;
+}
+function resolveLoop(config, name) {
+  if (config.loops[name]) {
+    return { key: name, loop: config.loops[name] };
+  }
+  const aliased = LOOP_ALIASES[name.toLowerCase()];
+  if (aliased && config.loops[aliased]) {
+    return { key: aliased, loop: config.loops[aliased] };
+  }
+  for (const [key, loop] of Object.entries(config.loops)) {
+    if (key.startsWith(name) || loop.name.toLowerCase().includes(name.toLowerCase())) {
+      return { key, loop };
+    }
+  }
+  const available = Object.keys(config.loops).join(", ");
+  throw new Error(`Unknown loop "${name}". Available: ${available}`);
+}
+
+// src/core/claude.ts
+import { spawn } from "child_process";
+async function spawnClaude(options) {
+  const { prompt, model, printMode = false, agentName, cwd } = options;
+  const args = [];
+  if (printMode) {
+    args.push("-p");
+    args.push("--dangerously-skip-permissions");
+  }
+  if (model) {
+    args.push("--model", model);
+  }
+  return new Promise((resolve, reject) => {
+    const child = spawn("claude", args, {
+      cwd,
+      stdio: printMode ? ["pipe", "pipe", "pipe"] : ["pipe", "pipe", "inherit"],
+      env: { ...process.env }
+    });
+    let output = "";
+    child.stdout?.on("data", (data) => {
+      const text = data.toString();
+      output += text;
+      if (agentName) {
+        const lines = text.split("\n");
+        for (const line of lines) {
+          if (line) {
+            process.stdout.write(`[${agentName}] ${line}
+`);
+          }
+        }
+      } else {
+        process.stdout.write(text);
+      }
+    });
+    if (printMode && child.stderr) {
+      child.stderr.on("data", (data) => {
+        const text = data.toString();
+        if (agentName) {
+          process.stderr.write(`[${agentName}] ${text}`);
+        } else {
+          process.stderr.write(text);
+        }
+      });
+    }
+    child.stdin?.write(prompt);
+    child.stdin?.end();
+    child.on("error", (err) => {
+      reject(new Error(`Failed to spawn claude: ${err.message}`));
+    });
+    child.on("close", (code, signal) => {
+      resolve({
+        output,
+        exitCode: code,
+        signal
+      });
+    });
+  });
+}
+
+// src/core/runner.ts
+var AGENT_COLORS = [
+  chalk3.cyan,
+  chalk3.magenta,
+  chalk3.yellow,
+  chalk3.green,
+  chalk3.blue,
+  chalk3.red
+];
+async function runLoop(loopName, options) {
+  const flowDir = resolveFlowDir(options.cwd, options.flow);
+  const config = loadConfig(flowDir);
+  const { key, loop } = resolveLoop(config, loopName);
+  const isMultiAgent = options.agents > 1 && loop.multi_agent !== false;
+  console.log();
+  console.log(
+    chalk3.bold(`  RalphFlow \u2014 ${loop.name}`) + (isMultiAgent ? chalk3.dim(` (${options.agents} agents)`) : "")
+  );
+  console.log();
+  if (isMultiAgent) {
+    await runMultiAgent(loop, flowDir, options);
+  } else {
+    await runSingleAgent(loop, flowDir, options);
+  }
+}
+async function runSingleAgent(loop, flowDir, options) {
+  for (let i = 1; i <= options.maxIterations; i++) {
+    console.log(chalk3.dim(`  Iteration ${i}/${options.maxIterations}`));
+    const prompt = readPrompt(loop, flowDir, options.agentName);
+    const result = await spawnClaude({
+      prompt,
+      model: options.model,
+      printMode: false,
+      cwd: options.cwd
+    });
+    if (result.output.includes(`<promise>${loop.completion}</promise>`)) {
+      console.log();
+      console.log(chalk3.green(`  Loop complete: ${loop.completion}`));
+      return;
+    }
+    if (result.signal === "SIGINT" || result.exitCode === 130) {
+      console.log(chalk3.dim(`  Iteration ${i} complete, restarting...`));
+      console.log();
+      continue;
+    }
+    if (result.exitCode !== 0 && result.exitCode !== null) {
+      console.log(chalk3.red(`  Claude exited with code ${result.exitCode}`));
+      return;
+    }
+    console.log(chalk3.dim(`  Iteration ${i} finished, continuing...`));
+    console.log();
+  }
+  console.log(chalk3.yellow(`  Max iterations (${options.maxIterations}) reached.`));
+}
+async function runMultiAgent(loop, flowDir, options) {
+  const agentCount = options.agents;
+  let completed = false;
+  const agentRunners = Array.from({ length: agentCount }, (_, idx) => {
+    const agentNum = idx + 1;
+    const agentName = `agent-${agentNum}`;
+    const colorFn = AGENT_COLORS[idx % AGENT_COLORS.length];
+    return runAgentLoop(loop, flowDir, {
+      ...options,
+      agentName
+    }, colorFn, () => completed, () => {
+      completed = true;
+    });
+  });
+  await Promise.allSettled(agentRunners);
+  console.log();
+  console.log(chalk3.green(`  All agents finished.`));
+}
+async function runAgentLoop(loop, flowDir, options, colorFn, isCompleted, setCompleted) {
+  const agentName = options.agentName;
+  for (let i = 1; i <= options.maxIterations; i++) {
+    if (isCompleted()) {
+      console.log(colorFn(`  [${agentName}] Stopping \u2014 completion detected.`));
+      return;
+    }
+    console.log(colorFn(`  [${agentName}] Iteration ${i}/${options.maxIterations}`));
+    const prompt = readPrompt(loop, flowDir, agentName);
+    const result = await spawnClaude({
+      prompt,
+      model: options.model,
+      printMode: true,
+      agentName,
+      cwd: options.cwd
+    });
+    if (result.output.includes(`<promise>${loop.completion}</promise>`)) {
+      console.log(colorFn(`  [${agentName}] Loop complete: ${loop.completion}`));
+      setCompleted();
+      return;
+    }
+    if (result.signal === "SIGINT" || result.exitCode === 130) {
+      console.log(colorFn(`  [${agentName}] Iteration ${i} complete, restarting...`));
+      continue;
+    }
+    if (result.exitCode !== 0 && result.exitCode !== null) {
+      console.log(chalk3.red(`  [${agentName}] Claude exited with code ${result.exitCode}`));
+      return;
+    }
+  }
+  console.log(chalk3.yellow(`  [${agentName}] Max iterations reached.`));
+}
+function readPrompt(loop, flowDir, agentName) {
+  const promptPath = join4(flowDir, loop.prompt);
+  let prompt = readFileSync3(promptPath, "utf-8");
+  if (agentName && loop.multi_agent !== false) {
+    const ma = loop.multi_agent;
+    if (ma.agent_placeholder) {
+      prompt = prompt.replaceAll(ma.agent_placeholder, agentName);
+    }
+  }
+  return prompt;
+}
+
+// src/cli/run.ts
+var runCommand = new Command2("run").description("Run a loop").argument("<loop>", "Loop to run (story, tasks, delivery)").option("-a, --agents <n>", "Number of parallel agents", "1").option("-m, --model <model>", "Claude model to use").option("-n, --max-iterations <n>", "Maximum iterations", "30").option("-f, --flow <name>", "Which flow to run (auto-detected if only one)").action(async (loop, opts) => {
+  try {
+    await runLoop(loop, {
+      agents: parseInt(opts.agents, 10),
+      model: opts.model,
+      maxIterations: parseInt(opts.maxIterations, 10),
+      flow: opts.flow,
+      cwd: process.cwd()
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(chalk4.red(`
+  ${msg}
+`));
+    process.exit(1);
+  }
+});
+
+// src/cli/status.ts
+import { Command as Command3 } from "commander";
+import chalk6 from "chalk";
+
+// src/core/status.ts
+import { readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
+import { join as join5 } from "path";
+import chalk5 from "chalk";
+import Table from "cli-table3";
+async function showStatus(cwd, flowName) {
+  const flows = flowName ? [flowName] : listFlows2(cwd);
+  if (flows.length === 0) {
+    console.log();
+    console.log(chalk5.yellow("  No flows found. Run `npx ralphflow init` first."));
+    console.log();
+    return;
+  }
+  for (const flow of flows) {
+    const flowDir = resolveFlowDir(cwd, flow);
+    const config = loadConfig(flowDir);
+    console.log();
+    console.log(chalk5.bold(`  RalphFlow \u2014 ${flow}`));
+    console.log();
+    const table = new Table({
+      chars: {
+        top: "",
+        "top-mid": "",
+        "top-left": "",
+        "top-right": "",
+        bottom: "",
+        "bottom-mid": "",
+        "bottom-left": "",
+        "bottom-right": "",
+        left: "  ",
+        "left-mid": "",
+        mid: "",
+        "mid-mid": "",
+        right: "",
+        "right-mid": "",
+        middle: "  "
+      },
+      style: { "padding-left": 0, "padding-right": 1 },
+      head: [
+        chalk5.dim("Loop"),
+        chalk5.dim("Stage"),
+        chalk5.dim("Active"),
+        chalk5.dim("Progress")
+      ]
+    });
+    const sortedLoops = Object.entries(config.loops).sort(([, a], [, b]) => a.order - b.order);
+    for (const [key, loop] of sortedLoops) {
+      const status = parseTracker(loop.tracker, flowDir, loop.name);
+      table.push([
+        loop.name,
+        status.stage,
+        status.active,
+        `${status.completed}/${status.total}`
+      ]);
+      if (status.agents && status.agents.length > 0) {
+        for (const agent of status.agents) {
+          table.push([
+            chalk5.dim(`  ${agent.name}`),
+            chalk5.dim(agent.stage),
+            chalk5.dim(agent.activeTask),
+            chalk5.dim(agent.lastHeartbeat)
+          ]);
+        }
+      }
+    }
+    console.log(table.toString());
+  }
+  console.log();
+}
+function parseTracker(trackerPath, flowDir, loopName) {
+  const fullPath = join5(flowDir, trackerPath);
+  const status = {
+    loop: loopName,
+    stage: "\u2014",
+    active: "none",
+    completed: 0,
+    total: 0
+  };
+  if (!existsSync4(fullPath)) {
+    return status;
+  }
+  const content = readFileSync4(fullPath, "utf-8");
+  const lines = content.split("\n");
+  for (const line of lines) {
+    const metaMatch = line.match(/^- (\w[\w_]*): (.+)$/);
+    if (metaMatch) {
+      const [, key, value] = metaMatch;
+      if (key === "stage") status.stage = value.trim();
+      if (key === "active_story" || key === "active_task") status.active = value.trim();
+      if (key === "completed_stories" || key === "completed_tasks") {
+        const arrayMatch = value.match(/\[(.+)\]/);
+        if (arrayMatch) {
+          status.completed = arrayMatch[1].split(",").filter((s) => s.trim()).length;
+        }
+      }
+    }
+  }
+  const unchecked = (content.match(/- \[ \]/g) || []).length;
+  const checked = (content.match(/- \[x\]/gi) || []).length;
+  if (unchecked + checked > 0) {
+    status.total = unchecked + checked;
+    status.completed = checked;
+  }
+  const agentTableMatch = content.match(/\| agent \|.*\n\|[-|]+\n((?:\|.*\n)*)/);
+  if (agentTableMatch) {
+    const agentRows = agentTableMatch[1].trim().split("\n");
+    status.agents = [];
+    for (const row of agentRows) {
+      const cells = row.split("|").map((s) => s.trim()).filter(Boolean);
+      if (cells.length >= 4) {
+        status.agents.push({
+          name: cells[0],
+          activeTask: cells[1],
+          stage: cells[2],
+          lastHeartbeat: cells[3]
+        });
+      }
+    }
+    if (status.agents.length === 0) {
+      status.agents = void 0;
+    }
+  }
+  return status;
+}
+
+// src/cli/status.ts
+var statusCommand = new Command3("status").description("Show pipeline status").option("-f, --flow <name>", "Show status for a specific flow").action(async (opts) => {
+  try {
+    await showStatus(process.cwd(), opts.flow);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(chalk6.red(`
+  ${msg}
+`));
+    process.exit(1);
+  }
+});
+
+// src/cli/index.ts
+var program = new Command4().name("ralphflow").description("Multi-agent AI workflow orchestration for Claude Code").version("0.1.0").addCommand(initCommand).addCommand(runCommand).addCommand(statusCommand);
+process.on("SIGINT", () => {
+  console.log();
+  console.log(chalk7.dim("  Interrupted."));
+  process.exit(130);
+});
+program.configureOutput({
+  writeErr: (str) => {
+    const clean = str.replace(/^error: /, "");
+    if (clean.trim()) {
+      console.error(chalk7.red(`  ${clean.trim()}`));
+    }
+  }
+});
+
+// src/bin/ralphflow.ts
+program.parse();

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "ralphflow",
+  "version": "0.1.0",
+  "description": "Multi-agent AI workflow orchestration framework for Claude Code. Define pipelines as loops, coordinate parallel agents, and ship structured work.",
+  "type": "module",
+  "bin": {
+    "ralphflow": "./dist/ralphflow.js"
+  },
+  "main": "./dist/core/index.js",
+  "types": "./dist/core/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/core/index.js",
+      "types": "./dist/core/index.d.ts"
+    },
+    "./cli": {
+      "import": "./dist/cli/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai-agents",
+    "multi-agent",
+    "workflow",
+    "orchestration",
+    "pipeline",
+    "state-machine",
+    "automation",
+    "developer-tools"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/user/ralph-flow"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist/",
+    "src/templates/"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "chokidar": "^4.0.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.1.0",
+    "hono": "^4.6.0",
+    "simple-git": "^3.27.0",
+    "ws": "^8.18.0",
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0"
+  }
+}

package/src/templates/claude-md.template.md

@@ -0,0 +1,33 @@
+# {{PROJECT_NAME}}
+
+{{PROJECT_DESCRIPTION}}
+
+## Architecture
+
+**Stack:** {{TECH_STACK}}
+
+<!-- Describe: folder structure, key modules, data flow, external services -->
+
+## Commands
+
+### Development
+{{DEV_COMMANDS}}
+
+### Testing
+<!-- npm test, pytest, etc. -->
+
+### Build & Deploy
+<!-- docker compose up, npm run build, etc. -->
+
+### Health Checks
+<!-- curl localhost:3000/health, etc. -->
+
+## Conventions
+
+- Follow existing patterns in the codebase
+- Write tests for new functionality
+- Use descriptive commit messages
+
+## URLs & Endpoints
+
+<!-- API base URL, frontend URL, admin panel, etc. -->

package/src/templates/code-implementation/loops/00-story-loop/loop.md

@@ -0,0 +1,21 @@
+# Story Loop — Execution
+
+## Using RalphFlow CLI
+
+```bash
+npx ralphflow run story
+```
+
+## Manual (without CLI)
+
+### Option 1: ralph-loop slash command
+
+```
+/ralph-loop "$(cat .ralph-flow/00-story-loop/prompt.md)" --max-iterations 30 --completion-promise "ALL STORIES PROCESSED"
+```
+
+### Option 2: while loop
+
+```bash
+while :; do cat .ralph-flow/00-story-loop/prompt.md | claude --dangerously-skip-permissions --model claude-opus-4-6; done
+```