writethevision 7.0.6 → 7.0.8

package/README.md

@@ -296,9 +296,34 @@ The Masterbuilder reads your vision document and coordinates the artisans.
 
 ## Vision Runner (Ralphy-Style)
 
-`wtv run` can also execute a project vision directly by generating a `PRD.md` (checklist) and iterating until all tasks are complete.
+`wtv run` (with no arguments) launches the **Vision Runner**, an autonomous loop that executes a project vision until completion.
 
-It maintains a `progress.txt` checkpoint log and, by default, creates a single git commit and pushes once at the end.
+It is designed for "Ralphy-style" execution: give it a vision, and it runs until the vision is a reality.
+
+### The Workflow
+
+1. **Pick a Vision**: WTV finds `VISION.md` (root) or files in `vision/*.md` and asks you to select one.
+2. **Generate Plan**: It prompts the engine (OpenCode, Codex, or Claude) to generate a detailed `PRD.md` with a task checklist.
+3. **Execute Loop**:
+   - Reads `PRD.md` to find the next unchecked task.
+   - Creates a focused prompt for the engine.
+   - Runs the engine to implement the task.
+   - Verifies the task was marked completed in `PRD.md`.
+   - Appends a checkpoint to `progress.txt`.
+   - Repeats until all tasks are done.
+4. **Finalize**: Creates a single git commit ("feat: complete <vision>") and pushes to remote (unless disabled).
+
+### File Contracts
+
+The Vision Runner relies on strict file conventions:
+
+- **Input**:
+  - `VISION.md` (or `vision/*.md`): The source of truth for *what* to build.
+- **Artifacts**:
+  - `PRD.md`: The execution checklist. Must use `- [ ]` for incomplete and `- [x]` for complete tasks. The runner stops when no `- [ ]` remain.
+  - `progress.txt`: An append-only log of every completed task with timestamps.
+
+### Usage
 
 ```bash
 wtv run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "writethevision",
-  "version": "7.0.6",
+  "version": "7.0.8",
   "description": "Write The Vision (WTV): vision-driven development with the Habakkuk workflow. 10 agents + 21 skills for Claude Code, Codex CLI, and OpenCode.",
   "author": "Christopher Hogg",
   "license": "MIT",

package/src/cli.js

@@ -1256,15 +1256,23 @@ async function checkForUpdates() {
 
     try {
         const packageName = getPackageName();
+        const checkEveryRun = process.env.WTV_UPDATE_CHECK_EVERY_RUN === '1';
         const notifier = updateNotifier({
             pkg: {
                 name: packageName,
                 version: getVersion(),
             },
-            updateCheckInterval: 1000 * 60 * 60 * 24 * 7,
+            updateCheckInterval: checkEveryRun ? Number.POSITIVE_INFINITY : 1000 * 60 * 60 * 24 * 7,
             shouldNotifyInNpmScript: false,
         });
 
+        if (checkEveryRun) {
+            try {
+                notifier.update = await notifier.fetchInfo();
+            } catch {
+            }
+        }
+
         const update = notifier.update;
         if (!update) return;
 
@@ -1290,7 +1298,7 @@ Or run latest once:
             },
         });
 
-        const shouldPrompt = process.stdin.isTTY && process.env.WTV_NO_AUTO_UPDATE !== '1' && !process.env.CI;
+        const shouldPrompt = process.stdin.isTTY && process.env.WTV_NO_AUTO_UPDATE !== '1' && !process.env.CI && !checkEveryRun;
         if (!shouldPrompt) return;
 
         const isDevCheckout = existsSync(join(PACKAGE_ROOT, '.git'));
@@ -3265,8 +3273,14 @@ async function runEngine(engine, promptText) {
     }
 
     if (normalized === 'claude') {
+        // Claude Code CLI: explicitly force text output so user config
+        // can't switch this to stream-json (which has extra requirements).
         return await new Promise((resolve, reject) => {
-            const child = spawn('claude', ['--dangerously-skip-permissions', '--output-format', 'stream-json', '-p', promptText], { stdio: 'inherit' });
+            const child = spawn(
+                'claude',
+                ['--dangerously-skip-permissions', '--print', '--output-format', 'text', promptText],
+                { stdio: 'inherit' },
+            );
             child.on('error', reject);
             child.on('exit', (code) => resolve(code ?? 1));
         });
@@ -3275,13 +3289,12 @@ async function runEngine(engine, promptText) {
     throw new Error(`Unsupported engine: ${engine}`);
 }
 
-function ensureProgressHeader(progressPath, { visionPath, engine, startSha }) {
+export function ensureProgressHeader(progressPath, { visionPath, engine, startSha }) {
     if (!existsSync(progressPath)) {
         writeFileSync(progressPath, '');
     }
 
     const existing = readFileSync(progressPath, 'utf8');
-    if (existing.trim().length > 0) return;
 
     const startedAt = new Date().toISOString();
     const header = [
@@ -3290,16 +3303,19 @@ function ensureProgressHeader(progressPath, { visionPath, engine, startSha }) {
         `Vision: ${visionPath}`,
         `Engine: ${engine}`,
         startSha ? `Start SHA: ${startSha}` : `Start SHA: (not a git repo)`,
+        startSha ? `Rollback hint: git reset --hard ${startSha}` : '',
         '',
     ].join('\n');
 
-    writeFileSync(progressPath, header);
+    if (existing.trim().length > 0) {
+        writeFileSync(progressPath, existing.trimEnd() + '\n\n' + header);
+    } else {
+        writeFileSync(progressPath, header);
+    }
 }
 
-async function generatePrdFromVision({ engine, visionPath, prdPath }) {
-    const visionContent = readFileSync(visionPath, 'utf8');
-
-    const promptText = `You are generating a PRD for a software project.
+export function generatePrdPrompt(visionContent) {
+    return `You are generating a PRD for a software project.
 
 Input vision document:
 ---
@@ -3316,6 +3332,12 @@ Requirements:
 - Do NOT implement any code yet.
 - Do NOT run git commit or git push.
 - Output is the updated files on disk (PRD.md).`;
+}
+
+async function generatePrdFromVision({ engine, visionPath, prdPath }) {
+    const visionContent = readFileSync(visionPath, 'utf8');
+
+    const promptText = generatePrdPrompt(visionContent);
 
     const code = await runEngine(engine, promptText);
     if (code !== 0) {
@@ -3332,7 +3354,7 @@ Requirements:
     }
 }
 
