gswd 1.0.0 → 1.1.0

package/bin/gswd-tools.cjs

@@ -11,6 +11,9 @@
  *   state read                           Read STATE.json
  *   state update-stage <stage> <status>  Update stage status
  *   state checkpoint <workflow> <id>     Write checkpoint
+ *   state cascade-invalidate <stage>     Cascade-invalidate downstream stages
+ *   state set-manual-mode <true|false>   Enable/disable manual mode
+ *   state update-manual-checkpoint <stage> <type>  Update manual checkpoint
  *   config read                          Read config.json gswd section
  *   config merge [--overrides json]      Merge gswd config
  *   render banner <name>                 Render stage banner
@@ -27,6 +30,11 @@
  *   audit [--auto-fix]                   Run Audit workflow
  *   compile                              Run Compile workflow
  *   bootstrap [@idea.md] [--auto] [--resume] [--skip-research] [--policy <name>]  Run full pipeline
+ *   render logo                         Render GSWD ASCII logo
+ *   render first-run-guide              Render first-run command guide
+ *   first-run-complete                  Mark first run as complete in STATE.json
+ *   intake write --description "..." --source interactive  Write INTAKE.json
+ *   intake read                         Read INTAKE.json
  */
 
 'use strict';
@@ -95,6 +103,25 @@ function outputText(text) {
   process.stdout.write(text + '\n');
 }
 
+// ─── Standalone Pipeline Guard ───────────────────────────────────────────────
+
+/**
+ * Check if running inside Claude Code. Pipeline commands require Claude Code's
+ * Task() API for agent spawning. When called standalone, print human-readable error.
+ */
+function guardPipelineCommand(commandName) {
+  // In Claude Code, spawnFn is provided at call time — this guard catches
+  // direct CLI invocation where pipeline commands produce no useful output.
+  // Check: if stdout is a TTY (real terminal, not piped), the user is likely
+  // running this manually outside Claude Code.
+  if (process.stdout.isTTY) {
+    console.log(`\nGSWD pipeline commands require Claude Code.`);
+    console.log(`Run /gswd:start inside a Claude Code session to use the full pipeline.\n`);
+    process.exit(2);
+  }
+  // Non-TTY (piped/CI): fall through to existing JSON error behavior
+}
+
 // ─── Argument Parsing ────────────────────────────────────────────────────────
 
 const args = process.argv.slice(2);
@@ -124,6 +151,9 @@ Commands:
   state read                           Read STATE.json
   state update-stage <stage> <status>  Update stage status
   state checkpoint <workflow> <id>     Write checkpoint
+  state cascade-invalidate <stage>     Cascade-invalidate downstream stages
+  state set-manual-mode <true|false>   Enable/disable manual mode
+  state update-manual-checkpoint <stage> <type>  Update manual checkpoint
   config read                          Read config.json gswd section
   config merge [--overrides json]      Merge gswd config
   render banner <name>                 Render stage banner
