twin-cli 0.2.1 → 0.3.1

package/README.md

@@ -139,8 +139,10 @@ Runs an autonomous build loop using Claude Code. Each iteration:
 - 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.
@@ -165,6 +167,10 @@ The twin encodes how you think. The project files encode what you are building.
 
 `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
 
 MIT

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.1",
+  "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})
@@ -106,6 +108,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 +127,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 +161,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 +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,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,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`);
 }