twin-cli 0.1.0 → 0.2.1

package/README.md

@@ -1,85 +1,139 @@
 # Twin-Driven Development
 
-> **Old TDD**: write the tests first. **New TDD**: write the twin first.
+Old TDD meant write the tests first. New TDD means 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**.
+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'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.
+You give an agent a task list. It finishes. It stops. Now you have to decide what comes next.
 
-**We call this Vampire Coding.** Technically hands-off. Practically consumed.
+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.
 
-The root cause: agents don't know what you *would* build next. They don't have your taste.
+This is Vampire Coding. Hands-off in theory. Consumed in practice.
 
-## The Solution
+The root cause: agents do not know what you would build next. They can execute. They cannot decide.
 
-Three commands. That's it.
+## The Fix
 
-```bash
-twin init     # encode your taste
-twin plan     # your twin decides what to build
-twin build    # your twin builds it
+Three commands.
+
+```
+twin init     # encode how you think
+twin plan     # your twin decides what to build next
+twin build    # your twin builds it without you
 ```
 
-## Prerequisites
+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)
-- **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`)
+- **Claude Code** — [docs.anthropic.com](https://docs.anthropic.com/en/docs/claude-code) (powers all three commands)
 
 ## Quick Start
 
+Each twin project starts in its own folder. Create one, then run from inside it.
+
 ```bash
-# 1. Set your OpenRouter API key
-export OPENROUTER_API_KEY="your-key-here"
+# 0. Create a project folder
+mkdir my-app && cd my-app
 
-# 2. Create your twin
+# 1. Create your twin (once)
 npx twin-cli init
 # → Asks your name, then 5 questions about how you build
-# → Generates dru.twin (or whatever your name is)
+# → Generates yourname.twin
 
-# 3. Generate your first plan
+# 2. Generate your first plan
 npx twin-cli plan
 # → Reads your twin, asks about your product, writes prd.json
 
-# 4. Let your twin build it
+# 3. Let your twin build
+npx twin-cli build
+# → Spawns Claude Code in a loop
+# → Builds each story, updates prd.json as it goes
+```
+
+## Example: Building a Habit Tracker
+
+A full walkthrough from zero to working app.
+
+```bash
+# Create the project
+mkdir habit-tracker && cd habit-tracker
+
+# Create your twin
+npx twin-cli init
+# → "What should we call you?" → Dru
+# → Answer 5 questions about how you build
+# → Generates dru.twin
+
+# Generate the plan
+npx twin-cli plan
+# → "What are you building?" → A habit app with GitHub-style tracking and timers
+# → "Who is it for?" → People who want to build daily habits
+# → Writes prd.json with 3-5 user stories based on YOUR taste
+
+# Build it
+npx twin-cli build
+# → Claude picks the first story, builds it, marks it done
+# → Picks the next story, builds it, marks it done
+# → You watch it happen in real time
+
+# Want more features? Plan again.
+npx twin-cli plan
+# → Sees what is done, generates the next batch
 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).
+Your `.twin` file is portable. Copy it into any new project and run `twin plan` to start.
+
+## Project Ideas
+
+Twin works best on new projects. Some things to try:
 
-## The Loop: init → plan → build → plan
+- 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
 
-This is the core workflow. Your twin drives the whole cycle:
+## The Loop
 
-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
+`init → plan → build → plan`
 
-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.
+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
+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.
+
+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.
 
 ## Commands
 
 ### `twin init`
-Asks your name, then 5 questions about how you build things. Generates `yourname.twin` — your decision-making DNA.
+
+Asks your name, then 5 questions about how you build things. Generates `yourname.twin`.
 
 ### `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.
+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 existing ones.
+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.
 
 ### `twin build`
+
 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, based on 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
@@ -89,29 +143,27 @@ 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.
+Requires 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?
+- **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 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.**
+- Your product's target user (that goes in a product doc)
+- Your tech stack (that goes in project config)
+- Your roadmap (that goes in a PRD)
 
-## Philosophy
+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.
 
-This project follows the skateboard-to-car model of iterative delivery.
+## What Comes Next
 
-What comes next: `twin tweak` for natural language updates, `twin share` for publishing your taste publicly.
+`twin tweak` for natural language updates. `twin share` for publishing your taste publicly.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "twin-cli",
-  "version": "0.1.0",
-  "description": "Encode your decision-making DNA into a .twin file. The .env of taste.",
+  "version": "0.2.1",
+  "description": "Your twin builds while you sleep. Not human in the loop. Twin in the loop.",
   "type": "module",
   "bin": {
     "twin": "./bin/twin.js"

package/src/build.js

@@ -56,27 +56,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 +104,41 @@ 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
+
+    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) {
+      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 +147,20 @@ 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;
-          }
-          process.stdout.write(text);
-          output += text;
+        const event = parseEvent(line);
+        if (!event) continue;
+
+        lastActivity = Date.now();
+
+        if (event.type === 'text') {
+          clearStatus();
+          process.stdout.write(event.text);
+          output += event.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 +171,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 });
     });
 
