ai-engineering-loop 1.14.0 → 1.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/.agents/{workflows/ai-engineering-loop.md → skills/ai-engineering-loop/SKILL.md} +8 -6
  2. package/.agents/skills/ai-engineering-loop/references/loop-hosts.md +44 -0
  3. package/.claude/skills/ai-engineering-loop/SKILL.md +9 -10
  4. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +44 -0
  5. package/CHANGELOG.md +47 -0
  6. package/README.md +52 -6
  7. package/adapters/dot/README.md +1 -1
  8. package/bin/ai-engineering-loop.js +296 -11
  9. package/core/grill-policy.md +1 -1
  10. package/core/runtime-safety.md +2 -1
  11. package/lib/auto-update.js +3 -1
  12. package/lib/cli-args.js +11 -0
  13. package/lib/doctor.js +4 -15
  14. package/lib/host-skill-build.js +15 -15
  15. package/lib/hosts/agent-formats.js +135 -0
  16. package/lib/hosts/commands.js +126 -0
  17. package/lib/hosts/detect.js +56 -0
  18. package/lib/hosts/doctor.js +76 -0
  19. package/lib/hosts/redetect.js +60 -0
  20. package/lib/hosts/registry.js +271 -0
  21. package/lib/hosts/table.js +35 -0
  22. package/lib/run-abandon.js +116 -0
  23. package/lib/sync-hosts.js +155 -112
  24. package/package.json +2 -3
  25. package/.agents/devil-advocate.md +0 -79
  26. package/.agents/judge.md +0 -58
  27. package/.claude/commands/ai-engineering-loop.md +0 -11
  28. package/.gemini/skills/ai-engineering-loop/SKILL.md +0 -61
  29. package/.gemini/skills/animate/RECIPES.md +0 -324
  30. package/.gemini/skills/animate/SKILL.md +0 -207
  31. package/.gemini/skills/animate-expo/RECIPES.md +0 -385
  32. package/.gemini/skills/animate-expo/SKILL.md +0 -263
  33. package/.gemini/skills/animation-vocabulary/SKILL.md +0 -181
  34. package/.gemini/skills/apple-design/SKILL.md +0 -290
  35. package/.gemini/skills/ask-sonner/API.md +0 -64
  36. package/.gemini/skills/ask-sonner/SKILL.md +0 -88
  37. package/.gemini/skills/backend-development/SKILL.md +0 -272
  38. package/.gemini/skills/backend-development/references/api-design-guidelines.md +0 -95
  39. package/.gemini/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  40. package/.gemini/skills/backend-development/references/security-checklist.md +0 -60
  41. package/.gemini/skills/emil-design-eng/SKILL.md +0 -674
  42. package/.gemini/skills/find-animation-opportunities/SKILL.md +0 -140
  43. package/.gemini/skills/improve-animations/AUDIT.md +0 -115
  44. package/.gemini/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  45. package/.gemini/skills/improve-animations/SKILL.md +0 -109
  46. package/.gemini/skills/mobile-native/SKILL.md +0 -311
  47. package/.gemini/skills/pick-ui-library/SKILL.md +0 -85
  48. package/.gemini/skills/prototype/PICKER.md +0 -197
  49. package/.gemini/skills/prototype/SKILL.md +0 -98
  50. package/.gemini/skills/review-animations/SKILL.md +0 -120
  51. package/.gemini/skills/review-animations/STANDARDS.md +0 -187
  52. package/.gemini/skills/write-swift/SKILL.md +0 -396
  53. package/.grok/commands/ai-engineering-loop.md +0 -11
  54. package/.grok/skills/ai-engineering-loop/SKILL.md +0 -62
  55. package/.grok/skills/ai-engineering-loop/references/loop-commands.md +0 -20
  56. package/.grok/skills/ai-engineering-loop/references/loop-deliver.md +0 -8
  57. package/.grok/skills/ai-engineering-loop/references/loop-goal.md +0 -10
  58. package/.grok/skills/ai-engineering-loop/references/loop-maker.md +0 -8
  59. package/.grok/skills/ai-engineering-loop/references/loop-review.md +0 -18
  60. package/.grok/skills/ai-engineering-loop/references/loop-risky.md +0 -9
  61. package/.grok/skills/ai-engineering-loop/references/loop-verify.md +0 -20
  62. package/.grok/skills/animate/RECIPES.md +0 -324
  63. package/.grok/skills/animate/SKILL.md +0 -207
  64. package/.grok/skills/animate-expo/RECIPES.md +0 -385
  65. package/.grok/skills/animate-expo/SKILL.md +0 -263
  66. package/.grok/skills/animation-vocabulary/SKILL.md +0 -181
  67. package/.grok/skills/apple-design/SKILL.md +0 -290
  68. package/.grok/skills/ask-sonner/API.md +0 -64
  69. package/.grok/skills/ask-sonner/SKILL.md +0 -88
  70. package/.grok/skills/backend-development/SKILL.md +0 -272
  71. package/.grok/skills/backend-development/references/api-design-guidelines.md +0 -95
  72. package/.grok/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  73. package/.grok/skills/backend-development/references/security-checklist.md +0 -60
  74. package/.grok/skills/emil-design-eng/SKILL.md +0 -674
  75. package/.grok/skills/find-animation-opportunities/SKILL.md +0 -140
  76. package/.grok/skills/improve-animations/AUDIT.md +0 -115
  77. package/.grok/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  78. package/.grok/skills/improve-animations/SKILL.md +0 -109
  79. package/.grok/skills/mobile-native/SKILL.md +0 -311
  80. package/.grok/skills/pick-ui-library/SKILL.md +0 -85
  81. package/.grok/skills/prototype/PICKER.md +0 -197
  82. package/.grok/skills/prototype/SKILL.md +0 -98
  83. package/.grok/skills/review-animations/SKILL.md +0 -120
  84. package/.grok/skills/review-animations/STANDARDS.md +0 -187
  85. package/.grok/skills/write-swift/SKILL.md +0 -396
  86. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-commands.md +0 -0
  87. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-deliver.md +0 -0
  88. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-goal.md +0 -0
  89. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-maker.md +0 -0
  90. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-review.md +0 -0
  91. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-risky.md +0 -0
  92. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-verify.md +0 -0