@@ -189,6 +219,12 @@ try {
     case 'bootstrap':
       handleBootstrap();
       break;
+    case 'first-run-complete':
+      handleFirstRunComplete();
+      break;
+    case 'intake':
+      handleIntake();
+      break;
     case '--help':
     case '-h':
     case 'help':
@@ -305,6 +341,38 @@ function handleState() {
       outputJson({ checkpoint_written: true, workflow, checkpoint_id: checkpointId });
       break;
     }
+    case 'cascade-invalidate': {
+      const stage = args[2];
+      if (!stage || !['imagine', 'specify', 'audit', 'compile'].includes(stage)) {
+        outputError('Usage: state cascade-invalidate <stage> (imagine|specify|audit|compile)');
+        process.exit(1);
+      }
+      stateModule.cascadeInvalidate(STATE_PATH, stage);
+      outputJson({ success: true, stage, action: 'cascade-invalidate' });
+      break;
+    }
+    case 'set-manual-mode': {
+      const enabledArg = args[2];
+      if (enabledArg !== 'true' && enabledArg !== 'false') {
+        outputError('Usage: state set-manual-mode <true|false>');
+        process.exit(1);
+      }
+      const enabled = enabledArg === 'true';
+      stateModule.setManualMode(STATE_PATH, enabled);
+      outputJson({ success: true, manual_mode: enabled });
+      break;
+    }
+    case 'update-manual-checkpoint': {
+      const stage = args[2] || null;
+      const interruptType = args[3] || null;
+      if (interruptType && interruptType !== 'mid_stage' && interruptType !== 'between_stages') {
+        outputError('Usage: state update-manual-checkpoint <stage|null> <mid_stage|between_stages|null>');
+        process.exit(1);
+      }
+      stateModule.updateManualCheckpoint(STATE_PATH, stage, interruptType);
+      outputJson({ success: true, stage, interrupt_type: interruptType });
+      break;
+    }
     default:
       outputError(`Unknown state subcommand: ${subcommand}`);
       process.exit(1);
@@ -393,6 +461,46 @@ function handleRender() {
       }
       break;
     }
+    case 'logo': {
+      const pkg = require('../package.json');
+      outputText(renderModule.renderLogo(pkg.version));
+      break;
+    }
+    case 'first-run-guide': {
+      outputText(renderModule.renderFirstRunGuide());
+      break;
+    }
+    case 'file-inventory': {
+      const defaultFiles = [
+        { path: '.planning/IMAGINE.md', description: 'Product vision, target user, and direction' },
+        { path: '.planning/DECISIONS.md', description: 'Frozen decisions, success metrics, risks' },
+        { path: '.planning/SPEC.md', description: 'Functional requirements with acceptance criteria' },
+        { path: '.planning/NFR.md', description: 'Non-functional requirements with thresholds' },
+        { path: '.planning/JOURNEYS.md', description: 'User journeys with FR and integration linkages' },
+        { path: '.planning/INTEGRATIONS.md', description: 'External integrations with status and fallbacks' },
+        { path: '.planning/research/ARCHITECTURE.md', description: 'Architecture patterns and project structure' },
+        { path: '.planning/research/FEATURES.md', description: 'Feature landscape with prioritization' },
+        { path: '.planning/research/PITFALLS.md', description: 'Common pitfalls and prevention strategies' },
+        { path: '.planning/research/STACK.md', description: 'Technology stack recommendations' },
+        { path: '.planning/research/SUMMARY.md', description: 'Research executive summary' },
+        { path: '.planning/PROJECT.md', description: 'GSD project context (compiled)' },
+        { path: '.planning/REQUIREMENTS.md', description: 'GSD requirements with traceability (compiled)' },
+        { path: '.planning/ROADMAP.md', description: 'GSD roadmap with phased journeys (compiled)' },
+        { path: '.planning/STATE.md', description: 'GSD project state and decisions (compiled)' },
+        { path: '.planning/research/gswd/SUMMARY.md', description: 'GSD-format research bridge (compiled)' },
+      ];
+
+      // Filter to only files that exist
+      const existingFiles = defaultFiles.filter(f => {
+        try {
+          fs.accessSync(path.join(CWD, f.path));
+          return true;
+        } catch { return false; }
+      });
+
+      process.stdout.write(renderModule.renderFileInventory(existingFiles) + '\n');
+      break;
+    }
     default:
       outputError(`Unknown render subcommand: ${subcommand}`);
       process.exit(1);