@@ -214,7 +248,9 @@ export async function build(maxIterations = 5) {
     if (output.includes(ALL_DONE_SIGNAL)) {
       console.log(`\n${'='.repeat(60)}`);
       console.log('  All stories complete!');
-      console.log(`${'='.repeat(60)}\n`);
+      console.log(`${'='.repeat(60)}`);
+      console.log('\nNext step — plan more features:');
+      console.log('  twin plan\n');
       break;
     }
 
@@ -225,7 +261,9 @@ export async function build(maxIterations = 5) {
       if (remaining.length === 0) {
         console.log(`\n${'='.repeat(60)}`);
         console.log('  All stories complete!');
-        console.log(`${'='.repeat(60)}\n`);
+        console.log(`${'='.repeat(60)}`);
+        console.log('\nNext step — plan more features:');
+        console.log('  twin plan\n');
         break;
       }
       console.log(`\nStory complete. ${remaining.length} remaining.\n`);

package/src/generate.js

@@ -42,9 +42,8 @@ Rules:
 - Keep it under 80 lines total
 - No preamble, no explanation — just the .twin file content`;
 
-export async function generateTwin(apiKey, name, interviewText) {
+export async function generateTwin(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}`,
   );
@@ -53,5 +52,6 @@ export async function generateTwin(apiKey, name, interviewText) {
   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.');
+  console.log('\nNext step — plan what to build:');
+  console.log('  twin plan');
 }

package/src/init.js

@@ -1,4 +1,3 @@
-import { requireKey, checkKey } from './llm.js';
 import { createPrompter } from './prompt.js';
 import { generateTwin } from './generate.js';
 
@@ -11,13 +10,7 @@ const QUESTIONS = [
 ];
 
 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('\n--- 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');
 
@@ -35,5 +28,5 @@ export async function init() {
   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);
+  await generateTwin(name, paired);
 }

package/src/llm.js

@@ -1,59 +1,52 @@
-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;
-}
+import { spawn } from 'node:child_process';
 
-export async function checkKey(key) {
-  try {
-    const res = await fetch('https://openrouter.ai/api/v1/models', {
-      headers: { 'Authorization': `Bearer ${key}` },
+export async function callLLM(systemPrompt, userMessage) {
+  const prompt = `${systemPrompt}\n\n${userMessage}`;
+
+  const output = await new Promise((resolve, reject) => {
+    const claude = spawn('claude', ['--print'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env },
     });
-    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 },
-      ],
-    }),
-  });
+    let stdout = '';
+    let stderr = '';
 
-  if (!res.ok) {
-    const err = await res.text();
-    console.error(`OpenRouter API error (${res.status}): ${err}`);
-    process.exit(1);
-  }
+    claude.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+
+    claude.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+
+    claude.on('close', (code) => {
+      if (code !== 0) {
+        console.error(`Claude Code exited with code ${code}.`);
+        if (stderr) console.error(stderr);
+        process.exit(1);
+      }
+      resolve(stdout.trim());
+    });
 
-  const data = await res.json();
-  const content = data.choices?.[0]?.message?.content;
+    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);
+      }
+      console.error(`\nFailed to spawn Claude: ${err.message}\n`);
+      process.exit(1);
+    });
+
+    claude.stdin.write(prompt);
+    claude.stdin.end();
+  });
 
-  if (!content) {
-    console.error('No content returned from API.');
+  if (!output) {
+    console.error('No content returned from Claude Code.');
     process.exit(1);
   }
 
-  return content;
+  return output;
 }

package/src/plan.js

@@ -1,6 +1,6 @@
 import { readFile, writeFile, readdir } from 'node:fs/promises';
 import { resolve, basename } from 'node:path';
-import { requireKey, checkKey, callLLM } from './llm.js';
+import { callLLM } from './llm.js';
 import { createPrompter } from './prompt.js';
 
 const TASK_SYSTEM_PROMPT = `You are a taste-aware product planner. You receive:
@@ -72,12 +72,6 @@ function parseLLMJson(raw) {
 }
 
 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);
@@ -119,7 +113,7 @@ export async function plan() {
   console.log('--- twin plan ---');
   console.log('Generating tasks that match your taste...\n');
 
-  const raw = await callLLM(key, TASK_SYSTEM_PROMPT, userMessage);
+  const raw = await callLLM(TASK_SYSTEM_PROMPT, userMessage);
 
   // Parse structured output
   let prd;
@@ -136,6 +130,19 @@ export async function plan() {
     prd.project = basename(process.cwd());
   }
 
+  // Merge with existing stories if prd.json already exists
+  if (existingPrd) {
+    try {
+      const existing = JSON.parse(existingPrd);
+      const existingStories = existing.userStories || [];
+      prd.userStories = [...existingStories, ...prd.userStories];
+      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');