twin-cli 0.2.1 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 Old TDD meant write the tests first. New TDD means write the twin first.
 
-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.
+A `.twin` file is the `.env` for your taste. 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
 
@@ -18,8 +18,8 @@ The root cause: agents do not know what you would build next. They can execute.
 
 Three commands.
 
-```
-twin init     # encode how you think
+```bash
+twin init     # your taste, in a file
 twin plan     # your twin decides what to build next
 twin build    # your twin builds it without you
 ```
@@ -33,6 +33,8 @@ Run `twin plan` once and you get the next batch of features you would have chose
 - **Node.js 18+** — [nodejs.org](https://nodejs.org)
 - **Claude Code** — [docs.anthropic.com](https://docs.anthropic.com/en/docs/claude-code) (powers all three commands)
 
+Run everything with `npx twin-cli` — no global install needed. This keeps you on the latest version automatically.
+
 ## Quick Start
 
 Each twin project starts in its own folder. Create one, then run from inside it.
@@ -82,13 +84,13 @@ npx twin-cli build
 # → Picks the next story, builds it, marks it done
 # → You watch it happen in real time
 
-# Want more features? Plan again.
+# Want more? Plan again.
 npx twin-cli plan
 # → Sees what is done, generates the next batch
 npx twin-cli build
 ```
 
-Your `.twin` file is portable. Copy it into any new project and run `twin plan` to start.
+Your `.twin` file is portable. Copy it into any new project and run `npx twin-cli plan` to start.
 
 ## Project Ideas
 
@@ -106,12 +108,12 @@ Twin works best on new projects. Some things to try:
 
 Your twin drives the whole cycle.
 
-1. **`twin init`** — encode how you think (once)
-2. **`twin plan`** — your twin generates tasks that match how you prioritize
+1. **`twin init`** — your taste, in a file (once)
+2. **`twin plan`** — your twin generates the next batch of stories, matched to 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 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.
+You did not write a task list. Your twin wrote it. You did not pick the next feature. Your twin picked it.
 
 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 +121,7 @@ Each iteration, Claude Code starts fresh but reads the files on disk. Your twin.
 
 ### `twin init`
 
-Asks your name, then 5 questions about how you build things. Generates `yourname.twin`.
+Asks your name, then 5 questions about how you build. Generates `yourname.twin`.
 
 ### `twin plan`
 
@@ -136,15 +138,29 @@ Runs an autonomous build loop using Claude Code. Each iteration:
 - 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
+- Repeats until all stories are done or the story limit is hit
 
 ```bash
-twin build                     # default: 5 iterations
-twin build --max-iterations 10 # custom limit
+npx twin-cli build                       # build the current stories (default: 3)
+npx twin-cli build --loop                # build, plan, build — fully autonomous
+npx twin-cli build --loop --stories 20   # stop after 20 stories
+npx twin-cli build --loop --minutes 30   # stop after 30 minutes
 ```
 
 Requires Claude Code installed and available in your PATH.
 
+### `twin steer`
+
+You have something to say but don't want to write a user story yourself. Just say it:
+
+```bash
+twin steer "I want users to be able to share their progress on Twitter"
+```
+
+Or run `twin steer` with no arguments to type or dictate a longer message.
+
+Your twin turns it into stories in `prd.json` and updates your `.twin` file with anything it can infer about your taste. Works any time — before a build, between runs, or from a second terminal while a build is running.
+
 ## What Goes in a `.twin` File
 
 - **Execution bias** — do you plan first or build first? Ship rough or wait for polish?
@@ -159,11 +175,11 @@ Requires Claude Code installed and available in your PATH.
 - Your tech stack (that goes in project config)
 - Your roadmap (that goes in a PRD)
 
-The twin encodes how you think. The project files encode what you are building. The twin is the founder. The project files are the company.
+The twin holds your taste. The project files hold what you are building. The twin is the founder. The project files are the company.
 
-## What Comes Next
+## Notes
 
-`twin tweak` for natural language updates. `twin share` for publishing your taste publicly.
+**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

@@ -3,6 +3,7 @@
 import { init } from '../src/init.js';
 import { plan } from '../src/plan.js';
 import { build } from '../src/build.js';
+import { steer } from '../src/steer.js';
 
 const command = process.argv[2];
 
@@ -17,17 +18,27 @@ 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 === 'steer') {
+  steer();
 } 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 steer [message]       Tell your twin what to build next
+  twin --help                Show this message
 `);
 } else {
   console.log(`Unknown command: ${command}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twin-cli",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "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,9 @@
 import { spawn } from 'node:child_process';
 import { readFile, writeFile, readdir } from 'node:fs/promises';
