multi-agents-cli 1.1.9 → 1.1.11

package/core/workflow/agent.js

@@ -836,6 +836,52 @@ const main = async () => {
 
   // Soft gate - backend selected but missing prerequisites
   if (project === 'backend') {
+    // Architectural change warning — no backend/ folder + integrated backend config
+    const backendFolderExists = fs.existsSync(path.join(ROOT, 'backend'));
+    const isIntegrated = config.backend?.type === 'integrated';
+
+    if (!backendFolderExists) {
+      separator();
+      console.log(`\n  ${yellow('⚠ No backend/ folder detected')}
+`);
+      if (isIntegrated) {
+        console.log(`  This project currently uses ${bold('integrated backend')} (${dim(config.frontend?.type || 'client framework')}).`);
+        console.log(`  Adding a separate backend will change your project architecture:
+`);
+      } else {
+        console.log(`  A ${bold('backend/')} directory does not exist yet.`);
+        console.log(`  Proceeding will create it and establish a separate backend:
+`);
+      }
+      console.log(`  ${dim('→')} A new ${bold('backend/')} directory will be created`);
+      console.log(`  ${dim('→')} Client API calls will need redirecting to the new backend`);
+      console.log(`  ${dim('→')} CONTRACTS.md will need updating`);
+      if (isIntegrated) {
+        console.log(`  ${dim('→')} Project config will update to ${bold('separate')} backend type
+`);
+      }
+      console.log('');
+
+      const archIdx = await arrowSelect('How would you like to proceed?', [
+        { label: `${green('→')} Proceed — I want to add a separate backend` },
+        { label: `${yellow('←')} Go back — keep current setup ${dim('← recommended')}` },
+      ], rl);
+
+      if (archIdx === 1) continue flowLoop;
+
+      // Update config to separate if was integrated
+      if (isIntegrated) {
+        try {
+          const cfgPath = path.join(ROOT, '.scaffold', '.config.json');
+          const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+          cfg.backend.type = 'separate';
+          fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2), 'utf8');
+          console.log(`  ${green('✓')} Project config updated to separate backend
+`);
+        } catch {}
+      }
+    }
+
     const clientCompleted = buildEntries.filter(e => e.scope === 'client' && e.status === 'COMPLETED');
     const clientLogicDone = clientCompleted.some(e => e.agent === 'LOGIC');
     const missing = [];
@@ -863,6 +909,42 @@ const main = async () => {
     }
   }
 
+
+  // Soft gate - shared selected but missing prerequisites
+  if (project === 'shared') {
+    const clientCompleted  = buildEntries.filter(e => e.scope === 'client'  && e.status === 'COMPLETED');
+    const backendCompleted = buildEntries.filter(e => e.scope === 'backend' && e.status === 'COMPLETED');
+    const clientUIДone     = clientCompleted.some(e => e.agent === 'UI');
+    const backendINITDone  = backendCompleted.some(e => e.agent === 'INIT');
+    const missing = [];
+
+    if (!clientUIДone) {
+      missing.push({ item: 'Client scaffold', detail: 'no completed client work found — SECURITY needs to know what auth patterns the client uses' });
+    }
+    if (!backendINITDone) {
+      missing.push({ item: 'Backend INIT', detail: 'backend not scaffolded yet — SECURITY needs to know the backend auth strategy and DB schema' });
+    }
+    if (!contracts.hasContent) {
+      missing.push({ item: 'CONTRACTS.md', detail: 'no shared types defined — auth utilities should align with established contracts' });
+    }
+
+    if (missing.length > 0) {
+      console.log(`\n${yellow('  ⚠ Shared prerequisites not fully met:')}
+`);
+      missing.forEach(m => {
+        console.log(`  ${dim('→')} ${bold(m.item)}`);
+        console.log(`     ${m.detail}\n`);
+      });
+      console.log(`  ${dim('The agent will proceed autonomously and make assumptions about auth patterns.')}`);
+      console.log(`  ${dim('These may need revision once client and backend are fully established.\n')}`);
+      const proceedIdx = await arrowSelect('Shared prerequisites not met:', [
+        { label: `${green('→')} Proceed anyway` },
+        { label: `${yellow('←')} Go back — pick a different scope  ${dim('← recommended')}` },
+      ], rl);
+      if (proceedIdx === 1) continue flowLoop;
+    }
+  }
+
   // ── Select agent (with re-selection loop + back to scope) ────────────────────
 
   const agentOptions = AGENTS[project] || [];
