ralphflow 0.1.0 → 0.3.0

package/README.md

@@ -1,5 +1,9 @@
 # RalphFlow
 
+<p align="center">
+  <img src="WiggumFlow.png" alt="RalphFlow" width="400" />
+</p>
+
 Multi-agent AI workflow orchestration for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
 
 Define pipelines as loops, coordinate parallel agents via file-based trackers, and ship structured work — from single-agent interactive sessions to multi-agent autonomous execution.

package/dist/ralphflow.js

@@ -141,7 +141,7 @@ import { Command as Command2 } from "commander";
 import chalk4 from "chalk";
 
 // src/core/runner.ts
-import { readFileSync as readFileSync3 } from "fs";
+import { readFileSync as readFileSync3, existsSync as existsSync4, mkdirSync as mkdirSync2, writeFileSync, readdirSync as readdirSync3, unlinkSync } from "fs";
 import { join as join4 } from "path";
 import chalk3 from "chalk";
 
@@ -150,12 +150,19 @@ import { readFileSync as readFileSync2, existsSync as existsSync3, readdirSync a
 import { join as join3 } from "path";
 import { parse as parseYaml } from "yaml";
 var LOOP_ALIASES = {
+  // code-implementation aliases
   story: "story-loop",
   stories: "story-loop",
   tasks: "tasks-loop",
   task: "tasks-loop",
   delivery: "delivery-loop",
-  deliver: "delivery-loop"
+  deliver: "delivery-loop",
+  // research aliases
+  discovery: "discovery-loop",
+  discover: "discovery-loop",
+  research: "research-loop",
+  document: "document-loop",
+  doc: "document-loop"
 };
 function listFlows2(cwd) {
   const baseDir = join3(cwd, ".ralph-flow");
@@ -222,55 +229,23 @@ function resolveLoop(config, name) {
 // 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");
-  }
+  const { prompt, model, cwd } = options;
+  const args = ["--dangerously-skip-permissions", prompt];
   if (model) {
-    args.push("--model", model);
+    args.unshift("--model", model);
   }
   return new Promise((resolve, reject) => {
     const child = spawn("claude", args, {
       cwd,
-      stdio: printMode ? ["pipe", "pipe", "pipe"] : ["pipe", "pipe", "inherit"],
+      stdio: "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,
+        output: "",
         exitCode: code,
         signal
       });
@@ -279,41 +254,104 @@ async function spawnClaude(options) {
 }
 
 // src/core/runner.ts
-var AGENT_COLORS = [
-  chalk3.cyan,
-  chalk3.magenta,
-  chalk3.yellow,
-  chalk3.green,
-  chalk3.blue,
-  chalk3.red
-];
+function agentsDir(flowDir, loop) {
+  const loopDir = join4(flowDir, loop.tracker, "..");
+  return join4(loopDir, ".agents");
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function cleanStaleAgents(dir) {
+  if (!existsSync4(dir)) return;
+  for (const file of readdirSync3(dir)) {
+    if (!file.endsWith(".lock")) continue;
+    const pidStr = readFileSync3(join4(dir, file), "utf-8").trim();
+    const pid = parseInt(pidStr, 10);
+    if (isNaN(pid) || !isProcessAlive(pid)) {
+      unlinkSync(join4(dir, file));
+    }
+  }
+}
+function acquireAgentId(dir, maxAgents) {
+  mkdirSync2(dir, { recursive: true });
+  cleanStaleAgents(dir);
+  for (let n = 1; n <= maxAgents; n++) {
+    const lockFile = join4(dir, `agent-${n}.lock`);
+    if (!existsSync4(lockFile)) {
+      writeFileSync(lockFile, String(process.pid));
+      return `agent-${n}`;
+    }
+  }
+  throw new Error(`All ${maxAgents} agent slots are occupied. Wait for one to finish or increase max_agents.`);
+}
+function releaseAgentId(dir, agentName) {
+  const lockFile = join4(dir, `${agentName}.lock`);
+  try {
+    unlinkSync(lockFile);
+  } catch {
+  }
+}
+function checkTrackerForCompletion(flowDir, loop) {
+  const trackerPath = join4(flowDir, loop.tracker);
+  if (!existsSync4(trackerPath)) return false;
+  const content = readFileSync3(trackerPath, "utf-8");
+  return content.includes(`<promise>${loop.completion}</promise>`);
+}
 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;
+  let agentName;
+  let agentDir;
+  if (options.multiAgent) {
+    if (loop.multi_agent === false) {
+      throw new Error(`Loop "${loop.name}" does not support multi-agent mode.`);
+    }
+    const ma = loop.multi_agent;
+    agentDir = agentsDir(flowDir, loop);
+    agentName = acquireAgentId(agentDir, ma.max_agents);
+  }
   console.log();
   console.log(
-    chalk3.bold(`  RalphFlow \u2014 ${loop.name}`) + (isMultiAgent ? chalk3.dim(` (${options.agents} agents)`) : "")
+    chalk3.bold(`  RalphFlow \u2014 ${loop.name}`) + (agentName ? chalk3.dim(` [${agentName}]`) : "")
   );
   console.log();
-  if (isMultiAgent) {
-    await runMultiAgent(loop, flowDir, options);
-  } else {
-    await runSingleAgent(loop, flowDir, options);
+  const cleanup = () => {
+    if (agentDir && agentName) {
+      releaseAgentId(agentDir, agentName);
+    }
+  };
+  process.on("exit", cleanup);
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(130);
+  });
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(143);
+  });
+  try {
+    await iterationLoop(loop, flowDir, options, agentName);
+  } finally {
+    cleanup();
   }
 }
-async function runSingleAgent(loop, flowDir, options) {
+async function iterationLoop(loop, flowDir, options, agentName) {
   for (let i = 1; i <= options.maxIterations; i++) {
-    console.log(chalk3.dim(`  Iteration ${i}/${options.maxIterations}`));
-    const prompt = readPrompt(loop, flowDir, options.agentName);
+    const label = agentName ? chalk3.dim(`  [${agentName}] Iteration ${i}/${options.maxIterations}`) : chalk3.dim(`  Iteration ${i}/${options.maxIterations}`);
+    console.log(label);
+    const prompt = readPrompt(loop, flowDir, agentName);
     const result = await spawnClaude({
       prompt,
       model: options.model,
-      printMode: false,
       cwd: options.cwd
     });
-    if (result.output.includes(`<promise>${loop.completion}</promise>`)) {
+    if (checkTrackerForCompletion(flowDir, loop)) {
       console.log();
       console.log(chalk3.green(`  Loop complete: ${loop.completion}`));
       return;
@@ -323,64 +361,15 @@ async function runSingleAgent(loop, flowDir, options) {
       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...`));
+    if (result.exitCode === 0 || result.exitCode === null) {
+      console.log(chalk3.dim(`  Iteration ${i} finished, continuing...`));
+      console.log();
       continue;
     }
-    if (result.exitCode !== 0 && result.exitCode !== null) {
-      console.log(chalk3.red(`  [${agentName}] Claude exited with code ${result.exitCode}`));
-      return;
-    }
+    console.log(chalk3.red(`  Claude exited with code ${result.exitCode}`));
+    return;
   }
-  console.log(chalk3.yellow(`  [${agentName}] Max iterations reached.`));
+  console.log(chalk3.yellow(`  Max iterations (${options.maxIterations}) reached.`));
 }
 function readPrompt(loop, flowDir, agentName) {
   const promptPath = join4(flowDir, loop.prompt);
@@ -395,10 +384,10 @@ function readPrompt(loop, flowDir, agentName) {
 }
 
 // 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) => {
+var runCommand = new Command2("run").description("Run a loop").argument("<loop>", "Loop to run (story, tasks, delivery, discovery, research, document)").option("--multi-agent", "Run as a multi-agent instance (auto-assigns agent ID)").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),
+      multiAgent: !!opts.multiAgent,
       model: opts.model,
       maxIterations: parseInt(opts.maxIterations, 10),
       flow: opts.flow,
@@ -418,7 +407,7 @@ import { Command as Command3 } from "commander";
 import chalk6 from "chalk";
 
 // src/core/status.ts
-import { readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
+import { readFileSync as readFileSync4, existsSync as existsSync5 } from "fs";
 import { join as join5 } from "path";
 import chalk5 from "chalk";
 import Table from "cli-table3";
@@ -495,7 +484,7 @@ function parseTracker(trackerPath, flowDir, loopName) {
     completed: 0,
     total: 0
   };
-  if (!existsSync4(fullPath)) {
+  if (!existsSync5(fullPath)) {
     return status;
   }
   const content = readFileSync4(fullPath, "utf-8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralphflow",
-  "version": "0.1.0",
+  "version": "0.3.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": {
@@ -40,7 +40,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/user/ralph-flow"
+    "url": "https://github.com/rahulthakur319/ralph-flow"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/templates/research/loops/00-discovery-loop/loop.md

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

package/src/templates/research/loops/00-discovery-loop/prompt.md

@@ -0,0 +1,119 @@
+# Discovery Loop — Identify Research Topics
+
+Read `.ralph-flow/00-discovery-loop/tracker.md` FIRST to determine where you are.
+
+> **Map the territory before exploring it.** Your job is to take a broad research brief and decompose it into specific, researchable topics. Each topic should be independently investigable and contribute to the overall research goal.
+
+> **WRITE ONLY TO:** `00-discovery-loop/topics.md`, `00-discovery-loop/tracker.md`, `01-research-loop/tracker.md`, `01-research-loop/findings.md`.
+
+**Pipeline:** `user brief → YOU → topics.md → 01-research-loop → findings`
+
+---
+
+## No Brief? Collect One
+
+If `topics.md` has no unprocessed topics and the tracker queue is empty/all done:
+1. Tell the user: *"No research brief found. Tell me what you want to research — describe questions, problems, or domains you want to understand."*
+2. Use `AskUserQuestion` to prompt: "What do you want to research or understand?" (open-ended)
+3. As the user narrates, capture the research brief in tracker log under `## Research Brief`
+4. **Confirm scope** — present the brief back. Use `AskUserQuestion` (up to 5 questions) to validate: correct scope? right depth? any areas to include/exclude? target audience? desired output format (PDF, PPT, document)?
+5. Apply corrections, finalize brief, proceed to normal flow
+
+---
+
+## State Machine (3 stages)
+
+```
+SCOPE    → Understand the research brief, define boundaries → stage: explore
+EXPLORE  → Search broadly for sub-domains, angles, key questions → stage: decompose
+DECOMPOSE → Break into TOPIC entries, write to topics.md, seed research tracker → kill
+```
+
+## First-Run Handling
+
+If Topics Queue in tracker is empty and Research Brief exists: proceed to SCOPE. If Topics Queue is populated, check for remaining unprocessed items.
+
+---
+
+## STAGE 1: SCOPE
+
+1. Read tracker → check if a Research Brief exists
+2. Read any existing context: `CLAUDE.md`, project files, existing research
+3. **Define research boundaries:**
+   - What is in scope vs. out of scope
+   - What depth is needed (surface survey vs. deep dive)
+   - Who is the audience (technical, executive, public)
+   - What output format is expected
+4. Update tracker: `stage: explore`, log entry with scope decisions
+
+## STAGE 2: EXPLORE
+
+1. **Broad exploration** — use `WebSearch`, `WebFetch`, file reads to survey the domain:
+   - Search for 10+ different angles on the research question
+   - Identify key sub-domains, stakeholders, competing perspectives
+   - Note data sources, reports, standards, regulations that exist
+   - Find gaps — what's hard to find, what's controversial, what needs primary research
+2. **Cluster findings** — group related areas into potential topic clusters
+3. Update tracker: `stage: decompose`, log entry with exploration summary
+
+## STAGE 3: DECOMPOSE
+
+1. Find next TOPIC numbers (check existing in `00-discovery-loop/topics.md`)
+2. Break the research space into **5-15 specific topics**, each:
+   - Independently researchable by a single agent
+   - Specific enough to produce focused findings (not "research everything about X")
+   - Clearly scoped with guiding questions
+   - Tagged with priority (high/medium/low) and estimated depth
+3. Append to `00-discovery-loop/topics.md` (format below)
+4. **Seed `01-research-loop/tracker.md`:**
+   1. Acquire `.ralph-flow/01-research-loop/.tracker-lock`:
+      - Exists + < 60s old → sleep 2s, retry up to 5 retries
+      - Exists + ≥ 60s old → stale, delete it
+      - Not exists → continue
+      - Write lock: `echo "discovery-loop $(date -u +%Y-%m-%dT%H:%M:%SZ)" > .ralph-flow/01-research-loop/.tracker-lock`
+      - Sleep 500ms, re-read lock, verify `discovery-loop` is in it
+   2. Add topics to `## Topics Queue` with metadata:
+      - `{agent: -, status: pending}` for topics with no dependencies
+      - `{agent: -, status: blocked}` for topics that depend on other topics
+   3. Add dependency entries to `## Dependencies` section
+   4. Release lock: `rm .ralph-flow/01-research-loop/.tracker-lock`
+5. Update own tracker: mark complete, `stage: scope`, log entry
+6. Exit: `kill -INT $PPID`
+
+If all topics have been discovered and queue is empty: `<promise>ALL TOPICS DISCOVERED</promise>`
+
+**Topic format:**
+```markdown
+## TOPIC-{N}: {Concise title}
+
+**Priority:** {high | medium | low}
+**Depth:** {surface | moderate | deep}
+**Depends on:** {TOPIC-{M} or "None"}
+
+### Research Question
+{The specific question(s) this topic should answer. 1-3 sentences.}
+
+### Scope
+{What to include and exclude. Key angles to cover.}
+
+### Suggested Sources
+{Types of sources to look for: government data, academic papers, news, industry reports, etc.}
+
+### Success Criteria
+- [ ] {What constitutes a complete investigation of this topic}
+```
+
+---
+
+## Rules
+
+- One research brief at a time. All 3 stages run in one iteration, one `kill` at the end.
+- Read tracker first, update tracker last.
+- Append to `topics.md` — never overwrite. Numbers globally unique and sequential.
+- Topics must be self-contained — the research loop never reads the original brief directly.
+- Each topic should take 1-3 research iterations to complete, not more.
+- Mark inter-topic dependencies explicitly (some topics build on findings from others).
+
+---
+
+Read `.ralph-flow/00-discovery-loop/tracker.md` now and begin.

package/src/templates/research/loops/00-discovery-loop/topics.md

@@ -0,0 +1,3 @@
+# Topics
+
+<!-- Add topics below. Format: ## TOPIC-{N}: {Title} + **Depends on:** tag -->

package/src/templates/research/loops/00-discovery-loop/tracker.md

@@ -0,0 +1,15 @@
+# Discovery Loop — Tracker
+
+- stage: scope
+- completed_topics: []
+- pending_topics: []
+
+---
+
+## Research Brief
+
+## Topics Queue
+
+## Dependency Graph
+
+## Log

package/src/templates/research/loops/01-research-loop/findings.md

@@ -0,0 +1,3 @@
+# Findings
+
+<!-- Add findings below. Format: ## FINDING-{N}: {Title} -->

package/src/templates/research/loops/01-research-loop/loop.md

@@ -0,0 +1,60 @@
+# Research Loop — Execution
+
+## Using RalphFlow CLI
+
+```bash
+# Single agent
+npx ralphflow run research
+
+# Multi-agent (3 parallel agents)
+npx ralphflow run research --agents 3
+```
+
+## Manual (without CLI)
+
+### Single Agent
+
+#### Option 1: ralph-loop slash command
+
+```
+/ralph-loop "$(cat .ralph-flow/01-research-loop/prompt.md)" --max-iterations 50 --completion-promise "ALL TOPICS RESEARCHED"
+```
+
+#### Option 2: while loop
+
+```bash
+while :; do cat .ralph-flow/01-research-loop/prompt.md | claude --dangerously-skip-permissions --model claude-opus-4-6; done
+```
+
+---
+
+### Multi-Agent (2+ terminals)
+
+Each terminal runs a named agent. `{{AGENT_NAME}}` is injected via `sed`.
+
+#### Terminal 1
+
+```bash
+AGENT=agent-1 && while :; do sed "s/{{AGENT_NAME}}/$AGENT/g" .ralph-flow/01-research-loop/prompt.md | claude --dangerously-skip-permissions --model claude-opus-4-6; done
+```
+
+#### Terminal 2
+
+```bash
+AGENT=agent-2 && while :; do sed "s/{{AGENT_NAME}}/$AGENT/g" .ralph-flow/01-research-loop/prompt.md | claude --dangerously-skip-permissions --model claude-opus-4-6; done
+```
+
+#### Terminal 3 (optional)
+
+```bash
+AGENT=agent-3 && while :; do sed "s/{{AGENT_NAME}}/$AGENT/g" .ralph-flow/01-research-loop/prompt.md | claude --dangerously-skip-permissions --model claude-opus-4-6; done
+```
+
+---
+
+## Notes
+
+- Single agent mode uses `cat` — no `{{AGENT_NAME}}` substitution needed (prompt defaults to `agent-1`)
+- Multi-agent mode uses `sed` to inject the agent name into the prompt
+- Each agent gets its own terminal — they coordinate via `tracker.md`
+- Up to 4 agents can run concurrently depending on topic dependency chains

package/src/templates/research/loops/01-research-loop/prompt.md

@@ -0,0 +1,182 @@
+# Research Loop — Investigate Topics
+
+**You are agent `{{AGENT_NAME}}`.** Multiple agents may work in parallel.
+Coordinate via `tracker.md` — the single source of truth.
+*(If you see the literal text `{{AGENT_NAME}}` above — i.e., it was not substituted — treat your name as `agent-1`.)*
+
+Read `.ralph-flow/01-research-loop/tracker.md` FIRST to determine where you are.
+
+> **Go deep, stay focused.** Each topic is a specific research question. Your job is to investigate thoroughly and produce structured findings. Use web search, file reading, and any available tools to gather evidence.
+
+**Pipeline:** `topics.md → YOU → findings.md → 02-story-loop → narratives`
+
+---
+
+## Tracker Lock Protocol
+
+Before ANY write to `tracker.md`, you MUST acquire the lock:
+
+**Lock file:** `.ralph-flow/01-research-loop/.tracker-lock`
+
+### Acquire Lock
+1. Check if `.tracker-lock` exists
+   - Exists AND file is < 60 seconds old → sleep 2s, retry (up to 5 retries)
+   - Exists AND file is ≥ 60 seconds old → stale lock, delete it (agent crashed mid-write)
+   - Does not exist → continue
+2. Write lock: `echo "{{AGENT_NAME}} $(date -u +%Y-%m-%dT%H:%M:%SZ)" > .ralph-flow/01-research-loop/.tracker-lock`
+3. Sleep 500ms (`sleep 0.5`)
+4. Re-read `.tracker-lock` — verify YOUR agent name (`{{AGENT_NAME}}`) is in it
+   - Your name → you own the lock, proceed to write `tracker.md`
+   - Other name → you lost the race, retry from step 1
+5. Write your changes to `tracker.md`
+6. Delete `.tracker-lock` immediately: `rm .ralph-flow/01-research-loop/.tracker-lock`
+7. Never leave a lock held — if your write fails, delete the lock in your error handler
+
+### When to Lock
+- Claiming a topic (pending → in_progress)
+- Completing a topic (in_progress → completed)
+- Updating stage transitions
+- Heartbeat updates (bundled with other writes, not standalone)
+
+### When NOT to Lock
+- Reading `tracker.md` — read-only access needs no lock
+- Reading `topics.md` or `findings.md` — always read-only for topics, append-only for findings
+
+---
+
+## Topic Selection Algorithm
+
+1. **Parse tracker** — read `completed_topics`, `## Dependencies`, Topics Queue metadata `{agent, status}`, Agent Status table
+2. **Update blocked→pending** — for each topic with `status: blocked`, check if ALL its dependencies (from `## Dependencies`) are in `completed_topics`. If yes, acquire lock and update to `status: pending`
+3. **Resume own work** — if any topic has `{agent: {{AGENT_NAME}}, status: in_progress}`, resume it (skip to the current stage)
+4. **Find claimable** — filter topics where `status: pending` AND `agent: -`
+5. **Apply priority** — prefer high-priority topics, then medium, then low
+6. **Claim** — acquire lock, set `{agent: {{AGENT_NAME}}, status: in_progress}`, update your Agent Status row, update `last_heartbeat`, release lock, log the claim
+7. **Nothing available:**
+   - All topics completed → emit `<promise>ALL TOPICS RESEARCHED</promise>`
+   - All remaining topics are blocked or claimed by others → log "{{AGENT_NAME}}: waiting — all topics blocked or claimed", exit: `kill -INT $PPID`
+
+### New Topic Discovery
+
+If you find a topic in the Topics Queue without `{agent, status}` metadata (e.g., added by the discovery loop while agents were running):
+1. Read the topic's `**Depends on:**` field in `topics.md`
+2. Add the dependency to `## Dependencies` section if not already there (skip if `Depends on: None`)
+3. Set status to `pending` (all deps in `completed_topics`) or `blocked` (deps incomplete)
+4. Set agent to `-`
+
+---
+
+## Anti-Hijacking Rules
+
+1. **Never touch another agent's `in_progress` topic** — do not modify, complete, or reassign it
+2. **Respect priority** — do not skip high-priority topics to grab low-priority ones unless high-priority are all blocked/claimed
+3. **Note overlap** — if your topic overlaps with another agent's active topic, log a NOTE in the tracker and avoid duplicating their research angles
+
+---
+
+## Heartbeat Protocol
+
+Every tracker write includes updating your `last_heartbeat` to current ISO 8601 timestamp in the Agent Status table. If another agent's heartbeat is **30+ minutes stale**, log a WARNING in the tracker log but do NOT auto-reclaim their topic — user must manually reset.
+
+---
+
+## Crash Recovery (Self)
+
+On fresh start, if your agent name has an `in_progress` topic but you have no memory of it:
+- Findings already written for that topic → resume at SYNTHESIZE stage
+- No findings found → restart from INVESTIGATE stage
+
+---
+
+## State Machine (2 stages per topic)
+
+```
+INVESTIGATE → Search, read, gather evidence on the topic           → stage: synthesize
+SYNTHESIZE  → Structure findings, write to findings.md, mark done  → next topic
+```
+
+When ALL done: `<promise>ALL TOPICS RESEARCHED</promise>`
+
+After completing ANY stage, exit: `kill -INT $PPID`
+
+---
+
+## STAGE 1: INVESTIGATE
+
+1. Read tracker → **run topic selection algorithm** (see above)
+2. Read topic in `topics.md` — understand the research question, scope, suggested sources
+3. If sibling topics are done, read their findings to avoid duplication and build on prior work
+4. Acquire lock → update tracker: your Agent Status row `active_topic: TOPIC-{N}`, `stage: investigate`, `last_heartbeat`, log entry → release lock
+5. **Deep research:**
+   - Use `WebSearch` for 5-10 different search queries covering different angles of the topic
+   - Use `WebFetch` to read key sources in detail (reports, articles, data pages)
+   - Read any relevant local files (project docs, data files, prior research)
+   - Cross-reference sources — look for consensus and disagreements
+   - Note data points, statistics, quotes, and source URLs
+   - If the topic requires it, explore primary sources (government sites, official reports)
+6. **Organize raw notes** — keep structured scratch notes as you research
+7. Acquire lock → update tracker: `stage: synthesize`, `last_heartbeat`, log entry → release lock
+8. Exit: `kill -INT $PPID`
+
+## STAGE 2: SYNTHESIZE
+
+1. Read your raw notes and all gathered evidence
+2. **Structure findings** — write a FINDING entry to `01-research-loop/findings.md`:
+   - Use the finding format below
+   - Include specific data points, statistics, and source citations
+   - Note confidence level for each key claim
+   - Flag gaps — what couldn't be found, what needs primary research
+3. Acquire lock:
+   - Add topic to `completed_topics` list
+   - Check off topic in Topics Queue: `[x]`, set `{completed}`
+   - **Unblock dependents:** for each topic in `## Dependencies` that lists the just-completed topic, check if ALL its dependencies are now in `completed_topics`. If yes, update that topic's status from `blocked` → `pending`
+   - Update your Agent Status row: clear `active_topic`
+   - Update `last_heartbeat`
+   - Log entry
+   - Release lock
+4. **Run topic selection algorithm again:**
+   - Claimable topic found → claim it, exit: `kill -INT $PPID`
+   - All topics completed → `<promise>ALL TOPICS RESEARCHED</promise>`
+   - All blocked/claimed → log "waiting", exit: `kill -INT $PPID`
+
+**Finding format:**
+```markdown
+## FINDING-{N}: {Title matching TOPIC title}
+
+**Source Topic:** TOPIC-{M}
+**Researched by:** {{AGENT_NAME}}
+**Date:** {ISO 8601 date}
+**Confidence:** {high | medium | low}
+
+### Key Findings
+{3-7 bullet points summarizing the most important discoveries. Each should be specific and evidence-backed.}
+
+### Detailed Analysis
+{2-4 paragraphs of structured analysis. Include data points, statistics, comparisons.}
+
+### Sources
+{Numbered list of sources with URLs where available}
+1. {Source title} — {URL or description}
+
+### Gaps & Open Questions
+{What couldn't be answered? What needs further investigation or primary research?}
+```
+
+---
+
+## First-Run Handling
+
+If Topics Queue in tracker is empty: read `topics.md`, scan `## TOPIC-{N}:` headers + `**Depends on:**` tags, populate queue with `{agent: -, status: pending|blocked}` metadata, then start.
+
+## Rules
+
+- One topic at a time per agent. One stage per iteration.
+- Read tracker first, update tracker last. Always use lock protocol for writes.
+- Append to `findings.md` — never overwrite. FINDING numbers match TOPIC numbers (FINDING-1 for TOPIC-1).
+- Findings must be self-contained — the story loop never reads `topics.md`.
+- Cite sources. Include URLs. Note confidence levels.
+- **Multi-agent: never touch another agent's in_progress topic. Coordinate via tracker.md.**
+
+---
+
+Read `.ralph-flow/01-research-loop/tracker.md` now and begin.

package/src/templates/research/loops/01-research-loop/tracker.md

@@ -0,0 +1,16 @@
+# Research Loop — Tracker
+
+- completed_topics: []
+
+## Agent Status
+
+| agent | active_topic | stage | last_heartbeat |
+|-------|--------------|-------|----------------|
+
+---
+
+## Dependencies
+
+## Topics Queue
+
+## Log

package/src/templates/research/loops/02-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/02-story-loop/prompt.md)" --max-iterations 20 --completion-promise "ALL STORIES WRITTEN"
+```
+
+### Option 2: while loop
+
+```bash
+while :; do cat .ralph-flow/02-story-loop/prompt.md | claude --dangerously-skip-permissions --model claude-opus-4-6; done
+```

package/src/templates/research/loops/02-story-loop/prompt.md

@@ -0,0 +1,109 @@
+# Story Loop — Condense Findings into Narratives
+
+Read `.ralph-flow/02-story-loop/tracker.md` FIRST to determine where you are.
+
+> **Turn research into readable stories.** Your job is to take raw findings and synthesize them into coherent, well-structured narrative stories. Each story should stand on its own while contributing to the overall research picture.
+
+> **WRITE ONLY TO:** `02-story-loop/stories.md`, `02-story-loop/tracker.md`.
+
+**Pipeline:** `findings.md → YOU → stories.md → 03-document-loop → final output`
+
+---
+
+## No Findings? Wait
+
+If `findings.md` has no unprocessed findings and the tracker queue is empty/all done:
+1. Check `01-research-loop/tracker.md` — is the research loop still running?
+   - Yes → tell user "Research is still in progress. Run story loop after research completes."
+   - No → `<promise>ALL STORIES WRITTEN</promise>`
+
+---
+
+## State Machine (2 stages per story)
+
+```
+DRAFT  → Read findings, identify themes, draft a narrative story → stage: refine
+REFINE → Polish language, verify citations, ensure coherence → mark done, kill
+```
+
+## First-Run Handling
+
+If Stories Queue in tracker is empty:
+1. Read ALL findings from `01-research-loop/findings.md`
+2. **Identify story themes** — group related findings into story clusters:
+   - Look for natural narrative arcs (problem → evidence → insight)
+   - Group by theme, not by topic number
+   - A story may synthesize 2-5 findings
+   - Some findings may contribute to multiple stories
+3. Create story entries in queue with titles and source findings
+4. Proceed to first story
+
+---
+
+## STAGE 1: DRAFT
+
+1. Read tracker → pick next unprocessed story from queue
+2. Read ALL source findings for this story from `findings.md`
+3. Read completed stories from `stories.md` to maintain consistency and avoid repetition
+4. **Draft the narrative:**
+   - Open with a compelling hook or framing question
+   - Build the argument/narrative logically
+   - Weave in specific data points, statistics, and evidence from findings
+   - Include source citations (inline references to finding sources)
+   - Address counterarguments or gaps where relevant
+   - Close with implications or key takeaways
+5. Write draft to `stories.md` (format below)
+6. Update tracker: `active_story: STORY-{N}`, `stage: refine`, log entry
+
+## STAGE 2: REFINE
+
+1. Re-read the draft from `stories.md`
+2. **Polish and verify:**
+   - Check narrative flow — does each paragraph lead naturally to the next?
+   - Verify all cited data points match the source findings
+   - Ensure the story stands alone (reader doesn't need to read findings)
+   - Tighten language — remove filler, sharpen claims, strengthen evidence links
+   - Add section headers for readability if the story is long
+   - Verify the story doesn't duplicate content from other completed stories
+3. Update the story in `stories.md` with refined version
+4. Mark done in tracker: check off queue entry, update `active_story: none`, `stage: draft`, log entry
+5. Exit: `kill -INT $PPID`
+
+If all stories written: `<promise>ALL STORIES WRITTEN</promise>`
+
+**Story format:**
+```markdown
+## STORY-{N}: {Compelling title}
+
+**Source Findings:** FINDING-{A}, FINDING-{B}, ...
+**Theme:** {1-sentence theme descriptor}
+**Word Count:** {target: 500-1500 words}
+
+### {Opening section header}
+{Hook + context setting. 1-2 paragraphs.}
+
+### {Evidence/analysis section header}
+{Core argument with data points and citations. 2-4 paragraphs.}
+
+### {Implications/takeaway section header}
+{What this means, what to do about it. 1-2 paragraphs.}
+
+---
+**Sources:** {Consolidated list of sources cited in this story}
+```
+
+---
+
+## Rules
+
+- One story at a time. Both stages run in one iteration, one `kill` at the end.
+- Read tracker first, update tracker last.
+- Stories must be self-contained — a reader should understand the story without reading the raw findings.
+- Write for the audience identified in the discovery loop's research brief (check `00-discovery-loop/tracker.md` for audience context).
+- Cite specific data points. Don't make vague claims — tie everything back to evidence.
+- Each story should be 500-1500 words. Quality over quantity.
+- Stories synthesize findings — they don't just summarize them. Add narrative structure, analysis, and implications.
+
+---
+
+Read `.ralph-flow/02-story-loop/tracker.md` now and begin.

package/src/templates/research/loops/02-story-loop/stories.md

@@ -0,0 +1,3 @@
+# Stories
+
+<!-- Add stories below. Format: ## STORY-{N}: {Title} -->

package/src/templates/research/loops/02-story-loop/tracker.md

@@ -0,0 +1,13 @@
+# Story Loop — Tracker
+
+- active_story: none
+- stage: draft
+- completed_stories: []
+
+---
+
+## Stories Queue
+
+## Completed Mapping
+
+## Log

package/src/templates/research/loops/03-document-loop/loop.md

@@ -0,0 +1,30 @@
+# Document Loop — Execution
+
+## Using RalphFlow CLI
+
+```bash
+npx ralphflow run document
+```
+
+## Manual (on-demand, single run)
+
+### Option 1: ralph-loop slash command
+
+```
+/ralph-loop "$(cat .ralph-flow/03-document-loop/prompt.md)" --max-iterations 1 --completion-promise "DOCUMENT COMPLETE"
+```
+
+### Option 2: Direct invocation (no while loop — runs once)
+
+```bash
+cat .ralph-flow/03-document-loop/prompt.md | claude --dangerously-skip-permissions --model claude-opus-4-6
+```
+
+---
+
+## Notes
+
+- This is an **on-demand** loop — it runs once to produce the final document, not in a recurring while loop
+- Run this after the story loop has completed all stories
+- The agent will ask for output format preferences if not specified in the research brief
+- Output files are written to the project root directory

package/src/templates/research/loops/03-document-loop/prompt.md

@@ -0,0 +1,122 @@
+# Document Loop — Compile Stories into Final Output
+
+Read `.ralph-flow/03-document-loop/tracker.md` FIRST to determine where you are.
+
+> **This is an on-demand loop.** Unlike discovery, research, and story loops, this loop runs once to produce the final document. It reads all completed stories and compiles them into the requested output format.
+
+> **WRITE ONLY TO:** `03-document-loop/tracker.md`, and the output file(s) in the project directory.
+
+**Pipeline:** `stories.md → YOU → final document (PDF, PPT, Markdown, etc.)`
+
+---
+
+## STAGE 1: COMPILE
+
+1. **Read context:**
+   - Read `00-discovery-loop/tracker.md` → get the Research Brief (audience, scope, output format)
+   - Read `02-story-loop/stories.md` → all completed stories
+   - Read `02-story-loop/tracker.md` → verify all stories are complete
+   - Read `CLAUDE.md` for any project-specific context
+
+2. **Determine output format** from the Research Brief. If not specified, use `AskUserQuestion`:
+   - "What format should the final document be? (markdown/pdf/ppt/html)" with options
+   - Also ask: "Any specific structure, branding, or style requirements?"
+
+3. **Plan document structure:**
+   - Executive summary / abstract
+   - Table of contents
+   - Arrange stories in logical reading order (not necessarily story-number order)
+   - Add transitions between stories for narrative flow
+   - Create introduction and conclusion that frame the overall research
+   - Add appendices if needed (methodology notes, full source list, data tables)
+
+4. **Write the document:**
+
+   **For Markdown (.md):**
+   - Write a single comprehensive markdown file to the project directory
+   - Include all sections, proper heading hierarchy, citations
+
+   **For HTML:**
+   - Write a styled HTML file with clean, professional CSS
+   - Include print-friendly styles for PDF conversion
+   - Responsive layout suitable for reading
+
+   **For PPT/Presentation:**
+   - Write a structured markdown file optimized for presentation
+   - Each major section = 1-3 slides
+   - Key findings as bullet points, not paragraphs
+   - Include speaker notes as HTML comments
+   - Create a companion script or instructions for converting to actual PPT (e.g., using marp, pandoc, or similar)
+
+   **For PDF:**
+   - Write a well-structured markdown or HTML file optimized for PDF conversion
+   - Include instructions for converting to PDF (pandoc, browser print, etc.)
+
+5. **Compile source bibliography:**
+   - Gather all sources from all findings
+   - Deduplicate and format consistently
+   - Add as appendix
+
+6. **Update tracker:**
+   - Record output file path, format, word count
+   - Log completion
+   - `<promise>DOCUMENT COMPLETE</promise>`
+
+---
+
+## Document Structure Template
+
+```markdown
+# {Research Title}
+
+**Prepared by:** {from CLAUDE.md or user context}
+**Date:** {current date}
+**Audience:** {from research brief}
+
+---
+
+## Executive Summary
+{2-3 paragraphs synthesizing the entire research. Key findings, implications, recommendations.}
+
+## Table of Contents
+{Auto-generated from section headers}
+
+---
+
+{Stories arranged in logical order, with transitions}
+
+## Story Section 1: {title}
+{Story content, refined for document context}
+
+## Story Section 2: {title}
+{Story content}
+
+...
+
+---
+
+## Conclusions & Recommendations
+{Cross-cutting insights that emerge from the stories together}
+
+## Appendix A: Methodology
+{Brief description of research approach}
+
+## Appendix B: Sources
+{Consolidated, deduplicated bibliography}
+```
+
+---
+
+## Rules
+
+- This runs ONCE, on-demand. It is not a recurring loop.
+- Read ALL stories before writing — the document must be coherent as a whole.
+- Respect the audience — adjust tone, depth, and jargon accordingly.
+- The document should add value beyond just concatenating stories — add executive summary, transitions, cross-cutting analysis, and recommendations.
+- Cite sources properly. Include a full bibliography.
+- Write to the project root directory, not inside `.ralph-flow/`.
+- If the user wants multiple formats, produce each one.
+
+---
+
+Read `.ralph-flow/03-document-loop/tracker.md` now and begin.

package/src/templates/research/loops/03-document-loop/tracker.md

@@ -0,0 +1,9 @@
+# Document Loop — Tracker
+
+- stage: compile
+- output_format: none
+- output_file: none
+
+---
+
+## Log

package/src/templates/research/ralphflow.yaml

@@ -0,0 +1,80 @@
+name: research
+description: "Discovery → Research → Story → Document pipeline for research projects"
+version: 1
+dir: .ralph-flow
+
+entities:
+  TOPIC:
+    prefix: TOPIC
+    data_file: 00-discovery-loop/topics.md
+  FINDING:
+    prefix: FINDING
+    data_file: 01-research-loop/findings.md
+  STORY:
+    prefix: STORY
+    data_file: 02-story-loop/stories.md
+
+loops:
+  discovery-loop:
+    order: 0
+    name: "Discovery Loop"
+    prompt: 00-discovery-loop/prompt.md
+    tracker: 00-discovery-loop/tracker.md
+    data_files:
+      - 00-discovery-loop/topics.md
+    entities: [TOPIC]
+    stages: [scope, explore, decompose]
+    completion: "ALL TOPICS DISCOVERED"
+    feeds: [research-loop]
+    multi_agent: false
+    cadence: 0
+
+  research-loop:
+    order: 1
+    name: "Research Loop"
+    prompt: 01-research-loop/prompt.md
+    tracker: 01-research-loop/tracker.md
+    data_files:
+      - 01-research-loop/findings.md
+    entities: [TOPIC, FINDING]
+    stages: [investigate, synthesize]
+    completion: "ALL TOPICS RESEARCHED"
+    fed_by: [discovery-loop]
+    feeds: [story-loop]
+    multi_agent:
+      enabled: true
+      max_agents: 4
+      strategy: tracker-lock
+      agent_placeholder: "{{AGENT_NAME}}"
+    lock:
+      file: 01-research-loop/.tracker-lock
+      type: echo
+      stale_seconds: 60
+    cadence: 0
+
+  story-loop:
+    order: 2
+    name: "Story Loop"
+    prompt: 02-story-loop/prompt.md
+    tracker: 02-story-loop/tracker.md
+    data_files:
+      - 02-story-loop/stories.md
+    entities: [STORY]
+    stages: [draft, refine]
+    completion: "ALL STORIES WRITTEN"
+    fed_by: [research-loop]
+    feeds: [document-loop]
+    multi_agent: false
+    cadence: 0
+
+  document-loop:
+    order: 3
+    name: "Document Loop"
+    prompt: 03-document-loop/prompt.md
+    tracker: 03-document-loop/tracker.md
+    entities: [STORY]
+    stages: [compile]
+    completion: "DOCUMENT COMPLETE"
+    fed_by: [story-loop]
+    multi_agent: false
+    cadence: 0