twin-cli 0.1.0

package/README.md

@@ -0,0 +1,118 @@
+# Twin-Driven Development
+
+> **Old TDD**: write the tests first. **New TDD**: write the twin first.
+
+A `.twin` file encodes your decision-making DNA — 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's not a project spec. It's **you**.
+
+## The Problem
+
+AI agents have velocity but no vector. They'll do whatever you tell them — but when you stop telling them, they stop. You're not writing code, but you're always on call. Checking at 2am. Writing the next batch. Going back to sleep.
+
+**We call this Vampire Coding.** Technically hands-off. Practically consumed.
+
+The root cause: agents don't know what you *would* build next. They don't have your taste.
+
+## The Solution
+
+Three commands. That's it.
+
+```bash
+twin init     # encode your taste
+twin plan     # your twin decides what to build
+twin build    # your twin builds it
+```
+
+## Prerequisites
+
+- **Node.js 18+** — [nodejs.org](https://nodejs.org)
+- **OpenRouter API key** — [openrouter.ai/keys](https://openrouter.ai/keys) (for `twin init` and `twin plan`)
+- **Claude Code** — [docs.anthropic.com/en/docs/claude-code](https://docs.anthropic.com/en/docs/claude-code) (for `twin build`)
+
+## Quick Start
+
+```bash
+# 1. Set your OpenRouter API key
+export OPENROUTER_API_KEY="your-key-here"
+
+# 2. Create your twin
+npx twin-cli init
+# → Asks your name, then 5 questions about how you build
+# → Generates dru.twin (or whatever your name is)
+
+# 3. Generate your first plan
+npx twin-cli plan
+# → Reads your twin, asks about your product, writes prd.json
+
+# 4. Let your twin build it
+npx twin-cli build
+# → Spawns Claude Code in a loop, builds each story, updates prd.json as it goes
+```
+
+Get an OpenRouter key at [openrouter.ai/keys](https://openrouter.ai/keys).
+
+## The Loop: init → plan → build → plan
+
+This is the core workflow. Your twin drives the whole cycle:
+
+1. **`twin init`** — create your taste profile (once)
+2. **`twin plan`** — your twin generates tasks that match how you'd prioritize
+3. **`twin build`** — your twin builds autonomously, updating prd.json as stories complete
+4. **`twin plan`** again — your twin sees what's done and plans what's next
+
+Each iteration, Claude Code starts fresh but reads the files on disk — your twin, the PRD, and a progress log. The files are the memory. Your taste stays consistent across every iteration.
+
+## Commands
+
+### `twin init`
+Asks your name, then 5 questions about how you build things. Generates `yourname.twin` — your decision-making DNA.
+
+### `twin plan`
+Reads your `.twin` file + project context, generates 3-5 atomic capabilities that match your taste.
+
+Writes **`prd.json`** — structured 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 existing ones.
+
+### `twin build`
+Runs an autonomous build loop using Claude Code. Each iteration:
+- Reads your twin file for taste
+- Reads `prd.json` for open stories
+- Picks the next story to build (the model decides, based on 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
+```
+
+Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and available in your PATH.
+
+## What Goes in a `.twin` File
+
+- **Execution Bias** — do you plan or build first? Ship ugly or wait for polish?
+- **Quality Compass** — how do you define "done"? What does "good" mean to you?
+- **Decision-Making Style** — how do you get unstuck? How do you evaluate tradeoffs?
+- **Strongly Held Beliefs** — what do you believe that others would disagree with?
+- **Anti-Patterns** — what do you refuse to do?
+
+## What Does NOT Go in a `.twin` File
+
+- Your product's target user (that's a product doc)
+- Your tech stack (that's a project config)
+- Your roadmap (that's a PRD)
+
+**The twin encodes how you think. Project files encode what you're building. The twin is the founder. The project files are the company.**
+
+## Philosophy
+
+This project follows the skateboard-to-car model of iterative delivery.
+
+What comes next: `twin tweak` for natural language updates, `twin share` for publishing your taste publicly.
+
+## License
+
+MIT

package/bin/twin.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+import { init } from '../src/init.js';
+import { plan } from '../src/plan.js';
+import { build } from '../src/build.js';
+
+const command = process.argv[2];
+
+function parseFlag(flag, defaultValue) {
+  const idx = process.argv.indexOf(flag);
+  if (idx === -1) return defaultValue;
+  return process.argv[idx + 1];
+}
+
+if (!command || command === 'init') {
+  init();
+} else if (command === 'plan') {
+  plan();
+} else if (command === 'build') {
+  const maxIterations = parseInt(parseFlag('--max-iterations', '5'), 10);
+  build(maxIterations);
+} else if (command === '--help' || command === '-h') {
+  console.log(`
+twin - encode your decision-making DNA
+
+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
+`);
+} else {
+  console.log(`Unknown command: ${command}`);
+  console.log(`Run "twin --help" for usage.`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "twin-cli",
+  "version": "0.1.0",
+  "description": "Encode your decision-making DNA into a .twin file. The .env of taste.",
+  "type": "module",
+  "bin": {
+    "twin": "./bin/twin.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "keywords": [
+    "twin",
+    "taste",
+    "ai",
+    "agent",
+    "decision-making",
+    "vibe-coding"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/build.js

@@ -0,0 +1,238 @@
+import { spawn } from 'node:child_process';
+import { readFile, writeFile, readdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const COMPLETION_SIGNAL = '<twin>STORY_COMPLETE</twin>';
+const ALL_DONE_SIGNAL = '<twin>ALL_COMPLETE</twin>';
+
+async function readIfExists(path) {
+  try {
+    return await readFile(path, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+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');
+    process.exit(1);
+  }
+  return resolve(cwd, twinFiles[0]);
+}
+
+function buildPrompt(twinContent, twinFilename, prdContent, progressContent) {
+  return `You are an autonomous builder working on a software project. You have two sources of truth:
+
+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' : ''}
+## 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.
+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
+
+## Rules
+- 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
+- Do NOT ask questions. Make decisions based on the twin and the PRD.
+
+## Twin file (${twinFilename})
+${twinContent}
+
+## prd.json
+${prdContent}
+${progressContent ? `\n## progress.md\n${progressContent}` : ''}
+`;
+}
+
+function extractTextFromEvent(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
+        .filter((block) => block.type === 'text')
+        .map((block) => block.text)
+        .join('');
+    }
+
+    // Partial streaming text delta
+    if (event.type === 'content_block_delta' && event.delta?.type === 'text_delta') {
+      return event.delta.text;
+    }
+
+    // Result message with text
+    if (event.type === 'result' && event.result) {
+      return null; // Already captured via deltas
+    }
+  } catch {
+    // Not valid JSON or unexpected shape — skip
+  }
+  return null;
+}
+
+function runIteration(prompt, cwd) {
+  return new Promise((resolvePromise) => {
+    const claude = spawn('claude', [
+      '--print',
+      '--dangerously-skip-permissions',
+      '--output-format', 'stream-json',
+    ], {
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env },
+    });
+
+    let output = '';
+    let buffer = '';
+    let hasReceivedText = false;
+
+    // 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)`);
+      }
+    }, 10_000);
+
+    claude.stdout.on('data', (chunk) => {
+      buffer += chunk.toString();
+      const lines = buffer.split('\n');
+      buffer = lines.pop(); // Keep incomplete last line in buffer
+
+      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;
+          }
+          process.stdout.write(text);
+          output += text;
+        }
+      }
+    });
+
+    claude.stderr.on('data', (chunk) => {
+      process.stderr.write(chunk);
+    });
+
+    claude.on('close', (code) => {
+      clearInterval(heartbeat);
+      // Process any remaining buffer
+      if (buffer.trim()) {
+        const text = extractTextFromEvent(buffer.trim());
+        if (text) {
+          process.stdout.write(text);
+          output += text;
+        }
+      }
+      if (!hasReceivedText) {
+        process.stdout.write('\r\x1b[K'); // Clear heartbeat line
+      }
+      resolvePromise({ output, code });
+    });
+
+    claude.on('error', (err) => {
+      clearInterval(heartbeat);
+      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);
+      }
+      console.error(`\nFailed to spawn Claude: ${err.message}\n`);
+      process.exit(1);
+    });
+
+    claude.stdin.write(prompt);
+    claude.stdin.end();
+  });
+}
+
+export async function build(maxIterations = 5) {
+  const cwd = process.cwd();
+
+  // 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');
+    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');
+    process.exit(0);
+  }
+
+  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'));
+
+    const prompt = buildPrompt(twinContent, twinFilename, currentPrd, progressContent);
+    const { output, code } = await runIteration(prompt, cwd);
+
+    if (code !== 0) {
+      console.log(`\nClaude exited with code ${code}. Continuing to next iteration...\n`);
+    }
+
+    // Check completion signals
+    if (output.includes(ALL_DONE_SIGNAL)) {
+      console.log(`\n${'='.repeat(60)}`);
+      console.log('  All stories complete!');
+      console.log(`${'='.repeat(60)}\n`);
+      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)}\n`);
+        break;
+      }
+      console.log(`\nStory complete. ${remaining.length} remaining.\n`);
+    }
+
+    if (i === maxIterations) {
+      console.log(`\nReached max iterations (${maxIterations}). Run \`twin build\` again to continue.\n`);
+    }
+  }
+}

