ai-engineering-loop 1.13.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 (117) hide show
  1. package/.agents/skills/ai-engineering-loop/SKILL.md +62 -0
  2. package/.agents/skills/ai-engineering-loop/references/loop-commands.md +20 -0
  3. package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
  4. package/.agents/skills/ai-engineering-loop/references/loop-goal.md +10 -0
  5. package/.agents/skills/ai-engineering-loop/references/loop-hosts.md +44 -0
  6. package/.agents/skills/ai-engineering-loop/references/loop-maker.md +8 -0
  7. package/.agents/skills/ai-engineering-loop/references/loop-review.md +18 -0
  8. package/.agents/skills/ai-engineering-loop/references/loop-risky.md +9 -0
  9. package/.agents/skills/ai-engineering-loop/references/loop-verify.md +20 -0
  10. package/.claude/skills/ai-engineering-loop/SKILL.md +28 -47
  11. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +20 -0
  12. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
  13. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +10 -0
  14. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +44 -0
  15. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +8 -0
  16. package/.claude/skills/ai-engineering-loop/references/loop-review.md +18 -0
  17. package/.claude/skills/ai-engineering-loop/references/loop-risky.md +9 -0
  18. package/.claude/skills/ai-engineering-loop/references/loop-verify.md +20 -0
  19. package/CHANGELOG.md +116 -0
  20. package/README.md +90 -5
  21. package/README.npm.md +6 -2
  22. package/THIRD_PARTY_NOTICES.md +29 -0
  23. package/adapters/dot/README.md +1 -1
  24. package/adapters/dot/skills/dot-dev-skill-router/SKILL.md +24 -16
  25. package/adapters/project-onboarding/SKILL.md +27 -0
  26. package/adapters/project-onboarding/references/output.md +29 -0
  27. package/adapters/quality/skills/ael-code-simplifier/SKILL.md +43 -0
  28. package/adapters/quality/skills/ael-receiving-code-review/SKILL.md +37 -0
  29. package/bin/ai-engineering-loop.js +1270 -75
  30. package/core/grill-policy.md +1 -1
  31. package/core/root-cause-analysis.md +6 -0
  32. package/core/runtime-safety.md +31 -3
  33. package/evals/cases/21-tier-t0-docs.json +34 -0
  34. package/evals/cases/22-tier-t1-small-pass.json +30 -0
  35. package/evals/cases/23-tier-t1-blocker.json +26 -0
  36. package/evals/cases/24-tier-t1-auth-escalates.json +30 -0
  37. package/lib/auto-update.js +488 -0
  38. package/lib/budget.js +31 -1
  39. package/lib/cli-args.js +95 -0
  40. package/lib/docs.js +91 -0
  41. package/lib/doctor.js +9 -14
  42. package/lib/gates.js +114 -1
  43. package/lib/host-skill-build.js +121 -0
  44. package/lib/hosts/agent-formats.js +135 -0
  45. package/lib/hosts/commands.js +126 -0
  46. package/lib/hosts/detect.js +56 -0
  47. package/lib/hosts/doctor.js +76 -0
  48. package/lib/hosts/redetect.js +60 -0
  49. package/lib/hosts/registry.js +271 -0
  50. package/lib/hosts/table.js +35 -0
  51. package/lib/migrations.js +84 -0
  52. package/lib/project-registry.js +148 -0
  53. package/lib/run-abandon.js +116 -0
  54. package/lib/run-state.js +6 -3
  55. package/lib/sync-hosts.js +456 -130
  56. package/lib/tier.js +134 -0
  57. package/lib/update-manager.js +17 -1
  58. package/lib/update-notice.js +192 -0
  59. package/lib/user-state.js +80 -0
  60. package/lib/verification-recorder.js +44 -0
  61. package/migrations/README.md +21 -0
  62. package/package.json +8 -4
  63. package/.agents/devil-advocate.md +0 -79
  64. package/.agents/judge.md +0 -58
  65. package/.agents/workflows/ai-engineering-loop.md +0 -24
  66. package/.claude/commands/ai-engineering-loop.md +0 -11
  67. package/.gemini/skills/ai-engineering-loop/SKILL.md +0 -74
  68. package/.gemini/skills/animate/RECIPES.md +0 -324
  69. package/.gemini/skills/animate/SKILL.md +0 -207
  70. package/.gemini/skills/animate-expo/RECIPES.md +0 -385
  71. package/.gemini/skills/animate-expo/SKILL.md +0 -263
  72. package/.gemini/skills/animation-vocabulary/SKILL.md +0 -181
  73. package/.gemini/skills/apple-design/SKILL.md +0 -290
  74. package/.gemini/skills/ask-sonner/API.md +0 -64
  75. package/.gemini/skills/ask-sonner/SKILL.md +0 -88
  76. package/.gemini/skills/backend-development/SKILL.md +0 -272
  77. package/.gemini/skills/backend-development/references/api-design-guidelines.md +0 -95
  78. package/.gemini/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  79. package/.gemini/skills/backend-development/references/security-checklist.md +0 -60
  80. package/.gemini/skills/emil-design-eng/SKILL.md +0 -674
  81. package/.gemini/skills/find-animation-opportunities/SKILL.md +0 -140
  82. package/.gemini/skills/improve-animations/AUDIT.md +0 -115
  83. package/.gemini/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  84. package/.gemini/skills/improve-animations/SKILL.md +0 -109
  85. package/.gemini/skills/mobile-native/SKILL.md +0 -311
  86. package/.gemini/skills/pick-ui-library/SKILL.md +0 -85
  87. package/.gemini/skills/prototype/PICKER.md +0 -197
  88. package/.gemini/skills/prototype/SKILL.md +0 -98
  89. package/.gemini/skills/review-animations/SKILL.md +0 -120
  90. package/.gemini/skills/review-animations/STANDARDS.md +0 -187
  91. package/.gemini/skills/write-swift/SKILL.md +0 -396
  92. package/.grok/commands/ai-engineering-loop.md +0 -11
  93. package/.grok/skills/ai-engineering-loop/SKILL.md +0 -94
  94. package/.grok/skills/animate/RECIPES.md +0 -324
  95. package/.grok/skills/animate/SKILL.md +0 -207
  96. package/.grok/skills/animate-expo/RECIPES.md +0 -385
  97. package/.grok/skills/animate-expo/SKILL.md +0 -263
  98. package/.grok/skills/animation-vocabulary/SKILL.md +0 -181
  99. package/.grok/skills/apple-design/SKILL.md +0 -290
  100. package/.grok/skills/ask-sonner/API.md +0 -64
  101. package/.grok/skills/ask-sonner/SKILL.md +0 -88
  102. package/.grok/skills/backend-development/SKILL.md +0 -272
  103. package/.grok/skills/backend-development/references/api-design-guidelines.md +0 -95
  104. package/.grok/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  105. package/.grok/skills/backend-development/references/security-checklist.md +0 -60
  106. package/.grok/skills/emil-design-eng/SKILL.md +0 -674
  107. package/.grok/skills/find-animation-opportunities/SKILL.md +0 -140
  108. package/.grok/skills/improve-animations/AUDIT.md +0 -115
  109. package/.grok/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  110. package/.grok/skills/improve-animations/SKILL.md +0 -109
  111. package/.grok/skills/mobile-native/SKILL.md +0 -311
  112. package/.grok/skills/pick-ui-library/SKILL.md +0 -85
  113. package/.grok/skills/prototype/PICKER.md +0 -197
  114. package/.grok/skills/prototype/SKILL.md +0 -98
  115. package/.grok/skills/review-animations/SKILL.md +0 -120
  116. package/.grok/skills/review-animations/STANDARDS.md +0 -187
  117. package/.grok/skills/write-swift/SKILL.md +0 -396
