multi-agents-cli 1.0.0

package/init.js

@@ -0,0 +1,1098 @@
+#!/usr/bin/env node
+
+/**
+ * multi-agents - Project Initializer
+ * Run with: npm run init           (inside existing project)
+ *        or: multi-agents init my-project  (global CLI)
+ *
+ * Runs once. Locked after completion via .scaffold/.initialized
+ */
+
+const readline  = require('readline');
+const fs        = require('fs');
+const path      = require('path');
+const os        = require('os');
+const { execSync, spawn } = require('child_process');
+
+// ── Colors ────────────────────────────────────────────────────────────────────
+
+const c = {
+  reset:  '\x1b[0m',
+  bold:   '\x1b[1m',
+  dim:    '\x1b[2m',
+  green:  '\x1b[32m',
+  blue:   '\x1b[34m',
+  yellow: '\x1b[33m',
+  cyan:   '\x1b[36m',
+  red:    '\x1b[31m',
+};
+
+const bold   = (s) => `${c.bold}${s}${c.reset}`;
+const green  = (s) => `${c.green}${s}${c.reset}`;
+const yellow = (s) => `${c.yellow}${s}${c.reset}`;
+const dim    = (s) => `${c.dim}${s}${c.reset}`;
+const cyan   = (s) => `${c.cyan}${s}${c.reset}`;
+const blue   = (s) => `${c.blue}${s}${c.reset}`;
+const red    = (s) => `${c.red}${s}${c.reset}`;
+
+// ── CLI argument handling ─────────────────────────────────────────────────────
+
+const args       = process.argv.slice(2);
+const isGlobalCLI = args[0] === 'init' && args[1];
+const projectArg  = isGlobalCLI ? args[1] : null;
+
+if (isGlobalCLI) {
+  const targetDir = path.resolve(process.cwd(), projectArg);
+
+  if (fs.existsSync(targetDir)) {
+    console.log(`\n${red(`  ✗ Directory "${projectArg}" already exists.`)}`);
+    console.log(dim('  Choose a different project name.\n'));
+    process.exit(1);
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  process.chdir(targetDir);
+
+  // Initialize git
+  try {
+    execSync('git init', { cwd: targetDir, stdio: 'pipe' });
+    execSync('git commit --allow-empty -m "init: project created"', { cwd: targetDir, stdio: 'pipe' });
+  } catch { /* git may not have user config yet — continue */ }
+}
+
+// ── Lock check ────────────────────────────────────────────────────────────────
+
+const ROOT        = process.cwd();
+const RUNTIME_DIR = path.join(ROOT, '.scaffold');
+const LOCK_FILE   = path.join(RUNTIME_DIR, '.initialized');
+
+// ── Decision tree ─────────────────────────────────────────────────────────────
+
+const CLIENT_FRAMEWORKS = [
+  { label: 'Next.js',       value: 'Next.js',    language: 'TypeScript', integratedBackend: true  },
+  { label: 'Angular',       value: 'Angular',    language: 'TypeScript', integratedBackend: false },
+  { label: 'Vue / Nuxt',    value: 'Nuxt',       language: 'TypeScript', integratedBackend: true  },
+  { label: 'SvelteKit',     value: 'SvelteKit',  language: 'TypeScript', integratedBackend: true  },
+  { label: 'Remix',         value: 'Remix',      language: 'TypeScript', integratedBackend: true  },
+  { label: 'Vite + React',  value: 'Vite+React', language: 'TypeScript', integratedBackend: false },
+];
+
+const BACKEND_FRAMEWORKS = [
+  { label: 'NestJS',   value: 'NestJS',   language: 'TypeScript' },
+  { label: 'Express',  value: 'Express',  language: 'TypeScript' },
+  { label: 'Fastify',  value: 'Fastify',  language: 'TypeScript' },
+  { label: 'Django',   value: 'Django',   language: 'Python'     },
+  { label: 'Laravel',  value: 'Laravel',  language: 'PHP'        },
+  { label: 'Rails',    value: 'Rails',    language: 'Ruby'       },
+];
+
+const STATE_OPTIONS = {
+  'Next.js':    ['Zustand', 'Redux Toolkit', 'Jotai', 'TanStack Query'],
+  'Vite+React': ['Zustand', 'Redux Toolkit', 'Jotai', 'TanStack Query'],
+  'Remix':      ['Zustand', 'Redux Toolkit', 'Jotai', 'TanStack Query'],
+  'Angular':    ['NgRx', 'Signals (built-in)', 'Akita'],
+  'Nuxt':       ['Pinia', 'Vuex'],
+  'SvelteKit':  ['Svelte stores (built-in)', 'Zustand'],
+};
+
+const UI_OPTIONS = {
+  'Next.js':    ['shadcn/ui', 'Radix UI', 'MUI', 'Chakra UI', 'Ant Design'],
+  'Vite+React': ['shadcn/ui', 'Radix UI', 'MUI', 'Chakra UI', 'Ant Design'],
+  'Remix':      ['shadcn/ui', 'Radix UI', 'MUI', 'Chakra UI', 'Ant Design'],
+  'Angular':    ['Angular Material', 'PrimeNG', 'Clarity'],
+  'Nuxt':       ['Vuetify', 'PrimeVue', 'Naive UI'],
+  'SvelteKit':  ['Skeleton', 'daisyUI', 'shadcn-svelte'],
+};
+
+const STYLING_OPTIONS = [
+  'Tailwind CSS',
+  'CSS Modules',
+  'Styled Components',
+  'SCSS / SASS',
+  'UnoCSS',
+];
+
+const ORM_OPTIONS = {
+  'NestJS':   ['TypeORM', 'Prisma', 'MikroORM', 'Drizzle'],
+  'Express':  ['Prisma', 'TypeORM', 'Drizzle', 'Sequelize'],
+  'Fastify':  ['Prisma', 'TypeORM', 'Drizzle'],
+  'Django':   ['Django ORM (built-in)', 'SQLAlchemy'],
+  'Laravel':  ['Eloquent (built-in)'],
+  'Rails':    ['Active Record (built-in)'],
+};
+
+const AUTH_OPTIONS = {
+  'NestJS':   ['Passport.js', 'JWT-only', 'OAuth2', 'Auth.js'],
+  'Express':  ['Passport.js', 'JWT-only', 'OAuth2'],
+  'Fastify':  ['fastify-jwt', 'Passport.js', 'OAuth2'],
+  'Django':   ['Django Auth (built-in)', 'DRF TokenAuth', 'OAuth2'],
+  'Laravel':  ['Laravel Sanctum', 'Laravel Passport', 'JWT'],
+  'Rails':    ['Devise', 'JWT', 'OAuth2'],
+};
+
+const IDE_CANDIDATES = [
+  {
+    cmd:     'code',
+    name:    'VS Code',
+    mac:     { app: 'Visual Studio Code', args: ['--new-window'] },
+    win:     { paths: ['{LOCALAPPDATA}\\Programs\\Microsoft VS Code\\Code.exe', '{ProgramFiles}\\Microsoft VS Code\\Code.exe'], args: ['--new-window'] },
+    linux:   { paths: ['/snap/bin/code', '/usr/bin/code', '/usr/local/bin/code'], args: ['--new-window'] },
+  },
+  {
+    cmd:     'cursor',
+    name:    'Cursor',
+    mac:     { app: 'Cursor', args: ['--new-window'] },
+    win:     { paths: ['{LOCALAPPDATA}\\Programs\\cursor\\Cursor.exe'], args: ['--new-window'] },
+    linux:   { paths: ['/usr/bin/cursor', '/opt/cursor/cursor'], args: ['--new-window'] },
+  },
+  {
+    cmd:     'webstorm',
+    name:    'WebStorm',
+    note:    'requires CLI launcher via Toolbox',
+    mac:     { app: 'WebStorm', args: [] },
+    win:     { paths: [], args: [] },
+    linux:   { paths: ['/opt/webstorm/bin/webstorm.sh'], args: [] },
+  },
+  {
+    cmd:     'idea',
+    name:    'IntelliJ IDEA',
+    note:    'requires CLI launcher via Toolbox',
+    mac:     { app: 'IntelliJ IDEA', args: [] },
+    win:     { paths: [], args: [] },
+    linux:   { paths: ['/opt/idea/bin/idea.sh'], args: [] },
+  },
+  {
+    cmd:     'zed',
+    name:    'Zed',
+    mac:     { app: 'Zed', args: [] },
+    win:     { paths: [], args: [] },
+    linux:   { paths: ['/usr/bin/zed', `${os.homedir()}/.local/bin/zed`], args: [] },
+  },
+  {
+    cmd:  null,
+    name: 'Other / Manual',
+    note: 'prints worktree path, open it yourself',
+    mac:  null,
+    win:  null,
+    linux:null,
+  },
+];
+
+// Expands {LOCALAPPDATA} / {ProgramFiles} placeholders for Windows paths
+const expandWinPath = (p) =>
+  p.replace('{LOCALAPPDATA}',  process.env.LOCALAPPDATA  || '')
+   .replace('{ProgramFiles}',  process.env.ProgramFiles  || 'C:\\Program Files');
+
+const buildIDEOptions = () => {
+  const platform = process.platform;
+
+  return IDE_CANDIDATES.map(ide => {
+    if (!ide.cmd) {
+      const noteStr = ide.note ? dim(`  (${ide.note})`) : '';
+      return { ...ide, detected: false, strategy: 'manual', label: `${ide.name}   ${dim('→')}${noteStr}` };
+    }
+
+    let detected  = false;
+    let strategy  = 'cli';
+
+    if (platform === 'darwin' && ide.mac) {
+      // Mac — check .app bundle in /Applications or ~/Applications
+      const system = `/Applications/${ide.mac.app}.app`;
+      const user   = path.join(os.homedir(), 'Applications', `${ide.mac.app}.app`);
+      detected = fs.existsSync(system) || fs.existsSync(user);
+      if (detected) strategy = 'mac-app';
+
+    } else if (platform === 'win32' && ide.win) {
+      // Windows — CLI first, then known exe paths
+      try {
+        execSync(`where ${ide.cmd}`, { stdio: 'pipe' });
+        detected = true;
+        strategy  = 'cli';
+      } catch {
+        const expanded = (ide.win.paths || []).map(expandWinPath);
+        detected = expanded.some(p => fs.existsSync(p));
+        if (detected) strategy = 'win-exe';
+      }
+
+    } else if (platform === 'linux' && ide.linux) {
+      // Linux — CLI first, then known install paths
+      try {
+        execSync(`which ${ide.cmd}`, { stdio: 'pipe' });
+        detected = true;
+        strategy  = 'cli';
+      } catch {
+        detected = (ide.linux.paths || []).some(p => fs.existsSync(p));
+        if (detected) strategy = 'linux-path';
+      }
+    }
+
+    const statusStr = detected ? green('✓ detected') : dim('✗ not found');
+    const noteStr   = ide.note ? dim(`  (${ide.note})`) : '';
+    return {
+      ...ide,
+      detected,
+      strategy,
+      label: `${ide.name}   ${statusStr}${noteStr}`,
+    };
+  });
+};
+
+const verifyIDE = (ide) => {
+  const platform = process.platform;
+
+  if (ide.strategy === 'mac-app' && ide.mac) {
+    // Mac — confirm .app exists and try to read version from plist
+    const appPath = `/Applications/${ide.mac.app}.app`;
+    if (!fs.existsSync(appPath) && !fs.existsSync(path.join(os.homedir(), 'Applications', `${ide.mac.app}.app`))) {
+      return { ok: false };
+    }
+    try {
+      const version = execSync(
+        `defaults read "/Applications/${ide.mac.app}.app/Contents/Info.plist" CFBundleShortVersionString`,
+        { stdio: 'pipe', encoding: 'utf8' }
+      ).trim();
+      return { ok: true, version };
+    } catch {
+      return { ok: true, version: null };
+    }
+  }
+
+  // Windows exe / Linux path / CLI — try --version
+  try {
+    const cmd = ide.strategy === 'win-exe'
+      ? `"${(ide.win?.paths || []).map(expandWinPath).find(p => fs.existsSync(p))}"`
+      : ide.strategy === 'linux-path'
+        ? `"${(ide.linux?.paths || []).find(p => fs.existsSync(p))}"`
+        : `"${ide.cmd}"`;
+    const result  = execSync(`${cmd} --version`, { stdio: 'pipe', encoding: 'utf8' });
+    const version = result.split('\n')[0].trim();
+    return { ok: true, version };
+  } catch {
+    return { ok: false };
+  }
+};
+
+// ── Tracking structure ────────────────────────────────────────────────────────
+
+const emptySlot = () => ({
+  branch:       null,
+  timestamp:    null,
+  launchedAt:   null,
+  status:       null,
+  missingCount: 0,
+  worktreePath: null,
+});
+
+const generateTrackingStructure = (config) => {
+  const bt = config.backend?.type;
+
+  const structure = {
+    client: {
+      UI:            emptySlot(),
+      LOGIC:         emptySlot(),
+      FORMS:         emptySlot(),
+      ROUTING:       emptySlot(),
+      TESTING:       emptySlot(),
+      ACCESSIBILITY: emptySlot(),
+    },
+    shared: {
+      SECURITY: emptySlot(),
+    },
+  };
+
+  if (bt === 'separate') {
+    structure.backend = {
+      API:     emptySlot(),
+      LOGIC:   emptySlot(),
+      AUTH:    emptySlot(),
+      DB:      emptySlot(),
+      EVENTS:  emptySlot(),
+      JOBS:    emptySlot(),
+      TESTING: emptySlot(),
+    };
+  }
+
+  return structure;
+};
+
+// ── GitHub remote setup ───────────────────────────────────────────────────────
+
+const detectGitHubUser = () => {
+  try {
+    return execSync('gh api user --jq .login',
+      { encoding: 'utf8', stdio: 'pipe' }).trim();
+  } catch {}
+  try {
+    return execSync('git config user.name',
+      { encoding: 'utf8', stdio: 'pipe' }).trim();
+  } catch {}
+  return null;
+};
+
+const setupUserRemote = (ROOT, projectName) => {
+  let currentOrigin = null;
+  try {
+    currentOrigin = execSync('git remote get-url origin',
+      { cwd: ROOT, encoding: 'utf8', stdio: 'pipe' }).trim();
+  } catch {}
+
+  // Already has their own remote — nothing to do
+  if (currentOrigin && !currentOrigin.includes('multi-agents-template')) return;
+
+  // Demote template origin to upstream
+  if (currentOrigin?.includes('multi-agents-template')) {
+    try {
+      execSync('git remote remove origin', { cwd: ROOT, stdio: 'pipe' });
+      execSync(`git remote add upstream ${currentOrigin}`, { cwd: ROOT, stdio: 'pipe' });
+      console.log(dim('  ℹ Template remote moved to upstream'));
+    } catch {}
+  }
+
+  // Write flag — agent will handle remote setup on first session
+  const flagPath = path.join(ROOT, '.scaffold', '.remote-setup-needed');
+  fs.writeFileSync(flagPath, JSON.stringify({
+    projectName,
+    createdAt: new Date().toISOString(),
+  }), 'utf8');
+
+  console.log(`\n  ${yellow('ℹ No remote configured.')} Your first agent session will set this up.`);
+  console.log(dim('  All work stays local until then.\n'));
+};
+
+const renderTrajectoryLines = (lines) => {
+  const HEADERS = ['Benefits', 'Best for', 'Use agents for', 'Handle manually'];
+  lines.forEach(l => {
+    if (!l) { console.log(''); return; }
+    if (l.startsWith('⚠'))         console.log(`  ${yellow(l)}`);
+    else if (HEADERS.includes(l))  console.log(`\n  ${bold(l)}`);
+    else if (l.startsWith('·'))    console.log(`  ${l}`);
+    else                           console.log(`  ${dim(l)}`);
+  });
+};
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+const ask = (question) =>
+  new Promise((resolve) => rl.question(question, (a) => resolve(a.trim())));
+
+// ── Selection helpers ─────────────────────────────────────────────────────────
+
+const showList = (items, showSkip = false) => {
+  items.forEach((item, i) => {
+    const label = typeof item === 'string' ? item : item.label;
+    console.log(`  ${dim(`${i + 1}.`)} ${label}`);
+  });
+  if (showSkip) console.log(`  ${dim('0.')} Skip ${dim('(agent will propose when needed)')}`);
+};
+
+const selectRequired = async (prompt, items) => {
+  while (true) {
+    console.log(`\n${bold(prompt)}`);
+    showList(items);
+    const input = await ask(`\n  ${bold('Select')} ${dim(`(1-${items.length})`)}: `);
+    const index = parseInt(input) - 1;
+    if (!isNaN(index) && index >= 0 && index < items.length) return items[index];
+    console.log(yellow(`  Please enter a number between 1 and ${items.length}.`));
+  }
+};
+
+const selectOptional = async (prompt, items) => {
+  if (!items || items.length === 0) return null;
+  while (true) {
+    console.log(`\n${bold(prompt)}`);
+    showList(items, true);
+    const input = await ask(`\n  ${bold('Select')} ${dim(`(0-${items.length})`)}: `);
+    if (input === '0' || input === '') return null;
+    const index = parseInt(input) - 1;
+    if (!isNaN(index) && index >= 0 && index < items.length) {
+      return typeof items[index] === 'string' ? items[index] : items[index].value;
+    }
+    console.log(yellow(`  Invalid selection. Please enter a number between 0 and ${items.length}.`));
+  }
+};
+
+const separator = () => console.log(`\n${dim('─'.repeat(60))}`);
+
+// ── Config writer ─────────────────────────────────────────────────────────────
+
+const writeConfig = (filePath, configs) => {
+  if (!fs.existsSync(filePath)) return;
+  let content = fs.readFileSync(filePath, 'utf8');
+
+  for (const [key, value] of Object.entries(configs)) {
+    if (!value) continue;
+    const regex = new RegExp(`(# @config ${key}\\s*:)([^\\n]*)`, 'g');
+    content = content.replace(regex, `$1 ${value}`);
+  }
+
+  for (const [key, value] of Object.entries(configs)) {
+    if (!value) continue;
+    const token = new RegExp(`\\{\\{${key}\\}\\}`, 'g');
+    content = content.replace(token, value);
+  }
+
+  fs.writeFileSync(filePath, content, 'utf8');
+};
+
+const ensureGitignore = (entry) => {
+  const p = path.join(ROOT, '.gitignore');
+  const content = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '';
+  if (!content.includes(entry)) fs.appendFileSync(p, `\n${entry}\n`);
+};
+
+const summaryLine = (label, value) => {
+  const padded = label.padEnd(20);
+  if (!value) {
+    console.log(`  ${dim(padded)}: ${yellow('(skipped - agent will propose when needed)')}`);
+  } else {
+    console.log(`  ${dim(padded)}: ${green(value)}`);
+  }
+};
+
+// ── Copy directory ────────────────────────────────────────────────────────────
+
+const copyDir = (src, dest) => {
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(dest, { recursive: true });
+  fs.readdirSync(src).forEach(file => {
+    const srcFile  = path.join(src, file);
+    const destFile = path.join(dest, file);
+    if (fs.statSync(srcFile).isDirectory()) {
+      copyDir(srcFile, destFile);
+    } else {
+      fs.copyFileSync(srcFile, destFile);
+    }
+  });
+};
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+const main = async () => {
+
+  // ── Lock check ───────────────────────────────────────────────────────────────
+
+  if (fs.existsSync(LOCK_FILE)) {
+    const ts = fs.readFileSync(LOCK_FILE, 'utf8').trim();
+    const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask2 = (q) => new Promise((resolve) => rl2.question(q, (a) => resolve(a.trim())));
+
+    console.log(`\n${yellow('  This project has already been initialized.')}`);
+    console.log(dim(`  Initialized on: ${ts}\n`));
+    console.log(`  ${dim('1.')} Continue  — run ${cyan('npm run launch')}`);
+    console.log(`  ${dim('2.')} Reset     — delete config and re-run initialization`);
+    console.log(`  ${dim('3.')} Exit\n`);
+
+    const choice = await ask2(`  ${bold('Select')} ${dim('(1-3)')}: `);
+
+    if (choice === '1') {
+      console.log('');
+      rl2.close();
+      const child = spawn('node', [path.join(ROOT, '.workflow', 'launch.js')], {
+        stdio: 'inherit',
+        cwd: ROOT,
+      });
+      child.on('exit', (code) => process.exit(code));
+      return;
+    } else if (choice === '2') {
+      console.log(yellow('\n  Resetting configuration...\n'));
+      fs.unlinkSync(LOCK_FILE);
+      const configPath = path.join(RUNTIME_DIR, '.config.json');
+      if (fs.existsSync(configPath)) fs.unlinkSync(configPath);
+      rl2.close();
+      console.log(green('  Reset complete. Re-running initialization...\n'));
+      // Fall through to run init again
+    } else {
+      console.log(dim('\n  Exited.\n'));
+      rl2.close();
+      return;
+    }
+  }
+
+  console.log('\n');
+  console.log(bold(cyan('  Multi-Agent Monorepo Template')));
+  console.log(dim('  Project Initializer\n'));
+  separator();
+
+  console.log(`\n${bold('Let\'s configure your project.')}`);
+  console.log(dim('  Required fields must be selected. Optional fields can be skipped (press 0 or Enter).\n'));
+  console.log(dim('  Skipped fields will be resolved by the agent when first needed.\n'));
+
+  // ── Project name ────────────────────────────────────────────────────────────
+
+  let projectName = '';
+  while (!projectName) {
+    projectName = await ask(`${bold('* Project name')}: `);
+    if (!projectName) console.log(yellow('  Project name is required. Please enter a name.'));
+  }
+
+  separator();
+
+  // ── Client ──────────────────────────────────────────────────────────────────
+
+  console.log(`\n${bold(blue('Client configuration'))}`);
+
+  const clientFw    = await selectRequired('* Client framework (required):', CLIENT_FRAMEWORKS);
+  const clientLang  = clientFw.language;
+  const clientState = await selectOptional('State management:', STATE_OPTIONS[clientFw.value] || []);
+  const clientUi    = await selectOptional('UI library:', UI_OPTIONS[clientFw.value] || []);
+  const clientStyle = await selectOptional('Styling:', STYLING_OPTIONS);
+
+  separator();
+
+  // ── Backend ─────────────────────────────────────────────────────────────────
+
+  console.log(`\n${bold(blue('Backend configuration'))}`);
+
+  // Check if client framework has integrated backend support
+  let useIntegratedBackend = false;
+  let backendFw   = null;
+  let backendLang = null;
+  let backendOrm  = null;
+  let backendAuth = null;
+  let backendType = null;
+
+  if (clientFw.integratedBackend) {
+    console.log(dim(`  ${clientFw.value} supports server-side rendering and API routes.\n`));
+    const integratedAnswer = await ask(`  ${bold('Use integrated backend')} ${dim(`(${clientFw.value} API routes/SSR)`)} ${dim('instead of a separate backend? (y/n)')}: `);
+    useIntegratedBackend = integratedAnswer.toLowerCase() === 'y';
+
+    if (useIntegratedBackend) {
+      backendType = 'integrated';
+      console.log(dim(`\n  Using ${clientFw.value} integrated backend. No separate backend needed.\n`));
+    }
+  }
+
+  if (!useIntegratedBackend) {
+    console.log(dim('  You can skip the backend framework and decide later.\n'));
+
+    let backendFwObj = undefined;
+    while (backendFwObj === undefined) {
+      console.log(`\n${bold('Backend framework:')}`);
+      showList(BACKEND_FRAMEWORKS, true);
+      const input = await ask(`\n  ${bold('Select')} ${dim(`(0-${BACKEND_FRAMEWORKS.length})`)}: `);
+      if (input === '0' || input === '') {
+        backendFwObj = null;
+      } else {
+        const index = parseInt(input) - 1;
+        if (isNaN(index) || index < 0 || index >= BACKEND_FRAMEWORKS.length) {
+          console.log(yellow(`  Please enter a number between 0 and ${BACKEND_FRAMEWORKS.length}.`));
+        } else {
+          backendFwObj = BACKEND_FRAMEWORKS[index];
+        }
+      }
+    }
+
+    backendFw   = backendFwObj ? backendFwObj.value    : null;
+    backendLang = backendFwObj ? backendFwObj.language : null;
+    backendOrm  = backendFw ? await selectOptional('ORM / database layer:', ORM_OPTIONS[backendFw] || []) : null;
+    backendAuth = backendFw ? await selectOptional('Auth strategy:', AUTH_OPTIONS[backendFw] || []) : null;
+    backendType = backendFw ? 'separate' : null;
+  }
+
+  separator();
+
+  // ── Environment ─────────────────────────────────────────────────────────────
+
+  console.log(`\n${bold(blue('Environment'))}`);
+
+  const osName = { darwin: 'macOS', win32: 'Windows', linux: 'Linux' }[process.platform] || process.platform;
+  console.log(`\n  ${dim('OS detected:')} ${bold(osName)}`);
+  console.log(dim('  Scanning for installed IDEs...\n'));
+
+  const ideOptions = buildIDEOptions();
+
+  const detectedIDEs  = ideOptions.filter(o => o.detected);
+  const undetectedIDEs = ideOptions.filter(o => !o.detected && o.cmd);
+  const manualOption  = ideOptions.filter(o => !o.cmd);
+
+  // Detected first → undetected → manual
+  const sortedIdeOptions = [...detectedIDEs, ...undetectedIDEs, ...manualOption];
+
+  if (detectedIDEs.length > 1) {
+    console.log(`\n  ${yellow('Multiple IDEs found on this machine')} — select your preference:\n`);
+  } else if (detectedIDEs.length === 1) {
+    console.log(`\n  ${green(`1 IDE found:`)} ${bold(detectedIDEs[0].name)}\n`);
+  } else {
+    console.log(`\n  ${yellow('No IDEs detected on this machine.')}\n`);
+  }
+
+  let ideChoice;
+  while (true) {
+    ideChoice = await selectRequired('* IDE / editor (required):', sortedIdeOptions);
+
+    // ── Confirmation ──────────────────────────────────────────────────────────
+    console.log(`\n  Selected: ${bold(ideChoice.name)}`);
+    if (ideChoice.cmd && !ideChoice.detected) {
+      console.log(yellow(`  ⚠ ${ideChoice.name} was not detected on PATH. It may not open automatically.`));
+    }
+    const confirmIde = await ask(`  ${bold('Confirm this selection?')} ${dim('(y/n)')}: `);
+    if (confirmIde.toLowerCase() !== 'y') {
+      console.log(dim('  Re-selecting...\n'));
+      continue;
+    }
+
+    // ── Double-check ──────────────────────────────────────────────────────────
+    if (!ideChoice.cmd) {
+      // Manual — no verification needed
+      console.log(dim('  Manual mode — worktree path will be printed at launch.'));
+      break;
+    }
+
+    console.log(dim(`\n  Verifying ${ideChoice.name}...`));
+    const verified = verifyIDE(ideChoice);
+
+    if (verified.ok) {
+      const versionStr = verified.version ? dim(` (${verified.version})`) : '';
+      console.log(`  ${green('✓')} ${ideChoice.name} confirmed${versionStr}`);
+      break;
+    }
+
+    console.log(`  ${yellow('!')} Could not verify ${ideChoice.name}. The CLI may not be installed or accessible.`);
+    const proceedAnyway = await ask(`  ${bold('Continue with this IDE anyway?')} ${dim('(y/n)')}: `);
+    if (proceedAnyway.toLowerCase() === 'y') break;
+    console.log(dim('  Re-selecting...\n'));
+  }
+
+  separator();
+
+  // ── Summary ─────────────────────────────────────────────────────────────────
+
+  console.log(`\n${bold('Review your configuration:')}\n`);
+  summaryLine('Project',           projectName);
+  summaryLine('Client framework',  clientFw.value);
+  summaryLine('Client language',   clientLang);
+  summaryLine('State management',  clientState);
+  summaryLine('UI library',        clientUi);
+  summaryLine('Styling',           clientStyle);
+  summaryLine('Backend type',     backendType === 'integrated' ? `${clientFw.value} integrated` : backendFw || '(skipped)');
+  if (backendType !== 'integrated') {
+    summaryLine('Backend language',  backendLang);
+    summaryLine('ORM',               backendOrm);
+    summaryLine('Auth',              backendAuth);
+  }
+  summaryLine('IDE / Editor',      ideChoice.name);
+
+  console.log('');
+  console.log(dim('  y = confirm  |  n = abort  |  e = edit (start over)\n'));
+  const confirm = await ask(`${bold('Confirm and write to config files?')} ${dim('(y/n/e)')}: `);
+
+  if (confirm.toLowerCase() === 'e') {
+    console.log(yellow('\n  Restarting configuration...\n'));
+    rl.close();
+    const { spawn } = require('child_process');
+    const child = spawn('node', [__filename], { stdio: 'inherit', cwd: ROOT });
+    child.on('exit', (code) => process.exit(code));
+    return;
+  }
+
+  if (confirm.toLowerCase() !== 'y') {
+    console.log(yellow('\n  Aborted. No files were changed.\n'));
+    rl.close();
+    return;
+  }
+
+  // ── Write configs ────────────────────────────────────────────────────────────
+
+  separator();
+  console.log(`\n${bold('Setting up your project...')}\n`);
+
+  // ── Clone multi-agents-core ──────────────────────────────────────────────────
+
+  const CORE_REPO = 'https://github.com/JDev-il/multi-agents-core.git';
+  const CORE_DIR  = path.join(ROOT, '.agents-core');
+
+  console.log(`  Fetching templates...`);
+  try {
+    execSync(`git clone "${CORE_REPO}" "${CORE_DIR}"`, { stdio: 'pipe' });
+    console.log(`  ${green('✓')} Templates fetched`);
+  } catch (err) {
+    console.log(`  ${red('✗')} Failed to fetch templates. Check your internet connection.`);
+    rl.close();
+    process.exit(1);
+  }
+
+  const TEMPLATES = path.join(CORE_DIR, 'templates');
+
+  copyDir(path.join(TEMPLATES, 'client'),  path.join(ROOT, 'client'));
+  copyDir(path.join(TEMPLATES, 'shared'),  path.join(ROOT, 'shared'));
+  if (backendType === 'separate') {
+    copyDir(path.join(TEMPLATES, 'backend'), path.join(ROOT, 'backend'));
+  }
+  fs.copyFileSync(path.join(TEMPLATES, 'CLAUDE.md'),    path.join(ROOT, 'CLAUDE.md'));
+  fs.copyFileSync(path.join(TEMPLATES, 'CONTRACTS.md'), path.join(ROOT, 'CONTRACTS.md'));
+  console.log(`  ${green('✓')} Templates copied`);
+
+  // ── Copy workflow scripts ────────────────────────────────────────────────────
+
+  const WORKFLOW_SRC  = path.join(CORE_DIR, 'workflow');
+  const WORKFLOW_DEST = path.join(ROOT, '.workflow');
+  fs.mkdirSync(WORKFLOW_DEST, { recursive: true });
+  copyDir(WORKFLOW_SRC, WORKFLOW_DEST);
+  console.log(`  ${green('✓')} Workflow scripts copied (.workflow/)`);
+
+  execSync(`rm -rf "${CORE_DIR}"`);
+  console.log(`  ${green('✓')} Temporary files cleaned up`);
+
+  // ── Write @config values ─────────────────────────────────────────────────────
+
+  writeConfig(path.join(ROOT, 'CLAUDE.md'), {
+    PROJECT_NAME: projectName,
+    PROJECT_ROOT: projectName,
+  });
+  console.log(`  ${green('✓')} CLAUDE.md configured`);
+
+  writeConfig(path.join(ROOT, 'client', 'CLAUDE.md'), {
+    PROJECT_NAME: projectName,
+    FRAMEWORK:    clientFw.value,
+    LANGUAGE:     clientLang,
+    STATE:        clientState,
+    UI_LIBRARY:   clientUi,
+    STYLING:      clientStyle,
+  });
+  console.log(`  ${green('✓')} client/CLAUDE.md configured`);
+
+  if (backendType === 'separate') {
+    writeConfig(path.join(ROOT, 'backend', 'CLAUDE.md'), {
+      PROJECT_NAME: projectName,
+      FRAMEWORK:    backendFw,
+      LANGUAGE:     backendLang,
+      ORM:          backendOrm,
+      AUTH:         backendAuth,
+    });
+    console.log(`  ${green('✓')} backend/CLAUDE.md configured`);
+  }
+
+  ensureGitignore('worktrees/');
+  ensureGitignore('.agents-core/');
+  ensureGitignore('.scaffold/');
+  ensureGitignore('.workflow/');
+
+  // Remove template-specific gitignore entries so generated files can be committed
+  const gitignorePath = path.join(ROOT, '.gitignore');
+  let gitignoreContent = fs.readFileSync(gitignorePath, 'utf8');
+  ['client/', 'backend/', 'shared/', 'CLAUDE.md', 'CONTRACTS.md', 'BUILD_STATE.md'].forEach(entry => {
+    gitignoreContent = gitignoreContent.replace(`\n${entry}`, '');
+    gitignoreContent = gitignoreContent.replace(`${entry}\n`, '');
+    gitignoreContent = gitignoreContent.replace(entry, '');
+  });
+  fs.writeFileSync(gitignorePath, gitignoreContent.trim() + '\n', 'utf8');
+  console.log(`  ${green('✓')} .gitignore updated`);
+
+  // ── Write .config.json ───────────────────────────────────────────────────────
+
+  const config = {
+    projectName,
+    ide: {
+      name:       ideChoice.name,
+      strategy:   ideChoice.strategy,
+      cmd:        ideChoice.cmd    || null,
+      app:        ideChoice.mac?.app  || null,
+      openArgs:   process.platform === 'darwin' ? (ideChoice.mac?.args  || [])
+                : process.platform === 'win32'  ? (ideChoice.win?.args  || [])
+                :                                 (ideChoice.linux?.args || []),
+      winPaths:   (ideChoice.win?.paths  || []).map(expandWinPath),
+      linuxPaths: ideChoice.linux?.paths || [],
+    },
+    client: {
+      framework: clientFw.value,
+      language:  clientLang,
+      state:     clientState,
+      uiLibrary: clientUi,
+      styling:   clientStyle,
+    },
+    backend: {
+      type:      backendType,
+      framework: backendFw,
+      language:  backendLang,
+      orm:       backendOrm,
+      auth:      backendAuth,
+    },
+  };
+
+  fs.writeFileSync(
+    path.join(RUNTIME_DIR, '.config.json'),
+    JSON.stringify(config, null, 2),
+    'utf8'
+  );
+  console.log(`  ${green('✓')} .scaffold/.config.json written`);
+
+  // ── Generate BUILD_STATE.md ──────────────────────────────────────────────────
+
+  const backendDisplay = backendType === 'integrated'
+    ? `${clientFw.value} integrated (API routes/SSR)`
+    : backendFw || 'Not configured';
+
+  const clientStack = [clientFw.value, clientLang, clientStyle, clientUi, clientState]
+    .filter(Boolean).join(' + ');
+
+  const backendStack = backendType === 'separate'
+    ? [backendFw, backendLang, backendOrm, backendAuth].filter(Boolean).join(' + ')
+    : backendDisplay;
+
+  const buildState = `# BUILD_STATE.md
+# Living project state. Read before every task. Update after completion.
+# Every agent must read this file at session start.
+
+## Project
+Name      : ${projectName}
+Initialized : ${new Date().toISOString()}
+
+## Stack
+Client  : ${clientStack}
+Backend : ${backendStack}
+
+## Client State
+- [ ] Scaffold - framework initialized
+- [ ] UI - components and layout
+- [ ] LOGIC - state management and API client
+- [ ] FORMS - form architecture
+- [ ] ROUTING - route definitions
+- [ ] TESTING - test suite
+- [ ] ACCESSIBILITY - a11y compliance
+
+## Backend State
+${backendType === 'integrated'
+  ? `Type: ${clientFw.value} integrated backend (API routes / SSR)
+- [ ] API routes - server-side endpoints
+- [ ] Auth - authentication strategy
+- [ ] DB - data layer if needed`
+  : backendType === 'separate'
+  ? `Type: Separate backend (${backendFw})
+- [ ] Scaffold - framework initialized
+- [ ] DB - schema and entities
+- [ ] API - endpoints and DTOs
+- [ ] AUTH - authentication strategy
+- [ ] LOGIC - business rules
+- [ ] EVENTS - webhooks and queues
+- [ ] JOBS - background tasks`
+  : 'Not configured - run node .workflow/launch.js and select backend when ready'}
+
+## Shared
+- [ ] CONTRACTS.md - no shared types defined yet
+
+## Dependency Rules
+Before starting any task, verify:
+- Client LOGIC requires: Client scaffold done
+- Client FORMS requires: Client scaffold done
+- Client ROUTING requires: Client scaffold done
+- API calls in client require: Backend API endpoints done OR mocked
+- Backend API requires: DB schema done (if using DB)
+- Backend AUTH requires: DB User entity done
+- Any cross-boundary types: Must exist in CONTRACTS.md first
+
+If a dependency is not met:
+  DEPENDENCY NOT MET - surface what is missing and propose options.
+  Never proceed silently on a missing dependency.
+
+## Agent Log
+| Date | Agent | Scope | Task | Status | Branch |
+|------|-------|-------|------|--------|--------|
+`;
+
+  fs.writeFileSync(path.join(ROOT, 'BUILD_STATE.md'), buildState, 'utf8');
+  console.log(`  ${green('✓')} BUILD_STATE.md generated`);
+
+  // ── Tracking ──────────────────────────────────────────────────────────────────
+
+  const trackingPath = path.join(RUNTIME_DIR, '.tracking.json');
+  if (!fs.existsSync(trackingPath)) {
+    const trackingStructure = generateTrackingStructure(config);
+    fs.writeFileSync(trackingPath, JSON.stringify(trackingStructure, null, 2), 'utf8');
+    console.log(`  ${green('✓')} .tracking.json generated`);
+  } else {
+    console.log(dim('  ℹ .tracking.json already exists — preserved'));
+  }
+
+  // ── Lock ─────────────────────────────────────────────────────────────────────
+
+  fs.writeFileSync(LOCK_FILE, new Date().toISOString());
+  console.log(`  ${green('✓')} Initialization locked`);
+
+  // ── Auto-commit ───────────────────────────────────────────────────────────────
+
+  try {
+    execSync('git add .', { cwd: ROOT, stdio: 'pipe' });
+    execSync('git commit -m "init: project configuration"', { cwd: ROOT, stdio: 'pipe' });
+    console.log(`  ${green('✓')} Project configuration committed`);
+  } catch (err) {
+    console.log(`  ${yellow('!')} Could not auto-commit. Run manually:`);
+    console.log(dim('     git add . && git commit -m "init: project configuration"'));
+  }
+
+  // ── Pre-commit hook — block direct commits to main ───────────────────────────
+
+  try {
+    const hooksDir  = path.join(ROOT, '.git', 'hooks');
+    const hookPath  = path.join(hooksDir, 'pre-commit');
+    const hookScript = `#!/bin/sh
+branch=$(git symbolic-ref --short HEAD 2>/dev/null)
+if [ "$branch" = "main" ]; then
+  echo ""
+  echo "  ⚠ Direct commits to main are not allowed."
+  echo "    Use npm run launch to start a task."
+  echo ""
+  exit 1
+fi
+`;
+    if (!fs.existsSync(hookPath)) {
+      fs.writeFileSync(hookPath, hookScript, { mode: 0o755 });
+      console.log(dim('  ℹ Pre-commit hook installed — direct main commits blocked'));
+    }
+  } catch { /* best-effort */ }
+
+  // ── Remote setup ─────────────────────────────────────────────────────────────
+
+  setupUserRemote(ROOT, projectName);
+
+  // ── Trajectory selection ─────────────────────────────────────────────────────
+
+  separator();
+  console.log(`\n${bold(green('  Project initialized successfully!'))}\n`);
+  console.log(`  ${bold('How do you want to build?')}\n`);
+
+  console.log(`  ${dim('1.')} ${bold('Multi-Agent Driven Orchestration')}`);
+  console.log(`${dim('     · Every task should start with npm run launch')}`);
+  console.log(`${dim('     · Each agent runs in its own git worktree — an isolated branch')}`);
+  console.log(`${dim('       and folder that merges back into main via npm run complete')}`);
+  console.log(`${dim('     · Faster builds and lower token spend than a single long session')}`);
+  console.log(`${yellow('     ⚠ If you commit directly to main yourself, you bypass the framework')}`);
+  console.log(`${yellow('       and break task tracking for any active agent branches')}\n`);
+
+  console.log(`  ${dim('2.')} ${bold('Shared Orchestration')}`);
+  console.log(`${dim('     · You and agents co-build — each owning a defined part of the codebase')}`);
+  console.log(`${dim('     · Agent tasks run in git worktrees; your work happens directly in the project')}`);
+  console.log(`${dim('     · Agent tasks are token-efficient; your tasks cost only what you prompt')}`);
+  console.log(`${dim('     · Define boundaries before work begins — agents for well-scoped work,')}`);
+  console.log(`${dim('       you for areas where requirements are still evolving')}`);
+  console.log(`${yellow('     ⚠ If you and an agent touch the same file, expect merge conflicts')}\n`);
+
+  const TRAJECTORY_DETAILS = {
+    '1': {
+      label: 'Multi-Agent Driven Orchestration',
+      full: [
+        'Every task must start with npm run launch.',
+        'Agent sessions load only task-relevant context, enabling reliable',
+        'chaining, predictable behavior, and efficient token usage.',
+        '',
+        '⚠ If you commit directly to main yourself, you bypass the framework',
+        '  and break task tracking for any active agent branches.',
+        '',
+        'Benefits',
+        '· Scoped context per task',
+        '· Predictable token consumption',
+        '· Lower cost than maintaining large, persistent sessions',
+        '· Better isolation between parallel work streams',
+      ],
+      next: 'launch',
+    },
+    '2': {
+      label: 'Shared Orchestration',
+      full: [
+        'You and agents work in the same codebase, each with clearly',
+        'defined ownership. File boundaries must be established before',
+        'work begins and remain fixed throughout the task.',
+        'Agents excel when scope is well-defined;',
+        'you excel when requirements are evolving.',
+        '',
+        'Use agents for',
+        '· Multi-file features',
+        '· Structured implementation work',
+        '· Domain-specific tasks',
+        '· Changes expected to exceed ~200 lines',
+        '',
+        'Handle manually',
+        '· Targeted bug fixes',
+        '· Configuration changes',
+        '· Small refactors',
+        '· Single-file edits under ~50 lines',
+        '',
+        '⚠ Avoid overlapping file ownership. Working on the same files',
+        '  as an active agent will create merge conflicts when merged.',
+        '⚠ If you are spending time repeatedly clarifying scope, stop',
+        '  and do the task yourself. The coordination cost often',
+        '  exceeds the implementation cost.',
+        '',
+        'Benefits',
+        '· Maximum agent efficiency for well-defined work',
+        '· Human flexibility where requirements change',
+        '· Scales well across large projects',
+        '· Most adaptable workflow — requires the most discipline',
+      ],
+      next: 'launch',
+    },
+  };
+
+  // Wrap in loop to support back navigation
+  let trajectory = null;
+  trajectoryLoop: while (true) {
+    while (!trajectory) {
+      const input = await ask(`  ${bold('Select (1-2)')}: `);
+      if (['1', '2'].includes(input)) trajectory = input;
+      else console.log(yellow('  Please enter 1 or 2.'));
+    }
+
+    const selected = TRAJECTORY_DETAILS[trajectory];
+    separator();
+    console.log(`\n  ${green('✓')} ${bold(selected.label)}\n`);
+    renderTrajectoryLines(selected.full);
+    console.log('');
+
+    const confirm = await ask(`  ${bold('Confirm?')} ${dim('(y / b = back)')}: `);
+    if (confirm.toLowerCase() === 'y') break trajectoryLoop;
+    trajectory = null; // reset and re-show menu
+    separator();
+    console.log(`\n  ${bold('How do you want to build?')}\n`);
+    console.log(`  ${dim('1.')} ${bold('Multi-Agent Driven Orchestration')}`);
+    console.log(`${dim('     · Every task should start with npm run launch')}`);
+    console.log(`${dim('     · Each agent runs in its own git worktree — an isolated branch')}`);
+    console.log(`${dim('       and folder that merges back into main via npm run complete')}`);
+    console.log(`${dim('     · Faster builds and lower token spend than a single long session')}`);
+    console.log(`${yellow('     ⚠ If you commit directly to main yourself, you bypass the framework')}`);
+    console.log(`${yellow('       and break task tracking for any active agent branches')}\n`);
+    console.log(`  ${dim('2.')} ${bold('Shared Orchestration')}`);
+    console.log(`${dim('     · You and agents co-build — each owning a defined part of the codebase')}`);
+    console.log(`${dim('     · Agent tasks run in git worktrees; your work happens directly in the project')}`);
+    console.log(`${dim('     · Agent tasks are token-efficient; your tasks cost only what you prompt')}`);
+    console.log(`${dim('     · Define boundaries before work begins — agents for well-scoped work,')}`);
+    console.log(`${dim('       you for areas where requirements are still evolving')}`);
+    console.log(`${yellow('     ⚠ If you and an agent touch the same file, expect merge conflicts')}\n`);
+  }
+
+  const selected = TRAJECTORY_DETAILS[trajectory];
+
+  // Store trajectory in config
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(RUNTIME_DIR, '.config.json'), 'utf8'));
+    cfg.trajectory = selected.label.toLowerCase().replace(/ /g, '-');
+    fs.writeFileSync(path.join(RUNTIME_DIR, '.config.json'), JSON.stringify(cfg, null, 2), 'utf8');
+  } catch { /* best-effort */ }
+
+  if (selected.next === 'launch') {
+    const launchInput = await ask(`  ${bold('Ready to launch your first task?')} ${dim('(y/n)')}: `);
+    if (launchInput.toLowerCase() === 'y') {
+      rl.close();
+      console.log('');
+      const child = spawn('node', [path.join(ROOT, '.workflow', 'launch.js')], {
+        stdio: 'inherit',
+        cwd: ROOT,
+      });
+      child.on('exit', (code) => process.exit(code));
+      return;
+    }
+  }
+
+  console.log('');
+  console.log(`  ${bold('When ready, run:')}`);
+  console.log(`  ${cyan('npm run launch')}\n`);
+  separator();
+  console.log('');
+  rl.close();
+};
+
+main().catch((err) => {
+  console.error('\n  Error:', err.message);
+  process.exit(1);
+});