package/src/generate.js

@@ -0,0 +1,57 @@
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { callLLM } from './llm.js';
+
+const SYSTEM_PROMPT = `You are a taste interpreter. You read someone's answers to 5 questions about how they build things, and you produce a .twin file — a Markdown document that encodes their decision-making DNA.
+
+The .twin file has these sections:
+
+# Twin — [Name or "Anonymous"]
+
+## Execution Bias
+- Speed vs polish preference
+- How they start things
+- Shipping philosophy
+
+## Quality Compass
+- How they define "done"
+- What "good" means to them
+- Standards they hold
+
+## Decision-Making Style
+- How they get unstuck
+- How they evaluate tradeoffs
+- Instincts and heuristics
+
+## Strongly Held Beliefs
+- Contrarian views
+- Things they refuse to do
+- Non-negotiable principles
+
+## Anti-Patterns
+- Things to avoid
+- Red flags they watch for
+- Patterns they reject
+
+Rules:
+- Write in second person ("You prefer...", "You believe...")
+- Be specific and opinionated, not generic
+- Use their actual words and phrasings when possible
+- Each bullet should be a concrete, actionable heuristic — not a vague platitude
+- If they didn't give enough signal for a section, write fewer bullets rather than making things up
+- Keep it under 80 lines total
+- No preamble, no explanation — just the .twin file content`;
+
+export async function generateTwin(apiKey, name, interviewText) {
+  const content = await callLLM(
+    apiKey,
+    SYSTEM_PROMPT,
+    `The builder's name is ${name}.\n\nHere are the interview answers. Generate the .twin file.\n\n${interviewText}`,
+  );
+
+  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('\nDrop this file into any project and your AI tools will know your taste.');
+}