package/lib/sync-hosts.js CHANGED
@@ -1,27 +1,29 @@
1
1
  'use strict';
2
2
 
3
3
  const fs = require('fs');
4
- const os = require('os');
5
4
  const path = require('path');
5
+ const { AGENTS, FORMATS, renderAgent, agentFileName } = require('./hosts/agent-formats.js');
6
+ const { HOSTS, HOST_IDS, SHARED_SKILLS_DIR, usesSharedSkills } = require('./hosts/registry.js');
7
+ const { detectHosts } = require('./hosts/detect.js');
8
+ const {
9
+ homeDir,
10
+ sha256,
11
+ userStatePath,
12
+ readJsonFile,
13
+ writeJsonFile,
14
+ readUserConfig,
15
+ writeUserConfig
16
+ } = require('./user-state.js');
6
17
 
7
18
  function packageRoot() {
8
19
  return path.join(__dirname, '..');
9
20
  }
10
21
 
11
- function homeDir(env = process.env) {
12
- if (env.AEL_HOME) return env.AEL_HOME;
13
- return os.homedir();
14
- }
15
-
16
- function applyGrokSkillOverlay(content) {
17
- const normalized = String(content).replace(/\r\n?/g, '\n');
18
- const match = normalized.match(/^---\n([\s\S]*?)\n---\n/);
19
- if (!match) return normalized;
20
- const yaml = match[1];
21
- if (/^user-invocable:\s*true\s*$/m.test(yaml)) return normalized;
22
- const nextYaml = `${yaml.replace(/\s*$/, '')}\nuser-invocable: true`;
23
- return `---\n${nextYaml}\n---\n${normalized.slice(match[0].length)}`;
24
- }
22
+ // Host packs. `core` is always installed; the others are opt-in so unrelated
23
+ // skills do not enter every session's skill index (issue #31).
24
+ const HOST_PACKS = Object.freeze(['core', 'backend', 'design', 'quality']);
25
+ const DEFAULT_HOST_PACKS = Object.freeze(['core']);
26
+ const MANIFEST_FILE = 'host-manifest.json';
25
27
 