@@ -18,12 +18,16 @@ const {
18
18
  homeDir,
19
19
  applyHostSync,
20
20
  hostSkillStatus,
21
+ resolveHostSelection,
22
+ planHostSync,
21
23
  formatHostSyncReport
22
24
  } = require('../lib/sync-hosts.js');
25
+ const hostCommands = require('../lib/hosts/commands.js');
23
26
  const { listDocs, readDoc } = require('../lib/docs.js');
24
27
  const {
25
28
  wantsCommandHelp,
26
29
  unknownWriterArgs,
30
+ effectiveCommand,
27
31
  commandHelp
28
32
  } = require('../lib/cli-args.js');
29
33
  const {
@@ -909,6 +913,12 @@ function statusJson() {
909
913
  result.contextVersion = metadata.contextVersion || null;
910
914
  result.projectProfile = metadata.projectProfile || null;
911
915
  result.freshness = { status: drift.status, reason: drift.reason, level: drift.level || null };
916
+ const activeRun = currentRunSafe(CWD);
917
+ if (activeRun && !TERMINAL_STATES.has(activeRun.state)) {
918
+ const info = require('../lib/run-abandon.js').staleRunInfo(activeRun);
919
+ result.activeRun = { runId: activeRun.runId, state: activeRun.state, updatedAt: activeRun.updatedAt || null, stale: info.stale, idleDays: info.idleDays };
920
+ if (info.stale) result.activeRun.hint = require('../lib/run-abandon.js').abandonCommand(activeRun.runId);
921
+ }
912
922
  }
913
923
  }
914
924
  return result;
