twin-cli 0.2.0 → 0.3.1

package/README.md

@@ -2,30 +2,32 @@
 
 Old TDD meant write the tests first. New TDD means write the twin first.
 
-A `.twin` file is your decision-making source code. Your taste. Your biases. Your heuristics. Drop it into any project and your AI tools make decisions the way you would.
-
-The twin is not a PRD. It is not a project spec. It is you.
+A `.twin` file encodes how you think. Drop it into any project. Your AI does not wait for instructions. It decides what to build next and builds it. Not human in the loop. Twin in the loop.
 
 ## The Problem
 
-AI agents have velocity but no vector. They do what you tell them. When you stop telling them, they stop.
+You give an agent a task list. It finishes. It stops. Now you have to decide what comes next.
 
-You are not writing code. But you are checking at 2am. Writing the next batch of tasks. Going back to sleep. Waking at 5am to check again.
+So you check at 2am. Write the next batch. Go back to sleep. Wake at 5am. Check again. You are not writing code but you are on call around the clock.
 
 This is Vampire Coding. Hands-off in theory. Consumed in practice.
 
-The root cause: agents do not know what you would build next. They do not have your taste.
+The root cause: agents do not know what you would build next. They can execute. They cannot decide.
 
 ## The Fix
 
 Three commands.
 
 ```
-twin init     # encode your taste
-twin plan     # your twin decides what to build
-twin build    # your twin builds it
+twin init     # encode how you think
+twin plan     # your twin decides what to build next
+twin build    # your twin builds it without you
 ```
 
