orbital-command 0.3.0 → 1.0.0

package/server/wizard/index.ts

@@ -10,10 +10,10 @@
 
 import fs from 'fs';
 import path from 'path';
-import crypto from 'crypto';
+import { spawn, execFileSync } from 'child_process';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
-import { buildSetupState, buildProjectState, ORBITAL_HOME } from './detect.js';
+import { buildSetupState, buildProjectState } from './detect.js';
 import { phaseSetupWizard } from './phases/setup-wizard.js';
 import { phaseWelcome } from './phases/welcome.js';
 import { phaseProjectSetup } from './phases/project-setup.js';
@@ -22,6 +22,8 @@ import { phaseConfirm, showPostInstall } from './phases/confirm.js';
 import { NOTES } from './ui.js';
 import { runConfigEditor } from './config-editor.js';
 import { runDoctor } from './doctor.js';
+import { isITerm2Available } from '../adapters/iterm2-adapter.js';
+import { registerProject } from '../global-config.js';
 
 export { runConfigEditor, runDoctor };
 
@@ -50,8 +52,8 @@ export async function runSetupWizard(packageVersion: string): Promise<void> {
 
   p.outro(
     state.linkedProjects.length > 0
-      ? `Run ${pc.cyan('orbital launch --open')} to open the dashboard.`
-      : `Run ${pc.cyan('orbital init')} in a project directory to get started.`
+      ? `Run ${pc.cyan('orbital')} to launch the dashboard.`
+      : `Run ${pc.cyan('orbital')} in a project directory to get started.`
   );
 }
 
@@ -73,7 +75,7 @@ export async function runProjectSetup(projectRoot: string, packageVersion: strin
 
   await runProjectPhases(state, useForce);
 
-  p.outro(`Run ${pc.cyan('orbital launch --open')} to open the dashboard.`);
+  p.outro(`Run ${pc.cyan('orbital')} to launch the dashboard.`);
 }
 
 // ─── Shared project phases (used by both flows) ────────────────
@@ -104,7 +106,7 @@ async function runProjectPhases(state: ReturnType<typeof buildProjectState>, use
       commands: state.selectedCommands,
     });
 
-    registerProject(state.projectRoot, state.projectName);
+    registerProject(state.projectRoot, { name: state.projectName });
     stampTemplateVersion(state.projectRoot, state.packageVersion);
 
     s.stop('Project ready.');
@@ -128,47 +130,294 @@ async function runProjectSetupInline(projectRoot: string, packageVersion: string
   await runProjectPhases(state, false);
 }
 
-// ─── Registration ──────────────────────────────────────────────
+// ─── Update Check ─────────────────────────────────────────────
 