@@ -950,6 +960,13 @@ function handleStatus() {
950
960
  console.log(`- Living Freshness: \x1b[32m${drift.status}\x1b[0m (${drift.reason})`);
951
961
  console.log(`- Context Files: ${REQUIRED_FILES.length}/${REQUIRED_FILES.length} verified (including metadata.json, glossary.md, adrs/)`);
952
962
 
963
+ const activeRun = currentRunSafe(CWD);
964
+ if (activeRun && !TERMINAL_STATES.has(activeRun.state)) {
965
+ console.log(`- Active run: ${activeRun.runId} (${activeRun.state})`);
966
+ const hint = staleRunHint(activeRun);
967
+ if (hint) log.warn(` ${hint}`);
968
+ }
969
+
953
970
  const hosts = hostSkillStatus({ home: homeDir(), version: VERSION });
954
971
  if (hosts.stale) {
955
972
  log.warn(`- Host skills: STALE (${hosts.staleFiles} file(s) behind package v${VERSION}${hosts.installedVersion ? `, installed v${hosts.installedVersion}` : ''})`);
@@ -1030,6 +1047,168 @@ function handleSyncHosts() {
1030
1047
  console.log(formatHostSyncReport(results, { version: VERSION, dryRun }));
1031
1048
  }
1032
1049
 
1050
+ function hostSyncOrExit(selection, { dryRun = false } = {}) {
1051
+ try {
1052
+ return applyHostSync({ home: homeDir(), hosts: selection, dryRun, version: VERSION });
1053
+ } catch (err) {
1054
+ log.error(`${err.code || 'SYNC_FAILED'}: ${err.message}`);
1055
+ process.exit(2);
1056
+ }
1057
+ }
1058
+
1059
+ function readTtyLine(question, fallback) {
1060
+ process.stdout.write(question);
1061
+ try {
1062
+ const buffer = Buffer.alloc(64);
1063
+ const bytes = fs.readSync(0, buffer, 0, buffer.length, null);
1064
+ return buffer.toString('utf8', 0, bytes).trim().toLowerCase() || fallback;
1065
+ } catch {
1066
+ return fallback;
1067
+ }
1068
+ }
1069
+
1070
+ // `hosts list|doctor|enable|disable` (issues #49, #52).
1071
+ function handleHosts() {
1072
+ const rest = process.argv.slice(3).filter((arg) => !arg.startsWith('-'));
1073
+ const sub = rest[0] || 'list';
1074
+ const json = process.argv.includes('--json');
1075
+ const home = homeDir();
1076
+ const selection = resolveHostSelection(home);
1077
+ if (sub === 'list') {
1078
+ const rows = hostCommands.listHosts({ home, selection });
1079
+ if (json) {
1080
+ console.log(JSON.stringify({ ok: true, source: selection.source, mode: selection.mode, hosts: rows }, null, 2));
1081
+ return;
1082
+ }
1083
+ console.log(hostCommands.formatHostsList(rows, selection));
1084
+ if (selection.source !== 'config') console.log('Run "ai-engineering-loop setup" to choose hosts explicitly.');
1085
+ return;
1086
+ }
1087
+ if (sub === 'doctor') {
1088
+ const { hostsDoctor, formatHostsDoctor } = require('../lib/hosts/doctor.js');
1089
+ const report = hostsDoctor({ home, selection, plan: planHostSync({ home, hosts: selection }) });
1090
+ console.log(json ? JSON.stringify(report, null, 2) : formatHostsDoctor(report));
1091
+ if (!report.ok) process.exitCode = 1;
1092
+ return;
1093
+ }
1094
+ if (sub !== 'enable' && sub !== 'disable') {
1095
+ log.error(`Unknown hosts subcommand "${sub}". Use: list, doctor, enable <id...>, disable <id...>. Nothing was written.`);
1096
+ process.exit(2);
1097
+ }
1098
+ let ids;
1099
+ try {
1100
+ ids = hostCommands.parseHostIds(rest.slice(1));
1101
+ } catch (err) {
1102
+ log.error(`${err.code}: ${err.message}. Nothing was written.`);
1103
+ process.exit(2);
1104
+ }
1105
+ if (!ids.length) {
1106
+ log.error(`hosts ${sub} needs at least one host id. Nothing was written.`);
1107
+ process.exit(2);
1108
+ }
1109
+ const next = hostCommands.changeHosts({ home, selection, [sub]: ids });
1110
+ const results = hostSyncOrExit(next);
1111
+ if (json) {
1112
+ console.log(JSON.stringify({ ok: true, [sub === 'enable' ? 'enabled' : 'disabled']: ids, hosts: [...next.enabled], files: results.map(({ content, ...item }) => item) }, null, 2));
1113
+ return;
1114
+ }
1115
+ log.info(`AI Engineering Loop — hosts ${sub} ${ids.join(', ')}`);
1116
+ console.log(formatHostSyncReport(results, { version: VERSION }));
1117
+ }
1118
+
1119
+ // `setup` (issue #49): the one-time, explicit replacement for a postinstall
1120
+ // hook. Detects agents (config folder or PATH binary, never executed), asks,
1121
+ // then syncs. Without a TTY it only prints the plan unless --yes is given.
1122
+ function handleSetup() {
1123
+ const home = homeDir();
1124
+ const json = process.argv.includes('--json');
1125
+ const yes = process.argv.includes('--yes');
1126
+ const hostsArg = argValue('--hosts');
1127
+ const modeArg = argValue('--mode');
1128
+ if (modeArg && !['auto', 'manual'].includes(modeArg)) {
1129
+ log.error('--mode must be auto or manual. Nothing was written.');
1130
+ process.exit(2);
1131
+ }
1132
+ const selection = resolveHostSelection(home);
1133
+ const rows = hostCommands.listHosts({ home, selection });
1134
+ let ids;
1135
+ try {
1136
+ ids = hostsArg ? hostCommands.parseHostIds(hostsArg) : rows.filter((row) => row.detected).map((row) => row.id);
1137
+ } catch (err) {
1138
+ log.error(`${err.code}: ${err.message}. Nothing was written.`);
1139
+ process.exit(2);
1140
+ }
1141
+ const interactive = process.stdin.isTTY && process.stdout.isTTY && !json && autoUpdate.autoUpdateAllowedHere();
1142
+ if (!yes && !interactive) {
1143
+ const plan = { ok: true, wrote: false, detected: rows.filter((row) => row.detected).map((row) => row.id), wouldEnable: ids };
1144
+ if (json) console.log(JSON.stringify(plan, null, 2));
1145
+ else {
1146
+ console.log(hostCommands.formatHostsList(rows, selection));
1147
+ console.log(`Would enable: ${ids.join(', ') || '(none detected)'}`);
1148
+ console.log('Nothing was written. Run "ai-engineering-loop setup --yes" (optionally --hosts a,b --mode auto|manual) to install.');
1149
+ }
1150
+ return;
1151
+ }
1152
+ let mode = hostCommands.setupMode({ modeArg, interactive: false });
1153
+ if (!yes) {
1154
+ console.log(hostCommands.formatHostsList(rows, selection));
1155
+ if (!ids.length) {
1156
+ console.log('No AI agent detected. Install one, or pick hosts with "setup --hosts <id,...>".');
1157
+ return;
1158
+ }
1159
+ const ok = readTtyLine(`Install the loop for ${ids.join(', ')}? [Y/n] `, 'y');
1160
+ if (!['y', 'yes'].includes(ok)) {
1161
+ console.log('Nothing was written.');
1162
+ return;
1163
+ }
1164
+ if (!modeArg) {
1165
+ mode = hostCommands.setupMode({ interactive: true, answer: readTtyLine(hostCommands.SETUP_MODE_QUESTION, '') });
1166
+ }
1167
+ }
1168
+ const next = hostCommands.applySetup({ home, ids, mode });
1169
+ const results = hostSyncOrExit(next);
1170
+ if (json) {
1171
+ console.log(JSON.stringify({ ok: true, wrote: true, enabled: [...next.enabled], mode: next.mode, files: results.map(({ content, ...item }) => item) }, null, 2));
1172
+ return;
1173
+ }
1174
+ log.info(`AI Engineering Loop — setup (${next.enabled.size} host${next.enabled.size === 1 ? '' : 's'}, mode ${next.mode})`);
1175
+ console.log(formatHostSyncReport(results, { version: VERSION }));
1176
+ }
1177
+
1178
+ // First-run hint (issue #49): no postinstall writes to HOME, so the first
1179
+ // interactive CLI use suggests `setup` once a day until hosts are chosen.
1180
+ function maybeSetupHint() {
1181
+ try {
1182
+ if (process.env.AEL_NO_SETUP_HINT === '1' || process.argv.includes('--json')) return;
1183
+ if (!process.stderr.isTTY || !autoUpdate.autoUpdateAllowedHere()) return;
1184
+ const home = homeDir();
1185
+ if (hostCommands.savedHosts(home)) return;
1186
+ const userState = require('../lib/user-state.js');
1187
+ const stampFile = userState.userStatePath('setup-hint.json', home);
1188
+ const last = userState.readJsonFile(stampFile, {});
1189
+ if (last.at && Date.now() - Date.parse(last.at) < 24 * 60 * 60 * 1000) return;
1190
+ const rows = hostCommands.listHosts({ home, selection: resolveHostSelection(home) });
1191
+ const detected = rows.filter((row) => row.detected).map((row) => row.id);
1192
+ if (!detected.length) return;
1193
+ userState.writeJsonFile(stampFile, { at: new Date().toISOString() });
1194
+ process.stderr.write(`ai-engineering-loop: detected ${detected.join(', ')}. Run "ai-engineering-loop setup" once to install the loop for them (silence: AEL_NO_SETUP_HINT=1).\n`);
1195
+ } catch {
1196
+ // A hint never breaks a command.
1197
+ }
1198
+ }
1199
+
1200
+ // New agents after setup (issue #52): `status` prints a short, rate-limited
1201
+ // notice in manual mode; auto mode is handled by the background `update auto`.
1202
+ function maybeNewHostsNotice() {
1203
+ try {
1204
+ if (process.argv.includes('--json') || !process.stderr.isTTY || !autoUpdate.autoUpdateAllowedHere()) return;
1205
+ const message = require('../lib/hosts/redetect.js').newHostsNotice({ home: homeDir() });
1206
+ if (message) process.stderr.write(`${message}\n`);
1207
+ } catch {
1208
+ // A notice never breaks a command.
1209
+ }
1210
+ }
1211
+
1033
1212
  function handleGenerateAdapter() {
1034
1213
  log.info('AI Engineering Loop — Generate delivery adapter (generate-adapter)');
1035
1214
  const hints = detectAdapterHints(CWD);
@@ -1085,7 +1264,72 @@ function workingTreePaths(rootDir) {
1085
1264
  }
1086
1265
 
1087
1266
  // Command: run
1267
+ // `run --abandon [--run <id>] --reason <text> --by <name> [--yes] [--json]`
1268
+ // (issue #46). ASSISTED asks for confirmation (or --yes); UNATTENDED runs are
1269
+ // refused unless a human passes --yes. Terminal runs exit 2.
1270
+ function handleRunAbandon() {
1271
+ const json = process.argv.includes('--json');
1272
+ const yes = process.argv.includes('--yes');
1273
+ const runAbandon = require('../lib/run-abandon.js');
1274
+ const fail = (err) => {
1275
+ if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'ABANDON_FAILED', error: err.message }));
1276
+ else log.error(err.message);
1277
+ process.exit(err.exitCode || 1);
1278
+ };
1279
+ try {
1280
+ const plan = runAbandon.planAbandon(CWD, { runId: argValue('--run'), reason: argValue('--reason'), by: argValue('--by') });
1281
+ const { run } = plan;
1282
+ if (run.mode === 'UNATTENDED' && !yes) {
1283
+ throw Object.assign(new Error(`Run ${run.runId} is UNATTENDED. Agents must not abandon it; a human can re-run with --yes.`), { code: 'UNATTENDED_REQUIRES_HUMAN', exitCode: 2 });
1284
+ }
1285
+ if (!yes) {
1286
+ if (json || !process.stdin.isTTY || !process.stdout.isTTY) {
1287
+ throw Object.assign(new Error(`Confirm abandoning run ${run.runId} (${run.state}) by re-running with --yes.`), { code: 'CONFIRMATION_REQUIRED' });
1288
+ }
1289
+ process.stdout.write(`Abandon run ${run.runId} (${run.state}, ${run.task ? `"${String(run.task).slice(0, 60)}"` : 'no task'})? Run data is kept. [y/N] `);
1290
+ const buffer = Buffer.alloc(16);
1291
+ let answer = '';
1292
+ try {
1293
+ answer = buffer.toString('utf8', 0, fs.readSync(0, buffer, 0, buffer.length, null)).trim().toLowerCase();
1294
+ } catch {
1295
+ answer = '';
1296
+ }
1297
+ if (!['y', 'yes'].includes(answer)) {
1298
+ console.log('Not abandoned.');
1299
+ process.exit(1);
1300
+ }
1301
+ }
1302
+ const result = runAbandon.abandonRun(CWD, { runId: run.runId, reason: plan.reason, by: plan.actor });
1303
+ if (json) console.log(JSON.stringify({ ok: true, ...result }));
1304
+ else {
1305
+ log.success(`✓ Run ${result.runId} abandoned (${result.from} -> CANCELLED) by ${result.by}: ${result.reason}`);
1306
+ console.log(result.released
1307
+ ? '- current.json released; refresh and auto-update will process this project again.'
1308
+ : `- current run unchanged${result.current ? ` (${result.current})` : ''}.`);
1309
+ }
1310
+ } catch (err) {
1311
+ fail(err);
1312
+ }
1313
+ }
1314
+
1315
+ // One-line hint for an active run that has not moved for STALE_RUN_DAYS.
1316
+ function staleRunHint(run) {
1317
+ const runAbandon = require('../lib/run-abandon.js');
1318
+ const info = runAbandon.staleRunInfo(run);
1319
+ if (!info.stale) return null;
1320
+ return `Run ${run.runId} has been ${run.state} for ${info.idleDays} day(s). If it is abandoned: ${runAbandon.abandonCommand(run.runId)}`;
1321
+ }
1322
+
1323
+ function currentRunSafe(dir) {
1324
+ try {
1325
+ return getCurrentRun(dir);
1326
+ } catch {
1327
+ return null;
1328
+ }
1329
+ }
1330
+
1088
1331
  function handleRun() {
1332
+ if (process.argv.includes('--abandon')) return handleRunAbandon();
1089
1333
  const runJson = process.argv.includes('--json');
1090
1334
  const realLog = console.log;
1091
1335
  if (runJson) console.log = () => {};
@@ -1264,7 +1508,7 @@ function handleRun() {
1264
1508
  } else {
1265
1509
  console.log(`- Fallback: CONTEXT_ISOLATION_ONLY (${grok.reason})`);
1266
1510
  }
1267
- console.log('- Skill: .grok/skills/ai-engineering-loop/SKILL.md');
1511
+ console.log('- Skill: .agents/skills/ai-engineering-loop/SKILL.md (spawn rules: references/loop-hosts.md, Grok CLI section)');
1268
1512
  }