+import { unlinkSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { runPlan } from './plan.js';
+import { callLLM } from './llm.js';
 
 const COMPLETION_SIGNAL = '<twin>STORY_COMPLETE</twin>';
 const ALL_DONE_SIGNAL = '<twin>ALL_COMPLETE</twin>';
@@ -17,7 +20,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 +32,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})
@@ -106,6 +110,7 @@ function runIteration(prompt, cwd) {
     let buffer = '';
     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',
@@ -124,6 +129,10 @@ function runIteration(prompt, cwd) {
     }
 
     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`);
@@ -154,8 +163,15 @@ function runIteration(prompt, cwd) {
 
         if (event.type === 'text') {
           clearStatus();
-          process.stdout.write(event.text);
           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');
+          }
         } else if (event.type === 'tool') {
           const label = TOOL_LABELS[event.name] || event.name;
           showStatus(label);
@@ -199,78 +215,329 @@ 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));
+
+async function processSteer(cwd, twinPath, prdPath) {
+  const steerPath = resolve(cwd, 'steer.md');
+  const steerContent = await readIfExists(steerPath);
+  if (!steerContent?.trim()) return;
+
+  const twinContent = await readFile(twinPath, 'utf-8');
+  const twinFilename = twinPath.split('/').pop();
+  const prdContent = await readFile(prdPath, 'utf-8');
+  const prd = JSON.parse(prdContent);
+
+  const maxNum = prd.userStories.reduce((max, s) => {
+    const m = s.id?.match(/\d+/);
+    return m ? Math.max(max, parseInt(m[0], 10)) : max;
+  }, 0);
+  const nextId = `US-${String(maxNum + 1).padStart(3, '0')}`;
+
+  // Send trimmed prd (id + title + status only) to reduce token count
+  const prdSummary = prd.userStories
+    .map((s) => `${s.id}: ${s.title} (${s.status})`)
+    .join('\n');
+
+  const result = await callLLM(
+    'You process developer steering input for a build loop. Output valid JSON only — no prose, no markdown fences.',
+    [
+      'Steering input from developer:',
+      steerContent,
+      '',
+      `Existing stories:\n${prdSummary}`,
+      '',
+      `${twinFilename}:\n${twinContent}`,
+      '',
+      `Next available story id: ${nextId} (increment for each additional story)`,
+      '',
+      'Output JSON with this exact shape:',
+      '{',
+      '  "newStories": [],    // stories to add to prd.json (id, title, userStory, acceptanceCriteria array, status:"open"), empty array if none',
+      '  "twinAppend": null   // text to append to the twin file if this input reveals something clear about the developer\'s taste, or null if nothing clear can be inferred',
+      '}',
+    ].join('\n')
+  );
+
+  let json;
+  try {
+    json = JSON.parse(result.replace(/^```(?:json)?\n?/m, '').replace(/\n?```$/m, '').trim());
+  } catch {
+    console.log(dim('  steer: could not parse response, skipping.'));
+    return;
+  }
+
+  if (json.newStories?.length > 0) {
+    prd.userStories.push(...json.newStories);
+    await writeFile(prdPath, JSON.stringify(prd, null, 2), 'utf-8');
+    console.log('');
+    for (const s of json.newStories) {
+      console.log(dim('  + ') + `${s.id}  ${s.title}`);
+    }
+  }
+
+  if (json.twinAppend) {
+    const current = await readFile(twinPath, 'utf-8');
+    await writeFile(twinPath, current.trimEnd() + '\n\n' + json.twinAppend + '\n', 'utf-8');
+    console.log(dim(`  Updated ${twinFilename}`));
+  }
+
+  // Clear steer.md so it isn't re-processed next cycle
+  await writeFile(steerPath, '', 'utf-8');
+}
+
+async function logPriorityJustification(twinContent, prdContent, storyNum, synthesisPath) {
+  const justification = await callLLM(
+    'You are a prioritization oracle. Answer in 1-3 sentences only. No preamble.',
+    `Twin file:\n${twinContent}\n\nprd.json:\n${prdContent}\n\nIf you could only ship one story this cycle, which would it be and why? Reference the twin file reasoning explicitly.`
+  );
+  const existing = await readIfExists(synthesisPath) || '';
+  const entry = `\n## Story ${storyNum} — ${new Date().toISOString()}\n\n**Priority justification:** ${justification}\n`;
+  await writeFile(synthesisPath, existing + entry, 'utf-8');
+}
+
+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));
+}
+
+// Show an overwriting status line while an async operation runs, then clear it.
+// msg can be a string, or an array of [afterSeconds, message] milestones.
+async function withStatus(msg, fn) {
+  const milestones = Array.isArray(msg)
+    ? msg.slice().sort((a, b) => a[0] - b[0])
+    : [[0, msg]];
+  const start = Date.now();
+  let shown = false;
+  const timer = setInterval(() => {
+    const elapsed = Math.round((Date.now() - start) / 1000);
+    const current = milestones.filter(([s]) => elapsed >= s).pop()[1];
+    process.stdout.write(`\r${dim(`${current} (${elapsed}s)`)}`);
+    shown = true;
+  }, 3_000);
+  try {
+    return await fn();
+  } finally {
+    clearInterval(timer);
+    if (shown) process.stdout.write('\r\x1b[K');
+  }
+}
+
+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;
+
+  // Write lock file so twin steer knows a build is running
+  const lockPath = resolve(cwd, '.twin-lock');
+  await writeFile(lockPath, String(process.pid), 'utf-8');
+  process.on('exit', () => { try { unlinkSync(lockPath); } catch {} });
+
+  // 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.\n');
+    console.log('  npx twin-cli plan             # plan the next batch, then build');
+    console.log('  npx twin-cli build --loop     # plan and build automatically\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');
+
+    // Process any steering input before deciding what to build next
+    await withStatus([
+      [0,   'Applying your steer...'],
+      [20,  'Still working...'],
+      [60,  'Your message is detailed — taking a moment...'],
+      [120, 'Almost there...'],
+    ], () => processSteer(cwd, twinPath, prdPath)).catch(() => {});
+
+    // Re-read prd.json (steer or previous story 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('\n  npx twin-cli plan             # plan the next batch, then build');
+        console.log('  npx twin-cli build --loop     # plan and build automatically\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(bar);
+      console.log('');
+
+      const newStories = await withStatus('Planning...', () => 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'));
+
+    // Log priority justification to synthesis.md before building
+    await withStatus('Thinking...', () =>
+      logPriorityJustification(twinContent, currentPrdContent, storyNum, resolve(cwd, 'synthesis.md'))
+    ).catch(() => {});
+
+    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('\n  npx twin-cli build            # keep building');
+      console.log('  npx twin-cli build --loop     # build and plan automatically\n');
     }
+    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,32 +109,41 @@ 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);
   }
 