-function registerProject(projectRoot: string, projectName?: string): void {
-  const registryPath = path.join(ORBITAL_HOME, 'config.json');
-  let registry: { version: number; projects: Array<Record<string, unknown>> };
+interface UpdateInfo {
+  current: string;
+  latest: string;
+  isOutdated: boolean;
+}
+
+async function checkForUpdate(
+  currentVersion: string,
+  cache: { lastUpdateCheck?: string; latestVersion?: string },
+): Promise<{ info: UpdateInfo | null; cacheChanged: boolean }> {
+  // Use cache if checked within 24 hours
+  if (cache.lastUpdateCheck && cache.latestVersion) {
+    const age = Date.now() - new Date(cache.lastUpdateCheck).getTime();
+    if (age < 24 * 60 * 60 * 1000) {
+      const isOutdated = cache.latestVersion !== currentVersion;
+      return {
+        info: { current: currentVersion, latest: cache.latestVersion, isOutdated },
+        cacheChanged: false,
+      };
+    }
+  }
 
+  // Fetch from npm registry
   try {
-    registry = fs.existsSync(registryPath)
-      ? JSON.parse(fs.readFileSync(registryPath, 'utf8'))
-      : { version: 1, projects: [] };
+    const res = await fetch('https://registry.npmjs.org/orbital-command/latest', {
+      signal: AbortSignal.timeout(3000),
+    });
+    const data = await res.json() as { version: string };
+    const latest = data.version;
+    return {
+      info: { current: currentVersion, latest, isOutdated: latest !== currentVersion },
+      cacheChanged: true,
+    };
   } catch {
-    registry = { version: 1, projects: [] };
+    return { info: null, cacheChanged: false };
   }
+}
 
-  if (!registry.projects) registry.projects = [];
-  if (registry.projects.some((proj: Record<string, unknown>) => proj.path === projectRoot)) return;
-
-  const COLORS = [
-    '210 80% 55%', '340 75% 55%', '160 60% 45%', '30 90% 55%',
-    '270 65% 55%', '50 85% 50%', '180 55% 45%', '0 70% 55%',
-  ];
-  const usedColors = registry.projects.map((proj: Record<string, unknown>) => proj.color);
-  const color = COLORS.find(c => !usedColors.includes(c)) || COLORS[0];
-
-  const name = projectName || path.basename(projectRoot);
-  const baseSlug = path.basename(projectRoot).toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '') || 'project';
-  const existingIds = registry.projects.map((proj: Record<string, unknown>) => proj.id);
-  const slug = existingIds.includes(baseSlug)
-    ? `${baseSlug}-${crypto.createHash('sha256').update(projectRoot).digest('hex').slice(0, 4)}`
-    : baseSlug;
-
-  registry.projects.push({
-    id: slug,
-    path: projectRoot,
-    name,
-    color,
-    registeredAt: new Date().toISOString(),
-    enabled: true,
+// ─── Hub Menu ─────────────────────────────────────────────────
+
+export type HubAction = 'launch' | 'init' | 'config' | 'doctor' | 'update' | 'status' | 'reset';
+
+export interface HubResult {
+  action: HubAction;
+  setItermPromptShown?: boolean;
+  updateCache?: { lastUpdateCheck: string; latestVersion?: string };
+}
+
+/**
+ * Context-aware hub menu — the main entry point for `orbital` (no args).
+ * Checks for updates, offers template sync, shows iTerm2 recommendation, then menu.
+ */
+export async function runHub(opts: {
+  packageVersion: string;
+  isProjectInitialized: boolean;
+  projectNames: string[];
+  itermPromptShown: boolean;
+  isMac: boolean;
+  lastUpdateCheck?: string;
+  latestVersion?: string;
+  projectPaths: Array<{ name: string; path: string }>;
+}): Promise<HubResult> {
+  const result: HubResult = { action: 'launch' };
+
+  p.intro(`${pc.bgCyan(pc.black(' Orbital Command '))} ${pc.dim(`v${opts.packageVersion}`)}`);
+
+  // ── Update check ──
+  const updateCheck = await checkForUpdate(opts.packageVersion, {
+    lastUpdateCheck: opts.lastUpdateCheck,
+    latestVersion: opts.latestVersion,
   });
 
-  fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2), 'utf8');
+  if (updateCheck.cacheChanged) {
+    result.updateCache = {
+      lastUpdateCheck: new Date().toISOString(),
+      latestVersion: updateCheck.info?.latest,
+    };
+  }
+
+  if (updateCheck.info?.isOutdated) {
+    p.log.info(
+      `Update available: ${pc.dim(`v${updateCheck.info.current}`)} → ${pc.cyan(`v${updateCheck.info.latest}`)}`
+    );
+
+    const updateChoice = await p.select({
+      message: 'Update Orbital Command now?',
+      options: [
+        { value: 'update', label: 'Yes, update' },
+        { value: 'skip', label: 'Skip for now' },
+      ],
+    });
+
+    if (!p.isCancel(updateChoice) && updateChoice === 'update') {
+      const s = p.spinner();
+      s.start('Updating Orbital Command...');
+      try {
+        execFileSync('npm', ['update', '-g', 'orbital-command'], { stdio: 'pipe', timeout: 60000 });
+        s.stop(`Updated to v${updateCheck.info.latest}!`);
+        p.outro(`Run ${pc.cyan('orbital')} again to use the new version.`);
+        process.exit(0);
+      } catch (err) {
+        s.stop('Update failed.');
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('EACCES') || msg.includes('permission denied')) {
+          p.log.error('Permission denied. Try running with sudo or ensure npm is installed via nvm.');
+        } else if (msg.includes('ETIMEDOUT') || msg.includes('timeout')) {
+          p.log.error('Update timed out. Check your network connection and try again.');
+        } else {
+          p.log.error(msg);
+        }
+      }
+    }
+  }
+
+  // ── Template staleness check ──
+  if (opts.projectPaths.length > 0) {
+    const mod = await import('../manifest.js');
+    const initMod = await import('../init.js');
+    const outdatedProjects: Array<{
+      name: string;
+      path: string;
+      details: string[];
+    }> = [];
+
+    for (const proj of opts.projectPaths) {
+      if (!fs.existsSync(proj.path)) {
+        p.log.warn(`${proj.name}: project path not found (${proj.path})`);
+        continue;
+      }
+      const manifest = mod.loadManifest(proj.path);
+      if (!manifest) continue;
+      const claudeDir = path.join(proj.path, '.claude');
+      mod.refreshFileStatuses(manifest, claudeDir);
+      const summary = mod.summarizeManifest(manifest);
+      const parts = Object.entries(summary.byType)
+        .filter(([, counts]) => counts.outdated > 0)
+        .map(([type, counts]) => `${counts.outdated} ${type}`);
+      if (parts.length > 0) {
+        outdatedProjects.push({ name: proj.name, path: proj.path, details: parts });
+      }
+    }
+
+    if (outdatedProjects.length > 0) {
+      const lines = outdatedProjects.map(proj =>
+        `  ${pc.cyan(proj.name.padEnd(16))} ${proj.details.join(', ')} outdated`
+      );
+      const count = outdatedProjects.length;
+      p.note(lines.join('\n'), `${count} project${count > 1 ? 's have' : ' has'} outdated templates`);
+
+      const syncChoice = await p.select({
+        message: 'Update project templates now?',
+        options: [
+          { value: 'update', label: 'Yes, update all safe files', hint: 'skips modified and pinned' },
+          { value: 'skip', label: 'Skip for now' },
+        ],
+      });
+
+      if (!p.isCancel(syncChoice) && syncChoice === 'update') {
+        for (const proj of outdatedProjects) {
+          const s = p.spinner();
+          s.start(`Updating ${proj.name}...`);
+          try {
+            initMod.runUpdate(proj.path, { dryRun: false });
+            s.stop(`${proj.name} updated.`);
+          } catch (err) {
+            s.stop(`${proj.name} failed.`);
+            p.log.warn(err instanceof Error ? err.message : String(err));
+          }
+        }
+      }
+    }
+  }
+
+  // ── iTerm2 recommendation (macOS only, one-time) ──
+  if (opts.isMac && !opts.itermPromptShown && !isITerm2Available()) {
+    p.note(
+      `Sprint dispatch, batch orchestration, and session management\n` +
+      `use iTerm2 tabs to run parallel Claude Code sessions.\n` +
+      `Without it, sessions fall back to basic subprocess mode.`,
+      'iTerm2 Recommended',
+    );
+
+    const itermChoice = await p.select({
+      message: 'Install iTerm2?',
+      options: [
+        { value: 'install', label: 'Open download page', hint: 'https://iterm2.com' },
+        { value: 'skip', label: 'Skip for now' },
+      ],
+    });
+
+    result.setItermPromptShown = true;
+
+    if (!p.isCancel(itermChoice) && itermChoice === 'install') {
+      spawn('open', ['https://iterm2.com'], { detached: true, stdio: 'ignore' }).unref();
+      p.log.info('Waiting for iTerm2 to install... (press any key to skip)');
+
+      await new Promise<void>((resolve) => {
+        let done = false;
+        const cleanup = (): void => {
+          if (done) return;
+          done = true;
+          process.stdin.setRawMode?.(false);
+          process.stdin.removeListener('data', onKey);
+          process.stdin.pause();
+          clearInterval(timer);
+          resolve();
+        };
+        const onKey = (): void => { cleanup(); };
+        const startTime = Date.now();
+        const MAX_WAIT = 10 * 60 * 1000; // 10 minutes
+        const timer = setInterval(() => {
+          if (isITerm2Available()) {
+            p.log.success('iTerm2 detected!');
+            cleanup();
+          } else if (Date.now() - startTime > MAX_WAIT) {
+            cleanup();
+          }
+        }, 3000);
+        process.stdin.setRawMode?.(true);
+        process.stdin.resume();
+        process.stdin.on('data', onKey);
+      });
+    }
+  }
+
+  // ── Build menu options based on project state ──
+  const projectHint = opts.projectNames.length > 0
+    ? pc.dim(` (${opts.projectNames.join(', ')})`)
+    : '';
+
+  const options: Array<{ value: HubAction; label: string; hint?: string }> = [];
+
+  if (opts.isProjectInitialized) {
+    options.push(
+      { value: 'launch', label: `Launch dashboard${projectHint}` },
+      { value: 'config', label: 'Config', hint: 'modify project settings' },
+      { value: 'doctor', label: 'Doctor', hint: 'health check & diagnostics' },
+      { value: 'update', label: 'Update templates', hint: 'sync to latest' },
+      { value: 'status', label: 'Status', hint: 'template sync status' },
+      { value: 'reset', label: 'Reset to defaults', hint: 'force-reset all templates' },
+    );
+  } else {
+    options.push(
+      { value: 'init', label: 'Initialize this project' },
+      { value: 'launch', label: `Launch dashboard${projectHint}` },
+    );
+  }
+
+  const action = await p.select({
+    message: 'What would you like to do?',
+    options,
+  });
+
+  if (p.isCancel(action)) {
+    p.cancel('Cancelled.');
+    process.exit(0);
+  }
+
+  // ── Double-confirm for destructive reset ──
+  if (action === 'reset') {
+    p.note(
+      'This will overwrite ALL hooks, skills, agents, and workflow config\n' +
+      'with the default templates. Modified and pinned files will be replaced.\n' +
+      'Your scopes, database, and orbital.config.json are preserved.',
+      'Warning',
+    );
+    const confirmReset = await p.confirm({
+      message: 'Are you sure you want to reset all templates?',
+      initialValue: false,
+    });
+    if (p.isCancel(confirmReset) || !confirmReset) {
+      p.cancel('Reset cancelled.');
+      process.exit(0);
+    }
+    const doubleConfirm = await p.confirm({
+      message: 'This cannot be undone. Continue?',
+      initialValue: false,
+    });
+    if (p.isCancel(doubleConfirm) || !doubleConfirm) {
+      p.cancel('Reset cancelled.');
+      process.exit(0);
+    }
+  }
+
+  result.action = action;
+  return result;
 }
 
 // ─── Template Version Stamping ─────────────────────────────────
