twin-cli 0.1.0 → 0.2.0

package/README.md

@@ -1,85 +1,135 @@
 # 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.
+A `.twin` file is your decision-making source code. Your taste. Your biases. Your heuristics. Drop it into any project and your AI tools make decisions the way you would.
 
-The twin is not a PRD. It's not a project spec. It's **you**.
+The twin is not a PRD. It is not a project spec. It is 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.
+AI agents have velocity but no vector. They do what you tell them. When you stop telling them, they stop.
 
-**We call this Vampire Coding.** Technically hands-off. Practically consumed.
+You are not writing code. But you are checking at 2am. Writing the next batch of tasks. Going back to sleep. Waking at 5am to check again.
 
-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 do not have your taste.
 
-Three commands. That's it.
+## The Fix
 
-```bash
+Three commands.
+
+```
 twin init     # encode your taste
 twin plan     # your twin decides what to build
 twin build    # your twin builds it
 ```
 
-## Prerequisites
+## 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
 
+Every twin project starts in its own folder. Create one, then run the commands 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 (only need to do this 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
+
+Here is 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 manually
+- **PWA** that replaces a spreadsheet you use every day
 
-This is the core workflow. Your twin drives the whole cycle:
+## The Loop
+
+`init → plan → build → plan`
+
+This is the core cycle. Your twin drives the whole thing.
 
 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
+2. **`twin plan`** — your twin generates tasks that match how you prioritize
+3. **`twin build`** — your twin builds on its own, updating `prd.json` as stories complete
+4. **`twin plan` again** — your twin reads what shipped and plans what comes next
 
-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.
+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 atomic 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 `prd.json` for open stories
-- Picks the next story to build (the model decides, based on your taste)
+- Picks the next story to build (the model decides, 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 +139,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 people 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.
 
 ## 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.0",
+  "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

@@ -214,7 +214,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 +227,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;