1269
1513
 
1270
1514
  const claudeSkill = path.join(CWD, '.claude', 'skills', 'ai-engineering-loop', 'SKILL.md');
@@ -1279,14 +1523,14 @@ function handleRun() {
1279
1523
  console.log('- Skill: .claude/skills/ai-engineering-loop/SKILL.md');
1280
1524
  }
1281
1525
 
1282
- const agAgent = path.join(CWD, '.agents', 'judge.md');
1283
- if (fs.existsSync(agAgent)) {
1526
+ const sharedSkill = path.join(CWD, '.agents', 'skills', 'ai-engineering-loop', 'SKILL.md');
1527
+ if (fs.existsSync(sharedSkill)) {
1284
1528
  console.log('------------------------------------------------------------');
1285
- log.bold('Antigravity host:');
1286
- console.log('- Subagent: invoke_subagent or Task; wait; never browser_subagent');
1529
+ log.bold('Shared .agents/skills hosts (Codex, Gemini CLI, Antigravity, Cursor, Copilot, ...):');
1530
+ console.log('- Same skill on every host; spawn rules per host: references/loop-hosts.md');
1287
1531
  console.log('- Devil\'s Advocate: 8 tool calls, diff file, skip css');
1288
1532
  console.log('- Judge: 4 tool calls, ledger + contract only');
1289
- console.log('- Workflow: .agents/workflows/ai-engineering-loop.md');
1533
+ console.log('- Skill: .agents/skills/ai-engineering-loop/SKILL.md');
1290
1534
  }
1291
1535
  console.log('------------------------------------------------------------\n');
1292
1536
  }