-  // Merge with existing stories if prd.json already exists
+  const newStories = prd.userStories || [];
+
+  // Merge with existing stories
   if (existingPrd) {
     try {
       const existing = JSON.parse(existingPrd);
       const existingStories = existing.userStories || [];
-      prd.userStories = [...existingStories, ...prd.userStories];
+      prd.userStories = [...existingStories, ...newStories];
       if (!prd.project && existing.project) prd.project = existing.project;
       if (!prd.description && existing.description) prd.description = existing.description;
     } catch {
@@ -143,11 +151,47 @@ export async function plan() {
     }
   }
 
-  // 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();
+  }
 
-  // Print stories to console
-  for (const story of prd.userStories) {
+  console.log('--- twin plan ---');
+  console.log('Your twin is deciding what to build next...\n');
+
+  const newStories = await runPlan(cwd);
+
+  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) {
@@ -155,7 +199,11 @@ 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            # build the next 3 stories`);
+  console.log(`  npx twin-cli build --loop     # build and plan automatically`);
 }

package/src/steer.js

@@ -0,0 +1,37 @@
+import { writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createPrompter } from './prompt.js';
+import { build } from './build.js';
+
+export async function steer() {
+  const cwd = process.cwd();
+  const steerPath = resolve(cwd, 'steer.md');
+
+  // Accept message as inline args or fall back to interactive prompt
+  const inline = process.argv.slice(3).join(' ').trim();
+  let message;
+
+  if (inline) {
+    message = inline;
+  } else {
+    const prompter = createPrompter();
+    message = await prompter.ask('What do you want to tell your twin?');
+    prompter.close();
+  }
+
+  if (!message) {
+    console.log('No message provided. Nothing written.');
+    process.exit(0);
+  }
+
+  await writeFile(steerPath, message, 'utf-8');
+
+  const lockPath = resolve(cwd, '.twin-lock');
+  if (existsSync(lockPath)) {
+    console.log('\nGot it. Your twin will pick this up at the next story boundary.\n');
+  } else {
+    console.log('');
+    await build({ maxStories: 1 });
+  }
+}