+The difference between a `.twin` file and a Claude MD or a rules file: those are instructions. This is a decision-maker. Your twin knows how you think and decides what comes next.
+
+Run `twin plan` once and you get the next batch of features you would have chosen. Run it again and you get the batch after that. Keep running it and you are watching your own product roadmap unfold without writing a single task yourself.
+
 ## Before You Start
 
 - **Node.js 18+** — [nodejs.org](https://nodejs.org)
@@ -33,13 +35,13 @@ twin build    # your twin builds it
 
 ## Quick Start
 
-Every twin project starts in its own folder. Create one, then run the commands from inside it.
+Each twin project starts in its own folder. Create one, then run from inside it.
 
 ```bash
 # 0. Create a project folder
 mkdir my-app && cd my-app
 
-# 1. Create your twin (only need to do this once)
+# 1. Create your twin (once)
 npx twin-cli init
 # → Asks your name, then 5 questions about how you build
 # → Generates yourname.twin
@@ -56,7 +58,7 @@ npx twin-cli build
 
 ## Example: Building a Habit Tracker
 
-Here is a full walkthrough from zero to working app.
+A full walkthrough from zero to working app.
 
 ```bash
 # Create the project
@@ -92,22 +94,24 @@ Your `.twin` file is portable. Copy it into any new project and run `twin plan`
 
 Twin works best on new projects. Some things to try:
 
-- **Habit tracker** with streaks and daily timers
-- **Personal landing page** with email capture and a changelog
-- **Micro-SaaS dashboard** for tracking one metric
-- **CLI tool** that solves a problem you keep solving manually
-- **PWA** that replaces a spreadsheet you use every day
+- Habit tracker with streaks and daily timers
+- Personal landing page with email capture and a changelog
+- Micro-SaaS dashboard for tracking one metric
+- CLI tool that solves a problem you keep solving by hand
+- PWA that replaces a spreadsheet you use each day
 
 ## The Loop
 
 `init → plan → build → plan`
 
-This is the core cycle. Your twin drives the whole thing.
+Your twin drives the whole cycle.
 
-1. **`twin init`** — create your taste profile (once)
+1. **`twin init`** — encode how you think (once)
 2. **`twin plan`** — your twin generates tasks that match how you prioritize
 3. **`twin build`** — your twin builds on its own, updating `prd.json` as stories complete
-4. **`twin plan` again** — your twin reads what shipped and plans what comes next
+4. **`twin plan` again** — your twin reads what shipped and decides what comes next
+
+You did not write a task list. The twin wrote it. You did not pick the next feature. The twin picked it. That is the shift: from reactive to proactive.
 
 Each iteration, Claude Code starts fresh but reads the files on disk. Your twin. The PRD. A progress log. The files are the memory. Your taste stays consistent across runs.
 
@@ -119,7 +123,7 @@ Asks your name, then 5 questions about how you build things. Generates `yourname
 
 ### `twin plan`
 
-Reads your `.twin` file and project context. Generates 3-5 atomic capabilities that match your taste. Writes `prd.json` with user stories and status tracking.
+Reads your `.twin` file and project context. Generates 3-5 capabilities that match your taste. Writes `prd.json` with user stories and status tracking.
 
 If no `product.md` exists, `twin plan` asks 2 quick questions to set up your project context first. Running it again adds new stories without duplicating old ones.
 
@@ -127,16 +131,18 @@ If no `product.md` exists, `twin plan` asks 2 quick questions to set up your pro
 
 Runs an autonomous build loop using Claude Code. Each iteration:
 
-- Reads your twin file for taste
+- Reads your twin file for how you think
 - Reads `prd.json` for open stories
-- Picks the next story to build (the model decides, guided by your taste)
+- Picks the next story to build (guided by your taste)
 - Builds it, commits, and marks it done in `prd.json`
 - Appends learnings to `progress.md`
 - Repeats until all stories are done or max iterations hit
 
 ```bash
-twin build                     # default: 5 iterations
-twin build --max-iterations 10 # custom limit
+twin build                       # build the current stories (default: 3)
+twin build --loop                # build, plan, build — fully autonomous
+twin build --loop --stories 20   # stop after 20 stories
+twin build --loop --minutes 30   # stop after 30 minutes
 ```
 
 Requires Claude Code installed and available in your PATH.
@@ -146,7 +152,7 @@ Requires Claude Code installed and available in your PATH.
 - **Execution bias** — do you plan first or build first? Ship rough or wait for polish?
 - **Quality compass** — how do you define "done"? What does "good" look like to you?
 - **Decision-making style** — how do you get unstuck? How do you weigh trade-offs?
-- **Strong beliefs** — what do you believe that most people would disagree with?
+- **Strong beliefs** — what do you believe that most would disagree with?
 - **Anti-patterns** — what do you refuse to do?
 
 ## What Does NOT Go in a `.twin` File
@@ -159,7 +165,11 @@ The twin encodes how you think. The project files encode what you are building.
 
 ## What Comes Next
 
-`twin tweak` for natural language updates. `twin share` for publishing your taste.
+`twin tweak` for natural language updates. `twin share` for publishing your taste publicly.
+
+## Notes
+
+**macOS users:** You may see a brief system popup the first time `twin build` spawns Claude Code. This is macOS verifying the process. It auto-dismisses. To prevent it, enable your terminal app under System Settings → Privacy & Security → Developer Tools.
 
 ## License
 

package/bin/twin.js

@@ -17,17 +17,24 @@ if (!command || command === 'init') {
 } else if (command === 'plan') {
   plan();
 } else if (command === 'build') {
-  const maxIterations = parseInt(parseFlag('--max-iterations', '5'), 10);
-  build(maxIterations);
+  const loop = process.argv.includes('--loop');
+  const storiesFlag = parseFlag('--stories', null);
+  const minutesFlag = parseFlag('--minutes', null);
+  const maxStories = storiesFlag ? parseInt(storiesFlag, 10) : (loop ? Infinity : 3);
+  const maxMinutes = minutesFlag ? parseInt(minutesFlag, 10) : null;
+  build({ maxStories, loop, maxMinutes });
 } else if (command === '--help' || command === '-h') {
   console.log(`
-twin - encode your decision-making DNA
+twin - your twin builds while you sleep
 
 Usage:
-  twin init                    Interview yourself, generate your .twin file
-  twin plan                    Generate tasks that match your taste
-  twin build [--max-iterations N]  Build autonomously using Claude Code (default: 5)
-  twin --help                  Show this message
+  twin init                  Interview yourself, generate your .twin file
+  twin plan                  Your twin decides what to build next
+  twin build [--stories N]   Build N stories using Claude Code (default: 3)
+  twin build --loop          Build, plan, build — fully autonomous
+  twin build --loop --stories 20  Stop after 20 stories
+  twin build --loop --minutes 30  Stop after 30 minutes
+  twin --help                Show this message
 `);
 } else {
   console.log(`Unknown command: ${command}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twin-cli",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Your twin builds while you sleep. Not human in the loop. Twin in the loop.",
   "type": "module",
   "bin": {

package/src/build.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import { readFile, writeFile, readdir } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { runPlan } from './plan.js';
 
 const COMPLETION_SIGNAL = '<twin>STORY_COMPLETE</twin>';
 const ALL_DONE_SIGNAL = '<twin>ALL_COMPLETE</twin>';
@@ -17,7 +18,7 @@ async function findTwinFile(cwd) {
   const files = await readdir(cwd);
   const twinFiles = files.filter((f) => f.endsWith('.twin'));
   if (twinFiles.length === 0) {
-    console.error('No .twin file found. Run `twin init` first.\n');
+    console.error('No .twin file found. Run `npx twin-cli init` first.\n');
     process.exit(1);
   }
   return resolve(cwd, twinFiles[0]);
@@ -29,22 +30,23 @@ function buildPrompt(twinContent, twinFilename, prdContent, progressContent) {
 1. **The twin file** (${twinFilename}) — this is the builder's taste, their decision-making DNA. Build the way they would build.
 2. **prd.json** — the product requirements with user stories. Each story has a status: "open", "in_progress", or "done".
 
-${progressContent ? '3. **progress.md** — notes from previous build iterations. Read this to understand what was already tried and learned.\n' : ''}
+${progressContent ? '3. **progress.md** — notes from previous build runs. Read this to understand what was already tried and learned.\n' : ''}
 ## Your task
 
 1. Read prd.json and find stories that are not "done"
-2. Pick the story YOU think should be built next based on the twin's taste and what makes sense given the current state of the codebase
-3. Build it. Write real, working code. Follow the acceptance criteria.
+2. Pick ONE story — the single story YOU think should be built next based on the twin's taste and the current state of the codebase
+3. Build that ONE story. Write real, working code. Follow the acceptance criteria.
 4. When the story's acceptance criteria are met, update prd.json: set that story's status to "done" and add "completedAt" with the current ISO timestamp
-5. Append to progress.md what you built, what files changed, and any learnings for future iterations
-6. Output ${COMPLETION_SIGNAL} when you finish a story
-7. If ALL stories in prd.json are "done", output ${ALL_DONE_SIGNAL} instead
+5. Append to progress.md what you built, what files changed, and any learnings
+6. Commit your work with a clear message
+7. Output ${COMPLETION_SIGNAL} when you finish the story
+8. If ALL stories in prd.json are "done" after completing yours, output ${ALL_DONE_SIGNAL} instead
 
 ## Rules
+- Build ONE story per run. Do not start a second story.
 - Build real features, not stubs
 - Follow the taste in the twin file — it tells you how this person builds
-- Commit your work with a clear message after completing a story
-- If you get stuck, note what blocked you in progress.md and move on to a different story
+- If you get stuck, note what blocked you in progress.md and output ${COMPLETION_SIGNAL} anyway
 - Do NOT ask questions. Make decisions based on the twin and the PRD.
 
 ## Twin file (${twinFilename})
@@ -56,27 +58,33 @@ ${progressContent ? `\n## progress.md\n${progressContent}` : ''}
 `;
 }
 
-function extractTextFromEvent(jsonLine) {
+function parseEvent(jsonLine) {
   try {
     const event = JSON.parse(jsonLine);
 
     // Text delta from assistant message streaming
     if (event.type === 'assistant' && event.message?.content) {
-      // Full message content (final)
-      return event.message.content
+      const text = event.message.content
         .filter((block) => block.type === 'text')
         .map((block) => block.text)
         .join('');
+      if (text) return { type: 'text', text };
     }
 
     // Partial streaming text delta
     if (event.type === 'content_block_delta' && event.delta?.type === 'text_delta') {
-      return event.delta.text;
+      return { type: 'text', text: event.delta.text };
     }
 
-    // Result message with text
-    if (event.type === 'result' && event.result) {
-      return null; // Already captured via deltas
+    // Tool use — show what Claude is doing
+    if (event.type === 'content_block_start' && event.content_block?.type === 'tool_use') {
+      const name = event.content_block.name || 'working';
+      return { type: 'tool', name };
+    }
+
+    // Tool result
+    if (event.type === 'content_block_start' && event.content_block?.type === 'tool_result') {
+      return { type: 'tool_done' };
     }
   } catch {
     // Not valid JSON or unexpected shape — skip
@@ -98,16 +106,46 @@ function runIteration(prompt, cwd) {
 
     let output = '';
     let buffer = '';
-    let hasReceivedText = false;
+    let lastActivity = Date.now();
+    let statusLine = false; // true when a status line is showing
+    let atLineStart = true; // track if cursor is at start of a line
+
+    const TOOL_LABELS = {
+      Read: 'Reading file',
+      Write: 'Writing file',
+      Edit: 'Editing file',
+      Bash: 'Running command',
+      Glob: 'Searching files',
+      Grep: 'Searching code',
+    };
+
+    function clearStatus() {
+      if (statusLine) {
+        process.stdout.write('\r\x1b[K');
+        statusLine = false;
+      }
+    }
+
+    function showStatus(msg) {
+      if (!atLineStart && !statusLine) {
+        process.stdout.write('\n');
+        atLineStart = true;
+      }
+      clearStatus();
+      const elapsed = Math.round((Date.now() - startTime) / 1000);
+      process.stdout.write(`\r\x1b[2m${msg} (${elapsed}s)\x1b[0m`);
+      statusLine = true;
+    }
 
     // Heartbeat timer — show elapsed time while waiting
     const startTime = Date.now();
     const heartbeat = setInterval(() => {
       const elapsed = Math.round((Date.now() - startTime) / 1000);
-      if (!hasReceivedText) {
-        process.stdout.write(`\rWorking... (${elapsed}s)`);
+      const idle = Date.now() - lastActivity;
+      if (idle > 5_000) {
+        showStatus('Working...');
       }
-    }, 10_000);
+    }, 5_000);
 
     claude.stdout.on('data', (chunk) => {
       buffer += chunk.toString();
@@ -116,15 +154,27 @@ function runIteration(prompt, cwd) {
 
       for (const line of lines) {
         if (!line.trim()) continue;
-        const text = extractTextFromEvent(line);
-        if (text) {
-          if (!hasReceivedText) {
-            // Clear the heartbeat line on first real output
-            process.stdout.write('\r\x1b[K');
-            hasReceivedText = true;
+        const event = parseEvent(line);
+        if (!event) continue;
+
+        lastActivity = Date.now();
+
+        if (event.type === 'text') {
+          clearStatus();
+          output += event.text;
+          // Hide completion signals from user — they're internal plumbing
+          const display = event.text
+            .replace(COMPLETION_SIGNAL, '')
+            .replace(ALL_DONE_SIGNAL, '');
+          if (display) {
+            process.stdout.write(display);
+            atLineStart = display.endsWith('\n');
           }
-          process.stdout.write(text);
-          output += text;
+        } else if (event.type === 'tool') {
+          const label = TOOL_LABELS[event.name] || event.name;
+          showStatus(label);
+        } else if (event.type === 'tool_done') {
+          clearStatus();
         }
       }
     });
@@ -135,17 +185,15 @@ function runIteration(prompt, cwd) {
 
     claude.on('close', (code) => {
       clearInterval(heartbeat);
+      clearStatus();
       // Process any remaining buffer
       if (buffer.trim()) {
-        const text = extractTextFromEvent(buffer.trim());
-        if (text) {
-          process.stdout.write(text);
-          output += text;
+        const event = parseEvent(buffer.trim());
+        if (event?.type === 'text') {
+          process.stdout.write(event.text);
+          output += event.text;
         }
       }
-      if (!hasReceivedText) {
-        process.stdout.write('\r\x1b[K'); // Clear heartbeat line
-      }
       resolvePromise({ output, code });
     });
 
@@ -165,78 +213,208 @@ function runIteration(prompt, cwd) {
   });
 }
 
-export async function build(maxIterations = 5) {
+// Dim helper for secondary/chrome text
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const bar = dim('─'.repeat(60));
+
+const STORY_RETRIES = 2;
+const STORY_RETRY_DELAYS = [10_000, 30_000]; // 10s, then 30s
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function summary(totalBuilt, cycles, elapsed) {
+  const mins = Math.round(elapsed / 60000);
+  const time = mins > 0 ? ` in ${mins}m` : '';
+  const cycleNote = cycles > 1 ? ` across ${cycles} cycles` : '';
+  return `${totalBuilt} stories built${cycleNote}${time}`;
+}
+
+export async function build({ maxStories = 3, loop = false, maxMinutes = null } = {}) {
   const cwd = process.cwd();
+  const startTime = Date.now();
+  const timeLimitMs = maxMinutes ? maxMinutes * 60 * 1000 : null;
+
+  // Clean exit on Ctrl+C — finish current story, then stop
+  let stopping = false;
+  process.on('SIGINT', () => {
+    if (stopping) process.exit(1); // Second Ctrl+C forces exit
+    stopping = true;
+    console.log(dim('\n\nStopping after current story finishes...\n'));
+  });
 
   // Find twin file
   const twinPath = await findTwinFile(cwd);
   const twinFilename = twinPath.split('/').pop();
-  const twinContent = await readFile(twinPath, 'utf-8');
 
   // Read prd.json — required
   const prdPath = resolve(cwd, 'prd.json');
   const prdContent = await readIfExists(prdPath);
   if (!prdContent) {
-    console.error('No prd.json found. Run `twin plan` first.\n');
+    console.error('No prd.json found. Run `npx twin-cli plan` first.\n');
     process.exit(1);
   }
 
   // Check if there are open stories
   const prd = JSON.parse(prdContent);
   const openStories = prd.userStories.filter((s) => s.status !== 'done');
-  if (openStories.length === 0) {
-    console.log('All stories in prd.json are already done. Run `twin plan` to generate more.\n');
+  if (openStories.length === 0 && !loop) {
+    console.log('All stories are done. Plan the next batch:\n  npx twin-cli plan\n');
     process.exit(0);
   }
+  // In loop mode with no open stories, the while loop will trigger planning
+
+  console.log('');
+  console.log(bar);
+  console.log(bold(`  twin build${loop ? ' --loop' : ''}`));
+  console.log(dim(`  ${twinFilename}`));
+  if (loop) {
+    const limits = [];
+    if (maxStories !== Infinity) limits.push(`${maxStories} stories`);
+    if (maxMinutes) limits.push(`${maxMinutes} min`);
+    console.log(dim(`  ${limits.length > 0 ? limits.join(' · ') : 'no limit — Ctrl+C to stop'}`));
+  } else {
+    const storiesThisRun = Math.min(maxStories, openStories.length);
+    console.log(dim(`  ${openStories.length} remaining · building ${storiesThisRun}`));
+  }
+  console.log(bar);
+  console.log('');
+
+  let totalBuilt = 0;
+  let cycle = 1;
+
+  while (totalBuilt < maxStories) {
+    // Check if user requested stop
+    if (stopping) {
+      console.log(bar);
+      console.log(bold('  Stopped'));
+      console.log(dim(`  ${summary(totalBuilt, cycle, Date.now() - startTime)}`));
+      console.log(bar);
+      console.log('');
+      break;
+    }
 
-  console.log(`\n--- twin build ---`);
-  console.log(`Using ${twinFilename}`);
-  console.log(`${openStories.length} stories remaining in prd.json`);
-  console.log(`Max iterations: ${maxIterations}\n`);
-
-  for (let i = 1; i <= maxIterations; i++) {
-    console.log(`\n${'='.repeat(60)}`);
-    console.log(`  Iteration ${i} of ${maxIterations}`);
-    console.log(`${'='.repeat(60)}\n`);
-
-    // Re-read files each iteration (they may have been updated)
-    const currentPrd = await readFile(prdPath, 'utf-8');
-    const progressContent = await readIfExists(resolve(cwd, 'progress.md'));
+    // Re-read twin each cycle (user may tweak mid-run)
+    const twinContent = await readFile(twinPath, 'utf-8');
+
+    // Re-read prd.json (previous story or plan cycle may have updated it)
+    const currentPrdContent = await readFile(prdPath, 'utf-8');
+    const currentPrd = JSON.parse(currentPrdContent);
+    const remaining = currentPrd.userStories.filter((s) => s.status !== 'done');
+
+    // No open stories — either plan more or exit
+    if (remaining.length === 0) {
+      if (!loop) {
+        console.log('');
+        console.log(bar);
+        console.log(bold('  All stories complete'));
+        console.log(dim(`  ${summary(totalBuilt, cycle, Date.now() - startTime)}`));
+        console.log(bar);
+        console.log('\nNext step — plan more features:');
+        console.log('  npx twin-cli plan\n');
+        break;
+      }
 
-    const prompt = buildPrompt(twinContent, twinFilename, currentPrd, progressContent);
-    const { output, code } = await runIteration(prompt, cwd);
+      // Loop mode — ask the twin to plan the next batch
+      console.log('');
+      console.log(bar);
+      console.log(bold(`  Cycle ${cycle} complete`));
+      console.log(dim('  Your twin is planning the next batch...'));
+      console.log(bar);
+      console.log('');
+
+      const newStories = await runPlan(cwd);
+
+      if (newStories.length === 0) {
+        console.log(bar);
+        console.log(bold('  Your twin has built everything it would build right now.'));
+        console.log(dim(`  ${summary(totalBuilt, cycle, Date.now() - startTime)}`));
+        console.log(bar);
+        console.log('');
+        break;
+      }
 
-    if (code !== 0) {
-      console.log(`\nClaude exited with code ${code}. Continuing to next iteration...\n`);
+      console.log(`Planned ${newStories.length} new stories:`);
+      for (const story of newStories) {
+        console.log(dim(`  ${story.id}`) + ` ${story.title}`);
+      }
+      console.log('');
+      cycle++;
+      continue; // Back to top of while loop to build them
     }
 
-    // Check completion signals
-    if (output.includes(ALL_DONE_SIGNAL)) {
-      console.log(`\n${'='.repeat(60)}`);
-      console.log('  All stories complete!');
-      console.log(`${'='.repeat(60)}`);
-      console.log('\nNext step — plan more features:');
-      console.log('  twin plan\n');
+    // Check time limit before starting next story
+    if (timeLimitMs && (Date.now() - startTime) >= timeLimitMs) {
+      const mins = Math.round((Date.now() - startTime) / 60000);
+      console.log(bar);
+      console.log(bold('  Time limit reached'));
+      console.log(dim(`  ${summary(totalBuilt, cycle, Date.now() - startTime)}`));
+      console.log(bar);
+      console.log('');
       break;
     }
 
-    if (output.includes(COMPLETION_SIGNAL)) {
-      // Re-read PRD to check remaining stories
-      const updatedPrd = JSON.parse(await readFile(prdPath, 'utf-8'));
-      const remaining = updatedPrd.userStories.filter((s) => s.status !== 'done');
-      if (remaining.length === 0) {
-        console.log(`\n${'='.repeat(60)}`);
-        console.log('  All stories complete!');
-        console.log(`${'='.repeat(60)}`);
-        console.log('\nNext step — plan more features:');
-        console.log('  twin plan\n');
+    // Build one story
+    const storyNum = totalBuilt + 1;
+
+    console.log('');
+    console.log(bar);
+    if (maxStories === Infinity) {
+      console.log(bold(`  Story ${storyNum}`));
+    } else {
+      console.log(bold(`  Story ${storyNum} of ${maxStories}`));
+    }
+    console.log(bar);
+    console.log('');
+
+    const progressContent = await readIfExists(resolve(cwd, 'progress.md'));
+    const prompt = buildPrompt(twinContent, twinFilename, currentPrdContent, progressContent);
+
+    let succeeded = false;
+    for (let attempt = 0; attempt <= STORY_RETRIES; attempt++) {
+      if (attempt > 0) {
+        const delay = STORY_RETRY_DELAYS[attempt - 1];
+        console.log(dim(`\n  API error — retrying in ${delay / 1000}s...\n`));
+        await sleep(delay);
+      }
+
+      const { output, code } = await runIteration(prompt, cwd);
+
+      if (code !== 0) {
+        if (attempt < STORY_RETRIES) continue; // retry
+        console.log(dim(`\nClaude exited with code ${code} after ${STORY_RETRIES + 1} attempts. Skipping story.\n`));
+        // Log the failure to progress.md so the next run knows
+        const progressPath = resolve(cwd, 'progress.md');
+        const existing = await readIfExists(progressPath) || '';
+        const note = `\n## Skipped story (${new Date().toISOString()})\nClaude exited with code ${code} after ${STORY_RETRIES + 1} attempts. Story was not counted.\n`;
+        await writeFile(progressPath, existing + note, 'utf-8');
         break;
       }
-      console.log(`\nStory complete. ${remaining.length} remaining.\n`);
+
+      succeeded = true;
+      if (output.includes(COMPLETION_SIGNAL) || output.includes(ALL_DONE_SIGNAL)) {
+        const afterPrd = JSON.parse(await readFile(prdPath, 'utf-8'));
+        const left = afterPrd.userStories.filter((s) => s.status !== 'done');
+        if (left.length > 0) {
+          console.log(dim(`\nStory done. ${left.length} open in prd.json.\n`));
+        }
+      }
+      break;
     }
 
-    if (i === maxIterations) {
-      console.log(`\nReached max iterations (${maxIterations}). Run \`twin build\` again to continue.\n`);
+    if (succeeded) totalBuilt++;
+  }
+
+  if (totalBuilt > 0 && totalBuilt >= maxStories) {
+    console.log(bar);
+    console.log(bold(`  Done`));
+    console.log(dim(`  ${summary(totalBuilt, cycle, Date.now() - startTime)}`));
+    console.log(bar);
+    if (!loop) {
+      console.log('\nKeep going:\n  npx twin-cli build');
     }
+    console.log('');
   }
 }

package/src/generate.js

@@ -43,15 +43,21 @@ Rules:
 - No preamble, no explanation — just the .twin file content`;
 
 export async function generateTwin(name, interviewText) {
-  const content = await callLLM(
-    SYSTEM_PROMPT,
-    `The builder's name is ${name}.\n\nHere are the interview answers. Generate the .twin file.\n\n${interviewText}`,
-  );
+  let content;
+  try {
+    content = await callLLM(
+      SYSTEM_PROMPT,
+      `The builder's name is ${name}.\n\nHere are the interview answers. Generate the .twin file.\n\n${interviewText}`,
+    );
+  } catch (err) {
+    console.error(`\n${err.message}\n`);
+    process.exit(1);
+  }
 
   const filename = `${name.toLowerCase().replace(/[^a-z0-9]/g, '')}.twin`;
   const outPath = resolve(process.cwd(), filename);
   await writeFile(outPath, content, 'utf-8');
-  console.log(`Done! Your twin file is at: ${outPath}`);
-  console.log('\nNext step — plan what to build:');
-  console.log('  twin plan');
+  console.log(`Done! Created ${filename}\n`);
+  console.log('Next step — plan what to build:');
+  console.log('  npx twin-cli plan');
 }

package/src/init.js

@@ -25,7 +25,8 @@ export async function init() {
   }
   prompter.close();
 
-  console.log('\nGenerating your .twin file...\n');
+  const filename = `${name.toLowerCase().replace(/[^a-z0-9]/g, '')}.twin`;
+  console.log(`\nGenerating ${filename}...\n`);
 
   const paired = answers.map((a) => `Q: ${a.question}\nA: ${a.answer}`).join('\n\n');
   await generateTwin(name, paired);

package/src/llm.js

@@ -22,21 +22,24 @@ export async function callLLM(systemPrompt, userMessage) {
 
     claude.on('close', (code) => {
       if (code !== 0) {
-        console.error(`Claude Code exited with code ${code}.`);
-        if (stderr) console.error(stderr);
-        process.exit(1);
+        const msg = stderr
+          ? `Claude Code exited with code ${code}: ${stderr.trim()}`
+          : `Claude Code exited with code ${code}.`;
+        reject(new Error(msg));
+        return;
       }
       resolve(stdout.trim());
     });
 
     claude.on('error', (err) => {
       if (err.code === 'ENOENT') {
-        console.error('\nClaude Code is not installed or not in PATH.');
-        console.error('Install it: https://docs.anthropic.com/en/docs/claude-code\n');
-        process.exit(1);
+        reject(new Error(
+          'Claude Code is not installed or not in PATH.\n'
+          + 'Install it: https://docs.anthropic.com/en/docs/claude-code'
+        ));
+        return;
       }
-      console.error(`\nFailed to spawn Claude: ${err.message}\n`);
-      process.exit(1);
+      reject(new Error(`Failed to spawn Claude: ${err.message}`));
     });
 
     claude.stdin.write(prompt);
@@ -44,8 +47,7 @@ export async function callLLM(systemPrompt, userMessage) {
   });
 
   if (!output) {
-    console.error('No content returned from Claude Code.');
-    process.exit(1);
+    throw new Error('No content returned from Claude Code.');
   }
 
   return output;

package/src/plan.js

@@ -62,6 +62,13 @@ async function bootstrapProduct() {
   return content;
 }
 
+const PLAN_RETRIES = 2;
+const PLAN_RETRY_DELAY = 15_000; // 15s
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
 function parseLLMJson(raw) {
   // Strip markdown code fences if the LLM wraps its response
   let cleaned = raw.trim();
@@ -71,36 +78,28 @@ function parseLLMJson(raw) {
   return JSON.parse(cleaned);
 }
 
-export async function plan() {
-  // Find *.twin file — required
-  const cwd = process.cwd();
+/**
+ * Headless plan — callable from the build loop.
+ * Requires product.md and a .twin file to already exist.
+ * Returns the array of NEW stories added (empty if the twin has nothing to add).
+ */
+export async function runPlan(cwd) {
   const files = await readdir(cwd);
   const twinFiles = files.filter((f) => f.endsWith('.twin'));
-  if (twinFiles.length === 0) {
-    console.error('No .twin file found. Run `twin init` first.\n');
-    process.exit(1);
-  }
-  if (twinFiles.length > 1) {
-    console.log(`Found multiple .twin files: ${twinFiles.join(', ')}. Using ${twinFiles[0]}.`);
-  }
+  if (twinFiles.length === 0) return [];
+
   const twinPath = resolve(cwd, twinFiles[0]);
   const twin = await readFile(twinPath, 'utf-8');
-  console.log(`Using ${twinFiles[0]}\n`);
 
-  // Read or bootstrap product.md
-  const productPath = resolve(process.cwd(), 'product.md');
-  let product = await readIfExists(productPath);
-  if (!product) {
-    product = await bootstrapProduct();
-  }
+  const productPath = resolve(cwd, 'product.md');
+  const product = await readIfExists(productPath);
+  if (!product) return []; // Can't plan without product context
 
-  // Read optional context files
-  const statusPath = resolve(process.cwd(), 'status.md');
-  const prdPath = resolve(process.cwd(), 'prd.json');
+  const statusPath = resolve(cwd, 'status.md');
+  const prdPath = resolve(cwd, 'prd.json');
   const status = await readIfExists(statusPath);
   const existingPrd = await readIfExists(prdPath);
 
-  // Assemble user message
   let userMessage = `## .twin file\n${twin}\n\n## product.md\n${product}`;
   if (status) {
     userMessage += `\n\n## status.md\n${status}`;
@@ -110,31 +109,89 @@ export async function plan() {
   }
   userMessage += '\n\nGenerate the next 3-5 capabilities as JSON.';
 
-  console.log('--- twin plan ---');
-  console.log('Generating tasks that match your taste...\n');
-
-  const raw = await callLLM(TASK_SYSTEM_PROMPT, userMessage);
+  let raw;
+  for (let attempt = 0; attempt <= PLAN_RETRIES; attempt++) {
+    try {
+      raw = await callLLM(TASK_SYSTEM_PROMPT, userMessage);
+      break;
+    } catch (err) {
+      if (attempt < PLAN_RETRIES) {
+        console.log(`\x1b[2m  API error — retrying plan in ${PLAN_RETRY_DELAY / 1000}s...\x1b[0m`);
+        await sleep(PLAN_RETRY_DELAY);
+      } else {
+        console.error(`Planning failed after ${PLAN_RETRIES + 1} attempts: ${err.message}`);
+        return [];
+      }
+    }
+  }
 
-  // Parse structured output
   let prd;
   try {
     prd = parseLLMJson(raw);
-  } catch (e) {
-    console.error('Failed to parse LLM response as JSON. Raw output:\n');
-    console.error(raw);
-    process.exit(1);
+  } catch {
+    return [];
   }
 
-  // Derive project name from cwd if LLM didn't provide one
   if (!prd.project) {
-    prd.project = basename(process.cwd());
+    prd.project = basename(cwd);
+  }
+
+  const newStories = prd.userStories || [];
+
+  // Merge with existing stories
+  if (existingPrd) {
+    try {
+      const existing = JSON.parse(existingPrd);
+      const existingStories = existing.userStories || [];
+      prd.userStories = [...existingStories, ...newStories];
+      if (!prd.project && existing.project) prd.project = existing.project;
+      if (!prd.description && existing.description) prd.description = existing.description;
+    } catch {
+      // If existing prd.json is malformed, just use the new one
+    }
   }
 
-  // Write prd.json
   await writeFile(prdPath, JSON.stringify(prd, null, 2) + '\n', 'utf-8');
+  return newStories;
+}
+
+/**
+ * Interactive plan — called from `twin plan` CLI command.
+ * Bootstraps product.md if missing, prints stories to console.
+ */
+export async function plan() {
+  // Find *.twin file — required
+  const cwd = process.cwd();
+  const files = await readdir(cwd);
+  const twinFiles = files.filter((f) => f.endsWith('.twin'));
+  if (twinFiles.length === 0) {
+    console.error('No .twin file found. Run `npx twin-cli init` first.\n');
+    process.exit(1);
+  }
+  if (twinFiles.length > 1) {
+    console.log(`Found multiple .twin files: ${twinFiles.join(', ')}. Using ${twinFiles[0]}.`);
+  }
+  console.log(`Using ${twinFiles[0]}\n`);
+
+  // Read or bootstrap product.md
+  const productPath = resolve(cwd, 'product.md');
+  let product = await readIfExists(productPath);
+  if (!product) {
+    product = await bootstrapProduct();
+  }
+
+  console.log('--- twin plan ---');
+  console.log('Your twin is deciding what to build next...\n');
+
+  const newStories = await runPlan(cwd);
 
-  // Print stories to console
-  for (const story of prd.userStories) {
+  if (newStories.length === 0) {
+    console.log('Your twin has nothing to add right now.\n');
+    return;
+  }
+
+  // Print new stories to console
+  for (const story of newStories) {
     console.log(`${story.id}. ${story.title}`);
     console.log(`   ${story.description}`);
     for (const ac of story.acceptanceCriteria) {
@@ -142,7 +199,10 @@ export async function plan() {
     }
     console.log('');
   }
+
+  const prdPath = resolve(cwd, 'prd.json');
   console.log(`---`);
   console.log(`Wrote ${prdPath}`);
-  console.log(`\nRun \`twin build\` to start building.`);
+  console.log(`\nNext step — let your twin build it:`);
+  console.log(`  npx twin-cli build`);
 }