ralphflow 0.5.1 → 0.5.2

package/dist/ralphflow.js

@@ -231,6 +231,48 @@ function checkTrackerAllChecked(flowDir, loop) {
   const unchecked = (content.match(/- \[ \]/g) || []).length;
   return checked > 0 && unchecked === 0;
 }
+function hasNewItemsInDataFile(flowDir, loop, config) {
+  if (!loop.entities || loop.entities.length === 0) return false;
+  const entityName = loop.entities[0];
+  const entity = config.entities?.[entityName];
+  if (!entity) return false;
+  const dataFilePath = join2(flowDir, entity.data_file);
+  if (!existsSync2(dataFilePath)) return false;
+  const trackerPath = join2(flowDir, loop.tracker);
+  if (!existsSync2(trackerPath)) return false;
+  const dataContent = readFileSync(dataFilePath, "utf-8");
+  const trackerContent = readFileSync(trackerPath, "utf-8");
+  const prefix = entity.prefix;
+  const itemRegex = new RegExp(`^## (${prefix}-\\d+):`, "gm");
+  const dataFileIds = [...dataContent.matchAll(itemRegex)].map((m) => m[1]);
+  if (dataFileIds.length === 0) return false;
+  const trackerIdRegex = new RegExp(`\\[[ x]\\]\\s*(${prefix}-\\d+)`, "gi");
+  const trackerIds = [...trackerContent.matchAll(trackerIdRegex)].map((m) => m[1]);
+  return dataFileIds.some((id) => !trackerIds.includes(id));
+}
+function stripStaleCompletion(flowDir, loop, config) {
+  if (!hasNewItemsInDataFile(flowDir, loop, config)) return false;
+  const trackerPath = join2(flowDir, loop.tracker);
+  if (!existsSync2(trackerPath)) return false;
+  let content = readFileSync(trackerPath, "utf-8");
+  const hadCompletion = content.includes(`<promise>${loop.completion}</promise>`) || content.includes(loop.completion);
+  if (!hadCompletion) return false;
+  content = content.replace(new RegExp(`<promise>${loop.completion}</promise>`, "g"), "");
+  content = content.replace(new RegExp(loop.completion, "g"), "");
+  writeFileSync(trackerPath, content);
+  console.log(chalk3.cyan(`  \u21BB New items detected in data file \u2014 cleared stale completion for ${loop.name}`));
+  return true;
+}
+function stripCompletionString(flowDir, loop) {
+  const trackerPath = join2(flowDir, loop.tracker);
+  if (!existsSync2(trackerPath)) return;
+  let content = readFileSync(trackerPath, "utf-8");
+  const had = content.includes(`<promise>${loop.completion}</promise>`) || content.includes(loop.completion);
+  if (!had) return;
+  content = content.replace(new RegExp(`<promise>${loop.completion}</promise>`, "g"), "");
+  content = content.replace(new RegExp(loop.completion, "g"), "");
+  writeFileSync(trackerPath, content);
+}
 async function runLoop(loopName, options) {
   const flowDir = resolveFlowDir(options.cwd, options.flow);
   const config = loadConfig(flowDir);
@@ -264,22 +306,25 @@ async function runLoop(loopName, options) {
     cleanup();
     process.exit(143);
   });
+  stripCompletionString(flowDir, loop);
   try {
-    await iterationLoop(key, loop, flowDir, options, agentName);
+    await iterationLoop(key, loop, flowDir, options, agentName, void 0, void 0, true, config);
   } finally {
     cleanup();
   }
 }