package/src/init.js

@@ -0,0 +1,39 @@
+import { requireKey, checkKey } from './llm.js';
+import { createPrompter } from './prompt.js';
+import { generateTwin } from './generate.js';
+
+const QUESTIONS = [
+  "When you start something new, do you plan first or build first?",
+  "Do you ship something ugly that works, or wait until it's polished?",
+  "How do you know when something is done?",
+  "Describe something you built or created that you're proud of. What made it good?",
+  "What do you believe about building things that most people would disagree with?",
+];
+
+export async function init() {
+  const key = requireKey();
+
+  console.log('\nChecking API connection...');
+  await checkKey(key);
+  console.log('Connected.\n');
+
+  console.log('--- twin init ---');
+  console.log('Answer a few questions. Say as much or as little as you want.');
+  console.log('Your answers will be used to generate your .twin file.\n');
+
+  const prompter = createPrompter();
+
+  const name = await prompter.ask('What should we call you? (First name is fine.)');
+
+  const answers = [];
+  for (const q of QUESTIONS) {
+    const answer = await prompter.ask(q);
+    answers.push({ question: q, answer });
+  }
+  prompter.close();
+
+  console.log('\nGenerating your .twin file...\n');
+
+  const paired = answers.map((a) => `Q: ${a.question}\nA: ${a.answer}`).join('\n\n');
+  await generateTwin(key, name, paired);
+}

