twin-cli 0.3.1 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 Old TDD meant write the tests first. New TDD means write the twin first.
 
-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.
+A `.twin` file is the `.env` for your taste. 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
 
@@ -18,8 +18,8 @@ The root cause: agents do not know what you would build next. They can execute.
 
 Three commands.
 
-```
-twin init     # encode how you think
+```bash
+twin init     # your taste, in a file
 twin plan     # your twin decides what to build next
 twin build    # your twin builds it without you
 ```
@@ -33,6 +33,8 @@ Run `twin plan` once and you get the next batch of features you would have chose
 - **Node.js 18+** — [nodejs.org](https://nodejs.org)
 - **Claude Code** — [docs.anthropic.com](https://docs.anthropic.com/en/docs/claude-code) (powers all three commands)
 
+Run everything with `npx twin-cli` — no global install needed. This keeps you on the latest version automatically.
+
 ## Quick Start
 
 Each twin project starts in its own folder. Create one, then run from inside it.
@@ -82,13 +84,13 @@ npx twin-cli build
 # → Picks the next story, builds it, marks it done
 # → You watch it happen in real time
 
-# Want more features? Plan again.
+# Want more? Plan again.
 npx twin-cli plan
 # → Sees what is done, generates the next batch
 npx twin-cli build
 ```
 
-Your `.twin` file is portable. Copy it into any new project and run `twin plan` to start.
+Your `.twin` file is portable. Copy it into any new project and run `npx twin-cli plan` to start.
 
 ## Project Ideas
 
@@ -106,12 +108,12 @@ Twin works best on new projects. Some things to try:
 
 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
+1. **`twin init`** — your taste, in a file (once)
+2. **`twin plan`** — your twin generates the next batch of stories, matched to 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.
+You did not write a task list. Your twin wrote it. You did not pick the next feature. Your twin picked it.
 
 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 +121,7 @@ Each iteration, Claude Code starts fresh but reads the files on disk. Your twin.
 
 ### `twin init`
 
-Asks your name, then 5 questions about how you build things. Generates `yourname.twin`.
+Asks your name, then 5 questions about how you build. Generates `yourname.twin`.
 
 ### `twin plan`
 
@@ -136,17 +138,29 @@ Runs an autonomous build loop using Claude Code. Each iteration:
 - 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
+- Repeats until all stories are done or the story limit is hit
 
 ```bash
-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
+npx twin-cli build                       # build the current stories (default: 3)
+npx twin-cli build --loop                # build, plan, build — fully autonomous
+npx twin-cli build --loop --stories 20   # stop after 20 stories
+npx twin-cli build --loop --minutes 30   # stop after 30 minutes
 ```
 
 Requires Claude Code installed and available in your PATH.
 
+### `twin steer`
+
+You have something to say but don't want to write a user story yourself. Just say it:
+
+```bash
+twin steer "I want users to be able to share their progress on Twitter"
+```
+
+Or run `twin steer` with no arguments to type or dictate a longer message.
+
+Your twin turns it into stories in `prd.json` and updates your `.twin` file with anything it can infer about your taste. Works any time — before a build, between runs, or from a second terminal while a build is running.
+
 ## What Goes in a `.twin` File
 
 - **Execution bias** — do you plan first or build first? Ship rough or wait for polish?
@@ -161,11 +175,7 @@ Requires Claude Code installed and available in your PATH.
 - Your tech stack (that goes in project config)
 - Your roadmap (that goes in a PRD)
 
-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.
-
-## What Comes Next
-
-`twin tweak` for natural language updates. `twin share` for publishing your taste publicly.
+The twin holds your taste. The project files hold what you are building. The twin is the founder. The project files are the company.
 
 ## Notes
 

package/bin/twin.js

@@ -3,6 +3,7 @@
 import { init } from '../src/init.js';
 import { plan } from '../src/plan.js';
 import { build } from '../src/build.js';
+import { steer } from '../src/steer.js';
 
 const command = process.argv[2];
 