-async function iterationLoop(configKey, loop, flowDir, options, agentName, db, flowName, forceFirstIteration) {
+async function iterationLoop(configKey, loop, flowDir, options, agentName, db, flowName, forceFirstIteration, config) {
   const loopKey = loop.name;
   const appName = basename(flowDir);
+  if (config) stripStaleCompletion(flowDir, loop, config);
   for (let i = 1; i <= options.maxIterations; i++) {
     if (!(forceFirstIteration && i === 1)) {
       if (db && flowName && isLoopComplete(db, flowName, loopKey)) {
         console.log(chalk3.green(`  \u2713 ${loop.name} \u2014 already complete`));
         return;
       }
-      if (checkTrackerForCompletion(flowDir, loop) || checkTrackerMetadataCompletion(flowDir, loop) || checkTrackerAllChecked(flowDir, loop)) {
+      const newItemsExist = config ? hasNewItemsInDataFile(flowDir, loop, config) : false;
+      if (!newItemsExist && (checkTrackerForCompletion(flowDir, loop) || checkTrackerMetadataCompletion(flowDir, loop) || checkTrackerAllChecked(flowDir, loop))) {
         if (db && flowName) markLoopComplete(db, flowName, loopKey);
         console.log(chalk3.green(`  \u2713 ${loop.name} \u2014 complete`));
         return;
@@ -301,7 +346,8 @@ async function iterationLoop(configKey, loop, flowDir, options, agentName, db, f
       skipPermissions: loop.skip_permissions
     });
     if (db && flowName) incrementIteration(db, flowName, loopKey);
-    if (checkTrackerForCompletion(flowDir, loop) || checkTrackerMetadataCompletion(flowDir, loop) || checkTrackerAllChecked(flowDir, loop)) {
+    const newItemsAfter = config ? hasNewItemsInDataFile(flowDir, loop, config) : false;
+    if (!newItemsAfter && (checkTrackerForCompletion(flowDir, loop) || checkTrackerMetadataCompletion(flowDir, loop) || checkTrackerAllChecked(flowDir, loop))) {
       if (db && flowName) markLoopComplete(db, flowName, loopKey);
       console.log();
       console.log(chalk3.green(`  Loop complete: ${loop.completion}`));
@@ -346,7 +392,8 @@ async function runE2E(options) {
           console.log(chalk3.green(`  \u2713 ${loop.name} \u2014 complete, skipping`));
           continue;
         }
-        if (checkTrackerForCompletion(flowDir, loop) || checkTrackerMetadataCompletion(flowDir, loop) || checkTrackerAllChecked(flowDir, loop)) {
+        const loopHasNewItems = hasNewItemsInDataFile(flowDir, loop, config);
+        if (!loopHasNewItems && (checkTrackerForCompletion(flowDir, loop) || checkTrackerMetadataCompletion(flowDir, loop) || checkTrackerAllChecked(flowDir, loop))) {
           markLoopComplete(db, flowName, loopKey);
           console.log(chalk3.green(`  \u2713 ${loop.name} \u2014 complete, skipping`));
           continue;
@@ -362,7 +409,7 @@ async function runE2E(options) {
         agentName = acquireAgentId(agentDir, loop.multi_agent.max_agents);
       }
       try {
-        await iterationLoop(key, loop, flowDir, options, agentName, db, flowName, isFirstLoop);
+        await iterationLoop(key, loop, flowDir, options, agentName, db, flowName, isFirstLoop, config);
       } finally {
         if (agentDir && agentName) releaseAgentId(agentDir, agentName);
       }
@@ -595,6 +642,39 @@ function buildPromptLoopConfig(loopDef) {
     stageConfigs
   };
 }
+function generateVisualProtocol() {
+  let s = "";
+  s += `## Visual Communication Protocol
+
+`;
+  s += `When communicating scope, structure, relationships, or status, render **ASCII diagrams** using Unicode box-drawing characters. These help the user see the full picture at the terminal without scrolling through prose.
+
+`;
+  s += `**Character set:** \`\u250C \u2500 \u2510 \u2502 \u2514 \u2518 \u251C \u2524 \u252C \u2534 \u253C \u2550 \u25CF \u25CB \u25BC \u25B6\`
+
+`;
+  s += `**Diagram types to use:**
+
+`;
+  s += `- **Scope/Architecture Map** \u2014 components and their relationships in a bordered grid
+`;
+  s += `- **Decomposition Tree** \u2014 hierarchical breakdown with \`\u251C\u2500\u2500\` and \`\u2514\u2500\u2500\` branches
+`;
+  s += `- **Data Flow** \u2014 arrows (\`\u2500\u2500\u2192\`) showing how information moves between components
+`;
+  s += `- **Comparison Table** \u2014 bordered table for trade-offs and design options
+`;
+  s += `- **Status Summary** \u2014 bordered box with completion indicators (\`\u2713\` done, \`\u25CC\` pending)
+
+`;
+  s += `**Rules:** Keep diagrams under 20 lines and under 70 characters wide. Populate with real data from current context. Render inside fenced code blocks. Use diagrams to supplement, not replace, prose.
+
+`;
+  s += `---
+
+`;
+  return s;
+}
 function generatePromptFromConfig(loop, loopIndex, allLoops) {
   const loopName = loop.name || "Loop " + (loopIndex + 1);
   const inputFiles = (loop.inputFiles || "").trim();
@@ -641,6 +721,7 @@ function generatePromptFromConfig(loop, loopIndex, allLoops) {
   p += `---
 
 `;
+  p += generateVisualProtocol();
   if (loop.multi_agent) {
     p += `## Tracker Lock Protocol
 
@@ -800,14 +881,20 @@ function generatePromptFromConfig(loop, loopIndex, allLoops) {
   p += `---
 
 `;
-  if (loop.multi_agent) {
-    p += `## First-Run Handling
+  {
+    const scanFile = primaryInputFile || "input.md";
+    p += `## First-Run / New ${entityTitle} Detection
 
 `;
-    const scanFile = primaryInputFile || "input.md";
-    p += `If ${entityTitle}s Queue in tracker is empty: read \`${scanFile}\`, scan \`## ${entityKey}:\` headers, populate queue with \`{agent: -, status: pending|blocked}\` metadata (compute from Dependencies), then start.
+    if (loop.multi_agent) {
+      p += `If ${entityTitle}s Queue in tracker is empty OR all entries are \`[x]\`: read \`${scanFile}\`, scan \`## ${entityKey}:\` headers + \`**Depends on:**\` tags. For any ${entityLower} NOT already in the queue, add as \`- [ ] ${entityKey}: {title}\` with \`{agent: -, status: pending|blocked}\` metadata (compute from Dependencies), then start.
 
 `;
+    } else {
+      p += `If ${entityTitle}s Queue in tracker is empty OR all entries are \`[x]\`: read \`${scanFile}\`, scan \`## ${entityKey}:\` headers + \`**Depends on:**\` tags. For any ${entityLower} NOT already in the queue, add as \`- [ ] ${entityKey}: {title}\` and update Dependencies. If new ${entityPlural} were added, proceed to process them.
+
+`;
+    }
     p += `---
 
 `;
@@ -857,6 +944,14 @@ function generatePromptFromConfig(loop, loopIndex, allLoops) {
 `;
       }
     }
+    if (i === 0) {
+      p += `${step++}. **Render a Scope Diagram** \u2014 output an ASCII architecture/scope map showing the areas this ${entityLower} touches, dependencies, and what needs to change
+`;
+    }
+    if (i === stageCount - 1 && stageCount > 1) {
+      p += `${step++}. **Render a Completion Summary** \u2014 output an ASCII status diagram showing what was built/changed, verification results, and how this ${entityLower} fits in overall progress
+`;
+    }
     if (loop.multi_agent) {
       p += `${step++}. Acquire lock \u2192 update tracker: stage, \`last_heartbeat\`, log entry \u2192 release lock
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralphflow",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Multi-agent AI workflow orchestration framework for Claude Code. Define pipelines as loops, coordinate parallel agents, and ship structured work.",
   "type": "module",
   "bin": {

package/src/dashboard/ui/prompt-builder.js

@@ -67,6 +67,26 @@ export function renderPromptConfigForm(loopIdx, loop, allLoops) {
   return html;
 }
 
+// -----------------------------------------------------------------------
+// Visual Communication Protocol for generated prompts
+// -----------------------------------------------------------------------
+
+function generateVisualProtocol() {
+  let s = '';
+  s += `## Visual Communication Protocol\n\n`;
+  s += `When communicating scope, structure, relationships, or status, render **ASCII diagrams** using Unicode box-drawing characters. These help the user see the full picture at the terminal without scrolling through prose.\n\n`;
+  s += `**Character set:** \`┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶\`\n\n`;
+  s += `**Diagram types to use:**\n\n`;
+  s += `- **Scope/Architecture Map** — components and their relationships in a bordered grid\n`;
+  s += `- **Decomposition Tree** — hierarchical breakdown with \`├──\` and \`└──\` branches\n`;
+  s += `- **Data Flow** — arrows (\`──→\`) showing how information moves between components\n`;
+  s += `- **Comparison Table** — bordered table for trade-offs and design options\n`;
+  s += `- **Status Summary** — bordered box with completion indicators (\`✓\` done, \`◌\` pending)\n\n`;
+  s += `**Rules:** Keep diagrams under 20 lines and under 70 characters wide. Populate with real data from current context. Render inside fenced code blocks. Use diagrams to supplement, not replace, prose.\n\n`;
+  s += `---\n\n`;
+  return s;
+}
+
 // -----------------------------------------------------------------------
 // Prompt generation engine
 // -----------------------------------------------------------------------
@@ -114,6 +134,9 @@ export function generatePromptFromConfig(loop, loopIndex, allLoops) {
   p += `**Pipeline:** \`${pipelineIn} → YOU → ${pipelineOut}\`\n\n`;
   p += `---\n\n`;
 
+  // ── VISUAL COMMUNICATION PROTOCOL ──
+  p += generateVisualProtocol();
+
   // ── MULTI-AGENT SECTIONS (conditional) ──
   if (loop.multi_agent) {
     // Tracker Lock Protocol
@@ -199,11 +222,15 @@ export function generatePromptFromConfig(loop, loopIndex, allLoops) {
   p += `After completing ANY stage, exit: \`kill -INT $PPID\`\n\n`;
   p += `---\n\n`;
 
-  // ── FIRST-RUN HANDLING ──
-  if (loop.multi_agent) {
-    p += `## First-Run Handling\n\n`;
+  // ── FIRST-RUN / NEW ITEM DETECTION ──
+  {
     const scanFile = primaryInputFile || 'input.md';
-    p += `If ${entityTitle}s Queue in tracker is empty: read \`${scanFile}\`, scan \`## ${entityKey}:\` headers, populate queue with \`{agent: -, status: pending|blocked}\` metadata (compute from Dependencies), then start.\n\n`;
+    p += `## First-Run / New ${entityTitle} Detection\n\n`;
+    if (loop.multi_agent) {
+      p += `If ${entityTitle}s Queue in tracker is empty OR all entries are \`[x]\`: read \`${scanFile}\`, scan \`## ${entityKey}:\` headers + \`**Depends on:**\` tags. For any ${entityLower} NOT already in the queue, add as \`- [ ] ${entityKey}: {title}\` with \`{agent: -, status: pending|blocked}\` metadata (compute from Dependencies), then start.\n\n`;
+    } else {
+      p += `If ${entityTitle}s Queue in tracker is empty OR all entries are \`[x]\`: read \`${scanFile}\`, scan \`## ${entityKey}:\` headers + \`**Depends on:**\` tags. For any ${entityLower} NOT already in the queue, add as \`- [ ] ${entityKey}: {title}\` and update Dependencies. If new ${entityPlural} were added, proceed to process them.\n\n`;
+    }
     p += `---\n\n`;
   }
 
@@ -248,6 +275,14 @@ export function generatePromptFromConfig(loop, loopIndex, allLoops) {
       }
     }
 
+    // Visual diagram trigger
+    if (i === 0) {
+      p += `${step++}. **Render a Scope Diagram** — output an ASCII architecture/scope map showing the areas this ${entityLower} touches, dependencies, and what needs to change\n`;
+    }
+    if (i === stageCount - 1 && stageCount > 1) {
+      p += `${step++}. **Render a Completion Summary** — output an ASCII status diagram showing what was built/changed, verification results, and how this ${entityLower} fits in overall progress\n`;
+    }
+
     // Tracker update
     if (loop.multi_agent) {
       p += `${step++}. Acquire lock → update tracker: stage, \`last_heartbeat\`, log entry → release lock\n`;

package/src/dashboard/ui/styles.css

@@ -1474,6 +1474,27 @@ body {
   font-weight: 600;
   margin-bottom: 8px;
 }
+.wizard-description-ref {
+  border-left: 3px solid var(--accent);
+  padding: 8px 12px;
+  margin-bottom: 16px;
+  background: rgba(99, 102, 241, 0.06);
+  border-radius: 0 6px 6px 0;
+}
+.wizard-description-ref-label {
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  color: var(--accent);
+  font-weight: 600;
+}
+.wizard-description-ref p {
+  margin: 4px 0 0;
+  font-size: 13px;
+  color: var(--text-secondary);
+  line-height: 1.5;
+  font-style: italic;
+}
 .wizard-hint {
   font-size: 13px;
   color: var(--text-dim);

package/src/dashboard/ui/templates.js

@@ -248,6 +248,9 @@ function renderTemplateWizard() {
   } else if (step === 1) {
     // Step 2: Define pipeline steps
     html += '<div class="wizard-step-card">';
+    if (wd.description) {
+      html += `<div class="wizard-description-ref"><span class="wizard-description-ref-label">Your description</span><p>${esc(wd.description)}</p></div>`;
+    }
     html += '<h3 class="wizard-question">Define your pipeline steps</h3>';
     html += '<p class="wizard-hint">Each step becomes a loop. For each, give it a name and optionally list its stages (comma-separated). Stages define what the AI agent does in each iteration cycle.</p>';
     html += '<div class="wizard-loops-list" id="wizardLoopsList">';

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

@@ -12,13 +12,39 @@ Read `.ralph-flow/{{APP_NAME}}/00-story-loop/tracker.md` FIRST to determine wher
 
 ---
 
+## Visual Communication Protocol
+
+When communicating scope, structure, relationships, or status, render **ASCII diagrams** using Unicode box-drawing characters. These help the user see the full picture at the terminal without scrolling through prose.
+
+**Character set:** `┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶`
+
+**Diagram types to use:**
+
+- **Scope/Architecture Map** — components and their relationships in a bordered grid
+- **Decomposition Tree** — hierarchical breakdown with `├──` and `└──` branches
+- **Data Flow** — arrows (`──→`) showing how information moves between components
+- **Comparison Table** — bordered table for trade-offs and design options
+- **Status Summary** — bordered box with completion indicators (`✓` done, `◌` pending)
+
+**Rules:** Keep diagrams under 20 lines and under 70 characters wide. Populate with real data from current context. Render inside fenced code blocks. Use diagrams to supplement, not replace, prose.
+
+---
+
 ## State Machine (3 stages per story)
 
 **FIRST — Check completion.** Read the tracker. If the Stories Queue has entries
-AND every entry is `[x]` (no pending stories), do NOT write the completion promise yet.
-Instead, go to **"No Stories? Collect Them"** to ask the user for new stories.
+AND every entry is `[x]` (no pending stories):
+1. **Re-scan `stories.md`** — read all `## STORY-{N}:` headers and compare
+   against the Stories Queue in the tracker.
+2. **New stories found** (in `stories.md` but not in the queue) → add them as
+   `- [ ] STORY-{N}: {title}` to the Stories Queue, update the Dependency Graph
+   from their `**Depends on:**` tags, then proceed to process the lowest-numbered
+   ready story via the normal state machine.
+3. **No new stories** → go to **"No Stories? Collect Them"** to ask the user.
+
 Only write `<promise>ALL STORIES PROCESSED</promise>` when the user explicitly
-confirms they have no more stories to add.
+confirms they have no more stories to add AND `stories.md` has no stories
+missing from the tracker queue.
 
 Pick the lowest-numbered `ready` story. NEVER process a `blocked` story.
 
@@ -28,7 +54,8 @@ Pick the lowest-numbered `ready` story. NEVER process a `blocked` story.
 
 **Triggers when:**
 - `stories.md` has no stories at all (first run, empty queue with no entries), OR
-- All stories in the queue are completed (`[x]`) and there are no `pending` stories left
+- All stories in the queue are completed (`[x]`), no `pending` stories remain, AND
+  `stories.md` has been re-scanned and contains no stories missing from the queue
 
 **Flow:**
 1. Tell the user: *"No pending stories. Tell me what you want to build — describe features, problems, or goals in your own words."*
@@ -45,9 +72,13 @@ CLARIFY   → Ask user up to 20 questions (5 at a time) → stage: decompose
 DECOMPOSE → Break into TASK-GROUP(s) + tasks, append to tasks.md, mark done → kill
 ```
 
-## First-Run Handling
+## First-Run / New Story Detection
 
-If Stories Queue in tracker is empty: read `stories.md`, scan `## STORY-{N}:` headers + `**Depends on:**` tags, populate queue as `- [ ] STORY-{N}: {title}`, build Dependency Graph.
+If Stories Queue in tracker is empty OR all entries are `[x]`: read `stories.md`,
+scan `## STORY-{N}:` headers + `**Depends on:**` tags. For any story NOT already
+in the queue, add as `- [ ] STORY-{N}: {title}` and build/update the Dependency Graph.
+If new stories were added, proceed to process them. If the queue is still empty
+after scanning, go to **"No Stories? Collect Them"**.
 
 ---
 
@@ -56,23 +87,32 @@ If Stories Queue in tracker is empty: read `stories.md`, scan `## STORY-{N}:` he
 1. Read tracker → pick lowest-numbered `ready` story
 2. Read the story from `stories.md` (+ any referenced screenshots)
 3. **Explore the codebase** — read `CLAUDE.md` for project context, then **20+ key files** across the areas this story touches. Understand current behavior, patterns, conventions, and what needs to change.
-4. Update tracker: `active_story: STORY-{N}`, `stage: clarify`, log entry
+4. **Render a Scope Map** — output an ASCII architecture/scope diagram showing:
+   - The areas of the codebase this story touches (components, modules, services)
+   - Dependencies and data flow between affected areas
+   - What exists today (`●`) vs. what needs to change (`○`)
+5. Update tracker: `active_story: STORY-{N}`, `stage: clarify`, log entry
 
 ## STAGE 2: CLARIFY
 
 1. Formulate questions about scope, priorities, edge cases, design choices
-2. **Ask up to 20 questions, 5 at a time** via `AskUserQuestion` (with options where possible):
+2. **Present understanding diagram first** — render an ASCII scope/architecture diagram showing your understanding of the story's scope. This gives the user a visual anchor to correct misconceptions before answering questions.
+3. **Ask up to 20 questions, 5 at a time** via `AskUserQuestion` — structure each round visually:
+   - For multi-option decisions: numbered list with one-line descriptions
+   - For design trade-offs: include a **comparison table** showing trade-offs (e.g., approach vs. complexity vs. speed)
+   - For scope boundaries: use an in/out list format
    - Round 1: Scope, intent, must-haves
    - Round 2+: Design choices, edge cases, preferences — based on prior answers
    - Stop early if clear enough
-3. Save Q&A summary in tracker log
-4. Update tracker: `stage: decompose`, log entry with key decisions
+4. Save Q&A summary in tracker log
+5. Update tracker: `stage: decompose`, log entry with key decisions
 
 ## STAGE 3: DECOMPOSE
 
 1. Find next TASK-GROUP and TASK numbers (check existing in `01-tasks-loop/tasks.md`)
 2. **Read already-written tasks** — if sibling tasks exist, read them to align scope boundaries
-3. Break story into TASK-GROUP(s) — one per distinct functional area, 2-6 tasks each
+3. **Render a Decomposition Tree** — output an ASCII tree showing the planned TASK-GROUP(s) and their tasks, with dependency arrows between tasks that depend on each other
+4. Break story into TASK-GROUP(s) — one per distinct functional area, 2-6 tasks each
 4. For each task, ask yourself: *What does success look like? How would someone confirm? What could silently break?*
 5. **Sanity-check:** Do NOT embed specific file paths in tasks — describe *what* changes, not *where*. The tasks loop will explore the codebase itself.
 6. Append to `01-tasks-loop/tasks.md` (format below)

package/src/templates/code-implementation/loops/01-tasks-loop/prompt.md

@@ -14,6 +14,24 @@ Read `.ralph-flow/{{APP_NAME}}/01-tasks-loop/tracker.md` FIRST to determine wher
 
 ---
 
+## Visual Communication Protocol
+
+When communicating scope, structure, relationships, or status, render **ASCII diagrams** using Unicode box-drawing characters. These help the user see the full picture at the terminal without scrolling through prose.
+
+**Character set:** `┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶`
+
+**Diagram types to use:**
+
+- **Scope/Architecture Map** — components and their relationships in a bordered grid
+- **Decomposition Tree** — hierarchical breakdown with `├──` and `└──` branches
+- **Data Flow** — arrows (`──→`) showing how information moves between components
+- **Comparison Table** — bordered table for trade-offs and design options
+- **Status Summary** — bordered box with completion indicators (`✓` done, `◌` pending)
+
+**Rules:** Keep diagrams under 20 lines and under 70 characters wide. Populate with real data from current context. Render inside fenced code blocks. Use diagrams to supplement, not replace, prose.
+
+---
+
 ## Tracker Lock Protocol
 
 Before ANY write to `tracker.md`, you MUST acquire the lock:
@@ -112,7 +130,11 @@ After completing ANY stage, exit: `kill -INT $PPID`
 3. If sibling tasks are done, read their commits/diffs to align
 4. Read `CLAUDE.md` for project context
 5. Explore codebase — **40+ files:** affected areas, dependencies, patterns
-6. Acquire lock → update tracker: your Agent Status row `active_task: TASK-{N}`, `stage: execute`, `last_heartbeat`, log entry → release lock
+6. **Render an Implementation Map** — output an ASCII diagram showing:
+   - Files/modules to create or modify (grouped by area)
+   - Data flow or control flow for the change
+   - How this task's changes connect to sibling tasks in the group
+7. Acquire lock → update tracker: your Agent Status row `active_task: TASK-{N}`, `stage: execute`, `last_heartbeat`, log entry → release lock
 7. Implement changes. Match existing patterns per `CLAUDE.md`.
 8. Deploy/rebuild (commands in `CLAUDE.md`)
 9. **Quick verify:** check container logs for errors, hit health endpoints, confirm no crashes
@@ -126,7 +148,11 @@ After completing ANY stage, exit: `kill -INT $PPID`
 3. **Functional verify:** test the actual change — hit new/modified endpoints, check DB state, verify expected behavior through CLI/curl/API calls
 4. **FAIL** → fix the issue, re-deploy, re-verify. If stuck, log details in tracker and move on
 5. **PASS** → continue to documentation
-6. Update `CLAUDE.md` (≤150 words net). Commit separately.
+6. **Render a Completion Summary** — output an ASCII status diagram showing:
+   - What was built/changed (files, endpoints, components)
+   - Verification results (pass/fail per acceptance criterion)
+   - How this task fits in the TASK-GROUP progress
+7. Update `CLAUDE.md` (≤150 words net). Commit separately.
 7. Create/update `.claude/skills/` if this task produced reusable knowledge. Skip if nothing reusable.
 8. **Mark done & unblock dependents:**
    - Acquire lock

package/src/templates/code-implementation/loops/02-delivery-loop/prompt.md

@@ -12,6 +12,24 @@ Read `.ralph-flow/{{APP_NAME}}/02-delivery-loop/tracker.md` FIRST to determine w
 
 ---
 
+## Visual Communication Protocol
+
+When communicating scope, structure, relationships, or status, render **ASCII diagrams** using Unicode box-drawing characters. These help the user see the full picture at the terminal without scrolling through prose.
+
+**Character set:** `┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶`
+
+**Diagram types to use:**
+
+- **Scope/Architecture Map** — components and their relationships in a bordered grid
+- **Decomposition Tree** — hierarchical breakdown with `├──` and `└──` branches
+- **Data Flow** — arrows (`──→`) showing how information moves between components
+- **Comparison Table** — bordered table for trade-offs and design options
+- **Status Summary** — bordered box with completion indicators (`✓` done, `◌` pending)
+
+**Rules:** Keep diagrams under 20 lines and under 70 characters wide. Populate with real data from current context. Render inside fenced code blocks. Use diagrams to supplement, not replace, prose.
+
+---
+
 ## First-Run Handling
 
 If Delivery Queue is empty, build it by scanning the task tracker:
@@ -47,18 +65,23 @@ Phase 1 → Phase 2 flows continuously in one iteration (no kill between them).
 2. Read phase plans from `01-tasks-loop/phases/`
 3. Read `CLAUDE.md` for project context
 4. **Review independently:** Walk through each task's verification steps. Note anything wrong, broken, or inconsistent. Build a presentation narrative.
-5. For cancelled tasks/groups: note what was superseded and why
+5. **Build a Delivery Diagram** — prepare an ASCII diagram for presentation showing:
+   - All task-groups in this story with completion status
+   - Per-task status (`✓` done, `✗` cancelled, `!` issues found)
+   - Data flow or architecture of what was built
+6. For cancelled tasks/groups: note what was superseded and why
 6. Record review notes in tracker log
 7. Update tracker: `active_story: STORY-{N}`, `stage: present-and-feedback`
 8. **Flow directly into Phase 2** (no stop)
 
 ## PHASE 2: PRESENT-AND-FEEDBACK (combined, one AskUserQuestion call)
 
-1. **Present structured walkthrough** of ALL task-groups in the story:
-   - Per task-group: what was built (plain language), how to verify it
+1. **Present structured walkthrough with diagrams:**
+   - Open with an ASCII **architecture/scope diagram** showing what was built (components, data flow, integrations)
+   - Per task-group: what was built (plain language), completion status, how to verify it
    - Any issues the agent found during Phase 1 review
    - Cancelled tasks/groups with brief explanation of what was superseded
-2. **Ask 3-4 questions in ONE `AskUserQuestion` call:**
+2. **Ask 3-4 questions in ONE `AskUserQuestion` call** — use visual grouping:
    - **Q1: Working correctly?** Does everything work as expected? Note any specific issues.
    - **Q2: Behavior or appearance?** Anything to change about look, feel, or behavior?
    - **Q3: Missing or new ideas?** Anything missing, or new ideas sparked by what you see?

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

@@ -12,13 +12,37 @@ Read `.ralph-flow/{{APP_NAME}}/00-discovery-loop/tracker.md` FIRST to determine
 
 ---
 
+## Visual Communication Protocol
+
+When communicating scope, structure, relationships, or status, render **ASCII diagrams** using Unicode box-drawing characters. These help the user see the full picture at the terminal without scrolling through prose.
+
+**Character set:** `┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶`
+
+**Diagram types to use:**
+
+- **Scope/Architecture Map** — components and their relationships in a bordered grid
+- **Decomposition Tree** — hierarchical breakdown with `├──` and `└──` branches
+- **Data Flow** — arrows (`──→`) showing how information moves between components
+- **Comparison Table** — bordered table for trade-offs and design options
+- **Status Summary** — bordered box with completion indicators (`✓` done, `◌` pending)
+
+**Rules:** Keep diagrams under 20 lines and under 70 characters wide. Populate with real data from current context. Render inside fenced code blocks. Use diagrams to supplement, not replace, prose.
+
+---
+
 ## No Brief? Collect One
 
+If the tracker queue has entries and all are `[x]`:
+1. **Re-scan `topics.md`** — read all `## TOPIC-{N}:` headers and compare against
+   the Topics Queue in the tracker. If new topics found, add them as
+   `- [ ] TOPIC-{N}: {title}` with appropriate metadata and proceed to process them.
+2. **No new topics** → proceed to "No Brief? Collect One" below.
+
 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)?
+4. **Confirm scope with a visual summary** — render an ASCII scope map showing the research boundaries, then 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
 
 ---
@@ -31,9 +55,14 @@ EXPLORE  → Search broadly for sub-domains, angles, key questions → stage: de
 DECOMPOSE → Break into TOPIC entries, write to topics.md, seed research tracker → kill
 ```
 
-## First-Run Handling
+## First-Run / New Topic Detection
 
-If Topics Queue in tracker is empty and Research Brief exists: proceed to SCOPE. If Topics Queue is populated, check for remaining unprocessed items.
+If Topics Queue in tracker is empty OR all entries are `[x]`: read `topics.md`,
+scan `## TOPIC-{N}:` headers + `**Depends on:**` tags. For any topic NOT already
+in the queue, add as `- [ ] TOPIC-{N}: {title}` with appropriate metadata, and
+update Dependencies. If new topics were added, proceed to process them.
+If the queue remains empty and Research Brief exists: proceed to SCOPE.
+If Topics Queue is populated with unchecked items, check for remaining unprocessed items.
 
 ---
 
@@ -46,7 +75,8 @@ If Topics Queue in tracker is empty and Research Brief exists: proceed to 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
+4. **Render a Scope Map** — output an ASCII diagram showing research domain boundaries (in-scope vs. out), key sub-domains identified, audience and depth indicators
+5. Update tracker: `stage: explore`, log entry with scope decisions
 
 ## STAGE 2: EXPLORE
 
@@ -61,7 +91,8 @@ If Topics Queue in tracker is empty and Research Brief exists: proceed to SCOPE.
 ## 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:
+2. **Render a Topic Tree** — output an ASCII decomposition tree showing all planned topics with priority markers (H/M/L), dependency arrows between topics, and estimated depth indicators (surface/moderate/deep)
+3. 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

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

@@ -14,6 +14,24 @@ Read `.ralph-flow/{{APP_NAME}}/01-research-loop/tracker.md` FIRST to determine w
 
 ---
 
+## Visual Communication Protocol
+
+When communicating scope, structure, relationships, or status, render **ASCII diagrams** using Unicode box-drawing characters. These help the user see the full picture at the terminal without scrolling through prose.
+
+**Character set:** `┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶`
+
+**Diagram types to use:**
+
+- **Scope/Architecture Map** — components and their relationships in a bordered grid
+- **Decomposition Tree** — hierarchical breakdown with `├──` and `└──` branches
+- **Data Flow** — arrows (`──→`) showing how information moves between components
+- **Comparison Table** — bordered table for trade-offs and design options
+- **Status Summary** — bordered box with completion indicators (`✓` done, `◌` pending)
+
+**Rules:** Keep diagrams under 20 lines and under 70 characters wide. Populate with real data from current context. Render inside fenced code blocks. Use diagrams to supplement, not replace, prose.
+
+---
+
 ## Tracker Lock Protocol
 
 Before ANY write to `tracker.md`, you MUST acquire the lock:
@@ -117,7 +135,8 @@ After completing ANY stage, exit: `kill -INT $PPID`
    - 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
+7. **Render an Evidence Map** — output an ASCII diagram showing key findings organized by sub-theme, source quality indicators, consensus vs. disagreement areas, and gaps that need attention
+8. Acquire lock → update tracker: `stage: synthesize`, `last_heartbeat`, log entry → release lock
 8. Exit: `kill -INT $PPID`
 
 ## STAGE 2: SYNTHESIZE
@@ -128,7 +147,8 @@ After completing ANY stage, exit: `kill -INT $PPID`
    - 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:
+3. **Render a Findings Summary** — output an ASCII status diagram showing key claims with confidence levels (H/M/L), how this topic connects to sibling topics, and gaps flagged for follow-up
+4. 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`

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

@@ -12,6 +12,24 @@ Read `.ralph-flow/{{APP_NAME}}/02-story-loop/tracker.md` FIRST to determine wher
 
 ---
 
+## Visual Communication Protocol
+
+When communicating scope, structure, relationships, or status, render **ASCII diagrams** using Unicode box-drawing characters. These help the user see the full picture at the terminal without scrolling through prose.
+
+**Character set:** `┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶`
+
+**Diagram types to use:**
+
+- **Scope/Architecture Map** — components and their relationships in a bordered grid
+- **Decomposition Tree** — hierarchical breakdown with `├──` and `└──` branches
+- **Data Flow** — arrows (`──→`) showing how information moves between components
+- **Comparison Table** — bordered table for trade-offs and design options
+- **Status Summary** — bordered box with completion indicators (`✓` done, `◌` pending)
+
+**Rules:** Keep diagrams under 20 lines and under 70 characters wide. Populate with real data from current context. Render inside fenced code blocks. Use diagrams to supplement, not replace, prose.
+
+---
+
 ## No Findings? Wait
 
 If `findings.md` has no unprocessed findings and the tracker queue is empty/all done:
@@ -47,7 +65,8 @@ If Stories Queue in tracker is empty:
 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:**
+4. **Render a Narrative Map** — output an ASCII diagram showing source findings and how they connect to this story's theme, the narrative arc (hook → evidence → implications), and how this story relates to other completed/planned stories
+5. **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

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

@@ -12,6 +12,24 @@ Read `.ralph-flow/{{APP_NAME}}/03-document-loop/tracker.md` FIRST to determine w
 
 ---
 
+## Visual Communication Protocol
+
+When communicating scope, structure, relationships, or status, render **ASCII diagrams** using Unicode box-drawing characters. These help the user see the full picture at the terminal without scrolling through prose.
+
+**Character set:** `┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶`
+
+**Diagram types to use:**
+
+- **Scope/Architecture Map** — components and their relationships in a bordered grid
+- **Decomposition Tree** — hierarchical breakdown with `├──` and `└──` branches
+- **Data Flow** — arrows (`──→`) showing how information moves between components
+- **Comparison Table** — bordered table for trade-offs and design options
+- **Status Summary** — bordered box with completion indicators (`✓` done, `◌` pending)
+
+**Rules:** Keep diagrams under 20 lines and under 70 characters wide. Populate with real data from current context. Render inside fenced code blocks. Use diagrams to supplement, not replace, prose.
+
+---
+
 ## STAGE 1: COMPILE
 
 1. **Read context:**
@@ -24,7 +42,8 @@ Read `.ralph-flow/{{APP_NAME}}/03-document-loop/tracker.md` FIRST to determine w
    - "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:**
+3. **Render a Document Blueprint** — output an ASCII diagram showing document sections in reading order with estimated word counts, story-to-section mapping, and appendix structure
+4. **Plan document structure:**
    - Executive summary / abstract
    - Table of contents
    - Arrange stories in logical reading order (not necessarily story-number order)