package/src/llm.js

@@ -0,0 +1,59 @@
+export function requireKey() {
+  const key = process.env.OPENROUTER_API_KEY;
+  if (!key) {
+    console.log('\nSet your OpenRouter API key first:');
+    console.log('  export OPENROUTER_API_KEY="your-key-here"');
+    console.log('\nGet one at https://openrouter.ai/keys\n');
+    process.exit(1);
+  }
+  return key;
+}
+
+export async function checkKey(key) {
+  try {
+    const res = await fetch('https://openrouter.ai/api/v1/models', {
+      headers: { 'Authorization': `Bearer ${key}` },
+    });
+    if (!res.ok) {
+      console.error(`\nAPI key check failed (${res.status}). Make sure your OPENROUTER_API_KEY is valid.`);
+      console.log('Get one at https://openrouter.ai/keys\n');
+      process.exit(1);
+    }
+  } catch (e) {
+    console.error('\nCould not connect to OpenRouter. Check your internet connection.\n');
+    process.exit(1);
+  }
+}
+
+export async function callLLM(apiKey, systemPrompt, userMessage) {
+  const res = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      model: 'google/gemini-3-flash-preview',
+      messages: [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: userMessage },
+      ],
+    }),
+  });
+
+  if (!res.ok) {
+    const err = await res.text();
+    console.error(`OpenRouter API error (${res.status}): ${err}`);
+    process.exit(1);
+  }
+
+  const data = await res.json();
+  const content = data.choices?.[0]?.message?.content;
+
+  if (!content) {
+    console.error('No content returned from API.');
+    process.exit(1);
+  }
+
+  return content;
+}

package/src/plan.js