@@ -181,7 +430,9 @@ function stampTemplateVersion(projectRoot: string, packageVersion: string): void
     const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
     if (config.templateVersion !== packageVersion) {
       config.templateVersion = packageVersion;
-      fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+      const tmp = configPath + `.tmp.${process.pid}`;
+      fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n', 'utf8');
+      fs.renameSync(tmp, configPath);
     }
   } catch { /* ignore malformed config */ }
 }

package/server/wizard/phases/welcome.ts

@@ -18,8 +18,7 @@ export async function phaseWelcome(state: ProjectSetupState): Promise<boolean> {
     const action = await p.select({
       message: 'What would you like to do?',
       options: [
-        { value: 'reinit', label: 'Re-initialize (--force)', hint: 'reset all templates to defaults' },
-        { value: 'configure', label: 'Open config editor', hint: 'modify settings without resetting' },
+        { value: 'configure', label: 'Open config editor', hint: 'modify settings' },
         { value: 'cancel', label: 'Cancel' },
       ],
     });
@@ -33,9 +32,6 @@ export async function phaseWelcome(state: ProjectSetupState): Promise<boolean> {
       await runConfigEditor(state.projectRoot, state.packageVersion, []);
       process.exit(0);
     }
-
-    // Re-init — continue through the full project setup with force
-    return true;
   }
 
   // Not initialized — continue normally

