ralphflow 0.1.0 → 0.2.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

@@ -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");
@@ -395,7 +402,7 @@ 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("-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),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralphflow",
-  "version": "0.1.0",
+  "version": "0.2.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