@@ -2001,6 +2245,8 @@ function handleState() {
2001
2245
  console.log(`State: ${run.state}`);
2002
2246
  console.log(`Iteration: ${run.iteration}`);
2003
2247
  console.log(`Artifacts: ${Object.keys(run.artifacts).join(', ') || 'none'}`);
2248
+ const hint = staleRunHint(run);
2249
+ if (hint) log.warn(hint);
2004
2250
  }
2005
2251
  } catch (err) {
2006
2252
  if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'STATE_FAILED', error: err.message }));
@@ -2044,6 +2290,7 @@ function handleSafeRefresh() {
2044
2290
  const current = getCurrentRun(CWD);
2045
2291
  if (current && !TERMINAL_STATES.has(current.state)) {
2046
2292
  log.warn(`Run ${current.runId} is active (${current.state}); skipping refresh until it finishes.`);
2293
+ log.dim(`If that run is abandoned, close it first: ${require('../lib/run-abandon.js').abandonCommand(current.runId)}`);
2047
2294
  process.exit(3);
2048
2295
  }
2049
2296
  const legacy = !fs.existsSync(path.join(CONTEXT_DIR, GENERATED_HASHES_FILE));
@@ -2190,6 +2437,17 @@ function handleUpdateAuto() {
2190
2437
  // Best effort.
2191
2438
  }
2192
2439
  const decision = autoUpdate.decideUpdate({ current: VERSION, distTags: cache.distTags, ...policy });
2440
+ // Agents installed after setup (#52): auto mode enables and syncs them here.
2441
+ let hostsResult = { added: [] };
2442
+ try {
2443
+ hostsResult = require('../lib/hosts/redetect.js').autoEnableNewHosts({ home: homeDir(), scope });
2444
+ if (hostsResult.added.length && decision.action !== 'apply') {
2445
+ const synced = applyHostSync({ home: homeDir(), hosts: resolveHostSelection(homeDir()), version: VERSION });
2446
+ hostsResult = { ...hostsResult, synced: synced.filter((item) => item.action === 'copy').length };
2447
+ }
2448
+ } catch (err) {
2449
+ hostsResult = { added: [], error: err.message };
2450
+ }
2193
2451
  const projects = projectRegistry.listProjects().projects;
2194
2452
  let result = null;
2195
2453
  if (decision.action === 'apply') {
@@ -2205,7 +2463,10 @@ function handleUpdateAuto() {
2205
2463
  } else {
2206
2464
  result = autoUpdate.processPending({ projects, readCurrentRun: readCurrentRunFor });
2207
2465
  }
2208
- out({ ok: true, policy: policy.policy, policySource: policy.source, scope, offline: cache.error || null, decision, result });
2466
+ const held = result && Array.isArray(result.pending) && result.pending.length
2467
+ ? { pendingHint: `Projects skipped because a run is active. If a run is abandoned, run in that project: ${require('../lib/run-abandon.js').abandonCommand()}` }
2468
+ : {};
2469
+ out({ ok: true, policy: policy.policy, policySource: policy.source, scope, offline: cache.error || null, decision, result, hosts: hostsResult, ...held });
2209
2470
  cacheUpdateHighlights({ ...cache, scope }, decision, packageName).catch(() => {});
2210
2471
  }
2211
2472
 
@@ -2258,7 +2519,12 @@ function handleProjects() {
2258
2519
  if (json) console.log(JSON.stringify({ ok: true, action, ...result }));
2259
2520
  else if (action === 'list') {
2260
2521
  if (!result.projects.length) console.log('No registered projects. They are added by init/run/status/refresh, or `projects add|scan`.');
2261
- for (const p of result.projects) console.log(`- ${p.path} (context ${p.contextVersion || '?'}, seen ${p.lastSeen})`);
2522
+ for (const p of result.projects) {
2523
+ const held = currentRunSafe(p.path);
2524
+ const info = held ? require('../lib/run-abandon.js').staleRunInfo(held) : { stale: false };
2525
+ const tag = info.stale ? `; held by stale run ${held.runId} (${held.state}, ${info.idleDays}d): run --abandon there` : '';
2526
+ console.log(`- ${p.path} (context ${p.contextVersion || '?'}, seen ${p.lastSeen}${tag})`);
2527
+ }
2262
2528
  } else console.log(JSON.stringify(result, null, 2));
2263
2529
  } catch (err) {
2264
2530
  if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'PROJECTS_FAILED', error: err.message }));
@@ -3046,6 +3312,9 @@ Commands:
3046
3312
  --recipe <id> bind an immutable compiled workflow plan
3047
3313
  --tier T0|T1|T2 --tier-reason <text> override the automatic tier (recorded)
3048
3314
  --json print runId, tier, tier reasons, and subagent count only
