gsdd-cli 0.1.0

package/bin/lib/health.mjs

@@ -0,0 +1,248 @@
+// health.mjs — Workspace integrity diagnostics
+//
+// IMPORTANT: No module-scope process.cwd() — ESM caching means sub-modules
+// evaluate once, so CWD must be computed inside function bodies.
+
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { readManifest, detectModifications } from './manifest.mjs';
+import { output } from './cli-utils.mjs';
+
+/**
+ * Factory function returning the health command.
+ * ctx must provide: { frameworkVersion }
+ */
+export function createCmdHealth(ctx) {
+  return async function cmdHealth(...healthArgs) {
+    const jsonMode = healthArgs.includes('--json');
+    const cwd = process.cwd();
+    const planningDir = join(cwd, '.planning');
+
+    // Pre-init guard
+    if (!existsSync(join(planningDir, 'config.json'))) {
+      if (jsonMode) {
+        output({ status: 'broken', errors: [{ id: 'E1', severity: 'ERROR', message: '.planning/config.json missing', fix: 'Run `gsdd init`' }], warnings: [], info: [] });
+      } else {
+        console.log('Not initialized. Run `gsdd init`.');
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    const errors = [];
+    const warnings = [];
+    const info = [];
+
+    // --- ERROR checks ---
+
+    // E1: config.json missing (already handled by pre-init guard, but keep for completeness)
+    // E2: config.json missing required fields
+    let config = null;
+    try {
+      config = JSON.parse(readFileSync(join(planningDir, 'config.json'), 'utf-8'));
+      const requiredFields = ['researchDepth', 'modelProfile', 'initVersion'];
+      const missing = requiredFields.filter((f) => !(f in config));
+      if (missing.length > 0) {
+        errors.push({ id: 'E2', severity: 'ERROR', message: `config.json missing required fields: ${missing.join(', ')}`, fix: 'Run `gsdd init` to regenerate' });
+      }
+    } catch {
+      errors.push({ id: 'E1', severity: 'ERROR', message: '.planning/config.json is unparseable', fix: 'Run `gsdd init`' });
+    }
+
+    // E3: templates/ missing
+    const templatesDir = join(planningDir, 'templates');
+    const hasTemplatesDir = existsSync(templatesDir);
+    const rolesDir = join(templatesDir, 'roles');
+    const delegatesDir = join(templatesDir, 'delegates');
+    const hasRolesDir = hasTemplatesDir && existsSync(rolesDir);
+    const hasDelegatesDir = hasTemplatesDir && existsSync(delegatesDir);
+
+    if (!hasTemplatesDir) {
+      errors.push({ id: 'E3', severity: 'ERROR', message: '.planning/templates/ missing', fix: 'Run `gsdd update --templates`' });
+    } else {
+      // E4: roles/ missing or empty
+      if (!hasRolesDir) {
+        errors.push({ id: 'E4', severity: 'ERROR', message: '.planning/templates/roles/ missing', fix: 'Run `gsdd update --templates`' });
+      } else {
+        const roleFiles = readdirSync(rolesDir).filter((f) => f.endsWith('.md'));
+        if (roleFiles.length === 0) {
+          errors.push({ id: 'E4', severity: 'ERROR', message: '.planning/templates/roles/ has 0 role files', fix: 'Run `gsdd update --templates`' });
+        }
+      }
+
+      // E5: delegates/ missing or empty
+      if (!hasDelegatesDir) {
+        errors.push({ id: 'E5', severity: 'ERROR', message: '.planning/templates/delegates/ missing', fix: 'Run `gsdd update --templates`' });
+      } else {
+        const delegateFiles = readdirSync(delegatesDir).filter((f) => f.endsWith('.md'));
+        if (delegateFiles.length === 0) {
+          errors.push({ id: 'E5', severity: 'ERROR', message: '.planning/templates/delegates/ has 0 delegate files', fix: 'Run `gsdd update --templates`' });
+        }
+      }
+    }
+
+    // --- WARNING checks ---
+
+    // W1: generation-manifest.json missing
+    const manifest = readManifest(planningDir);
+    if (!manifest) {
+      warnings.push({ id: 'W1', severity: 'WARN', message: 'generation-manifest.json missing', fix: 'Run `gsdd update --templates` to create' });
+    }
+
+    // W2 + W3: template/role hash mismatches and missing files
+    if (manifest && hasTemplatesDir) {
+      const allCategories = [
+        { name: 'delegates', dir: delegatesDir, hashes: hasDelegatesDir ? manifest.templates?.delegates : null },
+        { name: 'research', dir: join(templatesDir, 'research'), hashes: manifest.templates?.research },
+        { name: 'codebase', dir: join(templatesDir, 'codebase'), hashes: manifest.templates?.codebase },
+        { name: 'root templates', dir: templatesDir, hashes: manifest.templates?.root },
+        { name: 'roles', dir: rolesDir, hashes: hasRolesDir ? manifest.roles : null },
+      ];
+
+      for (const cat of allCategories) {
+        if (!cat.hashes) continue;
+        const result = detectModifications(cat.dir, cat.hashes);
+        if (result.modified.length > 0) {
+          warnings.push({ id: 'W2', severity: 'WARN', message: `${cat.name}: ${result.modified.length} file(s) modified locally (${result.modified.join(', ')})`, fix: 'Intentional? Run `gsdd update --templates` to reset' });
+        }
+        if (result.missing.length > 0) {
+          warnings.push({ id: 'W3', severity: 'WARN', message: `${cat.name}: ${result.missing.length} file(s) missing from disk (${result.missing.join(', ')})`, fix: 'Run `gsdd update --templates` to restore' });
+        }
+      }
+    }
+
+    // W4: ROADMAP.md references phases not found in .planning/phases/
+    const roadmapPath = join(planningDir, 'ROADMAP.md');
+    const phasesDir = join(planningDir, 'phases');
+    const roadmap = existsSync(roadmapPath) ? readFileSync(roadmapPath, 'utf-8') : null;
+    const phaseArtifacts = existsSync(phasesDir) ? listPhaseArtifacts(phasesDir) : [];
+
+    if (roadmap && existsSync(phasesDir)) {
+      const phaseNums = [];
+      for (const line of roadmap.split('\n')) {
+        const match = line.match(/^\s*[-*]\s*\[[ x-]\]\s*\*\*Phase\s+(\d+)/i);
+        if (match) phaseNums.push(parseInt(match[1], 10));
+      }
+      for (const num of phaseNums) {
+        const padded = String(num).padStart(2, '0');
+        const hasFile = phaseArtifacts.some((artifact) => artifact.phasePrefix === padded || artifact.phasePrefix === String(num));
+        if (!hasFile) {
+          warnings.push({ id: 'W4', severity: 'WARN', message: `ROADMAP.md references Phase ${num} but no files found in .planning/phases/`, fix: 'Create missing phase dirs or update ROADMAP' });
+        }
+      }
+    }
+
+    // W5: Phase dir has PLAN but no SUMMARY (stale in-progress)
+    if (phaseArtifacts.length > 0) {
+      const plans = phaseArtifacts.filter((artifact) => artifact.name.includes('PLAN'));
+      for (const plan of plans) {
+        const prefix = plan.name.split('-PLAN')[0];
+        const hasSummary = phaseArtifacts.some((artifact) =>
+          artifact.dir === plan.dir &&
+          artifact.name.startsWith(prefix) &&
+          artifact.name.includes('SUMMARY')
+        );
+        if (!hasSummary) {
+          warnings.push({ id: 'W5', severity: 'WARN', message: `${plan.displayPath} exists but no matching SUMMARY found (stale in-progress?)`, fix: 'Resume or complete the phase' });
+        }
+      }
+    }
+
+    // W6: No adapter surfaces detected
+    const adapterPaths = [
+      join(cwd, '.agents', 'skills'),
+      join(cwd, '.claude'),
+      join(cwd, '.opencode'),
+      join(cwd, '.codex'),
+    ];
+    const hasAnyAdapter = adapterPaths.some((p) => existsSync(p));
+    if (!hasAnyAdapter) {
+      warnings.push({ id: 'W6', severity: 'WARN', message: 'No adapter surfaces detected', fix: 'Run `gsdd init --tools <platform>`' });
+    }
+
+    // --- INFO checks ---
+
+    // I1: generation manifest was produced by a different framework version
+    if (manifest && manifest.frameworkVersion && manifest.frameworkVersion !== ctx.frameworkVersion) {
+      info.push({ id: 'I1', severity: 'INFO', message: `Generation manifest frameworkVersion (${manifest.frameworkVersion}) differs from current framework version (${ctx.frameworkVersion})`, fix: 'Run `gsdd update --templates`' });
+    }
+
+    // I2: Phase completion count
+    if (roadmap) {
+      const lines = roadmap.split('\n');
+      let total = 0;
+      let done = 0;
+      for (const line of lines) {
+        const match = line.match(/^\s*[-*]\s*\[([x ]|-)\]\s*\*\*Phase\s+\d+/i);
+        if (match) {
+          total++;
+          if (match[1] === 'x') done++;
+        }
+      }
+      if (total > 0) {
+        info.push({ id: 'I2', severity: 'INFO', message: `Phases: ${done}/${total} completed` });
+      }
+    }
+
+    // I3: Which adapters are installed
+    const installedAdapters = [];
+    if (existsSync(join(cwd, '.agents', 'skills'))) installedAdapters.push('open-standard-skills');
+    if (existsSync(join(cwd, '.claude'))) installedAdapters.push('claude');
+    if (existsSync(join(cwd, '.opencode'))) installedAdapters.push('opencode');
+    if (existsSync(join(cwd, '.codex'))) installedAdapters.push('codex');
+    if (existsSync(join(cwd, 'AGENTS.md'))) installedAdapters.push('agents');
+    if (installedAdapters.length > 0) {
+      info.push({ id: 'I3', severity: 'INFO', message: `Adapters installed: ${installedAdapters.join(', ')}` });
+    }
+
+    // --- Verdict ---
+    const hasErrors = errors.length > 0;
+    const hasWarnings = warnings.length > 0;
+    const status = hasErrors ? 'broken' : hasWarnings ? 'degraded' : 'healthy';
+
+    if (hasErrors) process.exitCode = 1;
+
+    if (jsonMode) {
+      output({ status, errors, warnings, info });
+    } else {
+      console.log(`\ngsdd health — workspace integrity check\n`);
+      if (errors.length > 0) {
+        for (const e of errors) console.log(`  ERROR: [${e.id}] ${e.message}\n    Fix: ${e.fix}`);
+      }
+      if (warnings.length > 0) {
+        for (const w of warnings) console.log(`  WARN:  [${w.id}] ${w.message}\n    Fix: ${w.fix}`);
+      }
+      if (info.length > 0) {
+        for (const i of info) console.log(`  INFO:  [${i.id}] ${i.message}${i.fix ? `\n    Fix: ${i.fix}` : ''}`);
+      }
+      console.log(`\n  Verdict: ${status.toUpperCase()}\n`);
+    }
+  };
+}
+
+function listPhaseArtifacts(phasesDir) {
+  const artifacts = [];
+  for (const entry of readdirSync(phasesDir, { withFileTypes: true })) {
+    const entryPath = join(phasesDir, entry.name);
+    if (entry.isFile()) {
+      artifacts.push(createPhaseArtifact('', entry.name));
+      continue;
+    }
+    if (!entry.isDirectory()) continue;
+    for (const child of readdirSync(entryPath, { withFileTypes: true })) {
+      if (child.isFile()) {
+        artifacts.push(createPhaseArtifact(entry.name, child.name));
+      }
+    }
+  }
+  return artifacts;
+}
+
+function createPhaseArtifact(dir, name) {
+  return {
+    dir,
+    name,
+    displayPath: dir ? `${dir}/${name}` : name,
+    phasePrefix: name.match(/^(\d+(?:\.\d+)?)-/)?.[1] || dir.match(/^(\d+(?:\.\d+)?)-/)?.[1] || null,
+  };
+}

package/bin/lib/init.mjs

@@ -0,0 +1,379 @@
+// init.mjs - CLI bootstrap, update, and help command implementations
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync } from 'fs';
+import { join, isAbsolute } from 'path';
+import * as readline from 'readline';
+import { renderSkillContent } from './rendering.mjs';
+import { buildManifest, writeManifest } from './manifest.mjs';
+import { parseFlagValue, parseToolsFlag, parseAutoFlag } from './cli-utils.mjs';
+import { DEFAULT_GIT_PROTOCOL, buildDefaultConfig, normalizeModelProfile } from './models.mjs';
+import { installProjectTemplates, refreshTemplates } from './templates.mjs';
+
+export function createCmdInit(ctx) {
+  return async function cmdInit(...initArgs) {
+    console.log('gsdd init - setting up SDD workflow\n');
+
+    const isAuto = parseAutoFlag(initArgs);
+    const toolsFlag = parseFlagValue(initArgs, '--tools');
+    const briefFlag = parseFlagValue(initArgs, '--brief');
+    let briefSource = null;
+
+    if (toolsFlag.invalid) {
+      console.error('ERROR: --tools requires a value. Example: gsdd init --tools claude');
+      process.exitCode = 1;
+      return;
+    }
+
+    if (briefFlag.invalid) {
+      console.error('ERROR: --brief requires a file path. Example: gsdd init --brief project-idea.md');
+      process.exitCode = 1;
+      return;
+    }
+
+    if (briefFlag.value) {
+      briefSource = isAbsolute(briefFlag.value) ? briefFlag.value : join(ctx.cwd, briefFlag.value);
+      if (!existsSync(briefSource)) {
+        console.error(`ERROR: Brief file not found: ${briefFlag.value}`);
+        process.exitCode = 1;
+        return;
+      }
+    }
+
+    const parsedTools = parseToolsFlag(initArgs);
+    if (isAuto && parsedTools.length === 0) {
+      console.error('ERROR: --auto requires --tools <platform>. Example: gsdd init --auto --tools claude');
+      process.exitCode = 1;
+      return;
+    }
+
+    const existed = existsSync(ctx.planningDir);
+    mkdirSync(join(ctx.planningDir, 'phases'), { recursive: true });
+    mkdirSync(join(ctx.planningDir, 'research'), { recursive: true });
+    console.log(existed
+      ? '  - .planning/ already exists (ensured subdirectories)'
+      : '  - created .planning/ directory structure');
+
+    installProjectTemplates(ctx);
+    await ensureConfig(ctx.cwd, ctx.planningDir, isAuto);
+
+    if (briefSource) {
+      cpSync(briefSource, join(ctx.planningDir, 'PROJECT_BRIEF.md'));
+      console.log('  - copied project brief to .planning/PROJECT_BRIEF.md');
+    }
+
+    generateOpenStandardSkills(ctx.cwd, ctx.workflows);
+    console.log('  - generated open-standard skills (.agents/skills/gsdd-*)');
+
+    const requestedTools = normalizeRequestedTools(parsedTools);
+    const platforms = parsedTools.length > 0 ? requestedTools : detectPlatforms(ctx.adapters);
+    for (const adapter of resolveAdapters(ctx.adapters, platforms)) {
+      adapter.generate();
+      console.log(`  - ${adapter.summary('generated')}`);
+    }
+
+    const manifest = buildManifest({ planningDir: ctx.planningDir, frameworkVersion: ctx.frameworkVersion });
+    writeManifest(ctx.planningDir, manifest);
+    console.log('  - wrote generation manifest');
+
+    console.log('\nSDD initialized.');
+    console.log('Next: run the new-project workflow to produce SPEC.md and ROADMAP.md:\n');
+
+    if (platforms.includes('claude'))
+      console.log('  Claude Code:  /gsdd-new-project');
+    if (platforms.includes('opencode'))
+      console.log('  OpenCode:     /gsdd-new-project');
+    if (platforms.includes('codex'))
+      console.log('  Codex CLI:    $gsdd-new-project');
+
+    // Always show the portable fallback
+    console.log('  Any tool:     open .agents/skills/gsdd-new-project/SKILL.md\n');
+  };
+}
+
+export function createCmdUpdate(ctx) {
+  return function cmdUpdate(...updateArgs) {
+    const isDry = updateArgs.includes('--dry');
+    const doTemplates = updateArgs.includes('--templates');
+
+    console.log(`gsdd update - regenerating adapter files${isDry ? ' (dry run)' : ''}\n`);
+
+    const parsedTools = parseToolsFlag(updateArgs);
+    const requestedTools = normalizeRequestedTools(parsedTools);
+    const platforms = parsedTools.length > 0 ? requestedTools : detectPlatforms(ctx.adapters);
+
+    let updated = false;
+
+    if (doTemplates) {
+      refreshTemplates({ ...ctx, isDry });
+      updated = true;
+    }
+
+    if (platforms.length > 0 || existsSync(join(ctx.cwd, '.agents', 'skills'))) {
+      if (isDry) {
+        console.log('  - would update open-standard skills (.agents/skills/gsdd-*)');
+      } else {
+        generateOpenStandardSkills(ctx.cwd, ctx.workflows);
+        console.log('  - updated open-standard skills (.agents/skills/gsdd-*)');
+      }
+      updated = true;
+    }
+
+    for (const adapter of getAdaptersToUpdate(ctx.adapters, platforms)) {
+      if (isDry) {
+        console.log(`  - would update ${adapter.name} adapter`);
+      } else {
+        adapter.generate();
+        console.log(`  - ${adapter.summary('updated')}`);
+      }
+      updated = true;
+    }
+
+    if (!updated) {
+      console.log('  - no adapters found to update (run `gsdd init` first)');
+    } else if (isDry) {
+      console.log('\nDry run complete. No files were written.\n');
+    } else {
+      if (doTemplates && existsSync(ctx.planningDir)) {
+        const manifest = buildManifest({ planningDir: ctx.planningDir, frameworkVersion: ctx.frameworkVersion });
+        writeManifest(ctx.planningDir, manifest);
+        console.log('  - updated generation manifest');
+      }
+      console.log('\nAdapters updated.\n');
+    }
+  };
+}
+
+export function cmdHelp() {
+  console.log(`
+gsdd - GSD Distilled CLI
+Spec-Driven Development for AI coding agents.
+
+Usage: gsdd <command> [args]
+
+Commands:
+  init [--tools <platform>] [--auto] [--brief <file>]
+                              Set up SDD + generate adapters
+                              --auto: non-interactive mode with smart defaults (requires --tools)
+                              --brief <file>: copy project brief to .planning/PROJECT_BRIEF.md
+  update [--tools <platform>] [--templates] [--dry]
+                              Regenerate adapters from latest framework sources
+                              --templates: also refresh .planning/templates/ and roles
+                              --dry: preview changes without writing files
+  health [--json]             Check workspace integrity (healthy/degraded/broken)
+  models [subcommand]         Inspect or update model profile / runtime overrides
+  find-phase [N]              Show phase info as JSON (for agent consumption)
+  verify <N>                  Run artifact checks for phase N
+  scaffold phase <N> [name]   Create a new phase plan file
+
+Platforms (for --tools):
+  claude    Generate Claude Code skills (.claude/skills/gsdd-*), commands (.claude/commands/gsdd-*.md), and native agents (.claude/agents/gsdd-*.md)
+  opencode  Generate OpenCode local slash commands (.opencode/commands/gsdd-*.md) + native agents (.opencode/agents/gsdd-*.md)
+  codex     Generate Codex CLI native plan-checker agent (.codex/agents/gsdd-plan-checker.toml)
+  agents    Generate/Update root AGENTS.md (bounded GSDD block)
+  cursor    Same as 'agents'
+  copilot   Same as 'agents'
+  gemini    Same as 'agents'
+  all       Generate all adapters (Claude, OpenCode, Codex, AGENTS-based surfaces)
+
+Notes:
+  - init always generates open-standard skills at .agents/skills/gsdd-* (portable workflow entrypoints)
+  - --tools claude also generates native commands at .claude/commands/gsdd-*.md and native agents at .claude/agents/gsdd-*.md
+  - --tools opencode also generates native agents at .opencode/agents/gsdd-*.md
+  - --tools codex generates .codex/agents/gsdd-plan-checker.toml (portable skill is the entry surface)
+  - root AGENTS.md is only written on init when explicitly requested via --tools agents (or all)
+
+Examples:
+  npx gsdd-cli init
+  npx gsdd-cli init --tools claude
+  npx gsdd-cli init --auto --tools claude --brief project-idea.md
+  npx gsdd-cli init --auto --tools all
+  npx gsdd-cli models show
+  npx gsdd-cli models profile quality
+  npx gsdd-cli models agent-profile --agent plan-checker --profile quality
+  npx gsdd-cli models set --runtime opencode --agent plan-checker --model anthropic/claude-opus-4-6
+  npx gsdd-cli models clear --runtime opencode --agent plan-checker
+  npx gsdd-cli init --tools agents
+  npx gsdd-cli init --tools all
+  npx gsdd-cli update
+  npx gsdd-cli find-phase
+  npx gsdd-cli verify 1
+  npx gsdd-cli scaffold phase 4 Payments
+
+Workflows (run via skills/adapters generated by init, not direct CLI):
+  map-codebase      Map or refresh codebase (.agents/skills/gsdd-map-codebase/)
+  audit-milestone   Audit a completed milestone (.agents/skills/gsdd-audit-milestone/)
+`);
+}
+
+function detectPlatforms(adapters) {
+  return Object.values(adapters)
+    .filter((adapter, index, arr) => arr.findIndex((other) => other.id === adapter.id) === index)
+    .filter((adapter) => adapter.detect())
+    .map((adapter) => adapter.name);
+}
+
+function normalizeRequestedTools(requestedTools) {
+  return requestedTools;
+}
+
+function generateOpenStandardSkills(cwd, workflows) {
+  for (const workflow of workflows) {
+    const dir = join(cwd, '.agents', 'skills', workflow.name);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'SKILL.md'), renderSkillContent(workflow));
+  }
+}
+
+function resolveAdapters(adapters, platformNames) {
+  const seen = new Set();
+  const resolved = [];
+
+  for (const platformName of platformNames) {
+    const adapter = adapters[platformName];
+    if (!adapter || seen.has(adapter.id)) continue;
+    seen.add(adapter.id);
+    resolved.push(adapter);
+  }
+
+  return resolved;
+}
+
+function getAdaptersToUpdate(adapters, platformNames) {
+  const requested = new Set(platformNames);
+  const seen = new Set();
+  const installed = [];
+
+  for (const [platformName, adapter] of Object.entries(adapters)) {
+    if (seen.has(adapter.id)) continue;
+    if (!requested.has(platformName) && !adapter.isInstalled()) continue;
+    seen.add(adapter.id);
+    installed.push(adapter);
+  }
+
+  return installed;
+}
+
+async function ensureConfig(cwd, planningDir, isAuto) {
+  const configFile = join(planningDir, 'config.json');
+  if (existsSync(configFile)) {
+    console.log('  - .planning/config.json already exists');
+    return;
+  }
+
+  if (isAuto) {
+    console.log('  - auto mode: writing config.json with defaults');
+    writeFileSync(configFile, JSON.stringify(buildDefaultConfig({ autoAdvance: true }), null, 2));
+    console.log('  - saved .planning/config.json (auto mode - autoAdvance enabled)\n');
+    return;
+  }
+
+  if (!process.stdin.isTTY) {
+    console.log('  - non-interactive mode detected: writing config.json with defaults');
+    writeFileSync(configFile, JSON.stringify(buildDefaultConfig(), null, 2));
+    console.log('  - saved .planning/config.json (defaults - re-run gsdd init in a terminal to customize)\n');
+    return;
+  }
+
+  const config = await promptForConfig(cwd);
+  writeFileSync(configFile, JSON.stringify(config, null, 2));
+  console.log('\n  - saved .planning/config.json\n');
+}
+
+async function promptForConfig(cwd) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
+
+  try {
+    console.log("  Let's configure the planning strategy for this project:\n");
+
+    console.log('  Research depth:');
+    console.log('   - balanced: SOTA research per phase (recommended)');
+    console.log('   - fast: skip deep domain research, plan from existing knowledge');
+    console.log('   - deep: exhaustive web sweeps + parallel researchers for every feature');
+    let researchDepth = await askQuestion('  Depth [balanced/fast/deep] (default: balanced): ');
+    researchDepth = researchDepth.trim().toLowerCase();
+    if (!['balanced', 'fast', 'deep'].includes(researchDepth)) researchDepth = 'balanced';
+
+    console.log('\n  Parallelization (run independent agents simultaneously):');
+    console.log('   - yes: faster, uses more tokens (recommended for non-trivial projects)');
+    console.log('   - no: sequential, lower token usage');
+    let parallelInput = await askQuestion('  Parallelize agents? [yes/no] (default: yes): ');
+    const parallelization = parallelInput.trim().toLowerCase() !== 'no';
+
+    console.log('\n  Version control for planning docs:');
+    console.log('   - yes: .planning/ tracked in git (recommended - enables history + recovery)');
+    console.log('   - no: .planning/ added to .gitignore (local only)');
+    let commitInput = await askQuestion('  Commit planning docs to git? [yes/no] (default: yes): ');
+    const commitDocs = commitInput.trim().toLowerCase() !== 'no';
+
+    console.log('\n  AI model profile for planning agents:');
+    console.log('   - balanced: capable model for most agents (recommended)');
+    console.log('   - quality: most capable model for research/roadmap (higher cost)');
+    console.log('   - budget: fastest/cheapest model (lower quality for complex tasks)');
+    let modelProfile = await askQuestion('  Model profile [balanced/quality/budget] (default: balanced): ');
+    modelProfile = normalizeModelProfile(modelProfile.trim().toLowerCase());
+
+    console.log('\n  Workflow agents (each adds quality but costs tokens/time):');
+    let researchInput = await askQuestion('  Research before planning each phase? [yes/no] (default: yes): ');
+    const workflowResearch = researchInput.trim().toLowerCase() !== 'no';
+
+    let planCheckInput = await askQuestion('  Verify plans achieve their goals before executing? [yes/no] (default: yes): ');
+    const workflowPlanCheck = planCheckInput.trim().toLowerCase() !== 'no';
+
+    let verifierInput = await askQuestion('  Verify phase deliverables after execution? [yes/no] (default: yes): ');
+    const workflowVerifier = verifierInput.trim().toLowerCase() !== 'no';
+
+    console.log('\n  Version Control Protocol (Advisory)');
+    console.log('   This captures preferred guidance. Repo/user conventions still win over framework defaults.');
+
+    let branchStrategy = await askQuestion('   Branching guidance (default: follow existing repo conventions; use feature branches for significant changes): ');
+    branchStrategy = branchStrategy.trim() || DEFAULT_GIT_PROTOCOL.branch;
+
+    let commitStrategy = await askQuestion('   Commit guidance (default: logical grouping, no phase/plan/task IDs unless requested): ');
+    commitStrategy = commitStrategy.trim() || DEFAULT_GIT_PROTOCOL.commit;
+
+    let prStrategy = await askQuestion('   PR guidance (default: follow existing repo review workflow): ');
+    prStrategy = prStrategy.trim() || DEFAULT_GIT_PROTOCOL.pr;
+
+    if (!commitDocs) {
+      ensureGitignoreEntry(cwd);
+    }
+
+    return {
+      researchDepth,
+      parallelization,
+      commitDocs,
+      modelProfile,
+      workflow: {
+        research: workflowResearch,
+        planCheck: workflowPlanCheck,
+        verifier: workflowVerifier,
+      },
+      gitProtocol: {
+        branch: branchStrategy,
+        commit: commitStrategy,
+        pr: prStrategy,
+      },
+      initVersion: 'v1.1',
+    };
+  } finally {
+    rl.close();
+  }
+}
+
+function ensureGitignoreEntry(cwd) {
+  const gitignorePath = join(cwd, '.gitignore');
+  const ignoreEntry = '\n# GSDD planning docs (local only)\n.planning/\n';
+
+  if (existsSync(gitignorePath)) {
+    const existing = readFileSync(gitignorePath, 'utf-8');
+    if (!existing.includes('.planning/')) {
+      writeFileSync(gitignorePath, existing + ignoreEntry);
+      console.log('  - added .planning/ to .gitignore');
+    }
+    return;
+  }
+
+  writeFileSync(gitignorePath, ignoreEntry.trimStart());
+  console.log('  - created .gitignore with .planning/ entry');
+}