26
28
  const BACKEND_SKILL_FILES = [
27
29
  'SKILL.md',
@@ -62,100 +64,180 @@ const EMIL_KOWALSKI_SKILL_FILES = Object.freeze({
62
64
  'write-swift': ['SKILL.md']
63
65
  });
64
66
 
65
- function backendSkillFiles(srcRoot, destRoot, { grokSkillOverlay = false } = {}) {
67
+ function backendSkillFiles(srcRoot, destRoot) {
66
68
  return BACKEND_SKILL_FILES.map((file) => ({
67
69
  src: path.posix.join(srcRoot, file),
68
70
  dest: path.join(destRoot, file),
69
71
  mode: 'upsert',
70
- ...(grokSkillOverlay && file === 'SKILL.md' ? { grokSkillOverlay: true } : {})
72
+ pack: 'backend'
71
73
  }));
72
74
  }
73
75
 
74
- function emilKowalskiSkillFiles(srcRoot, destRoot, { grokSkillOverlay = false } = {}) {
76
+ function emilKowalskiSkillFiles(srcRoot, destRoot) {
75
77
  return EMIL_KOWALSKI_SKILLS.flatMap((skill) => (
76
78
  EMIL_KOWALSKI_SKILL_FILES[skill].map((file) => ({
77
79
  src: path.posix.join(srcRoot, skill, file),
78
80
  dest: path.join(destRoot, skill, file),
79
81
  mode: 'upsert',
80
- ...(grokSkillOverlay && file === 'SKILL.md' ? { grokSkillOverlay: true } : {})
82
+ pack: 'design'
81
83
  }))
82
84
  ));
83
85
  }
84
86
 
85
- function hostFileMap(home) {
86
- const claude = path.join(home, '.claude');
87
- const grok = path.join(home, '.grok');
88
- const gemini = path.join(home, '.gemini');
89
- const agents = path.join(home, '.agents');
87
+ // Adopted skills (issue #36). project-onboarding ships with core; the quality
88
+ // pack (ael-code-simplifier, ael-receiving-code-review) is opt-in.
89
+ const QUALITY_SKILLS = Object.freeze(['ael-code-simplifier', 'ael-receiving-code-review']);
90
+
91
+ function adoptedSkillFiles(destRoot) {
90
92
  return [
91
- {
92
- id: 'claude',
93
- root: claude,
94
- files: [
95
- { src: '.claude/skills/ai-engineering-loop/SKILL.md', dest: path.join(claude, 'skills/ai-engineering-loop/SKILL.md'), mode: 'upsert' },
96
- ...backendSkillFiles('.claude/skills/backend-development', path.join(claude, 'skills/backend-development')),
97
- ...emilKowalskiSkillFiles('.claude/skills', path.join(claude, 'skills')),
98
- { src: 'adapters/dot/skills/task-impact-inquiry/SKILL.md', dest: path.join(claude, 'skills/task-impact-inquiry/SKILL.md'), mode: 'upsert' },
99
- { src: 'adapters/generate-adapter/SKILL.md', dest: path.join(claude, 'skills/generate-adapter/SKILL.md'), mode: 'upsert' },
100
- { src: 'adapters/generate-workflow/SKILL.md', dest: path.join(claude, 'skills/generate-workflow/SKILL.md'), mode: 'upsert' },
101
- { src: '.claude/agents/devil-advocate.md', dest: path.join(claude, 'agents/devil-advocate.md'), mode: 'upsert' },
102
- { src: '.claude/agents/judge.md', dest: path.join(claude, 'agents/judge.md'), mode: 'upsert' },
103
- { src: '.claude/commands/ai-engineering-loop.md', dest: path.join(claude, 'commands/ai-engineering-loop.md'), mode: 'upsert' }
104
- ]
105
- },
106
- {
107
- id: 'grok',
108
- root: grok,
109
- files: [
110
- { src: '.grok/skills/ai-engineering-loop/SKILL.md', dest: path.join(grok, 'skills/ai-engineering-loop/SKILL.md'), mode: 'upsert', grokSkillOverlay: true },
111
- ...backendSkillFiles('.grok/skills/backend-development', path.join(grok, 'skills/backend-development'), { grokSkillOverlay: true }),
112
- ...emilKowalskiSkillFiles('.grok/skills', path.join(grok, 'skills'), { grokSkillOverlay: true }),
113
- { src: 'adapters/dot/skills/task-impact-inquiry/SKILL.md', dest: path.join(grok, 'skills/task-impact-inquiry/SKILL.md'), mode: 'upsert', grokSkillOverlay: true },
114
- { src: 'adapters/generate-adapter/SKILL.md', dest: path.join(grok, 'skills/generate-adapter/SKILL.md'), mode: 'upsert', grokSkillOverlay: true },
115
- { src: 'adapters/generate-workflow/SKILL.md', dest: path.join(grok, 'skills/generate-workflow/SKILL.md'), mode: 'upsert', grokSkillOverlay: true },
116
- { src: '.grok/agents/devil-advocate.md', dest: path.join(grok, 'agents/devil-advocate.md'), mode: 'upsert' },
117
- { src: '.grok/agents/judge.md', dest: path.join(grok, 'agents/judge.md'), mode: 'upsert' },
118
- { src: '.grok/commands/ai-engineering-loop.md', dest: path.join(grok, 'commands/ai-engineering-loop.md'), mode: 'upsert' }
119
- ]
120
- },
121
- {
122
- id: 'gemini',
123
- root: gemini,
124
- files: [
125
- { src: '.gemini/skills/ai-engineering-loop/SKILL.md', dest: path.join(gemini, 'config/skills/ai-engineering-loop/SKILL.md'), mode: 'upsert' },
126
- ...backendSkillFiles('.gemini/skills/backend-development', path.join(gemini, 'config/skills/backend-development')),
127
- ...emilKowalskiSkillFiles('.gemini/skills', path.join(gemini, 'config/skills')),
128
- { src: 'adapters/dot/skills/task-impact-inquiry/SKILL.md', dest: path.join(gemini, 'config/skills/task-impact-inquiry/SKILL.md'), mode: 'upsert' },
129
- { src: 'adapters/generate-adapter/SKILL.md', dest: path.join(gemini, 'config/skills/generate-adapter/SKILL.md'), mode: 'upsert' },
130
- { src: 'adapters/generate-workflow/SKILL.md', dest: path.join(gemini, 'config/skills/generate-workflow/SKILL.md'), mode: 'upsert' }
131
- ]
132
- },
133
- {
134
- id: 'antigravity',
135
- root: agents,
136
- files: [
137
- ...backendSkillFiles('.agents/skills/backend-development', path.join(agents, 'skills/backend-development')),
138
- ...emilKowalskiSkillFiles('.agents/skills', path.join(agents, 'skills')),
139
- { src: '.agents/devil-advocate.md', dest: path.join(agents, 'devil-advocate.md'), mode: 'upsert' },
140
- { src: '.agents/judge.md', dest: path.join(agents, 'judge.md'), mode: 'upsert' },
141
- { src: '.agents/workflows/ai-engineering-loop.md', dest: path.join(agents, 'workflows/ai-engineering-loop.md'), mode: 'upsert' }
142
- ]
143
- },
144
- {
145
- id: 'dot',
146
- root: null,
147
- files: [
148
- { src: 'adapters/dot/skills/dot-dev-skill-router/SKILL.md', dest: path.join(claude, 'skills/dot-dev-skill-router/SKILL.md'), mode: 'update-if-exists', hostRoot: claude },
149
- { src: 'adapters/dot/skills/dot-dev-workflow/SKILL.md', dest: path.join(claude, 'skills/dot-dev-workflow/SKILL.md'), mode: 'update-if-exists', hostRoot: claude },
150
- { src: 'adapters/dot/skills/dot-dev-skill-router/SKILL.md', dest: path.join(grok, 'skills/dot-dev-skill-router/SKILL.md'), mode: 'update-if-exists', hostRoot: grok, grokSkillOverlay: true },
151
- { src: 'adapters/dot/skills/dot-dev-workflow/SKILL.md', dest: path.join(grok, 'skills/dot-dev-workflow/SKILL.md'), mode: 'update-if-exists', hostRoot: grok, grokSkillOverlay: true },
152
- { src: 'adapters/dot/skills/dot-dev-skill-router/SKILL.md', dest: path.join(gemini, 'config/skills/dot-dev-skill-router/SKILL.md'), mode: 'update-if-exists', hostRoot: gemini },
153
- { src: 'adapters/dot/skills/dot-dev-workflow/SKILL.md', dest: path.join(gemini, 'config/skills/dot-dev-workflow/SKILL.md'), mode: 'update-if-exists', hostRoot: gemini }
154
- ]
155
- }
93
+ { src: 'adapters/project-onboarding/SKILL.md', dest: path.join(destRoot, 'project-onboarding/SKILL.md'), mode: 'upsert' },
94
+ { src: 'adapters/project-onboarding/references/output.md', dest: path.join(destRoot, 'project-onboarding/references/output.md'), mode: 'upsert' },
95
+ ...QUALITY_SKILLS.map((skill) => ({
96
+ src: `adapters/quality/skills/${skill}/SKILL.md`,
97
+ dest: path.join(destRoot, skill, 'SKILL.md'),
98
+ mode: 'upsert',
99
+ pack: 'quality'
100
+ }))
156
101
  ];
157
102
  }
158
103
 
104
+ // Loop stage references sit beside each host's SKILL.md (issue #35).
105
+ const LOOP_REFERENCE_FILES = Object.freeze([
106
+ 'loop-commands.md',
107
+ 'loop-deliver.md',
108
+ 'loop-goal.md',
109
+ 'loop-hosts.md',
110
+ 'loop-maker.md',
111
+ 'loop-review.md',
112
+ 'loop-risky.md',
113
+ 'loop-verify.md'
114
+ ]);
115
+
116
+ function loopReferenceFiles(srcDir, destDir) {
117
+ return LOOP_REFERENCE_FILES.map((file) => ({
118
+ src: path.posix.join(srcDir, 'references', file),
119
+ dest: path.join(destDir, 'references', file),
120
+ mode: 'upsert'
121
+ }));
122
+ }
123
+
124
+ // The host-neutral core skill (#48): one source, byte-identical everywhere.
125
+ const CORE_SKILL_SRC = '.agents/skills/ai-engineering-loop';
126
+
127
+ // Every skill a host's skill folder gets: core loop skill, helpers, packs.
128
+ function skillFolderFiles(skillsDir) {
129
+ return [
130
+ { src: `${CORE_SKILL_SRC}/SKILL.md`, dest: path.join(skillsDir, 'ai-engineering-loop/SKILL.md'), mode: 'upsert' },
131
+ ...loopReferenceFiles(CORE_SKILL_SRC, path.join(skillsDir, 'ai-engineering-loop')),
132
+ ...backendSkillFiles('.agents/skills/backend-development', path.join(skillsDir, 'backend-development')),
133
+ ...emilKowalskiSkillFiles('.agents/skills', skillsDir),
134
+ { src: 'adapters/dot/skills/task-impact-inquiry/SKILL.md', dest: path.join(skillsDir, 'task-impact-inquiry/SKILL.md'), mode: 'upsert' },
135
+ { src: 'adapters/generate-adapter/SKILL.md', dest: path.join(skillsDir, 'generate-adapter/SKILL.md'), mode: 'upsert' },
136
+ { src: 'adapters/generate-workflow/SKILL.md', dest: path.join(skillsDir, 'generate-workflow/SKILL.md'), mode: 'upsert' },
137
+ ...adoptedSkillFiles(skillsDir)
138
+ ];
139
+ }
140
+
141
+ function agentFiles(host, home) {
142
+ if (!host.agents) return [];
143
+ const dir = path.join(home, host.agents.dir);
144
+ const format = FORMATS[host.agents.format];
145
+ if (!format) throw new Error(`${host.id}: unknown agent format ${host.agents.format}`);
146
+ return AGENTS.map((name) => {
147
+ const dest = path.join(dir, agentFileName(host.agents.format, name));
148
+ // Canonical repo copies (Claude, Grok) ship as files; others are rendered.
149
+ if (format.src) return { src: format.src(name), dest, mode: 'upsert' };
150
+ return { src: `agents/shared/${name}.body.md`, dest, mode: 'upsert', agentFormat: host.agents.format, agentName: name };
151
+ });
152
+ }
153
+
154
+ // Which hosts get files. After `setup` / `hosts enable|disable` the saved
155
+ // config decides. Before that (legacy installs) a host counts when one of its
156
+ // config directories exists, exactly like earlier releases; PATH binaries only
157
+ // feed `setup` and `hosts list`, so an automatic sync never creates folders for
158
+ // an agent the user has not opted into.
159
+ function resolveHostSelection(home) {
160
+ const config = readUserConfig(home);
161
+ const saved = config.hosts && typeof config.hosts === 'object' ? config.hosts : null;
162
+ if (saved && Array.isArray(saved.enabled)) {
163
+ const enabled = new Set(saved.enabled.filter((id) => HOST_IDS.includes(id)));
164
+ const disabled = new Set((Array.isArray(saved.disabled) ? saved.disabled : []).filter((id) => HOST_IDS.includes(id) && !enabled.has(id)));
165
+ return { enabled, disabled, source: 'config', mode: saved.mode === 'auto' ? 'auto' : 'manual' };
166
+ }
167
+ const enabled = new Set(detectHosts({ home, env: { PATH: '' } }).filter((d) => d.detected).map((d) => d.id));
168
+ // An earlier sync already installed files for this host: keep it.
169
+ const tracked = Object.keys(readHostManifest(home).files).map((file) => path.resolve(file));
170
+ for (const host of HOSTS) {
171
+ const dirs = [usesSharedSkills(host) ? null : host.skills.dir, host.agents && host.agents.dir].filter(Boolean)
172
+ .map((dir) => path.resolve(home, dir) + path.sep);
173
+ if (tracked.some((file) => dirs.some((dir) => file.startsWith(dir)))) enabled.add(host.id);
174
+ }
175
+ return { enabled, disabled: new Set(), source: 'legacy-dirs', mode: null };
176
+ }
177
+
178
+ // Groups of files per host, plus the shared ~/.agents/skills folder and
179
+ // update-only DOT skills. A file wanted by any enabled group is never pruned
180
+ // on behalf of a disabled one (Antigravity IDE and CLI share an agents dir).
181
+ function hostFileMap(home, selection = resolveHostSelection(home)) {
182
+ const groups = [];
183
+ const sharedUsers = HOSTS.filter((host) => usesSharedSkills(host));
184
+ const sharedEnabled = sharedUsers.some((host) => selection.enabled.has(host.id));
185
+ const sharedDisabled = !sharedEnabled && selection.source === 'config' && sharedUsers.some((host) => selection.disabled.has(host.id));
186
+ const skillDirs = [];
187
+ for (const host of HOSTS) {
188
+ const files = [];
189
+ if (!usesSharedSkills(host)) files.push(...skillFolderFiles(path.join(home, host.skills.dir)));
190
+ files.push(...agentFiles(host, home));
191
+ const enabled = selection.enabled.has(host.id);
192
+ if (enabled && !usesSharedSkills(host)) skillDirs.push(path.join(home, host.skills.dir));
193
+ groups.push({ id: host.id, enabled, disabled: selection.disabled.has(host.id), files });
194
+ }
195
+ groups.push({
196
+ id: 'shared',
197
+ enabled: sharedEnabled,
198
+ disabled: sharedDisabled,
199
+ files: skillFolderFiles(path.join(home, SHARED_SKILLS_DIR))
200
+ });
201
+ if (sharedEnabled) skillDirs.push(path.join(home, SHARED_SKILLS_DIR));
202
+ groups.push({
203
+ id: 'dot',
204
+ enabled: true,
205
+ disabled: false,
206
+ files: [...new Set(skillDirs)].flatMap((dir) => DOT_SKILLS.map((skill) => ({
207
+ src: `adapters/dot/skills/${skill}/SKILL.md`,
208
+ dest: path.join(dir, skill, 'SKILL.md'),
209
+ mode: 'update-if-exists'
210
+ })))
211
+ });
212
+ const wanted = new Set();
213
+ for (const group of groups) {
214
+ if (!group.enabled) continue;
215
+ group.files = group.files.filter((file) => {
216
+ const key = path.resolve(file.dest);
217
+ if (wanted.has(key)) return false;
218
+ wanted.add(key);
219
+ return true;
220
+ });
221
+ }
222
+ for (const group of groups) {
223
+ if (group.enabled) continue;
224
+ group.files = group.files.filter((file) => !wanted.has(path.resolve(file.dest)));
225
+ }
226
+ return groups;
227
+ }
228
+
229
+ const DOT_SKILLS = Object.freeze(['dot-dev-skill-router', 'dot-dev-workflow']);
230
+
231
+ // Directories AEL may own files under (obsolete-file cleanup is limited to them).
232
+ function managedRoots(home) {
233
+ const roots = new Set([path.join(home, '.agents')]);
234
+ for (const host of HOSTS) {
235
+ if (!usesSharedSkills(host)) roots.add(path.dirname(path.join(home, host.skills.dir)));
236
+ if (host.agents) roots.add(path.dirname(path.join(home, host.agents.dir)));
237
+ }
238
+ return [...roots].map((root) => path.resolve(root));
239
+ }
240
+
159
241
  function destExists(dest) {
160
242
  try {
161
243
  fs.lstatSync(dest);
@@ -195,20 +277,96 @@ function findSymlinkAncestor(home, destination) {
195
277
  return null;
196
278
  }
197
279
 
198
- function planHostSync({ packageRoot: root = packageRoot(), home = homeDir() } = {}) {
280
+ function normalizePacks(value) {
281
+ const list = Array.isArray(value)
282
+ ? value
283
+ : String(value || '').split(',');
284
+ const packs = new Set(['core']);
285
+ for (const raw of list) {
286
+ const pack = String(raw).trim();
287
+ if (!pack) continue;
288
+ if (!HOST_PACKS.includes(pack)) {
289
+ const err = new Error(`Unknown host pack "${pack}". Use: ${HOST_PACKS.join(', ')}`);
290
+ err.code = 'UNKNOWN_HOST_PACK';
291
+ throw err;
292
+ }
293
+ packs.add(pack);
294
+ }
295
+ return HOST_PACKS.filter((pack) => packs.has(pack));
296
+ }
297
+
298
+ function manifestPath(home) {
299
+ return userStatePath(MANIFEST_FILE, home);
300
+ }
301
+
302
+ function readHostManifest(home = homeDir()) {
303
+ const value = readJsonFile(manifestPath(home), null);
304
+ if (!value || typeof value !== 'object' || typeof value.files !== 'object' || value.files === null) {
305
+ return { schemaVersion: 1, version: null, files: {} };
306
+ }
307
+ return { schemaVersion: 1, version: value.version || null, files: value.files };
308
+ }
309
+
310
+ function readFileText(dest) {
311
+ try {
312
+ return fs.readFileSync(dest, 'utf8');
313
+ } catch {
314
+ return null;
315
+ }
316
+ }
317
+
318
+ function packageContent(root, file) {
319
+ if (file.agentFormat) return renderAgent(root, file.agentFormat, file.agentName);
320
+ const srcAbs = path.join(root, file.src);
321
+ return fs.readFileSync(srcAbs, 'utf8').replace(/\r\n?/g, '\n');
322
+ }
323
+
324
+
325
+
326
+ // Pack selection precedence: explicit argument > saved user config > legacy
327
+ // auto-detect (a non-core pack stays selected while any of its files is already
328
+ // installed, so upgrading never silently freezes an existing install).
329
+ function resolvePacks({ packs, home }) {
330
+ if (packs != null) return { packs: normalizePacks(packs), source: 'argument' };
331
+ const config = readUserConfig(home);
332
+ if (Array.isArray(config.hostPacks)) return { packs: normalizePacks(config.hostPacks), source: 'config' };
333
+ const detected = new Set(DEFAULT_HOST_PACKS);
334
+ for (const group of hostFileMap(home, { enabled: new Set(HOST_IDS), disabled: new Set(), source: 'all' })) {
335
+ for (const file of group.files) {
336
+ if (file.pack && file.pack !== 'core' && destExists(file.dest)) detected.add(file.pack);
337
+ }
338
+ }
339
+ return { packs: normalizePacks([...detected]), source: detected.size > 1 ? 'detected' : 'default' };
340
+ }
341
+
342
+ function planHostSync({ packageRoot: root = packageRoot(), home = homeDir(), packs = null, prune = false, hosts = null } = {}) {
199
343
  const results = [];
200
- for (const group of hostFileMap(home)) {
344
+ const selection = resolvePacks({ packs, home });
345
+ const hostSelection = hosts || resolveHostSelection(home);
346
+ const manifest = readHostManifest(home);
347
+ const groups = hostFileMap(home, hostSelection);
348
+ for (const group of groups) {
201
349
  for (const file of group.files) {
202
350
  const srcAbs = path.join(root, file.src);
203
- const hostRoot = file.hostRoot || group.root;
351
+ const pack = file.pack || 'core';
204
352
  const item = {
205
353
  id: group.id,
206
354
  src: file.src,
207
355
  dest: file.dest,
208
- mode: file.mode
356
+ mode: file.mode,
357
+ pack
209
358
  };
210
- if (hostRoot && !fs.existsSync(hostRoot)) {
211
- results.push({ ...item, action: 'skip', reason: 'host-missing' });
359
+ if (!group.enabled) {
360
+ const existing = group.disabled && destExists(file.dest) ? readFileText(file.dest) : null;
361
+ if (existing === null) {
362
+ results.push({ ...item, action: 'skip', reason: group.disabled ? 'host-disabled' : 'host-missing' });
363
+ continue;
364
+ }
365
+ // `hosts disable`: remove what AEL wrote, keep what the user edited.
366
+ const tracked = manifest.files[file.dest];
367
+ results.push(tracked && tracked.sha256 === sha256(existing)
368
+ ? { ...item, action: 'prune', reason: 'host-disabled' }
369
+ : { ...item, action: 'skip', reason: 'modified' });
212
370
  continue;
213
371
  }
214
372
  if (!fs.existsSync(srcAbs)) {
@@ -225,80 +383,240 @@ function planHostSync({ packageRoot: root = packageRoot(), home = homeDir() } =
225
383
  });
226
384
  continue;
227
385
  }
228
- if (file.mode === 'update-if-exists' && !destExists(file.dest)) {
386
+ const content = packageContent(root, file);
387
+ const existing = destExists(file.dest) ? readFileText(file.dest) : null;
388
+ if (!selection.packs.includes(pack)) {
389
+ if (prune && existing !== null) {
390
+ const tracked = manifest.files[file.dest];
391
+ const currentHash = sha256(existing);
392
+ const ours = (tracked && tracked.sha256 === currentHash) || existing === content;
393
+ results.push(ours
394
+ ? { ...item, action: 'prune' }
395
+ : { ...item, action: 'skip', reason: 'modified' });
396
+ continue;
397
+ }
398
+ results.push({ ...item, action: 'skip', reason: 'pack-not-selected' });
399
+ continue;
400
+ }
401
+ if (file.mode === 'update-if-exists' && existing === null) {
229
402
  results.push({ ...item, action: 'skip', reason: 'not-installed' });
230
403
  continue;
231
404
  }
232
- let content = fs.readFileSync(srcAbs, 'utf8').replace(/\r\n?/g, '\n');
233
- if (file.grokSkillOverlay) content = applyGrokSkillOverlay(content);
234
- if (destExists(file.dest) && fs.readFileSync(file.dest, 'utf8') === content) {
235
- results.push({ ...item, action: 'current' });
405
+ if (existing === content) {
406
+ results.push({ ...item, action: 'current', sha256: sha256(content) });
236
407
  continue;
237
408
  }
238
- results.push({ ...item, action: 'copy', content });
409
+ const tracked = existing === null ? null : manifest.files[file.dest];
410
+ // A file is "user-modified" when it exists and is not byte-identical to the
411
+ // content AEL last wrote. Legacy installs without a manifest count as
412
+ // modified, so the first managed sync keeps a backup instead of guessing.
413
+ const backup = existing !== null && !(tracked && tracked.sha256 === sha256(existing));
414
+ results.push({ ...item, action: 'copy', content, sha256: sha256(content), backup });
415
+ }
416
+ }
417
+ // Obsolete AEL files (decision 5 on #37): recorded in the manifest by an
418
+ // earlier sync but no longer shipped (for example a renamed skill). Removed
419
+ // when still byte-identical to what AEL wrote; edited ones are kept.
420
+ const known = new Set(results.map((item) => path.resolve(item.dest)));
421
+ const hostRoots = managedRoots(home);
422
+ for (const [dest, tracked] of Object.entries(manifest.files || {})) {
423
+ const abs = path.resolve(dest);
424
+ if (known.has(abs)) continue;
425
+ if (!hostRoots.some((root) => abs.startsWith(root + path.sep))) continue;
426
+ if (!destExists(abs)) {
427
+ results.push({ id: 'obsolete', src: null, dest: abs, pack: tracked.pack || null, action: 'forget' });
428
+ continue;
239
429
  }
430
+ if (findSymlinkAncestor(home, abs)) continue;
431
+ const current = readFileText(abs);
432
+ results.push(current !== null && tracked && sha256(current) === tracked.sha256
433
+ ? { id: 'obsolete', src: null, dest: abs, pack: tracked.pack || null, action: 'prune', reason: 'obsolete' }
434
+ : { id: 'obsolete', src: null, dest: abs, pack: tracked.pack || null, action: 'skip', reason: 'obsolete-modified' });
240
435
  }
436
+ results.packs = selection.packs;
437
+ results.packSource = selection.source;
438
+ results.hosts = [...hostSelection.enabled];
439
+ results.hostSource = hostSelection.source;
241
440
  return results;
242
441
  }
243
442
 
244
- function applyHostSync({ packageRoot: root = packageRoot(), home = homeDir(), dryRun = false } = {}) {
245
- const plan = planHostSync({ packageRoot: root, home });
443
+ // Remove directories emptied by --prune, never above <home>/.<host>/skills.
444
+ function removeEmptyParents(dir, home) {
445
+ let current = path.resolve(dir);
446
+ const stop = path.resolve(home);
447
+ for (let depth = 0; depth < 3; depth += 1) {
448
+ if (['skills', 'agents'].includes(path.basename(current)) || path.dirname(current) === stop || current === stop) return;
449
+ try {
450
+ if (fs.readdirSync(current).length > 0) return;
451
+ fs.rmdirSync(current);
452
+ } catch {
453
+ return;
454
+ }
455
+ current = path.dirname(current);
456
+ }
457
+ }
458
+
459
+ function backupPathFor(dest) {
460
+ const base = `${dest}.ael-backup`;
461
+ if (!destExists(base)) return base;
462
+ const stamp = new Date().toISOString().replace(/[:.]/g, '-');
463
+ return `${base}-${stamp}`;
464
+ }
465
+
466
+ function writeNoFollow(dest, content) {
467
+ const flags = fs.constants.O_WRONLY
468
+ | fs.constants.O_CREAT
469
+ | fs.constants.O_TRUNC
470
+ | (fs.constants.O_NOFOLLOW || 0);
471
+ const descriptor = fs.openSync(dest, flags, 0o600);
472
+ try {
473
+ fs.writeFileSync(descriptor, content);
474
+ } finally {
475
+ fs.closeSync(descriptor);
476
+ }
477
+ }
478
+
479
+ function applyHostSync({
480
+ packageRoot: root = packageRoot(),
481
+ home = homeDir(),
482
+ dryRun = false,
483
+ packs = null,
484
+ prune = false,
485
+ version = null,
486
+ hosts = null
487
+ } = {}) {
488
+ const plan = planHostSync({ packageRoot: root, home, packs, prune, hosts });
246
489
  const applied = [];
490
+ const manifest = readHostManifest(home);
491
+ let manifestChanged = false;
247
492
  for (const item of plan) {
248
- if (item.action !== 'copy') {
493
+ if (item.action === 'current') {
494
+ if (!dryRun && (!manifest.files[item.dest] || manifest.files[item.dest].sha256 !== item.sha256)) {
495
+ manifest.files[item.dest] = { sha256: item.sha256, pack: item.pack };
496
+ manifestChanged = true;
497
+ }
249
498
  applied.push(item);
250
499
  continue;
251
500
  }
252
- if (!dryRun) {
253
- if (findSymlinkAncestor(home, item.dest)) {
254
- applied.push({ ...item, action: 'skip', reason: 'symlink-ancestor', content: undefined });
255
- continue;
256
- }
257
- fs.mkdirSync(path.dirname(item.dest), { recursive: true });
258
- if (findSymlinkAncestor(home, item.dest)) {
259
- applied.push({ ...item, action: 'skip', reason: 'symlink-ancestor', content: undefined });
260
- continue;
501
+ if (item.action === 'prune') {
502
+ if (!dryRun) {
503
+ fs.unlinkSync(item.dest);
504
+ removeEmptyParents(path.dirname(item.dest), home);
505
+ delete manifest.files[item.dest];
506
+ manifestChanged = true;
261
507
  }
262
- const flags = fs.constants.O_WRONLY
263
- | fs.constants.O_CREAT
264
- | fs.constants.O_TRUNC
265
- | (fs.constants.O_NOFOLLOW || 0);
266
- const descriptor = fs.openSync(item.dest, flags, 0o600);
267
- try {
268
- fs.writeFileSync(descriptor, item.content);
269
- } finally {
270
- fs.closeSync(descriptor);
508
+ applied.push({ ...item, dryRun });
509
+ continue;
510
+ }
511
+ if (item.action === 'forget') {
512
+ if (!dryRun) {
513
+ delete manifest.files[item.dest];
514
+ manifestChanged = true;
271
515
  }
516
+ continue;
517
+ }
518
+ if (item.action !== 'copy') {
519
+ applied.push(item);
520
+ continue;
521
+ }
522
+ if (dryRun) {
523
+ applied.push({ ...item, content: undefined, dryRun });
524
+ continue;
272
525
  }
273
- applied.push({ ...item, content: undefined, dryRun });
526
+ if (findSymlinkAncestor(home, item.dest)) {
527
+ applied.push({ ...item, action: 'skip', reason: 'symlink-ancestor', content: undefined });
528
+ continue;
529
+ }
530
+ fs.mkdirSync(path.dirname(item.dest), { recursive: true });
531
+ if (findSymlinkAncestor(home, item.dest)) {
532
+ applied.push({ ...item, action: 'skip', reason: 'symlink-ancestor', content: undefined });
533
+ continue;
534
+ }
535
+ let backupPath = null;
536
+ if (item.backup) {
537
+ backupPath = backupPathFor(item.dest);
538
+ writeNoFollow(backupPath, fs.readFileSync(item.dest));
539
+ }
540
+ writeNoFollow(item.dest, item.content);
541
+ manifest.files[item.dest] = { sha256: item.sha256, pack: item.pack };
542
+ manifestChanged = true;
543
+ applied.push({ ...item, content: undefined, dryRun, backupPath });
544
+ }
545
+ if (!dryRun && manifestChanged) {
546
+ writeJsonFile(manifestPath(home), {
547
+ schemaVersion: 1,
548
+ version: version || manifest.version || null,
549
+ updatedAt: new Date().toISOString(),
550
+ files: manifest.files
551
+ });
552
+ } else if (!dryRun && version && manifest.version !== version && Object.keys(manifest.files).length > 0) {
553
+ writeJsonFile(manifestPath(home), { ...manifest, version, updatedAt: new Date().toISOString() });
274
554
  }
555
+ if (!dryRun && packs != null) writeUserConfig({ hostPacks: plan.packs }, home);
556
+ applied.packs = plan.packs;
557
+ applied.packSource = plan.packSource;
558
+ applied.hosts = plan.hosts;
559
+ applied.hostSource = plan.hostSource;
275
560
  return applied;
276
561
  }
277
562
 
563
+ function hostSkillStatus({ packageRoot: root = packageRoot(), home = homeDir(), version = null } = {}) {
564
+ const plan = planHostSync({ packageRoot: root, home });
565
+ const staleFiles = plan.filter((item) => item.action === 'copy').length;
566
+ const managedFiles = plan.filter((item) => item.action === 'current').length;
567
+ const manifest = readHostManifest(home);
568
+ return {
569
+ installedVersion: manifest.version,
570
+ packageVersion: version,
571
+ stale: staleFiles > 0,
572
+ staleFiles,
573
+ managedFiles,
574
+ packs: plan.packs,
575
+ packSource: plan.packSource
576
+ };
577
+ }
578
+
278
579
  function summarizeHostSync(results) {
279
- const summary = { copy: 0, current: 0, skip: 0 };
580
+ const summary = { copy: 0, current: 0, skip: 0, backup: 0, prune: 0 };
280
581
  for (const item of results) {
281
- if (item.action === 'copy') summary.copy += 1;
282
- else if (item.action === 'current') summary.current += 1;
582
+ if (item.action === 'copy') {
583
+ summary.copy += 1;
584
+ if (item.backup) summary.backup += 1;
585
+ } else if (item.action === 'current') summary.current += 1;
586
+ else if (item.action === 'prune') summary.prune += 1;
283
587
  else summary.skip += 1;
284
588
  }
285
589
  return summary;
286
590
  }
287
591
 
592
+ const QUIET_SKIP_REASONS = new Set(['host-missing', 'not-installed', 'pack-not-selected']);
593
+
288
594
  function formatHostSyncReport(results, { version, dryRun = false } = {}) {
289
595
  const summary = summarizeHostSync(results);
290
596
  const lines = [
291
597
  `Host skills sync (v${version || 'unknown'})${dryRun ? ' [dry-run]' : ''}`,
292
598
  `- copy: ${summary.copy} current: ${summary.current} skip: ${summary.skip}`
599
+ + (summary.backup ? ` backup: ${summary.backup}` : '')
600
+ + (summary.prune ? ` prune: ${summary.prune}` : '')
293
601
  ];
602
+ if (results.packs) lines.push(`- packs: ${results.packs.join(', ')} (${results.packSource || 'default'})`);
294
603
  for (const item of results) {
295
- if (item.action === 'skip' && item.reason === 'host-missing') continue;
296
- if (item.action === 'skip' && item.reason === 'not-installed') continue;
604
+ if (item.action === 'skip' && QUIET_SKIP_REASONS.has(item.reason)) continue;
297
605
  const rel = item.dest;
298
- if (item.action === 'copy') lines.push(` ${item.id.padEnd(12)} ${dryRun ? 'would-copy' : 'copied'} ${rel}`);
606
+ if (item.action === 'copy') {
607
+ lines.push(` ${item.id.padEnd(12)} ${dryRun ? 'would-copy' : 'copied'} ${rel}`);
608
+ if (item.backup) {
609
+ lines.push(` ${''.padEnd(12)} ${dryRun ? 'would-backup' : 'backed-up'} ${item.backupPath || `${rel}.ael-backup`}`);
610
+ }
611
+ } else if (item.action === 'prune') lines.push(` ${item.id.padEnd(12)} ${dryRun ? 'would-prune' : 'pruned'} ${rel}`);
299
612
  else if (item.action === 'current') lines.push(` ${item.id.padEnd(12)} current ${rel}`);
300
613
  else lines.push(` ${item.id.padEnd(12)} skip(${item.reason}) ${rel}`);
301
614
  }
615
+ const notSelected = results.filter((item) => item.reason === 'pack-not-selected');
616
+ if (notSelected.length) {
617
+ const packs = [...new Set(notSelected.map((item) => item.pack))];
618
+ lines.push(`Optional packs not installed: ${packs.join(', ')} (add with --pack ${packs.join(',')})`);
619
+ }
302
620
  if (summary.copy > 0 && !dryRun) {
303
621
  lines.push('Skill text already loaded in this session stays stale until you start a new session.');
304
622
  }
@@ -306,12 +624,20 @@ function formatHostSyncReport(results, { version, dryRun = false } = {}) {
306
624
  }
307
625
 
308
626
  module.exports = {
627
+ QUALITY_SKILLS,
628
+ LOOP_REFERENCE_FILES,
629
+ HOST_PACKS,
630
+ DEFAULT_HOST_PACKS,
631
+ normalizePacks,
632
+ readHostManifest,
633
+ hostSkillStatus,
309
634
  packageRoot,
310
635
  homeDir,
311
- applyGrokSkillOverlay,
312
636
  EMIL_KOWALSKI_SKILLS,
313
637
  EMIL_KOWALSKI_SKILL_FILES,
314
638
  hostFileMap,
639
+ resolveHostSelection,
640
+ managedRoots,
315
641
  planHostSync,
316
642
  applyHostSync,
317
643
  summarizeHostSync,