@@ -896,12 +978,14 @@ const main = async () => {
 
     const agentChoices = [
       ...agentOptions.map(a => {
-        const desc = dim(`  ${AGENT_DESCRIPTIONS[project]?.[a] || ''}`);
-        const tag  = a === recommendedAgent
-          ? cyan(completedAgents.length === 0 ? '  ← start here' : '  ← next step')
-          : '';
-        const label = a === recommendedAgent ? bold(a) : a;
-        return { label: `${label}${tag}${desc}` };
+        const desc      = dim(`  ${AGENT_DESCRIPTIONS[project]?.[a] || ''}`);
+        const completed = completedAgents.includes(a);
+        const isActive  = tracking?.[project]?.[a]?.status === 'ACTIVE';
+        const isNext    = a === recommendedAgent && !isActive;
+        const indicator = completed ? green('[✓]') : isActive ? yellow('[▶]') : isNext ? cyan(' → ') : dim('[ ]');
+        const label     = completed ? dim(a) : isActive ? yellow(bold(a)) : isNext ? bold(a) : a;
+        const tag       = isActive ? yellow('  ← in progress') : isNext ? cyan(completedAgents.length === 0 ? '  ← start here' : '  ← next step') : '';
+        return { label: `${indicator} ${label}${tag}${desc}` };
       }),
       { label: dim('← back to scope selection') },
     ];
@@ -911,6 +995,34 @@ const main = async () => {
     agent = agentOptions[agentIdx];
     contractsNote = '';
 
+    // ── Check for OTHER active agents in same scope ───────────────────────────
+    const otherActiveInScope = Object.entries(tracking?.[project] || {})
+      .filter(([a, data]) => a !== agent && data?.status === 'ACTIVE');
+
+    if (otherActiveInScope.length > 0) {
+      separator();
+      console.log(`\n  ${yellow('⚠ Active agent detected in ' + project + ' scope')}
+`);
+      for (const [a, data] of otherActiveInScope) {
+        console.log(`  ${dim('→')} ${bold(a)} is currently ${yellow('ACTIVE')}`);
+        console.log(`     Branch  : ${dim(data.branch)}`);
+        console.log(`     Launched: ${dim(data.launchedAt ? new Date(data.launchedAt).toLocaleString() : 'unknown')}
+`);
+      }
+      console.log(`  ${yellow('Launching')} ${bold(agent)} ${yellow('alongside an active agent in the same scope means:')}`);
+      console.log(`  ${dim('→')} Both agents may write to overlapping files`);
+      console.log(`  ${dim('→')} Scope violations may occur at merge time`);
+      console.log(`  ${dim('→')} CONTRACTS.md may receive conflicting entries
+`);
+
+      const warningIdx = await arrowSelect('How would you like to proceed?', [
+        { label: `${yellow('→')} Proceed anyway ${dim('— I understand the risks')}` },
+        { label: `${green('←')} Go back — pick a different agent ${dim('← recommended')}` },
+      ], rl);
+
+      if (warningIdx === 1) continue agentLoop;
+    }
+
     // Agent already active - decisional block
   const { active, slot: activeSlot } = guards.checkAgentActive(tracking, project, agent);
   if (active) {
@@ -1058,6 +1170,32 @@ const main = async () => {
   } // end else (argAgent bypass)
   } // end if (project !== 'cloud')
 
+  // ── First-run project context question (UI agent only, no completed agents) ──
+  let projectContext = '';
+  const isFirstRun = project === 'client' && agent === 'UI' && buildEntries.filter(e => e.status === 'COMPLETED').length === 0;
+
+  if (isFirstRun) {
+    separator();
+    console.log(`\n  ${bold('Before we begin...')}
+`);
+
+    if (prompts && process.stdin.isTTY) {
+      const ctxRes = await prompts({
+        type:    'text',
+        name:    'value',
+        message: '* What are you building?',
+        initial: 'e.g. A stock market prediction app with AI insights and portfolio tracking',
+      }, { onCancel: () => process.exit(0) });
+      const rawCtx = (ctxRes.value || '').trim();
+      const isPlaceholderCtx = rawCtx.startsWith('e.g. ');
+      projectContext = isPlaceholderCtx ? '' : rawCtx;
+    } else {
+      console.log(dim('  (optional — helps the agent make better decisions)'));
+      const input = await ask(`\n${bold('* What are you building?')}: `);
+      projectContext = input.trim();
+    }
+  }
+
   // ── Task description ──────────────────────────────────────────────────────────
 
   separator();
@@ -1105,6 +1243,11 @@ const main = async () => {
   let skipped  = [];
   contextSection = '';
 
+  // Inject project context if provided on first UI run
+  if (projectContext) {
+    contextSection += `\n---\n\n## Project Context\n\n${projectContext}\n\nUse this as the primary directive for what you are building. All component names, page structure, and UI decisions should align with this project description.\n`;
+  }
+
   if (AGENT_QUESTIONS[agent] && userSeedingContracts) {
     let gathering = true;
     while (gathering) {
@@ -1143,6 +1286,135 @@ const main = async () => {
     }
   }
 
+
+  // ── Backend simultaneous flow (client/LOGIC only, separate backend, first run) ──
+  let backendLaunchTiming = null;
+  const isSimultaneousCandidate =
+    project === 'client' &&
+    agent   === 'LOGIC'  &&
+    config.backend?.type === 'separate' &&
+    !argAgent &&
+    !buildEntries.some(e => e.scope === 'backend') &&
+    !tracking?.backend?.INIT?.backendPromptShown;
+
+  if (isSimultaneousCandidate) {
+    separator();
+    console.log(`\n  ${yellow('⚡ Backend not started yet')}\n`);
+    console.log(`  Your backend has not been scaffolded yet.`);
+    console.log(`  Since client/LOGIC establishes integration contracts, this is the ideal moment to plan backend scaffolding.\n`);
+
+    const intentIdx = await arrowSelect('Would you like to include backend/INIT?', [
+      { label: `${green('→')} Yes — I want to scaffold the backend` },
+      { label: `${dim('→')} No  — continue with client/LOGIC only` },
+    ], rl);
+
+    if (intentIdx === 0) {
+      console.log('');
+      const timingIdx = await arrowSelect('When would you like to scaffold backend/INIT?', [
+        { label: `${green('→')} Now   — open backend/INIT workspace alongside this LOGIC session\n              ${dim('A second IDE window will open. Both agents run in parallel.')}` },
+        { label: `${dim('→')} After — launch backend/INIT when LOGIC completes\n              ${dim('complete.js will prompt you immediately after merge.')}` },
+        { label: `${dim('→')} Skip  — changed my mind, continue with client/LOGIC only` },
+      ], rl);
+
+      if (timingIdx === 0) backendLaunchTiming = 'now';
+      else if (timingIdx === 1) backendLaunchTiming = 'after';
+      else backendLaunchTiming = 'skip';
+    } else {
+      backendLaunchTiming = 'skip';
+    }
+
+    // Write flag to backend/INIT tracking slot — prevents prompt from showing again
+    guards.updateTrackingSlot(tracking, 'backend', 'INIT', {
+      backendPromptShown:  true,
+      backendLaunchTiming,
+    }, ROOT);
+
+    // Inject backend coordination block into TASK.md contextSection
+    if (backendLaunchTiming === 'now') {
+      contextSection += `\n---\n\n## Backend Coordination\n\nBackend/INIT is running in parallel in a separate workspace.\nEstablish CONTRACTS.md entries early — the backend agent will consume them.\nDo not wait for backend confirmation. Work autonomously on client scope.\n`;
+    } else if (backendLaunchTiming === 'after') {
+      contextSection += `\n---\n\n## Backend Coordination\n\nBackend/INIT will launch after this LOGIC session completes.\nBe deliberate about API contracts — document all integration points in CONTRACTS.md.\nThe backend agent will use these as its starting reference.\n`;
+    }
+
+    // If Now — create backend/INIT worktree immediately
+    if (backendLaunchTiming === 'now') {
+      const beTimestamp    = Date.now();
+      const beBranchName   = `agent/backend/init/${beTimestamp}`;
+      const beWorktreeName = `backend-${config.projectName.toLowerCase().replace(/\s+/g, '-')}-init-${beTimestamp}`;
+      const beWorktreePath = path.join(ROOT, 'worktrees', beWorktreeName);
+
+      console.log(`\n  ${dim('Setting up backend/INIT workspace...')}\n`);
+
+      try {
+        execSync(`git worktree add "${beWorktreePath}" -b ${beBranchName}`, { cwd: ROOT, stdio: 'pipe' });
+
+        // Framework files
+        const beScope = generateClaudeScope({ project: 'backend', agent: 'INIT', branchName: beBranchName, worktreePath: beWorktreePath });
+        fs.writeFileSync(path.join(beWorktreePath, '.claude-scope'), beScope, 'utf8');
+
+        const beTask = AGENT_DESCRIPTIONS.backend?.INIT || 'scaffolds backend architecture, folder structure, DB setup, wiring config and contracts';
+        const beTaskMd = generateTaskMd({ project: 'backend', agent: 'INIT', task: beTask, branchName: beBranchName, contextSection: '', remoteSetupSection: '' });
+        fs.writeFileSync(path.join(beWorktreePath, 'TASK.md'), beTaskMd, 'utf8');
+
+        const bePkg = {
+          name: `${config.projectName.toLowerCase().replace(/\s+/g, '-')}-worktree`,
+          version: '1.0.0', private: true,
+          scripts: {
+            init:     'multi-agents init',
+            agent:    `node "${ROOT}/.workflow/run.js"`,
+            restart:  `node "${ROOT}/.workflow/restart.js"`,
+            reset:    `node "${ROOT}/.workflow/reset.js"`,
+            complete: `node "${ROOT}/.workflow/complete.js"`,
+          },
+        };
+        fs.writeFileSync(path.join(beWorktreePath, 'package.json'), JSON.stringify(bePkg, null, 2), 'utf8');
+
+        const beGitignore = ['# Framework files — never commit these to the agent branch', 'package.json', '.claude-scope', 'scope.json', 'TASK.md', '.vscode/', '.idea/', '.zed/', 'node_modules/'].join('\n') + '\n';
+        fs.writeFileSync(path.join(beWorktreePath, '.gitignore'), beGitignore, 'utf8');
+
+        // Tracking
+        guards.updateTrackingSlot(tracking, 'backend', 'INIT', {
+          branch:      beBranchName,
+          timestamp:   beTimestamp,
+          launchedAt:  new Date().toISOString(),
+          status:      'ACTIVE',
+          worktreePath: beWorktreePath,
+          backendPromptShown:  true,
+          backendLaunchTiming: 'now',
+        }, ROOT);
+
+        // TASKS_HISTORY
+        tasksHistory.ensureHistoryFile(ROOT);
+        tasksHistory.writeSessionEntry(ROOT, { scope: 'backend', agent: 'INIT', branch: beBranchName, task: beTask, launchedAt: new Date().toISOString() });
+
+        console.log(`  ${green('✓')} Backend/INIT worktree created: worktrees/${beWorktreeName}`);
+
+        // BUILD_STATE.md entry
+        const beBuildStatePath = path.join(ROOT, 'BUILD_STATE.md');
+        if (fs.existsSync(beBuildStatePath)) {
+          const beDate     = new Date().toISOString().split('T')[0];
+          const beLogEntry = `| ${beDate} | INIT | backend | ${beTask} | IN PROGRESS | ${beBranchName} |\n`;
+          fs.appendFileSync(beBuildStatePath, beLogEntry, 'utf8');
+          try {
+            execSync('git add BUILD_STATE.md', { cwd: ROOT, stdio: 'pipe' });
+            execSync(`git commit --no-verify -m "build: INIT task started on backend [${beBranchName}]"`, { cwd: ROOT, stdio: 'pipe' });
+            console.log(`  ${green('✓')} BUILD_STATE.md updated`);
+          } catch {}
+        }
+
+        // Open backend IDE window
+        const beIdeOpened = openIDE(beWorktreePath);
+        if (!beIdeOpened) console.log(`  ${yellow('!')} Could not open IDE for backend — open manually at: ${dim(beWorktreePath)}`);
+        console.log(`  ${green('✓')} Backend/INIT workspace open — start a Claude Code session there when ready\n`);
+
+      } catch (e) {
+        console.log(`  ${yellow('⚠')} Could not create backend/INIT worktree: ${e.message}`);
+      }
+    }
+
+    separator();
+  }
+
   separator();
 
   // ── Confirm ───────────────────────────────────────────────────────────────────
@@ -1225,6 +1497,13 @@ Mark each step complete. Only proceed to the task below when all are checked.
     });
     console.log(`  ${green('✓')} Worktree created: worktrees/${worktreeName}`);
   } catch (err) {
+    const msg = err.stderr?.toString() || err.message || '';
+    if (msg.includes('not a git repository')) {
+      console.error(`
+  ${red('✖')} Not a git repository. Run git init first, then npm run init.
+`);
+      process.exit(1);
+    }
     console.log(`  ${yellow('!')} Worktree may already exist - continuing.`);
   }
 

package/core/workflow/complete.js

@@ -9,7 +9,7 @@
  * Run from the repo root after a task is complete.
  */
 
-const readline          = require('readline');
+let prompts; try { prompts = require('prompts'); } catch { prompts = null; }
 const fs                = require('fs');
 const path              = require('path');
 const { execSync, spawn } = require('child_process');
@@ -51,15 +51,23 @@ if (!fs.existsSync(LOCK_PATH)) {
 
 const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
 
-// ── Readline ──────────────────────────────────────────────────────────────────
+// ── Arrow confirm helper ──────────────────────────────────────────────────────
 
-const rl = readline.createInterface({
-  input: process.stdin,
-  output: process.stdout,
-});
+const arrowConfirm = async (message, initial = true) => {
+  if (prompts && process.stdin.isTTY) {
+    const res = await prompts({ type: 'confirm', name: 'value', message, initial }, { onCancel: () => process.exit(0) });
+    return res.value ?? initial;
+  }
+  return initial;
+};
 
-const ask = (question) =>
-  new Promise((resolve) => rl.question(question, (a) => resolve(a.trim())));
+const arrowSelect = async (message, choices) => {
+  if (prompts && process.stdin.isTTY) {
+    const res = await prompts({ type: 'select', name: 'value', message, choices: choices.map((c, i) => ({ title: c, value: i })) }, { onCancel: () => process.exit(0) });
+    return res.value ?? 0;
+  }
+  return 0;
+};
 
 const separator = () => console.log(`\n${dim('─'.repeat(60))}`);
 
@@ -143,7 +151,6 @@ const main = async () => {
   if (worktrees.length === 0) {
     console.log(`\n${yellow('  No active task worktrees found.')}`);
     console.log(dim('  Run npm run agent to start a task.\n'));
-    rl.close();
     return;
   }
 
@@ -163,15 +170,8 @@ const main = async () => {
     selectedWorktree = worktrees[0];
     console.log(dim(`\n  Auto-selected: ${selectedWorktree.branch}\n`));
   } else {
-    while (!selectedWorktree) {
-      const input = await ask(`\n  ${bold('Select task to complete')} ${dim(`(1-${worktrees.length})`)}: `);
-      const index = parseInt(input) - 1;
-      if (!isNaN(index) && index >= 0 && index < worktrees.length) {
-        selectedWorktree = worktrees[index];
-      } else {
-        console.log(yellow(`  Please enter a number between 1 and ${worktrees.length}.`));
-      }
-    }
+    const idx = await arrowSelect('Select task to complete:', worktrees.map(wt => wt.branch));
+    selectedWorktree = worktrees[idx];
   }
 
   const { path: worktreePath, branch: branchName } = selectedWorktree;
@@ -219,7 +219,6 @@ const main = async () => {
       console.log(dim('  The following files are outside the allowed scope for ' + scopeMeta.agent + ' (' + scopeMeta.scope + '):\n'));
       violations.forEach(f => console.log('    ' + red('✗') + ' ' + f));
       console.log('\n' + dim('  Fix the violations, then re-run npm run complete.\n'));
-      rl.close();
       return;
     }
 
@@ -238,10 +237,9 @@ const main = async () => {
     if (!isCompleted && !isNonTTY) {
       console.log(`\n${yellow('  TASK.md is not marked as COMPLETED.')}`);
       console.log(dim('  The agent may still be working on this task.\n'));
-      const proceed = await ask(`  ${bold('Proceed with merge anyway?')} ${dim('(y/n)')}: `);
-      if (proceed.toLowerCase() !== 'y') {
+      const proceed = await arrowConfirm('Proceed with merge anyway?', false);
+      if (!proceed) {
         console.log(yellow('\n  Aborted. Complete the task first.\n'));
-        rl.close();
         return;
       }
     } else if (!isCompleted && isNonTTY) {
@@ -258,10 +256,9 @@ const main = async () => {
   console.log(`  ${dim('Into')}     : ${green('main')}`);
   console.log(`  ${dim('Worktree')} : ${dim(worktreePath)}\n`);
 
-  const confirm = isNonTTY ? 'y' : await ask(`${bold('Confirm merge into main?')} ${dim('(y/n)')}: `);
-  if (confirm.toLowerCase() !== 'y') {
+  const confirmMerge = isNonTTY ? true : await arrowConfirm('Confirm merge into main?');
+  if (!confirmMerge) {
     console.log(yellow('\n  Aborted.\n'));
-    rl.close();
     return;
   }
 
@@ -328,10 +325,9 @@ const main = async () => {
   } catch (err) {
     console.log(`  ${yellow('!')} Could not pull latest main.`);
     if (!isNonTTY) {
-      const proceedAnyway = await ask(`  ${bold('Proceed with merge anyway?')} ${dim('(y/n)')}: `);
-      if (proceedAnyway.toLowerCase() !== 'y') {
+      const proceedAnyway = await arrowConfirm('Proceed with merge anyway?');
+      if (!proceedAnyway) {
         console.log(yellow('\n  Aborted.\n'));
-        rl.close();
         return;
       }
     } else {
@@ -362,12 +358,10 @@ const main = async () => {
       } else {
         console.log(`\n${red('  ✗ Merge conflict in:')} ${conflicts.join(', ')}`);
         console.log(dim('  Resolve conflicts manually, then run: git commit\n'));
-        rl.close();
         return;
       }
     } catch {
       console.log(`\n${red('  ✗ Merge failed.')} Resolve manually.\n`);
-      rl.close();
       return;
     }
   }
@@ -391,6 +385,59 @@ const main = async () => {
     }
   } catch { /* best-effort */ }
 
+  // ── Write start:client / start:backend into root package.json ───────────────
+
+  try {
+    const CLIENT_START = {
+      'Next.js':    'cd client && npm install && npm run dev',
+      'Nuxt':       'cd client && npm install && npm run dev',
+      'SvelteKit':  'cd client && npm install && npm run dev',
+      'Remix':      'cd client && npm install && npm run dev',
+      'Vite+React': 'cd client && npm install && npm run dev',
+      'Angular':    'cd client && npm install && npx ng serve',
+    };
+    const BACKEND_START = {
+      'NestJS':   'cd backend && npm install && npm run start:dev',
+      'Express':  'cd backend && npm install && npm run dev',
+      'Fastify':  'cd backend && npm install && npm run dev',
+      'Django':   'cd backend && pip install -r requirements.txt && python manage.py runserver',
+      'FastAPI':  'cd backend && pip install -r requirements.txt && uvicorn main:app --reload',
+      'Laravel':  'cd backend && composer install && php artisan serve',
+      'Rails':    'cd backend && bundle install && bin/rails server',
+    };
+
+    const pkgPath = path.join(ROOT, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (!pkg.scripts) pkg.scripts = {};
+
+      const parts = branchName.split('/');
+      const _t = guards.loadTracking(ROOT, config);
+      const uiDone   = _t?.client?.UI?.status   === 'COMPLETED';
+      const initDone = _t?.backend?.INIT?.status === 'COMPLETED';
+
+      if (uiDone) {
+        const fw = config.client && config.client.framework;
+        const cmd = CLIENT_START[fw];
+        if (cmd && !pkg.scripts['start:client']) {
+          pkg.scripts['start:client'] = cmd;
+          fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+          console.log(`  ${green('✓')} start:client added to package.json (${cmd})`);
+        }
+      }
+
+      if (initDone) {
+        const fw = config.backend && config.backend.framework;
+        const cmd = BACKEND_START[fw];
+        if (cmd && !pkg.scripts['start:backend']) {
+          pkg.scripts['start:backend'] = cmd;
+          fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+          console.log(`  ${green('✓')} start:backend added to package.json (${cmd})`);
+        }
+      }
+    }
+  } catch { /* best-effort */ }
+
   // ── Update scaffold flags ──────────────────────────────────────────────────
 
   try {
@@ -442,13 +489,85 @@ const main = async () => {
   if (_agent) console.log(`  ${dim('Agent')}  : ${green(_agent)} ${dim('(' + _scope + ')')}`);
   if (_task)  console.log(`  ${dim('Task')}   : ${dim(_task)}`);
   console.log(`  ${dim('Branch')} : ${green(branchName)} merged into ${green('main')}\n`);
-  console.log(`  ${bold('What to do next:')}\n`);
-  console.log(`  Start a new task:`);
-  console.log(`  ${cyan('npm run agent')}\n`);
-  separator();
-  console.log('');
 
-  rl.close();
+  // ── Derive next step from tracking ──────────────────────────────────────────
+  const AGENT_ORDER = {
+    client:  ['UI', 'LOGIC', 'FORMS', 'ROUTING', 'TESTING', 'ACCESSIBILITY'],
+    backend: ['INIT', 'API', 'LOGIC', 'AUTH', 'DB', 'TESTING', 'EVENTS', 'JOBS'],
+    shared:  ['SECURITY'],
+  };
+  const SCOPE_ORDER = ['client', 'backend', 'shared'];
+
+  try {
+    const _tracking = guards.loadTracking(ROOT, config);
+
+    const findNextInScope = (scope) => {
+      const order = AGENT_ORDER[scope] || [];
+      for (const a of order) {
+        const slot = (_tracking[scope] || {})[a];
+        if (!slot || (slot.status !== 'COMPLETED' && slot.status !== 'ACTIVE')) return a;
+      }
+      return null;
+    };
+
+    let nextScope = null;
+    let nextAgent = null;
+
+    const scopesToCheck = [_scope, ...SCOPE_ORDER.filter(s => s !== _scope)];
+    for (const s of scopesToCheck) {
+      const n = findNextInScope(s);
+      if (n) { nextScope = s; nextAgent = n; break; }
+    }
+
+    separator();
+    console.log(`\n  ${bold('What to do next:')}`);
+
+    if (nextAgent) {
+      console.log(`\n  ${green('→')} ${bold(nextAgent)} ${dim('(' + nextScope + ')')}`);
+      console.log(`\n  ${cyan('npm run agent')}`);
+      console.log(`  ${dim('Select: ' + nextScope + ' → ' + nextAgent)}`);
+    } else {
+      console.log(`\n  ${cyan('npm run agent')}`);
+    }
+  } catch {
+    separator();
+    console.log(`\n  ${bold('What to do next:')}\n`);
+    console.log(`  ${cyan('npm run agent')}`);
+  }
+
+  console.log('\n');
+
+
+  // ── Backend/INIT launch prompt (if user chose 'after' during LOGIC session) ──
+  try {
+    const _tracking = guards.loadTracking(ROOT, config);
+    const beSlot    = _tracking?.backend?.INIT;
+    if (
+      _scope === 'logic' &&
+      _parts[0] === 'agent' && _parts[1] === 'client' &&
+      beSlot?.backendLaunchTiming === 'after' &&
+      beSlot?.status !== 'ACTIVE' &&
+      beSlot?.status !== 'COMPLETED'
+    ) {
+      separator();
+      console.log(`\n  ${yellow('⚡ Ready to scaffold your backend?')}\n`);
+      console.log(`  client/LOGIC is merged. This is the ideal moment to launch backend/INIT.\n`);
+
+      const { spawn: _spawn } = require('child_process');
+      const launchIdx = await arrowSelect('Launch backend/INIT?', [
+        'Launch backend/INIT now  ← recommended',
+        'Skip — I will handle it manually',
+      ]);
+
+      if (launchIdx === 1) {
+        console.log(`\n  ${green('✓')} Launching backend/INIT...\n`);
+        _spawn('node', [path.join(ROOT, '.workflow', 'agent.js'), '--scope=backend', '--agent=INIT'], {
+          cwd: ROOT, stdio: 'inherit',
+        });
+        return;
+      }
+    }
+  } catch { /* best-effort */ }
 };
 
 main().catch((err) => {