3315
+ --abandon [--run <id>] --reason <text> --by <name> [--yes] [--json]
3316
+ close a stale run as CANCELLED (kept on disk) and release current.json;
3317
+ ASSISTED asks to confirm, UNATTENDED needs --yes from a human
3049
3318
  state Inspect the current run ledger
3050
3319
  --run <id> target a non-current run
3051
3320
  --json print the complete machine-readable ledger
@@ -3162,7 +3431,13 @@ Commands:
3162
3431
  create [--run <id>] [--audience developer|agent|auditor]
3163
3432
  [--output <repository-relative-file>|-] [--json]
3164
3433
  inspect | brief <repository-relative-file> [--json]
3165
- sync-hosts Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
3434
+ setup One-time: detect AI agents (config folder or PATH binary, never run) and install for them
3435
+ --yes skip the prompt --hosts <id,...> pick hosts --json
3436
+ --mode auto|manual (prompt suggests auto; --yes / no TTY default to manual)
3437
+ Without a TTY and without --yes it only prints the plan
3438
+ hosts Show or change which AI agent hosts get the loop
3439
+ list [--json] | doctor [--json] | enable <id...> | disable <id...> (removes unedited AEL files)
3440
+ sync-hosts Install the loop skill and reviewer agents into every detected AI agent host
3166
3441
  (only hosts that already exist; DOT skills only if already installed)
3167
3442
  --dry-run print the plan without writing
3168
3443
  --pack <list> core (always), backend, design, quality; saved for later syncs
@@ -3194,14 +3469,15 @@ const command = args[0] || 'init';
3194
3469
  // Side-effect guard (issue #25): help never executes a command, and writer
3195
3470
  // commands reject unknown flags before touching any file.
