gspec 1.11.0 → 1.13.1

package/bin/gspec.js

@@ -2,15 +2,16 @@
 
 import { program } from 'commander';
 import { readdir, readFile, writeFile, mkdir, stat } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
+import { join, dirname, basename } from 'node:path';
+import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
 import chalk from 'chalk';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DIST_DIR = join(__dirname, '..', 'dist');
-const STARTERS_DIR = join(__dirname, '..', 'starters');
 const pkg = JSON.parse(await readFile(join(__dirname, '..', 'package.json'), 'utf-8'));
+const SPEC_VERSION = 'v1';
 
 const BANNER = `
   ${chalk.cyan('╔══════════════════════════════════════════════╗')}
@@ -117,67 +118,6 @@ function promptConfirmNo(message) {
   });
 }
 
-// --- Feature dependency map ---
-// Maps feature slugs to their required feature dependencies (other feature slugs).
-// This is used to auto-include dependencies when a user selects a feature.
-const FEATURE_DEPENDENCIES = {
-  'home-page': [],
-  'about-page': ['home-page'],
-  'contact-page': ['home-page'],
-  'services-page': ['home-page'],
-  'responsive-navbar': ['home-page'],
-  'contact-form': ['contact-page'],
-  'site-footer': ['home-page', 'about-page', 'contact-page'],
-  'theme-switcher': ['home-page', 'about-page', 'contact-page'],
-};
-
-function resolveFeatureDependencies(selectedSlugs) {
-  const resolved = new Set(selectedSlugs);
-  let changed = true;
-  while (changed) {
-    changed = false;
-    for (const slug of [...resolved]) {
-      const deps = FEATURE_DEPENDENCIES[slug] || [];
-      for (const dep of deps) {
-        if (!resolved.has(dep)) {
-          resolved.add(dep);
-          changed = true;
-        }
-      }
-    }
-  }
-  return [...resolved];
-}
-
-// --- Starter template utilities ---
-
-async function parseStarterDescription(filePath) {
-  const content = await readFile(filePath, 'utf-8');
-  const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
-  if (!match) return '';
-  const descLine = match[1].split('\n').find((l) => l.startsWith('description:'));
-  return descLine ? descLine.replace(/^description:\s*/, '').trim() : '';
-}
-
-async function listStarterTemplates(category) {
-  const dir = join(STARTERS_DIR, category);
-  let entries;
-  try {
-    entries = await readdir(dir);
-  } catch (e) {
-    if (e.code === 'ENOENT') return [];
-    throw e;
-  }
-  const mdFiles = entries.filter((f) => f.endsWith('.md'));
-  const templates = [];
-  for (const f of mdFiles) {
-    const slug = f.replace(/\.md$/, '');
-    const description = await parseStarterDescription(join(dir, f));
-    templates.push({ slug, description });
-  }
-  return templates;
-}
-
 function formatStarterName(slug) {
   if (slug === '_none') return 'None';
   return slug
@@ -186,10 +126,6 @@ function formatStarterName(slug) {
     .join(' ');
 }
 
-function stampVersion(content) {
-  return content.replace(/^(---\s*\n[\s\S]*?)gspec-version:\s*.+/m, `$1gspec-version: ${pkg.version}`);
-}
-
 function promptSelect(message, choices) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   console.log(chalk.bold(`\n${message}\n`));
@@ -239,74 +175,119 @@ function promptMultiSelect(message, choices) {
   });
 }
 
-async function seedStarterTemplates(cwd) {
-  const wantStarters = await promptConfirm(chalk.bold('  Would you like to start from a starter template? [y/N]: '));
-  if (!wantStarters) {
-    console.log(chalk.dim('\n  Skipped starter templates.\n'));
-    return;
-  }
-
-  const practices = await listStarterTemplates('practices');
-  const stacks = await listStarterTemplates('stacks');
-  const styles = await listStarterTemplates('styles');
-  const features = await listStarterTemplates('features');
+async function seedFromSavedSpecs(cwd) {
+  // Skip if gspec specs already exist in the project
+  try {
+    const existingFiles = await collectGspecFiles(join(cwd, 'gspec'));
+    if (existingFiles.length > 0) {
+      return;
+    }
+  } catch {}
 
-  if (practices.length === 0 || stacks.length === 0 || styles.length === 0) {
-    console.log(chalk.yellow('  Missing starter templates (practices, stacks, or styles). Skipping.\n'));
-    return;
-  }
+  // Check if ~/.gspec/ has any saved specs or playbooks
+  const gspecHome = join(homedir(), '.gspec');
+  let hasPlaybooks = false;
+  let playbooks = [];
+  try {
+    const pbEntries = await readdir(join(gspecHome, 'playbooks'));
+    playbooks = pbEntries.filter((f) => f.endsWith('.md'));
+    hasPlaybooks = playbooks.length > 0;
+  } catch {}
 
-  const NONE_OPTION = { slug: '_none', description: 'I will define my own' };
+  let savedTypes = [];
+  try {
+    const entries = await readdir(gspecHome);
+    for (const entry of entries) {
+      if (entry === 'playbooks') continue;
+      try {
+        const info = await stat(join(gspecHome, entry));
+        if (info.isDirectory()) {
+          const files = await readdir(join(gspecHome, entry));
+          if (files.filter((f) => f.endsWith('.md')).length > 0) {
+            savedTypes.push(entry);
+          }
+        }
+      } catch {}
+    }
+  } catch {}
 
-  // Single-select with auto-select for single-option categories
-  const practice = practices.length === 1
-    ? (console.log(chalk.dim(`\n  Using practice: ${formatStarterName(practices[0].slug)}`)), practices[0].slug)
-    : await promptSelect('Select a development practice', [...practices, NONE_OPTION]);
+  // Nothing saved — skip silently
+  if (!hasPlaybooks && savedTypes.length === 0) return;
 
-  const stack = stacks.length === 1
-    ? (console.log(chalk.dim(`  Using stack: ${formatStarterName(stacks[0].slug)}`)), stacks[0].slug)
-    : await promptSelect('Select a technology stack', [...stacks, NONE_OPTION]);
+  const wantSaved = await promptConfirm(chalk.bold('  Would you like to start from saved specs in ~/.gspec/? [y/N]: '));
+  if (!wantSaved) {
+    console.log(chalk.dim('\n  Skipped saved specs.\n'));
+    return;
+  }
 
-  const style = styles.length === 1
-    ? (console.log(chalk.dim(`  Using style: ${formatStarterName(styles[0].slug)}`)), styles[0].slug)
-    : await promptSelect('Select a visual style', [...styles, NONE_OPTION]);
+  // If playbooks exist, offer them first
+  if (hasPlaybooks) {
+    const playbookChoices = [];
+    for (const f of playbooks) {
+      const slug = f.replace(/\.md$/, '');
+      const content = await readFile(join(gspecHome, 'playbooks', f), 'utf-8');
+      const { fields } = parseFrontmatter(content);
+      playbookChoices.push({ slug, description: fields.description || '' });
+    }
 
-  let selectedFeatures = [];
-  if (features.length > 0) {
-    selectedFeatures = await promptMultiSelect('Select features (optional)', [...features, NONE_OPTION]);
-    selectedFeatures = selectedFeatures.filter(f => f !== '_none');
-  }
+    const INDIVIDUAL_OPTION = { slug: '_individual', description: 'Pick individual specs instead' };
+    const selected = await promptSelect('Select a playbook', [...playbookChoices, INDIVIDUAL_OPTION]);
 
-  // Auto-include feature dependencies
-  if (selectedFeatures.length > 0) {
-    const resolved = resolveFeatureDependencies(selectedFeatures);
-    const added = resolved.filter((f) => !selectedFeatures.includes(f));
-    if (added.length > 0) {
-      console.log(chalk.cyan(`\n  Auto-including dependencies: ${added.map(formatStarterName).join(', ')}`));
-      selectedFeatures = resolved;
+    if (selected !== '_individual') {
+      await restorePlaybook(selected, cwd);
+      return;
     }
   }
 
-  // Check for existing files
+  // Individual spec selection from ~/.gspec/
+  const NONE_OPTION = { slug: '_none', description: 'Skip' };
   const gspecDir = join(cwd, 'gspec');
   const filesToWrite = [];
-  if (practice !== '_none') {
-    filesToWrite.push({ src: join(STARTERS_DIR, 'practices', `${practice}.md`), dest: join(gspecDir, 'practices.md'), label: 'gspec/practices.md' });
-  }
-  if (stack !== '_none') {
-    filesToWrite.push({ src: join(STARTERS_DIR, 'stacks', `${stack}.md`), dest: join(gspecDir, 'stack.md'), label: 'gspec/stack.md' });
-  }
-  if (style !== '_none') {
-    filesToWrite.push({ src: join(STARTERS_DIR, 'styles', `${style}.md`), dest: join(gspecDir, 'style.md'), label: 'gspec/style.md' });
+
+  const CATEGORY_ORDER = [
+    { type: 'profiles', label: 'Select a profile', dest: 'profile.md', mode: 'single' },
+    { type: 'practices', label: 'Select practices', dest: 'practices.md', mode: 'single' },
+    { type: 'stacks', label: 'Select a stack', dest: 'stack.md', mode: 'single' },
+    { type: 'styles', label: 'Select a style', dest: 'style.md', mode: 'single' },
+    { type: 'features', label: 'Select features (optional)', dest: null, mode: 'multi' },
+  ];
+
+  for (const cat of CATEGORY_ORDER) {
+    if (!savedTypes.includes(cat.type)) continue;
+
+    const specs = await listSavedSpecs(cat.type);
+    if (specs.length === 0) continue;
+
+    if (cat.mode === 'single') {
+      const selected = specs.length === 1
+        ? (console.log(chalk.dim(`\n  Using ${cat.type}: ${formatStarterName(specs[0].slug)}`)), specs[0].slug)
+        : await promptSelect(cat.label, [...specs, NONE_OPTION]);
+
+      if (selected !== '_none') {
+        filesToWrite.push({
+          src: join(gspecHome, cat.type, `${selected}.md`),
+          dest: join(gspecDir, cat.dest),
+          label: `gspec/${cat.dest}`,
+        });
+      }
+    } else {
+      let selectedSlugs = await promptMultiSelect(cat.label, specs);
+      for (const slug of selectedSlugs) {
+        filesToWrite.push({
+          src: join(gspecHome, cat.type, `${slug}.md`),
+          dest: join(gspecDir, 'features', `${slug}.md`),
+          label: `gspec/features/${slug}.md`,
+        });
+      }
+    }
   }
-  for (const feature of selectedFeatures) {
-    filesToWrite.push({
-      src: join(STARTERS_DIR, 'features', `${feature}.md`),
-      dest: join(gspecDir, 'features', `${feature}.md`),
-      label: `gspec/features/${feature}.md`,
-    });
+
+  if (filesToWrite.length === 0) {
+    console.log(chalk.dim('\n  No specs selected. You can define specs using gspec commands.\n'));
+    return;
   }
 
+  // Check for existing files
   const existingFiles = [];
   for (const f of filesToWrite) {
     try {
@@ -317,11 +298,6 @@ async function seedStarterTemplates(cwd) {
     }
   }
 
-  if (filesToWrite.length === 0) {
-    console.log(chalk.dim('\n  No starter templates selected. You can define these files using gspec commands.\n'));
-    return;
-  }
-
   if (existingFiles.length > 0) {
     console.log(chalk.yellow(`\n  The following files already exist and will be overwritten:\n`));
     for (const label of existingFiles) {
@@ -330,31 +306,36 @@ async function seedStarterTemplates(cwd) {
     console.log();
     const confirmed = await promptConfirm(chalk.bold('  Continue and overwrite? [y/N]: '));
     if (!confirmed) {
-      console.log(chalk.dim('\n  Skipped starter templates.\n'));
+      console.log(chalk.dim('\n  Skipped saved specs.\n'));
       return;
     }
   }
 
-  // Copy files with version stamping
-  console.log(chalk.bold('\n  Seeding starter templates...\n'));
+  // Copy files
+  console.log(chalk.bold('\n  Restoring saved specs...\n'));
+  const outdated = [];
   for (const f of filesToWrite) {
     await mkdir(dirname(f.dest), { recursive: true });
     const content = await readFile(f.src, 'utf-8');
-    await writeFile(f.dest, stampVersion(content), 'utf-8');
+    await writeFile(f.dest, content, 'utf-8');
     console.log(`  ${chalk.green('+')} ${f.label}`);
+
+    const version = parseSpecVersion(content);
+    if (version && version !== SPEC_VERSION) {
+      outdated.push({ label: f.label, version });
+    }
   }
 
-  // Summary
-  console.log(chalk.bold('\n  Seeded gspec/ with:'));
-  console.log(`    Practice: ${practice === '_none' ? chalk.dim('(will define)') : formatStarterName(practice)}`);
-  console.log(`    Stack:    ${stack === '_none' ? chalk.dim('(will define)') : formatStarterName(stack)}`);
-  console.log(`    Style:    ${style === '_none' ? chalk.dim('(will define)') : formatStarterName(style)}`);
-  if (selectedFeatures.length > 0) {
-    console.log(`    Features: ${selectedFeatures.map(formatStarterName).join(', ')}`);
-  } else {
-    console.log(`    Features: ${chalk.dim('(will define)')}`);
+  console.log(chalk.green(`\n  ✓ Restored ${filesToWrite.length} spec${filesToWrite.length === 1 ? '' : 's'} into gspec/\n`));
+
+  if (outdated.length > 0) {
+    console.log(chalk.yellow('  ⚠ The following restored specs are outdated:\n'));
+    for (const o of outdated) {
+      console.log(`    ${chalk.yellow('!')} ${o.label} — version ${o.version} (current: ${SPEC_VERSION})`);
+    }
+    console.log();
+    console.log(chalk.yellow(`  Run ${chalk.bold('/gspec-migrate')} to update them to the current format.\n`));
   }
-  console.log();
 }
 
 async function findExistingFiles(target, cwd) {
@@ -568,11 +549,14 @@ const MIGRATE_COMMANDS = {
   opencode: '/gspec-migrate',
 };
 
-function parseGspecVersion(content) {
+function parseSpecVersion(content) {
   const match = content.match(/^---\n([\s\S]*?)\n---/);
   if (!match) return null;
-  const versionMatch = match[1].match(/^gspec-version:\s*(.+)$/m);
-  return versionMatch ? versionMatch[1].trim() : null;
+  const newMatch = match[1].match(/^spec-version:\s*(.+)$/m);
+  if (newMatch) return newMatch[1].trim();
+  const oldMatch = match[1].match(/^gspec-version:\s*(.+)$/m);
+  if (oldMatch) return oldMatch[1].trim();
+  return null;
 }
 
 async function collectGspecFiles(gspecDir) {
@@ -617,8 +601,8 @@ async function checkGspecFiles(cwd, targetName) {
   const outdated = [];
   for (const file of files) {
     const content = await readFile(file.path, 'utf-8');
-    const version = parseGspecVersion(content);
-    if (version === pkg.version) continue;
+    const version = parseSpecVersion(content);
+    if (version === SPEC_VERSION) continue;
     outdated.push({
       label: file.label,
       version,
@@ -630,8 +614,8 @@ async function checkGspecFiles(cwd, targetName) {
   console.log(chalk.yellow(`  Found existing gspec files that may need updating:\n`));
   for (const file of outdated) {
     const status = file.version
-      ? `version ${file.version} (current: ${pkg.version})`
-      : `no version (pre-${pkg.version})`;
+      ? `version ${file.version} (current: ${SPEC_VERSION})`
+      : `no version (pre-${SPEC_VERSION})`;
     console.log(`    ${chalk.yellow('!')} ${file.label} — ${status}`);
   }
   console.log();
@@ -644,6 +628,600 @@ async function checkGspecFiles(cwd, targetName) {
   console.log(`    ${chalk.cyan(cmd)}\n`);
 }
 
+// --- Save / Restore ---
+
+const GSPEC_HOME = join(homedir(), '.gspec');
+
+// Map gspec/ file paths to save/restore type folders
+const GSPEC_TYPE_MAP = {
+  'profile.md': 'profiles',
+  'stack.md': 'stacks',
+  'style.md': 'styles',
+  'practices.md': 'practices',
+};
+
+// Reverse: restore type folder → gspec/ destination filename
+const RESTORE_DEST_MAP = {
+  profiles: 'profile.md',
+  stacks: 'stack.md',
+  styles: 'style.md',
+  practices: 'practices.md',
+  features: null, // features keep their own filename
+};
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!match) return { fields: {}, body: content };
+  const fields = {};
+  for (const line of match[1].split('\n')) {
+    const idx = line.indexOf(':');
+    if (idx > 0) {
+      fields[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+    }
+  }
+  return { fields, body: content.slice(match[0].length) };
+}
+
+function setFrontmatterField(content, key, value) {
+  const match = content.match(/^(---\s*\n)([\s\S]*?)(\n---)/);
+  if (!match) {
+    // No frontmatter — create one
+    return `---\n${key}: ${value}\n---\n${content}`;
+  }
+  const lines = match[2].split('\n');
+  const existing = lines.findIndex((l) => l.startsWith(`${key}:`));
+  if (existing >= 0) {
+    lines[existing] = `${key}: ${value}`;
+  } else {
+    // Insert name as first field
+    lines.unshift(`${key}: ${value}`);
+  }
+  return `${match[1]}${lines.join('\n')}${match[3]}${content.slice(match[0].length)}`;
+}
+
+function promptInput(message) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(message, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function collectSavableFiles(cwd) {
+  const gspecDir = join(cwd, 'gspec');
+  const files = [];
+
+  try {
+    await stat(gspecDir);
+  } catch (e) {
+    if (e.code === 'ENOENT') return files;
+    throw e;
+  }
+
+  // Top-level spec files
+  const topEntries = await readdir(gspecDir);
+  for (const entry of topEntries) {
+    if (!entry.endsWith('.md') || entry.toLowerCase() === 'readme.md') continue;
+    const type = GSPEC_TYPE_MAP[entry];
+    if (!type) continue;
+    files.push({
+      path: join(gspecDir, entry),
+      type,
+      label: `gspec/${entry}`,
+    });
+  }
+
+  // Feature files
+  try {
+    const featureEntries = await readdir(join(gspecDir, 'features'));
+    for (const entry of featureEntries) {
+      if (!entry.endsWith('.md')) continue;
+      files.push({
+        path: join(gspecDir, 'features', entry),
+        type: 'features',
+        label: `gspec/features/${entry}`,
+      });
+    }
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+
+  return files;
+}
+
+async function saveSpec(cwd) {
+  console.log(BANNER);
+
+  const files = await collectSavableFiles(cwd);
+  if (files.length === 0) {
+    console.error(chalk.red('\n  No gspec files found in gspec/ directory.\n'));
+    process.exit(1);
+  }
+
+  // Let user select which file to save
+  console.log(chalk.bold('\n  Which spec would you like to save?\n'));
+  for (let i = 0; i < files.length; i++) {
+    const content = await readFile(files[i].path, 'utf-8');
+    const { fields } = parseFrontmatter(content);
+    const desc = fields.description ? ` — ${fields.description}` : '';
+    console.log(`  ${chalk.cyan(String(i + 1))}) ${files[i].label}${chalk.dim(desc)}`);
+  }
+  console.log();
+
+  const answer = await promptInput(chalk.bold(`  Select [1-${files.length}]: `));
+  const num = parseInt(answer, 10);
+  if (isNaN(num) || num < 1 || num > files.length) {
+    console.error(chalk.red(`\n  Invalid selection: "${answer}"`));
+    process.exit(1);
+  }
+
+  const selected = files[num - 1];
+
+  // Prompt for name
+  const name = await promptInput(chalk.bold('\n  Save name (no spaces, e.g. my-saas-stack): '));
+  if (!name) {
+    console.error(chalk.red('\n  Name is required.'));
+    process.exit(1);
+  }
+  if (/\s/.test(name)) {
+    console.error(chalk.red('\n  Name cannot contain spaces. Use hyphens instead (e.g. my-saas-stack).'));
+    process.exit(1);
+  }
+
+  // Read content and update frontmatter with name
+  let content = await readFile(selected.path, 'utf-8');
+  content = setFrontmatterField(content, 'name', name);
+
+  // Ensure description exists
+  const { fields } = parseFrontmatter(content);
+  if (!fields.description) {
+    const desc = await promptInput(chalk.bold('  Description (short summary): '));
+    if (desc) {
+      content = setFrontmatterField(content, 'description', desc);
+    }
+  }
+
+  // Write to ~/.gspec/{type}/{name}.md
+  const destDir = join(GSPEC_HOME, selected.type);
+  const destPath = join(destDir, `${name}.md`);
+  await mkdir(destDir, { recursive: true });
+
+  // Check if file already exists
+  try {
+    await stat(destPath);
+    const overwrite = await promptConfirm(chalk.yellow(`\n  ${selected.type}/${name} already exists. Overwrite? [y/N]: `));
+    if (!overwrite) {
+      console.log(chalk.dim('\n  Save cancelled.\n'));
+      return;
+    }
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+
+  // Uncheck all implementation checkboxes so saved specs start fresh
+  content = content.replace(/- \[x\]/g, '- [ ]');
+
+  await writeFile(destPath, content, 'utf-8');
+  console.log(chalk.green(`\n  ✓ Saved to ~/.gspec/${selected.type}/${name}.md\n`));
+}
+
+async function listSavedTypes() {
+  const types = [];
+  try {
+    const entries = await readdir(GSPEC_HOME);
+    for (const entry of entries) {
+      try {
+        const info = await stat(join(GSPEC_HOME, entry));
+        if (info.isDirectory()) {
+          const files = await readdir(join(GSPEC_HOME, entry));
+          const mdFiles = files.filter((f) => f.endsWith('.md'));
+          if (mdFiles.length > 0) types.push(entry);
+        }
+      } catch { /* skip */ }
+    }
+  } catch (e) {
+    if (e.code === 'ENOENT') return types;
+    throw e;
+  }
+  return types;
+}
+
+async function listSavedSpecs(type) {
+  const dir = join(GSPEC_HOME, type);
+  const entries = await readdir(dir);
+  const specs = [];
+  for (const entry of entries) {
+    if (!entry.endsWith('.md')) continue;
+    const content = await readFile(join(dir, entry), 'utf-8');
+    const { fields } = parseFrontmatter(content);
+    specs.push({
+      slug: entry.replace(/\.md$/, ''),
+      description: fields.description || '',
+    });
+  }
+  return specs;
+}
+
+async function restoreSpec(specPath, cwd) {
+  console.log(BANNER);
+
+  if (specPath) {
+    // Direct restore: e.g. "stacks/web", "features/auth-flow", or "playbook/my-starter"
+    const parts = specPath.split('/');
+    if (parts.length !== 2) {
+      console.error(chalk.red(`\n  Invalid format. Use: type/name (e.g. stacks/my-stack, playbook/my-starter)\n`));
+      process.exit(1);
+    }
+    const [type, name] = parts;
+    if (type === 'playbook' || type === 'playbooks') {
+      await restorePlaybook(name, cwd);
+    } else {
+      await restoreFile(type, name, cwd);
+    }
+    return;
+  }
+
+  // Interactive: pick type, then file
+  const types = await listSavedTypes();
+  if (types.length === 0) {
+    console.error(chalk.red('\n  No saved specs found in ~/.gspec/'));
+    console.error(chalk.dim('  Use "gspec save" to save specs first.\n'));
+    process.exit(1);
+  }
+
+  console.log(chalk.bold('\n  Select a spec type:\n'));
+  for (let i = 0; i < types.length; i++) {
+    console.log(`  ${chalk.cyan(String(i + 1))}) ${types[i]}`);
+  }
+  console.log();
+
+  const typeAnswer = await promptInput(chalk.bold(`  Select [1-${types.length}]: `));
+  const typeNum = parseInt(typeAnswer, 10);
+  if (isNaN(typeNum) || typeNum < 1 || typeNum > types.length) {
+    console.error(chalk.red(`\n  Invalid selection: "${typeAnswer}"`));
+    process.exit(1);
+  }
+
+  const selectedType = types[typeNum - 1];
+  const specs = await listSavedSpecs(selectedType);
+
+  if (specs.length === 0) {
+    console.error(chalk.red(`\n  No specs found in ~/.gspec/${selectedType}/\n`));
+    process.exit(1);
+  }
+
+  console.log(chalk.bold(`\n  Select a spec from ${selectedType}:\n`));
+  for (let i = 0; i < specs.length; i++) {
+    const desc = specs[i].description ? ` — ${specs[i].description}` : '';
+    console.log(`  ${chalk.cyan(String(i + 1))}) ${specs[i].slug}${chalk.dim(desc)}`);
+  }
+  console.log();
+
+  const specAnswer = await promptInput(chalk.bold(`  Select [1-${specs.length}]: `));
+  const specNum = parseInt(specAnswer, 10);
+  if (isNaN(specNum) || specNum < 1 || specNum > specs.length) {
+    console.error(chalk.red(`\n  Invalid selection: "${specAnswer}"`));
+    process.exit(1);
+  }
+
+  await restoreFile(selectedType, specs[specNum - 1].slug, cwd);
+}
+
+async function restoreFile(type, name, cwd) {
+  const srcPath = join(GSPEC_HOME, type, `${name}.md`);
+
+  try {
+    await stat(srcPath);
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      console.error(chalk.red(`\n  Not found: ~/.gspec/${type}/${name}.md\n`));
+      process.exit(1);
+    }
+    throw e;
+  }
+
+  const gspecDir = join(cwd, 'gspec');
+  let destPath;
+
+  if (type === 'features') {
+    destPath = join(gspecDir, 'features', `${name}.md`);
+  } else {
+    const destFile = RESTORE_DEST_MAP[type];
+    if (!destFile) {
+      console.error(chalk.red(`\n  Unknown spec type: ${type}\n`));
+      process.exit(1);
+    }
+    destPath = join(gspecDir, destFile);
+  }
+
+  // Check for existing file
+  try {
+    await stat(destPath);
+    const relPath = destPath.slice(cwd.length + 1);
+    const overwrite = await promptConfirm(chalk.yellow(`\n  ${relPath} already exists. Overwrite? [y/N]: `));
+    if (!overwrite) {
+      console.log(chalk.dim('\n  Restore cancelled.\n'));
+      return;
+    }
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+
+  await mkdir(dirname(destPath), { recursive: true });
+  const content = await readFile(srcPath, 'utf-8');
+  await writeFile(destPath, content, 'utf-8');
+
+  const relDest = destPath.slice(cwd.length + 1);
+  console.log(chalk.green(`\n  ✓ Restored ${type}/${name} → ${relDest}\n`));
+
+  const version = parseSpecVersion(content);
+  if (version && version !== SPEC_VERSION) {
+    console.log(chalk.yellow(`  ⚠ ${relDest} is version ${version} (current: ${SPEC_VERSION})`));
+    console.log(chalk.yellow(`    Run ${chalk.bold('/gspec-migrate')} to update it to the current format.\n`));
+  }
+}
+
+// --- Playbooks ---
+
+async function listSavedSpecsSafe(type) {
+  try {
+    return await listSavedSpecs(type);
+  } catch (e) {
+    if (e.code === 'ENOENT') return [];
+    throw e;
+  }
+}
+
+async function createPlaybook() {
+  console.log(BANNER);
+  console.log(chalk.bold('\n  Create a playbook\n'));
+  console.log(chalk.dim('  A playbook bundles saved specs so you can restore them all at once.\n'));
+
+  const NONE_OPTION = { slug: '_none', description: 'Skip' };
+
+  // --- Profile (0 or 1) ---
+  const profiles = await listSavedSpecsSafe('profiles');
+  let profile = null;
+  if (profiles.length > 0) {
+    profile = await promptSelect('Select a profile (or skip)', [...profiles, NONE_OPTION]);
+    if (profile === '_none') profile = null;
+  } else {
+    console.log(chalk.dim('  No saved profiles found — skipping.\n'));
+  }
+
+  // --- Stack (0 or 1) ---
+  const stacks = await listSavedSpecsSafe('stacks');
+  let stack = null;
+  if (stacks.length > 0) {
+    stack = await promptSelect('Select a stack (or skip)', [...stacks, NONE_OPTION]);
+    if (stack === '_none') stack = null;
+  } else {
+    console.log(chalk.dim('  No saved stacks found — skipping.\n'));
+  }
+
+  // --- Practices (0 or 1) ---
+  const practices = await listSavedSpecsSafe('practices');
+  let practice = null;
+  if (practices.length > 0) {
+    practice = await promptSelect('Select practices (or skip)', [...practices, NONE_OPTION]);
+    if (practice === '_none') practice = null;
+  } else {
+    console.log(chalk.dim('  No saved practices found — skipping.\n'));
+  }
+
+  // --- Style (0 or 1) ---
+  const styles = await listSavedSpecsSafe('styles');
+  let style = null;
+  if (styles.length > 0) {
+    style = await promptSelect('Select a style (or skip)', [...styles, NONE_OPTION]);
+    if (style === '_none') style = null;
+  } else {
+    console.log(chalk.dim('  No saved styles found — skipping.\n'));
+  }
+
+  // --- Features (0 to many) ---
+  const features = await listSavedSpecsSafe('features');
+  let selectedFeatures = [];
+  if (features.length > 0) {
+    selectedFeatures = await promptMultiSelect('Select features (optional)', features);
+  } else {
+    console.log(chalk.dim('  No saved features found — skipping.\n'));
+  }
+
+  // Check that at least one spec was selected
+  if (!profile && !stack && !practice && !style && selectedFeatures.length === 0) {
+    console.error(chalk.red('\n  No specs selected. Playbook not created.\n'));
+    process.exit(1);
+  }
+
+  // Prompt for playbook name
+  const name = await promptInput(chalk.bold('\n  Playbook name (no spaces, e.g. my-saas-starter): '));
+  if (!name) {
+    console.error(chalk.red('\n  Name is required.'));
+    process.exit(1);
+  }
+  if (/\s/.test(name)) {
+    console.error(chalk.red('\n  Name cannot contain spaces. Use hyphens instead (e.g. my-saas-starter).'));
+    process.exit(1);
+  }
+
+  // Prompt for description
+  const description = await promptInput(chalk.bold('  Description (short summary): '));
+
+  // Build playbook content
+  const lines = ['---'];
+  lines.push(`name: ${name}`);
+  if (description) lines.push(`description: ${description}`);
+  lines.push('---', '');
+  if (profile) lines.push(`profile: ${profile}`);
+  if (stack) lines.push(`stack: ${stack}`);
+  if (practice) lines.push(`practices: ${practice}`);
+  if (style) lines.push(`style: ${style}`);
+  if (selectedFeatures.length > 0) {
+    lines.push('features:');
+    for (const f of selectedFeatures) {
+      lines.push(`  - ${f}`);
+    }
+  }
+  lines.push('');
+
+  // Write playbook
+  const destDir = join(GSPEC_HOME, 'playbooks');
+  const destPath = join(destDir, `${name}.md`);
+  await mkdir(destDir, { recursive: true });
+
+  try {
+    await stat(destPath);
+    const overwrite = await promptConfirm(chalk.yellow(`\n  Playbook "${name}" already exists. Overwrite? [y/N]: `));
+    if (!overwrite) {
+      console.log(chalk.dim('\n  Cancelled.\n'));
+      return;
+    }
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+
+  await writeFile(destPath, lines.join('\n'), 'utf-8');
+
+  // Summary
+  console.log(chalk.green(`\n  ✓ Playbook saved to ~/.gspec/playbooks/${name}.md\n`));
+  console.log(chalk.bold('  Contents:'));
+  if (profile) console.log(`    Profile:   ${formatStarterName(profile)}`);
+  if (stack) console.log(`    Stack:     ${formatStarterName(stack)}`);
+  if (practice) console.log(`    Practices: ${formatStarterName(practice)}`);
+  if (style) console.log(`    Style:     ${formatStarterName(style)}`);
+  if (selectedFeatures.length > 0) {
+    console.log(`    Features:  ${selectedFeatures.map(formatStarterName).join(', ')}`);
+  }
+  console.log();
+  console.log(chalk.dim(`  Restore with: gspec restore playbook/${name}\n`));
+}
+
+function parsePlaybook(content) {
+  const { fields } = parseFrontmatter(content);
+  const body = content.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, '');
+  const result = { name: fields.name || '', description: fields.description || '' };
+
+  for (const line of body.split('\n')) {
+    const match = line.match(/^(\w+):\s*(.+)$/);
+    if (match) {
+      const [, key, value] = match;
+      if (key !== 'features') result[key] = value.trim();
+    }
+  }
+
+  // Parse features list
+  const featuresMatch = body.match(/^features:\s*\n((?:\s+-\s+.+\n?)+)/m);
+  if (featuresMatch) {
+    result.features = featuresMatch[1]
+      .split('\n')
+      .map((l) => l.replace(/^\s+-\s+/, '').trim())
+      .filter(Boolean);
+  } else {
+    result.features = [];
+  }
+
+  return result;
+}
+
+async function restorePlaybook(name, cwd) {
+  const srcPath = join(GSPEC_HOME, 'playbooks', `${name}.md`);
+
+  try {
+    await stat(srcPath);
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      console.error(chalk.red(`\n  Not found: ~/.gspec/playbooks/${name}.md\n`));
+      process.exit(1);
+    }
+    throw e;
+  }
+
+  const content = await readFile(srcPath, 'utf-8');
+  const playbook = parsePlaybook(content);
+
+  console.log(chalk.bold(`\n  Restoring playbook: ${playbook.name || name}\n`));
+  if (playbook.description) console.log(chalk.dim(`  ${playbook.description}\n`));
+
+  const gspecDir = join(cwd, 'gspec');
+  await mkdir(gspecDir, { recursive: true });
+
+  const restorations = [];
+  if (playbook.profile) restorations.push({ type: 'profiles', slug: playbook.profile });
+  if (playbook.stack) restorations.push({ type: 'stacks', slug: playbook.stack });
+  if (playbook.practices) restorations.push({ type: 'practices', slug: playbook.practices });
+  if (playbook.style) restorations.push({ type: 'styles', slug: playbook.style });
+  for (const f of playbook.features) {
+    restorations.push({ type: 'features', slug: f });
+  }
+
+  // Check for existing files
+  const existing = [];
+  for (const r of restorations) {
+    const destFile = r.type === 'features' ? join('features', `${r.slug}.md`) : RESTORE_DEST_MAP[r.type];
+    const destPath = join(gspecDir, destFile);
+    try {
+      await stat(destPath);
+      existing.push(`gspec/${destFile}`);
+    } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+  }
+
+  if (existing.length > 0) {
+    console.log(chalk.yellow('  The following files already exist and will be overwritten:\n'));
+    for (const label of existing) {
+      console.log(`    ${chalk.yellow('!')} ${label}`);
+    }
+    console.log();
+    const confirmed = await promptConfirm(chalk.bold('  Continue and overwrite? [y/N]: '));
+    if (!confirmed) {
+      console.log(chalk.dim('\n  Restore cancelled.\n'));
+      return;
+    }
+  }
+
+  // Restore all specs
+  const outdated = [];
+  for (const r of restorations) {
+    const srcFile = join(GSPEC_HOME, r.type, `${r.slug}.md`);
+    try {
+      await stat(srcFile);
+    } catch (e) {
+      if (e.code === 'ENOENT') {
+        console.log(`  ${chalk.yellow('!')} Skipped ${r.type}/${r.slug} — not found in ~/.gspec/`);
+        continue;
+      }
+      throw e;
+    }
+
+    const destFile = r.type === 'features' ? join('features', `${r.slug}.md`) : RESTORE_DEST_MAP[r.type];
+    const destPath = join(gspecDir, destFile);
+    await mkdir(dirname(destPath), { recursive: true });
+    const specContent = await readFile(srcFile, 'utf-8');
+    await writeFile(destPath, specContent, 'utf-8');
+    console.log(`  ${chalk.green('+')} gspec/${destFile}`);
+
+    const version = parseSpecVersion(specContent);
+    if (version && version !== SPEC_VERSION) {
+      outdated.push({ label: `gspec/${destFile}`, version });
+    }
+  }
+
+  console.log(chalk.green(`\n  ✓ Playbook "${playbook.name || name}" restored.\n`));
+
+  if (outdated.length > 0) {
+    console.log(chalk.yellow('  ⚠ The following restored specs are outdated:\n'));
+    for (const o of outdated) {
+      console.log(`    ${chalk.yellow('!')} ${o.label} — version ${o.version} (current: ${SPEC_VERSION})`);
+    }
+    console.log();
+    console.log(chalk.yellow(`  Run ${chalk.bold('/gspec-migrate')} to update them to the current format.\n`));
+  }
+}
+
 program
   .name('gspec')
   .description('Install gspec specification commands')
@@ -660,25 +1238,53 @@ program
 
     await install(targetName, process.cwd());
 
-    await seedStarterTemplates(process.cwd());
+    await seedFromSavedSpecs(process.cwd());
 
     await installSpecSync(targetName, process.cwd());
 
     await checkGspecFiles(process.cwd(), targetName);
 
-    // Post-install: instruct user to generate profile.md
+    // Post-install: instruct user to generate profile.md (only if it doesn't already exist)
+    const profilePath = join(process.cwd(), 'gspec', 'profile.md');
+    let profileExists = false;
+    try { await stat(profilePath); profileExists = true; } catch {}
+
     const targetLabel = TARGETS[targetName].label;
-    console.log();
-    console.log(chalk.bold.cyan('  ═══ Next Step ═══════════════════════════════════════════════'));
-    console.log();
-    console.log(chalk.bold.white('  Generate your product profile before continuing.'));
-    console.log();
-    console.log(`  Run ${chalk.bold.yellow('/gspec-profile')} in ${targetLabel} to create gspec/profile.md`);
-    console.log(`  — it defines what your product is, who it serves, and why it`);
-    console.log(`  exists. All other gspec commands use the profile as their foundation.`);
-    console.log();
-    console.log(chalk.bold.cyan('  ═════════════════════════════════════════════════════════════'));
-    console.log();
+    if (!profileExists) {
+      console.log();
+      console.log(chalk.bold.cyan('  ═══ Next Step ═══════════════════════════════════════════════'));
+      console.log();
+      console.log(chalk.bold.white('  Generate your product profile before continuing.'));
+      console.log();
+      console.log(`  Run ${chalk.bold.yellow('/gspec-profile')} in ${targetLabel} to create gspec/profile.md`);
+      console.log(`  — it defines what your product is, who it serves, and why it`);
+      console.log(`  exists. All other gspec commands use the profile as their foundation.`);
+      console.log();
+      console.log(chalk.bold.cyan('  ═════════════════════════════════════════════════════════════'));
+      console.log();
+    }
+  });
+
+program
+  .command('save')
+  .description('Save a gspec spec to ~/.gspec for reuse across projects')
+  .action(async () => {
+    await saveSpec(process.cwd());
+  });
+
+program
+  .command('restore')
+  .description('Restore a saved spec from ~/.gspec into the current project')
+  .argument('[spec]', 'spec to restore (e.g. stacks/my-stack, playbook/my-starter)')
+  .action(async (spec) => {
+    await restoreSpec(spec, process.cwd());
+  });
+
+program
+  .command('playbook')
+  .description('Create a playbook that bundles saved specs for quick project setup')
+  .action(async () => {
+    await createPlaybook();
   });
 
 program.parse();