@@ -0,0 +1,154 @@
+import { readFile, writeFile, readdir } from 'node:fs/promises';
+import { resolve, basename } from 'node:path';
+import { requireKey, checkKey, callLLM } from './llm.js';
+import { createPrompter } from './prompt.js';
+
+const TASK_SYSTEM_PROMPT = `You are a taste-aware product planner. You receive:
+1. A .twin file — the builder's decision-making DNA (how they think, what they value)
+2. A product.md — what they're building, for whom, and where it stands
+3. Optionally, a status.md — recent progress
+4. Optionally, an existing prd.json — stories already planned (avoid duplicating these)
+
+Your job: generate 3-5 atomic capabilities — things a user can DO after they're built. Not stubs, not refactors, not "set up X." Real, demoable features.
+
+Rules:
+- Match the builder's taste. If they ship fast, suggest quick wins. If they want polish, suggest completeness.
+- Order by priority — most impactful first
+- Use plain language, no jargon
+- Do NOT duplicate anything already in the existing tasks
+
+You MUST respond with valid JSON only. No markdown, no code fences, no explanation. Just the JSON object.
+
+Schema:
+{
+  "project": "short project name",
+  "description": "one-line project description",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "short capability title",
+      "description": "As a [user], I can [do thing] so that [value].",
+      "acceptanceCriteria": ["criterion 1", "criterion 2"],
+      "status": "open",
+      "whyNow": "one sentence: why this is the right next thing"
+    }
+  ]
+}
+
+Every story MUST have "status": "open". Do not include priority numbers — ordering in the array IS the priority.`;
+
+async function readIfExists(path) {
+  try {
+    return await readFile(path, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+async function bootstrapProduct() {
+  console.log('\nNo product.md found. Let\'s set up your project context.\n');
+
+  const prompter = createPrompter();
+
+  const what = await prompter.ask('What are you building?');
+  const who = await prompter.ask('Who is it for?');
+  prompter.close();
+
+  const content = `# Product\n\n## What\n${what}\n\n## Who\n${who}\n`;
+
+  const outPath = resolve(process.cwd(), 'product.md');
+  await writeFile(outPath, content, 'utf-8');
+  console.log(`\nWrote ${outPath}`);
+  return content;
+}
+
+function parseLLMJson(raw) {
+  // Strip markdown code fences if the LLM wraps its response
+  let cleaned = raw.trim();
+  if (cleaned.startsWith('```')) {
+    cleaned = cleaned.replace(/^```(?:json)?\s*\n?/, '').replace(/\n?```\s*$/, '');
+  }
+  return JSON.parse(cleaned);
+}
+
+export async function plan() {
+  const key = requireKey();
+
+  console.log('\nChecking API connection...');
+  await checkKey(key);
+  console.log('Connected.\n');
+
+  // 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 `twin init` first.\n');
+    process.exit(1);
+  }
+  if (twinFiles.length > 1) {
+    console.log(`Found multiple .twin files: ${twinFiles.join(', ')}. Using ${twinFiles[0]}.`);
+  }
+  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();
+  }
+
+  // Read optional context files
+  const statusPath = resolve(process.cwd(), 'status.md');
+  const prdPath = resolve(process.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}`;
+  }
+  if (existingPrd) {
+    userMessage += `\n\n## Existing prd.json (do NOT duplicate these stories)\n${existingPrd}`;
+  }
+  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(key, TASK_SYSTEM_PROMPT, userMessage);
+
+  // 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);
+  }
+
+  // Derive project name from cwd if LLM didn't provide one
+  if (!prd.project) {
+    prd.project = basename(process.cwd());
+  }
+
+  // Write prd.json
+  await writeFile(prdPath, JSON.stringify(prd, null, 2) + '\n', 'utf-8');
+
+  // Print stories to console
+  for (const story of prd.userStories) {
+    console.log(`${story.id}. ${story.title}`);
+    console.log(`   ${story.description}`);
+    for (const ac of story.acceptanceCriteria) {
+      console.log(`   - ${ac}`);
+    }
+    console.log('');
+  }
+  console.log(`---`);
+  console.log(`Wrote ${prdPath}`);
+  console.log(`\nRun \`twin build\` to start building.`);
+}

package/src/prompt.js

@@ -0,0 +1,63 @@
+import * as readline from 'node:readline';
+
+const INPUT_TIMEOUT_MS = 1500;
+
+export function createPrompter() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  async function ask(question) {
+    console.log(`\n${question}`);
+
+    const lines = [];
+    let timer = null;
+
+    return new Promise((resolve) => {
+      const finish = () => {
+        rl.removeListener('line', onLine);
+        resolve(lines.join(' ').trim());
+      };
+
+      const resetTimer = () => {
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(finish, INPUT_TIMEOUT_MS);
+      };
+
+      const onLine = (line) => {
+        const trimmed = line.trim();
+        if (trimmed !== '') {
+          lines.push(trimmed);
+        }
+        // If we have content, start/reset the timeout
+        if (lines.length > 0) {
+          resetTimer();
+        }
+      };
+
+      process.stdout.write('> ');
+      rl.on('line', onLine);
+
+      // For single-line answers (keyboard), also resolve on first Enter after content
+      // But give a moment for more lines to arrive (paste/voice)
+    });
+  }
+
+  // Drain any leftover input between questions
+  async function drain() {
+    return new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  async function askAndDrain(question) {
+    const answer = await ask(question);
+    await drain();
+    return answer;
+  }
+
+  function close() {
+    rl.close();
+  }
+
+  return { ask: askAndDrain, close };
+}