3196
3471
  if (!['-h', '--help', '-v', '--version'].includes(command)) {
3197
- if (wantsCommandHelp(command, args.slice(1))) {
3472
+ const checked = effectiveCommand(command, args.slice(1));
3473
+ if (wantsCommandHelp(checked, args.slice(1))) {
3198
3474
  const block = commandHelp(helpText(), command);
3199
3475
  console.log(block
3200
3476
  ? `Usage: npx ai-engineering-loop ${block.trim()}`
3201
3477
  : helpText());
3202
3478
  process.exit(0);
3203
3479
  }
3204
- const unknown = unknownWriterArgs(command, args.slice(1));
3480
+ const unknown = unknownWriterArgs(checked, args.slice(1));
3205
3481
  if (unknown.length > 0) {
3206
3482
  log.error(`Unknown argument(s) for "${command}": ${unknown.join(' ')}. Nothing was written.`);
3207
3483
  console.log(`Run "npx ai-engineering-loop ${command} --help" for usage.`);
@@ -3217,6 +3493,9 @@ if (['init', 'run', 'status', 'refresh'].includes(command)) {
3217
3493
  maybeAutoUpdate();
3218
3494
  }
3219
3495
 
3496
+ if (!['setup', 'hosts', 'sync-hosts', '-h', '--help', '-v', '--version'].includes(command)) maybeSetupHint();
3497
+ if (command === 'status') maybeNewHostsNotice();
3498
+
3220
3499
  switch (command) {
3221
3500
  case 'init':
3222
3501
  handleInit();
@@ -3311,6 +3590,12 @@ switch (command) {
3311
3590
  case 'sync-hosts':
3312
3591
  handleSyncHosts();
3313
3592
  break;
3593
+ case 'hosts':
3594
+ handleHosts();
3595
+ break;
3596
+ case 'setup':
3597
+ handleSetup();
3598
+ break;
3314
3599
  case 'generate-adapter':
3315
3600
  handleGenerateAdapter();
3316
3601
  break;
@@ -64,7 +64,7 @@ When the change can touch state, siblings, actors/approvals, or downstream work,
64
64
 
65
65
  On `adapter_type: dot`, this is mandatory. On other adapters, skip only when the change cannot touch those four (copy, CSS, comment).
66
66
 
67
- Canonical skill: `adapters/dot/skills/task-impact-inquiry/SKILL.md`. Host copies via `sync-hosts`: `~/.claude/skills/task-impact-inquiry/`, `~/.grok/skills/task-impact-inquiry/`, `~/.gemini/config/skills/task-impact-inquiry/`. Load that skill if present. If it is missing, still run this section. Do not claim the skill ran.
67
+ Canonical skill: `adapters/dot/skills/task-impact-inquiry/SKILL.md`. Host copies via `sync-hosts`: `~/.claude/skills/task-impact-inquiry/`, `~/.agents/skills/task-impact-inquiry/` (Codex, Gemini CLI, Grok, Cursor, Copilot, and other shared-folder hosts), `~/.gemini/config/skills/task-impact-inquiry/` (Antigravity). Load that skill if present. If it is missing, still run this section. Do not claim the skill ran.
68
68
 
69
69
  If Stage 1 grill already produced the matrix and the user confirmed it, do not run a second interview.
70
70
 
@@ -97,8 +97,9 @@ The CLI may update itself, but only under the policy the user chose (`~/.ai-engi
97
97
 
98
98
  - **Check:** `run`, `status`, `init`, and `refresh` start `update auto --background` detached at most once every 24 hours (`npm view <pkg> dist-tags`, 3 s timeout). The command itself never waits. Offline or failed checks keep the cached tags and stay silent.
99
99
  - **Opt-out:** `AEL_NO_AUTO_UPDATE=1`, `CI=true`, or `update policy off`.
100
- - **Apply (global installs only):** acquire `~/.ai-engineering-loop/update.lock`, verify the release (registry `repository.url` must match this package, and `dist.integrity` must exist), `npm install -g <pkg>@<target>`, `sync-hosts`, then `refresh --non-destructive` in every project in `~/.ai-engineering-loop/projects.json`. User-edited context files are kept and new templates are written as `*.ael-new`. Projects with an active run are skipped and retried later. Updates are deferred entirely while any UNATTENDED run is active.
100
+ - **Apply (global installs only):** acquire `~/.ai-engineering-loop/update.lock`, verify the release (registry `repository.url` must match this package, and `dist.integrity` must exist), `npm install -g <pkg>@<target>`, `sync-hosts`, then `refresh --non-destructive` in every project in `~/.ai-engineering-loop/projects.json`. User-edited context files are kept and new templates are written as `*.ael-new`. Projects with an active run are skipped and retried later; a human closes a stale run with `run --abandon --reason <text> --by <name>` (agents never abandon a run on their own). Updates are deferred entirely while any UNATTENDED run is active.
101
101
  - **Project installs (devDependency or npx):** notify only. `package.json` and lockfiles are never changed automatically. The notice shows current -> latest, 2-4 CHANGELOG highlights, one update command for the detected package manager (npm/pnpm/yarn/bun), and how to silence it (`AEL_NO_UPDATE_NOTICE=1` or `update policy off`). It appears at most once per 24 h per project, on an interactive stderr only, never in CI or `--json` output. Global `notify` and major notices use the same format.
102
+ - **Host setup (no install hooks):** the package defines no `preinstall`/`install`/`postinstall` script, so installing never writes to `$HOME`. `ai-engineering-loop setup` (interactive, or `--yes`) detects agents by config folder or by an executable on `PATH` (stat only, never executed) and saves the selection in `~/.ai-engineering-loop/config.json` (`hosts.enabled`, `hosts.disabled`, `hosts.mode`). `hosts enable|disable <id...>` change it; disabling removes only manifest-tracked, unedited AEL files. Before `setup`, sync writes only to hosts whose config folder exists. Agents never run `setup` or `hosts enable|disable` on their own initiative. Agents installed later are re-detected (stat only): with `hosts.mode: auto` the background `update auto` of a global install enables and syncs them (never a host the user disabled); with `manual` `status` shows one rate-limited notice. Neither writes or prints in CI, in `--json` output, or with `AEL_NO_AUTO_UPDATE`. `hosts doctor` is read-only.
102
103
  - **Legacy projects (no `.ael-generated.json` yet):** the first `refresh --non-destructive` overwrites AEL-managed context files directly and deletes obsolete AEL-managed files instead of writing `*.ael-new`. Old copies go to `.ai-engineering-loop/.ael-backup/<timestamp>/` first, and hashes are recorded so later updates use the normal flow. Append-only files (lessons, glossary) and all other user files are never touched. `sync-hosts` likewise removes host files it recorded in its manifest that the package no longer ships (unless edited).
103
104
  - **Majors:** `update apply --yes` runs `ai-engineering-loop migrate --from <old>` right after the install. `migrations/<major>.js` steps are idempotent and recorded in `~/.ai-engineering-loop/migrations.json`.
104
105
  - **Rollback:** `update rollback --yes` reinstalls the previous version, re-syncs host skills, and restores any legacy-update snapshot taken by that update.
@@ -435,7 +435,9 @@ function consumeSummary(home = homeDir()) {
435
435
  const last = state.lastApplied;
436
436
  if (!last || last.shown) return null;
437
437
  writeState({ ...state, lastApplied: { ...last, shown: true } }, home);
438
- const pending = last.pending && last.pending.length ? `, ${last.pending.length} pending` : '';
438
+ const pending = last.pending && last.pending.length
439
+ ? `, ${last.pending.length} pending (active run; if abandoned: ai-engineering-loop run --abandon --reason "<why>" --by <name> in that project)`
440
+ : '';
439
441
  const failed = last.failed && last.failed.length ? `, ${last.failed.length} failed` : '';
440
442
  return `ai-engineering-loop updated ${last.from} -> ${last.to}; hosts ${last.hosts}; ${last.refreshed}/${last.total} projects refreshed${pending}${failed}.`;
441
443
  }
package/lib/cli-args.js CHANGED
@@ -13,8 +13,12 @@ const WRITER_COMMANDS = Object.freeze({
13
13
  init: { flags: [], valued: [], positionals: [] },
14
14
  refresh: { flags: ['--non-destructive', '--json'], valued: [], positionals: [] },
15
15
  'sync-hosts': { flags: ['--dry-run', '--prune', '--json'], valued: ['--pack'], positionals: [] },
16
+ setup: { flags: ['--yes', '--json'], valued: ['--hosts', '--mode'], positionals: [] },
17
+ hosts: { flags: ['--json'], valued: [], positionals: null },
16
18
  update: { flags: ['--json', '--yes', '--background', '--force', '--no-pin'], valued: ['--channel', '--pin'], positionals: ['check', 'plan', 'apply', 'auto', 'policy', 'rollback', ...['off', 'notify', 'patch', 'minor', 'all']] },
17
19
  projects: { flags: ['--json'], valued: ['--root', '--depth'], positionals: null },
20
+ // `run --abandon` (issue #46) is a writer; plain `run` takes free text.
21
+ 'run:abandon': { flags: ['--abandon', '--yes', '--json'], valued: ['--run', '--reason', '--by'], positionals: [] },
18
22
  migrate: { flags: ['--json', '--dry-run'], valued: ['--from'], positionals: [] },
19
23
  verify: { flags: ['--json', '--serial', '--shell'], valued: ['--run', '--cmd', '--timeout-ms'], positionals: [] },
20
24
  'review-pack': { flags: ['--json'], valued: ['--run', '--base', '--profile'], positionals: [] },
@@ -28,6 +32,12 @@ function beforeSeparator(args) {
28
32
  return index === -1 ? args : args.slice(0, index);
29
33
  }
30
34
 
35
+ // `run --abandon ...` is checked as its own writer command.
36
+ function effectiveCommand(command, rest) {
37
+ if (command === 'run' && beforeSeparator(rest).includes('--abandon')) return 'run:abandon';
38
+ return command;
39
+ }
40
+
31
41
  function wantsCommandHelp(command, rest) {
32
42
  const scoped = beforeSeparator(rest);
33
43
  // `run` takes free-text task words; only a leading help flag counts.
@@ -78,6 +88,7 @@ module.exports = {
78
88
  HELP_FLAGS,
79
89
  WRITER_COMMANDS,
80
90
  beforeSeparator,
91
+ effectiveCommand,
81
92
  wantsCommandHelp,
82
93
  unknownWriterArgs,
83
94
  commandHelp
package/lib/doctor.js CHANGED
@@ -18,27 +18,16 @@ const REQUIRED_HOST_ASSETS = [
18
18
  '.claude/skills/review-animations/SKILL.md',
19
19
  '.claude/agents/devil-advocate.md',
20
20
  '.claude/agents/judge.md',
21
- '.grok/skills/ai-engineering-loop/SKILL.md',
22
- '.grok/skills/ai-engineering-loop/references/loop-review.md',
23
- '.grok/skills/backend-development/SKILL.md',
24
- '.grok/skills/emil-design-eng/SKILL.md',
25
- '.grok/skills/animate/SKILL.md',
26
- '.grok/skills/review-animations/SKILL.md',
27
21
  '.grok/agents/devil-advocate.md',
28
22
  '.grok/agents/judge.md',
29
- '.gemini/skills/ai-engineering-loop/SKILL.md',
30
- '.gemini/skills/ai-engineering-loop/references/loop-review.md',
31
- '.gemini/skills/backend-development/SKILL.md',
32
- '.gemini/skills/emil-design-eng/SKILL.md',
33
- '.gemini/skills/animate/SKILL.md',
34
- '.gemini/skills/review-animations/SKILL.md',
35
- '.agents/workflows/ai-engineering-loop.md',
23
+ '.agents/skills/ai-engineering-loop/SKILL.md',
24
+ '.agents/skills/ai-engineering-loop/references/loop-hosts.md',
36
25
  '.agents/skills/backend-development/SKILL.md',
37
26
  '.agents/skills/emil-design-eng/SKILL.md',
38
27
  '.agents/skills/animate/SKILL.md',
39
28
  '.agents/skills/review-animations/SKILL.md',
40
- '.agents/devil-advocate.md',
41
- '.agents/judge.md'
29
+ 'agents/shared/devil-advocate.body.md',
30
+ 'agents/shared/judge.body.md'
42
31
  ];
43
32
 
44
33
  const REQUIRED_SCHEMAS = [
@@ -1,15 +1,17 @@
1
1
  'use strict';
2
2
 
3
- // Host skill build (issue #35). One template plus one overlay per host produces
4
- // the four ai-engineering-loop host skills and their references/. The generated
5
- // files are committed (they ship in the npm package); a drift test fails when a
6
- // generated file is edited by hand instead of the source in skill-src/.
3
+ // Host skill build (issues #35, #48). One template plus one overlay produces a
4
+ // single host-neutral ai-engineering-loop skill and its references/. The same
5
+ // bytes are written to every output directory, so a host that reads several
6
+ // skill folders (Grok, Cursor, OpenCode, Amp, Augment) only ever sees identical
7
+ // copies. Host-specific spawn rules live in references/loop-hosts.md. The
8
+ // generated files are committed (they ship in the npm package); a drift test
9
+ // fails when a generated file is edited by hand instead of skill-src/.
7
10
 
8
11
  const fs = require('fs');
9
12
  const path = require('path');
10
13
 
11
14
  const SOURCE_DIR = 'skill-src/ai-engineering-loop';
12
- const HOSTS = Object.freeze(['claude', 'grok', 'gemini', 'antigravity']);
13
15
  const SKILL_CHAR_LIMIT = 4000;
14
16
  const GENERATED_NOTE = '<!-- Generated from skill-src/ by npm run build:skills; do not edit. -->';
15
17
 
@@ -61,16 +63,15 @@ function buildHostSkills(root = path.join(__dirname, '..')) {
61
63
  const refDir = path.join(src, 'references');
62
64
  const references = fs.readdirSync(refDir).filter((f) => f.endsWith('.md')).sort()
63
65
  .map((name) => ({ name, content: readText(path.join(refDir, name)) }));
66
+ const overlay = parseOverlay(readText(path.join(src, 'overlay.md')));
67
+ const dirs = String(overlay.outputs || '').split(',').map((d) => d.trim()).filter(Boolean);
68
+ if (!dirs.length) throw new Error('overlay needs "@@ outputs: <dir>[, <dir>]"');
69
+ const body = insertNote(render(template, overlay, 'overlay').replace(/\n{3,}/g, '\n\n').replace(/\s*$/, '\n'));
64
70
  const outputs = [];
65
- for (const host of HOSTS) {
66
- const overlay = parseOverlay(readText(path.join(src, 'hosts', `${host}.md`)));
67
- if (!overlay.output) throw new Error(`${host}: overlay needs "@@ output: <path>"`);
68
- const body = render(template, overlay, host).replace(/\n{3,}/g, '\n\n').replace(/\s*$/, '\n');
69
- outputs.push({ host, path: overlay.output, content: insertNote(body), kind: 'skill' });
70
- if (overlay.references) {
71
- for (const ref of references) {
72
- outputs.push({ host, path: path.posix.join(overlay.references, ref.name), content: ref.content, kind: 'reference' });
73
- }
71
+ for (const dir of dirs) {
72
+ outputs.push({ path: path.posix.join(dir, 'SKILL.md'), content: body, kind: 'skill' });
73
+ for (const ref of references) {
74
+ outputs.push({ path: path.posix.join(dir, 'references', ref.name), content: ref.content, kind: 'reference' });
74
75
  }
75
76
  }
76
77
  return outputs;
@@ -111,7 +112,6 @@ function writeHostSkills(root = path.join(__dirname, '..')) {
111
112
 
112
113
  module.exports = {
113
114
  SOURCE_DIR,
114
- HOSTS,
115
115
  SKILL_CHAR_LIMIT,
116
116
  GENERATED_NOTE,
117
117
  parseOverlay,