-async function runVisionTaskIteration({ engine, prdPath, progressPath, taskText, noTests, noLint }) {
+export async function runVisionTaskIteration({ engine, prdPath, progressPath, taskText, noTests, noLint, _runEngine }) {
     const promptText = `You are an autonomous coding agent executing a PRD.
 
 Files:
@@ -3360,7 +3382,8 @@ Stop after completing this one task.`;
 
     const progressBefore = existsSync(progressPath) ? readFileSync(progressPath, 'utf8') : '';
 
-    const code = await runEngine(engine, promptText);
+    const runFn = _runEngine || runEngine;
+    const code = await runFn(engine, promptText);
     if (code !== 0) {
         throw new Error(`Engine exited with code ${code}`);
     }
@@ -3382,6 +3405,71 @@ Stop after completing this one task.`;
     }
 }
 
+export function finalizeVisionRun({
+    prdPath,
+    visionPath,
+    hasGit,
+    startSha,
+    noPush,
+    _runGit,
+    _readFileSync,
+    _countUncheckedPrdTasks,
+    _getCurrentBranch
+}) {
+    const runGitFn = _runGit || runGit;
+    const readFileSyncFn = _readFileSync || readFileSync;
+    const countUncheckedFn = _countUncheckedPrdTasks || countUncheckedPrdTasks;
+    const getCurrentBranchFn = _getCurrentBranch || getCurrentBranch;
+
+    if (!hasGit) {
+        console.log(`\n  ${c.green}${sym.check}${c.reset} PRD complete (no git repo detected).\n`);
+        return;
+    }
+
+    const prdFinal = readFileSyncFn(prdPath, 'utf8');
+    if (countUncheckedFn(prdFinal) > 0) {
+        console.log(`\n  ${c.yellow}${sym.warn}${c.reset} PRD still has remaining tasks; skipping commit/push.\n`);
+        return;
+    }
+
+    const visionName = basename(visionPath).replace(/\.md$/, '');
+    const commitMessage = `feat: run vision (${visionName})`;
+
+    const addRes = runGitFn(['add', '-A']);
+    if (addRes.status !== 0) {
+        console.log(`\n  ${c.red}${sym.cross}${c.reset} git add failed.\n`);
+        return;
+    }
+
+    const statusRes = runGitFn(['status', '--porcelain']);
+    if (statusRes.status === 0 && String(statusRes.stdout || '').trim().length === 0) {
+        console.log(`\n  ${c.green}${sym.check}${c.reset} Nothing to commit.\n`);
+        return;
+    }
+
+    const commitRes = runGitFn(['commit', '-m', commitMessage]);
+    if (commitRes.status !== 0) {
+        console.log(`\n  ${c.red}${sym.cross}${c.reset} git commit failed.\n`);
+        return;
+    }
+
+    if (!noPush) {
+        const pushRes = runGitFn(['push']);
+        if (pushRes.status !== 0) {
+            const branch = getCurrentBranchFn();
+            if (branch) {
+                runGitFn(['push', '-u', 'origin', branch]);
+            }
+        }
+    }
+
+    console.log(`\n  ${c.green}${sym.check}${c.reset} Vision complete.`);
+    if (startSha) {
+        console.log(`  Started from: ${c.dim}${startSha}${c.reset}`);
+    }
+    console.log('');
+}
+
 async function visionRunner(opts) {
     const config = loadConfig();
     const interactive = process.stdout.isTTY && process.stdin.isTTY;
@@ -3389,10 +3477,9 @@ async function visionRunner(opts) {
     const prdPath = join(process.cwd(), 'PRD.md');
     const progressPath = join(process.cwd(), 'progress.txt');
 
-    const defaultEngine = normalizeVisionRunnerEngine(opts.engine || config.defaultTool || 'opencode');
-    let engine = defaultEngine;
+    let engine = normalizeVisionRunnerEngine(opts.engine || null);
 
-    if (!engine || !isSupportedVisionRunnerEngine(engine)) {
+    if (engine && !isSupportedVisionRunnerEngine(engine)) {
         engine = null;
     }
 
@@ -3453,6 +3540,12 @@ async function visionRunner(opts) {
     const hasGit = isGitRepo();
     const startSha = hasGit ? getGitHeadSha() : null;
 
+    if (!hasGit) {
+        console.log(`\n  ${c.yellow}${sym.warn} Warning:${c.reset} Not a git repository. Version control features disabled.\n`);
+    } else if (startSha) {
+        console.log(`\n  ${c.blue}${sym.info} Rollback hint:${c.reset} git reset --hard ${startSha}\n`);
+    }
+
     if (hasGit && !isWorkingTreeClean() && !opts.dryRun) {
         if (!interactive) {
             console.log(`\n  ${c.red}Error:${c.reset} Working tree is not clean (non-interactive mode).\n`);
@@ -3549,53 +3642,13 @@ async function visionRunner(opts) {
         }
     }
 
-    if (!hasGit) {
-        console.log(`\n  ${c.green}${sym.check}${c.reset} PRD complete (no git repo detected).\n`);
-        return;
-    }
-
-    const prdFinal = readFileSync(prdPath, 'utf8');
-    if (countUncheckedPrdTasks(prdFinal) > 0) {
-        console.log(`\n  ${c.yellow}${sym.warn}${c.reset} PRD still has remaining tasks; skipping commit/push.\n`);
-        return;
-    }
-
-    const visionName = basename(visionPath).replace(/\.md$/, '');
-    const commitMessage = `feat: run vision (${visionName})`;
-
-    const addRes = runGit(['add', '-A']);
-    if (addRes.status !== 0) {
-        console.log(`\n  ${c.red}${sym.cross}${c.reset} git add failed.\n`);
-        return;
-    }
-
-    const statusRes = runGit(['status', '--porcelain']);
-    if (statusRes.status === 0 && String(statusRes.stdout || '').trim().length === 0) {
-        console.log(`\n  ${c.green}${sym.check}${c.reset} Nothing to commit.\n`);
-        return;
-    }
-
-    const commitRes = runGit(['commit', '-m', commitMessage]);
-    if (commitRes.status !== 0) {
-        console.log(`\n  ${c.red}${sym.cross}${c.reset} git commit failed.\n`);
-        return;
-    }
-
-    if (!opts.noPush) {
-        const pushRes = runGit(['push']);
-        if (pushRes.status !== 0) {
-            const branch = getCurrentBranch();
-            if (branch) {
-                runGit(['push', '-u', 'origin', branch]);
-            }
-        }
-    }
-
-    console.log(`\n  ${c.green}${sym.check}${c.reset} Vision complete.`);
-    if (startSha) {
-        console.log(`  Started from: ${c.dim}${startSha}${c.reset}`);
-    }
-    console.log('');
+    finalizeVisionRun({
+        prdPath,
+        visionPath,
+        hasGit,
+        startSha,
+        noPush: opts.noPush
+    });
 }
 
 // ============================================================================
@@ -4565,7 +4618,7 @@ function showHelp() {
     console.log(`${pad}  ${c.cyan}vision${c.reset}        Show VISION.md status`);
     console.log(`${pad}  ${c.cyan}log${c.reset}           Show task logs`);
     console.log(`${pad}  ${c.cyan}meet${c.reset}          Meet Paul and the Artisans`);
-    console.log(`${pad}  ${c.cyan}run${c.reset}           Run the vision (PRD loop)`);
+    console.log(`${pad}  ${c.cyan}run${c.reset}           Run the vision (Vision Runner)`);
     console.log(`${pad}  ${c.cyan}help${c.reset}          Show this help\n`);
 
     console.log(`${pad}${c.bold}Agent Commands${c.reset}`);
@@ -4576,12 +4629,17 @@ function showHelp() {
     console.log(`${pad}  ${c.cyan}agents fav${c.reset} <name>   Toggle favorite`);
     console.log(`${pad}  ${c.cyan}agents rm${c.reset} <name>    Remove agent\n`);
 
+    console.log(`${pad}${c.bold}Vision Runner${c.reset}  ${c.dim}"That he may run that readeth it"${c.reset}`);
+    console.log(`${pad}  ${c.cyan}run${c.reset}               Launch Vision Runner (interactive)`);
+    console.log(`${pad}  ${c.cyan}run${c.reset} --vision <f>  Execute specific vision file`);
+    console.log(`${pad}  ${c.cyan}run${c.reset} --resume      Resume existing PRD.md\n`);
+
     console.log(`${pad}${c.bold}Habakkuk Workflow${c.reset}  ${c.dim}"Write the vision, make it plain"${c.reset}`);
     console.log(`${pad}  ${c.cyan}board${c.reset} [--all]        Show kanban board`);
     console.log(`${pad}  ${c.cyan}cry${c.reset} "desc"          Enter a problem or need`);
     console.log(`${pad}  ${c.cyan}wait${c.reset} <id>           Move to waiting (seeking)`);
     console.log(`${pad}  ${c.cyan}vision${c.reset} <id>         Move to vision (answer received)`);
-    console.log(`${pad}  ${c.cyan}run${c.reset} [id]           Run the vision, or move item to run`);
+    console.log(`${pad}  ${c.cyan}run${c.reset} <id>            Move to run (execution started)`);
     console.log(`${pad}  ${c.cyan}worship${c.reset} <id>        Move to worship (retrospective)`);
     console.log(`${pad}  ${c.cyan}note${c.reset} <id> "text"    Add note to item`);
     console.log(`${pad}  ${c.cyan}item${c.reset} <id>           Show item details`);
@@ -4599,6 +4657,18 @@ function showHelp() {
     console.log(`${pad}  ${c.dim}--gemini${c.reset}           Target Gemini CLI`);
     console.log(`${pad}  ${c.dim}--antigravity${c.reset}      Target Antigravity\n`);
 
+    console.log(`${pad}${c.bold}Vision Runner Options${c.reset}`);
+    console.log(`${pad}  ${c.dim}--vision <file>${c.reset}    Input vision file (default: discover)`);
+    console.log(`${pad}  ${c.dim}--engine <name>${c.reset}    Execution engine (opencode|codex|claude)`);
+    console.log(`${pad}  ${c.dim}--resume${c.reset}           Resume existing PRD.md`);
+    console.log(`${pad}  ${c.dim}--regenerate-prd${c.reset}   Force regeneration of PRD.md from vision`);
+    console.log(`${pad}  ${c.dim}--max-iterations <n>${c.reset} Stop after N tasks`);
+    console.log(`${pad}  ${c.dim}--dry-run${c.reset}          Show what would happen without running`);
+    console.log(`${pad}  ${c.dim}--fast${c.reset}             Skip tests and linting`);
+    console.log(`${pad}  ${c.dim}--no-tests${c.reset}         Skip tests`);
+    console.log(`${pad}  ${c.dim}--no-lint${c.reset}          Skip linting`);
+    console.log(`${pad}  ${c.dim}--no-push${c.reset}          Skip git push at end\n`);
+
     console.log(`${pad}${c.bold}Examples${c.reset}`);
     console.log(`${pad}  ${c.green}wtv${c.reset}                          ${c.dim}# Dashboard${c.reset}`);
     console.log(`${pad}  ${c.green}wtv agents${c.reset}                   ${c.dim}# List agents${c.reset}`);

package/src/engine.js

@@ -0,0 +1,109 @@
+import { spawn } from 'child_process';
+
+/**
+ * Base class for AI CLI engine adapters.
+ */
+class EngineAdapter {
+    constructor(cwd = process.cwd()) {
+        this.cwd = cwd;
+    }
+
+    /**
+     * Get the command and arguments for the engine.
+     * @param {string} prompt - The prompt to execute.
+     * @returns {{ command: string, args: string[] }}
+     */
+    getCommand(prompt) {
+        throw new Error('getCommand must be implemented by subclass');
+    }
+
+    /**
+     * Run the engine with the given prompt.
+     * @param {string} prompt - The prompt to execute.
+     * @param {object} options - Options for spawn.
+     * @returns {Promise<number>} - Exit code.
+     */
+    async run(prompt, options = {}) {
+        const { command, args } = this.getCommand(prompt);
+        
+        console.log(`[Engine] Running: ${command} ${args.join(' ')}`);
+
+        return new Promise((resolve, reject) => {
+            const child = spawn(command, args, {
+                cwd: this.cwd,
+                stdio: 'inherit', // Stream output to parent stdout/stderr
+                shell: true,      // Use shell to resolve command paths
+                ...options
+            });
+
+            child.on('error', (err) => {
+                reject(err);
+            });
+
+            child.on('close', (code) => {
+                resolve(code);
+            });
+        });
+    }
+}
+
+/**
+ * Adapter for OpenCode CLI.
+ */
+class OpenCodeEngine extends EngineAdapter {
+    getCommand(prompt) {
+        // Assumption: opencode takes the prompt as a single argument string
+        return {
+            command: 'opencode',
+            args: [prompt]
+        };
+    }
+}
+
+/**
+ * Adapter for Codex CLI.
+ */
+class CodexEngine extends EngineAdapter {
+    getCommand(prompt) {
+        // Assumption: codex takes the prompt as a single argument string
+        return {
+            command: 'codex',
+            args: [prompt]
+        };
+    }
+}
+
+/**
+ * Adapter for Claude Code CLI.
+ */
+class ClaudeEngine extends EngineAdapter {
+    getCommand(prompt) {
+        // Assumption: claude takes the prompt as a single argument string
+        // Note: Check if it needs -p or similar flag
+        return {
+            command: 'claude',
+            args: [prompt]
+        };
+    }
+}
+
+/**
+ * Factory to create the appropriate engine adapter.
+ * @param {string} name - The name of the engine ('opencode', 'codex', 'claude').
+ * @param {string} cwd - Current working directory.
+ * @returns {EngineAdapter}
+ */
+export function createEngine(name, cwd) {
+    switch (name.toLowerCase()) {
+        case 'opencode':
+            return new OpenCodeEngine(cwd);
+        case 'codex':
+            return new CodexEngine(cwd);
+        case 'claude':
+            return new ClaudeEngine(cwd);
+        default:
+            throw new Error(`Unsupported engine: ${name}`);
+    }
+}
+
+export { EngineAdapter, OpenCodeEngine, CodexEngine, ClaudeEngine };