@@ -23,6 +24,8 @@ if (!command || command === 'init') {
   const maxStories = storiesFlag ? parseInt(storiesFlag, 10) : (loop ? Infinity : 3);
   const maxMinutes = minutesFlag ? parseInt(minutesFlag, 10) : null;
   build({ maxStories, loop, maxMinutes });
+} else if (command === 'steer') {
+  steer();
 } else if (command === '--help' || command === '-h') {
   console.log(`
 twin - your twin builds while you sleep
@@ -34,6 +37,7 @@ Usage:
   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 steer [message]       Tell your twin what to build next
   twin --help                Show this message
 `);
 } else {

package/package.json

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

package/src/build.js

@@ -1,7 +1,9 @@
 import { spawn } from 'node:child_process';
 import { readFile, writeFile, readdir } from 'node:fs/promises';
+import { unlinkSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { runPlan } from './plan.js';
+import { callLLM } from './llm.js';
 
 const COMPLETION_SIGNAL = '<twin>STORY_COMPLETE</twin>';
 const ALL_DONE_SIGNAL = '<twin>ALL_COMPLETE</twin>';
@@ -218,6 +220,84 @@ const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
 const bar = dim('─'.repeat(60));
 
+async function processSteer(cwd, twinPath, prdPath) {
+  const steerPath = resolve(cwd, 'steer.md');
+  const steerContent = await readIfExists(steerPath);
+  if (!steerContent?.trim()) return;
+
+  const twinContent = await readFile(twinPath, 'utf-8');
+  const twinFilename = twinPath.split('/').pop();
+  const prdContent = await readFile(prdPath, 'utf-8');
+  const prd = JSON.parse(prdContent);
+
+  const maxNum = prd.userStories.reduce((max, s) => {
+    const m = s.id?.match(/\d+/);
+    return m ? Math.max(max, parseInt(m[0], 10)) : max;
+  }, 0);
+  const nextId = `US-${String(maxNum + 1).padStart(3, '0')}`;
+
+  // Send trimmed prd (id + title + status only) to reduce token count
+  const prdSummary = prd.userStories
+    .map((s) => `${s.id}: ${s.title} (${s.status})`)
+    .join('\n');
+
+  const result = await callLLM(
+    'You process developer steering input for a build loop. Output valid JSON only — no prose, no markdown fences.',
+    [
+      'Steering input from developer:',
+      steerContent,
+      '',
+      `Existing stories:\n${prdSummary}`,
+      '',
+      `${twinFilename}:\n${twinContent}`,
+      '',
+      `Next available story id: ${nextId} (increment for each additional story)`,
+      '',
+      'Output JSON with this exact shape:',
+      '{',
+      '  "newStories": [],    // stories to add to prd.json (id, title, userStory, acceptanceCriteria array, status:"open"), empty array if none',
+      '  "twinAppend": null   // text to append to the twin file if this input reveals something clear about the developer\'s taste, or null if nothing clear can be inferred',
+      '}',
+    ].join('\n')
+  );
+
+  let json;
+  try {
+    json = JSON.parse(result.replace(/^```(?:json)?\n?/m, '').replace(/\n?```$/m, '').trim());
+  } catch {
+    console.log(dim('  steer: could not parse response, skipping.'));
+    return;
+  }
+
+  if (json.newStories?.length > 0) {
+    prd.userStories.push(...json.newStories);
+    await writeFile(prdPath, JSON.stringify(prd, null, 2), 'utf-8');
+    console.log('');
+    for (const s of json.newStories) {
+      console.log(dim('  + ') + `${s.id}  ${s.title}`);
+    }
+  }
+
+  if (json.twinAppend) {
+    const current = await readFile(twinPath, 'utf-8');
+    await writeFile(twinPath, current.trimEnd() + '\n\n' + json.twinAppend + '\n', 'utf-8');
+    console.log(dim(`  Updated ${twinFilename}`));
+  }
+
+  // Clear steer.md so it isn't re-processed next cycle
+  await writeFile(steerPath, '', 'utf-8');
+}
+
+async function logPriorityJustification(twinContent, prdContent, storyNum, synthesisPath) {
+  const justification = await callLLM(
+    'You are a prioritization oracle. Answer in 1-3 sentences only. No preamble.',
+    `Twin file:\n${twinContent}\n\nprd.json:\n${prdContent}\n\nIf you could only ship one story this cycle, which would it be and why? Reference the twin file reasoning explicitly.`
+  );
+  const existing = await readIfExists(synthesisPath) || '';
+  const entry = `\n## Story ${storyNum} — ${new Date().toISOString()}\n\n**Priority justification:** ${justification}\n`;
+  await writeFile(synthesisPath, existing + entry, 'utf-8');
+}
+
 const STORY_RETRIES = 2;
 const STORY_RETRY_DELAYS = [10_000, 30_000]; // 10s, then 30s
 
@@ -225,6 +305,28 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 
+// Show an overwriting status line while an async operation runs, then clear it.
+// msg can be a string, or an array of [afterSeconds, message] milestones.
+async function withStatus(msg, fn) {
+  const milestones = Array.isArray(msg)
+    ? msg.slice().sort((a, b) => a[0] - b[0])
+    : [[0, msg]];
+  const start = Date.now();
+  let shown = false;
+  const timer = setInterval(() => {
+    const elapsed = Math.round((Date.now() - start) / 1000);
+    const current = milestones.filter(([s]) => elapsed >= s).pop()[1];
+    process.stdout.write(`\r${dim(`${current} (${elapsed}s)`)}`);
+    shown = true;
+  }, 3_000);
+  try {
+    return await fn();
+  } finally {
+    clearInterval(timer);
+    if (shown) process.stdout.write('\r\x1b[K');
+  }
+}
+
 function summary(totalBuilt, cycles, elapsed) {
   const mins = Math.round(elapsed / 60000);
   const time = mins > 0 ? ` in ${mins}m` : '';
@@ -237,6 +339,11 @@ export async function build({ maxStories = 3, loop = false, maxMinutes = null }
   const startTime = Date.now();
   const timeLimitMs = maxMinutes ? maxMinutes * 60 * 1000 : null;
 
+  // Write lock file so twin steer knows a build is running
+  const lockPath = resolve(cwd, '.twin-lock');
+  await writeFile(lockPath, String(process.pid), 'utf-8');
+  process.on('exit', () => { try { unlinkSync(lockPath); } catch {} });
+
   // Clean exit on Ctrl+C — finish current story, then stop
   let stopping = false;
   process.on('SIGINT', () => {
@@ -261,7 +368,9 @@ export async function build({ maxStories = 3, loop = false, maxMinutes = null }
   const prd = JSON.parse(prdContent);
   const openStories = prd.userStories.filter((s) => s.status !== 'done');
   if (openStories.length === 0 && !loop) {
-    console.log('All stories are done. Plan the next batch:\n  npx twin-cli plan\n');
+    console.log('All stories are done.\n');
+    console.log('  npx twin-cli plan             # plan the next batch, then build');
+    console.log('  npx twin-cli build --loop     # plan and build automatically\n');
     process.exit(0);
   }
   // In loop mode with no open stories, the while loop will trigger planning
@@ -299,7 +408,15 @@ export async function build({ maxStories = 3, loop = false, maxMinutes = null }
     // 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)
+    // Process any steering input before deciding what to build next
+    await withStatus([
+      [0,   'Applying your steer...'],
+      [20,  'Still working...'],
+      [60,  'Your message is detailed — taking a moment...'],
+      [120, 'Almost there...'],
+    ], () => processSteer(cwd, twinPath, prdPath)).catch(() => {});
+
+    // Re-read prd.json (steer or previous story 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');
@@ -312,8 +429,8 @@ export async function build({ maxStories = 3, loop = false, maxMinutes = null }
         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');
+        console.log('\n  npx twin-cli plan             # plan the next batch, then build');
+        console.log('  npx twin-cli build --loop     # plan and build automatically\n');
         break;
       }
 
@@ -321,11 +438,10 @@ export async function build({ maxStories = 3, loop = false, maxMinutes = null }
       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);
+      const newStories = await withStatus('Planning...', () => runPlan(cwd));
 
       if (newStories.length === 0) {
         console.log(bar);
@@ -370,6 +486,12 @@ export async function build({ maxStories = 3, loop = false, maxMinutes = null }
     console.log('');
 
     const progressContent = await readIfExists(resolve(cwd, 'progress.md'));
+
+    // Log priority justification to synthesis.md before building
+    await withStatus('Thinking...', () =>
+      logPriorityJustification(twinContent, currentPrdContent, storyNum, resolve(cwd, 'synthesis.md'))
+    ).catch(() => {});
+
     const prompt = buildPrompt(twinContent, twinFilename, currentPrdContent, progressContent);
 
     let succeeded = false;
@@ -413,7 +535,8 @@ export async function build({ maxStories = 3, loop = false, maxMinutes = null }
     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('\n  npx twin-cli build            # keep building');
+      console.log('  npx twin-cli build --loop     # build and plan automatically\n');
     }
     console.log('');
   }

package/src/plan.js

@@ -204,5 +204,6 @@ export async function plan() {
   console.log(`---`);
   console.log(`Wrote ${prdPath}`);
   console.log(`\nNext step — let your twin build it:`);
-  console.log(`  npx twin-cli build`);
+  console.log(`  npx twin-cli build            # build the next 3 stories`);
+  console.log(`  npx twin-cli build --loop     # build and plan automatically`);
 }

package/src/steer.js

@@ -0,0 +1,37 @@
+import { writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createPrompter } from './prompt.js';
+import { build } from './build.js';
+
+export async function steer() {
+  const cwd = process.cwd();
+  const steerPath = resolve(cwd, 'steer.md');
+
+  // Accept message as inline args or fall back to interactive prompt
+  const inline = process.argv.slice(3).join(' ').trim();
+  let message;
+
+  if (inline) {
+    message = inline;
+  } else {
+    const prompter = createPrompter();
+    message = await prompter.ask('What do you want to tell your twin?');
+    prompter.close();
+  }
+
+  if (!message) {
+    console.log('No message provided. Nothing written.');
+    process.exit(0);
+  }
+
+  await writeFile(steerPath, message, 'utf-8');
+
+  const lockPath = resolve(cwd, '.twin-lock');
+  if (existsSync(lockPath)) {
+    console.log('\nGot it. Your twin will pick this up at the next story boundary.\n');
+  } else {
+    console.log('');
+    await build({ maxStories: 1 });
+  }
+}