@@ -517,11 +625,77 @@ function handleCommit() {
 }
 
 function handleImagine() {
+  guardPipelineCommand('imagine');
+
+  // Handle update-vision subcommand (IMAGINE-05/06)
+  if (args[1] === 'update-vision') {
+    const newVision = args.slice(2).join(' ');
+    if (!newVision) {
+      outputError('Usage: imagine update-vision "<vision text>"');
+      process.exit(1);
+    }
+    const stateModule = loadModule('state');
+
+    const filesToUpdate = [
+      path.join(PLANNING_DIR, 'DECISIONS.md'),
+      path.join(PLANNING_DIR, 'IMAGINE.md'),
+    ];
+
+    const updated = [];
+    for (const filePath of filesToUpdate) {
+      try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        // Replace content between ## Vision and next ## heading (or end of file)
+        const updatedContent = content.replace(
+          /(^## Vision\s*\n)([\s\S]*?)(?=\n## |\n# |$)/m,
+          `$1\n${newVision}\n`
+        );
+        stateModule.safeWriteFile(filePath, updatedContent);
+        updated.push(filePath);
+      } catch (err) {
+        outputError(`Failed to update vision in ${filePath}: ${err.message}`);
+        process.exit(1);
+      }
+    }
+    outputJson({ updated: true, files: updated });
+    return;  // Exit handleImagine — do not proceed to main flow
+  }
+
   const imagineModule = loadModule('imagine');
 
   const autoMode = hasFlag('--auto');
   const skipResearch = hasFlag('--skip-research');
 
+  // Parse --rerun-context flag for re-run augmentation (IMAGINE-03)
+  const rerunContextPath = getFlag('--rerun-context');
+  let userFeedback;
+  let previousAgentOutputs;
+
+  if (rerunContextPath) {
+    const resolvedPath = path.resolve(CWD, rerunContextPath);
+    try {
+      userFeedback = fs.readFileSync(resolvedPath, 'utf-8');
+    } catch {
+      // Non-fatal: file not found, proceed without re-run augmentation
+    }
+    // Read previous agent outputs from persisted artifact files
+    previousAgentOutputs = {};
+    const agentFileMap = {
+      'market-researcher': path.join(PLANNING_DIR, 'COMPETITION.md'),
+      'icp-persona': path.join(PLANNING_DIR, 'ICP.md'),
+      'positioning': path.join(PLANNING_DIR, 'GTM.md'),
+      'brainstorm-alternatives': path.join(PLANNING_DIR, 'DIRECTIONS.md'),
+      'devils-advocate': path.join(PLANNING_DIR, 'RISKS.md'),
+    };
+    for (const [agentName, filePath] of Object.entries(agentFileMap)) {
+      try {
+        previousAgentOutputs[agentName] = fs.readFileSync(filePath, 'utf-8');
+      } catch {
+        // Agent artifact not found — no previous output for this agent
+      }
+    }
+  }
+
   // Find idea file: look for arg starting with @ or ending with .md
   let ideaFilePath = null;
   for (let i = 1; i < args.length; i++) {
@@ -553,6 +727,8 @@ function handleImagine() {
             skipResearch,
             planningDir: PLANNING_DIR,
             configPath: CONFIG_PATH,
+            previousAgentOutputs,
+            userFeedback,
           };
 
           imagineModule.runImagine(intakeOptions).then(function(result) {
@@ -576,6 +752,8 @@ function handleImagine() {
     skipResearch,
     planningDir: PLANNING_DIR,
     configPath: CONFIG_PATH,
+    previousAgentOutputs,
+    userFeedback,
   };
 
   // runImagine is async, handle with promise
@@ -591,6 +769,7 @@ function handleImagine() {
 }
 
 function handleSpecify() {
+  guardPipelineCommand('specify');
   const specifyModule = loadModule('specify');
 
   const autoMode = hasFlag('--auto');
@@ -620,6 +799,7 @@ function handleSpecify() {
 }
 
 function handleBootstrap() {
+  guardPipelineCommand('bootstrap');
   const bootstrapModule = loadModule('bootstrap');
 
   const autoMode = hasFlag('--auto');
@@ -664,6 +844,7 @@ function handleBootstrap() {
 }
 
 function handleAudit() {
+  guardPipelineCommand('audit');
   const auditModule = loadModule('audit');
 
   const autoFix = hasFlag('--auto-fix');
@@ -692,6 +873,7 @@ function handleAudit() {
 }
 
 function handleCompile() {
+  guardPipelineCommand('compile');
   const compileModule = loadModule('compile');
 
   try {
@@ -714,3 +896,49 @@ function handleCompile() {
     process.exit(1);
   }
 }
+
+function handleFirstRunComplete() {
+  const stateModule = loadModule('state');
+  const state = stateModule.readState(STATE_PATH);
+  if (!state) {
+    outputJson({ first_run_complete: false, error: 'STATE.json not found' });
+    return;
+  }
+  state.first_run_complete = true;
+  stateModule.writeState(STATE_PATH, state);
+  outputJson({ first_run_complete: true });
+}
+
+function handleIntake() {
+  const subCmd = args[1];
+  const intakeModule = loadModule('intake');
+
+  switch (subCmd) {
+    case 'write': {
+      const description = getFlag('--description');
+      const source = getFlag('--source') || 'interactive';
+      const ideaFile = getFlag('--idea-file');
+
+      if (!description) {
+        outputError('--description is required');
+        process.exit(1);
+      }
+
+      const result = intakeModule.writeIntake(GSWD_DIR, {
+        product_description: description,
+        source: source,
+        ...(ideaFile ? { idea_file: ideaFile } : {}),
+      });
+      outputJson(result);
+      break;
+    }
+    case 'read': {
+      const data = intakeModule.readIntake(GSWD_DIR);
+      outputJson(data || { error: 'No INTAKE.json found' });
+      break;
+    }
+    default:
+      outputError(`Unknown intake subcommand: ${subCmd}. Use 'write' or 'read'.`);
+      process.exit(1);
+  }
+}

package/bin/install.js

@@ -73,6 +73,14 @@ if (!fs.existsSync(srcDir)) {
 // Create destination directory
 fs.mkdirSync(destDir, { recursive: true });
 
+// Remove any stale .md files from a previous install before copying
+if (fs.existsSync(destDir)) {
+  const existing = fs.readdirSync(destDir).filter(f => f.endsWith('.md'));
+  for (const file of existing) {
+    fs.unlinkSync(path.join(destDir, file));
+  }
+}
+
 // Copy all .md files
 const files = fs.readdirSync(srcDir).filter(f => f.endsWith('.md'));
 let copied = 0;

package/commands/gswd/imagine.md

@@ -1,7 +1,7 @@
 ---
 name: gswd:imagine
 description: Validate product direction and freeze key decisions
-argument-hint: "[--auto] [--resume] [--skip-research] [@idea.md]"
+argument-hint: "[--auto] [--resume] [--skip-research] [--rerun-context <path>] [@idea.md]"
 allowed-tools:
   - Bash
   - Read
@@ -30,6 +30,7 @@ Turn a fuzzy product idea into a validated direction with frozen decisions.
 - `--auto` — apply auto policy for decision-making
 - `--resume` — continue from last checkpoint
 - `--skip-research` — disable research agents (faster, offline-friendly)
+- `--rerun-context <path>` — provide previous agent outputs and user feedback for augmented re-run
 
 **After this command:** Run `/gswd:specify` to build the execution-grade spec.
 </objective>
@@ -42,6 +43,11 @@ Turn a fuzzy product idea into a validated direction with frozen decisions.
    node ./bin/gswd-tools.cjs imagine $ARGUMENTS
    ```
 
+2.5. If `--rerun-context` flag is present, read the revision-notes file at the provided path and pass its content as additional context to the imagine workflow. The workflow will:
+   - Pass previous agent outputs to each agent's prompt as `<rerun_context>`
+   - Include user feedback in agent prompts so agents can build on or pivot from prior findings
+   - This enables the "Not satisfied — tell me more" re-run flow from `/gswd:start`
+
 3. The CLI runs the imagine workflow which may spawn research agents (unless `--skip-research`).
 
 4. Interactive prompts will ask the founder to confirm or override key decisions.