twin-cli 0.2.0 → 0.2.1

package/README.md

@@ -2,30 +2,32 @@
 
 Old TDD meant write the tests first. New TDD means write the twin first.
 
-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 is not a project spec. It is 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 do what you tell them. When you stop telling them, they stop.
+You give an agent a task list. It finishes. It stops. Now you have to decide what comes next.
 
-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.
+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.
 
 This is Vampire Coding. Hands-off in theory. Consumed in practice.
 
-The root cause: agents do not know what you would build next. They do not have your taste.
+The root cause: agents do not know what you would build next. They can execute. They cannot decide.
 
 ## The Fix
 
 Three commands.
 
 ```
-twin init     # encode your taste
-twin plan     # your twin decides what to build
-twin build    # your twin builds it
+twin init     # encode how you think
+twin plan     # your twin decides what to build next
+twin build    # your twin builds it without you
 ```
 
+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)
@@ -33,13 +35,13 @@ twin build    # your twin builds it
 
 ## Quick Start
 
-Every twin project starts in its own folder. Create one, then run the commands from inside it.
+Each twin project starts in its own folder. Create one, then run from inside it.
 
 ```bash
 # 0. Create a project folder
 mkdir my-app && cd my-app
 
-# 1. Create your twin (only need to do this once)
+# 1. Create your twin (once)
 npx twin-cli init
 # → Asks your name, then 5 questions about how you build
 # → Generates yourname.twin
@@ -56,7 +58,7 @@ npx twin-cli build
 
 ## Example: Building a Habit Tracker
 
-Here is a full walkthrough from zero to working app.
+A full walkthrough from zero to working app.
 
 ```bash
 # Create the project
@@ -92,22 +94,24 @@ Your `.twin` file is portable. Copy it into any new project and run `twin plan`
 
 Twin works best on new projects. Some things to try:
 
-- **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
+- 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
 
 ## The Loop
 
 `init → plan → build → plan`
 
-This is the core cycle. Your twin drives the whole thing.
+Your twin drives the whole cycle.
 
-1. **`twin init`** — create your taste profile (once)
+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 plans what comes next
+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.
 
@@ -119,7 +123,7 @@ Asks your name, then 5 questions about how you build things. Generates `yourname
 
 ### `twin plan`
 
-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.
+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 old ones.
 
@@ -127,9 +131,9 @@ If no `product.md` exists, `twin plan` asks 2 quick questions to set up your pro
 
 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, guided by 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
@@ -146,7 +150,7 @@ Requires Claude Code installed and available in your PATH.
 - **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?
+- **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
@@ -159,7 +163,7 @@ The twin encodes how you think. The project files encode what you are building.
 
 ## What Comes Next
 
-`twin tweak` for natural language updates. `twin share` for publishing your taste.
+`twin tweak` for natural language updates. `twin share` for publishing your taste publicly.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twin-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Your twin builds while you sleep. Not human in the loop. Twin in the loop.",
   "type": "module",
   "bin": {

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 });
     });
 

package/src/plan.js

@@ -130,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');