@jaimevalasek/aioson 1.17.3 → 1.19.0

package/src/commands/live.js

@@ -19,7 +19,7 @@ const {
 const { ensureDir, exists } = require('../utils');
 const { SUPPORTED_PROMPT_TOOLS } = require('../prompt-tool');
 const { isTmuxAvailable, launchTmuxSession, buildSessionName, hasSession, attachSession } = require('../lib/tmux-launcher');
-const { resolveResumeArgs } = require('../lib/tool-capabilities');
+const { resolvePermissionModeArgs, resolveResumeArgs } = require('../lib/tool-capabilities');
 
 const LIVE_EVENTS_LIMIT = 10;
 const LIVE_MESSAGE_LIMIT = 500;
@@ -116,14 +116,16 @@ function parseJsonOption(value) {
   }
 }
 
-// Combine `--resume` (mapped per-tool via TOOL_CAPS) with user-provided `--tool-args`.
-// Resume args go FIRST so that codex `resume --last` (subcommand) lands at argv[1].
-function buildLaunchArgs(options, tool) {
-  const resumeOpt = options.resume !== undefined ? options.resume : options.Resume;
-  const resumeArgs = resolveResumeArgs(tool, resumeOpt);
-  const userArgs = parseToolArgs(options['tool-args'] || options.toolArgs);
-  return [...resumeArgs, ...userArgs];
-}
+// Combine `--resume` (mapped per-tool via TOOL_CAPS) with user-provided `--tool-args`.
+// Resume args go FIRST so that codex `resume --last` (subcommand) lands at argv[1].
+function buildLaunchArgs(options, tool) {
+  const resumeOpt = options.resume !== undefined ? options.resume : options.Resume;
+  const resumeArgs = resolveResumeArgs(tool, resumeOpt);
+  const permissionMode = options['permission-mode'] || options.permissionMode;
+  const permissionArgs = resolvePermissionModeArgs(tool, permissionMode);
+  const userArgs = parseToolArgs(options['tool-args'] || options.toolArgs);
+  return [...resumeArgs, ...permissionArgs, ...userArgs];
+}
 
 function parseToolArgs(value) {
   if (value === undefined || value === null || value === '') return [];
@@ -234,7 +236,7 @@ async function resolveExecutablePath(command) {
     .filter(Boolean);
 
   const extensions = process.platform === 'win32'
-    ? Array.from(new Set(['', ...String(process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';').map((entry) => entry.toLowerCase())]))
+    ? Array.from(new Set([...String(process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';').map((entry) => entry.toLowerCase())]))
     : [''];
 
   for (const dir of pathEntries) {
@@ -1235,57 +1237,80 @@ async function runLiveStart({ args, options = {}, logger, t }) {
           };
         }
       } else {
-        // Non-tmux reuse logic (original behavior)
+        // Non-tmux reuse logic
         const existingTool = state.tool_session || null;
         if (existingTool && existingTool !== tool) {
-          throw new Error(t('live.tool_mismatch', { existing: existingTool, requested: tool }));
-        }
-
-        const attach = Boolean(options.attach);
-        let attachChild = null;
-        let attachResult = null;
-
-        if (attach && !noLaunch) {
-          attachChild = spawn(binaryPath, buildLaunchArgs(options, tool), {
-            cwd: targetDir,
-            env: process.env,
-            stdio: 'inherit'
+          // Auto-close stale session when tool changed (same pattern as tmux recovery above)
+          updateRun(db, {
+            runKey: existing.run.run_key,
+            status: 'completed',
+            summary: `Auto-closed: tool changed from ${existingTool} to ${tool}`,
+            eventType: 'session_closed',
+            phase: 'live',
+            message: `Tool mismatch — auto-closed previous ${existingTool} session`
           });
-          state.child_pid = attachChild.pid || null;
           if (existing.task?.task_key) {
-            const taskMeta = parseTaskMeta(existing.task);
-            taskMeta.child_pid = state.child_pid;
-            updateTask(db, { taskKey: existing.task.task_key, metaJson: taskMeta });
+            updateTask(db, {
+              taskKey: existing.task.task_key,
+              status: 'completed',
+              goal: `Auto-closed after tool change to ${tool}`
+            });
+          }
+          await clearAgentSession(runtimeDir, agentName);
+          if (!options.json) {
+            logger.log(t('live.tool_mismatch_auto_closed', { existing: existingTool, requested: tool }) ||
+              `Previous session (${existingTool}) auto-closed — starting new with ${tool}`);
+          }
+          // Fall through to create a new session below
+        } else {
+          // Tools match (or no previous tool) — reuse existing session
+          const attach = Boolean(options.attach);
+          let attachChild = null;
+          let attachResult = null;
+
+          if (attach && !noLaunch) {
+            attachChild = spawn(binaryPath, buildLaunchArgs(options, tool), {
+              cwd: targetDir,
+              env: process.env,
+              stdio: 'inherit',
+              shell: process.platform === 'win32'
+            });
+            state.child_pid = attachChild.pid || null;
+            if (existing.task?.task_key) {
+              const taskMeta = parseTaskMeta(existing.task);
+              taskMeta.child_pid = state.child_pid;
+              updateTask(db, { taskKey: existing.task.task_key, metaJson: taskMeta });
+            }
           }
-        }
 
-        await writeLiveState(runtimeDir, existing.sessionKey, state);
+          await writeLiveState(runtimeDir, existing.sessionKey, state);
 
-        if (!options.json) {
-          logger.log(t('live.session_already_active', { agent: agentName, session: existing.sessionKey, runKey: existing.run.run_key, dbPath }));
-        }
+          if (!options.json) {
+            logger.log(t('live.session_already_active', { agent: agentName, session: existing.sessionKey, runKey: existing.run.run_key, dbPath }));
+          }
 
-        if (attachChild) {
-          attachResult = await waitForChild(attachChild);
-        }
+          if (attachChild) {
+            attachResult = await waitForChild(attachChild);
+          }
 
-        return {
-          ok: true,
-          targetDir,
-          dbPath,
-          agent: existing.agentName,
-          tool: state.tool_session || tool,
-          taskKey: existing.task?.task_key || existing.sessionRef?.taskKey || null,
-          runKey: existing.run.run_key,
-          sessionKey: existing.sessionKey,
-          pid: state.child_pid || null,
-          processState: detectProcessState(state.child_pid),
-          reused: true,
-          open: true,
-          attached: attach,
-          childExitCode: attachResult?.code ?? null,
-          childSignal: attachResult?.signal ?? null
-        };
+          return {
+            ok: true,
+            targetDir,
+            dbPath,
+            agent: existing.agentName,
+            tool: state.tool_session || tool,
+            taskKey: existing.task?.task_key || existing.sessionRef?.taskKey || null,
+            runKey: existing.run.run_key,
+            sessionKey: existing.sessionKey,
+            pid: state.child_pid || null,
+            processState: detectProcessState(state.child_pid),
+            reused: true,
+            open: true,
+            attached: attach,
+            childExitCode: attachResult?.code ?? null,
+            childSignal: attachResult?.signal ?? null
+          };
+        }
       }
     }
 
@@ -1356,7 +1381,8 @@ async function runLiveStart({ args, options = {}, logger, t }) {
           child = spawn(binaryPath, buildLaunchArgs(options, tool), {
             cwd: targetDir,
             env: process.env,
-            stdio: 'inherit'
+            stdio: 'inherit',
+            shell: process.platform === 'win32'
           });
           taskMeta.child_pid = child.pid || null;
           updateTask(db, {
@@ -1368,7 +1394,8 @@ async function runLiveStart({ args, options = {}, logger, t }) {
         child = spawn(binaryPath, buildLaunchArgs(options, tool), {
           cwd: targetDir,
           env: process.env,
-          stdio: 'inherit'
+          stdio: 'inherit',
+          shell: process.platform === 'win32'
         });
         taskMeta.child_pid = child.pid || null;
         updateTask(db, {

package/src/commands/op-capture.js

@@ -27,6 +27,8 @@ const { captureSignal, readProposal, VALID_SIGNAL_TYPES } = require('../operator
 const { promoteProposal } = require('../operator-memory/decision');
 const { emitDossierEvent } = require('../lib/dossier-telemetry');
 
+const CONFIRMATIONS_JSONL = '.aioson/runtime/session-confirmations.jsonl';
+
 const PROMOTION_THRESHOLD = 2;
 
 function existsCheckFactory(identity) {
@@ -55,6 +57,8 @@ First detection writes to proposals/{slug}.md. Second detection promotes to deci
   const quote = options.quote;
   const proposal = options.proposal;
   const sourceAgent = options['source-agent'] || options.sourceAgent || 'unknown';
+  const featureSlug = options.feature ? String(options.feature) : null;
+  const sessionId = options['session-id'] || options.sessionId || null;
 
   if (!signal || !proposal) {
     const err = `op:capture — required: --signal=<type> --proposal=<paraphrase>. Got signal=${signal}, proposal=${proposal ? 'present' : 'missing'}.`;
@@ -95,7 +99,9 @@ First detection writes to proposals/{slug}.md. Second detection promotes to deci
       signal_type: signal,
       quote,
       proposal,
-      source_agent: sourceAgent
+      source_agent: sourceAgent,
+      feature_slug: featureSlug,
+      session_id: sessionId
     });
   } catch (err) {
     const errMsg = `op:capture failed: ${err.message}`;
@@ -104,6 +110,24 @@ First detection writes to proposals/{slug}.md. Second detection promotes to deci
     return { ok: false, exitCode: 1, error: errMsg };
   }
 
+  // M2: append confirmation signals to session accumulator for decision_rationale
+  if (signal === 'confirmation') {
+    try {
+      const accPath = path.join(targetDir, CONFIRMATIONS_JSONL);
+      const accDir = path.dirname(accPath);
+      fs.mkdirSync(accDir, { recursive: true });
+      const entry = JSON.stringify({
+        agent: sourceAgent,
+        decision: proposal,
+        quote: quote || null,
+        timestamp: new Date().toISOString()
+      });
+      fs.appendFileSync(accPath, entry + '\n', 'utf8');
+    } catch {
+      // best-effort — never block op:capture
+    }
+  }
+
   const count = result.proposal.detected_count;
 
   if (count >= PROMOTION_THRESHOLD) {
@@ -142,5 +166,6 @@ First detection writes to proposals/{slug}.md. Second detection promotes to deci
 
 module.exports = {
   runOpCapture,
-  PROMOTION_THRESHOLD
+  PROMOTION_THRESHOLD,
+  CONFIRMATIONS_JSONL
 };

package/src/commands/op-list.js

@@ -21,13 +21,15 @@ const { readDecision } = require('../operator-memory/decision');
 
 async function runOpList({ args = [], options = {}, logger }) {
   if (options.help === true || args.includes('--help') || args.includes('-h')) {
-    if (logger) logger.log('op:list [--proposals] [--include-archived] [--format=table|json] — list active decisions.');
+    if (logger) logger.log('op:list [--proposals] [--include-archived] [--feature=<slug>] [--agent=<name>] [--format=table|json] — list active decisions.');
     return { ok: true };
   }
 
   const format = options.format || 'table';
   const showProposals = Boolean(options.proposals);
   const includeArchived = Boolean(options['include-archived']);
+  const filterFeature = options.feature ? String(options.feature) : null;
+  const filterAgent = options.agent ? String(options.agent) : null;
 
   const resolved = resolveIdentity();
   ensureStorageTree(resolved.identity);
@@ -65,9 +67,39 @@ async function runOpList({ args = [], options = {}, logger }) {
     }
   }
 
+  // M3: apply --feature and --agent filters (BR-AO-07: AND-composable)
+  if (filterFeature) {
+    items = items.filter((item) => item.feature_slug === filterFeature);
+  }
+  if (filterAgent) {
+    items = items.filter((item) => item.source_agent === filterAgent);
+  }
+
   if (format === 'json' || options.json) {
+    // BR-AO-09: structured JSON output when --feature is used
+    if (filterFeature) {
+      const decisions = items.map((item) => ({
+        agent: item.source_agent || 'unknown',
+        signal: item.signal_type || null,
+        quote: Array.isArray(item.quotes) ? (item.quotes[item.quotes.length - 1] || null) : null,
+        proposal: item.proposal || item.body || item.title || null,
+        timestamp: item.last_reinforced || item.last_detected || null,
+        session_id: item.session_id || null
+      }));
+      const result = {
+        ok: true,
+        feature: filterFeature,
+        decisions,
+        total: decisions.length
+      };
+      if (options.json) return result;
+      if (logger) logger.log(JSON.stringify(result, null, 2));
+      return result;
+    }
+
     const result = {
       ok: true,
+      feature: null,
       identity: resolved.identity,
       identity_source: resolved.source,
       tier: showProposals ? 'proposals' : (includeArchived ? 'active+archive' : 'active'),

package/src/commands/store-system.js

@@ -351,6 +351,10 @@ async function runSystemPublish({ args, options, logger, t }) {
 
   logger.log('Creating ZIP package...');
   const zipBuffer = await createZipBuffer(files);
+  const MAX_ZIP_BYTES = 2 * 1024 * 1024;
+  if (zipBuffer.length > MAX_ZIP_BYTES) {
+    throw new Error(`ZIP exceeds 2 MB limit (${(zipBuffer.length / 1024 / 1024).toFixed(2)} MB). Reduce the number of files or bundle size.`);
+  }
   const zipBase64 = zipBuffer.toString('base64');
   const zipKb = (zipBuffer.length / 1024).toFixed(1);
   logger.log(`ZIP: ${zipKb} KB (${fileCount} files)`);

package/src/commands/tool-capabilities.js

@@ -6,9 +6,9 @@ const { TOOL_CAPS, getToolCapabilities, listSupportedTools } = require('../lib/t
 // so external clients (AIOSON Play, IDE extensions) can drive UI without
 // hard-coding their own copy of this lookup.
 //
-// Usage:
-//   aioson tool:capabilities --json
-//   aioson tool:capabilities --tool=claude --json
+// Usage:
+//   aioson tool:capabilities --json
+//   aioson tool:capabilities --tool=claude --json
 async function runToolCapabilities({ args: _args, options = {}, logger, t: _t }) {
   const tool = options.tool ? String(options.tool).trim() : null;
 
@@ -22,8 +22,8 @@ async function runToolCapabilities({ args: _args, options = {}, logger, t: _t })
     payload = { tool: tool.toLowerCase(), capabilities: caps };
   } else {
     payload = {
-      tools: TOOL_CAPS,
-      schema_version: 1,
+      tools: TOOL_CAPS,
+      schema_version: 2,
     };
   }
 
@@ -37,8 +37,8 @@ async function runToolCapabilities({ args: _args, options = {}, logger, t: _t })
     const caps = payload.capabilities;
     logger.log(`Tool: ${payload.tool}`);
     logger.log(`  binary:                ${caps.binary}`);
-    logger.log(`  install_command:       ${caps.install_command}`);
-    logger.log(`  supports_resume:       ${caps.supports_resume}`);
+    logger.log(`  install_command:       ${caps.install_command}`);
+    logger.log(`  supports_resume:       ${caps.supports_resume}`);
     if (caps.supports_resume) {
       logger.log(`  resume_last:           ${(caps.resume_last || []).join(' ')}`);
       logger.log(`  supports_session_id:   ${caps.supports_session_id}`);
@@ -48,9 +48,13 @@ async function runToolCapabilities({ args: _args, options = {}, logger, t: _t })
       logger.log(`  supports_session_picker: ${caps.supports_session_picker}`);
       if (caps.supports_session_picker) {
         logger.log(`  session_picker:        ${(caps.session_picker || []).join(' ')}`);
-      }
-    }
-  } else {
+      }
+    }
+    logger.log(`  supports_yolo:         ${caps.supports_yolo}`);
+    if (caps.supports_yolo) {
+      logger.log(`  yolo_args:             ${(caps.yolo_args || []).join(' ')}`);
+    }
+  } else {
     logger.log(`Supported tools: ${listSupportedTools().join(', ')}`);
     logger.log(`Run with --tool=<name> for details, or --json for the full map.`);
   }

package/src/commands/workflow-heal.js

@@ -12,6 +12,7 @@
  */
 
 const path = require('node:path');
+const fs = require('node:fs/promises');
 const {
   loadOrCreateState,
   activateStage,
@@ -26,6 +27,28 @@ const {
   incrementRetryCount,
   buildHealingActivation
 } = require('../self-healing');
+const { CHECKPOINTS_DIR } = require('./gate-approve');
+
+const GATE_ORDER = ['D', 'C', 'B', 'A'];
+
+async function readLatestCheckpoint(targetDir, slug) {
+  const dir = path.join(targetDir, CHECKPOINTS_DIR);
+  try {
+    const files = await fs.readdir(dir);
+    const matching = files
+      .filter((f) => f.endsWith(`-${slug}.json`))
+      .sort((a, b) => {
+        const gateA = a.replace('gate-', '').charAt(0);
+        const gateB = b.replace('gate-', '').charAt(0);
+        return GATE_ORDER.indexOf(gateA) - GATE_ORDER.indexOf(gateB);
+      });
+    if (matching.length === 0) return null;
+    const raw = await fs.readFile(path.join(dir, matching[0]), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
 
 async function runWorkflowHeal({ args, options, logger, t }) {
   const targetDir = path.resolve(process.cwd(), args[0] || '.');
@@ -58,6 +81,10 @@ async function runWorkflowHeal({ args, options, logger, t }) {
     return { ok: false, reason: 'stage_not_in_sequence' };
   }
 
+  // M1 checkpoint-at-gate: read latest checkpoint for recovery context (EC-AO-02: graceful fallback)
+  const featureSlug = state.featureSlug || null;
+  const checkpoint = featureSlug ? await readLatestCheckpoint(targetDir, featureSlug) : null;
+
   // Build healing activation
   let activation;
   try {
@@ -74,6 +101,24 @@ async function runWorkflowHeal({ args, options, logger, t }) {
     return { ok: false, reason: 'activation_failed', error: err.message };
   }
 
+  if (checkpoint) {
+    const sanitize = (s) => String(s || '').replace(/[\r\n]+/g, ' ').slice(0, 200);
+    const files = Array.isArray(checkpoint.prerequisites_snapshot)
+      ? checkpoint.prerequisites_snapshot.map((s) => sanitize(s && s.file)).join(', ') || 'none'
+      : 'none';
+    const cpBlock = [
+      '',
+      '## Checkpoint Recovery Context (auto-injected by AIOSON motor)',
+      '',
+      `> Last approved gate: **${sanitize(checkpoint.gate)}** (${sanitize(checkpoint.timestamp)})`,
+      `> Approved by: ${sanitize(checkpoint.agent)}`,
+      `> Artifacts at gate time: ${files}`,
+      ''
+    ].join('\n');
+    activation.prompt = activation.prompt + cpBlock;
+    activation.checkpoint = checkpoint;
+  }
+
   // Increment retry counter
   const newCount = await incrementRetryCount(targetDir, stage, activation.prompt.substring(0, 200));
 
@@ -127,10 +172,11 @@ async function runWorkflowHeal({ args, options, logger, t }) {
     retryCount: newCount,
     maxRetries: 3,
     runtime,
+    checkpoint: checkpoint || null,
     agent: activation.agent,
     instructionPath: activation.instructionPath,
     prompt: activation.prompt
   };
 }
 
-module.exports = { runWorkflowHeal };
+module.exports = { runWorkflowHeal, readLatestCheckpoint };

package/src/constants.js

@@ -190,6 +190,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'setup',
     displayName: 'Setup',
+    description: 'Project onboarding and context setup',
     command: '@setup',
     path: '.aioson/agents/setup.md',
     dependsOn: [],
@@ -198,6 +199,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'discovery-design-doc',
     displayName: 'Discovery/Design Doc',
+    description: 'Discovery and design doc generation',
     command: '@discovery-design-doc',
     path: '.aioson/agents/discovery-design-doc.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -206,6 +208,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'discover',
     displayName: 'Discover',
+    description: 'Semantic knowledge discovery and bootstrap cache generation',
     command: '@discover',
     path: '.aioson/agents/discover.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -214,6 +217,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'product',
     displayName: 'Product',
+    description: 'Product vision, PRD and feature scoping',
     command: '@product',
     path: '.aioson/agents/product.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -222,6 +226,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'deyvin',
     displayName: 'Deyvin',
+    description: 'Pair programming partner for continuity sessions',
     command: '@deyvin',
     path: '.aioson/agents/deyvin.md',
     aliases: ['pair'],
@@ -231,6 +236,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'analyst',
     displayName: 'Analyst',
+    description: 'Domain discovery and entity mapping (SMALL/MEDIUM)',
     command: '@analyst',
     path: '.aioson/agents/analyst.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -239,6 +245,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'architect',
     displayName: 'Architect',
+    description: 'Project structure and technical decisions (SMALL/MEDIUM)',
     command: '@architect',
     path: '.aioson/agents/architect.md',
     dependsOn: [
@@ -250,6 +257,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'ux-ui',
     displayName: 'UI/UX',
+    description: 'UI/UX design system and component spec (SMALL/MEDIUM)',
     command: '@ux-ui',
     path: '.aioson/agents/ux-ui.md',
     dependsOn: [
@@ -263,6 +271,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'pm',
     displayName: 'PM',
+    description: 'Backlog and user stories (MEDIUM only)',
     command: '@pm',
     path: '.aioson/agents/pm.md',
     dependsOn: [
@@ -277,6 +286,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'dev',
     displayName: 'Dev',
+    description: 'Feature implementation (any stack)',
     command: '@dev',
     path: '.aioson/agents/dev.md',
     dependsOn: [
@@ -289,8 +299,14 @@ const AGENT_DEFINITIONS = [
   {
     id: 'pentester',
     displayName: 'Pentester',
+    description: 'Adversarial security review and threat-surface mapping',
     command: '@pentester',
     path: '.aioson/agents/pentester.md',
+    flags: [
+      { name: 'mode', value: 'framework_target|app_target', description: 'Target mode for security review' },
+      { name: 'feature', value: '<slug>', description: 'Feature slug (required for app_target)' },
+      { name: 'scope', value: '<scope>', description: 'Target scope (required for app_target)' }
+    ],
     dependsOn: [
       '.aioson/context/project.context.md',
       '.aioson/context/spec-{slug}.md (active feature)'
@@ -300,6 +316,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'qa',
     displayName: 'QA',
+    description: 'Risk-first review and test generation (SMALL/MEDIUM)',
     command: '@qa',
     path: '.aioson/agents/qa.md',
     dependsOn: ['.aioson/context/discovery.md'],
@@ -308,6 +325,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'validator',
     displayName: 'Validator',
+    description: 'Technical validation against success contract',
     command: '@validator',
     path: '.aioson/agents/validator.md',
     dependsOn: [
@@ -319,6 +337,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'tester',
     displayName: 'Tester',
+    description: 'Systematic test engineering for implemented apps (all sizes)',
     command: '@tester',
     path: '.aioson/agents/tester.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -327,6 +346,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'orchestrator',
     displayName: 'Orchestrator',
+    description: 'Session protocol and parallel execution (MEDIUM)',
     command: '@orchestrator',
     path: '.aioson/agents/orchestrator.md',
     dependsOn: [
@@ -342,6 +362,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'squad',
     displayName: 'Squad',
+    description: 'Squad assembly and management',
     command: '@squad',
     path: '.aioson/agents/squad.md',
     dependsOn: [],
@@ -351,6 +372,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'orache',
     displayName: 'Orache',
+    description: 'Domain investigation and strategic research',
     command: '@orache',
     path: '.aioson/agents/orache.md',
     dependsOn: [],
@@ -359,6 +381,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'genome',
     displayName: 'Genome',
+    description: 'Domain genome creation and application',
     command: '@genome',
     path: '.aioson/agents/genome.md',
     dependsOn: [],
@@ -367,6 +390,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'design-hybrid-forge',
     displayName: 'Design Hybrid Forge',
+    description: 'Generate hybrid design skill from two visual parents',
     command: '@design-hybrid-forge',
     path: '.aioson/agents/design-hybrid-forge.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -375,14 +399,61 @@ const AGENT_DEFINITIONS = [
   {
     id: 'site-forge',
     displayName: 'Site Forge',
+    description: 'Clone, extract, and forge sites and design skills from any URL',
     command: '@site-forge',
     path: '.aioson/agents/site-forge.md',
     dependsOn: ['.aioson/context/project.context.md'],
     output: 'src/components/*.tsx + src/app/page.tsx + docs/research/{hostname}/ + public/images/{hostname}/'
   },
+  {
+    id: 'neo',
+    displayName: 'Neo',
+    description: 'System router: see the full picture, get guided to the right agent',
+    command: '@neo',
+    path: '.aioson/agents/neo.md',
+    dependsOn: ['.aioson/context/project.context.md'],
+    output: 'routing decision + agent handoff'
+  },
+  {
+    id: 'sheldon',
+    displayName: 'Sheldon',
+    description: 'Deep technical analysis and architecture review',
+    command: '@sheldon',
+    path: '.aioson/agents/sheldon.md',
+    dependsOn: ['.aioson/context/project.context.md'],
+    output: 'enriched PRD or architecture review'
+  },
+  {
+    id: 'committer',
+    displayName: 'Committer',
+    description: 'Professional Git commit generation from changes and context',
+    command: '@committer',
+    path: '.aioson/agents/committer.md',
+    dependsOn: [],
+    output: 'git commit(s)'
+  },
+  {
+    id: 'copywriter',
+    displayName: 'Copywriter',
+    description: 'Conversion-focused marketing copy',
+    command: '@copywriter',
+    path: '.aioson/agents/copywriter.md',
+    dependsOn: [],
+    output: 'marketing copy + content assets'
+  },
+  {
+    id: 'briefing',
+    displayName: 'Briefing',
+    description: 'Pre-production briefings and planning',
+    command: '@briefing',
+    path: '.aioson/agents/briefing.md',
+    dependsOn: ['.aioson/context/project.context.md'],
+    output: '.aioson/briefings/{slug}/'
+  },
   {
     id: 'profiler-researcher',
     displayName: 'Profiler Researcher',
+    description: 'Clone profiler: research phase',
     command: '@profiler-researcher',
     path: '.aioson/agents/profiler-researcher.md',
     dependsOn: [],
@@ -391,6 +462,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'profiler-enricher',
     displayName: 'Profiler Enricher',
+    description: 'Clone profiler: enrichment phase',
     command: '@profiler-enricher',
     path: '.aioson/agents/profiler-enricher.md',
     dependsOn: ['.aioson/profiler-reports/{person-slug}/research-report.md'],
@@ -399,6 +471,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'profiler-forge',
     displayName: 'Profiler Forge',
+    description: 'Clone profiler: forge and validate',
     command: '@profiler-forge',
     path: '.aioson/agents/profiler-forge.md',
     dependsOn: ['.aioson/profiler-reports/{person-slug}/enriched-profile.md'],