package/server/wizard/ui.ts

@@ -19,16 +19,15 @@ ${pc.cyan('.claude/')} directory — no database or external service required.`,
 
   setupComplete: `${pc.bold('Setup complete.')}
 
-  ${pc.cyan('orbital init')}            Add a project (run in a project directory)
-  ${pc.cyan('orbital launch --open')}   Start the dashboard
+  ${pc.cyan('orbital')}                 Add a project or launch the dashboard
   ${pc.cyan('orbital doctor')}          Health check & version info`,
 
-  addProject: `You can add projects now or later with ${pc.cyan('orbital init')}.
+  addProject: `You can add projects now or later by running ${pc.cyan('orbital')} in a project directory.
 Each project gets its own workflow, scopes, and quality gates.`,
 
   // Phase 2: Project setup (runs per-project)
   reconfigure: `This project is already initialized with Orbital Command.
-You can reconfigure settings or run ${pc.cyan('orbital init --force')} to reset.`,
+You can reconfigure settings or select ${pc.cyan('Reset to defaults')} from the hub menu.`,
 
   projectConfig: `${pc.bold('Project Config')} ${pc.dim('(.claude/orbital.config.json)')}
 
@@ -56,16 +55,16 @@ ${pc.cyan('Quality Gates')}  Automated checks (lint, typecheck, tests) before tr
 
   nextSteps: `${pc.bold('Next Steps')}
 
-  1. ${pc.cyan('orbital launch --open')}   Open the dashboard
+  1. Run ${pc.cyan('orbital')} and select ${pc.bold('Launch dashboard')}
   2. Create a scope from the board or use ${pc.cyan('/scope-create')}
   3. Use ${pc.cyan('/scope-implement')} to start working on a scope
 
 ${pc.bold('Useful Commands')}
 
+  ${pc.cyan('orbital')}           Hub menu — launch, config, doctor, etc.
   ${pc.cyan('orbital status')}    See template sync status
   ${pc.cyan('orbital config')}    Modify project settings
-  ${pc.cyan('orbital update')}    Sync to latest templates
-  ${pc.cyan('orbital doctor')}    Health check & version info`,
+  ${pc.cyan('orbital update')}    Sync to latest templates`,
 };
 
 // ─── Formatting Helpers ─────────────────────────────────────────

package/shared/api-types.ts

@@ -18,3 +18,109 @@ export interface AgentConfig {
   emoji: string;
   color: string;
 }
+
+// ─── Dispatch Flags (CLI flags passed to `claude`) ──────────
+
+export interface DispatchFlags {
+  permissionMode: 'bypass' | 'default' | 'plan' | 'acceptEdits';
+  verbose: boolean;
+  allowedTools: string[];
+  disallowedTools: string[];
+  appendSystemPrompt: string;
+  outputFormat: '' | 'text' | 'json' | 'stream-json';
+  noMarkdown: boolean;
+  printMode: boolean;
+}
+
+export const DEFAULT_DISPATCH_FLAGS: DispatchFlags = {
+  permissionMode: 'bypass',
+  verbose: true,
+  allowedTools: [],
+  disallowedTools: [],
+  appendSystemPrompt: '',
+  outputFormat: '',
+  noMarkdown: false,
+  printMode: false,
+};
+
+// ─── Dispatch Config (Orbital operational settings) ─────────
+
+export interface DispatchConfig {
+  staleTimeoutMinutes: number;
+  maxBatchSize: number;
+  maxConcurrent: number;
+  envVars: Record<string, string>;
+}
+
+export const DEFAULT_DISPATCH_CONFIG: DispatchConfig = {
+  staleTimeoutMinutes: 10,
+  maxBatchSize: 20,
+  maxConcurrent: 0,
+  envVars: {},
+};
+
+// ─── Validation ─────────────────────────────────────────────
+
+export const VALID_PERMISSION_MODES = ['bypass', 'default', 'plan', 'acceptEdits'] as const;
+export const VALID_OUTPUT_FORMATS = ['', 'text', 'json', 'stream-json'];
+export const VALID_TERMINAL_ADAPTERS = ['auto', 'iterm2', 'subprocess', 'none'];
+
+const SAFE_TOOL_NAME = /^[a-zA-Z0-9_:.-]+$/;
+const SAFE_ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export function validateToolName(name: string): boolean {
+  return SAFE_TOOL_NAME.test(name);
+}
+
+export function validateEnvKey(key: string): boolean {
+  return SAFE_ENV_KEY.test(key);
+}
+
+export function validateDispatchFlags(flags: Partial<DispatchFlags>): string | null {
+  if (flags.permissionMode !== undefined && !VALID_PERMISSION_MODES.includes(flags.permissionMode as typeof VALID_PERMISSION_MODES[number])) {
+    return `Invalid permissionMode: ${flags.permissionMode}`;
+  }
+  if (flags.outputFormat !== undefined && !VALID_OUTPUT_FORMATS.includes(flags.outputFormat as string)) {
+    return `Invalid outputFormat: ${flags.outputFormat}`;
+  }
+  if (flags.allowedTools !== undefined) {
+    if (!Array.isArray(flags.allowedTools)) return 'allowedTools must be an array';
+    for (const t of flags.allowedTools) {
+      if (typeof t !== 'string' || !validateToolName(t)) return `Invalid tool name: ${t}`;
+    }
+  }
+  if (flags.disallowedTools !== undefined) {
+    if (!Array.isArray(flags.disallowedTools)) return 'disallowedTools must be an array';
+    for (const t of flags.disallowedTools) {
+      if (typeof t !== 'string' || !validateToolName(t)) return `Invalid tool name: ${t}`;
+    }
+  }
+  if (flags.appendSystemPrompt !== undefined && typeof flags.appendSystemPrompt !== 'string') {
+    return 'appendSystemPrompt must be a string';
+  }
+  return null;
+}
+
+export function validateDispatchConfig(config: Partial<DispatchConfig> & { terminalAdapter?: string }): string | null {
+  if (config.terminalAdapter !== undefined && !VALID_TERMINAL_ADAPTERS.includes(config.terminalAdapter)) {
+    return `Invalid terminalAdapter: ${config.terminalAdapter}`;
+  }
+  if (config.staleTimeoutMinutes !== undefined && (typeof config.staleTimeoutMinutes !== 'number' || config.staleTimeoutMinutes < 1)) {
+    return 'staleTimeoutMinutes must be a positive number';
+  }
+  if (config.maxBatchSize !== undefined && (typeof config.maxBatchSize !== 'number' || config.maxBatchSize < 1)) {
+    return 'maxBatchSize must be a positive number';
+  }
+  if (config.maxConcurrent !== undefined && (typeof config.maxConcurrent !== 'number' || config.maxConcurrent < 0)) {
+    return 'maxConcurrent must be a non-negative number';
+  }
+  if (config.envVars !== undefined) {
+    if (typeof config.envVars !== 'object' || config.envVars === null || Array.isArray(config.envVars)) {
+      return 'envVars must be an object';
+    }
+    for (const key of Object.keys(config.envVars)) {
+      if (!validateEnvKey(key)) return `Invalid env var key: ${key}`;
+    }
+  }
+  return null;
+}

package/shared/workflow-engine.ts

@@ -385,7 +385,7 @@ export class WorkflowEngine {
       if (!targetList) continue;
       // Generate aliases for deployment-group targets (dev, staging, production)
       const group = targetList.group;
-      if (group === 'deployment') {
+      if (group?.startsWith('deploy')) {
         const sessionKey = targetList.sessionKey ?? '';
         lines.push(`  "to-${edge.to}:${edge.from}:${edge.to}:${sessionKey}"`);
       }

package/templates/agents/QUICK-REFERENCE.md

@@ -90,6 +90,7 @@ Before committing:
 | Chaos | "What breaks when things go wrong?" |
 | Frontend Designer | "What does the user see/experience?" |
 | Architect | "Does this fit our patterns?" |
+| Deep Dive | "What's the full picture before we change anything?" |
 | Rules Enforcer | "Do all project rules pass?" |
 
 ---

package/templates/agents/README.md

@@ -86,6 +86,7 @@ Every enforcement rule exists because a past mistake taught us it matters. Bypas
 │  "Protect quality and standards"                                           │
 │                                                                             │
 │     🏗️ Architect       - Patterns, structure, module boundaries            │
+│     🔬 Deep Dive       - Codebase audits, refactors, health reviews       │
 │     📋 Rules Enforcer  - Non-negotiable project rules (automated)          │
 │                                                                             │
 └─────────────────────────────────────────────────────────────────────────────┘

package/templates/agents/SKILL-TRIGGERS.md

@@ -85,6 +85,17 @@ These are **automatic** suggestions based on session state, not user phrases.
 
 ---
 
+## Agent Auto-Triggers by Phrase
+
+| User Says | Agent | Why |
+|-----------|-------|-----|
+| "Refactor", "clean up", "simplify" | 🔬 Deep Dive | Codebase health review needed |
+| "Tech debt", "health check", "audit" | 🔬 Deep Dive | Structural assessment |
+| "Pre-launch review", "before we release" | 🔬 Deep Dive | Comprehensive pre-release audit |
+| "Deep dive", "thorough review" | 🔬 Deep Dive | Explicit invocation |
+
+---
+
 ## Priority Order
 
 When multiple skills could apply, prioritize: